Return information about the buttons in a window
|
WSupported on Windows
|
USupported on Unix
|
|
NSupported in Synergy .NET
|
return = %B_INFO(window_id, subfunction, args)
Return value
return
A value that is specific to the subfunction. (^VAL)
Arguments
window_id
The ID of a window (see Discussion below). (n)
subfunction
One of the following: (n)
Return the number of buttons in a window.
Return the index of the default button.
Return the enabled state of a button.
Return the index (position in button set) of a button.
Return the justification setting for a window’s button set.
Return method information for a button.
Return a button’s name by passing its index.
Return the maximum number of buttons that can be displayed in a button set row or column for a window.
Return the placement (at the bottom of the window or along the right side) for a window’s button set.
Return the quick-select character for a button.
Return the button face type (text or graphic) for a button.
Return the text and length for a button ToolTip.
args
Arguments specific to subfunction.
On Windows and Unix, %B_INFO enables you to return information on a window’s buttons. (On Unix, buttons are not displayed, but they may be defined for a window.) See the individual subfunctions for details.
Note the following:
- For lists, pass the ID of the list’s containing window as window_id. (The ID of a list’s containing window is returned by the D_LCTRID subfunction for L_STATUS.)
- For tab sets, pass the window ID for the tab set.
- For composite windows, passing the composite container window’s ID instructs %B_INFO to return information about the buttons for that window only. For information on buttons for a child window, pass ID of the child window as window_id.
On OpenVMS, this function ignores all parameters and returns a value of 0.
count = %B_INFO(window_id, DSB_COUNT)
Return value
count
The number of buttons in the specified window or a value of 0 if the window has no buttons. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
Discussion
The DSB_COUNT subfunction of %B_INFO returns the number of buttons in the window specified by window_id. If the window has no buttons, DSB_COUNT returns a value of 0.
Examples
The following example returns the number of buttons in wndid:
btn_num = %b_info(wndid, DSB_COUNT)
index = %B_INFO(window_id, DSB_DEFAULT)
Return value
index
The index of the default button, or a value of 0 if no default button has been specified for the window. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
Discussion
The DSB_DEFAULT subfunction of %B_INFO tells you whether the specified window has a default button (if it doesn’t, DSB_DEFAULT returns a value of 0) and returns the index for the default button if there is one. The index (base 1) specifies the numeric position (from left to right or from top to bottom) of the button in relation to other buttons in the window.
Examples
The following example returns the index for the default button for wndid:
btn_dflt = %b_info(wndid, DSB_DEFAULT)
state = %B_INFO(window_id, DSB_ENABLED, button)
Return value
state
Returns TRUE (button is enabled), FALSE (button is disabled), or DSB_INPUT_ONLY (button is enabled only when its window or composite container is being processed). (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
button
The button name (if the passed value is alpha) or the index for the button (if passed value is numeric). (a or n)
Discussion
The DSB_ENABLED subfunction of %B_INFO returns the enabled state of the button specified with button.
You can specify a button by name (case-insensitive) or by numeric position. If you pass a number for button, it is interpreted as an index (base 1) that specifies the position of the button in relation to the other buttons for the window (from left to right, or from top to bottom). Note that a fatal error will occur if you pass a number that is less than 1, a number that is greater than the number of buttons in the window, or an alpha value that is not the name of a button in the window.
For information on the input-only state, see %B_ENABLE.
Examples
In the following example, %B_INFO returns the enabled state of the first button in the window’s button set:
btn_state = %b_info(wndid, DSB_ENABLED, 1)
index = %B_INFO(window_id, DSB_INDEX, name)
Return value
index
The index of the button specified by name, or 0 if the specified button is not found. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
name
The name (case-insensitive) of a button on the window specified by window_id. (a)
Discussion
The DSB_INDEX subfunction of %B_INFO returns the index of the button specified by name, or it returns a value of 0 if there is no such button. The index (base 1) specifies the numeric position (from left to right or from top to bottom) of the button in relation to other buttons in the window.
Examples
In the following example, %B_INFO returns the index for a button named lookup:
btn_index = %b_info(widid, DSB_INDEX, "lookup")
justification = %B_INFO(window_id, DSB_JUSTIFICATION)
Return value
justification
One of the following: (^VAL)
Buttons are left-justified if the button set is placed at the bottom of the window. Buttons are top-justified if the button set is placed vertically along the right side of the window.
Buttons are centered along the bottom or along the right side of the window.
Buttons are right-justified if the button set is placed at the bottom of the window. Buttons are bottom-justified if the button set is placed vertically along the right side of the window.
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
Discussion
The DSB_JUSTIFICATION subfunction of %B_INFO returns the justification setting for a window’s button set. For information on the justification setting for button sets, see .BUTTON_SET.
See also
- B_BUTTONSET routine
- L_BUTTONSET routine
Examples
In the following example, %B_INFO returns the justification setting for the window’s button set:
btn_just = %B_INFO(wndid, DSB_JUSTIFICATION)
address = %B_INFO(window_id, DSB_METHOD, button, [method_name][, elb_path])
or
xcall B_INFO(window_id, DSB_METHOD, button, [method_name][, elb_path])
Return value
address
The address of the button’s method, or 0 if the button has no method. (^VAL)
Arguments
window_id
The ID of a window. (See %B_INFO Discussion.) (n)
button
The button name (if passed as alpha) or the button index (if passed as numeric). (a or n)
method_name
(optional) Returned name of the method (or blank if there is no method for the button). (a)
elb_path
(optional) Returned path for the method’s ELB (or blank if there is no method for the button or if there is no ELB specified for the method). (a)
Discussion
The DSB_METHOD subfunction of %B_INFO tells you if a button has a method and returns the address for the method if there is one. If there is no method, DSB_METHOD returns 0. Optionally, it returns the name (method_name) of the method and the path (elb_path) for the method’s ELB.
You can specify a button by name (case-insensitive) or by numeric position. If you pass a number for button, it is interpreted as an index (base 1) that specifies the position of the button in relation to the other buttons for the window (from left to right, or from top to bottom). A fatal error will occur if you pass a number that is less than 1, a number that is greater than the number of buttons in the window, or an alpha value that is not the name of a button in the window.
See also
.BUTTON routine
Examples
In this example, %B_INFO returns the button method address for the button specified by btn_index and retrieves the button’s name (meth_name), as well as the path (elb_path) to the ELB that contains the button method:
meth_addr = %B_INFO(wndid, DSB_METHOD, btn_index, meth_name, elb_path)
success = %B_INFO(window_id, DSB_NAME, index, name)
or
xcall B_INFO(window_id, DSB_NAME, index, name)
Return value
success
True if index corresponds to a button; false if there is no button for index. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
index
The index of the button to access. This is an index (base 1) that specifies the numeric position (from left to right or from top to bottom) of the button in relation to other buttons in the window. (If index is non-numeric, a fatal Toolkit error will occur.) (n)
name
The returned name of the button specified by index. If no button is found for index, name is filled with spaces. (a)
Discussion
The DSB_NAME subfunction of %B_INFO indicates whether there is a button that corresponds to a specified index and, if there is, retrieves the name of the button:
- If a there is a button for index, DSB_NAME returns true and passes the name of the button in name.
- If there is no button for index, DSB_NAME returns false and fills name with spaces.
Examples
In the following example, %B_INFO tests to for the existence of a button in the window and, if there is, retrieves the name of the first button in the button set:
btn_index = 1 if (%B_INFO(wndid, DSB_NAME, btn_index, btn_name)) . . .
number = %B_INFO(window_id, DSB_PER_ROW_COL)
Return value
number
The maximum number of buttons per row or column, or 0 if no maximum has been set for the specified window’s button set. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
Discussion
The DSB_PER_ROW_COL subfunction of %B_INFO returns the maximum number of buttons that will be displayed in a row or column for the specified window’s button set. If no maximum has been set for the button set, this function returns zero. For information on the maximum setting for rows and for columns, see .BUTTON_SET.
Examples
In the following example, %B_INFO returns the maximum number of buttons that will be displayed in a row (if the button set for wndid is positioned at the bottom of the window) or in a column (if the button set for wndid is positioned vertically along the right side of the window):
num_btns = %B_INFO(wndid, DSB_PER_ROW_COL)
placement = %B_INFO(window_id, DSB_PLACEMENT)
Return value
placement
Returns DSB_BOTTOM (buttons are placed horizontally along the bottom of container) or DSB_RIGHT (buttons are placed vertically along the right side of the container). (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
Discussion
The DSB_PLACEMENT subfunction of %B_INFO returns the placement setting for a window’s button set, telling you whether the buttons are placed horizontally along the bottom of the window or vertically along the right side of the window.
See also
- Defining button placement and the default button for information on setting button placement
- .BUTTON_SET script command for information on setting button placement for a window
- B_BUTTONSET and L_BUTTONSET routines
Examples
In the following example, %B_INFO returns the placement setting for the window specified by wndid:
btn_plc = %b_info(wndid, DSB_PLACEMENT)
value = %B_INFO(window_id, DSB_SELECTCHAR, button[, char])
or
xcall B_INFO(window_id, DSB_SELECTCHAR, button[, char])
Return value
value
The ASCII value of the quick-select character for the button (specified with button), or 0 if the button has no quick-select character. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
button
The button name (if passed as alpha) or the button index (if passed as numeric). (a or n)
char
(optional) The returned quick-select character for the specified button, or %char(0) if the button has no quick-select character. (a)
Discussion
The DSB_SELECTCHAR subfunction of %B_INFO tells you if a button has a quick-select character and returns the ASCII value (value) of the character, if there is one. If there is no quick-select character, it returns 0. It optionally returns the quick-select character itself in char.
You can specify a button by name (case-insensitive) or by numeric position. If you pass a number for button, it is interpreted as an index (base 1) that specifies the position of the button in relation to the other buttons for the window (from left to right, or from top to bottom). Note that a fatal error will occur if you pass a number that is less than 1, a number that is greater than the number of buttons in the window, or an alpha value that is not the name of a button in the window.
See also
- .BUTTON routine
- B_BUTTONSET and L_BUTTONSET routines
Examples
In the following example, %B_INFO tests for a select character for the first button in the window’s button set and retrieves the quick-select character (in sel_char) if there is one:
btn_index = 1 if (%B_INFO(wndid, DSB_SELECTCHAR, btn_index, sel_char)) then . . .
type = %B_INFO(window_id, DSB_TYPE, button[, type_data])
or
xcall B_INFO(window_id, DSB_TYPE, button[, type_data])
Return value
type
Returns DSB_TEXT (text) or DSB_BITMAP (graphic). (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
button
The button name (if passed as alpha) or the button index (if passed as numeric). (a or n)
type_data
(optional) The returned type-specific data, which is the text for the button face (if the type is DSB_TEXT) or the image path (if the type is DSB_BITMAP). (a)
Discussion
The DSB_TYPE subfunction of %B_INFO returns the type of the button face (text or graphic) and optionally retrieves either the text for the button or the path for the button’s graphic.
You can specify a button by name (case-insensitive) or by numeric position. If you pass a number for button, it is interpreted as an index (base 1) that specifies the position of the button in relation to the other buttons for the window (from left to right, or from top to bottom). A fatal error will occur if you pass a number that is less than 1, a number that is greater than the number of buttons in the window, or an alpha value that is not the name of a button in the window.
See also
- Toolkit button graphics for information on supported graphic formats
- DSB_ADD for B_BUTTON and DSB_ADD for L_BUTTON
Examples
In the following example, %B_INFO returns the button type for the button named “lookup” and retrieves either the button’s text or the path for the button’s graphic in btn_data:
btn_type = %b_info(wndid, DSB_TYPE, "lookup", btn_data)
length = %B_INFO(window_id, DSB_TOOLTIP, button[, text]))
or
xcall B_INFO(window_id, DSB_TOOLTIP, button[, text])
Return value
length
The length of the button’s ToolTip text, or 0 if the button has no ToolTip. (^VAL)
Arguments
window_id
The ID of a window. (See the %B_INFO Discussion.) (n)
button
The button name (if passed as alpha) or the button index (if passed as numeric). (a or n)
text
(optional) The returned text of the button’s ToolTip. (a)
Discussion
The DSB_TOOLTIP subfunction of %B_INFO enables you to determine if a button on a window or a list has a ToolTip. It returns the length of a button’s ToolTip text (or zero if the button has no ToolTip). It optionally returns the text of the button’s ToolTip in text (or all blanks if the button has no ToolTip).
You can specify a button by name (case-insensitive) or by numeric position. If you pass a number for button, it is interpreted as an index (base 1) that specifies the position of the button in relation to the other buttons for the window (from left to right, or from top to bottom). Note that a fatal error will occur if you pass a number that is less than 1, a number that is greater than the number of buttons in the window, or an alpha value that is not the name of a button in the window.
Note the following for text:
- If text is not large enough to contain the ToolTip text for the button, that text shall be truncated to the size of text. (Length will still be returned with the full length of the ToolTip text.)
- If text is larger than the ToolTip text for the button, the remainder of text will contain spaces.
- If the button has no ToolTip, text is returned as all blanks.
Examples
In the following example, %B_INFO returns the ToolTip text (ttip_text) and the length of the ToolTip text (ttip_len) for a button named “lookup”:
ttip_len= %B_INFO(wndid, DSB_TOOLTIP, "lookup", ttip_text)
