SECTION 2.5 - THE TEXT TABLE VIEW-OBJECT ROUTINES
2.5.1 INTRODUCTION
The text table view-object provides an area for the simple output of text from a program. Text strings may be output at any character position within the window. There is no scrolling. An alternative option allows for the definition of active cells which respond to mouse input.The following sets of routines are available:
Creating and Handling a Text Table View-Object
2.5.2 CREATING AND HANDLING A TEXT TABLE VIEW-OBJECT
2.5.2.1 Introduction
The following routines are available:
Create a text table view-object - xdl_text_table
Create a text cell view-object - xdl_text_table_cell
Output a text string - xdl_text_table_text
Output a symbol - xdl_text_table_symbol
Clear the text table - xdl_text_table_clear
Clear a section - xdl_text_table_clearsect
Reset active strip message - xdl_text_table_input_message
Define an input cell - xdl_text_table_define_cell
Clear input cell(s) - xdl_text_table_clear_cell
Get selected input cell number - xdl_text_table_getinp
Calculate size requirements - xdl_text_table_getsize
Calculate cell text size - xdl_text_table_getcsize
2.5.2.2 Create a text table view-object - xdl_text_table
The routine xdl_text_table (xdlf_text_table) is used to create a new text table 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_TEXT_TABLE (IVH, IVHPARENT, IX, IY, ICSET, NCOLS,
+ NROWS, MINW, MINH, IFONT, 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)
IERR (W) Returns status from xdl_text_table call
'C' call:
int xdl_text_table (vh, vh_parent, x, y, cset, ncols, nrows, min_width,
min_height, font_type)
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)*/
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Unable to allocate required memory
2.5.2.3 Create a text cell view-object - xdl_text_table_cell
The routine xdl_text_table_cell (xdlf_text_table_cell) is used to create a new text table window view-object. In contrast with the standard text table, the user may define active cells within the window which respond to mouse input. An active strip may be displayed if required. 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_TEXT_TABLE_CELL (IVH, IVHPARENT, IX, IY, ICSET, IACT,
+ MAX_CELLS, NCOLS, NROWS, MINW, MINH, IFONT,
+ HIGHL_FN, 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)
IACT (R) Display active strip flag =1 yes, =0 no
MAX_CELLS (R) Maximum no. of input cells needed (0 if none)
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)
HIGHL_FN (R) Subroutine to call when highlighting/unhighlighting
takes place in a cell to allow additional user defined
actions to be carried out.
Call wiil be: CALL HIGHL_FN (IVH, ICELL, IFLAG)
Parameters: IVH (R) The file handle
ICELL (R) The cell number
IFLAG (R) Flag =1 highlight on
=0 highlight off
Note: Will still be called when not in input selection
mode even if the highlight option selected for this
mode via CALL XDLF_TEXT_TABLE_DEFINE_CELL is 0.
IERR (W) Returns status from xdl_text_table call
'C' call:
int xdl_text_table_cell (vh, vh_parent, x, y, cset, iact, max_cells,
ncols, nrows, min_width, min_height, font_type,
highl_fn)
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 iact; /* =1 active strip, =0 no active strip (R)*/
int max_cells; /* Maximum no. of cells allowed (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)*/
void (*highl_fn)(); /* Function to call when highlighting or
unhighlighting takes place in a cell to allow
additional user define actions to be carried
out. (May be a NULL function)
Call: highl_fn (ivh, icell, iflag)
Parameters: int *ivh The file handle (R)
int *icell The cell number (R)
int *iflag Flag =1 highlight on
=0 highlight off
Pointers used for parameters to allow
for Fortran case.
Note: Will still be called when not in input selection
mode even if the highlight option selected for this
mode via CALL XDLF_TEXT_TABLE_DEFINE_CELL is 0.
(R)*/
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Unable to allocate required memory
2.5.2.4 Output a text string - xdl_text_table_text
The routine xdl_text_table_text (xdlf_text_table_text) is used to output a text string to a text table view object.
Fortran call:
CALL XDLF_TEXT_TABLE_TEXT (IVH, XDLSTR(STRING), LEN, IROW, ICOL,
+ IBOLD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
STRING (R) The string to be output (see string)
** Pass the address using the XDLSTR function **
LEN (R) Length of the string (>0) (cf len_str)
IROW (R) Row number for the output of the text string
(see row)
ICOL (R) Column number for the output of the text string
(see col)
IBOLD (R) Flag =0 normal print, =1 bold print (black)
= 2/3 Red normal/bold print
= 4/5 Yellow normal/bold print
= 6/7 Green normal/bold print
= 8/9 Cyan normal/bold print
= 10/11 Blue normal/bold print
= 12/13 Magenta normal/bols print
IERR (W) Returns the status from xdl_text_table_text call
IERR (W) Returns the status from xdl_text_table_text call
'C' call: int xdl_text_table_text (vh, string, len_str, row, col, bold)
Parameters:
int vh; /* The xdl_text_table view-object handle (R)*/
char string[]; /* The string to be printed (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)*/
int row; /* The row number for outputting the string (R)*/
int col; /* The start column number for outputting the
text string (R)*/
int bold; /* Flag =0 normal print, =1 bold print (black)
= 2/3 Red normal/bold print
= 4/5 Yellow normal/bold print
= 6/7 Green normal/bold print
= 8/9 Cyan normal/bold print
= 10/11 Blue normal/bold print
= 12/13 Magenta normal/bols print
(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
bit 2 set: Position for start of text string outside
window
2.5.2.5 Output a symbol - xdl_text_table_symbol
The routine xdl_text_table_symbol (xdlf_text_table_symbol is used to output a symbol to a text table view object. The symbol lies within the space of a single character and its exact size depends on the character font used for the text output.
Fortran call:
CALL XDLF_TEXT_TABLE_SYMBOL (IVH, ISYMB, IROW, ICOL,
+ ICOLR, IERR)
Parameters:
IVH (R) View-object handle (see vh)
ISYMB (R) Symbol number
= 0 Open circle (within character)
= 1 Disk (within character)
= 2 Disk with black border (within character)
= 3 Open square (within character)
= 4 Filled square (within character)
= 5 Filled square with black border (within character)
= 6 Open square (full character width)
= 7 Filled square (full character width)
= 8 Filled square with black border (full character
width)
= 9 Open rectangle (full character size)
= 10 Filled rectangle (full character size)
= 11 Filled rectangle with black border (full character
size)
IROW (R) Row number for the output of the text string
(see row)
ICOL (R) Column number for the output of the text string
(see col)
ICOLR (R) Colour flag 0 = black
1 = red
2 = yellow
3 = green
4 = cyan
5 = blue
6 = magenta
IERR (W) Returns the status from xdl_text_table_symbol call
IERR (W) Returns the status from xdl_text_table_symbol call
'C' call: int xdl_text_table_symbol (vh, symb, row, col, colr)
Parameters:
int vh; /* The xdl_text_table view-object handle (R)*/
int symb; /* Symbol code
= 0 Open circle (within character)
= 1 Disk (within character)
= 2 Disk with black border (within character)
= 3 Open square (within character)
= 4 Filled square (within character)
= 5 Filled square with black border (within
character)
= 6 Open square (full character width)
= 7 Filled square (full character width)
= 8 Filled square with black border (full
character width)
= 9 Open rectangle (full character size)
= 10 Filled rectangle (full character size)
= 11 Filled rectangle with black border (full
character size)
(R)*/
int row; /* The row number for outputting the string (R)*/
int col; /* The start column number for outputting the
text string (R)*/
int colr; /* Colour code
0 = black
1 = red
2 = yellow
3 = green
4 = cyan
5 = blue
6 = magenta
(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
bit 2 set: Position for symbol outside window
2.5.2.6 Clear the text table - xdl_text_table_clear
The routine xdl_text_table_clear (xdlf_text_table_clear) is used to clear the text table.
Fortran call:
CALL XDLF_TEXT_TABLE_CLEAR (IVH, IERR)
Parameters: IVH (R) View-object handle (see vh) IERR (W) Returns status from xdl_text_table_clear IERR (W) Returns status from xdl_text_table_clear
'C' call: int xdl_text_table_clear (vh)
Parameters: int vh; /* View-object handle (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.5.2.7 Clear a section - xdl_text_table_clearsect
The routine xdl_text_table_clearsect (xdlf_text_table_clearsect) is used to clear a section of the text table.
Fortran call:
CALL XDLF_TEXT_TABLE_CLEARSECT (IVH, IROW1, ICOL1,
+ IROW2, ICOL2, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IROW1 (R) Row number of top left character of area to be
cleared
ICOL1 (R) Column no. of top left character of area to be
cleared
IROW2 (R) Row number of bottom right character of area to be
cleared
ICOL2 (R) Column no. of bottom right character of area to be
cleared
IERR (W) Returns status from xdl_text_table_clearsect
IERR (W) Returns status from xdl_text_table_clearsect
'C' call: int xdl_text_table_clearsect (vh, row1, col1, row2, col2)
Parameters:
int vh; /* View-object handle (R)*/
int row1; /* Row number of top left character of area to be
cleared (R)*/
int col1; /* Column no. of top left character of area to be
cleared (R)*/
int row2; /* Row number of bottom right character of area to be
cleared (R)*/
int col2; /* Column no. of bottom right character of area to be
cleared (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.5.2.8 Reset active strip message - xdl_text_table_input_message
The routine xdl_text_table_input_message (xdlf_text_table_input_message) is used to reset the message which will appear in the active strip when input is requested When the view-object is created, the default message is 'Select input'.
Fortran call:
CALL XDLF_TEXT_TABLE_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_text_table_input_message
call
'C' call: int xdl_text_table_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.5.2.9 Define an input cell - xdl_text_table_define_cell
The routine xdl_text_table_define_cell (xdlf_text_table_define_cell) is used to define an input cell within the text table. This may be selected via the mouse and will be highlighted when the pointer lies within the cell area.
Fortran call:
CALL XDLF_TEXT_TABLE_DEFINE_CELL (IVH, INUM, IROW1, ICOL1,
+ IROW2, ICOL2, IHIGH, IHIGH_N,
+ ICOLR_BG, ICOLR_L,
+ IERR)
Parameters:
IVH (R) View-object handle (see vh)
INUM (R) Cell number (must be in range define when text table set up
IROW1 (R) First row of cell
ICOL1 (R) First column of cell
IROW2 (R) Final row of cell
ICOL2 (R) Final column of cell
IHIGH (R) Highlight option (when text table in input selection mode)
= 1 coloured bg (underline if not colour)
= 2 coloured bg (surround box if not colour)
= 3 underline
= 4 surround box
IHIGH_2 (R) Highlight option when text table not in input selection
mode. As above but may be 0 for non such highlighting
ICOLR_BG (R) Colour for background highlght (1-7) Black, Red, Yellow, Green,
Cyan, Blue, Magenta
ICOLR_L (R) Colour for highlght lines(1-7) Black, Red, Yellow, Green,
Cyan, Blue, Magenta
IERR (W) Returns status from xdl_text_table_define_cell
call
'C' call:
int xdl_text_table_define_cell (vh, num, row1, col1, row2, col2, hightyp,
high_nosel, colr_bg, colr_l)
Parameters:
int vh; /* View-object handle (R)*/
int num; /* Cell number (must be in range define when text
table set up (R)*/
int row1; /* First row of cell (R)*/
int col1; /* First column of cell (R)*/
int row2; /* Final row of cell (R)*/
int col2; /* Final column of cell (R)*/
int hightyp; /* Highlight option (when text table in input
selection mode)
= 1 coloured bg (underline if not colour)
= 2 coloured bg (surround box if not colour)
= 3 underline
= 4 surround box
(R)*/
int high_nosel; /* Highlight option (when text table not in input
selection mode)
As above but may be 0 for no highlighting in this
mode (R)*/
int colr_bg; /* Colour for background highlght (1-7) Black, Red,
Yellow, Green, Cyan, Blue, Magenta (R)*/
int colr_l; /* Colour for highlght lines(1-7) Black, Red, Yellow,
Green, Cyan, Blue, Magenta (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
bit 2 set: Invalid cell number
bit 4 set: Other invalid parameters
2.5.2.10 Clear input cell(s) - xdl_text_table_clear_cell
The routine xdl_text_table_clear_cell (xdlf_text_table_clear_cell) is used to clear an input cell or all input cells within the text table. This dose not affect the text drawn in such areas just the input control.
Fortran call:
CALL XDLF_TEXT_TABLE_CLEAR_CELL (IVH, INUM, IERR)
Parameters:
IVH (R) View-object handle (see vh)
INUM (R) Cell number (must be in range define when text table set up)
or 0 to clear all cells
IERR (W) Returns status from xdl_text_table_clear_cell
call
'C' call: int xdl_text_table_clear_cell (vh, num)
Parameters:
int vh; /* View-object handle (R)*/
int num; /* Cell number (must be in range define when text
table set up) or 0 to claer all cells (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
bit 2 set: Invalid cell number
2.5.2.11 Get selected input cell number - xdl_text_table_getinp
The routine xdl_text_table_getinp (xdlf_text_table_getinp) is used find the cell number of the last input cell that was selected using the mouse.
Fortran call:
CALL XDLF_TEXT_TABLE_GETINP (IVH, INUM, IERR)
Parameters:
IVH (R) View-object handle (see vh)
INUM (W) Last selected cell number 0 if none
IERR (W) Returns status from xdl_text_table_clear_cell
call
'C' call: int xdl_text_table_getinp (vh, num)
Parameters: int vh; /* View-object handle (R)*/ int *num; /* Last selected cell number 0 if none (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.5.2.12 Calculate size requirements - xdl_text_table_getsize
The routine xdl_text_table_getsize (xdlf_text_table_getsize) is used to get the required size for a text table view-object given the numbers of rows and columns of characters required.
Fortran call:
CALL XDLF_TEXT_TABLE_GETSIZE (NCOLS, NROWS, IFONT, 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)
IWIDTH (W) Returns the width required (see w)
IHEIGHT (W) Returns the height required (see h)
'C' call: void xdl_text_table_getsize (ncols, nrows, font_type, 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 *w; /* Returns the width required (W)*/
int *h; /* Returns the height required (W)*/
Return: None
2.5.2.13 Calculate cell text size - xdl_text_table_getcsize
The routine xdl_text_table_getcsize (xdlf_text_table_getcsize) is used to get the required size for a text cell view-object given the numbers of rows and columns of characters required. and whether or not an activestip is to be displayed.
Fortran call:
CALL XDLF_TEXT_TABLE_GETCSIZE (NCOLS, NROWS, IFONT, IACT,
+ 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)
IACT (R) <=0 no active strip, =1 active strip present
IWIDTH (W) Returns the width required (see w)
IHEIGHT (W) Returns the height required (see h)
'C' call: void xdl_text_table_getcsize (ncols, nrows, font_type, iact, 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 iact; /* <=0 no active strip =1 active strip (R)*/
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