<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Mac OS X JarBundler ANT Task - DocumentType Nested Task</title>
  <meta http-equiv="Content-type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Language" content="en-us" />
  <meta name="ROBOTS" content="ALL" />
  <link href="styles.css" rel="stylesheet" media="all" type="text/css" />
</head>

<body>

<h2>JarBundler - Associating Files with your Application</h2>


<p>The nested <tt>&lt;documenttype&gt;</tt> task adds the appropriate elements to the <tt>Info.plist</tt>
file to associate a set of document file types with the application.  This association  means
that this application:

<ul>
  <li>will be included in the documents control-click "Open with.." list
  <li>will be selected if this document is dragged over it
  <li>can be selected as the default application for opening this document type
</ul>

<p>It is important to note that these association are done by the operation system, your
application must supply to proper code to handle the open document requires.

<p> Also see Apple Developer Documentation on the
<a href="http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/PListKeys.html#//apple_ref/doc/uid/20001431-101685">CFBundleDocumentTypes</a>
key.

<p><strong>NB: </strong> You must use at least one of the attributes "<tt>extensions</tt>",
<tt>mimetypes</tt> or "<tt>ostypes</tt>".  Any combination of these three may, of course, be used.


<h3><tt>DocumentType</tt> Task Attributes</h3>
<div align="center">
<table border="1" cellpadding="4" cellspacing="0" width="90%" style="font-size: 10pt;">

  <tr>
    <th>Attribute</th>
    <th>Description</th>
  </tr>

  <tr>
    <td class="attribute">name</td>
    <td class="description">
    An application's unique name for this document type.  For example, "<tt>Text Document</tt>" or
    "<tt>Raw Data Document</tt>"
    
    <div><strong>NB: </strong>Required attribute</div>
    </td>
  </tr>

  <tr>
    <td class="attribute">extensions</td>
    <td class="description">
    A comma or space delimited string of filename extensions.
    Do not specify the leading period. To open documents with 
    any extension, specify an extension with a single asterisk "<tt>*</tt>".    </td>
  </tr>

  <tr>
    <td class="attribute">ostypes</td>
    <td class="description">
     A comma or space delimited string of Mac OS types. Each value contains a four-letter type.
     To open documents of any type, 
     include four asterisk characters "<tt>****</tt>" as the type code. These codes are equivalent 
     to the legacy type codes used by Mac OS 9.  Currently, OS Types with leading or trailing
     spaces or commas cannot be processed.
    </td>
  </tr>

  <tr>
    <td class="attribute">mimetypes</td>
    <td class="description">
     A comma or space delimited string of mime-types.
    </td>
  </tr>

  <tr>
    <td class="attribute">UTI</td>
    <td class="description">
     A comma or space delimited string of Uniform Type Identifier (UTI) strings for the document. 
     UTIs are strings that uniquely identify abstract types. They can be used to
     describe a file format or data type but can also be used to describe type
     information for other sorts of entities, such as directories, volumes, or
     packages. For more information on UTIs, see the header file UTType.h,
     available as part of LaunchServices.framework in Mac OS X v10.3 and later.
Also see the Apple Developer Connection document 
    <a href="http://developer.apple.com/macosx/uniformtypeidentifiers.html">
    "Simplifying Data Handling with Uniform type Identifiers"</a>.      

    </td>
  </tr>





  <tr>
    <td class="attribute">iconfile</td>
    <td class="description">
     Specifies the name of an icon file used to associate with this document type.  This icon
     file is copied into the application bundle.  These icons will be used for the document
     look if this application is associated as the default application for this document type
     use the Finder "Get info" command with the document.
  </td>
  </tr>

  <tr>
    <td class="attribute">role</td>
    <td class="description">
    This key specifies the application's role with respect to the type. The value can be
    <tt>Editor</tt>, <tt>Viewer</tt>, <tt>Shell</tt>, or <tt>None</tt>. See 
    <a href="http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigApplications.html#//apple_ref/doc/uid/20002094-98566">
    "Document Configuration"</a>
    for descriptions of these values. 
    
    <div><strong>NB: </strong>Required attribute</div>
    </td>
  </tr>

  <tr>
    <td class="attribute">bundle</td>
    <td class="description">
    Used with extention and iconfile attributes to specify to Finder that a directory tree be 
    treated and displayed as a single document. See  
    <a href="http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/PListKeys.html">
    "Property List Key Reference"</a>,
    look for the document type key <tt>LSTypeIsPackage</tt>. 
    
    <div><strong>NB: </strong>Boolean attribute, takes "true" or "false", default is "false"</div>
    </td>
  </tr>





</table>
</div>




<!--Example ================================================================================-->

<h3>Example</h3>



<p>The following example shows four document types being associated with a JarBundler built 
Mac OS X application.  The first document type associates HTML files using the file extensions
<tt>html</tt> and <tt>htm</tt>.  The application also provides a custom icon file which can be
used by Finder to render files with these two extensions, if this application is chosen as the
default application.

<p>The second document type creates an association with files with the extension
<tt>rtf</tt>. In this case these files will be rendered by the Finder using a system default
icon or an icon set from another application. The application is also telling the Finder that
<tt>rtf</tt> files can be viewed but not edited.

<p>The third document type associates a <tt>mime-type</tt> for JPEG and PNG images. Again, the
application is declaring that it can only view files of this <tt>mime-type</tt>.

<p>The last document type is a bit interesting using the <tt>bundle</tt> attribute to
designate a directory, which has an extension, as a document.  The application has an
icon set which will be used by the Finder to render this directory.  The directory will 
not be seen from the Finder as a folder and can be copied and renamed as a single unit. This
structure can be very useful or creating complex associations of files which should be treated
as a unit.  The content of the document bundle can be viewed using a control-click and
choosing "Show Package Contents...".

<p>A document bundle has proven very useful in my own development work bring UNIX applications
onto to Mac OS X platform where the application would require several input file and create a
myriad of small output files.


<pre style="padding-left:2em; margin-bottom:0em;">


  &lt;jarbundler dir="release"...&gt; 
                
      &lt;documenttype name="Hello World HTML document"
                    extensions="html htm" 
                    iconFile="icons/html.icns"
                    role="Editor"/&gt;
                     
      &lt;documenttype name="Hello World RTF document"
                    extensions="rtf" 
                    role="Viewer"/&gt;

      &lt;documenttype name="Hello World images"
                    mimetypes="image/jpeg image/png" 
                    role="Viewer"/&gt;

      &lt;documenttype name="Hello Project document"
                    extensions="hello"
                    iconFile="icons/Hello Document.icns"
                    bundle="true"
                    role="Editor"/&gt;
                    
  &lt;/jarbundler&gt;

</pre>


</body>
</html>