%TB_INFO

Return toolbar information

WTSupported in traditional Synergy on Windows

return = %TB_INFO(tbid, subfunction[, arg, ...])

or

xcall TB_INFO(tbid, subfunction[, arg, ...])

Return value

return

On Windows, a value specific to the subfunction. On UNIX and OpenVMS, always returns false. (^VAL)

Arguments

tbid

The ID of a toolbar whose information you want returned. (n)

subfunction

One of the following to return the specified information: (n)

TBI_BUTTONS

Number of buttons on the toolbar and optionally the button names.

TBI_CLICK

Click actions for a toolbar button.

TBI_ENABLED

Enabled state of a toolbar or a toolbar button.

TBI_GROUP

Number of buttons in a button group and optionally the button names.

TBI_HEIGHT

The height (in pixels) of a toolbar or a toolbar button.

TBI_HWND

The window handle for a toolbar or a toolbar button.

TBI_LEFT

The horizontal position of a toolbar button.

TBI_ORIENTATION

The side of the application window that the toolbar occupies.

TBI_PLACED

The placed state of a toolbar.

TBI_TOOLTIP

The ToolTip text for a toolbar button.

TBI_TOP

The vertical position of a toolbar button.

TBI_TYPE

The type of a toolbar button (text or bitmap) and return the caption or graphic path.

TBI_WIDTH

The width (in pixels) of a toolbar or a toolbar button.

arg

(optional) One or more arguments as required for subfunction.

Discussion

%TB_INFO returns information about toolbars and toolbar buttons depending on the value of subfunction.

The value passed in tbid must be the ID of a toolbar created in Toolkit, or Toolkit will generate a runtime error. (The Toolbar does not need to be placed.) And the value passed as subfunction must be one of the TBI_ values listed above, or Toolkit will generate a runtime error.

TBI_BUTTONS

return = %TB_INFO(tbid, TBI_BUTTONS, [max, buttons])

or

xcall %TB_INFO(tbid, TBI_BUTTONS, [max, buttons])

Return value

return

The number of buttons on the toolbar specified by tbid. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

max

(optional) The maximum number of button names to return in the buttons array. (n)

buttons

(optional) The first element of an alphanumeric array of at least max elements. This is required if a value greater than zero is passed as max. (a)

Discussion

The TBI_BUTTONS subfunction of %TB_INFO returns the number of buttons on the specified toolbar (tbid). It returns zero if there are no buttons.

TBI_BUTTONS also returns the names of buttons on the specified toolbar if you pass max and buttons, and if max is greater than zero. It returns these names in all uppercase characters as elements in the buttons array. (The number of returned button names is the lesser of return and max.) Note that if you pass a value that’s greater than zero as max, you must also pass buttons. If you don’t pass max, the buttons argument is ignored (so button names are not returned).

Examples

The following example returns the number of buttons on the tb_id toolbar.

btn_num = %tb_info(tb_id, TBI_BUTTONS)

The next example returns the number of buttons on the tb_id toolbar, and it returns the names of the buttons. The first button name is stored in the first element of the array btn_array. Subsequent names are returned in subsequent array elements.

btn_num = %tb_info(tb_id, TBI_BUTTONS, btn_max, btn_array)

TBI_CLICK

return = %TB_INFO(tbid, TBI_CLICK, button_name, mouse_button, [vk_code], [string]
&        [, method])

or

xcall %TB_INFO(tbid, TBI_CLICK, button_name, mouse_button, [vk_code], [string]
&     [, method])

Return value

return

One or more of the following bit values (indicating which actions will be taken on a mouse click to the specified toolbar button), or 0 if no action is taken. (^VAL)

TBIC_VK

A keystroke is sent to the application.

TBIC_STRING

A string is sent to the application.

TBIC_METHOD

A method is invoked.

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

mouse_button

Indicates left, middle, or right click: TBIC_LEFT, TBIC_MIDDLE, TBIC_RIGHT. (n)

vk_code

