# Chapter 15: Widget Routines

DISLIN offers some routines for creating graphical user interfaces in Fortran and C programs. The routines are called widget routines and use the Motif widget libraries.

There are sets of routines in DISLIN for creating single widgets, for setting parameters, for requesting current widget values selected by the user and for creating dialogs.

Routines for creating single widgets begin with the characters 'WG', parameter setting routines with the characters 'SWG', requesting routines with the characters 'GWG' and dialog routines with the characters 'DWG'.

Normally, creating widget and parameter setting routines should be used between the routines WGINI and WGFIN while requesting routines can be called after WGFIN. Dialog routines can be used independently from the routines WGINI and WGFIN.

## 15.1 Widget Routines

W G I N I

The routine WGINI initializes the widget routines and creates a main widget.

The call is: | CALL WGINI (COPT, ID)
or: | int wgini (const char *copt);

COPT | is a character string that defines how children widgets are laid out in the main widget:
= 'VERT' | means that children widgets are laid out in columns from top to bottom.
= 'HORI' | means that children widgets are laid out in rows from left to right.
= 'FORM' | means that the position and size of children widgets is defined by the user with the routines SWGPOS, SWGSIZ and SWGWIN.
ID | is the returned widget index. It can be used as a parent widget index in other widget calls.

W G F I N

WGFIN terminates the widget routines. The widgets will be displayed on the screen. After choosing OK in the Exit menu, all widgets are deleted and the program is continued after WGFIN. After choosing Quit in the Exit menu, the program is terminated.

The call is: | CALL WGFIN
or: | void wgfin (void);

W G B A S

The routine WGBAS creates a container widget. It can be used as a parent widget for other widgets.

The call is: | CALL WGBAS (IP, COPT, ID)
or: | int wgbas (int ip, const char *copt);

IP | is the index of the parent widget.
COPT | is a character string that can have the values 'HORI', 'VERT' and 'FORM'. It determines how children widgets are laid out in the container widget (s. WGINI).
ID | is the returned widget index. It can be used as a parent widget index in other widget calls.

W G P O P

The routine WGPOP creates a popup menu in the menu bar of the main widget, or a popup submenu of a popup menu. Entries in the popup menu must be created with WGAPP or WGAPPB.

The call is: | CALL WGPOP (IP, CLAB, ID)
or: | int wgpop (int ip, const char *clab);

IP | is the index of a widget created by WGINI, or the index of another popup widget.
CLAB | is a character string containing the title of the popup menu.
ID | is the returned widget index. It can be used as a parent widget index for WGAPP or WGAPPB.

W G P O P B

The routine WGPOPB creates a popup menu in the menu bar of the main widget, or a popup submenu of a popup menu. WGPOPB uses an image as title instead of a character string.

The call is: | CALL WGPOPB (IP, IRAY, NW, NH, ID)
or: | int wgpopb (int ip, const unsigned char *iray, int nw, int nh);

IP | is the index of a widget created by WGINI, or the index of another popup widget.
IRAY | is a byte array containing the image. Each pixel must be represented as three bytes with the RGB values.
NW, NH | is the width and height of the image.
ID | is the returned widget index. It can be used as a parent widget index for WGAPP or WGAPPB.

W G A P P

The routine WGAPP creates an entry in a popup menu. The popup menu must be created with the routine WGPOP.

The call is: | CALL WGAPP (IP, CLAB, ID)
or: | int wgapp (int ip, const char *clab);

IP | is the index of a popup menu created with WGPOP.
CLAB | is a character string containing a label.
ID | is the returned widget index. It should be connected with a callback routine (see SWGCBK).

W G A P P B

The routine WGAPPB creates an image entry in a popup menu.

The call is: | CALL WGAPPB (IP, IRAY, NW, NH, ID)
or: | int wgappb (int ip, const unsigned char *iray, int nw, int nh);

IP | is the index of a popup menu created with WGPOP or WGPOPB.
IRAY | is a byte array containing the image. Each pixel must be represented as three bytes with the RGB values.
NW, NH | is the width and height of the image.
ID | is the returned widget index. It should be connected with a callback routine (see SWGCBK).

W G L A B

The routine WGLAB creates a label widget. The widget can be used to display a character string.

The call is: | CALL WGLAB (IP, CSTR, ID)
or: | int wglab (int ip, const char *cstr);

IP | is the index of the parent widget.
CSTR | is a character string that should be displayed.
ID | is the returned widget index.

W G I C O N

The routine WGICON creates a label widget with an icon as label.

The call is: | CALL WGICON (IP, CLAB, NW, NH, CFIL, ID)
or: | int wgicon (int ip, const char *clab, int nw, int nh, const char *cfil);

IP | is the index of the parent widget.
CLAB | is a character string that will be displayed if the mouse is moved over the label. This feature is only supported on Windows.
NW, NH | is the width and height of the icon. If NW = 0 and NH = 0, the height and width is calculated from the icon file.
CFIL | is a filename containing the icon.
ID | is the returned widget index.

W G I M G

The routine WGIMG creates a label widget with an image as label.

The call is: | CALL WGIMG (IP, CLAB, IRAY, NW, NH, ID)
or: | int wgimg (int ip, const char *clab, const unsigned char *iray, int nw, int nh);

IP | is the index of the parent widget.
CLAB | is a character string that will be displayed if the mouse is moved over the label. This feature is only supported on Windows.
IRAY | is a byte array containing the image. Each pixel must be represented as three bytes with the RGB values.
NW, NH | is the width and height of the image.
ID | is the returned widget index.

W G B U T

The routine WGBUT creates a button widget. The widget represents a labeled button that the user can turn on or off by clicking.

The call is: | CALL WGBUT (IP, CLAB, IVAL, ID)
or: | int wgbut (int ip, const char *clab, int ival);

IP | is the index of the parent widget.
CLAB | is a character string that will be used as a label.
IVAL | can have the values 0 (off) and 1 (on) and is used to initialize the button.
ID | is the returned widget index.

W G S T X T

The routine WGSTXT creates a scrolled widget that can be used for text output. The text cannot not be modified. Text entries in the widget can be made with the routine SWGTXT.

The call is: | CALL WGSTXT (IP, NSIZE, NMAX, ID)
or: | int wgstxt (int ip, int nsize, int nmax);

IP | is the index of the parent widget.
NSIZE | defines the vertical size of the widget in text rows.
NMAX | defines the maximal number of displayed entries in the scrolled widget. If this number is reached and a new entry is made, the first entry in the widget is deleted.
ID | is the returned widget index.

W G T X T

The routine WGTXT creates a text widget. The widget can be used to get text from the keyboard.

The call is: | CALL WGTXT (IP, CSTR, ID)
or: | int wgtxt (int ip, const char *cstr);

IP | is the index of the parent widget.
CSTR | is a character string that will be displayed in the text widget (≤ 256 characters).
ID | is the returned widget index.

W G L T X T

The routine WGLTXT creates a labeled text widget. The widget can be used to get text from the keyboard.

The call is: | CALL WGLTXT (IP, CLAB, CSTR, NWTH, ID)
or: | int wgltxt (int ip, const char *clab, const char *cstr, int nwth);

IP | is the index of the parent widget.
CLAB | is a character string containing a label. It will be displayed on the left side of the widget.
CSTR | is a character string that will be displayed in the text widget.
NWTH | defines the width of the text field (0 <= NWTH <= 100). For example, NWTH = 30 means that the width of the text field is: 0.3 * widget width.
ID | is the returned widget index.

W G F I L

The routine WGFIL creates a file widget. The widget can be used to get a filename from the keyboard. The filename can be typed directly into the file field or can be selected from a file selection box if an entry in the File menu is chosen.

