CurrencyConverter HOWTO

We build the application using the optional - BUILD-APPLICATION feature, distributed as part of OpenMCL. The + BUILD-APPLICATION feature, distributed as part of Clozure CL. The steps to build the Cocoa application are:
This sequence of steps causes Clozure CL to construct a Cocoa application bundle and write out the application executable to it, then quit. If all goes well, you should be able to run the @@ -44,5 +44,5 @@
Launch the OpenMCL IDE. It's safest to build the +
Launch the Clozure CL IDE. It's safest to build the application with a fresh IDE session, so if you have it running, you may wish to quit and relaunch before following @@ -66,5 +66,6 @@
Run BUILD-APPLICATION (be sure to correct the pathname to your CurrencyConverter nibfile. It is safest to use a full, - absolute pathname):
+ absolute pathname—not the relative pathname you see + below):
 (ccl::build-application :name "CurrencyConverter"
@@ -119,5 +120,5 @@
       You'll notice when you run the application that, even though
       you named it CurrencyConverter, the name in the main menu
-      appears as "OpenMCL". That's because OS X takes the
+      appears as "Clozure CL". That's because OS X takes the
       application's name, not from the application bundle's name, nor
       from the running code, but from an InfoPlist.strings file hidden
@@ -128,5 +129,5 @@
 
       
Find the entry named "CFBundleName" and change its value
-      from "OpenMCL" to "CurrencyConverter". The application's name
+      from "Clozure CL" to "CurrencyConverter". The application's name
       in the main menu bar should now appear correctly, as
       "CurrencyConverter". You may also want to change the other
Index: /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html
===================================================================
--- /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html	(revision 7798)
+++ /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html	(revision 7799)
@@ -35,5 +35,5 @@
 
       
We'll begin by using Apple's InterfaceBuilder application to
-        create a nibfile. The nibfile contains
+        create a nibfile. The nibfile contains
         archived versions of the Objective C objects that define the
         application's user interface. When you launch an application,
@@ -51,5 +51,5 @@
       
 
-      
NOTE: If you have not installed Apple's Developer Tools, you should
+      
NOTE: If you have not installed Apple's Developer Tools, you should
         do that now. You will not be able to build the CurrencyConverter
         example without them. The Developer Tools are distributed as an
@@ -81,9 +81,15 @@
       new application's name appears in the menus as
       "NewApplication". Save the new nibfile into the
-      "currency-converter" folder that you created earlier (on this
-      page). Give it the name "CurrencyConverter.nib".
+      "currency-converter" folder that you created earlier
+      (on this
+      page). InterfaceBuilder 3.0 gives you a choice of file
+      formats when you save a new nibfile; use the "NIB 3.x"
+      format—the "XIB 3.x" format works fine for editing your
+      user interface, but will not work correctly if you try to use it
+      in a working application. Give the new file the name
+      "CurrencyConverter.nib".
 
       
-        NOTE: Most Objective C application projects use a main
+        
NOTE: Most Objective C application projects use a main
         nibfile called "MainMenu.nib", and if you use XCode to create
         a new application project, it creates a nibfile with that
@@ -92,5 +98,5 @@
 
         
So, why do we tell you to use a different name? Clozure CL
-          has a main nibfile built into, whose name is
+          has a main nibfile built into it, whose name is
           "MainMenu.nib". Normally you don't see it, and don't even
           need to know that it exists. But the Clozure CL
@@ -98,12 +104,15 @@
           copying resources from the Clozure CL application, so that
           your new application has available to it all the built-in
-          Clozure CL tools. In order to avoid any confusion between
-          your application's nibfile and the MainMenu.nib built into
-          Clozure CL, we ask you to name your nibfile
-          "CurrencyConverter.nib".
-
-        Just try to keep in mind that whenever Apple's tutorial
-        refers to the "MainMenu.nib" file, it means the file we have
-        named "CurrencyConverter.nib".
+          Clozure CL tools. We ask you to name your nibfile
+          "CurrencyConverter.nib" so that it can coexist with the
+          Clozure CL main nibfile without causing any problems.
+
+        This difference between a Lisp project and an Objective C
+        project might be a little confusing at first. Just try to keep
+        in mind that whenever Apple's tutorial refers to the
+        "MainMenu.nib" file, it means the file we have just created
+        and named "CurrencyConverter.nib". In a Clozure CL project,
+        "MainMenu.nib" is the name of the main Lisp nibfile, not your
+        application's main nibfile.
       
 
@@ -124,15 +133,37 @@
 
 
+  What if You Need to Use InterfaceBuilder 2.x?
+
+
+If you are still using Mac OS X 10.4.x ("Tiger"), you can still
+  create a working nibfile and you can still follow the instructions
+  in this HOWTO to create a Cocoa application with Clozure CL. The
+  main obstacle to doing so is that the earlier versions of
+  InterfaceBuilder have a significantly different user interface, and
+  so you may find it hard to follow Apple's tutorial when working with
+  InterfaceBuilder.
+
+If you are working with Mac OS X 10.4.x ("Tiger"), you can
+  look here to find a description
+  of how to build the user interface files with the earlier version of
+  InterfaceBuilder. When you have finished building your user
+  interface, you can continue with the next
+  section, "Creating a Lisp File".
+
+One other thing: if you are using Mac OS X 10.4.x ("Tiger"), you
+  will be able to build Cocoa applications only on PPC Macs. The
+  Clozure CL Objective C support for Intel systems works only on Mac
+  OS X 10.5.x ("Leopard").
+
+
+
   Adding Custom Classes to the nibfile
 
 
-The user interface for your application looks right, but before it
-  can work right, we have to record some more information  in the
-  nibfile about the classes of the objects. In the following sections
-  we'll see how to write the Lisp code that defines your
-  application's classes. Before we're done with InteraceBuilder we
-  need to put references to those classes in the nibfile, so that
-  your application will create the correct objects when it
-  launches.
+Once the user interface for your application looks right, there is
+  still one important task to complete before you can use it. You must
+  record some information in the nibfile about the classes of the
+  objects, so that the application can create them with the right
+  connections in place.
 
 When you use XCode to write an Objective C application,
@@ -144,6 +175,6 @@
   that we use in the user interface.
 
-As you will see in the following sections, we'll be using Lisp code
-  to define two Objective C classes: Converter, and
+
As you will see in the following sections, we'll use Lisp code to
+  define two Objective C classes: Converter, and
   ConverterController. The Converter class implements the method that
   performs the actual currency conversion for our application; the
@@ -192,9 +223,7 @@
 
 
That's all it takes to add an instance of a custom class to the
-  nibfile. We do still have to add the ConverterController class, and
-  we need to tell the nibfile a few more pieces of information about
-  the two classes—specifically, we need to add the names of
-  instance variables and actions, and we need to create the
-  connections between the instances.
+  nibfile. We do still have to add the names of instance variables and
+  actions, and we need to create the connections between the
+  instances.
 
 
@@ -231,6 +260,7 @@
 
 In this application, the "convert:" action is the only action
-  defined for the user interface, so we are done. In more complex
-  applications you may need to define many actions and outlets.
+  defined for the user interface, so we are done with actions now. In
+  more complex applications you may need to define many actions and
+  outlets.
 
 Now we'll connect outlets to objects and actions.
@@ -246,9 +276,10 @@
 Select the "ConverterController" instance in the nibfile's main
   window, and Control-drag a connection to the "Exchange rate" text
-  field in the application's main window. When you release the mouse
-  button, InterfaceBuilder pops up a menu that lists the available
-  outlets. Choose "rateField" from the menu. The "rateField" outlet
-  of the "ConverterController" instance is now connected to the
-  "Exchange rate" text field.
+  field in the application's main window. (Be sure to connect to the
+  text field, not to its label!) When you release the mouse button,
+  InterfaceBuilder pops up a menu that lists the available
+  outlets. Choose "rateField" from the menu. The "rateField" outlet of
+  the "ConverterController" instance is now connected to the "Exchange
+  rate" text field.
 
 Repeat the same steps for the "Dollars" field and the "Amount"
