|
WSupported 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)
Number of buttons on the toolbar and optionally the button names.
Click actions for a toolbar button.
Enabled state of a toolbar or a toolbar button.
Number of buttons in a button group and optionally the button names.
The height (in pixels) of a toolbar or a toolbar button.
The window handle for a toolbar or a toolbar button.
The horizontal position of a toolbar button.
The side of the application window that the toolbar occupies.
The placed state of a toolbar.
The ToolTip text for a toolbar button.
The vertical position of a toolbar button.
The type of a toolbar button (text or bitmap) and return the caption or graphic path.
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.
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)
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)
A keystroke is sent to the application.
A string is sent to the application.
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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
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)