The call is: | CALL WGFIL (IP, CLAB, CFIL, CMASK, ID)
or: | int wgfil (int ip, const char *clab, const char *cfil, const char *cmask);

IP | is the index of the parent widget.
CLAB | is a character string used for an entry in the File menu.
CFIL | is a character string that will be displayed in the file widget (≤ 256 characters).
CMASK | specifies the search pattern used in determining the files to be displayed in the file selection box.
ID | is the returned widget index.

W G L I S

The routine WGLIS creates a list widget. This widget is used whenever an application must present a list of names from which the user can choose.

The call is: | CALL WGLIS (IP, CLIS, ISEL, ID)
or: | int wglis (int ip, const char *clis, int isel);

IP | is the index of the parent widget.
CLIS | is a character string that contains the list elements. Elements must be separated by the character '|'.
ISEL | defines the pre-selected element (>= 1).
ID | is the returned widget index.

W G D L I S

The routine WGDLIS creates a dropping list widget. This list widget can be used to save space in the parent widget.

The call is: | CALL WGDLIS (IP, CLIS, ISEL, ID)
or: | int wgdlis (int ip, const char *clis, int isel);

IP | is the index of the parent widget.
CLIS | is a character string that contains the list elements. Elements must be separated by the character '|'.
ISEL | defines the pre-selected element (>= 1).
ID | is the returned widget index.

W G B O X

The routine WGBOX creates a list widget where the list elements are displayed as toggle buttons.

The call is: | CALL WGBOX (IP, CLIS, ISEL, ID)
or: | int wgbox (int ip, const char *clis, int isel);

IP | is the index of the parent widget.
CLIS | is a character string that contains the list elements. Elements must be separated by the character '|'.
ISEL | defines the pre-selected element (>= 1).
ID | is the returned widget index.

W G S C L

The routine WGSCL creates a scale widget. The widget can be displayed in horizontal or vertical direction.

The call is: | CALL WGSCL (IP, CLAB, XMIN, XMAX, XVAL, NDEZ, ID)
or: | int wgscl (int ip, const char *clab, float xmin, float xmax, float xval, int ndez);

IP | is the index of the parent widget.
CLAB | is a character string used for a label.
XMIN | is a floating point value that defines the minimal value of the scale widget.
XMAX | is a floating point value that defines the maximal value of the scale widget.
XVAL | defines the value of the scale widget.
NDEZ | is the number of digits used in the scale widget.
ID | is the returned widget index.

W G P B A R

The routine WGPBAR creates progress bars. The widget can be displayed in horizontal or vertical direction.

The call is: | CALL WGPBAR (IP, XMIN, XMAX, XSTP, ID)
or: | int wgpbar (int ip, float xmin, float xmax, float xstp);

IP | is the index of the parent widget.
XMIN | is a floating point value that defines the minimal value of the progress bar.
XMAX | is a floating point value that defines the maximal value of the progress bar.
XSTP | defines the step size. XSTP is used to calculate the maximal number of rectangles in non-smoothed progress bars. XSTP is ignored for smoothed progress bars.
ID | is the returned widget index.

Additional note:

- The appearance of progress bars can be modified with the routines SWGCLR, SWGOPT and SWGTYP. The value of progress bars can be set with SWGVAL.

W G D R A W

The routine WGDRAW creates a draw widget that can be used for graphical output from DISLIN plotting routines.

The call is: | CALL WGDRAW (IP, ID)
or: | int wgdraw (int ip);

IP | is the index of the parent widget.
ID | is the returned widget index.

Additional notes:

- The returned widget ID of a draw widget can be used in the routine SETXID for setting the graphical output of DISLIN routines to the draw widget. For X11, SETXID should be called if the widgets are already realized. Normally, SETXID should be called in a callback routine.
- By default, the height of a draw widget is identical with the width of the widget. The height of draw widgets can be modified with the routine SWGDRW.

W G T B L

The routine WGTBL creates a table widget that can be used for data input and output.

The call is: | CALL WGTBL (IP, NROWS, NCOLS, ID)
or: | int wgtbl (int ip, ncols, nrows);

IP | is the index of the parent widget.
NCOLS, NROWS | are the number of rows and columns of the table.
ID | is the returned widget index.

Additional notes:

- The values of the table cells can be defined with the routines SWGTBL, SWGTBF, SWGTBI and SWGTBS for setting float, integer and character values. CELL values can be requested with the routines GWGTBL, GWGTBF, GWGTBI and GWGTBS.
- Table cells can be editable if this mode is enabled with the routines SWGOPT or SWGTBS. The set of possible input characters for editable table cells may be restricted with the 'VERIFY' option in SWGOPT and SWGTBS.
- The width of table columns can be modified with the routine SWGRAY.
- Fore- and background colours of table cells can be defined with SWGTBI.
- The routine SWGCB2 defines callback routines for table and main widgets.

W G O K

The routine WGOK creates a push button widget where the button has the same meaning as the OK entry in the Exit menu. If the button is pressed, all widgets are deleted and the program is continued after WGFIN.

The call is: | CALL WGOK (IP, ID)
or: | int wgok (int ip);

IP | is the index of the parent widget.
ID | is the returned widget index.

W G Q U I T

The routine WGQUIT creates a push button widget where the button has the same meaning as the QUIT entry in the Exit menu. If the button is pressed, the program is terminated.

The call is: | CALL WGQUIT (IP, ID)
or: | int wgquit (int ip);

IP | is the index of the parent widget.
ID | is the returned widget index.

W G P B U T

The routine WGPBUT creates a push button widget.

The call is: | CALL WGPBUT (IP, CLAB, ID)
IP | is the index of the parent widget.
CLAB | is a character string that will be used as a label.
ID | is the returned widget index. It should be connected with a callback routine.

Additional note:

- The status of a push button (if it is pressed or not) can be requested with GWGBUT.

W G P I C O N

The routine WGPICON creates a push button widget with an icon as label.

The call is: | CALL WGPICON (IP, CLAB, NW, NH, CFIL, ID)
or: | int wgpicon (int ip, const char *clab, int nw, int nh, const char *cfil);

IP | is the index of the parent widget.
CLAB | is a character string that will be displayed if the mouse is moved over the label. This feature is only supported on Windows.
NW, NH | is the width and height of the icon. If NW = 0 and NH = 0, the height and width is calculated from the icon file.
CFIL | is a filename containing the icon.
ID | is the returned widget index.

W G P I M G

The routine WGPIMG creates a push button widget with an image as label.

The call is: | CALL WGPIMG (IP, CLAB, IRAY, NW, NH, ID)
or: | int wgpimg (int ip, const char *clab, const unsigned char *iray, int nw, int nh);

IP | is the index of the parent widget.
CLAB | is a character string that will be displayed if the mouse is moved over the label. This feature is only supported on Windows.
IRAY | is a byte array containing the image. Each pixel must be represented as three bytes with the RGB values.
NW, NH | is the width and height of the image.
ID | is the returned widget index.

W G C M D

The routine WGCMD creates a push button widget. A corresponding system command will be executed if the button is pressed.

The call is: | CALL WGCMD (IP, CLAB, CMD, ID)
or: | int wgcmd (int ip, const char *clab, const char *cmd);

IP | is the index of the parent widget.
CLAB | is a character string that will be used as a label.
CMD | is a character string containing a system command.
ID | is the returned widget index.

W G S E P

The routine WGSEP separates widgets by drawing horizontal or vertical lines, or menu entries by drawing horizontal lines.

