@@ -38,5 +29,5 @@
Currency Converter example. The most important
difference between Apple's example and this one is that this
- one is implemented in Common Lisp instead of Objective C. It
+ one is implemented in Common Lisp instead of Objective-C. It
uses Clozure CL's Objective-C bridge to provide communication
between the Lisp code that you write and Apple's Cocoa
@@ -50,10 +41,27 @@
Apple's InterfaceBuilder application and Clozure CL.
+
An observant programmer will look at the code in this example
+ and say, "well, that's trivial! Why create all those classes and
+ connections and so forth just to perform a multiplcation?" That
+ observation is correct: the actual work done by the Currency
+ Converter application is trivial—both in the Lisp and the
+ Objective-C versions. The point of this example (and Apple's) is
+ not to show you how to perform a multiplication. The point is to
+ show you how Apple's frameworks implement and support the
+ Model-View-Controller paradigm, and how you can use that support
+ to build Cocoa applications. In fact, the work done by the
+ application is intentionally trivial, to emphasize the
+ frameworks rather than the particulars of the application.
+
+
This HOWTO has the additional purpose of showing you how
+ Clozure CL makes it possible to do exactly the same thing in
+ Lisp that you can do with Objective-C, so that you will
+ understand how to use Lisp with Apple's frameworks.
+
The current version of the Clozure CL Objective-C bridge
includes code that was formerly distributed separately as the
"Bosco" application framework. Because that framework has been
integrated with Clozure CL proper, it no longer exists as a
- separate project. "Bosco" now names only the decorative rodent
- at the top of this page.
+ separate project.
@@ -71,5 +79,5 @@
In some ways, the Lisp version of the example is simpler
- than the Objective C example, but the basic concepts are the
+ than the Objective-C example, but the basic concepts are the
same. In particular, the Lisp example follows the same
@@ -25,9 +25,9 @@
steps to build the Cocoa application are:
-
+
Load the application code into the IDE
Load the BUILD_APPLICATION feature
Run BUILD_APPLICATION with the proper arguments
-
+
This sequence of steps causes Clozure CL to construct a Cocoa
Index: /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html
===================================================================
--- /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html (revision 8464)
+++ /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui.html (revision 8465)
@@ -36,5 +36,5 @@
We'll begin by using Apple's InterfaceBuilder application to
create a nibfile. The nibfile contains
- archived versions of the Objective C objects that define the
+ archived versions of the Objective-C objects that define the
application's user interface. When you launch an application,
Mac OS X uses the archived objects in the nibfile to create the
@@ -70,5 +70,5 @@
create an application nibfile. InterfaceBuilder creates a new
application nibfile, but doesn't immediately save it. The
- Objective C objects that represent the new application's
+ Objective-C objects that represent the new application's
interface appear in a new untitled window:
@@ -91,5 +91,5 @@
-
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
@@ -108,5 +108,5 @@
Clozure CL main nibfile without causing any problems.
-
This difference between a Lisp project and an Objective C
+
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
@@ -120,6 +120,5 @@
Skip straight to the part of Apple's tutorial
called Defining
- the View: Building the User Interface. Read
- the introduction to
+the View: Building the User Interface. Read the introduction to
nibfiles, and follow the instructions to create the Currency Converter
interface. (Remember that when the tutorial tells you to open and edit
@@ -127,8 +126,9 @@
"CurrencyConverter.nib".) When you reach the end of the section
called Test
- the Interface, and move on to the short section afterward
- called What's Next,
- you are done creating the interface for your
-application. Save your nibfile and continue with the next section.
+the Interface, and move on to the short section afterward
+called What's
+Next, you are done creating the interface for your
+application. Save your nibfile and continue with the next section of
+this HOWTO.
@@ -153,5 +153,5 @@
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
+ Clozure CL Objective-C support for Intel systems works only on Mac
OS X 10.5.x ("Leopard").
@@ -167,8 +167,8 @@
connections in place.
-
When you use XCode to write an Objective C application,
- InterfaceBuilder can read the Objective C header files and use the
+
When you use XCode to write an Objective-C application,
+ InterfaceBuilder can read the Objective-C header files and use the
information in them to create descriptions of the classes in the
- Objective C code. When the application is written in Lisp,
+ Objective-C code. When the application is written in Lisp,
InterfaceBuilder can't read the class descriptions from the code,
and so we'll have to manually tell the nibfile about any classes
@@ -176,12 +176,11 @@
As you will see in the following sections, we'll use Lisp code to
- define two Objective C classes: Converter, and
+ define two Objective-C classes: Converter, and
ConverterController. The Converter class implements the method that
performs the actual currency conversion for our application; the
ConverterController class provides communication between the user
- interface and the Converter object. We need a way to create instaces
- of these two classes in the nibfile, so that launching the
- application creates these instances and the connections between them
- and the rest of the user interface.
+ interface and the Converter object. We need a way to create
+ instances of these two classes in the nibfile, so that launching the
+ application sets up all the objects correctly.
@@ -241,10 +240,10 @@
-
We'll connect each of the "field" outlets to one of the text
- fields in the CurrencyConverter UI, and we'll connect the
- "converter" outlet to the Converter instance that we created
- before. When the application launches, it creates the Converter and
+
We'll connect each of the "field" outlets to one of the text fields
+ in the CurrencyConverter UI, and we'll connect the "converter"
+ outlet to the Converter instance that we created before. When the
+ application launches, it creates the Converter and
ConverterController instances and establishes the connections that
- we specify in the nibfile.
+ we've specified in the nibfile.
@@ -264,5 +263,5 @@
outlets.
-
Now we'll connect outlets to objects and actions.
+
Now we'll connect outlets and actions to objects.
Index: /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html
===================================================================
--- /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html (revision 8464)
+++ /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/building_ui_tiger.html (revision 8465)
@@ -55,5 +55,5 @@
section and click the "New" button to create a new
nibfile. InterfaceBuilder creates a new application nibfile, but
- doesn't immediately save it. The Objective C objects that
+ doesn't immediately save it. The Objective-C objects that
represent the new application's interface appear in a new
untitled window:
@@ -72,5 +72,5 @@
-
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
@@ -89,5 +89,5 @@
Clozure CL main nibfile without causing any problems.
-
This difference between a Lisp project and an Objective C
+
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
@@ -183,5 +183,5 @@
-
Now add labels to the text fields, to idenitfy their
+
Now add labels to the text fields, to identify their
purposes for the user. For each text field, drag a Label object
from the palette and drop it next to the field. (Alternatively,
@@ -197,6 +197,6 @@
position the text field near the edge of the window, it also
displays guide lines to help you position the labels near the
- text fields. Just drag each text field until the blue guide
- lines appear, and release the label.
+ text fields. Just drag each label until the blue guide lines
+ appear, then release the label.
Now change the text of the labels. Click a label to select
@@ -233,8 +233,8 @@
The first two text fields accept user input; the last
- displays the result of the conversion. We want the first to text
- fields to be editable, so users can enter the values to use in
- the conversion. We don't want the last field to be editable, but
- we do want users to be able to copy text from it.
+ displays the result of the conversion. We want the first two
+ text fields to be editable, so users can enter the values to use
+ in the conversion. We don't want the last field to be editable,
+ but we do want users to be able to copy text from it.
We can control all this behavior using text-field
@@ -329,5 +329,5 @@
-
NOTE: This change isn't really enough to get your
+
NOTE: This change isn't really enough to get your
application to display the right name for the Application menu
when it's launched; the section
@@ -398,5 +398,5 @@
Users generally expect to be able to use the Tab key to move
from one text field to the next in a dialog
- box. InterfaceBuilder enables you to specify the tanning order
+ box. InterfaceBuilder enables you to specify the tabbing order
in text fields.
@@ -433,5 +433,5 @@
The visual elements of your application's user interface are
- all ready now. The last thing you must do is create descruptions
+ all ready now. The last thing you must do is create descriptions
of any custom classes used by the application when users
interact with the interface.
@@ -439,10 +439,9 @@
When a user clicks the "Convert" button, it should send a
message to a custom class that causes the conversion to take
- place, and the result to be displayed in the "Amount" field. In
- order for the application to connect the user interface to
- classes that perform these actions, you must add descriptions of
- your classes to the nibfile. Fortunately, InterfaceBuilder can
- create class descriptions and save them in the nibfile for
- you.
+ place. In order for the application to connect the user
+ interface to classes that perform these actions, you must add
+ descriptions of your classes to the nibfile. Fortunately,
+ InterfaceBuilder can create class descriptions and save them in
+ the nibfile for you.
@@ -554,11 +553,11 @@
view of the Inspector window, then click the "connect" button
to confirm.
-
Connect the "ConverterController" instance to text
+
Connect the "ConverterController" instance to the text
fields. Control-drag from the "ConverterController" instance
to the "Exchange Rate" field. Select "rateField" in the
"Outlets" view of the Inspector window and click "connect" to
- confirm. Then repeat this process, connecting "dollarField"
- to the "Dollars" text field, and "amountField" to the
- "Amount" field.
+ confirm. Then repeat this process, connecting "dollarField" to
+ the "Dollars" text field, and "amountField" to the "Amount"
+ field.
Finally, connect the "ConverterController" to the
"Converter" instance. Control-drag from the
@@ -566,5 +565,4 @@
instance. Select the "converter" outlet in the Inspector
window and click "connect" to confirm.
-
Index: /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html
===================================================================
--- /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html (revision 8464)
+++ /branches/gz-working/examples/cocoa/currency-converter/HOWTO_files/pages/conclusion.html (revision 8465)
@@ -17,5 +17,5 @@
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
+ Currency Converter, which, after all, just does a simple
multiplication. You can, however, use exactly the same steps to
build a much richer and more full-featured Cocoa
@@ -24,5 +24,5 @@
A more complex application will still consist of one or more
nibfiles and one or more Lisp source files. You will still use
- the Objective C bridge to define Objective C classes and
+ the Objective-C bridge to define Objective-C classes and
methods, and to use Cocoa library features. And you will still
use BUILD-APPLICATION to turn your source and nibfiles into
@@ -30,5 +30,5 @@
You should now be able to use Clozure CL to accomplish anything
- that an Objective C user can accomplish with Cocoa. Good luck!
+ that an Objective-C user can accomplish with Cocoa. Good luck!
In this section we'll write Lisp code that duplicates the
- features provided by the Objective C code in Apple's
+ 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
@@ -22,5 +22,5 @@
The Lisp code in this section of the HOWTO is considerably
- simpler than the corresponding Objective C code, in part
+ simpler than the corresponding Objective-C code, in part
because we can ignore the conventions that XCode uses for
laying out source files. We can just write all our definitions
@@ -37,5 +37,5 @@
(in-package "CCL")
-
Clozure CL'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
@@ -67,7 +67,7 @@
This is an ordinary CLOS class definition, with a couple of
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 CLOS
- definition actually creates a new Objective C class named
+ NS-OBJECT class in the "NS" package. NS-OBJECT is an Objective-C
+ class, the ancestor of all Objective-C objects. This CLOS
+ definition actually creates a new Objective-C class named
"Converter".
@@ -79,7 +79,7 @@
-
The Objective C bridge knows that when the metaclass
+
The Objective-C bridge knows that when the metaclass
is ns:+ns-object, it must lay out the class object
- in memory as an Objective C class, rather than a normal CLOS
+ in memory as an Objective-C class, rather than a normal CLOS
STANDARD-CLASS.
@@ -93,24 +93,27 @@
This is the method that actually does the currency
- conversion. It's very simple—really, it just multiples
+ conversion. It's a Lisp method that will be called when the
+ AppKit sends the Objective-C message "convertCurrency:atRate:"
+ It's very simple—really, it just multiples
currency times rate. Most of the text in the definition is
- Objective C bridge code that links the definition to the right
+ Objective-C bridge code that links the definition to the right
class with the right argument and return types.
objc:defmethod is a version of DEFMETHOD that
- creates Objective C method definitions.
+ creates methods that can execute in response to Objective-C
+ message-sends.
The syntax #/convertCurrency:atRate: uses the
"#/" 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
+ 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
+ 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
+ Objective-C conventions, but we perhaps need to emphasize the
+ details, since we are using Lisp code to call the Objective-C
methods.
@@ -163,21 +166,21 @@
-
Once again we use the Objective C bridge to define an
- Objective C class. This time, we provide several
+
Once again we use the Objective-C bridge to define an
+ Objective-C class. This time, we provide several
instance-variable definitions in the class, and name accessors
for each of them explicitly. The :FOREIGN-TYPE
- initargs enable us to specify the type of the field in the
- foreign (Objective C) class.
+ initargs enable us to specify the type of each field in the
+ foreign (Objective-C) class.
Each field in the definition of the ConverterController class
is an outlet that will be used to store a reference to one of
- the UI fields that you created in InterfaceBuilder. For
+ the text fields that you created in InterfaceBuilder. For
example, amount-field will be connected to the
- "Amount" text field.
+ "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
+ Objective-C bridge automatically converts Lisp-style field names
+ (like "amount-field") to Objective-C-style field names (like
"amountField"), when handling class definitions.
@@ -209,8 +212,8 @@
conversion. The only significant difference between this
implementation and Apple's is that the code is written in Lisp
- rather than Objective C.
+ rather than Objective-C.
This completes the definition of the CurrencyConverter's
- behavior. All that remains is to actually build the cocoa
+ behavior. All that remains is to actually build the Cocoa
application. The next section shows how to do that.
This HOWTO guide explains how to build interface databases
+ for Clozure CL (formerly OpenMCL).
+
+
Clozure CL's interface databases are
+ descriptions of foreign data structures and functions. Clozure
+ CL uses the interface databases to call C and Objective-C
+ functions, and to use C and Objective-C data
+ structures. Clozure CL provides the interface databases you
+ are most likely to need when writing Cocoa applications, but
+ it doesn't provide databases for every foreign library and
+ framework. For some applications, you may need to generate
+ interface databases yourself. This HOWTO shows how to do
+ that.
+
+
+
+
Online Documentation
+
+
+
+
The concepts explained here are also discussed in depth in
+ the OpenMCL online
+ documentation. See this
+ page for an explanation of how to generate interface
+ databases.
+
+
+
+
Interface Databases and the Foreign Function Interface
+
+
+
+
Clozure CL provides an integrated foreign function interface
+ that can call external C and Objective-C functions and methods,
+ define and instantiate Objective-C classes, and read and write
+ fields of C data structures. Using these features, a Lisp
+ program can interoperate freely with external libraries and
+ frameworks. Of special interest to Mac OS X programmers, Lisp
+ programs can link Mac OS X frameworks and use the features they
+ provide, including standard OS X features such as the AppKit,
+ CoreAudio, OpenGL, CoreAnimation, and so on.
+
+
+
+
Interface Databases and Frameworks
+
+
+
+
In order to use externally-defined functions and data
+ structures, Clozure CL needs descriptions of the entry points
+ and data fields, including their names and types. It reads
+ this information from the interface databases. A separate tool
+ called ffigen parses the header files that describe foreign
+ libraries and frameworks, such as the ones provided with
+ Apple's SDKs, to produce descriptions readable by Clozure CL's
+ parse-ffi subsystem. The parse-ffi subsystem then reads these
+ descriptions and writes the results of its processing to
+ files. These files, written by parse-ffi, are what we refer to
+ as interface databases.
+
+
+
+
Adding New Interface Databases
+
+
+
+
In order to generate a new set of interface databases, you
+ must follow these steps, explained in the following
+ sections:
+
+
+
Obtain and install the ffigen tool
+
Create an appropriately-named and -structured
+ subdirectory of the interfaces directory for your
+ platform
+
Write a script ("populate.sh") and then run it to populate the new interface
+ subdirectory
+
Using the parse-ffi subsystem, convert the ".ffi" files
+ created in the previous step to interface databases
+
+
+
+
+
1. Obtain and install ffigen
+
+
+
+
ffigen is a command-line tool, available from Clozure, that
+ parses C and Objective-C header files for use by the Clozure
+ CL parse-ffi subsystem. A "populate.sh" script drives the
+ ffigen tool to parse library or framework headers, and then
+ the Clozure CL parse-ffi subsystem converts the ffigen output
+ to interface databases. In order to generate interface
+ databases you must first obtain the latest version of ffigen
+ for the platform you are using.
+
+
ffigen is available from the Clozure ftp server
+ at clozure.com/pub/testing/. A
+ separate version of ffigen is available for each supported
+ platform. Make sure to get the latest version available for the
+ platform you are using. For example,
supports Apple's C compiler ("gcc") on the 64-bit Intel
+ platform ("x86-64").
+
+
Once you have the appropriate version of ffigen, unpack and
+ install it in a location where it will be convenient to
+ use. You might, for example, install it in /usr/local/ffigen,
+ or in ~/ffigen.
+
+
The ffigen distribution unpacks into a directory with the
+ following structure:
+
+
bin/
+
h-to-ffi.sh
+
ffigen/
+
bin/
+
ffigen
+
include/
+
+
To install ffigen, unpack the distribution, then move the
+ unpacked directory to its install location. For example, to
+ install it in /usr/local/ffigen:
You can now add a line to your shell's init script to add the
+ h-to-ffi.sh script to your PATH, and the script will find the
+ ffigen tool automatically.
+
+
For example, if your shell is bash, you can add this line to
+ your .bashrc or .bash_profile:
+
+
PATH="/usr/local/ffigen/bin:${PATH}"
+
+
+
+
+
2. Create An Interfaces Subdirectory
+
+
+
+
Clozure CL finds interface databases by consulting a
+ search-list. It initializes the search list when starting up,
+ and the exact contents of the search list depend on the
+ platform Clozure CL is running on. For example, a Mac OS X
+ version of Clozure CL running on the 64-bit Intel platform
+ searches "ccl/darwin-x86-headers64/", but a Mac OS X version
+ running on the 32-bit PowerPC platform searches
+ "ccl/darwin-headers/". We'll call this search directory
+ the interfaces directory. For the rest of this
+ discussion we'll assume we are running Clozure CL on Mac OS X
+ on the 64-bit Intel platform.
+
+
Each supported foreign library or framework has a
+ corresponding subdirectory of the interfaces directory. For
+ example, we can find a "cocoa" subdrectory of
+ "ccl/darwin-x86-headers64/"; it contains the interface databases
+ for the Cocoa framework. Similarly, the "gl" subdirectory
+ contains the interface databases for OpenGL.
+
+
In order to add support for a new framework, we must first
+ add a subdirectory for the framework to the interfaces
+ directory. For example, suppose we want to add support for the
+ TWAIN framework. This framework is one of the standard frameworks
+ provided in Mac OS X 10.5, but not one of those supported
+ out-of-the-box by Clozure CL.
+
+
To add TWAIN interfaces for use by Clozure CL, follow these
+ steps:
+
+
+
Create a subdirectory called "twain" in the interfaces directory
+
+
Create a subdirectory of "twain" called "C".
+
If you look inside any of the existing interfaces
+ subdirectories, you see that each one contains a similar
+ "C" subdirectory. The ffigen tool populates these "C"
+ subdirectories with ".ffi" files when it parses the
+ framework or library headers.
+
+
+
Inside the "C" subdirectory, create a file called
+ "populate.sh"
+
Again, you can see that the existing interfaces
+ subdirectories contain "populate.sh" files in their "C"
+ subdirectories. This file is the script that drives the
+ ffigen tool for the particular interface databases we are
+ creating. The next section explains what to put in the
+ "populate.sh" file.
+
+
+
+
+
+
+
3. Write and Run a "populate.sh" Script
+
+
+
+
If you look in the directory
+
+
ccl/darwin-x86-headers64/cocoa/C/
+
+
for example, you'll find a script named populate.sh. The
+ script sets up flags for the C compiler, and then calls
+ h-to-ffi.sh on each of several header files that define the
+ Objective-C data structures and entry points used by the Cocoa
+ framework. The first step in generating or regenerating the
+ interface databases is to run one of these populate.sh
+ scripts.
+
+
You can create a populate.sh script by copying an existing
+ one from another set of interfaces, then replacing the
+ references to the libraries or frameworks that the
+ populate.sh script processes. A good place to start is with
+ an existing populate.sh script that processes a library or
+ framework that is similar to, or related to, the one you want
+ to add.
+
+
For example, for our TWAIN interfaces, we can copy the
+ populate.sh script from the existing qtkit subdirectory. The
+ contents of the qtkit script are:
+
+
+
+#!/bin/sh
+# For now, things earlier than the 10.5 sdk are pointless
+rm -rf System Developer usr
+SDK=/Developer/SDKs/MacOSX10.5.sdk
+CFLAGS="-m64 -fobjc-abi-version=2 -isysroot ${SDK} -mmacosx-version-min=10.5"; export CFLAGS
+h-to-ffi.sh ${SDK}/System/Library/Frameworks/QTKit.framework/Headers/QTKit.h
+
+
+
+
Now we just need to change the reference to the QTKit header
+ file so that it refers instead to the TWAIN header file:
+
+
+#!/bin/sh
+# For now, things earlier than the 10.5 sdk are pointless
+rm -rf System Developer usr
+SDK=/Developer/SDKs/MacOSX10.5.sdk
+CFLAGS="-m64 -fobjc-abi-version=2 -isysroot ${SDK} -mmacosx-version-min=10.5"; export CFLAGS
+h-to-ffi.sh ${SDK}/System/Library/Frameworks/TWAIN.framework/Headers/TWAIN.h
+
+
+
Next you must run the script to generate the ".ffi" files
+ that will be used in the next step. Assuming you installed
+ ffigen as described in step 1, and made sure that it's on your
+ PATH, all you have to do is cd to the directory that contains
+ your new populate.sh script and execute it:
Now, if you look inside the C subdirectory of your twain
+ directory, you should find that it has been populated with
+ ".ff" files:
+
+
+oshirion:C mikel$ ls
+./ ../ Developer/ populate.sh*
+
+oshirion:C mikel$ ls Developer/SDKs/MacOSX10.5.sdk/System/Library/Frameworks/TWAIN.framework/Headers/
+./ ../ TWAIN.ffi
+
+
+
+
+
+
4. Use parse-ffi to Generate Interface Databases
+
+
+
+
The ".ffi" files, created in the prevoius step, contain a
+ series of s-expressions readable by the Clozure CL parse-ffi
+ subsystem. Each s-expression describes a datastructure or
+ entry point in the foreign library.
+
+
Once you have created a set of these ".ffi" files by running
+ a populate.sh script, you must next use Clozure CL to convert
+ the ".ffi" files into interface database files.
+
+
+
First, launch Clozure CL
+
+
Next, evaluate this form to load the parse-ffi subsystem:
+
(require "PARSE-FFI")
+
+
+
Next, supposing you want to parse the TWAIN files
+ created in the previous section, evaluate the following form:
+
(ccl::parse-standard-ffi-files :twain)
+
The parse-ffi subsystem looks for a subdirectory named
+ "twain" in the interface databases directory for the
+ current platform.
+
+
The first time you run this expression, you'll see
+ warnings like this one:
+
+; Warning: Interface file #P"ccl:darwin-x86-headers64;twain;types.cdb.newest" does not exist.
+
+
These warnings are normal.
+
+
+
Finally, evaluate the following form once more:
+
(ccl::parse-standard-ffi-files :twain)
+
In order to correctly describe some foreign definitions,
+ the parse-ffi subsystem needs information provided by the
+ first parse. Thus, to produce a complete and corrrect set of
+ interface databases, you should always evaluate
+ the parse-standard-ffi-files form twice.
+
+
+
+
+
+
+
+
Conclusion
+
+
+
+
Assuming all went well, you should now find a new set of
+ interface database files in the twain subdirectory of the
+ interface databases directory for your current
+ platform. Congratulations! You have added a new set of
+ interface databases to your Clozure CL installation.
+
+
For more information about ffigen and the interface
+ translation process, refer to the online documentation for the
+ Interface
+ Translator.
This HOWTO shows how you can load nibfiles
+ into a running copy of Clozure CL by evaluating Lisp forms. You
+ might want to load nibfiles this way to test user-interface
+ elements that you are working on for an application project, or
+ to enable an application to dynamically load optional
+ user-interface elements.
+
+
+
+
+
Nibfiles
+
+
+
+
A large part of developing Cocoa applications is creating
+ user-interface elements using the Cocoa frameworks. Although
+ it's perfectly possible to create any user-interface element
+ just by making method calls against the frameworks, the more
+ standard way to design a user interface is to use Apple's
+ InterfaceBuilder application to
+ create nibfiles—files of archived
+ Objective-C objects that implement the user-interface
+ elements.
+
+
InterfaceBuilder is an appliaction 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
+ need to make sure that Apple's Developer Tools are installed on
+ your system. Members of Apple's developer programs may download
+ the tools for free from
+ Apple's developer
+ website, but normally there is no need. You can simply
+ use the optional Developer Tools installer on the Mac OS X
+ system disks to install the tools.
+
+
+
+
Using Nibfiles
+
+
+
+
Using InterfaceBuilder, you can quickly and easily create
+ windows, dialog boxes, text fields, buttons, and other
+ user-interface elements. The elements you create with
+ InterfaceBuilder have the standard appearance and behavior
+ specified by Apple's Human Interface Guidelines.
+
+
InterfaceBuilder saves descriptions of these objects
+ in nibfiles. These files contain archived
+ representations of Objective-C classes and objects. When you
+ launch an application and it loads a nibfile, the Cocoa runtime
+ creates these Objective-C objects in memory, complete with any
+ instance-variable references to other objects that might have
+ been saved in the nibfile. In short, a nibfile is an archived
+ collection of user-interface objects that Cocoa can quickly and
+ easily revive in memory.
+
+
The normal way that Objective-C programmers use nibfiles is
+ by storing them in an application bundle. The application's
+ Info.plist file (also stored in the bundle) specifies which
+ nibfile is the application's main nibfile, and that file is
+ loaded automatically when the application starts up. The
+ application can dynamically load other nibfiles from the bundle
+ by making method calls.
+
+
Lisp applications written with Clozure CL can also use
+ nibfiles in this same fashion (see the "currency-converter"
+ HOWTO in the "cocoa" examples folder), but Lisp programmers are
+ accustomed to highly interactive development, and might want to
+ simply load an arbitrary nibfile into a running Clozure CL
+ session. Fortunately, this is easy to do.
+
+
+
+
How To Load a Nibfile
+
+
+
+
Let's start by loading a very simple nibfile from the Clozure
+ CL Listener window. Start by launching the Clozure CL
+ application.
+
+
In the same directory as this HOWTO file, you'll find a
+ nibfile named "hello.nib". This is an extremely simple nibfile
+ that creates a single Cocoa window with a greeting in it. We'll
+ use forms typed into the Listener window to load it.
+
+
We're going to call the Objective-C class
+ method loadNibFile:externalNameTable:withZone: to
+ load the nibfile into memory, creating the window that is
+ described in the file. First, though, we need to set up some
+ data structures that we'll pass to this method.
+
+
The arguments
+ to loadNibFile:externalNameTable:withZone: are a
+ pathname, a dictionary object, and a memory zone. As with every
+ Objective-C method call, we also pass the object that receives
+ the message, which in this case is the class NSBundle.
+
+
The pathname is just a reference to the nibfile we want to
+ load. The dictionary holds references to objects—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.
+
+
Don't worry if none of this makes sense to you; the code to
+ create these objects is simple and straightforward, and should
+ help clarify what's going on.
+
+
+
1. Get the Zone
+
+
+
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.
+
+
Before we can ask the application anything, we need a
+ reference to it. We'll ask the class NSApplication to give us a
+ reference to the running application.
+
+
Start by changing to the CCL package; most of the utility
+ functions we'll use are defined in that package:
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.
+
+
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.
+
+
Now that we have the application class, we can ask it for a
+ reference to the running application:
Now we have a reference to the application's zone. We can
+ pass it
+ to loadNibFile:externalNameTable:withZone: to
+ tell it to allocate the nibfile's objects in the
+ application's zone.
+
+
+
2. Make a Dictionary
+
+
+
The dictionary argument
+ to loadNibFile:externalNameTable:withZone: 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
+ key "NSNibOwner".
+
+
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 "NSNibTopLevelObjects".
+
+
For this first example, we'll pass an owner object (the
+ application object), but we don't need to collect toplevel
+ objects, so we'll omit
+ the "NSNibTopLevelObjects" key.
The window defined in the "hello.nib" file should appear
+ on the
+ screen. The loadNibFile:externalNameTable:withZone:
+ method returns T to indicate it loaded the
+ nibfile successfully; if it had failed, it would have
+ returned NIL.
-