The ClearWin+ function winio@ has the following form:
where the ellipses ... represents a list of arguments whose length depends on
what appears in the character variable format. The character string is
called a format string. The list must only contain arguments of type
INTEGER, DOUBLE PRECISION, CHARACTER or EXTERNAL functions.
At its very simplest, winio@ may be used to display information:
DOUBLE PRECISION x,y
c--- %wf display a floating point value ---
i=winio@('X = %ta%wf%nlY = %ta%wf',x,y)
%wf - Display Real is an example of a format code. The %wf format code displays
a floating point value with six decimal places as the default. New lines are
represented by %nl - Newline, and tabs %ta - Next Tabstop operate on a grid of 8-character intervals or
by setting tab stops with the %tl - Tab Locations format (see
Tab location). %2nl (for example) is used for two new lines and %3ta
(for example) is used for three tabs. Form-feed (%ff - Form Feed) has a special meaning in
a format window. It moves the current position to the left margin, beneath any
existing controls. The window is automatically constructed with a size to suit
%wd - Display Integer, %wx - Write Hex, %ws - Display String,
%wc - Display Character, %we - Display Real, and %wg - Display Real
are alternatives to %wd - Display Integer & %wf - Display Real with the
Hexadecimal integer output.
Floating point output in decimal form.
Floating point output in exponent form.
Floating point output in decimal or exponent form.
Each of these output format codes can be modified in order to control the manner
in which the information is presented. Details are given in
By using the additional format codes described below and in the following
sections, the resulting windows can prompt for and display a wide variety of
Each format code begins with the percent (%) character, followed by optional
size information of the form n or n.m where n and m
are integer constants (e.g. %6.4wd). n and/or m can be replaced
by an asterisk "*" with the corresponding value(s) being supplied as one or two
INTEGER arguments in the argument list. After the optional size
information, a two-letter code is used to define the format. This two letter
code is not case sensitive. Some format codes have mandatory size
information. These sizes are represented by uppercase N and M in
Four special characters, known as format modifiers, are often
inserted after the size information and before the two-letter code. The
first of these is the caret character (^) which indicates that a call-back
function is supplied in the argument list (after any other arguments required
by the format code). The tilde character (~) is used with certain format codes
to control the disabling (greying) of the control. The grave accent character
(`) is also used to modify the action of certain codes. These characters may
only be used with the codes that define them as detailed in
Format code reference.
The fourth character is the question mark (?) that is used with any format that
defines a control (as opposed to formats such as %ww - Window Style that modify the appearance
of the window as a whole). The question mark signifies that a help string is
supplied in the format. This string is displayed at the bottom of the window or
as a help "bubble" whenever the user's cursor lies over the corresponding
control. The text is either surrounded by square brackets, or a "@" character
is placed in the format string to indicate that the help string is supplied as
an extra argument. The text string that is supplied in either of these two
forms is known as a standard character string.
Many format codes are supplied with a list of options. When used, these are
placed in a comma-separated list and set between square brackets after the
two-letter format code. For example
If none of the options are used then the list, together with the square
brackets, may be omitted. However, if the option list is empty and a help
string is required, then square brackets must be inserted to represent the
empty list. These brackets are followed by the help string. For example:
Here is an example that uses a help string. It prompts the user for an integer
(%rd - Edit Integer) and augments the window with an additional help string.
i=winio@('No of children %?rd'
+ //'[How many children have you got?]',n_ch)
The following code would produce the same result:
help='How many children have you got?'
i=winio@('No of children %?rd@',n_ch,help)
Help strings may include line feed characters (char(10)) if necessary. The area
to contain the help text will be sized to fit the dimensions of the largest
string. The help text can be positioned at another location (e.g. inside a box)
by using the %he format. Alternatively, %bh - Bubble Help provides for 'bubble' help and %th - Tooltop Help
for 'tooltip' help (see Bubble
and tooltip help).
A toolbar requires a help string for each button (see the %tb - Bitmap Button example in
Bitmap button and toolbar).
Calls to winio@ may become quite complex. For this reason, a method is available
to continue a format over several calls to winio@. If the last character in a
format string is an ampersand (&) character, this character is removed from
the string and the format information is joined seamlessly to the next call to
i=winio@('Enter an integer %ta%rd%nl&',n)
i=winio@('Enter a second integer%ta%rd%nl&',m)
This creates a single window containing two integer edit boxes together with a
Note that, using this technique, it is possible to build a dialog box with a
structure that is controlled by your program logic. For example, if the user
had already supplied a file name you could omit a file open box, possibly
replacing it with a suitable message.
By default, a fixed size window created using winio@ has a maximum size of
1280x1280 pixels. This maximum can be increased by a prior call to
the routine set_max_dialog_size@.
If you choose to write some routines in Fortran and others in C++, then the
programming language that you use for the first call to winio@ for a given
format window must be the same as that used in any continuation calls. However,
it is possible to create one format window using Fortran and another using C++.