wksh(1)


wksh -- Windowing Korn Shell, graphical extensions to ksh

Synopsis

wksh [-mode] [+-aefhikmnprstuvx] [+-o option] ... [-c string] [arg ...]

Description

wksh (Windowing Korn Shell(TM)) offers a number of extensions to the standard Korn Shell (see ksh(1)) in order to create and manage graphical user-interface widgets. There are also a number of commands that allow the programmer to extend the wksh language by attaching C code dynamically, register C functions as new built-in commands, register new widget definitions, and call C functions directly from attached libraries. All normal ksh commands and features are also supported, wksh is a true superset of standard ksh.

The following sections give some background information on concepts that are shared by a number of commands.

A note on toolkits

wksh supports MoOLIT(TM) (a superset of OPEN LOOK®), and OSF(TM) Motif(TM) widget sets. This manual page will only cover Motif, because MoOLIT is now considered obsolete.

Most commands, including all commands from the Xt Intrinsics and Xlib layers and some convenience functions, apply to all three toolkits.

The programmer must specify which toolkit is being used either by giving wksh one of the options: -openlook or -motif, or by setting the variable $WKSHTOOLKIT to either OPENLOOK or MOTIF.


NOTE: OPENLOOK and -openlook imply the MoOLIT toolkit on systems that support MoOLIT.

Although slightly confusing this was done to maintain compatibility with older versions of wksh that supported OPEN LOOK.

This manual page cannot possibly explain how to use every widget of the Motif toolkit, you must refer to reference materials on Motif for that information. This manual page assumes basic familiarity with X concepts, see tutorial materials on wksh if that is not the case.

Widget handles

Most commands that would return a widget in the C language Xt Intrinsics will instead set an environment variable to a widget handle in wksh. A widget handle is an ASCII string used by wksh to access an actual widget pointer. Commands that create widget handles take as an argument an environment variable name set to the handle. For example, the XtCreateManagedWidget command looks like this:
   XtCreateManagedWidget MYWIDGET widget form $TOPLEVEL

After a command like this, $MYWIDGET can be used to attach children to the newly created form widget.


NOTE: In the call above, $TOPLEVEL was also set up by another built-in (XtAppInitialize) in an analogous fashion.

This manual page uses the following conventions in defining arguments to a command:


variable
name of the environment variable set as a side effect of the function to a returned widget handle

$handle

$parent
environment variable that was previously set to a widget handle by some other wksh command

ksh-cmd
any legal wksh command string

Resources

wksh has internal tables to convert resources, all conversions are automatic.

Resources are set using the notation:

   resource:value

In this notation, resource is the name of the resource, value is a string representation of the value. wksh uses String-to-Type converters on this value, as appropriate for the resource in question.

Here are some examples of resource setting notation:

   XtSetValues $MYWIDGET x:0 y:100 label:"a string"
   XtSetValues $WIDGET3 xRefWidget:"$WIDGET2"

When resources are retrieved using XtGetValues, a similar notation is used:

   resource:variable

the resource is the resource name as above. The variable is the name of an environment variable that receives a string representation of the value.

Aliases

For programmer convenience, a standard set of aliases are predefined for all of the X Intrinsics built-ins. These aliases follow a general naming standard: they always drop the ``Xt'' prefix, they include just the first character of each ``word'' in a command. There are a few exceptions to preserve uniqueness, but in all cases the aliases were chosen to be mnemonic and require minimal input. For example, XtCreateManagedWidget is aliased cmw, XtAddCallback is aliased acb.

Each command description lists the aliases available for that command. Some commands also have aliases providing short forms for commonly used options on that command. For example, ListOp -a is aliased listadd. These aliases provide enhanced readability.

Options

The wksh command accepts one new option

-mode
GUI mode, either ``motif'' or ``openlook''. If used, this option must be the first option to wksh. The default is -openlook, although this is now considered an obsolete toolkit, so users should specify -motif.

Other options available to wksh are the same as ksh (see ksh(1)).

Shell variables

The following environment variables are used by wksh and its associated commands to set certain defaults:

Variable Default if not set Use by wksh
WKSHLIBDIR /usr/X/lib/wksh Directory where convenience functions, examples, and so on are stored
WKSHBINDIR /usr/X/bin Directory where bootstrap executables olwksh (OPEN LOOK) and xmwksh (MOTIF) are stored
WKSHTOOLKIT OPEN LOOK Either OPENLOOK or MOTIF, toolkit to use if command line option -openlook or -motif is not specified
WKSHFPATH $FPATH Overrides $FPATH in the case of wksh execution. See ksh(1) for a description of FPATH

 Variable      Default if not set   Use by wksh
 WKSHLIBDIR    /usr/X/lib/wksh      Directory where
                                    convenience
                                    functions,
                                    examples, and so on
                                    are stored
 WKSHBINDIR    /usr/X/bin           Directory where
                                    bootstrap
                                    executables olwksh
                                    (OPEN LOOK) and
                                    xmwksh (MOTIF) are
                                    stored
 WKSHTOOLKIT   OPEN LOOK            Either OPENLOOK or
                                    MOTIF, toolkit to
                                    use if command line
                                    option -openlook or
                                    -motif is not
                                    specified
 WKSHFPATH     $FPATH               Overrides $FPATH in
                                    the case of wksh
                                    execution.  See
                                    ksh(1) for a
                                    description of
                                    FPATH

