cappuccino/Tools/nib2cib/nib2cib.1

.Dd April 3, 2011
.Os "Cappuccino"
.Dt NIB2CIB 1 "PRM"
.nh
.\"-----------------------------------------------------------------------------------------
.Sh NAME
.\"-----------------------------------------------------------------------------------------
.Nm nib2cib
.Nd convert Interface Builder files to Cappuccino cib files
.\"-----------------------------------------------------------------------------------------
.Sh SYNOPSIS
.\"-----------------------------------------------------------------------------------------
.Nm
--watch
.Op options
.Op Pa directory
.Nm
.Op options
.Op Pa input Op Pa output
.Nm
.Op --version | -h | --help
.\"-----------------------------------------------------------------------------------------
.Sh "DESCRIPTION"
.\"-----------------------------------------------------------------------------------------
.Nm
converts an Interface Builder file into a Cappuccino cib file that can be loaded
into a Cappuccino application.
.Pp
There are two main converting modes in which nib2cib can be used:
.Sy watch mode
and
.Sy single mode.
.\"-----------------------------------------------------------------------------------------
.Ss "Watch Mode"
.\"-----------------------------------------------------------------------------------------
The easiest way to use nib2cib is in
.Sy watch mode.
This is done by using the syntax:
.Pp
.D1 nib2cib --watch [options] Op Pa directory
.Pp
If
.Ar directory
is omitted, a "Resources" directory in the current working directory is watched,
and if no "Resources" directory exists, the current working directory is watched.
.Pp
If
.Ar directory
is passed, is not a path to a "Resources" directory, and there is a "Resources" directory
within
.Ar directory ,
then that "Resources" directory is watched. Otherwise
.Ar directory
is watched. This allows you to pass the path to your application directory instead
of its "Resources" directory.
.Pp
In watch mode,
.Nm
goes into an infinite loop and monitors the watched directory for changes to xib/nib
files. There are three types of changes
.Nm
will respond to:
.Bl -tag -hang
.It add, modify
When a new xib/nib file is detected or an existing xib/nib file is modified, it is converted into
a cib file with the same base name if there is no corresponding cib file with a later
modification time.
.It delete
When a xib/nib file is deleted, the corresponding cib file is deleted as well.
.El
.Pp
Ordinarily in watch mode
.Nm
will only display a log line for each file that is added, modified or deleted, and a confirmation
when the corresponding cib has been generated or deleted. You can use the
.Fl v
option in watch mode to display more detailed information when a cib is generated.
.\"-----------------------------------------------------------------------------------------
.Ss "Single Mode"
.\"-----------------------------------------------------------------------------------------
In
.Sy single mode,
you convert a single file xib/nib file into a cib. The only advantages of using single mode over
watch mode are:
.Bl -dash -width 0n
.It
You may want to view verbose output temporarily to debug the conversion, or use different
options for different source files.
.It
You can specify an output name that is not based on the input name.
.El
.Pp
Most of the time watch mode will be sufficient, but if you do need to use single mode,
.Nm
tries to make it as easy as possible. If you navigate to your application directory and invoke:
.Pp
.D1 nib2cib
.Pp
this will look for "MainMenu.xib" or "MainMenu.nib" in the current directory and then in a "Resources"
directory within the current directory, if such a directory exists. Since these are
the default names used in Cappuccino, this usage covers the default case with no extra work.
.Pp
If your xib/nib file is not named "MainMenu.xib" or "MainMenu.nib", or you want to run
.Nm
from a directory other than the application directory or its "Resources" directory,
you can specify an input path:
.Pp
.D1 nib2cib Pa path
.Pp
Note that
.Pa path
does not need the ".xib" or ".nib" extension, since that is assumed. If you were to invoke:
.Pp
.D1 nib2cib foo
.Pp
this would look for "foo.xib" and "foo.nib" in the current directory and in a "Resources" directory
within the current directory. The output of nib2cib in this case would be "foo.cib" in
the same directory as the source file.
.Pp
If you want
.Nm
to generate a cib file with a different base name or in a different directory than
the input file, you may also specify an output path:
.Pp
.D1 nib2cib Pa input Pa output
.Pp
As with input filenames, you do not need to add the ".cib" extension to the output path,
this is assumed.
.\"-----------------------------------------------------------------------------------------
.Ss "Themes"
.\"-----------------------------------------------------------------------------------------
To do its conversions accurately,
.Nm
needs to access the themes you use. If you are using the standard Aristo2 theme, there is
nothing extra to do.
.Pp
If you are using a custom default theme, usually you specify this using a
.Ar CPDefaultTheme
item in your application's Info.plist. In this case
.Nm
will read the theme name from the Info.plist. If you set the default theme programmatically
and not in the Info.plist, then you should use the
.Fl \-default-theme
option to specify the theme name.
.Pp
If you are loading additional themes in your code using:
.Pp
.D1 [[CPThemeBlend alloc] initWithContentsOfURL:]
.Pp
then you should inform
.Nm
about it by passing the theme names as
.Fl \-theme Ar name
options, one for each theme that you load.
.Pp
Themes are searched for in the Resources, $CAPP_BUILD/Debug and
$CAPP_BUILD/Release directories.
.Pp
If you have a list of auxiliary themes in your Info.plist using the
.Ar CPAuxiliaryThemes
item,
.Nm
will load them automatically, you do not have to do anything special.
.\"-----------------------------------------------------------------------------------------
.Ss "Framework Image Resources"
.\"-----------------------------------------------------------------------------------------
If you need to use image resources located in a framework -- for example in a button -- you have two choices:
.Bl -dash -width 0n
.It
Use the plain image name in Xcode. During conversion,
.Nm
will first search the app’s Resources directory for an image with the given name, then it will
search all of the Resources directories of the debug frameworks, followed by the release frameworks.
The first match wins, and if the image was found in a framework, the framework's bundle identifier
is recorded so the image can be loaded from the correct bundle at runtime.
.It
If you want to ensure you use an image from a specific framework, in Xcode use <image>@<framework>
for the image name, where <image> is the base image name
with no extension and <framework> is the framework name. For example, to use the image "cancel.png" 
in the framework "JQueryFileUpload", you would use this as the image name in Xcode:
.Pp
   cancel@JQueryFileUpload