(optional) The virtual key code for the specified mouse_button, or zero if there is no virtual key code. (n)

string

(optional) The string generated by the specified mouse_button, or all spaces if no string is generated. (a)

method

(optional) The method for the specified mouse_button, or all spaces if there is no method. Method names are returned in all uppercase characters. (a)

Discussion

The TBI_CLICK subfunction of %TB_INFO enables you to determine if any action will be taken on a mouse click to a toolbar button (button_name), and returns information about actions taken (i.e., any virtual key generated, string generated, or method called).

If a mouse button does not have a method, Toolkit will not generate a virtual key code or a string, even if these are assigned to the button. See the TBB_LOAD Discussion.

If button_name isn’t a valid button name for tbid, Toolkit will generate a runtime error.

Examples

The following example determines if there are any actions for the button specified by btn_name. Each of the following IF statements (which use the bitwise operator &) returns true if the specified bit is set in btn_actions or zero if it isn’t.

btn_actions = %tb_info(tb_id, TBI_CLICK, btn_name, mouse)
if (btn_actions & TBIC_VK)           ;True if button has a virtual key
.
.
.
if (btn_actions & TBIC_STRING)       ;True if button has a string
.
.
.
if (btn_actions & TBIC_METHOD)       ;True if button has a method
.
.
.

The next example returns the virtual key code, string, and method for the specified button.

btn_actions = %tb_info(tb_id, TBI_CLICK, btn_name, mouse, btn_vk,
&             btn_string, btn_method)

TBI_ENABLED

return = %TB_INFO(tbid, TBI_ENABLED[, button_name])

or

xcall %TB_INFO(tbid, TBI_ENABLED[, button_name])

Return value

return

True if the button or toolbar is enabled; false if the button or toolbar is disabled. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

(optional) The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

If button_name is passed, the TBI_ENABLED subfunction of %TB_INFO returns the enabled state of the button. (If button_name is passed as a non-blank value that isn’t a button name for tbid, Toolkit will generate a runtime error.)

If button_name is not passed or is blank, TBI_ENABLED returns the enabled state of the toolbar specified by tbid.

Examples

The following example returns the enabled state of the tb_id toolbar.

tb_status = %tb_info(tb_id, TBI_ENABLED)

The next example returns the enabled state of the toolbar button btn_name.

btn_status = %tb_info(tb_id, TBI_ENABLED, btn_name)

TBI_GROUP

return = %TB_INFO(tbid, TBI_GROUP, button_name, [max, members])

or

xcall %TB_INFO(tbid, TBI_GROUP, button_name, [max, members])

Return value

return

The number of buttons in the group that button_name belongs to, or 0 if button_name is not part of a button group. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

max

(optional) The maximum number of button names to return in the members array. (n)

members

(optional) The first element of an alphanumeric array of at least max elements. This is required if max is passed and is greater than zero. (a)

Discussion

The TBI_GROUP subfunction of %TB_INFO returns the number of buttons in the group that button_name belongs to. It returns zero if button_name is not a member of a button group. If button_name is not a valid button name for tbid, Toolkit will generate a runtime error.

TBI_GROUP also returns the names of buttons in the group if you pass max and members, and if max is greater than zero. It returns these names as elements in the members array. (The number of returned button names is the lesser of return and max.) Note that if you pass a value that’s greater than zero as max, you must also pass members. If you don’t pass max, the members argument is ignored (so button names are not returned).

Examples

The following example returns the number of buttons in the group that the button btn_name belongs to. If btn_name doesn’t belong to a button group, the following returns zero.

btn_number = %tb_info(tb_id, TBI_GROUP, btn_name)

The next example returns the number of buttons in the button group that btn_name belongs to, and it returns the names of the buttons in that group. The first button name is stored in the first element of the array btn_array. Subsequent names are returned in subsequent array elements.

btn_number = %tb_info(tb_id, TBI_GROUP, btn_name, btn_max, btn_array)

TBI_HEIGHT

return = %TB_INFO(tbid, TBI_HEIGHT[, button_name])