The following environment variables are set by various commands in wksh as conveniences to the user. Full details are given under the associated command.

Variable Set by command Summary
WKSHAPI XtAppInitialize One of: OPENLOOK, MOTIF, or MOOLIT
TOPLEVEL XtAppInitialize The handle of the TopLevelShell Widget
APPNAME XtAppInitialize The Application's name

 Variable   Set by command    Summary
 WKSHAPI    XtAppInitialize   One of: OPENLOOK,
                              MOTIF, or MOOLIT
 TOPLEVEL   XtAppInitialize   The handle of the
                              TopLevelShell
                              Widget
 APPNAME    XtAppInitialize   The Application's
                              name

Sub-object convenience variables

Some widgets which contain sub-objects automatically store the widget handle of the sub-object in a variable when the widget is created. The variable name which holds the sub-object handle is constructed by adding a suffix to the parent's variable name. In the table below, VAR stands for the parent's widget handle variable.

Widget Convenience variable Sub object
MOTIF:
MessageBox $VAR_CAN Cancel button
$VAR_DEF Default button
$VAR_HELP Help button
$VAR_LAB Message label
$VAR_OK OK button
$VAR_SEP Separator
$VAR_SYM Symbol label
FileSelectionBox $VAR_APPLY Apply button
$VAR_DEF Default button
$VAR_CAN Cancel button
$VAR_HELP Help button
$VAR_OK OK button
$VAR_SEP Separator
$VAR_FILTLAB Filter label
$VAR_FILTTXT Filter text
$VAR_SELLAB Selection label
$VAR_TEXT Text
MainWindow $VAR_SEP1 Separator 1
$VAR_SEP2 Separator 2

 Widget             Convenience variable   Sub object
 MOTIF:
 MessageBox         $VAR_CAN               Cancel button
                    $VAR_DEF               Default button
                    $VAR_HELP              Help button
                    $VAR_LAB               Message label
                    $VAR_OK                OK button
                    $VAR_SEP               Separator
                    $VAR_SYM               Symbol label
 FileSelectionBox   $VAR_APPLY             Apply button
                    $VAR_DEF               Default button
                    $VAR_CAN               Cancel button
                    $VAR_HELP              Help button
                    $VAR_OK                OK button
                    $VAR_SEP               Separator
                    $VAR_FILTLAB           Filter label
                    $VAR_FILTTXT           Filter text
                    $VAR_SELLAB            Selection label
                    $VAR_TEXT              Text
 MainWindow         $VAR_SEP1              Separator 1
                    $VAR_SEP2              Separator 2

In addition, for the OPEN LOOK ScrollingList widget two variables are constantly kept up to date by wksh: $VAR_NUMITEMS, $VAR_CURITEM, and $VAR_CURINDEX, which are respectively the number of items in the list, the text of the current item, and the index of the current item. Callbacks can be any arbitrary wksh command line. During execution of the command line, the environment variable CB_WIDGET will be set to the handle of the widget on whose behalf the callback is being executed.

Files


/usr/X/lib/wksh/olexamples
OPEN LOOK example programs

/usr/X/lib/wksh/xmexamples
Motif example programs

/usr/X/lib/wksh/xlibexamples
Xlib example programs

/usr/X/lib/wksh/olwksh.rc
bootstrap rc file for OPEN LOOK/MoOLIT

/usr/X/lib/wksh/xmwksh.rc
bootstrap rc file for MOTIF

/usr/X/lib/wksh/pixmaps
Pixmaps for example programs

/usr/X/bin/olwksh
bootstrap executable file for OPEN LOOK/MoOLIT

/usr/X/bin/xmwksh
bootstrap executable file for MOTIF

/usr/X/bin/wksh
bootstrap executable file for wksh

Usage

The wksh executable provides new built-in commands and shell functions. Built-in commands are built into the shell, much like other standard ksh built-in commands, for example echo or cd. Shell functions are small wksh scripts pulled into an application the first time referenced. Text for these shell functions is contained in the directory /usr/lib/wksh/xmfuncs. It is often useful to take these standard functions and modify them for slightly different purposes, although by convention the programmer should change the function name when making such modifications. Most of them are short (ten to twenty lines). The following sections will note when commands are provided using shell functions as opposed to built-in commands, although to the programmer there is no visible difference.

The commands will be divided into three sections: Widget Set Independent Graphics Commands, Motif Graphics Commands, and C Function Access Commands.


addbuttons $parent [ label command ] ...

addbuttons -w $parent [ variable label command ] ..
Add a set of buttons to a parent widget. This shell function is useful for adding a set of buttons to a menu or RowColumn in a concise manner.

