Add, delete, or modify a button on a list
|
WSupported on Windows
|
|
|
|
xcall L_BUTTON(list_id, [subfunction,] args)
Arguments
list_id
The ID of the list that contains or will contain the button. (n)
subfunction
(optional) One of the following: (n)
Add a button to the list. (default)
Delete a button from the list.
Modify a button on the list.
args
One or more arguments, depending on subfunction.
Discussion
L_BUTTON creates, deletes, or modifies a Windows-style button on a list. See the individual subfunctions for details.
On Unix and OpenVMS, this routine is ignored.
See also
Using the button routines for general information on buttons and button sets on windows, tab sets, and lists
xcall L_BUTTON(list_id, [DSB_ADD,] name, [DSB_TEXT|DSB_BITMAP], [type_data], & [method], [elb], [select_char], [position][, tooltip])
Arguments
list_id
The ID of the list you want to add the button to. (n)
name
The name of the button to add (a maximum of 30 characters). (a)
DSB_TEXT | DSB_BITMAP
(optional) The button face type. Pass DSB_TEXT (default) for text or DSB_BITMAP for a graphic. (n)
type_data
(optional) Text for the button face if the type is DSB_TEXT, or the filename of the graphic if the type is DSB_BITMAP. (a)
method
(optional) The name of the method subroutine to invoke. (a)
elb
(optional) The name of the executable library (.elb) that contains method. (a)
select_char
(optional) The quick-select character. (a)
position
(optional) The position the button will be inserted in the button set. (a or n)
tooltip
(optional) The text of a ToolTip to be displayed when the mouse pointer rests over the button. (a)
Discussion
The DSB_ADD subfunction of L_BUTTON enables you to add a button to a list. If there are no existing buttons, a default button set is created. By default, button sets are placed at the bottom of the list, are left-justified, and can have as many buttons on a row as will fit before the row wraps. You can change these defaults with L_BUTTONSET.
Buttons are not included in the list’s tabbing order. In order to select a button, it must either be clicked or invoked using its quick-select character.
For information on the arguments for this subroutine, see the DSB_ADD Discussion. All the comments in that section (which discuss arguments for windows and tab sets), apply to lists as well.
Examples
The following example adds an OK button named “I_OK.” When the button is selected, standard termination processing occurs. The OK button has the quick-select character “K”, so when Alt+K is pressed, a click of the OK button is simulated. If there are other buttons on the list, this button will be added to the end of the button set. Note that we didn’t include “DSB_ADD”. You can omit DSB_ADD when you add a button because DSB_ADD is the default.
xcall l_button(listid, "I_OK", DSB_TEXT, "OK",,, "K")
The next example creates a button named “lookup” with a graphic, lookup.gif, on its face. Clicking this button will invoke the lookup subroutine located in the button.elb library. This button will be added to the beginning of the button set and will have the ToolTip “Enter a customer number.”
xcall l_button(listid, DSB_ADD, "lookup", DSB_BITMAP, "lookup.gif", & "lookup", "button.elb", 1, "Enter a customer number")
xcall L_BUTTON(list_id, DSB_DELETE, name)
Arguments
list_id
The ID of the list that contains the button you want to delete. (n)
name
The name of the button to delete. (a)
Discussion
The DSB_DELETE subfunction of L_BUTTON deletes a button from a list. Remaining buttons are repositioned as if the deleted button had never existed. For example, if the button is the second button of three in a button set, the third button will be moved to the second button position.
Name is not case sensitive. If no button with the specified name exists, Toolkit generates a fatal error.
Examples
The following example deletes a button named lookup.
xcall l_button(wndid, DSB_DELETE, "lookup")
xcall L_BUTTON(list_id, DSB_MODIFY, name, [DSB_TEXT|DSB_BITMAP], [type_data], & [method], [elb], [select_char], [position][, tooltip])
Arguments
list_id
The ID of the list that contains the button you want to modify. (n)
name
The name of the button to modify. (a)
DSB_TEXT | DSB_BITMAP
(optional) The new button face type. Pass DSB_TEXT for text or DSB_BITMAP for a graphic. If not passed, the previous value is used. (n)
type_data
(optional) New text for the button if the type is DSB_TEXT, or the filename of the graphic if the type is DSB_BITMAP. (a)
method
(optional) The name of a new method subroutine to invoke. (a)
elb
(optional) The name of the library to find method in. (a)
select_char
(optional) A new quick-select character. (a)
position
(optional) A position you want the button moved to in the button set. (a or n)
tooltip
(optional) The text of a ToolTip to be displayed when the mouse pointer rests over the button. (a)
Discussion
The DSB_MODIFY subfunction of L_BUTTON modifies a button in a list.
For information on the arguments for this subroutine, see the DSB_MODIFY Discussion. All the comments in that section (which apply to windows and tab sets), apply to lists as well.
The following example specifies that the button face for the lookup button will display a new graphic named lookup2.jpg. (We’re assuming that the button previously had a graphic displayed on the button face. If it instead had text on the button face, this example would need to pass DSB_BITMAP as the type argument to prevent “lookup2.jpg” from being interpreted as a text string rather than a filename.)
xcall l_button(listid, DSB_MODIFY, "lookup",, "lookup2.jpg")
The following example changes the button face for the lookup button to the text “Search All”.
xcall l_button(listid, DSB_MODIFY, "lookup", DSB_TEXT, "Search All")
The following example changes the method name and the ELB for the lookup button.
xcall l_button(listid, DSB_MODIFY, "lookup",,, "search_all", "button2.elb")
The following example changes the button so that it no longer calls a method when clicked. Instead, Toolkit will use the first ten characters of the button name to signal a menu entry.
xcall l_button(listid, DSB_MODIFY, "lookup",,, "")
The following example changes the button so that Toolkit no longer looks in a specific ELB for the method.
xcall l_button(listid, DSB_MODIFY, "lookup",,,, "")
The following example changes the quick-select character for the button to “S”. When the user presses Alt+S, the button will be activated.
xcall l_button(listid, DSB_MODIFY, "lookup",,,,, "S")
The following example moves the lookup button to the beginning of the button set. (This will be the far left of top depending the orientation of the button set.)
xcall l_button(listid, DSB_MODIFY, "lookup",,,,,, 1)
The following example moves the lookup button to the position that precedes the I_CANCEL button. Depending on the button set orientation, it will be above or to the left of the I_CANCEL button.
xcall l_button(listid, DSB_MODIFY, "lookup",,,,,, "I_CANCEL")
The following example moves the lookup button to the third position in the button set. Depending on the orientation of the button set, it will be either the third button from the top or the third button from the left.
xcall l_button(listid, DSB_MODIFY, "lookup",,,,,, 3)
The following example moves the lookup button to the end of the button set. Depending on the orientation of the button set, it will either be at the far right or the bottom of the button set.
xcall l_button(listid, DSB_MODIFY, "lookup",,,,,, "")
The following example sets the ToolTip text to “Enter a vendor number”:
xcall l_button(listid, DSB_MODIFY, "lookup",,,,,,, "Enter a vendor number")
