Window formats

In this section:

• Introduction
• Call-back functions
• Window formats
• Closing a window
• Updating windows
• Advanced use of format windows
• Format codes grouped by function
• Alphabetical index of format codes

The ClearWin+ function winio@ has the following form:

INTEGER winio@(format,...)
CHARACTER(*) format

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:

       WINAPP
       INCLUDE <windows.ins>
       DOUBLE PRECISION x,y
       x=1.0
       y=2.5
 c---  %wf display a floating point value ---
       i=winio@('X = %ta%wf%nlY = %ta%wf',x,y)
       END

%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 its contents.

%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 following usage:

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 Data output.

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 information.

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 the text.

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

%gr[black,rgb_colours]

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:

%20.10?eb[][Edit box]

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.

      WINAPP
       INCLUDE <windows.ins>
       INTEGER n_ch
       n_ch=0
       i=winio@('No of children %?rd'
     +   //'[How many children have you got?]',n_ch)
      END

The following code would produce the same result:

      CHARACTER*80 help
       help='How many children have you got?'
       n_ch=0
       i=winio@('No of children %?rd@',n_ch,help)
      END

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 (Help Location) format. Alternatively, %th (Tooltip 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 winio@.

For example:

i=winio@('Enter an integer      %ta%rd%nl&',n)
i=winio@('Enter a second integer%ta%rd%nl&',m)
i=winio@('%cn%`bt[Done]')

This creates a single window containing two integer edit boxes together with a button.

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++.

See Also

WINSTYLE@