In the first form, the parent is the first argument to the function, followed by any number of pairs of arguments specifying the label on the button and the command to be executed if the button is selected.

In the second form, with the -w option, addbuttons takes triplets of arguments after the parent is specified. Each triplet specifies the environment variable to be set to the handle of the newly created button, the label, and the associated command.

By default, addbuttons creates PushButtonGadgets. Set the environment variable BUTTONTYPE to obtain a different kind of button.


addfields $parent [ variable label verification charsvisible ] ...
This shell function adds a set of captioned text fields to a parent widget. This command is useful for adding a set of captioned text fields to a RowColumn in a concise manner.

The parent is the first argument to the function, followed by any number of 4-tuples of arguments specifying the variable to contain the TextField widget handle, the label, the verification function called on the TextField widget, and the width of the TextField in number of characters.

On return, each variable contains the widget handle of the corresponding TextField widget. A variable whose name is the TextField's variable with _CAP appended holds the handle of the widget that was created.

One additional environment variable modifies the initial resources on the created Caption and TextField widgets:


$TFARGS
list of resource definitions passed to the newly created TextField widgets

confirm "message" yes-ycommand no-ncommand
fatal "message"
warn "message"

The warn, fatal, and confirm shell functions provide commonly needed functionality for popping up high priority message windows to the user. Each creates a DialogShell the first time it is called, and re-uses it on subsequent calls.

confirm displays message, and creates two buttons, YES and NO. If YES is selected, then ycommand is executed. If NO is selected, then ncommand is executed. Both ycommand and ncommand must be valid wksh commands.

The fatal function is useful in non-recoverable situations. It displays message inside a notice shell with an OK button, and exits as soon as the OK button is selected.

The warn function is useful if a non-fatal error has occurred. It displays message inside a notice shell with an OK button that does nothing.


DataOp [-prs] $widget
This built-in command prints or resets data throughout widget trees. This command is useful in a number of situations, for example, implementing quick databases, implementing property windows, and easing the implementation of the Reset and Reset to Factory buttons. This command prints or resets data in Scale, Toggle Button, and Text widgets.

The DataOp options corresponds, respectively, to the aliases:


dataprint $widget . . .
print data from widget trees. It recursively descends the $widget tree and prints to stdout a set of name=value lines that corresponds to the data stored in each data widget. The name printed is the name of the widget in question.

datareset $widget data . . .
parse and reset data to widget trees. It takes a set of pairs of widget trees and data of the same form as that printed by the dataprint command, and sets the values on all the widget trees to the named values. It error checks to ensure consistency with the name portion of the data.

-s
print data in ``short'' form. In short form, each piece of data is printed separated by the ``|'' symbol.

If any widget has the name nodata then the recursion does not descend that widget. Thus, a widget hierarchy can be designed to gather data from some subtrees and not others.


MnemonicOp [-sc] $widget
manipulate mnemonics throughout widget trees.

mnsetup $widget . . .
setup mnemonics on the widget trees The mnsetup command sets up all children recursively under $widget so that mnemonics will appear on all action widgets and captions. It first scans the entire tree of all its arguments looking for children that already have mnemonics, keeping track of them. Then it takes a second pass over the tree and finds unique single letter keys to use for the mnemonics. It uses an internal scoring system to find the ``best'' mnemonic for each item in turn, preferring letters closer to the front of each ``word'' in each string, capital letters, removing whitespace, and so on. It is possible for the command to not find a unique mnemonic, either because none exists or because finding a unique set would be too time consuming. In this case, it prints a warning to stderr.

mnclear $widget . . .
clear all mnemonics on the widget trees The mnclear command descends the $widget tree recursively and clears all mnemonics resources.

under $widget [ pixels ]

over $widget [ pixels ]

rightof $widget [ pixels ]

leftof $widget [ pixels ]

floatbottom

floattop

floatright

floatleft

spanwidth

spanheight
These shell functions add form constraints to the children of Form widgets. These functions are automatically included the first time referenced.

Each echos to stdout a set of form constraints to perform the desired action. Thus, they are most often used inside backquotes or $( ... ) in the resource list of the child be added to the form.

under (over) specify the child should be placed under (over) another child in the form. If pixels is not specified, it defaults to ``0''.

rightof (leftof) places a new child to the right (left) of another child a certain number of pixels.

floatbottom (floattop) and floatright (floatleft) make a child float along the bottom (top) edge of the form, or along the right (left) edge, respectively. They take no arguments. floatbottom and floattop may be used in conjunction with under, over, or spanwidth. Floatright and floatleft may be used in conjunction with rightof, leftof or spanheight.

spanwidth and spanheight make the child span the entire width or height of the form, respectively. They take no arguments. spanwidth may be used in conjunction with under, over, or floatbottom. spanheight may be used in conjunction with rightof, leftof, or floatright.


widlist [ -r ] [ args ...]

widlist [-R ] [ args ...]

widlist [-c ] [ args ...]

widlist [-h ] [ args ...]
list information about widgets and their resources to stdout. widlist is useful for debugging, quickly finding the exact spelling of a particular resource name, or determining what widget classes are available.

