CHAPTER 25 |
Configuration |
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 |
|
|
Toolbar |
|
|
Makefile templates |
For further information on Sun WorkShop Visual resources, see Appendix D, "Application Defaults", starting on page 871. For information on using visu_config, see Chapter 23, "User-Defined Widgets", starting on page 631.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" on page 717.
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:
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 Sun 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_editxd_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.
See "Adding Callback Functionality" on page 232 for details on how to use the editing facility to edit callbacks and "Code Preludes" on page 248 for a description of prelude editing.
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.
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 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.xpmSun 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
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.xpmor:visu.arrowButtonPixmap: /home/me/visu_bitmaps/my_arrow.xpm
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" on page 152). 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.
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" on page 164 for instructions on setting up transparent colors.
visu_config's Widget Edit dialog lets you specify icons for user-defined widgets. For more information, see "Widget Attributes" on page 643.
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" on page 275 for further details.
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,XmArrowButtonTo stop a user-defined widget, specify the class name:visu.stopList: boxWidgetClass,formWidgetClassvisu_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", starting on page 631. Widgets that are removed from the palette in visu_config cannot be added back in using Sun WorkShop Visual 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:visu*pm_separate.set:trueWhen 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: 600The 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: 2visu*icon_panel.basic_icons.numColumns: 2! Set both labels and icons onvisu*pm_both.set: true! You might also want to make the tool a bit widervisu.main_window.width: 750! Four columns, with labels underneathXDesigner*widgetPalette.composite.buttonBox.XmRowColumn.\
orientation: VERTICALXDesigner*widgetPalette.composite.buttonBox.numColumns: 4XDesigner*widgetPalette.basic.buttonBox.XmRowColumn.\
orientation: VERTICALXDesigner*widgetPalette.basic.buttonBox.numColumns: 4XDesigner*widgetPalette*xwidget_icons*orientation: VERTICALXDesigner*widgetPalette*xwidget_icons.numColumns: 4XDesigner*widgetPalette*_defn_icons*orientation: VERTICALXDesigner*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.
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: Cutem_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
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
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.xpmThese pixmaps can be overridden by changing the resource or by providing a file earlier in the search path.
This section describes resources that control Makefile generation. For an introduction to this feature, see Chapter 19, "Makefile Generation", starting on page 559.
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: .ovisu.executableFileSuffix:visu.uidFileSuffix: .uid
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/motif1visu.mmfcMakeTemplateFile: $VISUROOT/make_templates/mfcThere 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.
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", starting on page 559, 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:
#Sun WorkShop Visual:XD_C_PROGRAMS=XDG_C_PROGRAM_LISTThe 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 EDITOrdinary 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:XDG_C_PROGRAM: XDG_C_PROGRAM_OBJECT $(XD_C_OBJECTS) $(XD_C_STUB_OBJECTS)#Sun 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 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.#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 EDITThe 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 Sun WorkShop Visual's private use only and are not intended to be modified.
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: blackXDdynamic*background: whiteFor application specific resources, use the application class name as it appears in XDesigner for your product, for example:XApplication*XmPushButton.background: #dedededededeApplication 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" on page 871.
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.