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

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.

Discussion

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)

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)

DSB_DEFAULT

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)

DSB_ENABLED

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)

DSB_INDEX

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

DSB_JUSTIFICATION

justification = %B_INFO(window_id, DSB_JUSTIFICATION)

Return value

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.

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

Examples

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

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)

DSB_NAME

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:

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

DSB_PER_ROW_COL

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)

DSB_PLACEMENT

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

Examples

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

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

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

DSB_TYPE

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

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)

DSB_TOOLTIP

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:

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)