Adding Icons to Nodes

RAYZ's builtin nodes all have icons associated with them, to help the user identify them in the menu and on the worksheet. It is possible to provide such icons for plugin nodes as well. This section discusses how to do that.

Icon Image File Format

In the Node plugin examples is the source for the Pizza node, which allows the user to select a pizza and toppings and then email the order to her favorite restaurant. We want to associate an icon with this node, and have that icon show up in the node menu (and optionally on the node itself).

The icon for this node is shown here: This image is contained in the file Pizza.tiff, in the Nodes directory of the plugin examples.

Icon images must be 8-bit, 3 channel images in a format that RAYZ can read, eg .tiff, .sgi, .jpeg, etc. They can be any size, but RAYZ's own icons are 60 pixels wide and 45 pixels high, so that is the recommended size.

Having Separate Icon Image Files

There are two ways to associate an icon with a node plugin. The first relys on RAYZ's notion of Themes, which are collections of user interface preferences. In this method, the icon image must be present in the RAYZ Themes directory, which is normally found at
.rayz/2.0/Themes 

So the Pizza.tiff file should be copied into either

~/.rayz/2.0/Themes/Icons/Pizza.tiff
or
C:\.rayz\2.0\Themes\Icons\Pizza.tiff
Depending on whether the platform is Unix or Windows.

To direct the plugin to load and show that icon, add the following line to the Init() function in the node source:

cpiDefineIcon( "Nodes/Pizza", "Pizza.tiff",
                NULL, NULL, NULL, NULL, NULL, 255, 0, 255 );
This routine is defined as follows:
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 )
The baseName refers to a location in the Theme Search Path, which is a user preference. Since this is a node, this string begins with "Nodes/", and then follows the node name. In this case, that means that the baseName is "Nodes/Pizza", as shown in the example. This tells RAYZ to associate the coming filenames with the Node named Pizza.

The location of the icon image file defaults to the paths shown at the start of this section, namely

~/.rayz/2.0/Themes/Icons/Pizza.tiff
or
C:\.rayz\2.0\Themes\Icons\Pizza.tiff
depending on whether the platform is Unix or Windows. You could of course introduce another directory level, if you had multiple nodes, so that you were placing icon images at
~/.rayz/2.0/Themes/Icons/Pizza/normal.tiff
~/.rayz/2.0/Themes/Icons/Pizza/located.tiff
etc, and
~/.rayz/2.0/Themes/Icons/DayForNight/normal.tiff
~/.rayz/2.0/Themes/Icons/DayForNight/located.tiff
and so on for each node that you have.

The normalFile icon is the icon image in its default state. If any other icon is NULL, RAYZ will default to using the normalFile icon.

The transColor values are the RGB value of a color which is defined to be transparent. This allows areas within the icon to be transparent. Note that transparency is an on/off attribute - there is no notion of alpha or or partial transparency. By default in RAYZ, the transparent color is magenta (255 0 255).

Compiling Icons into Plugins

In most cases, it is preferable to compile the icon image into the plugin itself. This makes the plugin larger, but it means that only a single file has to be distributed and installed. There are two steps to accomplishing this.

First, you need to define the icon image as a binary array. There are many ways to do this, and in a future release of RAYZ we will provide a utility for creating these arrays. For this example, one has been supplied. It is found in the source example directory, in the file Pizza.h. This file is then included in the source file Pizza.C.

Second, pass the binary table to RAYZ. This is done with the call

void    cpiRegisterIconData( const char      *name,
                             CPI_Int32        sizeX,
                             CPI_Int32        sizeY,
                             const CPI_Uint8 *iconData,
                             CPI_Uint8        transColorRed,
                             CPI_Uint8        transColorGreen,
                             CPI_Uint8        transColorBlue );
The name field should be the name of the icon file you are replacing (defining) with this call; in this example, the file is called Pizza.tiff, so that is the name of the icon which is registered. Thus you can register a separate icon image for normal, located, etc, if you want to.
The size is the dimensions in pixels, normally 60 x 45
The iconData is the structure defined in the header file
The transColor should be the same color used in the cpiDefineIcon() call, which normally is magenta (255 0 255)

So in our Pizza example, the call looks like this:

cpiRegisterIconData( "Pizza.tiff", 60, 45, icon_image, 
                     255, 0, 255 );
Note that in order to make this work, you need both calls to get an icon to work. Thus the example contains both calls, eg
Init()
{
    ... define other gui widgets

    // set up the pizza icon
    cpiRegisterIconData( "Pizza.tiff", 60, 45, icon_image,
                         255, 0, 255 );

    // define the location of the pizza icon
    cpiDefineIcon( "Pizza", "Nodes/Pizza.tiff",
                   NULL, NULL, NULL, NULL, NULL, 255, 0, 255 );
}

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

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