SECTION 2.2 - THE MENU AREA VIEW-OBJECT ROUTINES
2.2.1 INTRODUCTION
The menu area view-object provides an area containing a menu from which items may be selected by the user by means of the mouse. Typically, an application will use the same menu area for a series of different menus. The menu area has an optional title. It also has an optional extra menu item situated below the other menu items and separated from them. This item is typically used either as a 'Quit' item or as an item which will instruct the program to return to the previously displayed menu. The menu area also has an 'active strip' at the top of the area.The following sets of routines are available:
Creating and Handling a Menu Area View-Object
2.2.2 CREATING AND HANDLING A MENU AREA VIEW-OBJECT
2.2.2.1 Introduction
The following routines are available:
Create a menu area view-object - xdl_menu_area
Set up a new menu - xdl_menu_area_setmenu
Get the selected item number - xdl_menu_area_getitem
Get position of selected item - xdl_menu_area_getrootxy
Get menu area size requirements - xdl_menu_area_getsize
2.2.2.2 Create a menu area view-object - xdl_menu_area
The routine xdl_menu_area (xdlf_menu_area) is used to create a new menu area view-object. The maximum lengths for text strings and the maximum number of items are give. The actual menu items are subsequently added using the xdl_menu_area_setmenu (xdlf_menu_area_setmenu) routine.
Fortran call:
CALL XDLF_MENU_AREA (IVH, IVHPARENT, IX, IY, ICSET, MAXITEMS,
+ MAXLEN, IFONT, IQUIT, MAXTITL, MINWIDTH,
+ MINHEIGHT, 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)
MAXITEMS (R) Max. no. of menu items (see max_items)
MAXLEN (R) Max. no. chars in an item name
(see max_name_chars)
IFONT (R) Font type (1->5 verysmall->extralarge)
(see font_type)
IQUIT (R) =1 allow, =0 disallow quit box (see quit_box)
MAXTITL (R) Maximum title length (see max_title_len)
MINWIDTH (R) Minimum width or 0 (see min_width)
MINHEIGHT (R) Minimum height or 0 (see min_height)
IERR (W) Returns status from xdl_menu_area call
'C' call:
int xdl_menu_area (vh, vh_parent, x, y, cset, max_items, max_name_chars,
font_type, quit_box, max_title_len, min_width, min_height)
Parameters:
int vh; /* User selected view-object handle (R)*/
int vh_parent; /* View-object handle for the parent view-object,
if 0 then a base frame is created to
enclose the menu area 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 max_items; /* Maximum number of possible items in the
menu (R)*/
int max_name_chars; /* Maximum number of characters in a menu item
name string (R)*/
int font_type; /* Font type for menu items and title to be used
in calculating the size requirements:
1 = very small
1 = small
2 = medium
3 = large
4 = extra-large (R)*/
int quit_box; /* = 1, Allow room for a menu 'quit/return'
item box in addition to the max_items other
menu items.
The string for the quit box must not exceed
max_name_chars in length; = 0, do not (R)*/
int max_title_len; /* Maximum length of the title string in
characters; 0 if no title will be used (R)*/
int min_width; /* The minimum width for the Menu area
view-object. This will be used only if it
exceeds the width calculated from the details
supplied above. If 0 then the calculated
width will be used (R)*/
int min_height; /* The minimum height for the Menu area
view-object. This will be used only if it
exceeds the height calculated from the
details supplied above. If 0 then the
calculated height will be used (R)*/
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Unable to get memory for global data structure
bit 2 set; Unable to get memory for 'text' array
bit 3 set; Unable to get memory for menu item details array
bit 4 set; Unable to get memory for copy of title
bit 5 set; A required font not available
2.2.2.3 Set up a new menu - xdl_menu_area_setmenu
The routine xdl_menu_area_setmenu (xdlf_menu_area_setmenu) is used to set an initial or new menu within a previously created menu area view-object. The length of the text strings and the number of items must be within the limits set for the menu area but the routine takes care of the layout of the items on the displayed menu.
Fortran call:
CALL XDLF_MENU_AREA_SETMENU (IVH, NITEMS, XDLSTR(NAMES), NAMLEN,
+ XDLSTR(TITLE), ITLEN, XDLSTR(QUITNAM),
+ IQLEN, IFONT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
NITEMS (R) Number of menu items (see num_items)
NAMES (R) Fortran array of character strings containing
the menu item names.
[CHARACTER*NAMLEN NAMES(NITEMS)].
** Pass address using XDLSTR function **
(see names)
NAMLEN (R) Length of the menu item names character strings
(Must be >0 cf name_len)
TITLE (R) Title character string (see title)
** Pass address using XDLSTR function **
ITLEN (R) Length of title string if > 0; -1 if no title
(cf title_len)
QUITNAM (R) Quit-box character string (see quit_name)
** Pass address using XDLSTR function **
IQLEN (R) Length of quit-box string if > 0; -1 if no
quit-box (cf quit_len)
IFONT (R) Font type (1 to 4 small to extralarge or 0 for
largest that there is room for) (see font_type)
IERR (W) Returns the status from xdl_menu_area_setmenu call
'C' call:
int xdl_menu_area_setmenu (vh, num_items, names, name_len, title,
title_len, quit_name, quit_len, font_type)
Parameters:
int vh; /* View-object handle (R)*/
int num_items; /* No. of items in the menu (R)*/
char * names; /* Item 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) (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) */
char * title; /* Title string (R)*/
int title_len; /* If 0 then the length of the title string is
determined assuming that 'title' is a null terminated
string; if > 0 it is the length of the title string;
if = -1 then do not output a title ('title' ignored
in this case) (R) */
char * quit_name;/* Quit box name string (R)*/
int quit_len; /* If 0 then the length of the quit box string is
determined assuming that 'quit_name' is a null
terminated string; if > 0 it is the length of the
title string; if = -1 then do not output a quit
box ('quit_name' ignored in this case) (R) */
int font_type; /* Font type: if 1-5, use very-small/small/medium/large/
extra-large font respectively if space permitting.
(If not the the font size will be reduced till a
suitable one is found); if 0, use the largest
font which fits (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.2.2.4 Get the selected item number - xdl_menu_area_getitem
The routine xdl_menu_area_getitem (xdlf_menu_area_getitem) returns the item number of the last selected menu item. It will normally be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that a menu_area view-object has returned input.
Fortran call:
CALL XDLF_MENU_AREA_GETITEM (IVH, ITEM, IQUIT)
Parameters: IVH (R) The view-object handle (see vh) ITEM (W) Returns the menu item number (see item) IQUIT (W) Returns 0 for normal item, 1 for quit box (see quit)
'C' call: int xdl_menu_area_getitem (vh, item, quit)
Parameters: int vh; /* View-object handle (R)*/ int *item; /* Returns the selected item number (W) */ int *quit; /* Returns 0 for a normal item, 1 if quit box (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.2.2.5 Get position of selected item - xdl_menu_area_getrootxy
The routine xdl_menu_area_getrootxy (xdlf_menu_area_getrootxy) gets the root x, y position of the last selected menu item; this is taken as being half way up right hand side of the item box. It may be used for example as a focus for an error message if required. It will normally be called after a call to the routine xdl_menu_area_getitem (xdlf_menu_area_getitem).
Fortran call:
CALL XDLF_MENU_AREA_GETROOTXY (IVH, IXROOT, IYROOT)
Parameters: IVH (R) The view-object handle (see vh) IXROOT (W) Returns the root x position (see xroot) IYROOT (W) Returns the root y position (see yroot)
'C' call: int xdl_menu_area_getrootxy (vh, xroot, yroot)
Parameters:
int vh; /* View-object handle (R)*/
int *xroot; /* Returns the x root position (half way up right hand
side of item box) of the last selected menu item) (W)*/
int *yroot; /* Returns the y root position cf xroot (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.2.2.6 Get menu area size requirements - xdl_menu_area_getsize
The routine xdl_menu_area_getsize (xdlf_menu_area_getsize) is used to calculate the size requirements for a menu area based on the maximum lengths of text strings required and the maximum number of menu items required.
Fortran call:
CALL XDLF_MENU_AREA_GETSIZE (MAXITEMS, MAXNAM, IFONT, IQUIT,
+ MAXTITL, IWIDTH, IHEIGHT)
Parameters:
MAXITEMS (R) Max. no. of menu items (see max_items)
MAXNAM (R) Max. item name length (chars)
(see max_name_chars)
IFONT (R) Font type (1-4) (see font_type)
IQUIT (R) =1 allow quit box , =0 do not (see quit_box)
MAXTITL (R) Max. title length, 0 if no title
(see max_title_len)
IWIDTH (W) Returns the width required (see w)
IHEIGHT (W) Returns the height required (see h)
'C' call:
void xdl_menu_area_getsize (max_items, max_name_chars, font_type,
quit_box, max_title_len, w, h)
Parameters:
int max_items; /* Maximum number of possible items in the
menu (R)*/
int max_name_chars; /* Maximum number of characters in a menu item
name string (R)*/
int quit_box; /* = 1, Allow room for a menu 'quit/return'
item box in addition to the max_items other
menu items.
The string for the quit box must not exceed
max_name_chars in length; = 0, do not (R)*/
int font_type; /* Font type for menu items and title to be
used in calculating the size requirements:
1 = very small font,
2 = small font,
3 = medium font,
4 = large font,
5 = extra-large font (R)*/
int max_title_len; /* Maximum length of the title string in
characters; 0 if no title will be used (R)*/
int *w; /* Returns the width required (0 if font not
found) (W)*/
int *h; /* Returns the height required (0 if font not
found) (W)*/
Return: None
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998