Changeset 8479

Timestamp:

Feb 13, 2008, 10:22:52 AM (17 years ago)

Author:

mikel

Message:

edits to the nob-loading HOWTO

Location:

trunk/source/examples/cocoa/nib-loading

Files:

• HOWTO.html (modified) (9 diffs)
• nib-loading.lisp (modified) (1 diff)

trunk/source/examples/cocoa/nib-loading/HOWTO.html

@@ -38 +38 @@
         elements.</p>
       
-      <p>InterfaceBuilder is an appliaction that ships with Apple's
+      <p>InterfaceBuilder is an application that ships with Apple's
         Developer Tools. The Developer Tools are an optional install
         that comes with Mac OS X. Before you can use this HOWTO, you'll
@@ -114 +114 @@
 
       <p>The pathname is just a reference to the nibfile we want to
-        load. The dictionary holds references to objects&mdash;the
-        object that owns the nibfile (in this case, the running
-        NSApplication object), and an array used to hold any toplevel
-        objects in the nibfile. The zone is areference to the area of
-        memory where the nibfile objects will be allocated.</p>
+        load. The dictionary holds references to objects. In this
+        first simple example, we'll use it only to identify the
+        nibfile's owner, which in this case is the application
+        itself. The zone is a reference to the area of memory where
+        the nibfile objects will be allocated.</p>
 
       <p>Don't worry if none of this makes sense to you; the code to
@@ -128 +128 @@
       </div>
 
-      <p>First, we'll get the zone from the running application. We'll
-        tell Cocoa to allocate the nibfile objects in the same zone that
-        the application uses, so getting a zone is a simple matter of
-        asking the application for the one it's using.</p>
+      <p>First, we'll get a memory zone. We'll tell Cocoa to allocate
+        the nibfile objects in the same zone that the application
+        uses, so getting a zone is a simple matter of asking the
+        application for the one it's using.</p>
 
       <p>Before we can ask the application anything, we need a
@@ -148 +148 @@
 
       <pre>
