Configuration

20

20.1 Introduction

There are several ways to customize 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
Toolbar
Makefile templates

For further information on WorkShop Visual resources, see Appendix A, "Application Defaults", starting on page 719. For information on using visu_config, see Chapter 14, "User-Defined Widgets", starting on page 471.

20.2 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 A, "Application Defaults" for details on using WorkShop Visual's application resources. This first resource controls whether or not you wish the callback editing mechanism to be present:

callbackEditing

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 SunSoft WorkShop Edit Server, you will need to specify which editor to use.

editor

This resource specifies the location of the shell wrapper script which starts up the editor. By default it is set to:

$VISUROOT/lib/scripts/xd_edit

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 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 the Adding Callback Functionality section on page 239 for details on how to use the editing facility to edit callbacks and the Code Preludes section on page 256 for a description of prelude editing.

20.3 Palette Icons

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, 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.

20.3.1 Specifying the Icon File

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

$VISUROOT/lib/locale/<your-locale>/app-defaults/visu

where VISUROOT is your 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

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, 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

20.3.2 Default Pixmaps

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 WorkShop Visual resource file:

visu.arrowButtonPixmap: my_arrow.xpm

or:

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

20.3.3 Pixmap Requirements

You can create your own color pixmaps for icons using XPM3 format. This format can be created using the WorkShop Visual Pixmap editor (see the Editing Pixmaps section on page 160). Icon pixmaps can be any size; the palette and tree are displayed with a vertical spacing to accommodate the tallest icon. The 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 WorkShop Visual, the icons are dithered to grey scales.

20.4 Palette Contents

You can stop certain Motif widget classes from appearing on the 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 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 14, "User-Defined Widgets", starting on page 471. Widgets that are removed from the palette in visu_config cannot be added back in using WorkShop Visual resources.

20.5 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.

20.5.1 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:

visu*pm_separate.set:true

When you separate the palette in the resource file, you must also explicitly set the default height of the 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

visu*icon_panel.composite_icons.XmRowColumn.\

orientation: VERTICAL

visu*icon_panel.composite_icons.numColumns: 4

visu*icon_panel.basic_icons.XmRowColumn.\

orientation: VERTICAL

visu*icon_panel.basic_icons.numColumns: 4

visu*icon_panel*xwidget_icons.XmRowColumn.\

orientation: VERTICAL

visu*icon_panel*xwidget_icons.numColumns: 4

visu*icon_panel*defn_icons.XmRowColumn.\

orientation: VERTICAL

visu*icon_panel*defn_icons.numColumns: 4

20.6 Toolbar

The 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.

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

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:

visu.toolbarDescription:separator,em_cut,\

em_copy,em_paste,separator,wm_prim,\

wm_layout,separator,gm_c

20.6.2 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

20.6.3 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.

20.7 Makefile Features

This section describes resources that control Makefile generation. For an introduction to this feature, see Chapter 15, "Makefile Generation", starting on page 525.

20.7.1 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.executableFileSuffix:

visu.uidFileSuffix: .uid

20.7.2 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/motif¹

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:

visu.makefileTemplate:\

# System configuration\n\

# ---------------------\n\

\n\

# everything is in /usr/include or /usr/lib\n\

XINCLUDES=\n\

XLIBS=\n\

LDLIBS=\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.

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

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

#WorkShop Visual:XD_C_PROGRAMS=XDG_C_PROGRAM_LIST

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:

#DO NOT EDIT >>>

XD_C_PROGRAMS=\

myapp1\

myapp2

#<<< DO NOT EDIT

Ordinary template symbols, without the _LIST suffix, represent single files. You can combine any number of ordinary template symbols in lines such as:

#WorkShop Visual:XDG_C_PROGRAM: XDG_C_PROGRAM_OBJECT 
$(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS)

#WorkShop Visual:	$(CC) XDG_C_DEBUG_FLAGS $(CFLAGS) $(CPPFLAGS) 
$(LDFLAGS) -o XDG_C_PROGRAM XDG_C_PROGRAM_OBJECT $(XD_C_OBJECTS) 
$(XD_C_STUB_OBJECTS) $(MOTIFLIBS) $(LDLIBS)

When 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.

#DO NOT EDIT >>>

myapp1: myapp1.o $(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(CC) 
$(CFLAGS) $(XDG_DEBUG_FLAGS) $(CPPFLAGS) $(LDFLAGS) -o myapp1 
myapp1.o

$(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(MOTIFLIBS) $(LDLIBS)

#<<< DO NOT EDIT

#DO NOT EDIT >>>

myapp2: myapp2.o $(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(CC) 
$(CFLAGS) $(XDG_DEBUG_FLAGS) $(CPPFLAGS) $(LDFLAGS) -o myapp2 
myapp2.o

$(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS) $(MOTIFLIBS) $(LDLIBS)

#<<< DO NOT EDIT

The following table shows the ordinary template symbols. You can add a _LIST suffix to any of these symbols to generate the corresponding list symbol.

Table 20-1 Makefile Template Symbols
Name	Use
XDG_C_PROGRAM_SOURCE	C source for main program (main.c)
XDG_C_PROGRAM_OBJECT	Corresponding object (main.o)
XDG_C_PROGRAM	Corresponding executable (main)
XDG_C_SOURCE	C source (foo.c)
XDG_C_OBJECT	Corresponding object (foo.o)
XDG_C_STUB_SOURCE	C stubs (stubs.c)
XDG_C_STUB_OBJECT	Corresponding object (stubs.o)
XDG_C_EXTERN	C header (externs.h)
XDG_C_PIXMAP	C pixmaps (pixmaps.h)
XDG_CC_PROGRAM_SOURCE	C++ source for main program (main.cpp)
XDG_CC_PROGRAM_OBJECT	Corresponding object (main.o)
XDG_CC_PROGRAM	Corresponding executable (main)
XDG_CC_SOURCE	C++ source (foo.cpp)
XDG_CC_OBJECT	Corresponding object (foo.o)
XDG_CC_STUB_SOURCE	C++ stubs (stubs.cpp)
XDG_CC_STUB_OBJECT	Corresponding object (stubs.o)
XDG_CC_EXTERN	C++ header (externs.h)
XDG_CC_PIXMAP	C++ pixmaps (pixmaps.h)
XDG_UIL_SOURCE	UIL source (foo.uil)
XDG_UIL_OBJECT	Corresponding compiled UIL (foo.uid)
XDG_C_FOR_UIL_PROGRAM_SOURCE	C for UIL source with main program (main.c)
XDG_C_FOR_UIL_PROGRAM_OBJECT	Corresponding object (main.o)
XDG_C_FOR_UIL_PROGRAM	Corresponding executable (main)
XDG_C_FOR_UIL_SOURCE	C for UIL source (foo.c)
XDG_C_FOR_UIL_OBJECT	Corresponding object (foo.o)
XDG_C_FOR_UIL_EXTERN	C for UIL header (externs.h)
XDG_UIL_PIXMAP	UIL pixmaps (pixmaps.uil)
XDG_X_RESOURCE_FILE	X resource file (foo.res)
XDG_C_DEBUG_FLAGS	C compiler debugger flag(s)
XDG_CPP_DEBUG_FLAGS	C++ compiler debugger flag(s)

The file names shown in parentheses are for illustration only.

¹ $ is the path to the root of the installation directory.