Introduction

This chapter describes the command line switches understood by Sun WorkShop Visual. They fall into two categories: those which affect Sun WorkShop Visual running interactively and those which can be used for command line code generation. This chapter also describes the command line versions of Sun WorkShop Visual Capture and Sun WorkShop Visual Replay and the commands provided for conversion of UIL and GIL code into Sun WorkShop Visual save files.

Command Line Switches for Interactive Use

The following command line switches are available:

TABLE  24-1   visu command line options for interactive use

Switch	Meaning
windows	Start Sun WorkShop Visual in Microsoft Windows mode
f file	Specify input file
L	Use private colormap
x	Display this explanation (and exit)
V	Display Sun WorkShop Visual version information (the program is not run)

For further information on starting Sun WorkShop Visual in Microsoft Windows mode see "Starting in Microsoft Windows Mode" on page 364.

Using a private colormap is useful if you intend to use a lot of colors in the pixmap editor. See "Editing Pixmaps" on page 152 for a description of the pixmap editor. If you do select this option, however, you may observe strange color effects in other windows.

Generating Code from the Command Line

The command line synopsis is:

visu [-csepAKCSEulbarmRMFWX [code_file]] [-windows] -f filename

code_file represents the file to be generated. If you do not specify a code_file, Sun WorkShop Visual generates code to the last target file specified in your source file for the given language.

For Java code generation (-J) and pixmaps (-pixmaps) multiple source files may be generated and the names of the code files are the names of the classes (for Java) or the pixmaps used in your design. Therefore, code_file is the target directory for these source files.

filename represents the design file (.xd) to be used as a source for the code generation. You must always specify a filename. If you do not also specify a code_file, use the -f separator to indicate that you are providing only one filename.

The -windows switch specifies Microsoft Windows mode. For further information on starting Sun WorkShop Visual in Microsoft Windows mode see "Starting in Microsoft Windows Mode" on page 364.

The M, F, W and R switches are only used in conjunction with the -windows switch.

Examples

The command:

visu -c foo.c -f foo.xd

generates C code from the design in foo.xd into the file foo.c.

The command:

visu -c -f foo.xd

generates C code from foo.xd into the target file that was specified the last time C code was generated from foo.xd via the Generate Dialog.

You can use a single command to generate multiple files using one of the following forms:

visu -c -e -s -f foo.xd

or

visu -c <c_file> -e <extern_file> -s <stub_file> -f foo.xd

Sun WorkShop Visual exits with status zero if successful and non-zero status if it fails to generate the code for any reason.

Trouble-Shooting

Sun WorkShop Visual must be connected to an X server to generate code from the command line. Usually command line code generation does not create any visible windows but windows do appear momentarily on the server screen for designs containing certain types of widgets, such as ScrolledList and ScrolledText and when generating Microsoft Windows code.

If you don't specify a code_file, Sun WorkShop Visual relies on the filename saved in the design file for the specified type of code. The filename is only saved when you specify it on the Generate Dialog and then save the file. If you have never used the Generate Dialog to generate this type of code from the design file, Sun WorkShop Visual produces only an error message.

In all cases, the generate toggles are set as they were last saved in the design file. If you have never generated this type of code from the design file, default toggle settings are used.

Sun WorkShop Visual Replay

Sun WorkShop Visual Replay (when used to record user actions) is supplied as a stand-alone application called visu_record. .

The following line shows how to use visu_record:

visu_record -f MyRecordScript AnApplication

MyRecordScript is the name of a file into which a script recording the session will be saved. AnApplication is the name of the application you wish to record.

The following line shows how to use visu_replay:

You can leave out the filename argument for both Sun WorkShop Visual Replay and XD/Record. XD/Record will then output to standard output and Sun WorkShop Visual Replay will read from standard input.

The following table shows the full list of command line switches available for both visu_record and visu_replay:

TABLE  24-3   visu_record/visu_replay command line options

