.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 @ for the image name, where is the base image name with no extension and 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: NSClasses BorderView .It For each class listed in .Ar NSClasses , a corresponding NS_.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 /Frameworks/Debug .It /Frameworks .It /packages/cappuccino/Frameworks/Debug .It /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 /nib2cib.conf nib2cib options that apply to all nibs in /Resources. .It Em /Resources/.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.