The call is: | CALL WGSEP (IP, ID)
or: | int wgsep (int ip);

IP | is the index of the parent widget.
ID | is the returned widget index.

Additional notes:

- WGSEP draws by default horizontal lines. Vertical lines can be defined with the routine SWGTYP.
- Several line drawing styles can be selected with the routine SWGOPT.

## 15.2 Parameter Setting Routines

S W G W T H

The routine SWGWTH sets the default width of horizontal and parent/base widgets.

The call is: | CALL SWGWTH (NWTH)
or: | void swgwth (int nwth);

NWTH | is an integer containing a positive number of characters or a negative number between -1 and 100. If NWTH < 0, the widget width is set to ABS(NWTH) * NWIDTH / 100 where NWIDTH is the screen width. Default: NWTH = 20

S W G D R W

The routine SWGDRW modifies the height of draw widgets.

The call is: | CALL SWGDRW (XF)
or: | void swgdrw (float xf);

XF | is a positive floating point number. The height of a draw widget is set to XF * NW where NW is the widget width. Default: XF = 1.

S W G C L R

The routine SWGCLR defines colours for widgets.

The call is: | CALL SWGCLR (XR, XG, XB, COPT)
or: | void swgclr (float xr, float xg, float xb, const char *copt);

XR, XG, XB | are RGB values between 0 and 1.
COPT | is a character string that can have the values 'BACK', 'FORE', 'SCROLL', 'LTEXT' and 'PBAR'. The keywords 'BACK' and 'FORE' define background and foreground colours, 'SCROLL' defines the colour of the slider in scale widgets, and 'LTEXT' sets the background colour of the edit window in labeled text widgets.

Additional notes:

- Colours can not be defined for push button widgets. This is a restriction in the Windows API.
- Multiple draw widgets must have the same background colour since they belong to the same widget class. The same is valid for multiple main widgets created by WGINI.

S W G F N T

The routine SWGFNT defines fonts for widgets.

The call is: | CALL SWGFNT (CFNT, NPTS)
or: | void swgfnt (const char *cfnt, int npts);

CFNT | is a character string containing the font. For Windows, CFNT can contain a TrueType font (see WINFNT), or one of the Windows raster fonts such as System, FixedSys, Terminal, Courier, MS Serif and MS Sans Serif. For X11, CFNT can contain an X11 font. CNFT = 'STANDARD' resets the font to the default value.
NPTS | is the font size in points (72 points = 1 inch). Note that only a few different font sizes are available for Windows raster fonts. For X11, the parameter NPTS will be ignored since the font size is already part of the font name.

S W G F O C

The routine SWGFOC sets the keyboard focus to the specified widget.

The call is: | CALL SWGFOC (ID)
or: | void swgfoc (int id);

ID | is the widget index.

S W G O P T

The routine SWGOPT sets widget options.

The call is: | CALL SWGOPT (COPT, CKEY)
or: | void swgopt (const char *copt, const char *ckey);

COPT | is a character string containing an option.
CKEY | is a character string containing a keyword:
= 'BORDER' | This keyword defines borders around table cells. COPT can have the values 'NONE','COLUMNS', 'ROWS' and 'BOTH'. The default value is 'BOTH'.
= 'BACKGROUND' | sets an image as background for the main widget. COPT should contain the name of an BMP file containing the image. If the image is smaller than the size of the main widget, the image will be duplicated. Otherwise, it will be clipped.
= 'CALLBACK' | The behaviour of callback routines for text widgets can be modified with this keyword. COPT can have the values 'RETURN', 'CHANGE' and 'BOTH'. For 'RETURN', the callback routine is only called if a return is given in the text field, for 'CHANGE, the callback routine is called for each change in the text field. The default value is 'RETURN'.
= 'CLOSE' | This keyword changes the behaviour of the close button of the main widget. For COPT = 'QUIT', the program will be terminated. For COPT = 'OK', the main widget is deleted and the program is continued after WGFIN.
= 'CODING' | defines the coding of strings in widgets. COPT can have the values 'ANSI' (default), 'UTF8', 'RUSSIAN' and 'GREEK'. This option is only available on Windows systems, but not for X11.
= 'DIALOG' | Dialog widgets created by the DWG routines described in paragraph 15.5 can have the topmost attribute, so that they are not overplotted by other windows. COPT can have the values 'STANDARD' and 'TOP'. This option is only on Windows systems available, not on X11 systems.
= 'EDIT' | This keyword defines if table cells are editable or not. COPT can have the values 'OFF' and 'ON'.
= 'FILE' | This keyword disables or enables a text widget created by WGFIL for the selected file name. COPT can have the values 'NOFIELD' and 'FIELD' (default).
= 'FRAME' | Enables or disables a frame around table and draw widgets. COPT can have the values 'OFF' and 'ON'.
= 'HEADER' | This keyword enables header cells in table widgets. COPT can have the values 'NONE', 'COLUMNS', 'ROWS' and 'BOTH'.
= 'MAIN' | Enables a fullscreen mode for the main widget if COPT has the value 'FULL'.
= 'MASK' | If CKEY = 'MASK', COPT can have the values 'STANDARD' and 'USER'. For COPT = 'USER', the mask entry in the routines WGFIL and DWGFIL can be controlled completely by the user. For that case, the mask parameter in WGFIL and DWGFIL can have the following syntax: it contains of a pair of strings separated by a '+' sign. The first string contains the label, the second string the search filter. For example: 'Data (*.dat)+*.dat'. 'Data (*.dat)' is the label while '*.dat' the filter. Multiple pairs of strings for the mask are also possible.
= 'PBAR' | This option changes the appearance of progress bars. COPT can have the values 'SMOOTH', 'NOSMOOTH', 'BACK', 'NOBACK', 'LABEL',' NOLABEL', 'FRAME' and 'NOFRAME'. The defaults are 'NOSMOOTH', 'BACK', 'NOLABEL' and 'FRAME'.
= 'POSITION' | If CKEY = 'POSITION', COPT can have the values 'STANDARD' and 'CENTER'. For COPT = 'CENTER', the main widget will be centred on the screen. The default position of the main widget is the upper left corner of the screen.
= 'SCROLL' | This option changes the behaviour of callback routines for scroll widgets. COPT can have the values 'TRACK', 'BUTTON' and 'END'. If COPT = 'TRACK', the callback routine is called for each change of the scroll value. If COPT = 'BUTTON', the callback routine is only called if a user releases the mouse button. For COPT = 'END', the callback routine is called at the end of the scroll action.
= 'SEPARATOR' | This option selects a line style for WGSEP. COPT can have the values 'STANDARD', 'SINGLE', 'DOUBLE', 'DASH' and 'DDASH'. The style 'STANDARD' is used by default.
= 'SLIDER' | Specifies whether a label for the current slider value is displayed or not. COPT can have the values 'VALUE' (default) and 'NOVALUE'.
= 'VERIFY' | The keyword 'VERIFY' enables a check of input characters in text and table cells. COPT can have the values 'NONE', 'INTEGER', 'FLOAT', 'EFLOAT', 'DFLOAT', 'ALPHA', 'NALPHA', 'EMAIL', 'TIME', 'DATE', 'PHONE', 'HEXA' and 'OCTAL'. The default value is COPT = 'NONE'. A table of the possible characters correspondig to the verify options is given below.

Additional note:

- Some X11 Window managers ignore the position of the main widget.