or

xcall %TB_INFO(tbid, TBI_HEIGHT[, button_name])

Return value

return

The height in pixels of a toolbar or a toolbar button. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

(optional) The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

If button_name is passed and isn’t blank, the TBI_HEIGHT subfunction of %TB_INFO returns the height of the specified button in pixels. (If button_name is passed as a non-blank value that isn’t a valid button name for tbid, Toolkit will generate a runtime error.)

If button_name is not passed or is blank, TBI_HEIGHT returns the height of the toolbar (tbid) in pixels. Note that this is the actual height of the toolbar’s window (whether placed or not), which may differ from the height passed when the toolbar was created (i.e., the height passed to the TB_CREATE subfunction of %TB_TOOLBAR or %TB_TKCREATE).

Examples

The following example returns the height of the tb_id toolbar.

tb_height = %tb_info(tb_id, TBI_HEIGHT)

The next example returns the height of the toolbar button specified by btn_name, unless btn_name is blank (in which case it returns the toolbar height).

tb_height = %tb_info(tb_id, TBI_HEIGHT, btn_name)

TBI_HWND

return = %TB_INFO(tbid, TBI_HWND[, button_name])

or

xcall %TB_INFO(tbid, TBI_HWND[, button_name])

Return value

return

The handle to a toolbar or a toolbar button. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

(optional) The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

The TBI_HWND subfunction of %TB_INFO returns the window handle for a toolbar or a toolbar button. This is useful if you want to subclass the window or query its characteristics.

If button_name is passed and isn’t blank, TBI_HWND returns the window handle for the specified toolbar button. (If button_name is passed as a non-blank value that isn’t a valid button name for tbid, Toolkit will generate a runtime error.)

If button_name is not passed or is blank, TBI_HWND returns the window handle for the toolbar (tbid).

Examples

The following example returns the handle of the tb_id toolbar.

tb_handle = %tb_info(tb_id, TBI_HWND)

The next example returns the handle of a button (btn_name) on the tb_id toolbar.

tb_handle = %tb_info(tb_id, TBI_HWND, btn_name)

TBI_LEFT

return = %TB_INFO(tbid, TBI_LEFT, button_name)

or

xcall %TB_INFO(tbid, TBI_LEFT, button_name)

Return value

return

The horizontal position in pixels of the left side of button_name. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

The TBI_LEFT subfunction of %TB_INFO returns the horizontal position in pixels of the left side of the button specified by button_name. This position is relative to the toolbar’s client area.

If button_name isn’t a valid button name for tbid, Toolkit will generate a runtime error.

Examples

The following example returns the horizontal position of the left side of button btn_name.

left_side = %tb_info(tb_id, TBI_LEFT, btn_name)

TBI_ORIENTATION

return = %TB_INFO(tbid, TBI_ORIENTATION)

or

xcall %TB_INFO(tbid, TBI_ORIENTATION)

Return value

return

The side of the application window that the toolbar occupies: TCB_TOP, TCB_BOTTOM, TCB_LEFT, TCB_RIGHT. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

Discussion

The TBI_ORIENTATION subfunction of %TB_INFO returns the side of the application window that the specified toolbar (tbid) occupies (or will occupy if the toolbar is not placed).

Examples

The following example returns the position of the tb_id toolbar in the application window.

position = %tb_info(tb_id, TBI_ORIENTATION)

TBI_PLACED

return = %TB_INFO(tbid, TBI_PLACED)

or

xcall %TB_INFO(tbid, TBI_PLACED)

Return value

return

True if the toolbar is placed; otherwise false. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

Discussion

The TBI_PLACED subfunction of %TB_INFO returns the placed state of the toolbar specified by tbid.

Examples

The following example determines if the tb_id toolbar is placed.

position = %tb_info(tb_id, TBI_PLACED)

TBI_TOOLTIP

return = %TB_INFO(tbid, TBI_TOOLTIP, button_name[, text])

or

