SECTION 2.4 - THE I/O WINDOW VIEW-OBJECT ROUTINES
2.4.1 INTRODUCTION
The I/O window view-object provides an area for the output of text from the program and input of text strings by the user when required (e.g. for a question and answer sequence). The I/O window has an 'active strip' at the top to indicate whether or not the program is waiting for a reply string to be input by the user. When the program is waiting for input, then the message 'Input reply' is displayed in the active strip. Options are available for text editing, selecting/pasting, command recall and window scrolling.The following sets of routines are available:
Creating and Handling an I/O Window View-Object
2.4.2 CREATING AND HANDLING AN I/O WINDOW VIEW-OBJECT
2.4.2.1 Introduction
The following routines are available:
Create an I/O window view-object - xdl_io_window
Output a text string - xdl_io_window_print
Get an input text string - xdl_io_window_getstring
Reset active strip message - xdl_io_window_input_message
Set keyboard focus - xdl_io_window_set_focus
Get a root window position - xdl_io_window_rootxy
Calculate size requirements - xdl_io_window_getsize
2.4.2.2 Create an I/O window view-object - xdl_io_window
The routine xdl_io_window (xdlf_io_window) is used to create a new I/O window view-object. The user may specify the size of the window in pixels or in terms of the required numbers of rows and columns of characters.
Fortran call:
CALL XDLF_IO_WINDOW (IVH, IVHPARENT, IX, IY, ICSET, NCOLS,
+ NROWS, MINW, MINH, IFONT, NSCROLL, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVHPARENT (R) View-object handle for parent 0=none
(see vh_parent)
IX (R) X position (may be -1 if no parent) (see x)
IY (R) Y position (may be -1 if no parent) (see y)
ICSET (R) Colorset number (see cset)
NCOLS (R) No. of cols of characters or 0 (see ncols)
NROWS (R) No. of rows of characters or 0 (see nrows)
MINW (R) Minimum width in pixels (see min_width)
MINH (R) Minimum height in pixels (see min_height)
IFONT (R) Font type (1->5 very-small->extra-large)
(see font_type)
NSCROLL (R) The number of pages (of nrows lines) to be
saved for scrolling option (0 if no scrolling)
IERR (W) Returns status from xdl_io_window call
'C' call:
int xdl_io_window (vh, vh_parent, x, y, cset, ncols, nrows, min_width,
min_height, font_type, nscroll)
Parameters:
int vh; /* User selected view-object handle (R)*/
int vh_parent; /* View-object handle for the parent base frame,
if 0 then a base level frame is created to
enclose the i/o window view-object (R)*/
int x; /* x coordinate for the view-object.
If no parent may be -1 to give default x (R)*/
int y; /* y coordinate for the view-object.
If no parent may be -1 to give default y (R)*/
int cset; /* Number of the colorset to be used -
normally 0 (R)*/
int ncols; /* Number of columns of characters (if 0 then
this will be calculated from min_width which
must then be given a value > 0. (R)*/
int nrows; /* Number of rows of characters (if 0 then
this will be calculated from min_height which
must then be given a value > 0. (R)*/
int min_width; /* Minimum window width in pixels. If this is
greater than the width calculated from the
number of character columns requirement then
this value will be used as the window width
(R)*/
int min_height; /* Minimum window height in pixels. If this is
greater than the height calculated from the
number of character rows requirement then
this value will be used as the window height
(R)*/
int font_type; /* Font type (1-5) for very_small, small, medium,
large or extra-large font. (R)*/
int nscroll; /* No. of pages which may be back scrolled;
0 if no scrolling */
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Memory allocation error
2.4.2.3 Output a text string - xdl_io_window_print
The routine xdl_io_window_print (xdlf_io_window_print) is used to output a text string to an I/O window view object. The string for the C routine may contain newline characters and the Fortran routine has options for newlines at the start and/or end of the string.
Fortran call:
CALL XDLF_IO_WINDOW_PRINT (IVH, XDLSTR(STRING), LEN, NEWLIN,
+ IERR)
Parameters:
IVH (R) View-object handle (see vh)
STRING (R) The string to be printed (see string)
** Pass the address using the XDLSTR function **
LEN (R) Length of the string (>0) (cf len_str)
NEWLIN (R) =0 no newlines, =1 newline before printing the
string,
=2 newline after printing the string, =3 newlines
before and after printing the string
IERR (W) Returns the status from xdl_io_window_print call
'C' call: int xdl_io_window_print (vh, string, len_str)
Parameters:
int vh; /* The xdl_io_window view-object handle (R)*/
char string[]; /* The string to be printed
Note: \f, \r and \v will all be treated as \n
(newline)
\b is ignored
\t (tab) is converted to a space
(R)*/
int len_str; /* The length of the string. If the string is null
terminated, then 0 may be given and the length
of the string will then be determined by the
routine (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.4.2.4 Get an input text string - xdl_io_window_getstring
The routine xdl_io_window_getstring (xdlf_io_window_getstring) is used to return an input text string. It will normally be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that an I/O window view-object has returned input.
Fortran call:
CALL XDLF_IO_WINDOW_GETSTRING (IVH, XDLSTR(STRING), MAXLEN,
+ IERR)
Parameters:
IVH (R) View-object handle (see vh)
STRING (W) Returned string (see string)
** Pass address using the XDLSTR function **
MAXLEN (R) Maximum allowed length for the returned string
( > 0) (cf max_len)
IERR (W) Returns status from xdl_io_window_getstring call
'C' call: int xdl_io_window_getstring (vh, string, max_len)
Parameters:
int vh; /* View-object handle (R)*/
char string[]; /* Returned string (W)*/
int max_len; /* if >0 Maximum length of returned string allowed
(excluding terminating null - string must be
at least max_len + 1 characters in length)
if <0 abs(max_len) characters will be returned padded
with blanks if needed (for 'fortran' use) (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.4.2.5 Reset active strip message - xdl_io_window_input_message
The routine xdl_io_window_input_message (xdlf_io_window_input_message) is used to reset the message which will appear in the active strip when input is requested When the I/O window view-object is created, the default message is 'Input reply'.
Fortran call:
CALL XDLF_IO_WINDOW_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE),
+ LEN, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MESSAGE (R) Character string containing the message
(see message)
** Pass address using the XDLSTR function **
LEN (R) Length of the message string - must be >0
(cf len) (max 60 chars)
IERR (W) Returns status from xdl_io_window_input_message
call
'C' call: int xdl_io_window_input_message (vh, message, len)
Parameters:
int vh; /* View-object handle (R)*/
char *message; /* Message string (max of 60 chars long) (R)*/
int len; /* Length of the message string; if 0 then length
will be found assuming a null terminated string
(R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.4.2.6 Set keyboard focus - xdl_io_window_set_focus
The routine xdl_io_window_set_focus (xdlf_io_window_set_focus) is used to reset the keyboard focus to the i/o window. If the window is not currently viewable, an attempt will be made again after a requested number of milliseconds and this will be repeated if needed up to a maximum requested number of times. This procedure may be needed, for example, if a new i/o window view-object has just been created.
Fortran call:
CALL XDLF_IO_WINDOW_SET_FOCUS (IVH, MSEC, NTRY, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MSEC (R) If window not currently visable, retry after 'MSEC'
milliseconds
NTRY (R) Maximum no. of retries to attempt.
IERR (W) Returns status from xdl_io_window_set_focus call
'C' call: int xdl_io_window_set_focus (vh, msec, ntry)
Parameters:
int vh; /* View-object handle (R)*/
int msec; /* If window not currently visable, retry after
'msec' milliseconds (R)*/
int ntry; /* Maximum no. of retries to attempt (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.4.2.7 Get a root window position - xdl_io_window_rootxy
The routine xdl_io_window_rootxy (xdlf_io_windowrootxy) gets the root window x, y position at the right hand side of the io_window on the line above the one currently containing the cursor. It is basically intended to be used as a position for an error message popup-notice if the program finds some kind of error in an input text string.
Fortran call:
CALL XDLF_IO_WINDOW_ROOTXY (IVH, IXROOT, IYROOT, IERR)
Parameters: IVH (R) View-object handle (see vh) IXROOT (W) Returns the required x root position (see xroot) IYROOT (W) Returns the required y root position (see yroot) IERR (W) Returns status from xdl_io_window_rootxy call
'C' call: int xdl_io_window_rootxy (vh, xroot, yroot)
Parameters:
int vh; /* View-object handle (R)*/
int *xroot; /* Returns the required xroot position e.g for use with
an error notice after the input of an incorrect string
(W)*/
int *yroot; /* Returns the required yroot position (W)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.4.2.8 Calculate size requirements - xdl_io_window_getsize
The routine xdl_io_window_getsize (xdlf_io_window_getsize) is used to get the required size for an I/O window view-object given the numbers of rows and columns of characters required.
Fortran call:
CALL XDLF_IO_WINDOW_GETSIZE (NCOLS, NROWS, IFONT, NSCROLL, IWIDTH,
+ IHEIGHT)
Parameters:
NCOLS (R) No. of cols of characters or 0 (see ncols)
NROWS (R) No. of rows of characters or 0 (see nrows)
IFONT (R) Font type (1->5 very-small->extra-large)
(see font_type)
NSCROLL (R) No. of scrolling pages or 0 if no scrolling;
(any value >0 has the same effect)
IWIDTH (W) Returns the width required (see w)
IHEIGHT (W) Returns the height required (see h)
'C' call: void xdl_io_window_getsize (ncols, nrows, font_type, nscroll, w, h)
Parameters:
int ncols; /* Number of columns of characters ( > 0 ) (R)*/
int nrows; /* Number of rows of characters ( > 0 ) (R)*/
int font_type; /* Font type (1-5) for very-small, small, medium,
large or extra-large font. (R)*/
int nscroll; /* No. of scrolling pages to save */
int *w; /* Returns the width required (W)*/
int *h; /* Returns the height required (W)*/
Return: None
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998