widlist, with no options, lists currently active widgets along with information about their parents, handles, name, and state. In all cases, if args is not specified, information for all widgets is listed.

The -r option lists resources for each of args, which may be either widget class names or widget handles. The -R option lists constraint resources, if any. Constraint resources are resources that a manager class widget imposes on its children. The -c option lists all available widget class names. The -h option lists all widget handles.


widload classname ...
attach customized widgets to the wksh process. To use widload, first attach a dynamic shared object file to wksh containing the widget's definition and code using the libload command (see ``C Function Access Commands'' below). Call widload giving as its arguments the class record symbol names of the widgets to attach. Create an instance of the new widget by specifying the widget name with an XtCreateWidget or XtCreateManagedWidget call. (or follow the normal wksh convention for gadgets). wksh searchs for a symbol with the correct name and considers it the class record constant to use.

When adding customized widgets, there should be String to Type and Type to String converters registered for any resource accessed by the wksh XtGetValues or XtSetValues commands that the widget uses. wksh provides enough converters to handle most Motif widget resources. The easiest way to register additional converters is to write an attachable wksh command that will do all the registration, or use the call command to call an internal subroutine written to do such initializations. Better yet, the widget should automatically register all the converters it needs when its class initialize function is invoked, then no special action is needed.


XBell [ volume ]
ring the terminal bell. volume range -100 and +100, the default is 0, which rings the bell at the server default value. The alias is bell.

XFlush
flush the X Event queue. This command is generally not needed because the queue is flushed automatically whenever the client is awaiting user input. This command is normally explicitly invoked when the program writes a message to a widget and then performs some time consuming operation. Unless XFlush is explicitly invoked, the message will not appear until the operation has completed and the client again begins processing user input. For example, to write ``Please Wait'' to a StaticText widget and then perform a long operation, call XFlush right after setting the string resource so the user sees the message immediately.

XtAddCallback $widget resource ksh-cmd
add the named ksh-command to the callback list resource on the widget handle $widget. The alias for this command is acb. The order callbacks are executed if more than one callback is registered for the named resource is undefined. It is also possible to set a callback list resource to a ksh-command using XtSetValues but all other previously registered callbacks are lost. XtAddCallback simply adds a new callback to the list.

XtCallCallbacks $widget resource
execute all callbacks that are registered with $widget on resource. The alias for this command is ccb.

XtRemoveAllCallbacks $widget resource
remove all callbacks associated with the widget's resource. The alias for this command is racb.

XtAddInput [ device ] [ ksh-cmd ...]

XtAddInput [-d file-descriptor ] [ ksh-cmd ...]
register an input source with the X Intrinsics. The alias for this command is ain. Whenever an input line is available on the named source, ksh-cmd is called one by one, and the arguments to these commands will consist of the (unquoted) line. If the ksh-cmd argument is not present, it defaults to the shell eval command. Usually a user defined function is used as the ksh-cmd.

The input source may be a device, or a fifo pipe. With the -d option, a numerical file descriptor may be named.


XtAddTimeOut $TOPLEVEL milliseconds [ ksh-cmd ...]
register a ksh-cmd to be executed milliseconds in the future. The alias for this command is ato. The ksh-cmd may be any arbitrary wksh command line. Note that the commands are executed only once, if the command should be executed again another timeout should be scheduled within the command itself. The actual resolution of the internal timer is server and operating system dependent, and a request may be rounded to the nearest time interval supported on the system.

XtAppCreateShell variable wid-name wid-class $parent [ res:value ...]
create a new TopLevelShell widget. The alias for this command is acs. variable is the name of an environment variable receiving the widget's handle. This handle can be used on other wksh command calls to operate on the widget. wid-name is the name of the widget, and is used by the X Windows System for resource defaults and other purposes. class is one of the supported wksh shell widget classes such as topLevelShell. $parent is the handle of the parent widget, the toplevel widget of the entire application. After these basic arguments, there can be any number of pairs of resources and values separated by colons.

XtCreatePopupShell variable wid-name wid-class $parent [ res:value ...]
create a new popup shell widget. The alias for this command is cps. variable is the name of an environment variable receiving the widget's handle. This handle can be used on other wksh command calls to operate on the widget. wid-name is the name of the widget, which is used by the X Windows System for resource defaults and other purposes. class is one of the supported wksh shell widget classes such as popupWindowShell or menuShell. $parent is the handle of the parent widget, the toplevel widget of the entire application. After these basic arguments, there can be any number of pairs of resources and values separated by colons.

XtCreateWidget variable wid-name wid-class $parent [ res:value ...]

XtCreateManagedWidget variable wid-name wid-class $parent [ res:value ...]
create a new widget. The alias for these commands is cw and cmw respectively. A child created using XtCreateWidget is not managed by the parent. If a child is not managed, it will not appear on the screen initially. Whether or not a child is managed can be changed by the XtManageChildren and XtUnmanageChildren commands.

