NAME
output_window - window to display data
PROTOTYPE
unitptr output_window( int n, char *pcWin, char *pcFmt, unitptr uHost)
ARGUMENTS
- int n
- number of input parameters to be displayed
- 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 coordinates ((0,0) corresponds to the lower left screen corner), and width, height specify the size of the window in pixels.
- char *pcFmt
- character string specifying what is displayed in the window (see below).
- unitptr uHost
- host unit for newly created instance
RETURN VALUE:
- unitptr u
- pointer to newly created unit
INTERFACE OF CREATED UNIT:
- X_in[n]:
- (input field 0) vector containing
parameter values to be displayed.
DESCRIPTION:
Creates a unit that provides a window for data
display. The initial position, size and the title
of the window are specified with the first argument string pcWin.
The layout of the window (i.e., any displayed text
and widgets for data entry and display) is determined by a
format string pcFmt and follows a similar scheme as used
for the familiar printf function.
The format string pcFmt is composed of zero or more directives:
ordinary characters (not % ) which are copied unchanged into
the display window that is provided by the created unit;
widget specifications, each of which results in creating
a widget (such as a field for data display);
or options that modify properties of
existing widgets or of the entire window. Each widget
specification or option is
introduced by the character %. For a description
of the available widget specifications, see
section WIDGET SPECIFICATIONS below. The available
widgets include widgets for numeric data display,
areas into which the output of other
NST window units may be redirected and a single type
of `return button'' to block the display.
INTERFACE OF THE CREATED UNIT:
The created unit will have zero or more input fields with
a suitable number of pins to hold any data values belonging
to the display widgets.
There are alway two additional fields:
- EPS_in[1]
- (next to last field): determines blocking behavior (see
BLOCKING MODES below)
- CTL_in[1]
- (last field; control field): a value of 0 skips
operation of this unit.
WIDGET SPECIFICATIONS:
Basically, the interpretation of the format string pcFmt
is modeled after the use of the format string in the
printf function of the C-language. I.e., any text in pcFmt is
simply printed into the window, with the exception of format
directives that start with a % and that are interpreted
in a special way: these portions will be missing in the displayed
text and define things like line breaks (effected by the format field
%n), general options (such as %H, that 'hides' the window
until it is executed), or the insertion of 'widgets' for
data display (such as %f for a float value) that will occur in the
running text at the position where the format directive was
encountered. Display of the characters following a widget specification
will continue at the next character position behind the displayed widget.
In addition, the line spacing will be automatically adjusted so that the
available vertical space in the window is fully used.
Format of a widget specification:
Each widget specification is of the form %a:b:c:dC, i.e. starts with
a %-character, followed by zero to four numeric arguments
a...d which must be separated by colons. Each of these four arguments
may be an arithmetic expression that evaluates to a floating point number.
An additional requirement is that the entire widget specification may
not contain any spaces.
Repetitions of a Widget group:
The special repetition directive
%a:b{head%|body%|tail%}
will be expanded into b (=lines) groups of a repetitions of
the central part body, with head and tail prepended/appended
to each such group. Additionally, any occurrence of the special
tokens $R ("row nr") and $C ("column nr") will be replaced
by corresponding row and column nrs indicating the current
position in the resulting a*b matrix layout.
If only a is given, b=1 will be assumed.
Example:
%a:b{$R:%| el[$R,$C]%| %n%}
will for a=2, b=3 become expanded into
0: el[0,0] el[0,1] el[0,2] %n1: el[0,0] el[0,1] el[0,2] %n
If only a single or no %| is given, the corresponding
directives will be read as %a:bbody%|tail% or %a:bbody%.
All remaining widget specifications are delimited by a single command character
(here indicated by a C') that specifies the type of the widget
directive.
- a:bv
- insert decimal representation of parameter value
taken from next input pin (starting with pin 0 for
the first %f directive in pcFmt ), using field width
of a characters and b decimals. If a is negative,
the inserted decimal value will be leftadjusted, with an
optional sign or a blank, if the sign is positive.
- a:bf
- the same as %a:bf
- %n
- Insert line break
- %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.
- %>
- 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.
- %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.
- %i:j~
- similar, but temporarily merges columns i...j into
- %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.
- %#
- rest of line is comment (this allows to
embed comments within complex format strings)
- %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.
- %wt
- display text in a field w characters wide.
Each %t field gives rise to a text field with a
single text input pin. The first such field will appear
after the numeric input field 0.
The order of text input fields follow the
order of %t directives.
- %w:ht
- similar as %wt, but yielding wxh text area
for display of up to h lines. The text area will
appear as a "sunken" rectangle with darker background color.
Lines that are too long are clipped. If there are more than
h lines, only the first h lines will be visible.
- %^
- make previous %w:ht text widget scrolling, i.e., each exec_unit
will append the current input and scroll the window contents,
if necessary.
- %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.
- %!name
- make the previous named area (cf. below)
into a callback trigger for a named unit name.
The unit name will be executed once whenever
the mouse pointer enters the named area.
- %!!name
- dito, but name will be executed continuously while the
mouse pointer is within the named area.
- %!!!name
- dito, but name will be executed once whenever
the mouse pointer leaves the named area.
- %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.
- %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.
The named area has w*z pixels width
and h*z pixels height, unless the last form is used,
in which width and height are in character units.
The third parameter z is an optional zoom factor
(default=1). The optional parameter a is a value
between 0 and 1 and specifies the vertical alignment
of the named area, if its height w*z is not an integral
multiple of the line spacing ( a=0 puts all fractional
space above, a=1 below the named area; a=0.5 leads
to vertical centering). A named area can be used to display
the output of another window unit if its name name
is specified for the window title parameter of the other unit.
The named area indents' the current left margin by the width
and height required to cover the named area with a rectangle
of letters. Thus, a line break %n will return to the old left
margin only after the vertical height of the named area has
been used up. To do this in a single step, requires to use
the paragraph break %p.
BLOCKING MODES:
The default behavior for exec_unit(u) for this unit is to
display its inputs and to block only if
there is a %R or %X button (in this case, execution will
continue when the button is pressed).
EMBEDDING OF OUTPUT WINDOWS IN NAMED AREAS:
An output window can be embedded in a named area of
an input_window unit; this allows to combine input
and output in a rather flexible way (cf. input_window ).
SEE ALSO:
input_window
FILE
/homes/jontrup/nst5/man/../o.sol2//../nstsrc/nst_scrn.c