|C H A P T E R 25|
There are several ways to customize X-Designer, using either the resource file or xdconfig. This section explains the main features that can be customized via the resource file. These features are:
For further information on X-Designer resources, see Appendix E. For information on using xdconfig, see Chapter 23.
Another area of X-Designer which can be configured using resources is the dynamic display window. This window has its own application class name and, therefore, its own resource file. Details are provided in Dynamic Display Window.
This section describes the application resources and environment variables needed to configure the editing mechanism. See Appendix E for details on using X-Designer's application resources. This first resource controls whether or not you wish the callback editing mechanism to be present:
This resource controls whether callback editing is enabled; if it is set to false then the buttons relating to this feature do not appear.
If you wish to use callback and prelude editing, you will need to specify which editor to use.
This resource specifies the location of the shell wrapper script which starts up the editor. By default it is set to:
xd_edit is a text file containing a shell script which provides the startup command applicable to different editors. If the editor you wish to use is not listed in this file, the default is to use the behavior specified for the editor "vi". When an editor is invoked, an "xterm" is started and X-Designer tries to move to the appropriate line in the stubs or primary source file (according to whether you are editing callbacks or preludes respectively). This is not applicable to all editors. Motif-based editors, for example, do not need an "xterm" and some editors cannot move to a specified line on startup.
The file xd_edit contains some examples for different types of editor along with explanatory comments. You can add special information for your chosen editor by copying existing lines. Refer to the documentation for your UNIX shell for details of the shell scripting language.
The xd_edit shell script checks the EDITOR environment variable for the name of the editor you wish to use. If it is not set, the script checks the VISUAL environment variable. If that is also not set, the default is "vi". If you wish to use either of these variables, specify the name along with the full directory name if it is not in a directory listed by your PATH environment variable. Once the script has decided on an editor, it runs the editor in the terminal program defined by the environment variable XD_TERM. If this is not set, the default is to use the xterm program.
See your UNIX documentation for details on using environment variables.
See Adding Callback Functionality for details on how to use the editing facility to edit callbacks and Code Preludes for a description of prelude editing.
X-Designer has an icon for each widget class. The icon is drawn on the palette buttons and displayed in the tree hierarchy. The icon can be either a full color XPM format pixmap or a monochrome bitmap. On start-up, X-Designer searches through the application resources to find a pixmap or bitmap file for each icon. If one cannot be found, a built-in bitmap is used.
Each Motif widget has an application resource that specifies its icon file. The application resource file is:
where XDROOT is your X-Designer install directory and your-locale is your local language locale name. The default locale is C. The LANG environment variable may tell you what your locale name is.
The application resource file contains a complete list of resource names for the Motif widget icons. For example, the resource for the ArrowButton icon is:
X-Designer searches in the same way as XmGetPixmap() to find the bitmap file. This search path is complex; for details, refer to the Motif documentation. In practice, X-Designer places the default pixmap files in $XDROOT/bitmaps and adds $XDROOT/bitmaps/%B to the XBMLANGPATH environment variable. Individual users can provide their own local pixmaps by creating a file of the correct name, such as arrow.xpm, in a directory and adding that directory with the file matching string "/%B" to the SW_VISU_XBMLANGPATH environment variable. For example,
setenv SW_VISU_XBMLANGPATH /home/me/pix/%B
X-Designer comes with two sets of icon pixmaps. The default set is located in $XDROOT/bitmaps. These icons are drawn using minimal color and will work on either color or monochrome screens.
A set of color pixmaps is located in $XDROOT/color_icons. To change to the color pixmaps, either set the environment variable SW_VISU_ICONS to color_icons, or add $XDROOT/color_icons/%B to the SW_VISU_XBMLANGPATH environment variable. To revert to the default icons either unset SW_VISU_ICONS or set it to bitmaps.
Alternatively, an individual user can specify a different file name by setting the resource in a local copy of the X-Designer resource file:
You can create your own color pixmaps for icons using XPM3 format. This format can be created using the X-Designer Pixmap editor (see Editing Pixmaps). Icon pixmaps can be any size; the palette and tree are displayed with a vertical spacing to accommodate the tallest icon. The X-Designer display looks best when all icon pixmaps are the same size. Default sizes are 32 by 32 for the large-screen icon pixmap and 20 by 20 for the small-screen version.
When printed from X-Designer, the icons are dithered to grey scales.
The icon should contain an area of transparency. X-Designer uses this area to display highlighting and structure colors in the tree and the background color on the palette button. XPM supports transparency by means of the color name "none" (not the color object "none"). See Transparent Colors for instructions on setting up transparent colors.
xdconfig's Widget Edit dialog lets you specify icons for user-defined widgets. For more information, see Widget Attributes.
The Edit Definitions dialog lets you specify an icon for each palette definition and a file name to be used as a fallback if the resource is not set. The pixmap file is searched for in the same way as the default pixmaps. If X-Designer cannot find the pixmap it will use the default pixmap for the widget that is at the root of the definition. See Editing the Definitions File for further details.
You can stop certain Motif widget classes from appearing on the X-Designer palette using the stopList resource. In addition, you can use xdconfig to stop user-defined widgets appearing on the palette. Because stopped widgets do not appear on the palette, they cannot be created interactively. They can be read in from a save file generated by X-Designer but are not selectable.
To stop a Motif widget class, specify the class name in the stopList resource. For example, to remove the Motif PanedWindow and ArrowButton from your widget palette, set the resource:
To stop a user-defined widget, specify the class name:
xdconfig has a Stopped Motif Widgets dialog which contains a toggle for each of the Motif widgets. For more information, see Chapter 23. Widgets that are removed from the palette in xdconfig cannot be added back in using X-Designer resources.
The default settings display a vertical palette containing three columns of widget icons and attached to the main window. You can change the default layout using the resource file. You can also change the palette layout at run time using the Palette Menu.
You can display the palette in a separate window. To separate the palette at run time, use the "Separate Palette" option in the Palette Menu. To have a separate palette by default, set the following resource:
When you separate the palette in the resource file, you must also explicitly set the default height of the X-Designer main window:
The resource file contains several examples of alternative layouts, such as:
By default, tooltip help is displayed as you pass the mouse pointer over widgets on the palette. If you wish to turn this option off throughout X-Designer, set it to "false" in the resource file:
You can also control this for individual widgets on the palette, for example:
The X-Designer interface includes a toolbar. Buttons in the toolbar correspond to buttons in the menus. Generally, when you select a toolbar button, it does exactly the same thing as the corresponding menu button.
To configure buttons into the toolbar, use the toolbarDescription resource. This should contain a comma-separated list of the widget names of the buttons. It can also contain the word separator to add extra space between items and the word flavor to insert the Microsoft Windows flavor option menu.
To obtain the widget name of a button, search X-Designer's application resource file for the entry that sets the labelString resource on the button in the menu bar. See Appendix E, for details on the location of application resource files.
X-Designer's resource file contains this line:
em_cut is the widget name of the "Cut" button in the Edit Menu.
The following line produces a toolbar with "Cut", "Copy", "Paste", "Core resources...", "Layout..." (layout editor), and "C" (code generation) buttons:
The toolbar buttons have the same widget name as the counterpart menu button and so, by default (assuming that no pixmaps are configured), they appear with the same words. For example, the resource file contains the line:
By default, this applies to both the menu and the toolbar. You might want to remove the ellipsis for the toolbar version since code generation buttons in the toolbar do not display a dialog. To do this, add the following line:
The toolbar buttons also have a string resource associated with them that specifies an XPM pixmap or X11 bitmap file in exactly the same way as for the palette buttons.
These pixmaps can be overridden by changing the resource or by providing a file earlier in the search path.
By default, tooltip help is displayed as you pass the mouse pointer over the buttons on the toolbar. If you wish to turn this option off throughout X-Designer, set it to "false" in the resource file:
You can also control this for individual widgets on the toolbar, for example:
This section describes resources that control Makefile generation. For an introduction to this feature, see Chapter 19.
Object and executable file names are derived from source file names by suffix substitution. The suffixes are specified by the following application resources:
The template used for generating new Makefiles is defined in two ways: either by filename or directly in the resource file. The second way is used as a fallback if the file cannot be found.
The template file is specified by one of two resources:
There are two resources so that you can have different templates customized to pick up the appropriate class libraries. The value for the resource can contain environment variables which will be expanded by /bin/sh.
The fallback template is specified by the makefileTemplate resource:
You can edit the Makefile variables set at the beginning of the template to reflect your system configuration. For example, you can set the XINCLUDES variable to the path for your X include files.
This section explains the symbols used in the Makefile template. In general we recommend that you not edit the default template except for the variables at the beginning. If you want to edit the actual template lines, first read Chapter 19, and try to get the results you want by setting a variable.
Lines in the Makefile template that begin with #X-Designer: are template lines. When X-Designer generates or updates a Makefile, it creates instances of the appropriate template lines for each design file based on the files you have generated and converts the special symbols beginning with an XDG_ prefix (X-Designer generated) to file names. XDG_ symbols convert to a single file, or a list of files if the symbol name ends with the _LIST suffix.
List symbols are used singly and not mixed with ordinary symbols in lines such as the following:
The XDG_C_PROGRAM_LIST symbol translates to a list of all executables that the Makefile can build. A typical instance of this template line is:
Ordinary template symbols, without the _LIST suffix, represent single files. You can combine any number of ordinary template symbols in lines such as:
When X-Designer generates the Makefile, it adds a separate instance of these lines for each design file for which you have generated code with the "Main program" toggle set. Other files in the application are linked in as XD_C_OBJECTS and XD_C_STUB_OBJECTS.
myapp1: myapp1.o $(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(CC) $(CFLAGS) $(XDG_DEBUG_FLAGS) $(CPPFLAGS) $(LDFLAGS) -o myapp1 myapp1.o
myapp2: myapp2.o $(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(CC) $(CFLAGS) $(XDG_DEBUG_FLAGS) $(CPPFLAGS) $(LDFLAGS) -o myapp2 myapp2.o
The following table shows the ordinary template symbols. You can add a _LIST suffix to most of these symbols to generate the corresponding list symbol. You cannot add _LIST to the "FLAGS" symbols. The filenames shown in parentheses are for illustration only.
For completeness, the following table shows you the Makefile template symbols used for Smart Code generation. Note, however, that these are for X-Designer's private use only and are not intended to be modified.
To ensure that your application looks and feels the same inside X-Designer and when running as an independent application, the dynamic display runs off a separate X resource database and has its own application class name--XDdynamic.
This means that the dynamic display cannot pick up X-Designer specific resources. What you see inside X-Designer is what you will see when you compile and run your code.
The dynamic display can be configured independently by creating a file called XDdynamic and placing both application specific and general resources in the file. For example, to produce a black and white appearance for printing add lines of the form:
For application specific resources, use the application class name as it appears in XDesigner for your product, for example:
Application specific resources of this type only load if the current application class matches the class in the file.
The XDdynamic file should be placed where X-Designer can pick it up through the normal X resource search mechanisms, as mentioned in Introduction.
XDdynamic resources affect only the dynamic display, and have no effect on any generated code.
Any Loose Bindings for the application are loaded after the XDdynamic resource file, and are similarly loaded into the separate application resource database: these take precedence over XDdynamic resources.
Specific resources applied to individual widgets through the resource panels are unaffected by all this, and will always take effect.