variable is the name of an environment variable receiving the widget's handle. This handle can be used on other wksh command calls to operate on the widget. wid-name is the name of the widget, which is used by the X Windows System for resource defaults and other purposes. class is one of the supported wksh shell widget classes such as popupWindowShell or menuShell. $parent is the handle of the parent widget, the toplevel widget of the entire application. After these basic arguments, there can be any number of pairs of resources and values separated by colons.


XtDestroyWidget $widget ...
destroy widgets and all their children. The alias for this command is dw. XtDestroyWidget takes a list of widget handles as its arguments, and destroys them in turn. Any environment variables holding handles to the widget or their children become invalid. Most widgets also have destroyCallback resources which will be executed immediately before the widget is destroyed.

XtGetValues $widget resource:variable ...

XtSetValues $widget resource:value ...
take a widget handle and get or set resource values for that widget. The alias for these commands are gv and sv respectively. The widget handle presumably comes from a previous call to XtCreateManagedWidget, XtCreateWidget, OlInitialize, and so on.

XtGetValues takes a list of one or more resource:variable pairs and stores an ASCII version of each resource value into the corresponding variable.

XtSetValues takes a list of one or more resource:value pairs and sets resource value into the corresponding value.


XtMainLoop
go into an infinite loop processing X events. The alias for this command is ml. It would typically be the final line of an wksh script. However, while creating widgets interactively, this command can be interrupted via the Intr key on the keyboard. Thus, to make widgets display on the screen, you can use the XtMainLoop command. If something looks incorrect, hit the Intr key, interactively modify the widgets, then call XtMainLoop again.

If XtMainLoop is not executing, no X events for the application are processed, and so nothing happens on the screen in response to keyboard, mouse actions, and so on, until XtMainLoop is executed again.


XtManageChildren $widget . . .

XtUnmanageChildren $widget . . .
manage or unmanage widget children. The aliases for these commands are mc and umc respectively. These commands take any number of widget handles (presumably from a previous call to XtCreateManagedWidget, XtCreateWidget, and so on). All the widgets named in a given call must have a common parent. When a widget is ``managed'' its parent will take it into account when determining screen layout. Even if the widget is managed, it will not appear on the screen unless it is also realized and mapped. Most widgets by default are mapped when they are managed, but this behavior is controlled by a boolean resource called mappedWhenManaged.

XtMapWidget $widget . . .

XtUnmapWidget $widget . . .
map or unmap widgets. The aliases for these commands are mw and umw respectively. These commands take any number of widget handles (presumably from a previous call to XtCreateManagedWidget, XtCreateWidget, XtAppInitialize and so on). When a widget is ``mapped'' its window is displayed on the screen. In order to be mapped, a widget must also be realized and managed. If the widget has children, they are recursively mapped or unmapped as well.

XtPopup $widget [GrabNone|GrabExclusive|GrabNonexclusive]

XtPopdown $widget
bring up and down windows previously created using XtCreatePopupShell. The aliases for these commands are pu and pd respectively. XtPopup takes a widget handle, and optionally a grab type, and brings up the popup window. The default is GrabNone.

XtPopdown takes a widget handle as its argument and pops down the widget, which then disappears from the screen.


XtRealizeWidget $widget . . .

XtUnrealizeWidget $widget . . .
realize or unrealize widgets. The alias for these commands are rw and urw respectively. These commands take any number of widget handles (presumably from a previous call to XtCreateManagedWidget, XtCreateWidget, OlInitialize, or XtAppInitialize and so on). When a widget is ``realized'' its window is created on the display and final initialization of the widget is completed. If the widget has children, they are recursively realized or unrealized as well.

XtSetSensitive $widget [true]