@@ -274,8 +305,9 @@
 
We need to add one more connection: from the "Convert" button in
   the application window to the "ConverterController"
-  instance. Control drag a connection from the "Convert" button to
-  the "ConverterController" instance. InterfaceBuilder pops up a
-  menu; choose the "convert:" action from the menu to connect the
-  button to the action.
+  instance. Control drag a connection from the "Convert" button in the
+  application window to the "ConverterController" instance in the
+  nibfile's main window. InterfaceBuilder pops up a menu; choose the
+  "convert:" action from the menu to connect the button to the
+  action.
 
 The nibfile now contains descriptions of the needed cusstom
Index: /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html
===================================================================
--- /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html	(revision 7799)
+++ /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html	(revision 7799)
@@ -0,0 +1,31 @@
+
+
+  
+    CurrencyConverter HOWTO
+    
+  
+
+  
+
+    

+      Building the User Interface on "Tiger"
+    
+
+    
+      If you are using Mac OS X 10.4.x ("Tiger") to build your
+      application, then the Apple tutorial's section on building the
+      UI may be somewhat confusing. Apple's tutorial uses
+      InterfaceBuilder 3.x to show how to build an interface, and
+      there were many interface changes between versions 2.x and 3.x
+      of InterfaceBuilder. In this section we see how to build the UI
+      using InterfaceBuilder 2.x.
+
+      
+        Apple's Tutorial
+      
+
+    
+  
+
+
Index: /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html
===================================================================
--- /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html	(revision 7798)
+++ /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html	(revision 7799)
@@ -15,5 +15,5 @@
     
       This concludes our HOWTO on building the Apple
