Catalog File

The Catalog file is a textual description of how the Builder Xcessory Palette should appear. The Palette shows multiple groups of items. For example, all Motif Container widget classes are shown together.1

Contents of catalog file

The Catalog file contains information on the name given to the Catalog, including the following information:

  • List of groups
  • Name that should be shown with each group
  • Interface items that initially appear within the group

If you use the Builder Xcessory Object Packager to create a catalog file, you will see how to locate items by direct manipulation within groups and how to set their attributes. You may modify the catalog file later, or create the file manually.

Catalog File Format

Catalog files use the following format:

<catalog attribute>;
<catalog attribute>;
<...>;
Group <groupname> [ : <condition> ] {
<group attribute>;
<group attribute>;
<...>;
Items {
<itemname> [ : <condition> ] {
<item attribute>;
<item attribute>;
<...>;
};
! ... additional groups or items ...
};
! ... additional groups or items ...
};
!... additional groups ...

The file begins with attributes that apply to the catalog as a whole. A list of Palette groups and the contents of those groups follows the catalog attributes.

Group specifications

A Group specification lists all of the items and other groups that are to be displayed as part a Palette group of the given name. Each group can include an optional condition that is used by Builder Xcessory to determine whether to show a group and its contents.

Item specifications

Groups can contain Items and Group specifications. The Items section lists the actual Palette items that correspond to an object class in a WML file. Similar to a Group specification, items can include an optional condition that is used by Builder Xcessory to determine whether to show the item.

We'll use the first part of the file for the Motif widgets, provided by Builder Xcessory, as an example:

!
! Default Motif Widget Catalog
!
DocName = "Motif Widgets";
Group motif_containers : Language != "JAVA" {
DocName = "Motif Containers";
DefaultState = Open;
Items {
xm_main_window {
 Class = "XmMainWindow";
 DocName = "XmMainWindow";
 PixmapFile = "MainW";
 CollectionFile = "MainW";
 Exported;
};
xm_scrolled_window {
Class = "XmScrolledwindow";
DocName = "XmScrolledwindow";
PixmapFile = "ScrolledW";
CollectionFile = "ScrolledW";
Exported;
};
xm_paned_window {
Class = "XmPanedWindow";
DocName = "XmPanedWindow";
PixmapFile = "PanedW";
CollectionFile = "PanedW";
Exported;
};
! other items not shown
};
};

Item Attributes

You can use the following attributes in an item specification:

Class

Syntax

Class = "WMLClassName";

Description

Specifies the object class as named in a WML file. This attribute is required for every item.

CollectionFile

Syntax

CollectionFile = "FileBaseName";

Description

Specifies the collection file to use when creating an instance of this object. Builder Xcessory appends ".col" to the given FileBaseName and searches:

${HOME}/.builderXcessory/collections

followed by

{BX}/xcessory/collections

when looking for the file.

The collection file is a simple UIL file that specifies resources to set on each instance of the object class that Builder Xcessory creates. The Object Packager generates a collection file for every object class that you add.

DocName

Syntax

DocName = "String";

Description

Specifies the string to display in the label that the Palette pops up over the item when the Palette is in Pixmaps Only view.

Exported

Syntax

Exported;

Description

Currently unused by Builder Xcessory. Exported indicates visibility to other users in the future.

PixmapFile

Syntax

PixmapFile = "FileBaseName";

Description

Specifies the pixmap file basename to use as the icon for the object on the Palette. Pixmap files have the .pix extension and can be located in either ${HOME}/.builderXcessory/pixmaps or {BX}/xcessory/pixmaps. Builder Xcessory uses a default pixmap for any items that do not specify a PixmapFile attribute or for which the PixmapFile cannot be found.

Pixmap files are XPM Version 3 format files. To be consistent with the other pixmaps on the Palette, icons should be 32x32 pixels and use no more than 8 colors. All of the pixmaps provided with Builder Xcessory use no more than 7 common colors and a separate color as to act as a common group background. You can use {BX}/xcessory/pixmaps/BXTemplate.pix as a starting point for your own icons.

Groups Attributes

Groups specifications can use the following attributes.

DefaultState

Syntax

DefaultState = Open | Closed;

Description

Specifies whether the group should be fully displayed (Open) or displayed only as its name or DocName (Closed).

DocName

Syntax

DocName = "String";

Description

Specifies the string to display in the Palette to identify the group. When the Palette uses the Outline View, this string is displayed next to the folder button. In the Tabbed View, the string is displayed on the tab corresponding to this group.

Catalog Attributes

The following attributes apply to catalog files:

DocName

Syntax

DocName = "String";

Description

Specifies the name to use for the catalog as whole. This string is displayed in the Palette window's title bar if the catalog is loaded into an empty Palette.

Include

Syntax

Include "CatalogFileName";

Description

Specifies another catalog file that should be included whenever this catalog file is loaded. The CatalogFileName can be either a fully qualified pathname (such as /usr/local/ui/extra.cat) or simply the name of the catalog (such as extra.cat). In the former case, Builder Xcessory simply loads the specified file. In the latter case, Builder Xcessory looks in both ${HOME}/.builderXcessory/package and {BX}/xcessory/package for a file of the given name.

Conditions

Both the item and the group can optionally name conditions under which they should appear on the Palette. Conditions consist of one or more tests combined using logical AND (&&) and inclusive OR (||) operators. You can specify groupings and precedence using parentheses. If no groupings are specified, tests are performed from left to right.

Test types

The valid tests are of two types:

  • Unary tests for the truth of a state
  • Binary tests of two values

Unary tests

Unary tests are specified using SystemAttribute(<tag>). If the attribute to which the <tag> refers is set as true, SystemAttribute resolves as true. You can negate the test using the '!' character.

Valid System Attribute tags

The following table lists and defines valid SystemAttribute tags:

 
Tag  Definition 
DXm  True if user specified -dec, or loadDEC resource is True. 
EPak  True if user specified -ics, or loadICS resource is True. 
IrisGL  True if user specified +openGL, or useOpenGL resource is False. 
OpenGL  True if user specified -openGL, or useOpenGL resource is True. 
 

Binary tests

Binary tests compare a tag attribute to a value. You can make comparisons using the following operators:

  • == for equality
  • != for inequality
  • < for less than
  • > for greater than
  • >= for greater than or equal
  • <= for less than or equal

    Note: You can only make the greater than/less than comparisons on numeric attributes.

Binary valid tags

The following table lists valid tags in comparisons:

 
Tag  Definition  Operators 
DatabaseName Test the value of the databaseName resource.  ==, != 
Env(var)  Test the value of the shell environment variable named "var".  ==, != 
Language  Test the value of the user's selected code generation language.  ==, != 
Platform  Test the name of the operating system on which BX is running. This is the name returned by the uname() system call.  ==, != 
Version  Test the version number of the operating system on which BX is running. This will be the version returned by uname().  ==, !=, <, >,>=, <= 
 

 

Documentation: