Add, delete, or modify a button on a window or tab set
|
WTSupported in traditional Synergy on Windows
|
|
|
|
xcall B_BUTTON(container_id, [subfunction,] args)
Arguments
container_id
The ID of the window or tab set that contains or will contain the button. (n)
subfunction
(optional) One of the following: (n)
Add a button to the window or tab set. (default)
Delete a button from the window or tab set.
Modify a button in the window or tab set.
args
One or more arguments, depending on subfunction.
B_BUTTON creates, deletes, or modifies a Windows-style button on a window or tab set. See the individual subfunctions for details.
This routine has no effect on applications running on UNIX or OpenVMS or in Synergy .NET. It does, however, save button information on these platforms, so if the window is saved to a window library (by using U_SAVE) and later loaded from that library on a Windows platform in traditional Synergy, the button will be on the window (assuming ISAM-compatible platforms).
See also
Using the button routines for general information on buttons and button sets on windows, tab sets, and lists
xcall B_BUTTON(container_id, [DSB_ADD,] name, [DSB_TEXT|DSB_BITMAP], & [type_data], [method], [elb], [select_char], [position][, tooltip])
Arguments
container_id
The ID of the window or tab set 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 for text (default) 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. If not passed or blank, the button will not have a 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)
The DSB_ADD subfunction of B_BUTTON enables you to add a button to a window or tab set. If there are no existing buttons, a default button set is created. By default, button sets are placed at the bottom of the window or tab set, 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 B_BUTTONSET.)
The window or tab set will expand downward or to the right to accommodate the buttons, which may cause your window to extend beyond the bottom or right side of the application window. Also note that buttons are a standard size; text that exceeds that size will not be visible.
You can specify text or a graphic for the button face:
- If you specify text with DSB_TEXT, use type_data to specify the text to display on the button face.
- If you specify a graphic with DSB_BITMAP, use type_data to specify the name of a graphic file to display on the button face. See Toolkit button graphics for information on supported graphic formats.
If you don’t pass type_data, the button’s name will be displayed on the button’s face.
If you pass method, the method subroutine you pass will be invoked when the button is pressed. The arguments passed to the method are the window ID, button name, and the 20 optional method data arguments passed to I_INPUT, L_INPUT, or any of the other input routines that allow method data arguments (L_SELECT, for example). If you don’t pass method, the first ten characters of the button’s name are used to signal a menu entry when the button is pressed.
If you want Toolkit to look in a specific ELB (executable library) for the method specified by method, pass the filename of the ELB as the elb argument. You can pass the elb argument only if you pass the method argument.
Specifying a quick select character
Select_char is case insensitive. The character specified by select_char does not have to exist in the button’s text, but if it does exist in the button’s text, the first occurrence of select_char will be underlined.
If select_char is specified in a call to B_BUTTON, when the window is being processed by C_PROCESS, I_INPUT, TS_PROCESS, T_VIEW, T_EDIT, AX_INPUT, L_INPUT, or L_SELECT, in many cases pressing Alt+select_char will have the effect of selecting the button. However, this works only for enabled buttons on the currently active window or tab set, which means that a button can be activated only when the application is processing the window or tab set that contains the button. (For information on how Alt+select_char works with composite windows, see Alt+key button activation.)
To avoid confusing the user, we recommend that no two buttons have the same quick-select character. However, if they do, the following rules apply:
- If the buttons with the conflicting quick-select character are on the same window, the quick-select character is assigned to the last button defined. The other buttons will not have a quick-select character.
- Within a tab set, if the tab set container and a contained window define buttons with the same quick-select character, the contained window’s button is assigned the quick-select character, and the button on the tab set will have its quick-select character removed. When a different tab is active, one that does not contain a button with a conflicting quick-select character, the quick-select character will be re-enabled on the tab set button.
- In the case of nested windows, where an input routine is called for a second window within a method for the first window, the quick-select characters for buttons in the first window will still work as long as they are enabled and do not conflict with buttons on the second window. If there is a conflict, the buttons on the second window get the quick-select character until the input process on the second window is exited, at which point any overridden quick-select characters for the first window will be restored.
In the case where the Alt+select_char combination for a button matches that for a menu column, the button gets the quick-select character. Note, however, that pressing Alt and releasing it, followed by the quick-select character, activates the menu column.
Specifying the button’s position
The position argument enables you to insert the button at a given point in the button set:
- To add the button above or to the left of an existing button (depending on the button set’s orientation), pass the name of the existing button. The position argument is not case sensitive.
- To specify a numeric position among existing buttons, pass a position number, which is an index (base 1) that specifies the numeric position (left-to-right or top-to-bottom) among existing buttons. For example, if you pass 1, the button is added as the left-most or top button. If you pass 2, the button will be added as the second button to the left or the second button from the top.
- To add the button to the end of the existing buttons (to the far right or bottom of the button set), pass position as a zero-length or blank alphanumeric value.
Toolkit generates a fatal error if you pass a name for position that doesn’t match any of the existing button names or if you pass a number that’s less than 1 or greater than the number of buttons on the window plus 1.
To add a ToolTip to the button, pass a non-blank value with a length that is greater than zero for tooltip. Note that a ToolTip’s length can be no longer than the operating system’s maximum length for an alphanumeric field. (See DSB_TOOLTIP for information on retrieving ToolTip text.)
Examples
The following example adds an OK button named I_OK with a quick-select character K. When Alt+K is pressed, a click of the OK button is simulated. If there are other buttons on the window, 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 b_button(wndid, "I_OK", DSB_TEXT, "OK",,, "K")
The next example creates a button named lookup with a graphic (lookup.bmp) on its face. Clicking this button will invoke the lookup subroutine located in the button.elb library, and moving the mouse pointer over this button will display the ToolTip “Enter a customer name.” This button will be added to the beginning of the button set because the value 1 is passed as the position argument.
xcall b_button(wndid, DSB_ADD, "lookup", DSB_BITMAP, "lookup.bmp", & "lookup", "button.elb",, 1, "Enter a customer name")
xcall B_BUTTON(container_id, DSB_DELETE, name)
Arguments
container_id
The ID of the window or tab set that contains the button you want to delete. (n)
name
The name of the button to delete. (a)
Discussion
The DSB_DELETE subfunction of B_BUTTON deletes a button from a window or tab set. 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 that name exists, Toolkit generates a fatal error.
Examples
The following example deletes a button named lookup.
xcall b_button(wndid, DSB_DELETE, "lookup")
xcall B_BUTTON(container_id, DSB_MODIFY, name, [DSB_TEXT|DSB_BITMAP], & [type_data], [method], [elb], [select_char], [position][, tooltip])
Arguments
container_id
The ID of the window or tab set 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 type of button face. 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 executable library (.elb) that contains method. (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)
The DSB_MODIFY subfunction of B_BUTTON modifies a button in a window or tab set. Use the name argument to specify the name (case-insensitive) of an existing button. (If name isn’t the name of an existing button, Toolkit will generate a fatal error.)
If a button has no method, you can use the method argument to add a method. If a button does have a method, you can use the method argument to change the method (by passing the new method name) or remove the method (by passing method as blank or zero-length), which causes Toolkit to signal the button name as a menu entry. Note that if you change the method for a button and an ELB has been specified for the previous method, Toolkit will look for the new method in the same ELB unless you also pass the elb argument.
The elb argument enables you to specify a new ELB for a button’s method or instruct Toolkit not to use a previous elb specification. If you pass a new library name as the elb argument, Toolkit will look only in this library (and any libraries linked to it) to find the method specified by method. If you pass elb as blank or zero-length, Toolkit will look in any available module or open ELB (rather than the ELB specified in a previous elb specification). So results depend on the application’s context (which libraries are open). For the DSB_MODIFY subfunction, you can pass elb without passing method and vice versa.
You can change what appears on the button’s face. The type_data argument can be passed without also specifying a type (DSB_TEXT or DSB_BITMAP), and a type can be passed without type_data. But if you pass DSB_TEXT or DSB_BITMAP, you may need to pass type_data to prevent a caption from being interpreted as the filename for a graphic or vice versa. For information on supported graphic formats, see Toolkit button graphics.
The select_char argument enables you to specify a new quick-select character for a button or remove a quick-select character from a button. To specify a new quick-select character, pass the character as select_char. To remove a quick-select character from a button, pass select_char as blank or zero-length. See Specifying a quick select character for more information.
The position argument enables you to move the button to a new position in the button set.
- To move the button above or to the left of an existing button (depending on the button set’s orientation), pass the name of the existing button. The position argument is not case sensitive.
- To specify a numeric position among existing buttons, pass a position number, which is an index (base 1) that specifies the new numeric position (left to right or top to bottom) among existing buttons. For example, if you pass 1, the button will be moved to the left-most or top position in the button set. If you pass 2, the button will be moved to the second position to the left or the second position from the top in the button set.
- To move the button to the end of existing buttons (to the far right or bottom of the button set), pass position as a zero-length or blank alphanumeric value.
Note that Toolkit generates a fatal error if you pass a name for position that doesn’t match any of the existing button names or if you pass a number that’s less than 1 or greater than the number of buttons on the window plus 1.
To modify the ToolTip for a button, pass a non-blank value with a length that is greater than zero for tooltip. Note that a ToolTip’s length can be no longer than the operating system’s maximum length for an alphanumeric field. (See DSB_TOOLTIP for information on retrieving ToolTip text.)
The following example changes the button face for the lookup button. It will display a new graphic named lookup2.png. (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 to prevent Toolkit from interpreting “lookup2.png” as a text string rather than a filename.)
xcall b_button(wndid, DSB_MODIFY, "lookup",, "lookup2.png")
The following example changes the button face for the lookup button to the text “Search All”.
xcall b_button(wndid, DSB_MODIFY, "lookup", DSB_TEXT, "Search All")
The next example changes the method name and the ELB for the lookup button.
xcall b_button(wndid, DSB_MODIFY, "lookup",,, "search_all", "button2.elb")
The next 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 b_button(wndid, DSB_MODIFY, "lookup",,, "")
The next example changes the button so that Toolkit no longer looks in a specific ELB for the method.
xcall b_button(wndid, DSB_MODIFY, "lookup",,,, "")
The next example changes the quick-select character for the button to “s”. When the user presses Alt+S, the button will be activated.
xcall b_button(wndid, DSB_MODIFY, "lookup",,,,, "s")
The next example moves the lookup button to the beginning of the button set. (This will be the far left or top depending the orientation of the button set.)
xcall b_button(wndid, DSB_MODIFY, "lookup",,,,,, 1)
The next 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 b_button(wndid, DSB_MODIFY, "lookup",,,,,, "I_CANCEL")
The next 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 b_button(wndid, DSB_MODIFY, "lookup",,,,,, 3)
The next 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 b_button(wndid, DSB_MODIFY, "lookup",,,,,, "")
The next example sets the ToolTip text to “Enter vendor number”:
xcall b_button(wndid, DSB_MODIFY, "lookup",,,,,,, "Enter vendor number")
