Previous Next Contents Generated Index Doc Set Home




There are several ways to customize Sun WorkShop Visual, using either the resource file or visu_config. This section explains the main features that can be customized via the resource file. These features are:

Callback and Prelude editing
Palette icons
Palette contents and layout
Makefile templates
For further information on Sun WorkShop Visual resources, see Appendix  D, "Application Defaults". For information on using visu_config, see Chapter 23, "User-Defined Widgets".

Another area of Sun WorkShop Visual 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.

Setting up Callback and Prelude Editing

There are two mechanisms for editing callbacks and preludes. The first uses the Sun Edit Services and the second simply invokes an editor of your choice in an "xterm" window. This section describes the application resources, applications and environment variables needed to configure the editing mechanism. See Appendix D, "Application Defaults" for details on using Sun WorkShop Visual'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 without using the Sun WorkShop Edit Server, 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 Sun WorkShop Visual 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.

Using the Editing Facility

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.

Palette Icons

Sun WorkShop Visual 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, Sun WorkShop Visual 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.

Specifying the Icon File

Each Motif widget has an application resource that specifies its icon file. The application resource file is:


where VISUROOT is your Sun WorkShop Visual 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:

visu.arrowButtonPixmap: arrow.xpm
Sun WorkShop Visual 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, Sun WorkShop Visual places the default pixmap files in $VISUROOT/bitmaps and adds $VISUROOT/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

Default Pixmaps

Sun WorkShop Visual comes with two sets of icon pixmaps. The default set is located in $VISUROOT/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 $VISUROOT/color_icons. To change to the color pixmaps, either set the environment variable SW_VISU_ICONS to color_icons, or add $VISUROOT/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 Sun WorkShop Visual resource file:

visu.arrowButtonPixmap: my_arrow.xpm

visu.arrowButtonPixmap: /home/me/visu_bitmaps/my_arrow.xpm

Pixmap Requirements

You can create your own color pixmaps for icons using XPM3 format. This format can be created using the Sun WorkShop Visual 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 Sun WorkShop Visual 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 Sun WorkShop Visual, the icons are dithered to grey scales.

Transparent Area

The icon should contain an area of transparency. Sun WorkShop Visual 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.

Icons for User-Defined Widgets

visu_config's Widget Edit dialog lets you specify icons for user-defined widgets. For more information, see Widget Attributes.

Icons for Palette Definitions

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 Sun WorkShop Visual 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.

Palette Contents

You can stop certain Motif widget classes from appearing on the Sun WorkShop Visual palette using the stopList resource. In addition, you can use visu_config 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 Sun WorkShop Visual 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:

visu.stopList: XmPanedWindow,XmArrowButton
To stop a user-defined widget, specify the class name:

visu.stopList: boxWidgetClass,formWidgetClass
visu_config has a Stopped Motif Widgets dialog which contains a toggle for each of the Motif widgets. For more information, see Chapter 23, "User-Defined Widgets". Widgets that are removed from the palette in visu_config cannot be added back in using Sun WorkShop Visual resources.

Palette Layout

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.

Separate Palette

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 Sun WorkShop Visual main window:

visu.main_window.height: 600
The resource file contains several examples of alternative layouts, such as:

! Two columns is good if you do not have user defined widgets

visu*icon_panel.composite_icons.numColumns: 2
visu*icon_panel.basic_icons.numColumns: 2
! Set both labels and icons on

visu*pm_both.set: true
! You might also want to make the tool a bit wider

visu.main_window.width: 750
! Four columns, with labels underneath

orientation: VERTICAL
XDesigner*widgetPalette.composite.buttonBox.numColumns: 4
orientation: VERTICAL
XDesigner*widgetPalette.basic.buttonBox.numColumns: 4
XDesigner*widgetPalette*xwidget_icons*orientation: VERTICAL
XDesigner*widgetPalette*xwidget_icons.numColumns: 4
XDesigner*widgetPalette*_defn_icons*orientation: VERTICAL
XDesigner*widgetPalette*_defn_icons.numColumns: 4


The Sun WorkShop Visual 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.

Configuring the Toolbar

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 Sun WorkShop Visual's application resource file for the entry that sets the labelString resource on the button in the menu bar. See Appendix D, "Application Defaults", for details on the location of application resource files.

