%B_INFO

Return information about the buttons in a window

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX

 

return = %B_INFO(window_id, subfunction, args)

return

A value that is specific to the subfunction. (^VAL)

window_id

The ID of a window (see Discussion below). (n)

subfunction

One of the following: (n)

DSB_COUNT

Return the number of buttons in a window.

DSB_DEFAULT

Return the index of the default button.

DSB_ENABLED

Return the enabled state of a button.

DSB_INDEX

Return the index (position in button set) of a button.

DSB_JUSTIFICATION

Return the justification setting for a window’s button set.

DSB_METHOD

Return method information for a button.

DSB_NAME

Return a button’s name by passing its index.

DSB_PER_ROW_COL

Return the maximum number of buttons that can be displayed in a button set row or column for a window.

DSB_PLACEMENT

Return the placement (at the bottom of the window or along the right side) for a window’s button set.

DSB_SELECTCHAR

Return the quick-select character for a button.

DSB_TYPE

Return the button face type (text or graphic) for a button.

DSB_TOOLTIP

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:

On OpenVMS, this function ignores all parameters and returns a value of 0.

DSB_COUNT

count = %B_INFO(window_id, DSB_COUNT)

count

The number of buttons in the specified window or a value of 0 if the window has no buttons. (^VAL)

window_id

The ID of a window. (See the %B_INFO Discussion.) (n)

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.

The following example returns the number of buttons in wndid:

btn_num = %b_info(wndid, DSB_COUNT)

DSB_DEFAULT

index = %B_INFO(window_id, DSB_DEFAULT)

index

The index of the default button, or a value of 0 if no default button has been specified for the window. (^VAL)

window_id

The ID of a window. (See the %B_INFO Discussion.) (n)

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.

The following example returns the index for the default button for wndid:

btn_dflt = %b_info(wndid, DSB_DEFAULT)

DSB_ENABLED

state = %B_INFO(window_id, DSB_ENABLED, button)

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)

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)

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.

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)

DSB_INDEX

index = %B_INFO(window_id, DSB_INDEX, name)

index

The index of the button specified by name, or 0 if the specified button is not found. (^VAL)

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)

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.

In the following example, %B_INFO returns the index for a button named lookup:

btn_index = %b_info(widid, DSB_INDEX, "lookup")

DSB_JUSTIFICATION

justification = %B_INFO(window_id, DSB_JUSTIFICATION)

justification

One of the following: (^VAL)

DSB_BEGIN

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.

DSB_CENTER

Buttons are centered along the bottom or along the right side of the window.

DSB_END

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.

window_id

The ID of a window. (See the %B_INFO Discussion.) (n)

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.

In the following example, %B_INFO returns the justification setting for the window’s button set:

btn_just = %B_INFO(wndid, DSB_JUSTIFICATION)

DSB_METHOD

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])

address

The address of the button’s method, or 0 if the button has no method. (^VAL)

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)

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.

.BUTTON routine

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)

DSB_NAME

success = %B_INFO(window_id, DSB_NAME, index, name)

or

xcall B_INFO(window_id, DSB_NAME, index, name)

success

True if index corresponds to a button; false if there is no button for index. (^VAL)

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)

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:

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))
.
.
.

DSB_PER_ROW_COL

number = %B_INFO(window_id, DSB_PER_ROW_COL)

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)

window_id

The ID of a window. (See the %B_INFO Discussion.) (n)

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.

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)

DSB_PLACEMENT

placement = %B_INFO(window_id, DSB_PLACEMENT)

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)

window_id

The ID of a window. (See the %B_INFO Discussion.) (n)

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.

In the following example, %B_INFO returns the placement setting for the window specified by wndid:

btn_plc = %b_info(wndid, DSB_PLACEMENT)

DSB_SELECTCHAR

value = %B_INFO(window_id, DSB_SELECTCHAR, button[, char])

or

xcall B_INFO(window_id, DSB_SELECTCHAR, button[, char])

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)

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)

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.

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
.
.
.

DSB_TYPE

type = %B_INFO(window_id, DSB_TYPE, button[, type_data])

or

xcall B_INFO(window_id, DSB_TYPE, button[, type_data])

type

Returns DSB_TEXT (text) or DSB_BITMAP (graphic). (^VAL)

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)

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.

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)

DSB_TOOLTIP

length = %B_INFO(window_id, DSB_TOOLTIP, button[, text]))

or

xcall B_INFO(window_id, DSB_TOOLTIP, button[, text])

length

The length of the button’s ToolTip text, or 0 if the button has no ToolTip. (^VAL)

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)

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:

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)