[ Previous | Next | Contents | Glossary | Home | Search ]
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.)

  1. $HOME/Locale/app-custom/ Class
  2. $HOME/app-custom/Class
  3. /usr/lib/X11/Locale/app-custom/ Class
  4. /usr/lib/X11/app-custom/Class
  5. $HOME/Locale /app-custom/DEFAULT
  6. $HOME/app-custom/DEFAULT
  7. /usr/lib/X11/Locale /app-custom/DEFAULT
  8. /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 $MWM**clientDecoration appears in the app-custom file for XClock and the dtwm window manager is currently running, the customizing tool expands this syntax to:

Dtwm*XClock*clientDecoration

If the mwm window manager is currently running, this syntax expands to:

mwm*XClock*clientDecoration

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:

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:

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:

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


[ Previous | Next | Contents | Glossary | Home | Search ]