XtSetSensitive $widget [false]
set a widget to be sensitive (true) or insensitive (false). The alias for this command is ss. This command takes a widget handle (presumably from a previous call to XtCreateManagedWidget, XtCreateWidget, OlInitialize, XtAppInitialize, and so on. When a widget is insensitive, the user is unable to interact with it. Some widgets change their visual appearance if they are insensitive as well. If the widget has children, they are recursively set to be sensitive or insensitive as well.

This command should be used rather than simply setting the sensitive resource of a widget, since this command correctly takes care of subwidgets.

These built-ins and functions are available when running wksh in Motif mode.

ListOp [-adpsgSDitbC] $widget [args]
Operations specific to the Motif List widget.

The aliases, corresponding to the options adpsgSDitbC respectively, are:


listadd $widget [-P index] [item | -f file] . . .
add new items on the end of the XmList. After the $widget argument, further arguments can either be the text of an item to add to the list, or with the -f option the name of a file each of whose lines will be added as an item to the list, or with the -P (position) option the index of an existing item which new items will be inserted after. If no -P options are given, then items are added to the end of the list. For example:

listadd $W -P 4 "Item 1" "Item 2"

will add the strings "Item 1", "Item 2" after the 4th item in the list. Item indices always start at 1. Using 0 as the index will add items to the end of the list. Using the -f option to add each line of a file to the list is a highly efficient way to maintain large lists.


listdel $widget [ index ... | all]
delete list items. After the $widget argument, the rest of the arguments are a list of indices of items to delete. Note that the indices are kept constant during the life of the command, and after the items are deleted all remaining items are renumbered so the list of indices are always consecutive and start at 1. So, the following two lines would perform the same function:
   	listdel $W 1 2
   	listdel $W 1; listdel $W 1

The first command deletes the first and second items in one operation, after which the remaining items would be renumbered. The second line deletes the first item, after which the remaining items would be renumbered, then deletes the first item again (thus deleting the second item of the original list).

You may also use the special keyword "all" instead of a list of items, in that case all items will be deleted.


listsel $widget index
causes the named items to be selected. You may use the special keyword "all" to select all items in the list.

listdesel $widget index ...
causes the named items to become deselected. You may use the special keyword "all" to deselect all items in the list.

listget $widget index ...
prints the named items to stdout. You may use the special keyword "all" to print a list of all items in order to stdout.

listgetsel $widget
prints a list of all selected items label text to stdout.

listgetselpos $widget
prints a list of all selected items indexes to stdout.

listput $widget index string ...
replaces the text of the named index item with the following argument. Any number of index/string pairs may be specified.

listbot $widget index
Scroll the named item to the bottom of the list.

listtop $widget index
Scroll the named item to the top of the list.

listchange $widget item ...
quickly remove all items and add back the new items. Faster than calling listdel and listadd separately.

TextOp [-gsrGSCaidl] $widget
Operate on the xmText widget. Aliases corresponding to each option -gsrGSCaidl are:

textget $widget
Print the text from a Text widget to stdout.

textset $widget [string]
Set the text of a Text widget.

textreplace $widget from-pos to-pos string
Replace text in a Text widget starting at index from-pos up to and including character position to-pos with string.

textgetsel $widget
print the selected text in a Text widget to stdout.

textsetsel $widget from-pos to-pos
set selected text in a Text widget starting at character position from-pos and going up to and including position to-pos.

textclearsel $widget
Clear the selection in a Text widget.

textappend $widget text
append text to the end of a text widget.

textinsert $widget position text
insert text at position, which is an integer starting at 0.

textshow $widget position
Scroll the text in a text widget so that position is in the viewing area.

textlastpos $widget
Print the index of the last position of the named text widget.

XmCreateWIDGET [-m] var parent name [res:val ...]
For every Motif widget, there is a convenience function defined to create that widget. There are also some convenience functions for creating certain commonly needed composite widget structures. All of these convenience functions take the same argument structure. The -m option, if present, indicates that the newly created widget should be immediately managed. The default is that they are not immediately managed and would require a call to XtManageWidget before showing. The var is the name of an environment variable that will receive the handle of the newly created widget. parent is the handle of the parent of the widget to be created, name is the name of the newly created widget. Any number of res:val arguments may be given that specify initial settings for resources.

There is no room here to discuss all of these commands, see Motif documentation for complete details. Here is a list of all the convenience functions currently supported by wksh, along with their aliases in parentheses:

   XmCreateBulletinBoardDialog (crtbulletinbd)
   XmCreateCascadeButton (crtcascadeb)
   XmCreateCascadeButtonGadget (crtcascadebg)
   XmCreateCommand (crtcommand)
   XmCreateDialogShell (crtdialogs)
   XmCreateDrawingArea (crtdrawinga)
   XmCreateDrawnButton (crtdrawnb)
   XmCreateErrorDialog (crterrord)
   XmCreateFileSelectionBox (crtfilesb)
   XmCreateFileSelectionDialog (crtfilesd)
   XmCreateForm (crtform)
   XmCreateFormDialog (crtformd)
   XmCreateFrame (crtframe)
   XmCreateInformationDialog (crtinformationd)
   XmCreateLabel (crtlabel)
   XmCreateLabelGadget (crtlabelg)
   XmCreateList (crtlist)
   XmCreateMainWindow (crtmainw)
   XmCreateMenuBar (crtmenub)
   XmCreateMenuShell (crtmenus)
   XmCreateMessageBox (crtmessageb)
   XmCreateMessageDialog (crtmessaged)
   XmCreateOptionMenu (crtoptionm)
   XmCreatePanedWindow (crtpanedw)
   XmCreatePopupMenu (crtpopupm)
   XmCreatePromptDialog (crtpromptd)
   XmCreatePulldownMenu (crtpulldownm)
   XmCreatePushButton (crtpushb)
   XmCreatePushButtonGadget (crtpushbg)
   XmCreateQuestionDialog (crtquestiond)
   XmCreateRadioBox (crtradiob)
   XmCreateRowColumn (crtrowc)
   XmCreateScale (crtscale)
   XmCreateScrollBar (crtscrollb)
   XmCreateScrolledList (crtscrolledl)
   XmCreateScrolledText (crtscrolledt)
   XmCreateScrolledWindow (crtscrolledw)
   XmCreateSelectionBox (crtselectionb)
   XmCreateSelectionDialog (crtselectiond)
   XmCreateSeparator (crtseparator)
   XmCreateSeparatorGadget (crtseparatorg)
   XmCreateText (crttext)
   XmCreateToggleButton (crttoggleb)
   XmCreateToggleButtonGadget (crttogglebg)
   XmCreateWarningDialog (crtwarningd)
   XmCreateWorkingDialog (crtworkingd)
These commands are not graphical in nature, instead they allow a programmer to directly call C functions from wksh. These commands support arbitrary structures to be passed to functions, pieces of memory to be accessed and modified, etc.


NOTE: As in programming directly in C, it is quite easy to cause wksh to core dump by using these features.

These features are useful for testing subroutine libraries without writing extensive C programs, or for accessing existing library functions from wksh. For example, it is not very difficult to make TLI networking calls from shell by using these functions.


call [-F] [-n] [-r] func [ arg ] ... [++] [ arg-modifier ] ...
call calls a C function with a desired set of arguments. It puts the return value of func, in hex, into the environment variable RET. By default, call returns the return value of the function. However, the -r option reverses the notion of success for the function (0 is failure, nonzero is success), and the -n option returns success if the function returns a nonnegative value.

The argument func is either the name of a C function, to be looked up in the internal table of functions, or a hex address. Due to the danger in calling a function with a misinterpreted address, a hex address must begin with ``0x''.

A maximum of 10 args is allowed and each argument is one of three types:


type/value descriptor
arg starts with an ``@''. This argument types has two parts: the type descriptor and the value descriptor. The type descriptor is the name of a 'C' data type (for example, long, struct, strbuf, char *); if the type is a structure type, the type will be considered to be a pointer to that type. The value descriptor is a legal value of this type.

number
arg starts with a number. Numerical arguments are interpreted as unsigned long integers and are parsed in that form. For example, the argument 3 is equivalent to @ulong:3.

string
arg is a string. This argument is taken directly from the command line.

Any memory allocated due to the parsing of the type/value descriptor mechanism will be freed after func has returned, unless the -F option has been given. When you need to free the structure, use strfree. (The memory for the string or number is not allocated using malloc and can not be freed or stored, it will be overwritten.)

The set of arguments, arg-modifier (often referred to as a ``overrides''), are used to change certain fields of some arguments. The form of these modifiers is:

   field subscript-expression operator=val

where:


field
refers to a field of one of the arguments. The argument number or argument type may be used to limit the search for field. If the field is left out, this implies an override for the whole first argument.

subscript-expression
optional and of the form '[integer expression]'. The type of the field must be an array or pointer type.

operator=val
may only be used if the field is an integer type. The set of operators is +, -, &, |, *, /, %, and ^, interpreted as in C. val must be a valid value descriptor for the type of the field.

cmdload cmdname . . .
attach new built-in commands to the wksh process. Create a dynamic shared object file containing the cmdname definition using the libload command. Then attach it to wksh by executing the command libload with only one argument, the path to the shared object.


NOTE: A full path to the shared object should be used if it does not reside in /usr/lib.

Call cmdload giving the arguments the names of the built-in commands as the user should type them.

For each command, a function is needed following these interfacing rules:


addbuttons Example:
This example demonstrates using addbuttons to create rectButton widgets inside an Exclusives widget. The following code would take advantage of the shell feature whereby a variable can be set just for the execution of a single command:
   cmw EX ex exclusives $TOPLEVEL
   BUTTONTYPE=rectButton addbuttons $EX \
   	"First"  do_first \
   	"Second" do_second

addfields Examples:
if $POP_UCA is the upper control area of a popupWindowShell, one can add several captioned textFields to it as follows:
   sv $POP_UCA alignCaptions:true
   addfields $POP_UCA \
   	NAME   "Name:"      :   16 \
   	ADDR   "Address:"   :  20 \
   	PHONE  "Telephone:" : 18

To put the captions above each textField, use the CAPARGS variable as follows:

   sv $POP_UCA alignCaptions:true
   CAPARGS="position:top" addfields $POP_UCA \
   	NAME   "Name:"      :   16 \
   	ADDR   "Address:"   :  20 \
   	PHONE  "Telephone:" : 18

XtAppInitialize Example:
When using Motif, use XtAppInitialize instead of OlInitialize:
   XtAppInitialize TOPLEVEL myapp Myapp "$@"

widload Example:
Using widload, for example, if a new widget whose class record symbol is fancyLookingWidgetClass is contained in a dynamic shared object named libfancy.so, the commands would be:
   libload /usr/lib/libfancy.so
   widload fancyLooking

After this, create an instance of the new widget by specifying fancyLooking on an XtCreateWidget or XtCreateManagedWidget call. If the widget is really a Gadget, then use normal wksh conventions, fancyLookingGadget in the above example.


XtCreateManagedWidget Example:
An example of a newly created managed child widget using XtCreateManagedWidget:
   XtCreateManagedWidget TEXT1 text1 text $PARENT \
   	value:"hello world"

XtGetValues and XtSetValues Examples:
   XtGetValues $TEXT value:S width:W

would store the current string resource into the environment variable $S and the current width into the variable $W.

   XtSetValues $TEXT value:"Hello World" background:Yellow

would set the current string resource to the string ``Hello World'' and the current background color to Yellow.


call Examples:

call Example 1:
       call malloc 1024	# Allocates a buffer
       BUF=$RET	# Stores pointer in BUF
       echo $BUF
   

RESPONSE: 0x4581568 # Note that BUF is a pointer

call strcpy $BUF 'hello world' # Copies string into BUF call altprintf '%s ' $BUF # Print the contents of BUF

RESPONSE: hello world

call free $BUF # Frees the buffer


call Example 2:
       call strdup 'a:b:c'	# mallocs space for a:b:c
       BUF=$RET
       call strtok $BUF :	# breaks up string by :
       while true
       do
           P=$RET	# set P to current segment
           call altprintf '%s
       ' $P	# Print out current segment
           if call strtok 0 :	# see if the return is 0
           then
               break	# break if it is
           fi
       done
       call free $BUF
   

This will print out:

a b c


call Example 3:
Suppose you have declared (see struct, typedef)
       typedef struct hello {
           int x;
           int y;
       } hello_t;

you can say

   call hellofunc @hello_t:{1,30}

and get a POINTER to a structure of type hello passed to hellofunc.


call Example 4:
Suppose you have declared:
       struct sub {
           int subsubx;
       };
       struct sub {
           int subx;
           struct subsub *suby;
       };
       struct top {
           int x;
           struct sub y;
       };

call strprint top '@top:{1,{2,{3}}}'

   RESPONSE: { x=1, { subx=2, {subsubx=3 } }

Using an argument modifier:

call strprint top '@top:{1,{2,{3}}}' ++ subsubx=4

   RESPONSE: { x=1, { subx=2, {subsubx=4 } }
Or, alternatively (they all do the same thing):
   call strprint top '@top:{1,{2,{3}}}' ++ 2.y.suby.subsubx=4
   call strprint top '@top:{1,{2,{3}}}' ++ y.suby.subsubx=4
   call strprint top '@top:{1,{2,{3}}}' ++ y.subsubx=4
   

RESPONSE: { x=1, { subx=2, {subsubx=4 } }


define Example:
   define X 1
   define -R X 2
   call strprint -p long '@long:X'
   

RESPONSE: long=1(0x1)


deflist Example:
   #include "my.h"
   #include "exksh.h"
   

struct symarray Mydefines[] = { { "MYVAL", MYVAL }, { "MYOTHERVAL", MYOTHERVAL }, { NULL, 0 } };

In a script, you can then say:

   deflist Mydefines

deref Example:
   # Output is for an intel 386 machine
   

call strdup "hi there" # Allocates a duped pointer BUF=$RET # Stores pointer in BUF deref -9 $BUF aaa echo $aaa deref -l -9 $BUF aaa echo $aaa

RESPONSE: 0x686920746865726500 # hex equiv. of "hi there" 0x742069686572656800000000


field_comp Example:
   struct strbuf maxlen:int len:int 'buf:char *'
   call malloc 4096	# Allocate a character buffer
   buf=$RET	# Store its pointer in buf
   call -F nop "@strbuf:{4096, 0, p$buf }"	# Allocates a strbuf
   strbuf=$RET	# Store pointer in strbuf
   call getmsg $FD $strbuf 0 0	# Call getmsg with the strbuf
   field_comp strbuf $strbuf len=4	# Before going on, make sure
   	# the len is 4

field_get Example:
   struct strbuf maxlen:int len:int 'buf:char *'
   call malloc 4096	# Allocate a character buffer
   buf=$RET	# Store its pointer in buf
   call nop "@strbuf:{4096, 0, p$buf }"	# Allocates a strbuf
   strbuf=$RET	# Store pointer in strbuf
   call getmsg $FD $strbuf 0 0	# Call getmsg with the strbuf
   field_get strbuf $strbuf len	# See the value of len

At this point, the length field is printed to stdout.


symbolic Examples:

symbolic Example 1:
   struct mine a b c
   define MY_VAL1 1
   define MY_VAL2 2
   symbolic -t mine.a -t mine.c MY_VAL1 MY_VAL2
   call -F nop '@mine:{MY_VAL1, MY_VAL2, 2}'
   ptr=$RET
   field_get mine $ptr .
   

RESPONSE: { a=MY_VAL1, b=2, c=MY_VAL2 }


symbolic Example 2:
   struct mine a b c
   define MY_VAL1 1
   define MY_VAL2 2
   symbolic -m -t mine.a -t mine.c MY_VAL1 MY_VAL2
   call strprint mine '@mine:{3, MY_VAL2, 2}'
   

RESPONSE: { a=MY_VAL1|MY_VAL2, b=2, c=MY_VAL2 }

References

ksh(1)

In addition, the Motif manual pages are essential for programming graphics using wksh, and the Xt Intrinsics Toolkit Reference Manual is also very helpful.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004