CHAPTER 4 - THE PANEL ITEM ROUTINES AND CALLBACKS
4.1 INTRODUCTION
The xdl_panel_item routines provide standard window items which may be used within the coding of view-objects. They differ from the main view-objects in that they are used to serve the internal needs of a view-object rather than being directly called from an application program.The following sets of routines are available:
Panel Choice Item Routines
Panel Button Item Routines
Panel Label Item Routines
Panel Value Item Routines
Panel Slider Item Routines
Panel I/O Item Routines
4.2 PANEL CHOICE ITEM ROUTINES
4.2.1 Introduction
These are routines for creating and handling a panel choice item.
The following routines are available:
Create a panel choice item - xdl_panel_choice
Reset panel choice item - xdl_panel_choice_reset
Get window id - xdl_panel_choice_wid
Get size - xdl_panel_choice_size
4.2.2 Create a panel choice item - xdl_panel_choice
The routine xdl_panel_choice is used to create a panel choice item with a popup menu. The item has a label, an indicator box to indicate a drop down menu and a display of the currently selected menu item. A callback routine is invoked when a menu item is selected.
'C' call:
Panel_object xdl_panel_choice (vh, wid, x, y, label, nstrings, strings,
df_item, font_type, brdr,
min_width, min_height, callback)
Parameters:
int vh; /* View-object handle (R)*/
Window wid; /* Window id of panel choice's parent window (R)*/
int x; /* x position of the panel choice area (R)*/
int y; /* y position of the panel choice area (R)*/
char *label; /* Label for panel choice (null terminated string)
(R)*/
int nstrings; /* Number of items in choice options menu (R)*/
char **strings; /* Pointer to list of null terminated strings with
choice options (R)*/
int df_item; /* Default item number (1 to nstrings) (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int min_width; /* Minimum width of the panel choice item; this will
be used if it is greater than the width calculated
using the length of the strings, font type etc.
(R)*/
int min_height; /* Minimum height of the panel choice item; this will
be used if it is greater than the height calculated
using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned choice
selection (R)*/
/*
Callback: (*callback)(int iv, int item)
iv The offset in the XDL_view_objects array for the parent
view-object to which the panel choice item belongs.
item The selected item number from the popup menu.
*/
Return: None
4.2.3 Reset panel choice item - xdl_panel_choice_reset
The routine xdl_panel_choice_reset is used to reset the selected item for a panel choice item.'C' call: void xdl_panel_choice_reset (panel_object, item)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
choice item was created using
xdl_panel_choice (R)*/
int item; /*The number of the item to select from
1 up (R)*/
Return: None
4.2.4 Get window id - xdl_panel_choice_wid
The routine xdl_panel_choice_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_choice_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.2.5 Get size - xdl_panel_choice_size
The routine xdl_panel_choice_size is used to predetermine the size of a panel choice item.
'C' call:
void xdl_panel_choice_size (max_len, max_string, brdr, font_type,
width, height)
Parameters: int max_len; /* Maximum length of label string */ int max_string; /* Maximum length of menu choice string */ int brdr; /* =1 draw border (1 thick), =0 do not (R)*/ int font_type; /* Font size (1-5) (R)*/ int *width; /* Returns the required width (W)*/ int *height; /* Returns the required height (W)*/
Return: None
4.3 PANEL BUTTON ITEM ROUTINES
4.3.1 Introduction
These are routines for creating and handling a panel button item.
The following routines are available:
Create a panel button item - xdl_panel_button
Set a new button label string - xdl_panel_button_set
Get window id - xdl_panel_button_wid
Get size - xdl_panel_button_size
4.3.2 Create a panel button item - xdl_panel_button
The routine xdl_panel_button creates a panel button item. A callback routine is invoked when the panel button is selected.
'C' call:
Panel_object xdl_panel_button (vh, wid, x, y, label, max_len,
font_type, brdw, min_width, min_height,
bold, cntr, button_number, callback)
Parameters:
int vh; /* View-object handle (R)*/
Window wid; /* Window id of panel button's parent window (R)*/
int x; /* x position of the panel button area (R)*/
int y; /* y position of the panel button area (R)*/
char *label; /* Label for panel button (null terminated string)
(copy will be made) (R)*/
int max_len; /* Maximum no. of characters to be allowed for the
label string (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdw; /* Border width for button (0 upwards) (R)*/
int min_width; /* Minimum width of the panel button item; this
will be used if it is greater than the width
calculated using the length of the label, font
type etc. (R)*/
int min_height; /* Minimum height of the panel button item; this
will be used if it is greater than the height
calculated using the font type etc. (R)*/
int bold; /* =1 bold print, =0 normal (R)*/
int cntr; /* =0 left justified, =1 centered (R)*/
int button_number; /* Button number to pass onto callback routine;
enables the same callback routine to be used
for several buttons if required provided that
each button is assigned a different number (R)*/
void (*callback)(); /* Callback routine when button selected (R)*/
/*
Callback: (*callback)(int iv, int button_number)
iv The offset in the XDL_view_objects array
for the parent view-object to which the
panel button item belongs.
button_number The button number given when the button was
created.
*/
Return: Panel_object for created item.
4.3.3 Set a new button label string - xdl_panel_button_set
The routine xdl_panel_button_set is used to output a new label string in a panel button.'C' call: void xdl_panel_button_set (panel_object, label, len, bold, cntr)
Parameters:
Panel_object panel_object; /*The panel object returned when the label
was created using xdl_panel_button (R)*/
char * label; /*String containing the new label (R)*/
int len; /*Length of string; if 0 then length will
be determined assuming a null terminated
string (R)*/
int bold; /*Bold print flag =1 bold print,
=0 normal (R)*/
int cntr; /*=0 left justified, =1 centered (R)*/
Return: None
4.3.4 Get window id - xdl_panel_button_wid
The routine xdl_panel_button_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_button_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.3.5 Get size - xdl_panel_button_size
The routine xdl_panel_button_size is used to predetermine the size of a panel button item.'C' call: void xdl_panel_button_size (max_len, font_type, brdw, width, height)
Parameters: int max_len; /* Maximum length of label string */ int font_type; /* Font size (1-5) (R)*/ int brdw; /* Border width (R)*/ int *width; /* Returns the required width (W)*/ int *height; /* Returns the required height (W)*/
Return: None
4.4 PANEL LABEL ITEM ROUTINES
4.4.1 Introduction
These are routines for creating and handling a panel label item.
The following routines are available:
Create a panel label item - xdl_panel_label
Set a new panel label string - xdl_panel_label_set
Get window id - xdl_panel_label_wid
Get size - xdl_panel_label_size
4.4.2 Create a panel label item - xdl_panel_label
The routine xdl_panel_label is used to create a panel label item. This merely displays a text string which may be changed when required.
'C' call:
Panel_object xdl_panel_label (vh, wid, x, y, label, max_len,
font_type, brdr,
min_width, min_height, bold)
Parameters:
Window wid; /* Window id of panel label's parent window (R)*/
int x; /* x position of the panel label area (R)*/
int y; /* y position of the panel label area (R)*/
int vh; /* View-object handle (R)*/
char *label; /* Label for panel label (null terminated string)
(copy will be made) (R)*/
int max_len; /* Maximum no. of characters to be allowed for the
label string (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int min_width; /* Minimum width of the panel label item; this will
be used if it is greater than the width calculated
using the length of the label, font type etc. (R)*/
int min_height; /* Minimum height of the panel label item; this will
be used if it is greater than the height calculated
using the font type etc. (R)*/
int bold; /* =1 bold print, =0 normal (R)*/
Return: Panel_object for created item.
4.4.3 Set a new panel label string - xdl_panel_label_set
The routine xdl_panel_label_set is used to output a new label text string for a panel label item.'C' call: void xdl_panel_label_set (panel_object, label, len, bold)
Parameters:
Panel_object panel_object; /*The panel object returned when the label
was created using xdl_panel_label (R)*/
char * label; /*String containing the new label (R)*/
int len; /*Length of string; if 0 then length will be
determined assuming a null terminated
string (R)*/
int bold; /*Bold print flag =1 bold print,
=0 normal (R)*/
Return: None
4.4.4 Get window id - xdl_panel_label_wid
The routine xdl_panel_label_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_label_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.4.5 Get size - xdl_panel_label_size
The routine xdl_panel_label_size is used to predetermine the size of a panel label item.'C' call: void xdl_panel_label_size (max_len, font_type, brdr, width, height)
Parameters: int max_len; /* Maximum length of label string */ int font_type; /* Font size (1-5) (R)*/ int brdr; /* =1 draw border (1 thick), =0 do not (R)*/ int *width; /* Returns the required width (W)*/ int *height; /* Returns the required height (W)*/
Return: None
4.5 PANEL VALUE ITEM ROUTINES
4.5.1 Introduction
These are routines for creating and handling a panel value item.
The following routines are available:
Create a panel value item - xdl_panel_value
Set a new panel value string - xdl_panel_value_set
Get window id - xdl_panel_value_wid
Get size - xdl_panel_value_size
4.5.2 Create a panel value item - xdl_panel_value
The routine xdl_panel_value is used to create a panel value item. This displays a label and an value string. The value string may be changed by the user causing a callback routine to be invoked.
'C' call:
Panel_object xdl_panel_value (vh, wid, x, y, label, valstr, maxv_len,
font_type, brdr,
min_width, min_height, callback)
Parameters:
Window wid; /* Window id of panel value's parent window (R)*/
int x; /* x position of the panel value area (R)*/
int y; /* y position of the panel value area (R)*/
int vh; /* View-object handle (R)*/
char *label; /* Label for panel value (null terminated string) (R)*/
char *valstr; /* Initial value string (null terminated) (R)*/
int maxv_len; /* Maximum no. of characters to be allowed for the
value string (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int min_width; /* Minimum width of the panel value item; this will be
used if it is greater than the width calculated
using the length of the label, length of the value,
font type etc. (R)*/
int min_height; /* Minimum height of the panel value item; this will be
used if it is greater than the height calculated
using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned value
position (R)*/
/*
Callback: (*Callback)(int iv, char * valstr, int len, int max_len)
iv The offset in the XDL_view_objects array for the
parent view-object to which the panel value item
belongs.
valstr Pointer to the returned value string
len Length of the returned value string
max_len Maximum allowed length of a value string
*/
Return: Panel_object for created item.
4.5.3 Set a new panel value string - xdl_panel_value_set
The routine xdl_panel_value_set is used to replace the current panel value string with a new value string.'C' call: void xdl_panel_value_set (panel_object, valstr, len)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
value was created using xdl_panel_value
(R)*/
char * valstr; /*String containing the new value (R)*/
int len; /*Length of string; if 0 then length will be
determined assuming a null terminated
string (R)*/
Return: None
4.5.4 Get window id - xdl_panel_value_wid
The routine xdl_panel_value_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_value_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.5.5 Get size - xdl_panel_value_size
The routine xdl_panel_value_size is used to predetermine the size of a panel value item.
'C' call:
void xdl_panel_value_size (max_len, maxv_len, font_type, brdr, width,
height)
Parameters:
int max_len; /* Maximum length of label string */
int maxv_len; /* Maximum no. of characters to be allowed for the
value string (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int *width; /* Returns the required width (W)*/
int *height; /* Returns the required height (W)*/
Return: None
4.6 PANEL SLIDER ITEM ROUTINES
4.6.1 Introduction
These are routines for creating and handling a panel slider item.
The following routines are available:
Create a panel slider item - xdl_panel_slider
Reset a panel slider position - xdl_panel_slider_reset
Get window id - xdl_panel_slider_wid
Get size - xdl_panel_slider_size
4.6.2 Create a panel slider item - xdl_panel_slider
The routine xdl_panel_slider is used to create a panel slider item. This has a label and a slider bar with a moveable grip box. When the grip box on the slider is moved a callback routine is invoked.
'C' call:
Panel_object xdl_panel_slider (vh, wid, x, y, label, font_type,
travel_len, startpos, brdr,
min_width, min_height, callback)
Parameters:
Window wid; /* Window id of panel slider's parent window (R)*/
int x; /* x position of the panel slider area (R)*/
int y; /* y position of the panel slider area (R)*/
int vh; /* View-object handle (R)*/
char *label; /* Label for panel slider (null terminated string)
(R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int travel_len; /* Travel length of slider (in pixels). The
slider positions will represent travel_len+1
discrete values (R)*/
int startpos; /* Start position of the slider from 0 to
travel_len (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int min_width; /* Minimum width of the panel slider item; this
will be used if it is greater than the width
calculated using the length of the label,
length of the slider, font type etc. (R)*/
int min_height; /* Minimum height of the panel slider item; this
will be used if it is greater than the height
calculated using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned slider
position (R)*/
/*
Callback: (*callback)(int iv, int curpos, int travel_len)
iv The offset in the XDL_view_objects array for
the parent view-object to which the panel
slider item belongs.
cupos The current position of the grip box along
the slider.
travel_len The total travel length along the slider.
*/
Return: None
4.6.3 Reset a panel slider position - xdl_panel_slider_reset
The routine xdl_panel_slider_reset is used to set a new slider position for a panel slider item.'C' call: void xdl_panel_slider_reset (panel_object, islide)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
i/o item was created using xdl_panel_io
(R)*/
int islide; /*The slider position from 0 to 'travel_len'
(R)*/
Return: None
4.6.4 Get window id - xdl_panel_slider_wid
The routine xdl_panel_slider_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_slider_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.6.5 Get size - xdl_panel_slider_size
The routine xdl_panel_slider_size is used to predetermine the size of a panel slider item.
'C' call:
void xdl_panel_slider_size (max_len, font_type, travel_len, brdr,
width, height)
Parameters:
int max_len; /* Maximum length of label string */
int font_type; /* Font size (1-5) (R)*/
int travel_len; /* Travel length of slider (in pixels). The
slider positions will represent travel_len+1
discrete values (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int *width; /* Returns the required width (W)*/
int *height; /* Returns the required height (W)*/
Return: None
4.7 PANEL I/O ITEM ROUTINES
4.7.1 Introduction
These are routines for creating and handling a panel i/o item.
The following routines are available:
Create a panel io item - xdl_panel_io
Set a new panel i/o item prompt - xdl_panel_io_prompt
Clear/reset a panel i/o item - xdl_panel_io_clear
Get window id - xdl_panel_io_wid
Get size - xdl_panel_io_size
4.7.2 Create a panel io item - xdl_panel_io
The routine xdl_panel_io is used to create a panel i/o item. This displays a prompt string and an input reply area. This reply area enables the user to input a character string. If this reply is longer than the reply space available then scrolling will take place. When a string is terminated by the Return or Enter key or if the Escape key is pressed, a callback routine will be invoked.
'C' call:
Panel_object xdl_panel_io (vh, wid, x, y, max_pr, min_rp, max_rp,
font_type, brdr, ch_count,
min_width, min_height, callback)
Parameters:
Window wid; /* Window id of panel i/o item's parent window (R)*/
int x; /* x position of the panel i/o item area (R)*/
int y; /* y position of the panel i/o item area (R)*/
int vh; /* View-object handle (R)*/
int max_pr; /* Max. no. of chars in prompt (R)*/
int min_rp; /* Minimum width of displayed reply field (in
characters) (R)*/
int max_rp; /* Maximum allowed reply string length (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int ch_count; /* =1 show character count, =0 do not (R)*/
int min_width; /* Minimum width of the panel i/o item; this will be
used if it is greater than the width calculated
using the maximum length of the prompt, mimimum
length of the reply field, font type etc. (R)*/
int min_height; /* Minimum height of the panel i/o item; this will be
used if it is greater than the height calculated
using the font type etc. (R)*/
void (*callback)(); /* Callback routine to take returned reply (R)*/
/*
Callback: (*Callback)(int iv, char * reply, int len, int max_rp,
int flag, int iret)
iv The offset in the XDL_view_objects array for the
parent view-object to which the panel value item
belongs.
reply Pointer to the returned value string
len Length of the returned reply string
max_rp Maximum allowed length of a reply string
flag Flag passed on from call to xdl_panel_io_prompt
iret = 1 non-blank string
= 0 blank string
=-1 escape pressed
*/
Return: Panel_object for created item.
4.7.3 Set a new panel i/o item prompt - xdl_panel_io_prompt
The routine xdl_panel_io_prompt is used to set a new prompt and prepare for a new input reply string.'C' call: void xdl_panel_io_prompt (panel_object, prompt, len, flag)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
i/o item was created using xdl_panel_io
(R)*/
char * prompt; /*String containing the new prompt (R)*/
int len; /*Length of prompt; if 0 then length will be
determined assuming a null terminated
string (R)*/
int flag; /*Flag to be passed to callback routine to
identify current prompt etc. */
Return: None
4.7.4 Clear/reset a panel i/o item - xdl_panel_io_clear
The routine xdl_panel_io_clear is used to clear a panel i/o item. It will remain inactive until another call of the routine xdl_panel_io_prompt.'C' call: void xdl_panel_io_clear (panel_object)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
i/o item was created using xdl_panel_io
(R)*/
Return: None
4.7.5 Get window id - xdl_panel_io_wid
The routine xdl_panel_io_wid is used to return the window identifier of the panel item's window.'C' call: void xdl_panel_io_wid (panel_object, wid)
Parameters:
Panel_object panel_object; /*The panel object returned when the panel
item was created (R) */
Window *wid; /*Returns the window identifier (W) */
Return: None
4.7.6 Get size - xdl_panel_io_size
The routine xdl_panel_io_size is used to predetermine the size of a panel I/O item.
'C' call:
void xdl_panel_io_size (max_pr, min_rp, max_rp, font_type, brdr, ch_count,
width, height)
Parameters:
int max_pr; /* Max. no. of chars in prompt (R)*/
int min_rp; /* Minimum width of displayed reply field (in
characters) (R)*/
int max_rp; /* Maximum allowed reply string length (R)*/
int font_type; /* Font type 1 to 5, very-small to extra-large (R)*/
int brdr; /* =1 draw border (1 thick), =0 do not (R)*/
int ch_count; /* =1 show character count, =0 do not (R)*/
int *width; /* Returns the required width (W)*/
int *height; /* Returns the required height (W)*/
Return: None
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998