Switch	Meaning
x	Display information about the tool
f file	Save to file (otherwise stdout) for visu_record Read from file (otherwise stdin) for visu_replay
use n	Skip n shells before the real Application Shell
lang locale	Run visu_record/visu_replay (including the graphical user interface and all error messages) in locale and ignore any LANG settings
p	Preprocess script with C preprocessor before replaying
v	Verbose output
V	Print visu_record/visu_replay version information
w	Print summary information about the display, server and window manager
O	Override (program exit for non-motif applications
i	interactive (uses the Capture/Replay dialog - ignores `-f')
I	Force the dialog to appear
exit-on-error	Terminate the visu_replay script and the application if a command cannot be replayed
user-on-error	Terminate the visu_replay script and the application if a command cannot be replayed but remain in the application
skip-on-error	Jump to the next sequence in the script if a visu_replay command cannot be replayed

Sun WorkShop Visual Capture

Sun WorkShop Visual Capture is supplied as a stand-alone application called visu_capture.

The following line gives an example of how visu_capture can be used:

visu_capture AnApplication

This displays the Capture dialog and runs the application, AnApplication.

The following table shows the full list of command line switches available:

TABLE  24-4   visu_capture command line options

Switch	Meaning
x	Display information about visu_capture
f file	Save to file. No Capture dialog is displayed with this option
lang locale	Run visu_capture (including the graphical user interface and all error messages) in locale and ignore any LANG settings
use n	Skip n shells before the real Application Shell
v	Verbose output
V	Print visu_capture version information
w	Print summary information about the display, server and window manager
O	Override (program exit for non-motif applications
i	interactive (uses the Capture/Replay dialog - ignores `-f'). This is the default behavior
I	Force the dialog to appear
j	Java-Ready Capture
static-design	Take a single snapshot of the Application Shell

Converting UIL Source to Sun WorkShop Visual Save Files

The uil2xd filter converts UIL source code to Sun WorkShop Visual save files. It reads UIL source from standard input and writes a save file for Sun WorkShop Visual on standard output.

By default, uil2xd generates a save file for the latest release of Sun WorkShop Visual. The command line synopsis is:

uil2xd [-tlxywhpsaX] [-I include_dir]

The command line options are listed in the following table:

TABLE  24-5   uil2xd command line options

Switch	Meaning
t	Don't convert ScrolledWindow containing Text to Scrolled Text. By default uil2xd converts a ScrolledWindow widget containing a Text widget into a ScrolledText widget. Use the -t flag to preserve the structure.
l	Don't convert ScrolledWindow containing List to Scrolled List. By default uil2xd converts a ScrolledWindow widget containing a List widget into a ScrolledList widget. Use the -l flag to preserve the structure.
x	Pass through XmNx resources. By default uil2xd does not output absolute positions in the save file. Use the -x flag to pass XmNx resources into the output file.
y	Pass through XmNy resources. By default uil2xd does not output absolute positions in the save file. Use the -y flag to pass XmNy resources into the output file.
w	Pass through XmNwidth resources. By default uil2xd does not output absolute sizes in the save file. Use the -w flag to pass XmNwidth resources into the output file.
h	Pass through XmNheight resources. By default uil2xd does not output absolute sizes in the save file. Use the -h flag to pass XmNheight resources into the output file.
p	Preserve position resources in output file. Same as -x -y
s	Preserve size resources in output file. Same as -w -h
a	Preserve position and size resources in output file. Same as -p -s
e	Explain how to recover from syntax errors
A	Generate fake attachments for unattached form children
I include_dir	Adds include_dir to the list of directories that will be searched for include files.
X	Print list of switches.

uil2xd does not handle the following constructs:

String tables containing compound strings

Color_table

Icon

Ascii tables in argument definition

Integer tables in argument definition

Imported keyword - this is a fatal error

Exported keyword

Private keyword

Creation procedure

Default character set clause

Identifier section

Except for the imported keyword, uil2xd simply ignores these constructs.

Converting GIL Source to Sun WorkShop Visual Save Files

The gil2xd filter converts Sun Microsystems Inc.'s DevGuide save files into Sun WorkShop Visual save files. The converter works by mapping the OPEN LOOK objects into Motif objects. It reads GIL source from standard input and writes a save file for Sun WorkShop Visual on standard output.

It generates a save file for the latest version of Sun WorkShop Visual. The command line synopsis is:

gil2xd [-xywhpsaX]

The command line options are listed in the following table:

TABLE  24-6   gil2xd command line options

Switch	Meaning
x	Pass through XmNx resources. By default gil2xd does not output absolute positions in the save file. Use the -x flag to pass XmNx resources into the output file.
y	Pass through XmNy resources. By default gil2xd does not output absolute positions in the save file. Use the -y flag to pass XmNy resources into the output file.
w	Pass through XmNwidth resources. By default gil2xd does not output absolute sizes in the save file. Use the -w flag to pass XmNwidth resources into the output file.
h	Pass through XmNheight resources. By default gil2xd does not output absolute sizes in the save file. Use the -h flag to pass XmNheight resources into the output file.
p	Preserve position resources in output file. Same as -x -y
s	Preserve position and size resources in output file. Same as -w -h
a	Preserve position and size resources in output file. Same as -p -s
X	Print list of switches

gil2xd does not handle connections other than function calls and the simple notify actions for buttons which can be mapped to links. Other connections are reported as warnings. gil2xd simply ignores these constructs.

Mappings

Few of the mappings from OPEN LOOK objects to Motif widgets are straightforward as they depend somewhat on their context. The fundamentals of the mappings are outlined below.

base-window

Maps to a DialogShell with a MainWindow child with a Form work area.

popup-window

Maps to a DialogShell with a Form child.

canvas-pane

Maps to a DrawingArea which will be a child of a ScrolledWindow if horizontal-scrollbar or vertical-scrollbar is true. An associated PopupMenu
is created as a child of the DrawingArea.

control-area

Maps to a Form.

menu

Maps to a Menu. If the menu has a menu-title attribute, the first child widget will be a Label which shows the title, followed by a Separator. The menu items are mapped to additional children of the Menu. If the menu-type attribute is command, the widgets will be ToggleButtons; if they have an associated menu they will be CascadeButtons, otherwise they will be PushButtons. As Sun WorkShop Visual has no concept of shared menus, menus which are referenced from more than one place will map to copies of the Menu.

message

Maps to a Label.

button

Maps to a PushButton if it does not have a menu, otherwise it maps to a CascadeButton. This CascadeButton will be created in a MenuBar. CascadeButtons which have the same y co-ordinate will be created in the same MenuBar. The MenuBar will be created in an enclosing MainWindow if possible, otherwise it will be created at the appropriate location.

slider and gauge

Both map to a Scale. Separators will be added as children for tick marks and Labels may be added to show the min-value-string and max-value-string. The min-value and max-value map to the Scale's minimum and maximum fields respectively.

setting

Maps to an OptionMenu if setting-type is stack, otherwise maps to a RowColumn. The choices are mapped to PushButtons in an OptionMenu and ToggleButtons in a RowColumn. For exclusive and non-exclusive settings the ToggleButton is adjusted so that the indicator is not used (shadowThickness = 2, marginLeft = 0, indicatorOn = false).

text field

Maps to RowColumn with Label and Text widgets. Text will be ScrolledText if text-type is set to multiline.

list

Maps to a ScrolledList. If the list has a label attribute set, the ScrolledList is created as a child of a RowColumn with a Label child which displays the label. If the list has a title attribute, the ScrolledList is created as a child of a Frame with a Label to display this title.

drop-target

Maps to a Label.

stack

Maps to a Form which has each of the stack members as children. The children are attached to both sides of the Form.

group

Maps to a RowColumn which has each of the member widgets as children.

term-pane and text-pane

Both map to ScrolledText.

Attributes

Once the gil objects have been mapped to widgets the attributes must be mapped to appropriate widget resources. The following resources are always mapped:

TABLE  24-7   Resources that are Always Mapped

gil	xd	Notes
x	XmNx
y	XmNy
width	XmNwidth
height	XmNheight
foreground-color	XmNforeground
background-color	XmNbackground
initial-state	XmNsensitive	inactive - sensitive = false invisible - managed = false

The width and height resources are only used if the -w or -h flags are set when gil2xd is run. The x and y resources will be output if the -x or -y flags are set. However, for widgets which are children of Forms the x and y co-ordinates will be used to calculate default Form attachments to preserve the approximate layout.

Note that many of the Motif manager widgets will ignore explicit x, y, width and height resources anyway. The gil2xd filter can be used without any of the runtime flags to produce an adequate layout which can be easily modified using Sun WorkShop Visual.

Other resources are mapped to the nearest possible resource.

TABLE  24-8   Resources that are Mapped to the Nearest Possible Resource

gil	xd	Notes
columns	XmNcolumns
constant-width	XmNrecomputeSize
group-type	XmNorientation	Sets XmNnumColumns, XmNorientation and XmNpacking to reproduce a similar layout of group
icon-file	XmNiconPixmap
icon-label	XmNiconName
icon-mask	XmNiconMask
initial-state	XmNinitialState	DialogShell only
initial-value	XmNvalue
label	XmNlabelString	If matching label-type attribute is glyph then label is mapped to labelPixmap
label	XmNtitle	For shells
label	XmNtitleString	For gauge
label-type	XmNlabelType
layout-type	XmNorientation
max-value	XmNmaximum
menu-type	XmNradioBehavior	If exclusive, XmNradioBehavior = true
min-value	XmNminimum
multiple-selections	XmNselectionPolicy	If set, XmNselectionPolicy = MULTIPLE_SELECT
orientation	XmNorientation
pinnable	XmNtearOffModel	If pinnable, XmNtearOffModel = TEAR_OFF_ENABLED
read-only	XmNeditable
resizeable	XmNallowResize
rows	XmNnumColumns	Sets XmNnumColumns, XmNorientation and XmNpacking to reproduce a similar layout of settings
rows	XmNrows	For text widget
rows	XmNvisibleItemCount	For list widget
selection-required	XmNradioAlwaysOne
show-border	XmNshadowThickness	If set sets XmNshadowThickness to 1 for forms which are not children of a Shell
show-value	XmNshowValue
slider-width	XmNscaleWidth	Sets XmNscaleWidth or XmNscaleHeight depending on orientation
stored-length	XmNmaxLength
text-initial-value	XmNvalue
text-type	XmNeditMode	If multiline, XmNscrollVertical = false, rows maps to XmNrows
title	XmNlabelString
value-length	XmNcolumns

Actions which have a CallFunction function_type are mapped to callbacks where appropriate.

TABLE  24-9   Actions that are Mapped to Callbacks

Action	Callback	Widget
Create	XmNcreateCallback	Any
Destroy	XmNdestroyCallback	Any
Notify	XmNactivateCallback	PushButton
select	XmNinputCallback	DrawingArea
adjust	XmNinputCallback	DrawingArea
DoubleClick	XmNinputCallback	DrawingArea
Repaint	XmNexposeCallback	DrawingArea
Resize	XmNresizeCallback	DrawingArea
Select	XmNvalueChangedCallback	Gauge
Adjust	XmNdragCallback	Gauge
Notify	XmNvalueChangedCallback	Gauge
Popup	XmNmapCallback	Menu
Popdown	XmNunmapCallback	Menu
Notify	XmNentryCallback	Menu
Notify	XmNvalueChangedCallback	ToggleButton
Unselect	XmNvalueChangedCallback	ToggleButton
Popup	XmNpopupCallback	Shell
Popdown	XmNpopdownCallback	Shell
Notify	XmNactivateCallback	Text
KeyPress	XmNvalueChangedCallback	Text
Notify	XmNentryCallback	RowColumn
Done	XmNunmapCallback	Form
Notify	XmNbrowseSelectionCallback	List

There are a number of other gil actions which are not detailed in this list. These are not supported by the filter as there is no appropriate Motif callback.

Notify actions for PushButtons which have a Show, Hide, Enable or Disable connection are mapped to the appropriate Sun WorkShop Visual link.