CHAPTER 5 - XDL_VIEW LAYOUT ROUTINES
5.1 INTRODUCTION
The xdl_view layout routines are designed to assist the layout of view-objects for a program where several objects are to be fitted together to give a tidy looking layout. The basic look of the layout may be preserved and new positions and sizes automatically calculated if the size requirements of any of the individual objects are changed. The basic procedure requires that the layout is defined in terms of pairs of objects and/or previously defined pairs. Each newly defined pair may be in a horizontal or vertical direction. Minimum size requirements are given for the individual objects and recursive procedures are used to calculate the overall size requirement for the layout and to reset the sizes and positions of the individual objects. There is also an option to include a table (regular rows and columns of single objects) as an item of a pair.The following sets of routines are available:
Determining XDL_VIEW Layout Parameters
5.2 DETERMINING XDL_VIEW LAYOUT PARAMETERS
5.2.1 Introduction
The following routines are available:
Initialise lists - xdl_layout_init
Define a single object - xdl_layout_set_single
Give details for a table - xdl_layout_set_table
Give details of layout pair - xdl_layout_set_pair
Determine the layout - xdl_layout
Get object position and size - xdl_layout_get_position
Reset objects in table - xdl_layout_reset_table
Reset single object position - xdl_layout_reset_single
5.2.2 Initialise lists - xdl_layout_init
The routine xdl_layout_init (xdlf_layout_init) is used to initialise the lists of single objects, tables of objects and layout pairs. It must be called before using any other routine and again if it is desired to re-initialise the lists.
Fortran call:
CALL XDLF_LAYOUT_INIT (IERR)
Parameters: IERR (W) Returns status from xdl_layout_init call
'C' call: int xdl_layout_init ()
Parameters:
{
ns = 0;
nt = 0;
np = 0;
return 0;
}
/* Fortran binding: xdlf_layout_init */
void xdlf_layout_init (ierr)
int *ierr;
Return: Status = 0 OK
5.2.3 Define a single object - xdl_layout_set_single
The routine xdl_layout_set_single (xdlf_layout_set_single) is used to give details of each single object to be included in the layout. The minimum needed with and height must be given. Details are also given for what is to happen if the space available for the object is expanded as the layout is determined.
Fortran call:
CALL XDLF_LAYOUT_SET_SINGLE (XDLSTR(NAME), LEN, IW, IH,
+ IHJUST, IVJUST, IERR)
Parameters:
NAME (R) Name by which to identify the single object
(max 20 chars)
** Pass address using the XDLSTR function **
LEN (R) Length of the name (>0)
IW (R) Minimum width needed (e.g. from a ..getsize routine)
IH (R) Minimum height needed
IHJUST (R) Horizontal justification required if width is
expanded.
0=expand allowed,
1=left justify,
2=right justify,
3=centre
IVJUST (R) Vertical justification required if height is
expanded.
0=expand allowed,
1=top justify,
2=bottom justify,
3=centre
IERR (W) Returns status from xdl_layout_set_single call
'C' call: int xdl_layout_set_single(name, len, w, h, hjust, vjust)
Parameters:
char *name; /* Name used to identify the object (max 20 chars) (R)*/
int len; /* Length of the name string (may be 0 if a null terminated
string is passed) (R)*/
int w; /* Minimum width needed for the object (R)*/
int h; /* Minimum height needed for the object (R)*/
int hjust; /* Horizontal justification required if width is
expanded.
0=expand allowed,
1=left justify,
2=right justify,
3=centre (R)*/
int vjust; /* Vertical justification required if height is
expanded.
0=expand allowed,
1=top justify,
2=bottom justify,
3=centre (R)*/
Return: Status = 0 OK, >0 error
=1 name already used
=2 list of single objects full
5.2.4 Give details for a table - xdl_layout_set_table
The routine xdl_layout_set_table (xdlf_layout_set_table) is used to to give details of a table of single objects set out in a series of rows and columns. An equal amount of space will be allocated to each object though the placing of the object within that space will depend on the justification codes given when that single object is defined using xdl_layout_set_single (xdlf_layout_set_single).
Fortran call:
CALL XDLF_LAYOUT_SET_TABLE (XDLSTR(NAME), LEN, NROWS, NCOLS,
+ XDLSTR(NAMES), NAMLEN, IORDER,
+ IWIDTH, IHEIGHT,
+ IERR)
Parameters:
NAME (R) Name used to identify the table (max 20
chars)
LEN (R) Length of the naem string (>0)
NROWS (R) Number of rows of items
NCOLS (R) Number of columns of items
NAMES (R) Fortran array of character strings containing
the single object names.
[CHARACTER*NAMLEN NAMES(NITEMS)].
** Pass address using XDLSTR function **
Can pass a blank string for an absent item.
(see names)
NAMLEN (R) Length of the single object names character strings
(Must be >0 cf name_len)
IORDER (R) Order of items in the names list =1 column fastest,
=2 row fastest
IWIDTH (R) Mimimum width required for the table (may be 0)
IHEIGHT (R) Minimum height required for the table (may be 0)
IERR (W) Returns status from xdl_layout_set_table call
'C' call:
int xdl_layout_set_table (name, len, nrows, ncols, names, name_len,
order, w, h)
Parameters:
char *name; /* Name used to identify the table (max 20 chars) (R)*/
int len; /* Length of the name (may be 0 if a null terminated
string is passed to the routine (R)*/
int nrows; /* Number of rows of objects in the table (R)*/
int ncols; /* Number of columns of objects in the table (R)*/
char * names; /* Single object names - this may either an array of
pointers to num_items null terminated character strings
(len_name=0) or a character string num_items*len_name
in length with each name occupying len_name characters
(left justified and padded to the right with blanks
if needed) Can pass blank name string or null string
for an absent item (R)*/
int name_len; /* Item name length (0 = array of pointers to
null-terminated character strings (e.g. for 'C'
programs) or the length of each name string
(e.g. for Fortran programs). See also the previous
item (R) */
int order; /* Order of items in the names list =1 column fastest,
=2 row fastest (R) */
int w; /* Mimimum width required for the table (may be 0) (R)*/
int h; /* Minimum height required for the table (may be 0) (R)*/
Return: Status = 0 OK, >0 error
=1 name already used
=2 list of tables full
=3 single not defined
=4 single already used
5.2.5 Give details of layout pair - xdl_layout_set_pair
The routine xdl_layout_set_pair (xdlf_layout_set_pair) is used to go give details of a layout pair. The full layout is made by combining pairs in succession. Each pair in the layout may be either horizontal or vertical. Each of the two children of a pair may be another pair, a single object or a table of single objects.
Fortran call:
CALL XDLF_LAYOUT_SET_PAIR (IHORV, JUST, XDLSTR(NAME), LEN,
+ XDLSTR(NAME_CH1), LEN1,
+ XDLSTR(NAME_CH2), LEN2,
+ IWIDTH, IHEIGHT, ISEP, IPCNT, IERR)
Parameters:
IHORV (R) =0 horizontal pair, =1 vertical pair
JUST (R) Layout/justification code for the two children
= 1 Expand both children
= 2 Fix left (top), expand right (bottom)
= 3 Expand left (top), fix right (bottom)
= 4 Left/left (top/top) justify
= 5 Left/right (top/bottom) justify
= 6 Right/right) (bottom/bottom) justify
NAME (R) Name string used to identify the pair (max 20 chars)
** Pass address using XDLSTR function **
LEN (R) Length of the name string (>0)
NAME_CH1 (R) Name string of the first child (previously set
single, table or another pair)
** Pass address using XDLSTR function **
LEN1 (R) Length of name for child 1 (>0)
NAME_CH2 (R) Name string of the second child (previously set
single, table or another pair)
** Pass address using XDLSTR function **
LEN2 (R) Length of name for child 2 (>0)
IWIDTH (R) Minumum width required (may be 0)
IHEIGHT (R) Minimum height required (may be 0)
ISEP (R) Separation required between the halves of the pair
IPCNT (R) Suggested allocation of width/height between the
two halves of the pair if both expanded.
IERR (W) Returns status from xdl_layout_set_pair call
'C' call:
int xdl_layout_set_pair (h_or_v, just, name, len, name_child1, len1,
name_child2, len2, w, h, sep, percent)
Parameters:
int h_or_v; /* =0 horizontal pair, =1 vertical pair (R) */
int just; /* Layout/justification code for the two children
= 1 Expand both children
= 2 Fix left (top), expand right (bottom)
= 3 Expand left (top), fix right (bottom)
= 4 Left/left (top/top) justify
= 5 Left/right (top/bottom) justify
= 6 Right/right) (bottom/bottom) justify
(R) */
char *name; /* Name used to identify the pair (max 20 chars)
(R)*/
int len; /* Length of name; may be 0 if 'name' is a null
terminated string (R) */
char *name_child1; /* Name of first (previously defined) child (R)*/
int len1; /* Length of this name; may be 0 if name_child1
is a null terminated string (R)*/
char *name_child2; /* Name of second (previously defined) child (R)*/
int len2; /* Length of this name; may be 0 if name_child2
is a null terminated string (R)*/
int w; /* Minimum width required (may be 0) (R)*/
int h; /* Minimum height required (may be 0) (R)*/
int sep; /* Separation required between the halves of the
pair (R)*/
int percent; /* Suggested allocation of width/height between the
two halves of the pair if both expanded (R)*/
Return: Status = 0 OK, >0 error
=1 name already used
=2 list of pairs full
=3 child 1 not yet defined
=4 child 1 already used
=5 child 2 not yet defined
=6 child 2 already used
5.2.6 Determine the layout - xdl_layout
The routine xdl_layout (xdlf_layout) is used to determine the layout from the previously defined layout pairs, tables of objects and single objects. The position and size parameters for each individual object can then be found using the routine xdl_layout_get_position (xdlf_layout_get_position)
Fortran call:
CALL XDLF_LAYOUT (XDLSTR(NAME), LEN, IX, IY, IWIDTH, IHEIGHT,
+ IERR)
Parameters:
NAME (R) Name string used to identify the top level
pair for the layout (max 20 chars)
** Pass address using XDLSTR function **
LEN (R) Length of the name string (>0)
IX (R) Required x coordinate for the top left of the layout
IY (R) Required y coordinate for the top left of the layout
IWIDTH (W) Returns the calculated width of the layout
IHEIGHT (W) Returns the calculated height of the layout
IERR (W) Returns status from xdl_layout call
'C' call: int xdl_layout (name, len, x, y, w, h)
Parameters:
char *name; /* Name of the top level pair for the layout (R)*/
int len; /* Length of the name (may be 0 if the name string is
null terminated) (R)*/
int x; /* Required x coordinate for the top left of the layout
(R)*/
int y; /* Required y coordinate for the top left of the layout
(R)*/
int *w; /* Returns the calculated width of the layout (W)*/
int *h; /* Returns the calculated height of the layout (W)*/
Return: Status = 0 OK, >0 error
=1 top level pair not found
5.2.7 Get object position and size - xdl_layout_get_position
The routine xdl_layout_get_position (xdlf_layout_get_position) is used to get the position and size for each individual single object after the layout has been determined using the xdl_layout (xdlf_layout) routine.
Fortran call:
CALL XDLF_LAYOUT_GET_POSITION (XDLSTR(NAME), LEN, IX, IY,
IWIDTH, IHEIGHT, IERR)
Parameters:
NAME (R) Name of the single object
** Pass address using XDLSTR function **
LEN (R) Length of the name string (>0)
IX (W) Returns the x coordinate for the top left of the
single object
IY (W) Returns the y coordinate for the top left of the
single object
IWIDTH (W) Returns the calculated width of the single object
IHEIGHT (W) Returns the calculated height of the single object
IERR (W) Returns status from xdl_layout_get_position call
'C' call: int xdl_layout_get_position (name, len, x, y, w, h)
Parameters:
char *name; /* The name of the single object (R)*/
int len; /* The length of the string (may be 0 if a null terminated
string was given) (R)*/
int *x; /* Returns the x coordinate for the top left of the
single object (W) */
int *y; /* Returns the y coordinate for the top left of the
single object (W) */
int *w; /* Returns the calculated width of the single object (W)*/
int *h; /* Returns the calculated height of the single object (W)*/
Return: Status = 0 OK, >0 error
=1 object not found (or not a single object)
5.2.8 Reset objects in table - xdl_layout_reset_table
The routine xdl_layout_reset_table (xdlf_layout_reset_table) is used to reset the positions of the objects within a table after the required size and position of the table have been determined. It will normally be called internally via the xdl_layout (xdlf_layout) routine but is made available for user access if required just to layout a table.
Fortran call:
CALL XDLF_LAYOUT_RESET_TABLE (XDLSTR(NAME), LEN, IX, IY,
IWIDTH, IHEIGHT, IERR)
Parameters:
NAME (R) Name of the table
** Pass address using XDLSTR function **
LEN (R) Length of the name string (>0)
IX (R) Required x coordinate for the top left of the table
IY (R) Required y coordinate for the top left of the table
IWIDTH (R) Required width of the table
(>= min width required)
IHEIGHT (R) Required height of the table
(>= min height required)
IERR (W) Returns status from xdl_layout_reset_table call
'C' call: int xdl_layout_reset_table (name, len, x, y, w, h)
Parameters:
char *name; /* Name of the table (R)*/
int len; /* Length of the name (may be 0 if the name string is
null terminated (R)*/
int x; /* Required x position for the top left of the table (R)*/
int y; /* Required y position for the top left of the table (R)*/
int w; /* Required width of the table (must be >= minimum width
needed) (R) */
int h; /* Required height of the table (must be >= minimum
height needed) (R) */
Return: Status = 0 OK, >0 error
=1 name not found or not a table
5.2.9 Reset single object position - xdl_layout_reset_single
The routine xdl_layout_reset_single (xdlf_layout_reset_single) is used to reset the position of a single object after the required size and position of the object have been determined. It will normally be called internally via the xdl_layout (xdlf_layout) routine but is made available for user access if required just to reset the position of a single object.
Fortran call:
CALL XDLF_LAYOUT_RESET_SINGLE (XDLSTR(NAME), LEN, IX, IY,
IWIDTH, IHEIGHT, IERR)
Parameters:
NAME (R) Name of the single object
** Pass address using XDLSTR function **
LEN (R) Length of the name string (>0)
IX (R) Required x coordinate for the top left of the object
IY (R) Required y coordinate for the top left of the object
IWIDTH (R) Required width of the object
(>= min width required)
IHEIGHT (R) Required height of the object
(>= min height required)
IERR (W) Returns status from xdl_layout_reset_single call
'C' call: int xdl_layout_reset_single (name, len, x, y, w, h)
Parameters:
char *name; /* Name of the single object (R)*/
int len; /* Length of the name (may be 0 if the name string is
null terminated (R)*/
int x; /* Required x position for the top left of the object (R)*/
int y; /* Required y position for the top left of the object (R)*/
int w; /* Required width of the object (must be >= minimum width
needed) (R) */
int h; /* Required height of the object (must be >= minimum
height needed) (R) */
Return: Status = 0 OK, >0 error
=1 name not found or not a single object
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998