The following table shows the possible characters for the different 'VERIFY' options in SWGOPT:

        -----------------------------------------------------
        |    NONE     |         all characters              |
        -----------------------------------------------------
        |  INTEGER    |         0 - 9, '+', '-'             |
        -----------------------------------------------------
        |   FLOAT     |      0 - 9, '.', '+', '-'           |
        -----------------------------------------------------
        |   DFLOAT    |   0 - 9, '.', '+', '-', 'd', 'D'    |
        -----------------------------------------------------
        |   EFLOAT    |   0 - 9, '.', '+', '-', 'e', 'E'    |
        -----------------------------------------------------
        |   DIGITS    |             0 - 9                   |
        -----------------------------------------------------
        |   ALPHA     |          a - z, A - Z, ' '          |
        -----------------------------------------------------
        |   NALPHA    |       a - z, A - Z, 0 - 9, ' '      |
        -----------------------------------------------------
        |   EMAIL     | a - z, A - Z, 0 - 9, '.', '@', '-'  |
        -----------------------------------------------------
        |    TIME     |            0 - 9, ':'               |
        -----------------------------------------------------
        |    DATE     |         0 - 9, '.', '/'             |
        -----------------------------------------------------
        |   PHONE     |         0 - 9, '-', ' ', '/'        |
        -----------------------------------------------------
        |    HEXA     |    0 - 9, A - E, a - e, 'x', 'X'    |
        -----------------------------------------------------
        |   OCTAL     |           0 - 7, 'o, 'O'            |
        -----------------------------------------------------

S W G I O P

The routine SWGIOP sets integer options for widgets.

The call is: | CALL SWGIOP (N, CKEY)
or: | void swgiop (int n, const char *ckey);

N | is an integer option.
= 'CKEY' | is a character string containing a keyword:
= 'TABLE' | means that N defines the number of visible rows in scrolled table widgets.
= 'LIST' | means that N defines the number of visible entries in scrolled list widgets.
= 'DLIST' | means that N defines the width of the list in dropping list widgets. For N = 0, the list has the same width as the widget. A negative value sets the width of the list in pixel, a positive value the width in number of characters.
= 'HMARGIN' | sets the horizontal margin in text and push button widgets (only X11). The default margins are 5 for text widgets and 2 for push button widgets. N = -1 defines this values.
= 'VMARGIN' | sets the vertical margin in text and push button widgets (only X11). The default margins are 5 for text widgets and 2 for push button widgets. N = -1 defines this values.
= 'ICON' sets an icon ID for the routines WGICON, WGPICON, and for the header line of a main widget. The icon is taken from the program resource. N = -1 resets this option. (Only Windows).
Defaults: (8, 'TABLE'), (8, 'LIST'), (0, 'DLIST'), (-1, 'HMARGIN'), (-1, 'VMARGIN'), (-1, 'ICON').

S W G P O P

The routine SWGPOP modifies the appearance of the popup menu bar.

The call is: | CALL SWGPOP (COPT)
or: | void swgpop (const char *copt);

COPT | is a character string containing an option:
= 'NOOK' | suppresses the 'OK' entry in the 'EXIT' menu.
= 'NOQUIT' | suppresses the 'QUIT' entry in the 'EXIT' menu.
= 'NOHELP' | suppresses the 'HELP' button in the menu bar.
= 'OK' | enables the 'OK' entry in the 'EXIT' menu (default).
= 'QUIT' | enables the 'QUIT' entry in the 'EXIT' menu (default).
= 'HELP' | enables the 'HELP' button in the menu bar (default).

S W G T I T

The routine SWGTIT defines a title displayed in the main widget.

The call is: | CALL SWGTIT (CTIT)
or: | void swgtit (const char *ctit);

CTIT | is a character string containing the title.

S W G H L P

The routine SWGHLP sets a character string that will be displayed if the Help menu is clicked by the user.

The call is: | CALL SWGHLP (CSTR)
or: | void swghlp (const char *cstr);

CSTR | is a character string that will be displayed in the help box. The character '|' can be used as a newline character.

S W G S I Z

The routine SWGSIZ defines the size of form and main widgets.

The call is: | CALL SWGSIZ (NW, NH)
or: | void swgsiz (int nw, int nh);

NW, NH | are the width and height of the widget in pixels.

S W G P O S

The routine SWGPOS defines the position of widgets.

The call is: | CALL SWGPOS (NX, NY)
or: | void swgpos (int nx, int ny);

NX, NY | are the upper left corner of the widget in pixels. The point is relative to the upper left corner of the parent widget.

S W G W I N

The routine SWGWIN defines the position and size of widgets.

The call is: | CALL SWGWIN (NX, NY, NW, NH)
or: | void swgwin (int nx, int ny, int nw, int nh);

NX, NY | are the upper left corner of the widget in pixels. The point is relative to the upper left corner of the parent widget.
NW, NH | are the width and height of the widget in pixels.

S W G T Y P

The routine SWGTYP modifies the appearance of certain widgets.

The call is: | CALL SWGTYP (CTYPE, CLASS)
or: | void swgtyp (const char *ctype, const char *class);

CTYPE | is a character string containing a keyword:
= 'VERT' | means that list elements in box widgets or scale widgets will be displayed in vertical direction. Lines plotted by WGSEP will have a vertical orientation.
= 'HORI' | means that list elements in box widgets, scale widgets and progress bars will be displayed in horizontal direction. Lines plotted by WGSEP will have a horizontal orientation.
= 'GRID' | means that box widgets will be displayed in matrix form.
= 'SCROLL' | means that scrollbars will be created in list, table, draw and main widgets.
= 'NOSCROLL' | means that no scrollbars will be created in list, table, draw and main widgets.
= 'VSCROLL' | means that just a vertical scrollbar is created in list widgets.
= 'AUTO' | means that scrollbars will be created in list widgets if the number of elements is greater than 8.
= 'OPEN' | means that a file selection box for reading files is defined.
= 'SAVE' | means that a file selection box for saving files is defined.
= 'STRING' | means that a popup menu can be directly connected with a callback routine. Normally, menu entries in a popup menu can be connected with callback routines.
= 'NORESIZE' | means that the size of the main widget cannot be changed with the mouse. The default behaviour is 'RESIZE'.
= 'NOEDIT' | defines non editable text widgets.
= 'PASS' | enables hidden password input for text widgets.
CLASS | is a character string containing the widget class where CLASS can have the values 'LIST', 'BOX', 'SCALE', 'PBAR', 'TABLE', 'DRAW', 'FILE', 'SEPARATOR', 'POPUP', 'MAIN' and 'TEXT'. If CLASS = 'LIST', CTYPE can have the values 'AUTO', 'SCROLL' and 'NOSCROLL'. If CLASS has one of the values 'BOX', 'SCALE', 'PBAR' and 'SEPARATOR', CTYPE can have the values 'VERT' and 'HORI'. The class 'BOX' can have the additional value 'GRID'. The class 'TABLE' can have the options 'AUTO', 'SCROLL' and 'NOSCROLL'. For CLASS = 'DRAW', CTYPE can have the values 'SCROLL' and 'NOSCROLL'. The size of a graphics in draw widgets with scroll bars can be defined with the routine WINSIZ before SETXID. If CLASS = 'FILE', CTYPE can have the values 'OPEN' and 'SAVE'. If CLASS = 'POPUP', CTYPE can have the values 'STRING' and 'MENU'. For CLASS = 'MAIN', CTYPE can have the values 'RESIZE' and 'NORESIZE', or 'SCROLL' and 'NOSCROLL'. For CLASS = 'TEXT', CTYPE can have the values 'EDIT', 'NOEDIT' and 'PASS'. Defaults: ('VERT', 'BOX'), ('HORI', 'SCALE'), ('AUTO', 'TABLE'), ('HORI', 'PBARS'), ('HORI', 'SEPARATOR'), ('AUTO', 'LIST'), ('NOSCROLL', 'DRAW'), ('OPEN', 'FILE'), ('MENU', 'POPUP'), ('RESIZE', 'MAIN'), ('NOSCROLL', 'MAIN'), ('EDIT', 'TEXT').

