Understanding the app-custom Files

AIX Version 4.3 AIXwindows Programming Guide

Understanding the app-custom Files

The resources that are important to customize should be listed in an app-custom file. The app-custom file contains all of the necessary information to generate a customizing tool interface that is unique for each application. For more information, see the following:

Location of the app-custom Files

The customizing tool uses the application class to name app-custom files. Applications have two names: their application name, which is usually the name used to start the application, and their application class, which is permanently coded into the application.

By default, the customizing tool searches for the app-custom file in the following places, in the order listed. The first file found is used. ($HOME is the user's home directory. Locale is the locale in which custom is running. Class is the class of the application to be customized.)

$HOME/Locale/app-custom/ Class
$HOME/app-custom/Class
/usr/lib/X11/Locale/app-custom/ Class
/usr/lib/X11/app-custom/Class
$HOME/Locale /app-custom/DEFAULT
$HOME/app-custom/DEFAULT
/usr/lib/X11/Locale /app-custom/DEFAULT
/usr/lib/X11/app-custom/DEFAULT

The place where the customizing tool looks for the app-custom file can be changed by specifying the Custom.appCustomPath resource.

Format of the app-custom Files

Each line of the resource panel description file has the following format:

Group   Type    Resource  
  Description        [Values];

Following is an explanation of these parameters:

Group	Groups are used to organize similar resources. For example, scrollbar color, scrollbar on/off, and number of scrolled lines to save are all different types of resources, but they are related. The Group parameter can be any character string in any language you choose. If more than one word is used for the group or if it contains any double-byte character strings, it must be enclosed in quotation marks. You are limited to a maximum of 20 groups. The groups are listed on the Resource Category button on the Customizing Tool main window.
Type	The Type parameter specifies whether the possible values of a resource should be limited to colors, fonts, or other types. The customizing tool provides graphical tools that assist in setting a valid value for the resource type. The type of a resource must be one of the predefined customizing tool types.
Resource	This is the actual resource string (for example, background). The complete resource string must be listed exactly as it would be in a resource database; it cannot* be prefaced by the application name or class and it must begin with an * (asterisk) or a . (period). This is required because the customizing tool attaches the application class to the beginning of each resource string prior to writing the string to the resource database. The custom command also accepts the following syntax, which is intended for the Window Manager client-specific resources: `$MWM%%Resource` where each `%` is either an `` (asterisk) or a `.`(period). The customizing tool attempts to determine whether a window manager that is compatible with the mwm window manager is currently running. If so, it substitutes the name or class of the window manager for $MWM* and inserts the class name of the application between the `*` (asterisks), `..` (periods), `.` (asterisk, period), or `.` (period, asterisk), represented by `%%` above. If the customizing tool does not detect that a window manager known to be compatible with mwm is running, then all resource description statements containing $MWM* are ignored. For example, if `$MWMclientDecoration` appears in the app-custom file for XClock and the dtwm** window manager is currently running, the customizing tool expands this syntax to: `DtwmXClockclientDecoration` If the mwm window manager is currently running, this syntax expands to: `mwmXClockclientDecoration` If no window manager compatible with mwm is running, then this entire statement (from the Group name to the `;` (semicolon)) is ignored, and this resource is not shown on the user interface.
Description	This is a descriptive explanation of each resource that you can customize. This string is chosen to represent the resource on the panel. It can be any descriptive text but should be brief because space is limited on the custom interface. Although the resource string must be in English, the description can be in any language, which implies that language-specific app-custom files are localized files that are encoded in the current native locale at run time. It is also necessary to enclose any double-byte character string in double quotes. The `\n` characters are recognized in description strings as a new-line character and can be used to break the description into multiple lines.
Values	Some data types require additional data from which to create the interface.

The following provides a more detailed description of individual data type app-custom file syntax:

The color, font, cursor, file name, number, and string data types all use the following syntax:
```
Group   Type    Resource    Description;
```
Following is an example of a color resource app-custom file syntax:
```
"Menu Bar" Color *menubar*background "menu bar background";
```
A picture data type can be specified in the app-custom file using the following syntax:
```
Group   Picture Resource     Description PictureType;
```
Following is an example of the app-custom file syntax:
```
Icon    Picture *appIcon     "application icon"  bitmap;
```
The PictureType value can be one of three types: bitmap, pixmap, or all. If bitmap is set, only bitmaps can be browsed; pixmap is similar. However, if all is set, both bitmaps and pixmaps are browsed.
Bitmaps are black and white images where file names end with .bm or .xbm; pixmaps are multicolored images where file extensions are .pm or .px.
The selectmany data type allows many values to be selected from a list of choices. It is limited to 20 items. A selectmany data type can be specified in the app-custom file using the following syntax:
```
Group   SelectMany       Resource        Description
        "Separator"      Item1 [= String] Item2 [= String]... ;
```
The Separator parameter specifies one or more characters that are used to separate each of the items the user selected when the resource definition is written to the .Xdefaults file. Following is an example of the app-custom file syntax:
```
Foods   SelectMany *iceCream  "Ice Cream Choices"
        " " vanilla chocolate strawberry ;
```
If you want to see more descriptive names for the choices, you can attach a string to each value with an = (equal sign). This is especially useful for translating values into other languages.
The following is an example:
```
Foods   SelectMany  *iceCream   "Ice Cream Choices"
        ", "
        vanilla = "Vanilla Flavor"
        chocolate = Fudge
        strawberry ;
```
The selectone type is a generic data type for choosing one value from among a list of choices. It is limited to 20 items. A selectone data type can be specified in the app-custom file using the following syntax:
```
Group   SelectOne   Resource     Description
        Item1 [= String] Item2 [= String]... ;
```
Following is an example of the app-custom file syntax:
```
Foods   SelectOne   iceCream    "Ice Cream Choices"
                          vanilla chocolate strawberry ;
```
The selectone data type is represented by an Option menu button to switch between the values. The first option is always <default>. This is consistent with the other data types because no values are written to the resource database unless you have specifically chosen one.
You can select an item by pressing the Option button, dragging the mouse over the list, and releasing the mouse button on your choice.

If you want to see more descriptive names for the choices, you can attach a string to each value with an = (equal sign). This is especially useful for translating values to other languages.

The following is an example:
```
Foods   SelectOne   *iceCream  "Ice Cream Choices"
        vanilla = "Vanilla Flavor"
        chocolate = Fudge
        strawberry ;
```
Comments must begin with an ! (exclamation point) as the first character on the line.

A brief example of an app-custom file follows:

! XClock app-custom file
Size      Number      *width        "width of clock";
Size      Number      *height       "height of clock";
Color     Color       *foreground   "foreground";
Color     Color       *hands        "analog hands";
Color     Color       *highlight    "highlight analog hands";
Color     SelectOne   *reverseVideo "reverse video"
          true false;
Font      Font        *font         "digital clock font";
Behavior  Number      *update       "interval of updates/n (sec)";
Behavior  SelectOne   *analog       "type of clock"
          true = analog false = digital;
Behavior  SelectOne   *chime        "chime every half hour"
          true false;
Behavior  Number      *padding      "internal padding (pixels)";

Guidelines for Writing app-custom Files

The following are guidelines for writing app-custom files:

Creating app-custom Files

If you already have resources in your .Xdefaults file for an application, you can load your resource values onto the customizing tool interface, remove the old resources from your .Xdefaults file, and use the customizing tool to customize the application in the future.

If the app-custom file does not contain all the resource strings you need, you can create a subdirectory named app-custom in your $HOME directory, copy the app-custom file from the /usr/lib/X11/app-custom directory into it, and add the needed resource strings to this file. To create a new app-custom file, copy the DEFAULT app-custom file and use it as a template.

If you want to create a new app-custom file, you should add the app-custom file and the application name to the Custom.listOfApps resource. This resource is used to display the application names on the starting dialog. The application name and corresponding app-custom file must be listed in pairs with the following syntax:

Application:app-custom,

For example:

Custom.listOfApps: 
xclock:XClock,custom:Custom,msmit:Msmit

You can specify a maximum of 100 applications.

Organizing Resource Categories

Group resources into the following recommended categories:

Colors
Fonts
Size and position
Icon
Graphics
Behaviors

If the application resources do not fall into one of these categories, you can create additional categories. The new categories can be added after the other categories. You can create a new category if any of the standard categories contain too many resources (more than 15 or 20). The new category needs to be added after the category whose limit was exceeded.

Choosing Resources

The following are some general guidelines for selecting which resources to list in app-custom files:

The resources in each category should be those resources the application writer decides are commonly used or those that may be important to customize.
Do not list the same resource more than once in a given app-custom file. Doing so can lead to unexpected results.
Although colors and fonts can be set on each object or groups of objects, try to keep it simple. For example, *background sets the background color of the application to one color.
You should append an * (asterisk) to the name of window manager client resources. This convention tells the user that the window manager has to be restarted for changes to these resources to take effect. For example,
```
   $MWM**clientDecoration    "client decoration *"
```
Resource strings should not be prefaced with the application name or class because the customizing tool prepends the class name to the resource string when saving to the resource file.
The descriptions of the resource should be no more than 20 to 30 characters long. If longer descriptions are needed, the \n (new-line) character can be used to break the description into multiple lines.
The maximum number of bytes in any quoted string is 500.

Once you create your app-custom file, you can check the syntax by running the customizing tool.

Related Information

Using the AIXwindows Customizing Tool Overview

Using the Customizing Tool Main Window

Using the Browsers

How to Start the Customizing Tool

The xset command