-      CurrencyConverter example in Lisp with OpenMCL. Your own Lisp
+      CurrencyConverter example in Lisp with Clozure CL. Your own Lisp
       applications are likely to be considerably more complex than the
       Currency Converter, which, after all, just does a simpe
@@ -29,5 +29,5 @@
       standalone Cocoa applications.
 
-      You should now be able to use OpenMCL to accomplish anything
+      
You should now be able to use Clozure CL to accomplish anything
       that an Objective C user can accomplish with Cocoa. Good luck!
 
Index: /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/making_project.html
===================================================================
--- /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/making_project.html	(revision 7798)
+++ /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/making_project.html	(revision 7799)
@@ -19,12 +19,12 @@
     
       This HOWTO is distributed with example files that include a
-      working nibfile and a Lisp source file, named
-      "CurrencyConverter.nib" and "CurrencyConverter.lisp",
-      respectively. You can build a working copy of
-      the example application by using these files, but, if you wish
-      to understand how to build your own Lisp application projects,
-      you should probably follow the instructions here to create your
-      own source file and nibfile, and use the example files only for
-      reference in case something goes wrong.
+      working nibfile (a file of user-interface objects,
+      named "CurrencyConverter.nib") and a Lisp source file (named
+      "CurrencyConverter.lisp"). You can build a working copy of the
+      example application by using these files, but you probably
+      shouldn't. If you want to understand how to build your own Lisp
+      application projects, you should follow the instructions here to
+      create your own source file and nibfile, and use the example
+      files only for reference in case something goes wrong.
     
 
@@ -36,5 +36,5 @@
       First, create a project folder to hold the files you are
       going to create. When your project is complete, the folder will
-      contain a nibfile that defines the user interface, and
+      contain a nibfile that defines the user interface, and
       a Lisp source file that defines the behavior of the
       application. Those two files are really all there is to a Lisp
Index: /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/writing_lisp.html
===================================================================
--- /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/writing_lisp.html	(revision 7798)
+++ /trunk/ccl/examples/cocoa/currency-converter/HOWTO_files/pages/writing_lisp.html	(revision 7799)
@@ -15,7 +15,7 @@
     

       In this section we'll write Lisp code that duplicates the