S W G J U S

The routine SWGJUS defines the alignment of labels in label and button widgets and of cell values in table widgets.

The call is: | CALL SWGJUS (CJUS, CLASS)
or: | void swgjus (const char *cjus, const char *class);

CJUS | is a character string defining the alignment:
= 'LEFT' | means left-justified.
= 'CENTER' | means centred.
= 'RIGHT' | means left-justified.
CLASS | is a character string defining the widget class. CLASS can have the values 'LABEL', 'BUTTON' and 'TABLE'. Defaults: ('LEFT', 'LABEL'), ('CENTER', 'BUTTON'), ('CENTER', 'TABLE').

S W G S P C

The routine SWGSPC defines horizontal and vertical space between widgets.

The call is: | CALL SWGSPC (XSPC, YSPC)
or: | void swgspc (float xspc, float yspc);

XSPC, YSPC | are floating point numbers defining the space between widgets. For non negative values, the spaces XSPC * NWCHAR and YSPC * NHCHAR are used where NWCHAR and NHCHAR are the current character width and height. For negative values, the horizontal and vertical spaces are set to ABS(XSPC) * NWIDTH / 100 and ABS (YSPC) * NHEIGHT where NWIDTH and NHEIGHT are the width and height of the screen. Default: (4.0, 0.5).

S W G S T P

The routine SWGSTP defines a step value for scale widgets.

The call is: | CALL SWGSTP (XSTP)
or: | void swgstp (float xstp);

XSTP | is a positive floating point number defining the step value. The default value is (MAX - MIN) / 100.

S W G M R G

The routine SWGMRG defines margins for widgets.

The call is: | CALL SWGMRG (IVAL, CMRG)
or: | void swgmrg (int ival, const char *cmrg);

IVAL | is the margin value in pixels.
CMRG | is a character string that can have the values 'LEFT', 'TOP', 'RIGHT' and 'BOTTOM'. By default, all margins are zero.

S W G M I X

The routine SWGMIX defines control characters for separating elements in list strings.

The call is: | CALL SWGMIX (CHAR, CMIX)
or: | void swgmix (const char *char, const char *cmix);

CHAR | is a new control character.
CMIX | is a character string that defines the function of the control character. CMIX can have the value 'SEP'.

S W G C B K

The routine SWGCBK connects a widget with a callback routine. The callback routine is called if the status of the widget is changed. Callback routines can be defined for button, pushbutton, file, list, scale, box, text and table widgets, and for popup menu entries. Since the syntax of callback routines for table and main widgets is different, they must be defined with SWGCB2.

The call is: | CALL SWGCBK (ID, ROUTINE)
or: | void swgcbk (int id, (void) (*routine)(int id));

ID | is a widget ID.
ROUTINE | is the name of a routine defined by the user. In Fortran, the routine must be declared as EXTERNAL. The only parameter that is passed to the callback routine is the widget ID.

S W G C B 2

The routine SWGCB2 defines callback routines for table and main widgets. A callback routine for a main widget is called when the size of the main widget has changed. A callback for a table widget is called when the value of a table cell has changed, or when it is clicked.

The call is: | CALL SWGCB2 (ID, ROUTINE)
or: | void swgcb2 (int id, (void) (*routine)(int id, int irow, int icol));

ID | is a widget ID.
ROUTINE | is the name of a routine defined by the user. In Fortran, the routine must be declared as EXTERNAL. The parameters passed to the callback routine are the widget ID, the row number and the column number of the table cell that has invoked the callback routine, or the new width and height of the main widget in pixels.

S W G C B 3

The routine SWGCB3 defines callback routines for mouse wheel events in draw widgets.

The call is: | CALL SWGCB3 (ID, ROUTINE)
or: | void swgcb3 (int id, (void) (*routine)(int id, int ival));

ID | is a widget ID.
ROUTINE | is the name of a routine defined by the user. In Fortran, the routine must be declared as EXTERNAL. The parameters passed to the callback routine are the widget ID and an integer variable, that can have the values 1 und -1. A positive value means that the wheel was rotated forward away from the user, a negative value indicates that the wheel was rotated backward.

S W G A T T

The routine SWGATT sets widget attributes.

The call is: | CALL SWGATT (ID, CATT, CKEY)
or: | void swgatt (int id, const char *catt, const char *ckey);

ID | is a widget ID.
CATT | is a character string containing an attribute.
CKEY | is a character string containing a keyword:
= 'STATUS' | If CKEY = 'STATUS', CATT can have the values 'ACTIVE', 'INACTIVE' and 'INVISIBLE'.
= 'CLOSE' | The keyword 'CLOSE' can have the attributes 'ACTIVE' and 'INACTIVE'. It allows a user to disable the close button of the main widget.
= 'LIST' | If CKEY = 'LIST', CATT can have new list elements for a list widget. In that case, CATT has the same meaning as the parameter CLIS in WGLIS.
= 'MENU' | The menu header line in a main widget can be disabled with the attribute 'OFF'. The default value is 'ON'. ID should contain the widget ID of the main widget.
= 'MINI' | This option allows to disable the minimize button in the header line of a main widget. CATT can have the values 'OFF' and 'ON'.
= 'MAXI' | This option allows to disable the maximize button in the header line of a main widget. CATT can have the values 'OFF' and 'ON'.
= 'ICON' | The icon in the header line of a main widget can be replaced by an icon in a .ico file (only Windows). CATT should contain the name of the .ico file.

S W G B G D

The routine SWGBGD changes the background colour of widgets.

The call is: | CALL SWGBGD (ID, XR, XG, XB)
or: | void swgbgd (int id, float xr, float xg, float xb);

ID | is the widget ID.
XR, XG, XB | are RGB values between 0 and 1.

S W G F G D

The routine SWGFGD changes the foreground colour of widgets.

The call is: | CALL SWGFGD (ID, XR, XG, XB)
or: | void swgfgd (int id, float xr, float xg, float xb);

ID | is the widget ID.
XR, XG, XB | are RGB values between 0 and 1.

S W G B U T

The routine SWGBUT sets the status of a button widget.

The call is: | CALL SWGBUT (ID, IVAL)
or: | void swgbut (int id, int ival);

ID | is a widget ID of a button widget.
IVAL | can have the values 0 and 1.

S W G L I S

The routine SWGLIS changes the selection in a list widget.

The call is: | CALL SWGLIS (ID, ISEL)
or: | void swglis (int id, int isel);

ID | is a widget ID of a list widget.
ISEL | defines the selected element (>= 1).

S W G B O X

The routine SWGBOX changes the selection in a box widget.

The call is: | CALL SWGBOX (ID, ISEL)
or: | void swgbox (int id, int isel);

ID | is a widget ID of a box widget.
ISEL | defines the selected element (>= 1).

S W G T X T

The routine SWGTXT changes the value of a text widget and the text string of label and push button widgets.

The call is: | CALL SWGTXT (ID, CVAL)
or: | void swgtxt (int id, const char *cval);

ID | is a widget ID of a text widget.
CVAL | is a character string containing the new text.

S W G I N T

The routine SWGINT changes the value of a text widget.

The call is: | CALL SWGINT (ID, IVAL)
or: | void swgint (int id, int ival);

ID | is a widget ID of a text widget.
IVAL | is an integer number which will be displayed in a text widget.

S W G F L T

