NAME

PROTOTYPE

ARGUMENTS

int n

If n>0, output field X_out will consist of n output pins. In this case, the first n of the numeric input widgets specified in argument fmt for output field 0 (see below) will send their values to these pins (and it is the responsibility of the user to choose n sufficient). If n=0 (the recommended value), the necessary number d of pins of output field X_out will be determined automatically from fmt.

char *pcWin

character string specifying title, position, and size of window. General format: "title xll yll width height", where title is an arbitrary sequence of characters not containing any white space, xll, yll is a pair of integers specifying the location of the lower left corner of the window in pixel coor- dinates ((0,0) corresponds to the lower left screen corner), and width, height specify the size of the window in pix- els.

char *pcFmt

character string specifying what is displayed in the window and how data may be entered through "widgets" (see below).

unitptr uHost

host unit for newly created instance

RETURN VALUE:

unitptr u

pointer to newly created unit

SYNOPSIS:

INTERFACE OF THE CREATED UNIT:

Input Fields:

in_0[1]

determines blocking behavior (see BLOCKING MODES below)

in_1[1]

control field; a value of 0 skips operation of this unit.

Output Fields:

EXECUTION OF CREATED UNIT:

WIDGET SPECIFICATIONS:

Format of a widget specification:

Types of widget specifications:

0.