-      features provided by the Objective C code in Apple's example. In
-      Apple's example, the explanation of the Objective C code begins
-      with the
+      features provided by the Objective C code in Apple's
+      tutorial. In Apple's tutorial, the explanation of the Objective
+      C code begins with the
       section Bridging
       the Model and View: The Controller.
@@ -25,5 +25,5 @@
       because we can ignore the conventions that XCode uses for
       laying out source files. We can just write all our definitions
-      into a single Lisp source file, and load that file into OpenMCL
+      into a single Lisp source file, and load that file into Clozure CL
       when we are ready to build the application.
 
@@ -37,5 +37,5 @@
       (in-package "CCL") 
 
-      OpenMCL's Objective C bridge code is defined in the "CCL"
+      
Clozure CL's Objective C bridge code is defined in the "CCL"
       package. Usually, when building an application, you'll create a
       package for that application and import the definitions you need
@@ -68,9 +68,9 @@
       simple wrinkles. First, the superclass it inherits from is the
       NS-OBJECT class in the "NS" package. NS-OBJECT is an Objective C
-      class, the ancestor of all Objective C objects. This CLOSE
+      class, the ancestor of all Objective C objects. This CLOS
       definition actually creates a new Objective C class named
       "Converter".
 
-      We tell OpenMCL how to build the right kind of class object
+      
We tell Clozure CL how to build the right kind of class object
       by including the :METACLASS option in the definition:
 
@@ -94,5 +94,5 @@
       This is the method that actually does the currency
       conversion. It's very simple—really, it just multiples
-      currency times rate. Most of the text in the definition is
+      currency times rate. Most of the text in the definition is
       Objective C bridge code that links the definition to the right
       class with the right argument and return types.
@@ -102,14 +102,16 @@
 
       The syntax #/convertCurrency:atRate: uses the
-      "#/" reader macro to read a symbol in mixed case, so that you
-      can see in your code the same name that Objective C uses for the
-      method, without worrying about how the name might be converted
-      between Lisp and Objective C conventions. The number of
-      arguments to an Objective C method is the number of colons in
-      the name, plus one. Each colon indicates an argument, and there
-      is always an extra "self" argument that refers to the object
-      that receives the message. These are normal Objective C
-      conventions, but we perhaps need to emphasize the details, since
-      we are using Lisp code to call the Objective C methods.
+      "#/" reader macro to read a symbol with case preserved, so that
+      you can see in your code the same name that Objective C uses for
+      the method, without worrying about how the name might be
+      converted between Lisp and Objective C conventions.
+
+      The number of arguments to an Objective C method is the
+      number of colons in the name, plus one. Each colon indicates an
+      argument, and there is always an extra "self" argument that
+      refers to the object that receives the message. These are normal
+      Objective C conventions, but we perhaps need to emphasize the
+      details, since we are using Lisp code to call the Objective C
+      methods.
 
       We indicate the return type and the types of arguments in
@@ -169,10 +171,14 @@
 
       
Each field in the definition of the ConverterController class
-      corresponds to one of the UI fields that you created in
-      InterfaceBuilder. For example, amount-field
-      corresponds to the text field that is connected to
-      the amountField outlet. The Objective C bridge
-      converts Lisp-style names (like "amount-field") to Objective
-      C-style names (like "amountField"). 
+      is an outlet that will be used to store a reference to one of
+      the UI fields that you created in InterfaceBuilder. For
+      example, amount-field will be connected to the
+      "Amount" text field. 
+
+      Why did we spell the name "amount-field" in Lisp code, and
+      "amountField" when creating the outlet in InterfaceBuilder?  The
+      Objective C bridge automatically converts Lisp-style field names
+      (like "amount-field") to Objective C-style field names (like
+      "amountField"), when handling class definitions.
 
       The converter field at launch time contains a
@@ -201,5 +207,5 @@
       "convertCurrency:atRate:" method of the Converter class. It then
       sets the text of the amount-field to reflect the result of the
-      conversion. The only singificant difference between this
+      conversion. The only significant difference between this
       implementation and Apple's is that the code is written in Lisp
       rather than Objective C.