The routine SWGFLT changes the value of a text widget.

The call is: | CALL SWGFLT (ID, XVAL, NDIG)
or: | void swgflt (int id, float xval, int ndig);

ID | is a widget ID of a text widget.
XVAL | is a floating point number which will be displayed in a text widget.
NDIG | is the number of digits displayed after the decimal point. NDIG = -2 means that the number of digits is calculated by DISLIN.

S W G F I L

The routine SWGFIL changes the value of a file widget.

The call is: | CALL SWGFIL (ID, CFIL)
or: | void swgfil (int id, const char cfil);

ID | is a widget ID of a file widget.
CFIL | is a character string containing the new filename.

S W G S C L

The routine SWGSCL changes the value of a scale widget, and the value of scrollbars at draw widgets.

The call is: | CALL SWGSCL (ID, XVAL)
or: | void swgscl (int id, float xval);

ID | is a widget ID of a scale or draw widget. If the widget ID is passed as it's negative value, the vertical scrollbar of a draw widget is changed. Otherwise, the horizontal scrollbar.
XVAL | is a floating point number containing the new value of the scrollbar.

S W G V A L

The routine SWGVAL changes the value of a progress bar.

The call is: | CALL SWGVAL (ID, XVAL)
or: | void swgval (int id, float xval);

ID | is a widget ID of a progress bar.
XVAL | is a floating point number containing the new value of the progress bar.

S W G T B F

The routine SWGTBF sets floating point values in table cells.

The call is: | CALL SWGTBF (ID, XVAL, NDIG, IROW, ICOL, COPT)
or: | void swgtbf (int id, float xval, int ndig, int irow, int icol, const char *copt);

ID | is a widget ID of a table widget.
XVAL | is a floating point number which will be displayed in a table widget.
NDIG | is the number of digits displayed after the decimal point (&ge -2). NDIG = -2 means that the number of digits is calculated by DISLIN.
IROW, ICOL | are the row and column indices of the table cell (&ge -1). The value -1 means that a complete row or column is filled with XVAL and the index 0 corresponds to header cells.
COPT | is a character string that can have the value 'VALUE'.

S W G T B I

The routine SWGTBI sets integers in table cells, or defines fore- and background colours for table cells.

The call is: | CALL SWGTBI (ID, IVAL, IROW, ICOL, COPT)
or: | void swgtbi (int id, int ival, int irow, int icol, const char *copt);

ID | is a widget ID of a table widget.
IVAL | is an integer that contains the cell or a colour value. Colour values can be calculated from RGB values with the function INTRGB.
IROW, ICOL | are the row and column indices of the table cell (&ge -1). The value -1 means that a complete row or column is used while the index 0 corresponds to header cells.
COPT | is a character string that defines the meaning of IVAL. COPT can have the values 'VALUE', 'BACK', 'FORE' and 'SYSTEM'. The options 'BACK' and 'FORE' are used for back- and foreground colours. The option 'SYSTEM' resets the colours in table cells back to system values.

S W G T B L

The routine SWGTBL passes an array of floating point values to a table widget.

The call is: | CALL SWGTBL (ID, XRAY, N, NDIG, IDX, COPT)
or: | void swgtbl (int id, const float *xray, int n, int ndig, int idx, const char *copt);

ID | is a widget ID of a table widget.
XRAY | is an array of floating point numbers.
N | is the number of elements in XRAY.
NDIG | is the number of digits displayed after the decimal point (&ge -2) for XRAY. NDIG = -2 means that the number of digits is calculated by DISLIN.
IDX | is the index of a table row or column (&ge 1). IDX may be ignored for some options in COPT.
COPT | is a character string that can have the values 'ROW', 'COLUMN', 'RTABLE' and 'CTABLE'. The keyword 'ROW' means that a table row is filled with XRAY. 'COLUMN' means that a column is used. For COPT = 'RTABLE', the complete table is filled with XRAY by rows and for COPT = 'CTABLE', the table is filled by columns.

S W G T B S

The routine SWGTBS sets character values and options for single table cells.

The call is: | CALL SWGTBS (ID, CVAL, IROW, ICOL, COPT)
or: | void swgtbs (int id, const char *cval, int irow, int icol, const char *copt);

ID | is a widget ID of a table widget.
CVAL | is a character string that contains the new cell value or a character option. Up to 80 characters are accepted by table cells.
IROW, ICOL | are the row and column indices of the table cell (&ge -1). The value -1 means that a complete row or column is used while the index 0 corresponds to header cells.
COPT | is a character string that defines the meaning of CVAL. COPT can have the values 'VALUE', 'EDIT', 'ALIGN' and 'VERIFY'. The option 'EDIT' enables or disables edit mode for table cells where the corresponding option in CVAL can have the values 'ON' and 'OFF'. The default behaviour is 'OFF'. 'ALIGN' defines the alignment in table cells where CVAL can have the keywords 'LEFT', 'CENTER' and 'RIGHT'. The default value is 'RIGHT'. The keyword 'VERIFY' enables the check of input characters for table cells where CVAL can be one of the verify options of figure 15.1. The default verify option is 'NONE'.

S W G R A Y

The routine SWGRAY sets the width of table columns. It should be called before WGTBL.

The call is: | CALL SWGRAY (XRAY, N, COPT)
or: | void swgray (const float *xray, int n, const char *copt);

XRAY | is an array of floating point numbers. A positive value is interpreted as characters, a negative number as percent from the widget width. If a table contains a header column, the first index of XRAY is used for that column.
N | is the number of elements in XRAY.
COPT | is a character string that can have the value 'TABLE'.

## 15.3 Requesting Routines

Requesting routines can be used to request the current widget values selected by the user. The routines must be called after WGFIN.

G W G B U T

The routine GWGBUT returns the status of a button or push button widget.

The call is: | CALL GWGBUT (ID, IVAL)
or: | int gwgbut (int id);

ID | is the index of the button widget.
IVAL | is the returned status where IVAL = 0 means off and IVAL = 1 means on.

G W G T X T

The routine GWGTXT returns the input of a text widget.

The call is: | CALL GWGTXT (ID, CSTR)
or: | void gwgtxt (int id, char *cstr);

ID | is the index of the text widget.
CSTR | is the returned character string that can have up to 256 characters.

G W G I N T

The routine GWGINT returns the input of a text widget as an integer value.

The call is: | CALL GWGINT (ID, IVAL)
or: | int gwgint (int id);

ID | is the index of the text widget.
IVAL | is the integer number.

G W G F L T

The routine GWGFLT returns the input of a text widget as a floating point value.

The call is: | CALL GWGFLT (ID, XVAL)
or: | float gwgflt (int id);

ID | is the index of the text widget.
XVAL | is the floating point number.

G W G F I L

The routine GWGFIL returns the input of a file widget.

The call is: | CALL GWGFIL (ID, CFIL)
or: | void gwgfil (int id, char *cfil);

ID | is the index of the file widget.
CFIL | is the returned filename that can have up to 256 characters.

G W G L I S

The routine GWGLIS returns the selected element of a list widget.

The call is: | CALL GWGLIS (ID, ISEL)
or: | int gwglis (int id);

ID | is the index of the list widget.
ISEL | is the selected list element returned by GWGLIS.

G W G B O X

The routine GWGBOX returns the selected element of a box widget.

The call is: | CALL GWGBOX (ID, ISEL)
or: | int gwgbox (int id);

ID | is the index of the box widget.
ISEL | is the selected element returned by GWGBOX.

G W G S C L

The routine GWGSCL returns the value of a scale widget, or the value of a scrollbar at draw widgets.

