Defining Custom Icons

There are two ways to define an icon for use in a RAYZ plugin. The first, and slightly simpler, method, is to just refer to an image file that resides on disk. The second is to compile in the image with the plugin.

Method One - Refering to a File

The advantage of using an image file is that the code (and the work involved) is slightly simpler. The disadvantage is that distributing your plugin to users involves also distributing the image file. Also, those image files have to be installed in a specific place, which increases the chances that your user will never see the icon you so lovingly crafted. We do not recommend that you implement icons with this method. However, this section is necessary because there is overlap with the second, recommended, method.

To use an icon in this way, you use the setup call

void  cpiDefineIcon( const char  *baseName,
                     const char  *normalFile,
                     const char  *locatedFile,
                     const char  *disabledFile,
                     const char  *selectedFile,
                     const char  *selectedLocatedFile,
                     const char  *selectedDisabledFile,
                     CPI_Uint8    transColorRed,
                     CPI_Uint8    transColorGreen,
                     CPI_Uint8    transColorBlue );
This allows a file to be defined for each of the icon's possible states, namely
Normal
Located (mouse currently over the icon)
Selected
Disabled
Selected Disabled
Selected Located

You must supply an entry for the "Normal" state, but NULL may be given for any other icon states for which there is no image. In those cases, the "Normal" state icon will be used.

The baseName is path which is appended to the current Theme path, to create a path name to the icons. The current Theme path can be seen (and changed) in the File Paths section of the Preferences dialog - the default Theme path is $HOME/.rayz/2.2/Themes.

For example, given the following call:

   cpiDefineIcon( "Nodes/Pizza/", "Pizza.tiff",
                   NULL, NULL, NULL, NULL, NULL, 255, 0, 255 );
RAYZ would look for the file called Pizza.tiff in the directory
$HOME/.rayz/2.2/Themes/Icons/Nodes/Pizza/

The three entries for transColorRed, Green and Blue define the color which is used as a transparency value for the icon. RAYZ icons are not alpha-blended with the background, they are simply painted onto the interface. So the color given here is the color which will be transparent. There is no semi-transparency. This means that anti-aliased icons are more difficult to do in RAYZ, unless the entire icon is color-matched to the interface. You can do that, but since the user can change all the interface colors, that might not be a good idea.

The default transparency color in RAYZ is magenta, which is (255, 0, 255)

Method Two - Compiling in the Icon

The advantage to compiling in the icon data is that your plugin is now completely self-contained. By distributing a single file, your user will see exactly what she is supposed to see, with no messy secondary installation. The disadvantage is that setting up the plugin takes an extra step or two. This is the preferred method of incorporating icons into nodes, and this is the method we use in all our examples.

To compile in the icon image, you still need to define the icon as given in Method One, and then there is the added step of registering the icon data. This looks like this:

   cpiRegisterIconData( "Pizza.tiff", Pizza_SIZEX, Pizza_SIZEY, 
                         Pizza_data, 255, 0, 255 );
This must be done for each icon that was defined in the preceding cpiDefineIcon() call. The definition of cpiRegisterIconData is:
void  cpiRegisterIconData( const char        *name,
                           CPI_Int32          sizeX,
                           CPI_Int32          sizeY,
                           const CPI_Uint8   *iconData,
                           CPI_Uint8          transColorRed,
                           CPI_Uint8          transColorGreen,
                           CPI_Uint8          transColorBlue );
where "name" must match the name of the filename given in cpiDefineIcon(). The size is the size of the image in pixels, and the iconData array is an array of pixel data of the appropriate size. The RAYZ developer's kit comes with a utility program, rayz_iconreader, which can read in an icon image file and write out a header file for inclusion in the plugin. This is explained fully in the next section.

The transColorRed, Green and Blue values are the same as for Method One, and in RAYZ the default transparency color is magenta, or (255, 0, 255).

rayz_iconreader

rayz_iconreader is a utility program, supplied with the developer's kit, which will read in a 3 channel tiff file (only) and write out a header file which can be included in your plugin. The syntax is:
rayz_iconreader <inputfile> <iconfile> <outputfile>
where:
<inputfile>  is the full path to the icon file to read
<iconfile>   is a base name for use in constructing #defines, etc
<outputfile> is the full path to the resulting header file
For example, to create the file Pizza.h, which is supplied with the examples, the command line use was:
% rayz_iconreader Pizza.tiff Pizza Pizza.h
Important Note: The resulting array declaration is appended to the contents of the output file, if any. This allows a use such as:
% rayz_iconreader icon1.tiff Icon1 icons.h
% rayz_iconreader icon2.tiff Icon2 icons.h
% rayz_iconreader icon3.tiff Icon3 icons.h
In which all the icons are defined in a single header file.

Part of the output is a set of #define statements listing the size of the icon, which may be used in the Register() calls. For example, the file Pizza.h (supplied as an example), lists

#define Pizza_SIZEX 60
#define Pizza_SIZEY 45
These constants are then used in the call to cpiRegisterIconData().

Important note: Icons must be 3 channel, tiff format files. Alpha is not currently used in RAYZ icon images. To create an icon image with transparent areas, use the transparency color (magenta, by default) instead of alpha.


[Previous Page] [Next Page]
[Table of Contents] [Index]

Copyright © 2002 Silicon Grail Inc.
736 Seward Street, Hollywood, CA 90038