wksh(1) wksh(1)
NAME
wksh - Windowing Korn Shell, graphical extensions to ksh
SYNOPSIS
wksh [-mode] [_aefhikmnprstuvx] [_o option] . . . [-c string]
[arg . . .]
DESCRIPTION
wksh (Windowing Korn Shell) 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 (a superset of OPEN LOOKO), and OSF Motif
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 that 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.
Copyright 1994 Novell, Inc. Page 1
wksh(1) wksh(1)
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 that 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:
Copyright 1994 Novell, Inc. Page 2
wksh(1) wksh(1)
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:
Copyright 1994 Novell, Inc. Page 3
wksh(1) wksh(1)
Variable Default if not set Use by wksh
_______________________________________________________________
WKSHLIBDIR /usr/X/lib/wksh Directory where convenience
functions, examples, etc.
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
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.
Copyright 1994 Novell, Inc. Page 4
wksh(1) wksh(1)
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.
Callback Convenience Variables
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.
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
Copyright 1994 Novell, Inc. Page 5
wksh(1) wksh(1)
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.
Widget Set Independent Graphics 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
Copyright 1994 Novell, Inc. Page 6
wksh(1) wksh(1)
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 variables modify 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.
Copyright 1994 Novell, Inc. Page 7
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 8
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 9
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 10
wksh(1) wksh(1)
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 . . .]
Copyright 1994 Novell, Inc. Page 11
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 12
wksh(1) wksh(1)
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 . . .
Copyright 1994 Novell, Inc. Page 13
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 14
wksh(1) wksh(1)
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,
Copyright 1994 Novell, Inc. Page 15
wksh(1) wksh(1)
OlInitialize, XtAppInitialize, etc. 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.
Motif Graphical Commands
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
Copyright 1994 Novell, Inc. Page 16
wksh(1) wksh(1)
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.
Copyright 1994 Novell, Inc. Page 17
wksh(1) wksh(1)
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.
Copyright 1994 Novell, Inc. Page 18
wksh(1) wksh(1)
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 po-
sition 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 cer-
tain 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)
Copyright 1994 Novell, Inc. Page 19
wksh(1) wksh(1)
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)
C Function Access Commands
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 that 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
Copyright 1994 Novell, Inc. Page 20
wksh(1) wksh(1)
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.
Copyright 1994 Novell, Inc. Page 21
wksh(1) wksh(1)
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 that 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.
Copyright 1994 Novell, Inc. Page 22
wksh(1) wksh(1)
For each command, a function is needed following
these interfacing rules:
the name of the function must be the same as
the name of the new built-in command,
prepended with b_
the arguments to the function are int argc
and char *argv[], the same kind of arguments
used for a main function. As usual, argv[0]
is set to the name of the command, the rest
of the arguments are the strings the user
passed down on the call.
the function should return int, return 0 on
success and nonzero on failure
in the current version of wksh, stdin of the
command cannot be read, get information
through the argument list
to print to the command's stdout, use
altprintf instead of printf, use the same
arguments as printf
some provided functions allow access to wksh
environment variables or execute other shell
command lines
int altprint(char *format, type arg, . . .);
use this rather than printf
void env_set(char *name=value);
set the name environment variable to
value
void env_gb1(char *name=value);
set global environmental variable name
to value
void env_set_var(char *name, char*value);
same as env_set
char*env_get(chap *name);
get the current value of name
environment variable
Copyright 1994 Novell, Inc. Page 23
wksh(1) wksh(1)
char * env_get_gbl(char *name);
get the current value of name global
environment variable
Widget handle_to_widget(char *arg0, char *handle);
return the widget identifier of a
handle
void ksh_eval(char *command);
evaluate command
define [-R] name value
add a new #define to the list. name
should be a valid 'C' define name;
value must be an integer value.
If name has already been defined, and
the -R option is present, the value
will not be re-assigned.
deflist [[-p]name] address
add a new list of #defines to the
define list. These lists are sets of
name/value pairs represented by
structures of type symarray,
preferably sorted.
struct symarray {
const char *str;
unsigned long addr;
};
address address of an array of
symarray structures
name tag for this set of define's
deref [-p] [-l] [-len] address [shell-
variable]
read the contents of a pointer. deref
will show the contents of the pointer,
address, in hexadecimal, either byte-
by-byte (where each byte is
represented by a pair of hex digits)
or long-by-long. By default, the
output is long-by-long, with only the
first long being printed. If the -len
Copyright 1994 Novell, Inc. Page 24
wksh(1) wksh(1)
option (where len is an integer) is
supplied, then the output is byte-by-
byte for len bytes. If the -l option
is supplied, the output will be
printed long-by-long. Note that the
long-by-long output can look very
different based on the machine's byte
ordering.
The -p option will cause the output to
be printed on the standard output,
otherwise, the output will be placed
in shell-variable. If shell-variable
is not supplied, RET will be used.
field_comp type address [criterion] . . .
compare internal data at address of
the designated type against criteria
supplied to the command. These
criteria are of the form:
field=value.
type type descriptor
address address descriptor
field a field of type
val a legal value for field's type
field_get [-v shell-
variable] type address [field-
name] . . .
print internal data at address, of the
designated type, selecting fields
supplied to the command. field-name
must be a valid field name or a '.'
for the whole value.
If shell-variable is given, the output
will be put in the environment;
otherwise, it is printed to stdout.
finddef defname [shell-variable]
find the value of a #define, (see
deflist and define). It should not be
Copyright 1994 Novell, Inc. Page 25
wksh(1) wksh(1)
necessary to use this function
frequently, since the parser will
substitute the value while parsing.
finddef places the value in shell-
variable, or, by default, RET.
findsym symbol-name [shell-variable]
find the address of a symbol in the
running process.
libload [[-p] name] object-name
libload [[-n] name] object-name
access a needed shared object. If the
architecture does not support dynamic
shared objects nothing is actually
loaded.
name the object. If there is a
symbol accessible by the name
name_libinit or libinit_name,
this function will be called.
sizeof typename [shell-variable]
find the size of a C type.
struct [-R] name fld[:type] . . .
declare a structure, name, with fields
fld. If type is not present for a
field, the type is assumed to be long.
If name has already been defined, and
the -R option is present, the value
will not be re-assigned.
symbolic -m -
t type[.field] . . . symbolic . . .
associate symbolic names with a
designated type or a field of a
structure of this type. symbolic must
be #define's declared earlier. Any
type assigned symbolic values must be
of an integer valued type. The -m
option causes each value to be
considered a mask and the set of
values on output should be separated
Copyright 1994 Novell, Inc. Page 26
wksh(1) wksh(1)
by | symbols.
typedef type typename
declare new types. type must be a
valid type descriptor. typename is
the name of the type being defined; it
must be a valid identifier.
dbpr level command
execute command if the variable DEBUG
is greater than or equal to level.
decl type var
declare an environment variable as
representing a pointer to the
designated C type.
findxsym symbol-name
use nm to find symbol. This is only
necessary for static variables.
free var
free the memory of a previously
allocated and declared environment
variable representing a C data
structure.
getaddr symbol-or-address
put the address of the expression into
RET, like getaddr.
help [function]
print out a designated shell function
or all, sending the output through pg.
iset var val
set value of integer variable to new
value.
kload [-f function-array] [-a alias-
array] [-v var-array]
read in an array of built-in
variables, aliases or functions.
Copyright 1994 Novell, Inc. Page 27
wksh(1) wksh(1)
malloc count var
allocate space using malloc(3C) and
put the pointer in var.
new @type:value var
use call to allocate a data structure
and put the pointer into the named
variable.
newfree var
free a data structure allocated by
new.
prctl [-v prvar] [-p] [-
d symbol . . .] [type]
control the output of
strprint/field_get. The -v option
allows capturing the output in a
variable, if there is output. The -p
option forces the current setting to
be output. The normal reset form
allows the specifying of print
conventions (names: field names are
printed, hex: integer output is in
hex, dec: integer output is in
decimal). The -d option allows for
passing the output captured with a
previous prctl back in as input.
symbol can be PRSYMBOLIC, PRHEX, and
so on. By default, the output setting
is PRSYMBOLIC|PRMIXED|PRNAMES (output
will use symbolics when available,
will print both hex and decimal for
integer values and will print field
names within structures).
revreturn command
reverse failure return codes.
function] type [type] . . .
set_special [-f free-function] [-P print-
function] [-p parse-
designate a new parse, print or free
function for a data type.
Copyright 1994 Novell, Inc. Page 28
wksh(1) wksh(1)
setargs arguments
take out overrides from list of
arguments and put them in specargs
array.
Examples
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
Copyright 1994 Novell, Inc. Page 29
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 30
wksh(1) wksh(1)
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 } }
Copyright 1994 Novell, Inc. Page 31
wksh(1) wksh(1)
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
Copyright 1994 Novell, Inc. Page 32
wksh(1) wksh(1)
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 the
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 }
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
Copyright 1994 Novell, Inc. Page 33
wksh(1) wksh(1)
/usr/X/bin/wksh bootstrap executable file for
wksh
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.
Copyright 1994 Novell, Inc. Page 34