Previous Next Contents Generated Index Doc Set Home


CHAPTER 24

Command Line Operations





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.

Using a private colormap is useful if you intend to use a lot of colors in the pixmap editor. See Editing Pixmaps 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]] [-G directory [-O]] 
[--windows] -f filename


TABLE  24-2   visu command line options
Switch
Code file generated

c

C

s

C stubs

e

C externs

p

C/C++ pixmaps

A

Force ANSI C (use with -c, -s and -e)

K

Force K&R C (use with -c, -s and -e)

C

C++

S

C++ stubs

E

C++ externs

u

UIL

l

C for UIL

b

C externs for UIL

a

UIL pixmaps

r

X resource file

m

Makefile

X

X resource file (synonym for r)

M

Generate Motif flavor C++

F

Generate Motif XP flavor C++

J

Generate Java to the directory specified as code_file

-G directory

Generate to this directory (as if from the Generate Dialog)

-O (with -G)

Objects only. Generate no main code

W

Generate Microsoft Windows MFC flavor C++

pixmaps

Generate all pixmaps to separate .xpm files in the directory specified as code_file

R

Microsoft Windows resource file

windows

Start Sun WorkShop Visual in Microsoft Windows mode

f file

Specify input file




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.

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 testscript

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

t target

Use 'target' alternative internal libraries if available

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

interval ms

Allow ms (milliseconds) between execution of commands

ignore-server-time

Allow the client to run as fast as possible


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

t target

Use 'target' alternative internal libraries if available

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.




Previous Next Contents Generated Index Doc Set Home

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