The call is: | CALL GWGSCL (ID, XVAL)
or: | float gwgscl (int id);

ID | is a widget ID of a scale or draw widget. If the widget ID is passed as it's negative value, the value of the vertical scrollbar of a draw widget is returned. Otherwise, the value of the horizontal scrollbar.
XVAL | is the returned value.

G W G S I Z

The routine GWGSIZ returns the size of widgets.

The call is: | CALL GWGSIZ (ID, NW, NH)
or: | void gwgsiz (int id, int *nw, int *nh);

ID | is the index of the scale widget.
NW, NH | are the returned width and height of the widget in pixels.

G W G T B F

The routine GWGTBF returns the value of a table cell as floating point number.

The call is: | CALL GWGTBF (ID, IROW, ICOL, XVAL)
or: | float gwgtbf (int id, int irow, int icol);

ID | is the index of a table widget.
IROW, ICOL | are the row and column indices of the table cell (&ge 1).
XVAL | is the returned floating point number.

G W G T B I

The routine GWGTBI returns the value of a table cell as integer number.

The call is: | CALL GWGTBI (ID, IROW, ICOL, IVAL)
or: | int gwgtbf (int id, int irow, int icol);

ID | is the index of a table widget.
IROW, ICOL | are the row and column indices of the table cell (&ge 1).
IVAL | is the returned integer number.

G W G T B L

The routine GWGTBL fills a floating point user array with table values.

The call is: | CALL GWGTBL (ID, XRAY, N, IDX, COPT)
or: | void gwgtbl (int id, float *xray, int n, int idx, const char *copt);

ID | is the index of a table widget.
XRAY | is a floating point array that will contain the cell values after the call to GWGTBL.
N | is the number of elements in XRAY.
IDX | is the index of a table row or column (&ge 1), or may be ignored.
COPT | is a character string that can have the values 'ROW', 'COLUMN', 'RTABLE' and 'CTABLE'. The keywords have the same meaning as in SWGTBL.

G W G T B S

The routine GWGTBS returns the value of a table cell as character string.

The call is: | CALL GWGTBS (ID, IROW, ICOL, CVAL)
or: | void gwgtbs (int id, int irow, int icol, const char *cval);

ID | is the index of a table widget.
IROW, ICOL | are the row and column indices of the table cell (&ge 1).
CVAL | is the returned character string that can have up to 80 characters.

G W G A T T

The routine GWGATT returns a widget attribute.

The call is: | CALL GWGATT (ID, IATT, COPT)
or: | int gwgatt (int id, const char *copt);

ID | is a widget ID.
IATT | is a returned attribute. If COPT = 'STATUS', IATT can have the values 0 for 'ACTIVE', 1 for 'INACTIVE' and 2 for 'INVISIBLE'.
COPT | is a character string that can have the value 'STATUS'.

G W G X I D

The routine GWGXID returns the window ID for a specified widget ID.

The call is: | CALL GWGXID (ID, IWINID)
or: | int gwgxid (int id);

ID | is the widget ID.
IWINID | is the returned window ID.

Additional note:

- For X11, the window ID of a widget can only be calculated if the widget is already realized. This means that GWGXID should be called in a callback routine and not directly behind a widget. For X11, widgets are realized in the routine WGFIN.

G W G G U I

The routine GWGGUI returns the used GUI of the Dislin library.

The call is: | CALL GWGGUI (IRET)
or: | int gwggui (void);

IRET | identifies the used GUI. IRET = 1 means OpenMotif, IRET = 2 GTK and IRET = 3 Windows API.

## 15.4 Utility Routines

I T M S T R

The routine ITMSTR extracts a list element from a list string.

The call is: | CALL ITMSTR (CLIS, IDX, CITEM)
or: | char *itmstr (const char *clis, int idx);

CLIS | is a character string that contains the list elements (s. WGLIS).
IDX | is the index of the element that should be extracted from CLIS.
CITEM | is a character string containing the extracted list element. For C, the returned string is an allocated pointer via malloc and can be freed by a user.

I T M C N T

The routine ITMCNT returns the number of elements in a list string.

The call is: | N = ITMCNT (CLIS)
or: | int itmcnt (const char *clis);

CLIS | is a character string that contains the list elements (s. WGLIS).
N | is the calculated number of elements in CLIS.

I T M N C A T

The routine ITMNCAT concatenates an element to a list string.

The call is: | CALL ITMNCAT (CLIS, N, CITEM)
or: | void itmcat (char *clis, int n, const char *citem);

CLIS | is a character string that contains the list elements (s. WGLIS).
N | is the maximal number of characters that can be stored in CLIS.
CITEM | is a character string that will be concatenated to CLIS. If CLIS is blank, CITEM will be the first element in CLIS.

Additional notes:

- Trailing blanks in CLIS and CITEM will be ignored.
- ITMNCAT is a replacement of ITMCAT with the additional parameter N for avoiding buffer overflows. ITMCAT is still in the library for providing compatibility.

F R E E P T R

The routine FREEPTR deallocates space that is allocated in a Dislin routine before. The routine is only useful for C.

The call is: | void freeptr (void *ptr);

ptr | is a pointer to a memory address.

M S G B O X

The routine MSGBOX displays a message in form of a dialog widget. It can be used to display messages in callback routines.

The call is: | CALL MSGBOX (CSTR)
or: | void msgbox (const char *cstr);

CSTR | is a character string containing a message.

R E A W G T

The routine REAWGT realizes a widget tree. Since the windows ID of a widget can only be calculated for X11 if the widget is already realized, this routine is useful if the windows ID of a widget is needed before WGFIN. Normally, the widget tree is realized in WGFIN.

The call is: | CALL REAWGT
or: | void reawgt (void);

S E N D O K

The routine SENDOK has the same meaning as when the OK entry in the Exit menu is pressed. All widgets are deleted and the program is continued after WGFIN.

The call is: | CALL SENDOK
or: | void sendok (void);

S E N D M B

The routine SENDMB sends a mouse button 2 event to the DISLIN routine DISFIN. It can be used for closing the graphics window.

The call is: | CALL SENDMB
or: | void sendmb (void);

D O E V N T

The routine DOEVNT processes pending events in the widget event queue. This routine should be called during a time intensive calculation to give a user the chance to interact with the widget program. For example to check if the user has canceled the calculation.

The call is: | CALL DOEVNT
or: | void doevnt (void);

## 15.5 Dialog Routines

Dialog routines are collections of widgets that can be used to display messages, to get text strings, to get filenames from a file selection box and to get selections from a list of items. Dialog routines can be used independently from the routines WGINI and WGFIN.

D W G M S G

The routine DWGMSG displays a message.

The call is: | CALL DWGMSG (CSTR)
or: | void dwgmsg (const char *cstr);

CSTR | is a character string that will be displayed in a message box. Multiple lines can be separated by the character '|'.

D W G B U T

The routine DWGBUT displays a message that can be answered by the user with 'Yes' or 'No'.

The call is: | CALL DWGBUT (CSTR, IVAL)
or: | int dwgbut (const char *cstr, int ival);

CSTR | is a character string that will be displayed in a message box. Multiple lines can be separated by the character '|'.
IVAL | is the returned answer of the user. IVAL = 1 means 'Yes', IVAL = 0 means 'No'. IVAL is also used to initialize the button.

D W G T X T

The routine DWGTXT creates a dialog widget that can be used to prompt the user for input.

The call is: | CALL DWGTXT (CLAB, CSTR)
or: | char *dwgtxt (const char *clab, const char *cstr);