-        ? (setf *my-app-class* (#_NSClassFromString (%make-nsstring "NSApplication")))
-        #&lt;OBJC:OBJC-CLASS NS:NS-APPLICATION (#x7FFF704C5C00)&gt;
+        ? (setf  *my-app*
+                 (let* ((class-name (%make-nsstring "NSApplication"))
+                        (appclass (#_NSClassFromString class-name)))
+                   (#/release class-name)
+                   (#/sharedApplication appclass)))
+        #&lt;LISP-APPLICATION &lt;LispApplication: 0x1b8de0&gt; (#x1B8DE0)&gt;
       </pre>
 
-      <p>Notice, by the way, that this form allocates an NSString
-        object. We do it this way for the sake of simplicity, but it's
-        not an example of good programming practice. NSStrings are
-        foreign objects, allocated by the Objective-C runtime. They
-        are not garbage-collected by Lisp, and so when you create them
-        they hang around in memory until you manually deallocate them,
-        or until you quit from Clozure CL.</p>
-
-      <p>This simple example goes on to create several foreign objects
-        by evaluating forms in the Listener, storing some of them in
-        global variables. In this example, these objects are never
-        deallocated. It's not a problem in such a small example; we
-        just create a handful of objects at the Listener, and they are
-        disposed of when we quit Clozure CL. But when writing real
-        applications using the Objective-C bridge, you will need to
-        learn to use Cocoa's memory-management discipline so that you
-        can ensure that foreign objects are allocated and deallocated
-        properly.</p>
-
-      <p>Now that we have the application class, we can ask it for a
-        reference to the running application:</p>
-
-      <pre>
-        ? (setf *my-app* (#/sharedApplication *my-app-class*))
-        #&lt;LISP-APPLICATION <LispApplication: 0x1b8e20> (#x1B8E20)&gt;
-        </pre>
+      <p>Let's review this form step-by-step.</p>
+
+      <p>First of all, it's going to store the returned application
+      object in the variable <code>*my-app*</code>, so that we have it
+      convenient for later use.</p>
+
+      <p>We need an <code>NSString</code> object that contains the
+      name of the application class, so the code allocates one by
+      calling <code>%make-nsstring</code>. The <code>NSString</code>
+      object is a dynamically-allocated foreign object, not managed by
+      Lisp's garbage-collector, so we'll have to be sure to release it
+      later.</p>
+
+      <p>The code next uses the class-name to get the
+      actual <code>NSApplication</code> class object, by
+      calling <code>#_NSClassFromString</code>.</p>
+
+      <p>Finally, after first releasing the <code>NSString</code>
+      object, it calls <code>#/sharedApplication</code> to get the
+      running application object, which turns out to be an instance
+      of <code>LispApplication</code>.</p>
 
         <p>Voilà! We have a reference to the running Clozure CL
@@ -188 +187 @@
         </pre>
 
-        <p>Now we have a reference to the application's zone. We can
-          pass it
-          to <code>loadNibFile:externalNameTable:withZone:</code> to
-          tell it to allocate the nibfile's objects in the
-          application's zone.</p>
+        <p>Now we have a reference to the application's zone, which is
+          one of the parameters we need to pass
+          to <code>loadNibFile:externalNameTable:withZone:</code>.</p>
 
         <div class="section-head">
@@ -199 +196 @@
 
         <p>The dictionary argument
-          to <code>loadNibFile:externalNameTable:withZone:</code> is used
-          for two purposes. First, we use it to pass an owner object to
-          the method. Some Cocoa objects need to have references to owner
-          objects. For example, a window might need to check with an owner
-          object to determine whether its fields and buttons should be
-          enabled. You supply an owner object in the dictionary, under the
+          to <code>loadNibFile:externalNameTable:withZone:</code> is
+          used for two purposes: to identify the nibfile's owner, and
+          to collect toplevel objects.</p>
+
+        <p>The nibfile's owner becomes the owner of all the toplevel
+          objects created when the nibfile is loaded, objects such as
+          windows, buttons, and so on. A nibfile's owner manages the
+          objects created when the nibfile is loaded, and provides a
+          way for your code to get references to those objects. You
+          supply an owner object in the dictionary, under the
           key <code>"NSNibOwner"</code>.</p>
 
-        <p>The second purpose of the dictionary object is to collect
-          references to any toplevel objects (such as buttons, text
-          fields, and so on) that the runtime creates when loading the
-          nibfile. To collect these, you pass an NSMutableArray object
-          under the key <code>"NSNibTopLevelObjects"</code>.</p>
+        <p>The toplevel objects are objects, such as windows, that are
+          created when the nibfile is loaded. To collect these, you
+          can pass an <code>NSMutableArray</code> object under the
+          key <code>"NSNibTopLevelObjects"</code>.</p>
 
         <p>For this first example, we'll pass an owner object (the
@@ -219 +219 @@
 
         <pre>
-          ? (setf *my-dict* (#/dictionaryWithObject:forKey: (@class ns-mutable-dictionary) *my-app* #@"NSNibOwner"))
+          ? (setf *my-dict* 
+                  (#/dictionaryWithObject:forKey: (@class ns-mutable-dictionary) 
+                                                  *my-app* 
+                                                  #@"NSNibOwner"))
           #&lt;NS-MUTABLE-DICTIONARY {
                                   NSNibOwner = &lt;LispApplication: 0x1b8e10&gt;;
@@ -235 +238 @@
 
         <pre>
-          ? (setf *nib-path* (%make-nsstring (namestring "/usr/local/openmcl/trunk/source/examples/cocoa/nib-loading/hello.nib")))
-          #&lt;NS-MUTABLE-STRING "/usr/local/openmcl/trunk/source/examples/cocoa/nib-loading/hello.nib" (#x13902C10)&gt;
+          ? (setf *nib-path* 
+                  (%make-nsstring 
+                     (namestring "/usr/local/openmcl/ccl/examples/cocoa/nib-loading/hello.nib")))
+          #&lt;NS-MUTABLE-STRING "/usr/local/openmcl/ccl/examples/cocoa/nib-loading/hello.nib" (#x13902C10)&gt;
         </pre>
 
@@ -243 +248 @@
 
         <pre>
-          ? (setf *nib-path* (%make-nsstring (namestring "/usr/local/openmcl/trunk/source/examples/cocoa/nib-loading/hello.nib")))
-          #&lt;NS-MUTABLE-STRING "/usr/local/openmcl/trunk/source/examples/cocoa/nib-loading/hello.nib" (#x13902C10)&gt;
-          ? (#/loadNibFile:externalNameTable:withZone: (@class ns-bundle) *nib-path* *my-dict* *my-zone*)
+          ? (#/loadNibFile:externalNameTable:withZone: 
+                  (@class ns-bundle)
+                  *nib-path*
+                  *my-dict*
+                  *my-zone*)
           T
         </pre>

trunk/source/examples/cocoa/nib-loading/nib-loading.lisp

@@ -25 +25 @@
     (values load-succeeded-p context)))
 
+(setf  *my-app*
+       (let* ((class-name (%make-nsstring "NSApplication"))
+              (appclass (#_NSClassFromString class-name)))
+         (#/release class-name)
+         (#/sharedApplication appclass)))
+
 
 #|