.Pp
During conversion, nib2cib will check the named framework for the given image, and if it is found
the framework's bundle identifier is recorded so the image can be loaded from the correct bundle at runtime.
.El
.\"-----------------------------------------------------------------------------------------
.Ss "Userland NS Classes"
.\"-----------------------------------------------------------------------------------------
Let's say you are working on a subclass of CPTextField called FormField. Obviously you will
want to use FormFields in cibs. You would also like to have some reasonable defaults established
for the view in Xcode, and perhaps override or ignore some CPTextField settings that do not apply to FormField.
.Pp
.Nm
allows you to dynamically define NS classes and use them in Interface Builder. Here's how:
.Bl -enum
.It
Indicate which classes will be used in Interface Builder by setting an
.Ar NSClasses
item in Info.plist:

 <key>NSClasses</key>
 <array>
     <string>BorderView</string>
 </array>
.It
For each class listed in
.Ar NSClasses ,
a corresponding NS_<class>.j file must be
created. This file is structured exactly like a Cappuccino NS class, with one exception:

 @implementation BorderView (NSCoding)

 - (id)NS_initWithCoder:(CPCoder)aCoder
 {
     self = [super NS_initWithCoder:aCoder];

     if (self)
     {
         // Do default initialization here
     }

     return self;
 }

 @end

 @implementation NS_BorderView : BorderView

 + (Class)classForKeyedArchiver
 {
     return [BorderView class];
 }

 - (id)initWithCoder:(CPCoder)aCoder
 {
     return [self NS_initWithCoder:aCoder];
 }

 @end