CLAB | is a character string that will be displayed in the dialog widget.
CSTR | is a character string that is used to initialize the text field. After the call to DWGTXT, CSTR returns the user input. For the C Routine, the user input is returned as function value. The returned pointer is allocated by malloc and can be freed by a user.

D W G F I L

The routine DWGFIL creates a file selection box that can be used to get a filename.

The call is: | CALL DWGFIL (CLAB, CFIL, CMASK)
or: | char *dwgfil (const char *clab, const char *cfil, const char *cmask);

CLAB | is a character string that will be displayed in the dialog widget.
CFIL | is the returned filename selected by the user. The variable can also be used to pre-define a filename. For the C Routine, the user input is returned as function value. The returned pointer is allocated by malloc and can be freed by a user.
CMASK | specifies the search pattern used in determining the files to be displayed in the file selection box.

D W G L I S

The routine DWGLIS creates a dialog widget that can be used to to get a selection from a list of items.

The call is: | CALL DWGLIS (CLAB, CLIS, ISEL)
or: | int dwglis (const char *clab, const char *clis, int isel);

CLAB | is a character string that will be displayed in the dialog widget.
CLIS | is a character string that contains the list elements. Elements must be separated by the character '|'.
ISEL | defines the pre-selected element and contains the selected element after return. Element numbering begins with the number 1.

D W G E R R

The routine DWGERR returns a status for the routines DWGFIL, DWGTXT and DWGLIS. The routine can be used to check directly after the routines above if the OK button is pressed in the routines.

The call is: | CALL DWGERR (ISTAT)
or: | int dwgerr ();

ISTAT | is a returned status. If ISTAT = 0, the OK button in the routines DWGFIL, DWGTXT and DWGLIS is pressed. Otherwise, the CANCEL button is pressed, or an error occured.

## 15.6 Example

The following short program creates some widgets and requests the values of the widgets.

          PROGRAM EXA1
          CHARACTER*80 CL1,CFIL

          CL1='Item1|Item2|Item3|Item4|Item5'
          CFIL=' '

          CALL SWGTIT ('EXAMPLE 1')
          CALL WGINI  ('VERT', IP)

          CALL WGLAB  (IP, 'File Widget:', ID)
          CALL WGFIL  (IP, 'Open File', CFIL, '*.c', ID_FIL)

          CALL WGLAB  (IP, 'List Widget:', ID)
          CALL WGLIS  (IP, CL1, 1, ID_LIS)

          CALL WGLAB  (IP, 'Button Widgets:', ID)
          CALL WGBUT  (IP, 'This is Button 1', 0, ID_BUT1)
          CALL WGBUT  (IP, 'This is Button 2', 1, ID_BUT2)

          CALL WGLAB  (IP, 'Scale Widget:', ID)
          CALL WGSCL  (IP, ' ', 0., 10., 5., 1, ID_SCL)

          CALL WGOK   (IP, ID_OK)
          CALL WGFIN

          CALL GWGFIL (ID_FIL, CFIL)
          CALL GWGLIS (ID_LIS, ILIS)
          CALL GWGBUT (ID_BUT1, IB1)
          CALL GWGBUT (ID_BUT2, IB2)
          CALL GWGSCL (ID_SCL, XSCL)
          END

The next example displays some widgets packed in two columns.

          PROGRAM EXA2
          CHARACTER*80 CL1,CSTR

          CL1='Item1|Item2|Item3|Item4|Item5'
          CSTR=' '

          CALL SWGTIT ('EXAMPLE 2')
          CALL WGINI  ('HORI', IP)
          CALL WGBAS  (IP, 'VERT', IPL)
          CALL WGBAS  (IP, 'VERT', IPR)

          CALL WGLAB  (IPL, 'Text Widget:', ID)
          CALL WGTXT  (IPL, CSTR, ID_TXT1)
          CALL WGLAB  (IPL, 'List Widget:', ID)
          CALL WGLIS  (IPL, CL1, 1, ID_LIS)
          CALL WGLAB  (IPR, 'Labeled Text Widget:', ID)
          CALL WGLTXT (IPR, 'Give Text:', CSTR, 40, ID_TXT2)
          CALL WGLAB  (IPR, 'Box Widget:', ID)
          CALL WGBOX  (IPR, CL1, 1, ID_BOX)

          CALL WGQUIT (IPL, ID_OK)
          CALL WGOK   (IPL, ID_OK)
          CALL WGFIN
          END

The following example explains the use of callback routines. A list widget is created and the selected list element is displayed in a text widget.

          PROGRAM EXA3
          COMMON /MYCOM1/ ID_LIS,ID_TXT
          COMMON /MYCOM2/ CLIS
          CHARACTER*80 CLIS
          EXTERNAL MYSUB

          CLIS = 'Item 1|Item 2|Item 3|Item 4|Item 5'

          CALL WGINI  ('VERT', IP)
          CALL WGLIS  (IP, CLIS, 1, ID_LIS)
          CALL SWGCBK (ID_LIS, MYSUB)
          CALL WGTXT  (IP, ' ', ID_TXT)
          CALL WGFIN
          END

          SUBROUTINE MYSUB (ID)
    C     ID   is the widget ID of WGLIS ( = ID_LIS)

          COMMON /MYCOM1/ ID_LIS,ID_TXT
          COMMON /MYCOM2/ CLIS
          CHARACTER*80 CLIS, CITEM

          CALL GWGLIS (ID_LIS, ISEL)
          CALL ITMSTR (CLIS, ISEL, CITEM)
          CALL SWGTXT (ID_TXT, CITEM)
          END

The C coding of example 3 is given below:

    #include <stdio.h>
    #include "dislin.h"

    void mysub (int ip);

    static int id_lis, id_txt;
    static char clis[] = "Item 1|Item 2|Item 3|Item 4|Item 5";

    main()
    { int  ip;

      swgtit ("Example 3");

      ip      = wgini  ("VERT");
      id_lis  = wglis (ip, clis, 1);
      swgcbk (id_lis, mysub);

      id_txt = wgtxt (ip, " ");
      wgfin ();
    }

    void mysub (int id)
    { int isel;
      char *citem;

      isel = gwglis (id_lis);
      citem = itmstr (clis, isel);
      swgtxt (id_txt, citem);
    }

The last example creates a table widget.

          PROGRAM EXA4
          REAL XRAY(50),XWRAY(6)
          CHARACTER*80 CSTR
          DATA XWRAY/-10.,-18.,-18.,-18.,-18.,-18./

          DO I=1,50
            XRAY(I)=I
          END DO

          CALL SWGWTH (100)
          CALL SWGTIT ('DISLIN Table Widget')

          CALL WGINI ('VERT',IP)

          CALL SWGOPT ('BOTH','HEADER')
          CALL SWGTYP ('NOSCROLL', 'TABLE')
          CALL SWGRAY (XWRAY, 6, 'TABLE')
          CALL WGTBL (IP,10,5,ID_TBL)

          CALL SWGTBS (ID_TBL, 'Table', 0, 0, 'VALUE')

          DO I=1,10
            IF (I.EQ.10) THEN
              WRITE(CSTR, '(A,I2)') 'R',I
            else
              WRITE(CSTR,'(A,I1)') 'R',I
            END IF
            CALL SWGTBS (ID_TBL, CSTR, I, 0, 'VALUE')
          END DO

          DO I=1,5
            WRITE(CSTR, '(A,I1)') 'C',I
            CALL SWGTBS (ID_TBL, CSTR, 0, I, 'VALUE')
          END DO

          CALL SWGTBL(ID_TBL, XRAY, 50, 2, 0, 'CTABLE')

          CALL WGOK (IP, ID_OK)
          CALL WGFIN
          END

Next | Previous | Contents