Apr 1, 2008, 5:07:25 PM (12 years ago)

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

1 edited


  • trunk/source/doc/src/objc-bridge.xml

    r8908 r8981  
    3030    Cocoa.</para>
     32  <!-- ============================================================ -->
    3233  <sect1 id="Objective-C-Changes-1.2">
    3334    <title>Changes in 1.2</title>
    3536    <para>Version 1.2 of &CCL; exports most of the useful symbols
    3637    described in this chapter; in previous releases, most of them were
    37     private in the <code>CCL</code> package.</para>
     38    private in the <literal>CCL</literal> package.</para>
    3940    <para>There are several new reader macros that make it much more
    40     conveinent than before to refer to several classes of symbols used
     41    convenient than before to refer to several classes of symbols used
    4142    with the Objective-C bridge. For a full description of these
    4243    reader-macros, see
    5253    <para>The Objective-C bridge defines the
    53       type <code>NS:CGFLOAT</code> as the Lisp type of the preferred
     54      type <literal>NS:CGFLOAT</literal> as the Lisp type of the preferred
    5455      floating-point type on the current platform, and defines the
    55       constant <code>NS:+CGFLOAT+</code>.  On DarwinPPC32, the foreign
    56       types <code>:cgfloat</code>, <code>:&lt;NSUI&gt;nteger</code>,
     56      constant <literal>NS:+CGFLOAT+</literal>.  On DarwinPPC32, the foreign
     57      types <literal>:cgfloat</literal>, <literal>:&lt;NSUI&gt;nteger</literal>,
    5758      and
    58       <code>:&lt;NSI&gt;nteger</code> are defined by the Objective-C
     59      <literal>:&lt;NSI&gt;nteger</literal> are defined by the Objective-C
    5960      bridge (as 32-bit float, 32-bit unsigned integer, and 32-bit
    6061      signed integer, respectively); these types are defined as 64-bit
    6364    <para>Every Objective-C class is now properly named, either with a
    64       name exported from the <code>NS</code> package (in the case of a
     65      name exported from the <literal>NS</literal> package (in the case of a
    6566      predefined class declared in the interface files) or with the
    66       name provided in the <code>DEFCLASS</code> form (with <code>:METACLASS</code>
    67       <code>NS:+NS-OBJECT</code>) which defines the class from Lisp.
     67      name provided in the <literal>DEFCLASS</literal> form (with <literal>:METACLASS</literal>
     68      <literal>NS:+NS-OBJECT</literal>) which defines the class from Lisp.
    6869      The class's Lisp name is now proclaimed to be a "static"
    69       variable (as if by <code>DEFSTATIC</code>, as described in the
     70      variable (as if by <literal>DEFSTATIC</literal>, as described in the
    7071      <link linkend="Static_Variables">"Static Variables"
    7172      section</link>) and given the class object as its value.  In
    8990  </sect1>
     92  <!-- ============================================================ -->
    9193  <sect1 id="Using-Objective-C-Classes">
    9294    <title>Using Objective-C Classes</title>
    140142  </sect1>
     144  <!-- ============================================================ -->
    142145  <sect1 id="Instantiating-Objective-C-Objects">
    143146    <title>Instantiating Objective-C Objects</title>
    160163    <para>Allocating an instance of an Objective-C class involves sending the
    161164      class an "alloc" message, and then using those initargs that
    162       <emphasis>don't</emphasis> correspond to slot initags as the
     165      <emphasis>don't</emphasis> correspond to slot initargs as the
    163166      "init" message to be sent to the newly-allocated instance.  So, the
    164167      example above could have been done more verbosely as:</para>
    199202      do this, the object is only allocated, and not initialized.  It
    200203      then sends the "init" message to do the initialization by hand.</para>
     205    <para>There is an alternative API for instantiating Objective-C
     206      classes. You can
     207      call <literal>OBJC:MAKE-OBJC-INSTANCE</literal>, passing it the
     208      name of the Objective-C class as a string. In previous
     209      releases, <literal>OBJC:MAKE-OBJC-INSTANCE</literal> could be
     210      more efficient than <literal>OBJC:MAKE-INSTANCE</literal> in
     211      cases where the class did not define any Lisp slots; this is no
     212      longer the case. You can now
     213      regard <literal>OBJC:MAKE-OBJC-INSTANCE</literal> as completely
     214      equivalent to <literal>OBJC:MAKE-INSTANCE</literal>, except that
     215      you can pass a string for the classname, which may be convenient
     216      in the case that the classname is in some way unusual.</para>
    201217  </sect1>
     219  <!-- ============================================================ -->
    203220  <sect1 id="Calling-Objective-C-Methods">
    204221    <title>Calling Objective-C Methods</title>
    307324(send v1 :set-bounds (send v2 'bounds))
    308325      </programlisting>
    309       <para>There are also several psuedo-functions provided for convenience
     326      <para>There are also several pseudo-functions provided for convenience
    310327        by the Objective-C compiler, to make objects of specific types. The
    311328        following are currently supported by the bridge: NS-MAKE-POINT,
    428445  </sect1>
     447  <!-- ============================================================ -->
    430448  <sect1 id="Defining-Objective-C-Classes">
    431449    <title>Defining Objective-C Classes</title>
    514532  </sect1>
     534  <!-- ============================================================ -->
    516535  <sect1 id="Defining-Objective-C-Methods">
    517536    <anchor id="anchor_Defining-Objective-C-Methods"/>
    523542      belonging to Objective-C classes which have been defined in
    524543      Lisp.</para>
    525545    <para>You can use either of two different macros to define methods
    526     on Objective-C classes. <literal>define-objc-method</literal>
    527     accepts a two-element list containing a message selector name and
    528     a class name, and a body. <literal>objc:defmethod</literal>
    529     superficially resembles the normal
    530     CLOS <literal>defmethod</literal>, but creates methods on
    531     Objective-C classes with the same restrictions as those created
    532     by <literal>define-objc-method</literal>.</para>
     546      on Objective-C classes. <literal>define-objc-method</literal>
     547      accepts a two-element list containing a message selector name
     548      and a class name, and a body. <literal>objc:defmethod</literal>
     549      superficially resembles the normal
     550      CLOS <literal>defmethod</literal>, but creates methods on
     551      Objective-C classes with the same restrictions as those created
     552      by <literal>define-objc-method</literal>.</para>
    534554    <sect2>
    760780       </programlisting>
     782       <para>If the <literal>OBJC:DEFMETHOD</literal> creates a new
     783       method, then it displays a message to that effect. These
     784       messages may be helpful in catching errors in the names of
     785       method definitions. In addition, if
     786       a <literal>OBJC:DEFMETHOD</literal> form redefines a method in
     787       a way that changes its type signature, &CCL; signals a
     788       continuable error.</para>
    762789    </sect2>
    768795        how and when you can replace the definition of an Objective C
    769796        method.  Currently, if you break these rules, nothing will
    770         collapse, but the behaviour will be confusing; so
     797        collapse, but the behavior will be confusing; so
    771798        don't.</para>
    772799      <para>Objective C methods can be redefined at runtime, but
    783810  </sect1>
     812  <!-- ============================================================ -->
     813  <sect1 id="Loading-Objc-Frameworks">
     814    <title>Loading Frameworks</title>
     816    <para>On Mac OS X, a framework is a structured directory
     817      containing one or more shared libraries along with metadata such
     818      as C and Objective-C header files. In some cases, frameworks may
     819      also contain additional items such as executables.</para>
     821    <para>Loading a framework means opening the shared libraries and
     822      processing any declarations so that &CCL; can subsequently call
     823      its entry points and use its data structures. &CCL; provides the
     824      function <literal>OBJC:LOAD-FRAMEWORK</literal> for this
     825      purpose.</para>
     827    <programlisting>
     828(OBJC:LOAD-FRAMEWORK framework-name interface-dir)
     829    </programlisting>
     831    <para><literal>framework-name</literal> is a string that names the
     832    framework (for example, "Foundation", or "Cocoa"),
     833    and <literal>interface-dir</literal> is a keyword that names the
     834    set of interface databases associated with the named framework
     835    (for example, <literal>:foundation</literal>,
     836    or <literal>:cocoa</literal>).</para>
     838    <para>Assuming that interface databases for the named frameworks
     839    exist on the standard search
     840    path, <literal>OBJC:LOAD-FRAMEWORK</literal> finds and initializes
     841    the framework bundle by searching OS X's standard framework search
     842    paths. Loading the named framework may create new Objective-C
     843    classes and methods, add foreign type descriptions and entry
     844    points, and adjust &CCL;'s dispatch functions.</para>
     846    <para>If interface databases don't exist for a framework you want
     847    to use, you will need to create them. For more information about
     848    creating interface databases,
     849    see <link linkend="Creating-new-interface-directories">Creating
     850    new interface directories</link>.</para>
     851  </sect1>
     853  <!-- ============================================================ -->
    785854  <sect1 id="How-Objective-C-Names-are-Mapped-to-Lisp-Symbols">
    786855    <title>How Objective-C Names are Mapped to Lisp Symbols</title>
    787856    <para>There is a standard set of naming conventions for Cocoa
    788857      classes, messages, etc.  As long as they are followed, the
    789       bridge is fairly good at automaticallly translating between Objective-C
     858      bridge is fairly good at automatically translating between Objective-C
    790859      and Lisp names.</para>
    791860    <para>For example, "NSOpenGLView" becomes ns:ns-opengl-view;
    821890    <para>Alternatively, you can define a special translation rule
    822891      for your exception.  This is useful for an exceptional name that
    823       you need to use througout your code.  Some examples:</para>
     892      you need to use throughout your code.  Some examples:</para>
    824893    <programlisting>
    825894(ccl::define-classname-translation "WiErDclass" wierd-class)
Note: See TracChangeset for help on using the changeset viewer.