Sun WorkShop Visual's resource file contains this line:

visu*em_cut.labelString: Cut
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:


Labels for Toolbar 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:

visu*gm_c.labelString: C...
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:

visu*toolbar.gm_c.labelString: C

Pixmaps for Toolbar Buttons

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.

visu*toolbar.em_copy_file.toolbarPixmap: em_copy_file.xpm
These pixmaps can be overridden by changing the resource or by providing a file earlier in the search path.

Makefile Features

This section describes resources that control Makefile generation. For an introduction to this feature, see Chapter 19, "Makefile Generation".

File Suffixes

Object and executable file names are derived from source file names by suffix substitution. The suffixes are specified by the following application resources:

visu.objectFileSuffix: .o
visu.uidFileSuffix: .uid

Makefile Template

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:

visu.motifMakeTemplateFile: $VISUROOT/make_templates/motif1
visu.mmfcMakeTemplateFile: $VISUROOT/make_templates/mfc
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:

# System configuration\n\
# ---------------------\n\
# everything is in /usr/include or /usr/lib\n\
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.

Template Protocol

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, "Makefile Generation", and try to get the results you want by setting a variable.

Lines in the Makefile template that begin with #Sun WorkShop Visual: are template lines. When Sun WorkShop Visual 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 (Sun WorkShop Visual 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:

#Sun WorkShop Visual:	$(CC) XDG_C_DEBUG_FLAGS $(CFLAGS) $(CPPFLAGS) 
When Sun WorkShop Visual 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.

TABLE  25-1   Makefile Template Symbols


C source for main program (main.c)


Corresponding object (main.o)


Corresponding executable (main)


C source (foo.c)


Corresponding object (foo.o)


C stubs (stubs.c)


Corresponding object (stubs.o)


C header (externs.h)


C pixmaps (pixmaps.h)


C++ source for main program (main.cpp)


Corresponding object (main.o)


Corresponding executable (main)


C++ source (foo.cpp)


Corresponding object (foo.o)


C++ stubs (stubs.cpp)


Corresponding object (stubs.o)


C++ header (externs.h)


C++ pixmaps (pixmaps.h)


Include directory for extra Java Widgets


Archive Library for extra Java Widgets


UIL source (foo.uil)


Corresponding compiled UIL (foo.uid)


C for UIL source with main program (main.c)


Corresponding object (main.o)


Corresponding executable (main)


C for UIL source (foo.c)


Corresponding object (foo.o)


C for UIL header (externs.h)


UIL pixmaps (pixmaps.uil)


X resource file (foo.res)


C compiler debugger flag(s)


C++ compiler debugger flag(s)

For completeness, the following table shows you the Makefile template symbols used for Smart Code generation. Note, however, that these are for Sun WorkShop Visual's private use only and are not intended to be modified.

TABLE  25-2   Private Makefile Template Symbols for Smart Code


Smart Code C++ object files


Smart Code C++ source files


Server-side Smart Code C++ object files


Server-side Smart Code C++ source files


Server-side Smart Code C++ executeable name


Server-side Smart Code C++ main object file


Server-side Smart Code C++ main source file


Compiler flags required for C/C++ Smart Code


Linker flags required for C/C++ Smart Code


Smart Code C object files


Smart Code C source files


Server-side Smart Code C/C++ Compiler flags


Server-side Smart Code C/C++ Linker flags


Server-side Smart Code C object files


Server-side Smart Code C source files


Server-side Smart Code C executeable name


Server-side Smart Code C main object file


Server-side Smart Code C main source file

Dynamic Display Window

To ensure that your application looks and feels the same inside Sun WorkShop Visual 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 Sun WorkShop Visual specific resources. What you see inside Sun WorkShop Visual 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:

XDdynamic*foreground: black
XDdynamic*background: white
For application specific resources, use the application class name as it appears in XDesigner for your product, for example:

XApplication*XmPushButton.background: #dededededede
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 Sun WorkShop Visual 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.

1 $VISUROOT is the path to the root of the Sun WorkShop Visual installation directory.

Previous Next Contents Generated Index Doc Set Home

Copyright © 2000 Sun Microsystems, Inc. & Imperial Software Technology Ltd. All Rights Reserved.