The only difference between this file and a Cappuccino NS file is that
.Sy classForKeyedArchiver
is a class method instead of an instance method.
.It
If necessary, the main class'
.Sy encodeWithCoder
can be enhanced to do extra work to support
.Sy nib2cib.
.Pp
By making your classes key-value coding compliant, you can use User Defined
Runtime Attributes in Interface Builder to configure your custom views without
any code.
.El
.\"-----------------------------------------------------------------------------------------
.Sh "OPTIONS"
.\"-----------------------------------------------------------------------------------------
The following options are available in watch mode or single mode:
.Bl -tag -width 4n
.It Fl v, \-verbose
Displays more information about the internal workings of nib2cib. This can be set multiple
times to increase the amount of information displayed. If passed once, general information
is displayed. If passed more than once, detailed information about individual view conversions
is displayed.
.It Fl R Pa path
NOTE: This option is deprecated and has no effect.
.It Fl \-default-theme Ar name
Specifies the name of the default theme used by your application. This is only necessary
if you are not using Aristo2 and you have not specified the default theme in your application's
Info.plist. For more information see
.Sy Themes
above.
.It Fl t, \-theme Ar name
Specifies the name of an additional theme to load. May be used multiple times. For more
information, see
.Sy Themes
above.
.It Fl \-config Pa path
Specifies the path to an Info.plist file from which to read configuration information about
your application, such as the system font and default theme. Ordinarily you do not need to
use this option, as
.Nm
uses the Info.plist in the application directory, which is inferred from
the input file.
.It Fl F
Specify the name or path of a framework to load before converting. This is only useful if:
.Bl -dash -width 0n -hang
.It
Your IB files use classes from the framework.
.It
Those classes need to serialize/deserialize more data than their superclasses.
.It
Those classes implement encodeWithCoder: and initWithCoder:.
.El
.Pp
This option may be used multiple times to load multiple frameworks. If the argument
contains a "/" character, it is considered to be a relative or absolute path and
the framework is searched for at that location. Otherwise it is considered a framework
name and is searched for in the following directories:
.Bl -ohang -offset 4n
.It $CAPP_BUILD/Debug
.It $CAPP_BUILD/Release
.It <App>/Frameworks/Debug
.It <App>/Frameworks
.It <narwhal>/packages/cappuccino/Frameworks/Debug
.It <narwhal>/packages/cappuccino/Frameworks
.El
.It Fl \-quiet
Tells
.Nm
to output nothing. This is useful if you are using
.Nm
in a shell script and are only interested in the return value. Note that this
option overrides the
.Fl v
option.
.It Fl \-no-stored-options
Tells
.Nm
not to read stored options. See
.Sy Stored Options
below for more information.
.It Fl \-no-colors
Tells
.Nm
to strip any color information from the output. This is useful if you need to pipe the output.
.It Fl \-version
Prints the current version of
.Nm
and immediately exits.
.Nm
in a shell script and are only interested in the return value.
.It Fl h, \-help
Displays
.Nm
usage and options.
.El
.\"-----------------------------------------------------------------------------------------
.Ss "Stored Options"
.\"-----------------------------------------------------------------------------------------
To make it easier to use nib2cib in an automated way, you can store command line options
that will apply to converted xibs/nibs. To store command line options, you enter the
options on a single line into a text file. For example, if you always want to set
"MyTheme" as the default theme, you would create a text file with this line:
.Pp
.D1 --default-theme MyTheme
.Pp
If an option takes a parameter and the parameter contains spaces, it must be enclosed in
single or double quotes. You may store options in the following three places, in increasing
order of precedence:
.Bl -ohang -offset 4n
.It Em ~/.nib2cibconfig
nib2cib options that apply to all nibs converted under your user account.
.It Em <app>/nib2cib.conf
nib2cib options that apply to all nibs in <app>/Resources.
.It Em <app>/Resources/<xib-or-nib-basename>.conf
nib2cib options that apply to a specific xib or nib. For example, if the xib
is called MainMenu.xib, the stored options file would be MainMenu.conf.
.El
.Pp
Each of these files is read in the order listed above, and if it exists, its options
are merged with the previous file's options. Options in later files (more specific)
override options in earlier files (more generic). After all of the stored options
are merged, the command line options are merged in. Thus command line options always
override stored options.
.Pp
Using stored options is especially useful if your xibs/nibs use custom themes or
frameworks. By using stored options, you can avoid remembering (or forgetting!) to
specify the theme or framework every time you invoke
.Nm .
.Pp
To prevent
.Nm
from reading stored options, and thus only use command line options, use the
.Fl \-no-stored-options
option on the command line.
.\"-----------------------------------------------------------------------------------------
.Sh "RETURN VALUES"
.\"-----------------------------------------------------------------------------------------
.Nm
returns 0 for a successful conversion and >0 if an error occurred.