option (command character from l,{,},H,h,k,<,' )

1.

non-valued widget specification (command character from =,^,v,R,X,n,p,x),

2.

numeric valued widget specification (command character from b,B,c,C,d,D,f,F,g,G,i,I,j,J,s,S)

3.

text valued widget specification (command character from i,I,j,J, f,F,g,G,t,T).

Column-wise organisation of widgets:

Repetitions of a Widget group:

     %a:b{head%|body%|tail%}

Example:

     %a:b{$R:%| el[$R,$C]%| %n%}

    0: el[0,0] el[0,1] el[0,2] %n1: el[1,0] el[1,1] el[1,2] %n

I. Widget options:

%n

Insert line break. If a line contains text widgets with height>0, the next line will be below the deepest text widget, so that new items won't collide with the area of any widget on the previous line.

%p

Insert paragraph break: skips below the current indentation caused by a preceding named area (cf. below). Without a named area, effect is the same as for a line break.

%i~

( number i followed by tilde character) switch to column i: any text or widgets always fills a a particular column (initially, the leftmost column 0). After a %i~, any further material will put into column i. Columns can be filled in any order and grow in width and height according to the added items. At the end, the final widget layout will be the juxtaposition of all filled columns, aligned by their upper borders. A %i~ always ends the current line, before switching to the new column i.

%i:j~

similar, but temporarily merges columns i...j into a single, wider column to allow text lines to span several columns. If the width of a textline exceeds the sum of all column widths in the range i..j, the rightmost column j will be enlarged by the required additional width. A %i:j~ always ends the current line, before switching to the new columns i..j.

%f<

Add all following numeric pins to output field f (if a non-consecutive set of output fields is specified in this way, the intermediate, unspecified output fields will be created with zero pins).

%>

flush following items of current line to the right (but trailing blanks between the rightmost item and the %n will be retained as a right margin)

%a>

if 0<a<1: as before, but shift items only by a fraction of a<1 of the maximal possible amount (i.e., for centering use %0.5> ). If a>=1: insert a blanks (can also be used to enforce a minimal column width).

%k

keep all text outputs in a single output field instead of a separate output field for each text output. The single text output field will have three pins for each text output. The first pin is of type STRING and holds the null-terminated text string, the remaining two pins are of type SCALAR float and hold the cursor position in the viewable text rectangle (specified as position=column+line*linewidth; the top left char in the text window has column=0,line=0) and the offset of the cursor with respect to the first character of the entire text.

%H

('Hide'). Defer opening of window until first execution call.

%h

('Hide firmly'). Defer opening of window until first ctrl_unit(NST_W_OPEN,u) call and automatically close window after execution.

%ah

('syntax hint'). Define syntax coloring of next text window according to syntax with number=a. Allowable syntax numbers are found in nst_aux2.h.

%[,%]

parenthesis to group a number of buttons into a group of which at most one member may be 'On'. If the user attempts to change a second button of the group to 'On', any other button of the group that is 'On' will be set to 'Off'. The parenthesis may enclose any other items of the format string. This does neither affect these items, nor the definition of the group. Several non-overlapping groups may be defined, however, no nesting of groups is supported. Note that grouped buttons can distinguish on-off and off-on callbacks (while ungrouped buttons do not). Therefore, single grouped buttons may be useful when on-off and off-on state changes need separate callbacks.

%![,%]

similar, but now a button in the group that is "On" can only be reset to "Off" by pressing another button in the group: If the group was initialized with one button on, this guarantees that always exactly one button in the group will be on.

%#

rest of line is comment (this allows to embed comments within complex format strings)

II. Non-valued widgets:

%R

('return button') Creates a button labelled OK but without an associated value (the label can be overriden with the %l specifier, cf. below). A window with this button will block until this button has been pressed.

%X

same effect as %R, but with automatic closing of the window after the button was pressed.

%z %az

insert "zoom button", initialized to "on". Such a button always terminates the current line (i.e., contains an implicit %n). When a zoom button is switched "off", the next a lines of the GUI (if only %z is given, all lines between this and the next zoom button) will become hidden in a "fold" until the button is switched to "on". The window will shrink with the upper edge kept fixed. %0z and %-az is like %z and %az, but with the button initialized to "off". Zoom buttons can be labelled with a %l option in the same way as the other buttons (described below) and can also trigger callbacks (cf. below).

%Z %aZ

as before, but now the window will keep the position of the lower edge fixed under size changes and the pointer will be warped to the new position of the button.

%a^

add a vertical scrollbar of a characters width to the preceding text ( %t-) widget.

%a:bv

insert decimal representation of current setting of previous slider (ignored, if no such slider exists). Use field width of a characters and display b decimals (default values are a=7,b=3).

%wl

insert a horizontal ruler that is w characters wide. If w=0, the ruler will extend to the right margin. If w<0, the ruler will stop -w characters before the right margin. (if w is absent, the command is interpreted entirely different: it then introduces a label for a previous button widget, cf. below).

%!name

make the previous widget into a callback trigger for a named unit name. If the previous widget is a named area, entering the area with the mouse pointer will trigger the callback. If the widget is a is a text field, button, zoom button or a slider, any change to its value will cause unit name to be executed once. An exception are buttons in a %[..%] or %![..%] group: they trigger only when going "on" (this also applies to the additional forms shown below. Callbacks of textfields with illegal content are not called. The forms below can be used to transmit the changed value to unit name: The name "*" (a single asterisk) can be used as a shorthand for the name of the previous callback name (this applies also to the alternate three forms below). More than one named unit can be executed, when name is specified as a comma separated list of the names of the units. Alternatively, several callback tokens can follow after a widget.

%f:i!name

whenever previous widget changes its value, the new value is copied into field f, pin i. of named unit name; then, unit name is executed, after which control returns to the present unit (for a named area, the arguments f and i will be ignored).

%f!name

as above, but copies the entire (numeric) field of which the previous numeric widget's pin is a member into into field f of named unit name (the fields must be compatible).

%!!name

similar as above, but for repeated execution of name: if the associated widget is a named area or button or zoom button, the unit name is executed repeatedly as long as the mouse pointer is within the named area or the button is 'on' (between execution calls, the status of the other widgets is processed, so that several buttons can control several named units 'simultaneously). If there is no associated widget (e.g., when %!!name appears before any other widgets), name will be executed repeatedly while the input window is active. The other forms %f!!name and %f:i!!name are analogous to the above. NOTE: when %!!name appears after a named area, the named area is then no longer considered as not belonging to the input_window and the named unit(s) name are called repeatedly as long as the cursor is inside the named area.

%!!!name

if the widget is a %[..%]-grouped or %![..%] grouped button or a zoom button, name will be executed once when the button makes the transition off->on. For a named area, the callback is triggered when the cursor leaves the area. For text fields the callback is called once the focus leaves this field. For all other widgets there will be no effect.

%a?name

info button labelled name. When pressed, one of the routines (the a-th, or 0-th, if a is absent) previously registered with nst_register_help_cmd() will be called, and the string name will be passed as its main argument. The button can be relabelled with a subsequent %lotherlabel (without changing the argument string name for the called routine). Info buttons have no output pin associated with them.

Note:

%w:h:z:a=name

insert a 'named area' of name name to accommodate the output of another window unit, if its output is monochrome or color map. If only %=name is given, the named area is interpreted differently, cf. %w:h:z==name below.

%w:h:z:a=:name

insert a 'named area' of name name to accommodate the output of another window unit, if its output is RGB.

%w:h:z:a=::name

insert a 'named area' of name name to accommodate the output of another window unit, if its output is RGB-3d.

%w:h:z==name

insert a 'named area' of name name to accommodate the output of an output_window unit. In this case, w and h specify the size of the named area in characters. If only %=name is given (i.e., if the parameters w, h, z and the second '=' are absent), this is taken as a shorthand for choosing the size of the named area to be the same as for a float entry field. If the third parameter z is present and has value 0, this will suppress an otherwise drawn frame around the named area (in the %=name - case, this effect can be achieved by specifying the second '='). NOTE: if text lines appear to overlap, this may indicate that the embedded output window needs more lines than were specified (.%n newlines count!)

a:b:c:dC

with C=i,j for integer values and C=f,g for decimal floating point values. The j,g versions accept also a blank input (mapped to the numeric value -NST_HUGE), while the i,f versions don't. If none of a..d is specified, the default input range will be -NST_HUGE..NST_HUGE and the preset value is zero. If only a is specified, the input range is the same, and the preset value is a. If a and b are specified, the input range will be the interval between a and b, and the preset value will be a. If a,b and c are specified, the input range will be as before, but the preset value will be c, if c is contained in the input range. Otherwise the preset value will be a or b, whichever is closer to c. Finally, if in addition d is specified, it will set the total field width (in characters). A value of d=0 switches to a default field width of 10. The specified field width will remain in effect also for all subsequent numeric text input fields (separate widths are maintained for the integer and the floating type fields) until a new width is specified. Note that the entered data can be accessed in two ways: 1. as numeric value at a pin of output field out_0 (unless the %< option is used to select a different field) and 2. as a text string in some output field out_i, (i>0).

%a:b:c:ds

If the next character is not a hat (.^) char, this specifies the creation of a horizontal slider, otherwise, it will specify a vertical slider. The extent of the slider is given by the fourth argument d and will be in characters, if d>0, or in pixels, if d<0. The associated floating point value will be from the interval [a,b]. If none of a..d is specified, the default input range will be the unit interval [0,1] with a preset value of zero. If only a is specified, the input range will be the smallest interval containing the values 0,1 and a, and the preset value will be given by a. If a and b are specified, the input range will be the interval between a and b, and the preset value will be a. If a,b and c are specified, the input range will be as before, but the preset value will be c, if c is contained in the input range. Otherwise the preset value will be the a or b, whichever is closer to c. If no width d is given, the slider will have the same extent as the previous slider or named area, or d=0 is assumed, if it is the first slider. A value of d=0 makes the slider autosize its extent. There may be at most one autosize slider per line (but multiple sliders with a specified with are allowed). All autosize sliders of a window will be vertically aligned and use the largest common width such that each autosize slider still fits on its line. The numeric value of a slider can be displayed using a %v-specification.

%a:b:c:wb

%a:b:c:wd

Both of these specify the creation of a rectangular button for choosing between two (the default) or more numeric values. If at least two values a,b are specified, the first will correspond to the value returned when the button is off, the second to the value when the button is on. The initial setting of the button is off, unless a third argument c is specified, the value of which (either a or b; if c is not from the set {a,b}, the closer one of the two values a,b is used) then determines the initial setting of the button. If no arguments are specified, the default values are taken as a=0,b=1,c=0. If C=b the state of the button will be preserved between successive uses of the window. If C=d, the button will always be reinitialized to the preset setting, when the window is used again. If argument w is provided, the currently used width for a button will be changed to w. w=0 specifies the default width of 10 characters. To label a button with the text pqr..s (which must be a character sequence of maximal length w uninterrupted by white space), append the sequence %lpqr..s after the type characer of the button to be labeled (example: \.%b%lexit for a 0-1 button labeled "exit").

%c

insert "close" button. Similar to the previous d-button, but operation of this button will also exit and close the window.

%w:h:x:yt

Inserts text input field of which a rectangle of width w and height abs(h) is visible. For h<0, the window will have additional small buttons for interactive vertical resizing (within the range given by its maximal useable height H, which is abs(h)+y, unless y<0, cf. below). Each line will be of length w-1+x (the last character position is reserved for the cursor, therefore the useable number of characters is one less than the actually provided space). If y>0, H will be the maximal useable number of text lines (longer texts will be clipped). If y<0, H will only set a minimal height H=abs(h)+abs(y) and the actual text height is allowed to grow from H as needed when more lines are added (it will again shrink down to H, when lines are removed again). The visible rectangle will scroll with cursor movements. If x and/or y are not specified values of zero are assumed and the visible rectangle coincides with the entire text window. The remaining default values are w=10,h=1. If the window format does not contain a %k directive, the text is available at pin 0 of the associated output field, and pin 1 will hold the cursor position in the viewable text rectangle (specified as position=column+line*linewidth; the top left char in the text window has column=0,line=0), and pin 2 will hold the offset of the cursor with respect to the first character of the entire text. Otherwise (presence of a %k directive), the text input field will add three such pins to a single output field that is shared by all text outputs. For syntax selective coloring, precede the %t directive with a %ah syntax hint directive, where the integer a must specify the coloring scheme ( cf. %ah directive documentation).

%w:0t

Special case of the above: make a text field of width w for password entry (the specified height of 0 will cause the field to echo any character with a '*' symbol).

%w:h:x:ym

like %w:h:x:yt (i.e., text window), but the contents cannot be edited interactively. However, initialization with the %..%% directive or via text output pins is possible in the same way as for a normal text window.

%w:h:n:mA

text field to access directory. This will insert a non-editable text field of width w and height h that shows a listing of the directory that is specified in the first line of the text field (the text field may be initialized with the % and % brackets, as any other text field. If h<0, the window will be vertically resizeable with a maximal height of abs(h). If no initialization is made, the default is the current directory. Subdirectories in the listing are indicated by a trailing slash and their selection will replace the currently specified directory and display a new listing of the selected subdirectory. To move into the parent directory, select "../". Additionally, if n is given and non-zero, selection of a file or directory in the present text field will copy the selected file name or directory name into the n-th successor text field (if n>0) or into the n-th predecessor text field (if n<0), provided such text field exists. There, the file name can be edited and used as if it were normal input. Additionally, if m is given and non-zero, a further text field at offset m is searched for a filter string. This filter string will be used to display only a subset of the directory files (only file names are filtered; directories are always shown). NOTE: the setting of the current directory of the running process is not affected by these operations.

%e,E,m,M

Reserved for future extensions.

SETTING FONTS:

   %Font=fontname

    %!<em>
    %!<nl>

SETTING COLORS:

   %!<colorname>

EDITING IN INPUT FIELDS:

Ctrl-A,E:

goto begin/end of line

Ctrl-B,F:

one letter backward/forward

Ctrl-U,D:

one letter upward/downward

Ctrl-K:

kill line (into paste buffer)

Ctrl-L:

kill entire text (into paste buffer)

Ctrl-C:

copy selection into paste buffer

Ctrl-V:

insert (and empty) paste buffer at cursor

Ctrl-W:

jump to matching delimiter

Ctrl-H:

backspace erase

Ctrl-R:

delete current char

Ctrl-T,Z:

goto top/bottom of text

Ctrl-X:

kill selection (into paste buffer)

Ctrl-Y:

yank paste buffer

BLOCKING MODES:

   mode entry condition -------- exit condition
   -----------------------------------------------------
   -1 ---- always FALSE ---------- always TRUE --------
    0 ---- always TRUE --------- inputs completed ----
    1 --- window is open -------- inputs completed ----
    2 window is open AND mouse - inputs completed ----
       cursor is within window
    3 ---- as before --------- inputs completed OR mouse
    ---------------------------- cursor leaves window -
    4 ---- as before -------- mouse cursor leaves window
   -----------------------------------------------------

CONTROL MODES:

EXAMPLES:

     pcFmt="b s n 4< c 0<i n t2<f"

SEE ALSO:

FILE