xcall %TB_INFO(tbid, TBI_TOOLTIP, button_name[, text])

Return value

return

The number of characters in the ToolTip for the specified button, or 0 if there is no ToolTip for the button. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

text

(optional) The text of the ToolTip, or all spaces if there is no ToolTip. (a)

Discussion

The TBI_TOOLTIP subfunction of %TB_INFO enables you to determine if a toolbar button has a ToolTip and returns the length of the ToolTip if there is one. It also returns the text for the ToolTip if you pass text. Note that return is the actual length of the ToolTip, which may be longer than text.

If button_name isn’t a valid button name for tbid, Toolkit will generate a runtime error.

Examples

The following example returns the text for the ToolTip for btn_name.

%tb_info(tb_id, TBI_TOOLTIP, btn_name, tooltip)

TBI_TOP

return = %TB_INFO(tbid, TBI_TOP, button_name)

or

xcall %TB_INFO(tbid, TBI_TOP, button_name)

Return value

return

The vertical position in pixels of the top side of button_name. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

The TBI_TOP subfunction of %TB_INFO returns the vertical position in pixels of the top side of the button specified by button_name. This position is relative to the client area.

If button_name isn’t a valid button name for tbid, Toolkit will generate a runtime error.

Examples

The following example returns the vertical position of the top side of button btn_name.

top_side = %tb_info(tb_id, TBI_TOP, btn_name)

TBI_TYPE

return = %TB_INFO(tbid, TBI_TYPE, button_name[, text])

or

xcall %TB_INFO(tbid, TBI_TYPE, button_name[, text])

Return value

return

The button type: TBLOAD_TYPE_TEXT (text button) or TBLOAD_TYPE_BMAP (image button). (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

text

(optional) The caption for a text button or the path for the image for an image button. (a)

Discussion

The TBI_TYPE subfunction of %TB_INFO returns the type of a button and, if text is passed, one of the following:

• If return is TBLOAD_TYPE_TEXT, it returns the caption of the specified button in text.
• If return is TBLOAD_TYPE_BMAP, it returns the path of the image file (the path passed to the TBB_LOAD subfunction of %TB_BUTTON) as text.

If button_name isn’t a valid button name for tbid, Toolkit will generate a runtime error.

Examples

The following example uses the type of button btn_name to determine which routine to call, and it passes the caption or the image path to the routine.

using (btn_type = %tb_info(tb_id, TBI_TYPE, btn_name, btn_text))
&   select
    (TBLOAD_TYPE_TEXT), xcall change_text_btn(btn_name, btn_text)
    (TBLOAD_TYPE_BMAP), xcall change_bmap_btn(btn_name, btn_text) 
endusing

TBI_WIDTH

return = %TB_INFO(tbid, TBI_WIDTH[, button_name])

or

xcall %TB_INFO(tbid, TBI_WIDTH[, button_name])

Return value

return

The width in pixels of the toolbar or toolbar button. (^VAL)

Arguments

tbid

The ID of a toolbar created in Toolkit. (n)

button_name

(optional) The name (case-insensitive) of a button on the toolbar specified by tbid. (a)

Discussion

If button_name is passed, the TBI_WIDTH subfunction of %TB_INFO returns the width of the specified button in pixels. (If button_name is passed as a non-blank value that isn’t a button name for tbid, Toolkit will generate a runtime error.)

If button_name is not passed or is blank, TBI_WIDTH returns the width of the toolbar (tbid) in pixels. Note that this is the actual width of the toolbar’s window (whether placed or not), which may differ from the width passed when the toolbar was created (i.e., the width passed to the TB_CREATE subfunction of %TB_TOOLBAR or to %TB_TKCREATE).

Examples

The following example returns the width of the tb_id toolbar.

tb_width = %tb_info(tb_id, TBI_WIDTH)

The next example returns the width of the toolbar button specified by btn_name, unless btn_name is blank (in which case it returns the toolbar width).

tb_width = %tb_info(tb_id, TBI_WIDTH, btn_name)