Changeset 8695


Ignore:
Timestamp:
Mar 8, 2008, 10:04:52 PM (12 years ago)
Author:
mikel
Message:

added more discussion of the IDE and its UI, and of BUILD-APPLICATION

Location:
trunk/source/doc/src
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/glossary.xml

    r8694 r8695  
    1616  </glossaryinfo>
    1717
     18  <glossdiv id="A">
     19        <!-- ******************** A ********************  -->
     20        <title>A</title>
     21
     22        <glossentry id="application_bundle">
     23          <glossterm>application bundle</glossterm>
     24
     25          <glossdef>
     26
     27                <para>A specially-structured directory that Mac OS X
     28                recognizes as a
     29                launchable <glossterm linkend="Cocoa">Cocoa</glossterm>
     30                application. Graphical applications on Mac OS X are
     31                represented as application bundles.</para>
     32
     33          </glossdef>
     34
     35        </glossentry>
     36   
     37  </glossdiv>
     38
    1839  <glossdiv id="C">
    1940        <!-- ******************** C ********************  -->
     
    3051
    3152          </glossdef>
     53        </glossentry>
     54   
     55        <glossentry id="creator_code">
     56          <glossterm>creator code</glossterm>
    3257
     58          <glossdef>
     59
     60                <para>A four-character identifier used in Mac OS X to uniquely
     61                identify an application.</para>
     62
     63          </glossdef>
    3364        </glossentry>
    3465   
     
    73104        </glossentry>
    74105   
     106        <glossentry id="InterfaceBuilder">
     107          <glossterm>InterfaceBuilder</glossterm>
     108
     109          <glossdef>
     110
     111                <para>An application supplied by Apple with their developer
     112                tools that can be used to interactively build user-interface
     113                elements for <glossterm linkend="Cocoa">Cocoa</glossterm>
     114                applications.</para>
     115
     116          </glossdef>
     117
     118        </glossentry>
     119   
    75120  </glossdiv>
    76121
     
    95140  </glossdiv>
    96141
     142  <glossdiv id="N">
     143        <!-- ******************** N ********************  -->
     144        <title>N</title>
     145
     146        <glossentry id="nibfile">
     147          <glossterm>nibfile</glossterm>
     148
     149          <glossdef>
     150
     151                <para>A data file created by
     152                Apple's <glossterm linkend="InterfaceBuilder">InterfaceBuilder</glossterm>
     153                application, which contains archived Objective-C objects that
     154                define user-interface elements for
     155                a <glossterm linkend="Cocoa">Cocoa</glossterm>
     156                application. Under Mac OS
     157                X, <glossterm linkend="Cocoa">Cocoa</glossterm> applications
     158                typically create their user interface elements by reading
     159                nibfiles and unarchiving the objects in them.</para>
     160
     161          </glossdef>
     162
     163        </glossentry>
     164   
     165  </glossdiv>
     166
    97167  <glossdiv id="R">
     168
    98169        <!-- ******************** R ********************  -->
    99170        <title>R</title>
  • trunk/source/doc/src/ide.xml

    r8694 r8695  
    2121
    2222    <para>The IDE is still in a preliminary state, and may lack many
    23     features you would expect to find in a polished Cocoa
    24     application. It does, however, provide a text editor and listener
    25     windows, an inspector for Lisp data structures, and a means of
    26     easily building a Cocoa application in Lisp. In addition, its
    27     source code provides an example of a fairly complex Cocoa
    28     application written in Lisp.</para>
     23      features you would expect to find in a polished Cocoa
     24      application. It does, however, provide a text editor and listener
     25      windows, an inspector for Lisp data structures, and a means of
     26      easily building a Cocoa application in Lisp. In addition, its
     27      source code provides an example of a fairly complex Cocoa
     28      application written in Lisp.</para>
    2929
    3030    <para>A more rudimentary version of the Clozure CL IDE has been
     
    3939   
    4040    <para>Building the Clozure CL IDE is now a very simple
    41     process.</para>
     41      process.</para>
    4242
    4343    <orderedlist>
     
    4747      <listitem>
    4848        <para>Run ccl from the shell. The easiest way to do this is
    49         generally to execute the openmcl or openmcl64 command.</para>
     49          generally to execute the openmcl or openmcl64 command.</para>
    5050      </listitem>
    5151      <listitem>
     
    5555
    5656    <para>For example, assuming that the &CCL; distribution is
    57     installed in "/usr/local/ccl", the following sequence of shell
    58     interactions builds the IDE:</para>
     57      installed in "/usr/local/ccl", the following sequence of shell
     58      interactions builds the IDE:</para>
    5959
    6060    <programlisting>
    61 oshirion:ccl mikel$ openmcl64
    62 Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
    63 ? (require :cocoa-application)
    64 ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
    65 ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
    66 
    67   [...many lines of "Compiling" and "Loading" omitted...]
    68 
    69 Saving application to /usr/local/ccl/Clozure CL.app/
    70 
    71 oshirion:ccl mikel$
     61      oshirion:ccl mikel$ openmcl64
     62      Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
     63      ? (require :cocoa-application)
     64      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
     65      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
     66
     67      [...many lines of "Compiling" and "Loading" omitted...]
     68
     69      Saving application to /usr/local/ccl/Clozure CL.app/
     70
     71      oshirion:ccl mikel$
    7272
    7373    </programlisting>
     
    8787      launched, the IDE initially displays a
    8888      single <glossterm linkend="listener_window">listener
    89       window</glossterm> that you can use to interact with Lisp. You
     89        window</glossterm> that you can use to interact with Lisp. You
    9090      can type Lisp expressions for evaluation at the prompt in the
    9191      listener window. You can also
     
    109109
    110110      <para>Editor windows
    111       implement <glossterm linkend="hemlock">Hemlock</glossterm>
    112       editing commands. You can use all the editing and customization
    113       features of Hemlock within any editor window (including listener
    114       windows).</para>
     111        implement <glossterm linkend="hemlock">Hemlock</glossterm>
     112        editing commands. You can use all the editing and customization
     113        features of Hemlock within any editor window (including listener
     114        windows).</para>
    115115    </sect2>
    116116   
     
    118118      <title>The Lisp Menu</title>
    119119      <para>The Lisp menu provides several commands for interacting
    120       with the running Lisp session, in addition to the ways you can
    121       interact with it by evaluating expressions. You can evaluate a
    122       selected range of text in any editing buffer. You can compile
    123       and load the contents of editor windows (please note that in the
    124       current version, &CCL; compiles and loads the contents of the
    125       file associated with an editor window; that means that if you
    126       try to load or compile a window that has not been saved to a
    127       file, the result is an error).</para>
     120        with the running Lisp session, in addition to the ways you can
     121        interact with it by evaluating expressions. You can evaluate a
     122        selected range of text in any editing buffer. You can compile
     123        and load the contents of editor windows (please note that in the
     124        current version, &CCL; compiles and loads the contents of the
     125        file associated with an editor window; that means that if you
     126        try to load or compile a window that has not been saved to a
     127        file, the result is an error).</para>
    128128
    129129      <para>You can interrupt computations, trigger breaks, and select
    130       restarts from the Lisp menu. You can also display a backtrace or
    131       open the <link linkend="section_inspector_window">Inspector
    132       window</link>.</para>
     130        restarts from the Lisp menu. You can also display a backtrace or
     131        open the <link linkend="section_inspector_window">Inspector
     132          window</link>.</para>
    133133    </sect2>
    134134
     
    136136      <title>The Tools Menu</title>
    137137      <para>The tools menu provides access to the Apropos and
    138       Processes windows. The Apropos window searches the running Lisp
    139       image for symbols that match any text you enter. You can use the
    140       Apropos window to quickly find function names and other useful
    141       symbols. The Processes window lists all threads running in the
    142       current Lisp session. If you double-click a process entry, &CCL;
    143       opens an <link linkend="section_inspector_window">Inspector
    144       window</link> on that process.</para>
     138        Processes windows. The Apropos window searches the running Lisp
     139        image for symbols that match any text you enter. You can use the
     140        Apropos window to quickly find function names and other useful
     141        symbols. The Processes window lists all threads running in the
     142        current Lisp session. If you double-click a process entry, &CCL;
     143        opens an <link linkend="section_inspector_window">Inspector
     144          window</link> on that process.</para>
    145145    </sect2>
    146146
     
    149149      <anchor id="section_inspector_window"/>
    150150      <para>The Inspector window displays information about a Lisp
    151       value. The information displayed varies from the very simple, in
    152       the case of a simple data value such as a character, to the
    153       complex, in the case of structured data such as lists or CLOS
    154       objects. The lefthand column of the window's display shows the
    155       names of the object's attributes; the righthand column shows the
    156       values associated with those attributes. You can inspect the
    157       values in the righthand column by double-clicking them.</para>
     151        value. The information displayed varies from the very simple, in
     152        the case of a simple data value such as a character, to the
     153        complex, in the case of structured data such as lists or CLOS
     154        objects. The lefthand column of the window's display shows the
     155        names of the object's attributes; the righthand column shows the
     156        values associated with those attributes. You can inspect the
     157        values in the righthand column by double-clicking them.</para>
    158158
    159159      <para>Inspecting a value in the righthand column changes the
    160       Inspector window to display the double-clicked object. You can
    161       quickly navigate the fields of structured data this way,
    162       inspecting objects and the objects that they refer
    163       to. Navigation buttons at the top left of the window enable you
    164       to retrace your steps, backing up to return to previously-viewed
    165       objects, and going forward again to objects you navigated into
    166       previously.</para>
     160        Inspector window to display the double-clicked object. You can
     161        quickly navigate the fields of structured data this way,
     162        inspecting objects and the objects that they refer
     163        to. Navigation buttons at the top left of the window enable you
     164        to retrace your steps, backing up to return to previously-viewed
     165        objects, and going forward again to objects you navigated into
     166        previously.</para>
    167167
    168168      <para>You can change the contents of a structured object by
    169       evaluating expressions in a listener window. The refresh button
    170       (marked with a curved arrow) updates the display of the
    171       Inspector window, enabling you to quickly see the results of
    172       changing a data structure.</para>
     169        evaluating expressions in a listener window. The refresh button
     170        (marked with a curved arrow) updates the display of the
     171        Inspector window, enabling you to quickly see the results of
     172        changing a data structure.</para>
    173173    </sect2>
    174174
     
    178178   
    179179    <para>&CCL; builds the IDE from sources in the "objc-bridge" and
    180     "cocoa-ide" directories in the &CCL; distribution. The IDE as a
    181     whole is a relatively complicated application, and is probably not
    182     the best place to look when you are first trying to understand how
    183     to build Cocoa applications. For that, you might benefit more from
    184     the examples in the "examples/cocoa/" directory. Once you are
    185     familiar with those examples, though, and have some experience
    186     building your own application features using Cocoa and the
    187     Objective-C bridge, you might browse through the IDE sources to
    188     see how it implements its features.</para>
     180      "cocoa-ide" directories in the &CCL; distribution. The IDE as a
     181      whole is a relatively complicated application, and is probably not
     182      the best place to look when you are first trying to understand how
     183      to build Cocoa applications. For that, you might benefit more from
     184      the examples in the "examples/cocoa/" directory. Once you are
     185      familiar with those examples, though, and have some experience
     186      building your own application features using Cocoa and the
     187      Objective-C bridge, you might browse through the IDE sources to
     188      see how it implements its features.</para>
    189189
    190190    <para>The search path for &CCL;'s <code>REQUIRE</code> feature
    191     includes the "objc-bridge" and "cocoa-ide" directories. You can
    192     load features defined in these directories by
    193     using <code>REQUIRE</code>. For example, if you want to use the
    194     Cocoa features of &CCL; from a terminal session (or from an Emacs
    195     session using SLIE or ILISP), you can evaluate <code>(require
    196     :cocoa)</code>.</para>
    197   </sect1>
    198 
     191      includes the "objc-bridge" and "cocoa-ide" directories. You can
     192      load features defined in these directories by
     193      using <code>REQUIRE</code>. For example, if you want to use the
     194      Cocoa features of &CCL; from a terminal session (or from an Emacs
     195      session using SLIE or ILISP), you can evaluate <code>(require
     196        :cocoa)</code>.</para>
     197  </sect1>
     198
     199  <sect1><title>The Application Builder</title>
     200   
     201    <para>One important feature of the IDE currently has no Cocoa user
     202      interface: the application builder. The application builder
     203      constructs a
     204      Cocoa <glossterm linkend="application_bundle">application
     205        bundle</glossterm> that runs a Lisp image when double-clicked. You
     206      can use the application builder to create Cocoa applications in
     207      Lisp. These applications are exactly like Cocoa applications
     208      created with XCode and Objective-C, except that they are written
     209      in Lisp.</para>
     210
     211    <para>To make the application builder available, evaluate the
     212      expression <code>(require :build-application)</code>. &CCL; loads
     213      the required subsystems, if necessary.</para>
     214
     215    <para>
     216      <command><varname>BUILD-APPLICATION</varname> <varname>&amp;key</varname>
     217        (<parameter>name</parameter> <replaceable>"MyApplication"</replaceable>)
     218        (<parameter>type-string</parameter> <replaceable>"APPL"</replaceable>)
     219        (<parameter>creator-string</parameter> <replaceable>"OMCL"</replaceable>)
     220        (<parameter>directory</parameter> <replaceable>(current-directory)</replaceable>)
     221        (<parameter>nibfiles</parameter> <replaceable>NIL</replaceable>)
     222        (<parameter>main-nib-name</parameter> <replaceable>NIL</replaceable>)
     223        (<parameter>application-class</parameter> <replaceable>'GUI::COCOA-APPLICATION</replaceable>)
     224        (<parameter>toplevel-function</parameter> <replaceable>NIL</replaceable>)
     225        [Function]</command>
     226    </para>
     227
     228    <para>
     229      The <varname>build-application</varname> function constructs an
     230      application bundle, populates it with the files needed to satisfy
     231      Mac OS X that the bundle is a launchable application, and saves an
     232      executable Lisp image to the proper subdirectory of the
     233      bundle. Assuming that the saved Lisp image contains correct code,
     234      a user can subsequently launch the resulting Cocoa application by
     235      double-clicking its icon in the Finder, and the saved Lisp
     236      environment runs.
     237    </para>
     238
     239    <para>The keyword arguments control various aspects of application
     240      bundle as <code>BUILD-APPLICATION</code> builds it.</para>
     241    <variablelist>
     242
     243      <varlistentry>
     244        <term><varname>name</varname></term>
     245        <listitem>
     246          <para>Specifies the application name of the
     247            bundle. <code>BUILD-APPLICATION</code> creates an application
     248            bundle whose name is given by this parameter, with the
     249            extension ".app" appended. For example, using the default
     250            value for this parameter results in a bundle named
     251            "MyApplication.app".</para>
     252        </listitem>
     253      </varlistentry>
     254
     255      <varlistentry>
     256        <term><varname>type-string</varname></term>
     257        <listitem>
     258          <para>Specifies type of bundle to create. You should normally
     259            never need to change the default value, which Mac OS X uses to
     260            identify application bundles.</para>
     261        </listitem>
     262      </varlistentry>
     263
     264      <varlistentry>
     265        <term><varname>creator-string</varname></term>
     266        <listitem>
     267          <para>Specifies the <glossterm linkend="creator_code">creator
     268              code</glossterm>, which uniquely identifies the application
     269            under Mac OS X. The default creator code is that of &CCL;. For
     270            more information about reserving and assigning creator codes,
     271            see
     272            Apple's <ulink url="http://developer.apple.com/datatype/index.html">developer
     273              page</ulink> on the topic.</para>
     274        </listitem>
     275      </varlistentry>
     276
     277      <varlistentry>
     278        <term><varname>directory</varname></term>
     279        <listitem>
     280          <para>The directory in which <code>BUILD-APPLICATION</code>
     281            creates the application bundle. By default, it creates the
     282            bundle in the current working directory. Unless you
     283            use <code>CURRENT-DIRECTORY</code> to set the working
     284            directory, the bundle may be created in some unexpected place,
     285            so it's safest to specify a full pathname for this argument. A
     286            typical value might be <code>"/Users/foo/Desktop/"</code>
     287            (assuming, of course, that your username is "foo").</para>
     288        </listitem>
     289      </varlistentry>
     290
     291      <varlistentry>
     292        <term><varname>nibfiles</varname></term>
     293        <listitem>
     294          <para>A list of pathnames, where each pathname identifies
     295            a <glossterm linkend="nibfile">nibfile</glossterm> created
     296            with
     297            Apple's <glossterm linkend="InterfaceBuilder">InterfaceBuilder</glossterm>
     298            application. <code>BUILD-APPLICATION</code> copies each
     299            nibfile into the appropriate place in the application bundle,
     300            enabling the application to load user-interface elements from
     301            them as-needed. It is safest to provide full pathnames to the
     302            nibfiles in the list. Each nibfile must be in ".nib" format,
     303            not ".xib" format, in order that the application can load
     304            it.</para>
     305        </listitem>
     306      </varlistentry>
     307
     308      <varlistentry>
     309        <term><varname>main-nib-name</varname></term>
     310        <listitem>
     311          <para>The name of
     312            the <glossterm linkend="nibfile">nibfile</glossterm> to load
     313            initially when launching. The user-interface defined in this
     314            nibfile becomes the application's main interface. You must
     315            supply the name of a suitable nibfile for this parameter, or
     316            the resulting application uses the &CCL; user
     317            interface.</para>
     318        </listitem>
     319      </varlistentry>
     320
     321      <varlistentry>
     322        <term><varname>application-class</varname></term>
     323        <listitem>
     324          <para>The name of the application's CLOS class. The defaut
     325            value is the class provided by &CCL; for graphical
     326            applications. Supply the name of your application class if you
     327            implement one. If not, &CCL; uses the default class.</para>
     328        </listitem>
     329      </varlistentry>
     330
     331      <varlistentry>
     332        <term><varname>toplevel-function</varname></term>
     333        <listitem>
     334          <para>The toplevel function that runs when the application
     335            launches. Normally the default value, which is &CCL;'s
     336            toplevel, works well, but in some cases you may wish to
     337            customize the behavior of the application's toplevel. The best
     338            source of information about writing your own toplevel is the
     339            &CCL; source code, especially the implementations
     340            of <code>TOPLEVEL-FUNCTION</code> in
     341            "ccl/level-1/l1-application.lisp"</para>
     342        </listitem>
     343      </varlistentry>
     344
     345    </variablelist>
     346
     347    <para>Please note that <code>BUILD-APPLICATION</code> is a work in
     348    progress. It can easily build a working Cocoa application, but it
     349    still has limitations that may in some cases prove
     350    inconvenient. For example, in the current version it provides no
     351    easy way to specify an application delegate different from the
     352    default. If you find the current limitations
     353    of <code>BUILD-APPLICATION</code> too restrictive, and want to rty
     354    extending it for your use, you can find the source code for it
     355    in "ccl/cocoa-ide/build-application.lisp".</para>
     356
     357    <para>For more information on how to
     358    use <code>BUILD-APPLICATION</code>, see the Currency Converter
     359    example in "ccl/examples/cocoa/currency-converter/".</para>
     360  </sect1>
    199361
    200362</chapter>
Note: See TracChangeset for help on using the changeset viewer.