Load and manipulate toolbar buttons
|
WSupported on Windows
|
|
|
|
return = %TB_BUTTON(id, subfunction, arg[, ...])
or
xcall TB_BUTTON(id, subfunction, arg[, ...])
Return value
return
On Windows, a value specific to the subfunction. On Unix and OpenVMS, always returns false. (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
subfunction
The toolbar function to perform: (n)
Add a button to the toolbar.
Define a button group on the toolbar.
Force a button to appear in either an up or down state; or simulate a mouse click.
Delete (and remove) a toolbar button.
Enable a disabled toolbar button.
Disable a toolbar button.
Return the up or down state of a toolbar button.
arg
One or more arguments, depending on subfunction.
%TB_BUTTON enables you to load and manipulate toolbar buttons. See the individual subfunctions for details.
You must include the file toolbar.def to use this function.
The following example uses %TB_BUTTON to add buttons to a toolbar. If the user chooses to change the image for a button, a call to %TB_BUTTON deletes the button and adds a new one with the selected image.
;Create a toolbar at the top of the application, with unspecified
; width and a height of 70 pixels
tb_toolbar(TB_CREATE, tbid, TBC_TOP, 0, 70)
;Add a 60x60 pixel button named "O_EXIT" at 5,5 using the image exit.png
;On left click, call m_signal with the button name
;On right click, call mod_button with the button name
tb_button(tbid, TBB_LOAD, "O_EXIT", 5, 5, 60, 60, TBLOAD_TYPE_BMAP,
& "exit.png", "Exit the application",,, "m_signal",,,,,,
& "mod_button")
;Now do the same for "O_HELP", but placed at 75,5 and using the
; image help.png
tb_button(tbid, TBB_LOAD, "O_HELP", 75, 5, 60, 60, TBLOAD_TYPE_BMAP,
& "help.png", "Get Help",,, "m_signal",,,,,, "mod_button")
;Place the toolbar
tb_toolbar(TB_PLACE, tbid)
repeat
begin
m_process("") ;Process the menu
; (you could call any input routine here)
if (g_select)
using g_entnam select
("O_EXIT "), exitloop ;Handle O_EXIT by exiting
;We don't need to handle O_HELP,
; because M_PROCESS does
endusing
end
.
.
.
function mod_button, ^val, reentrant
;
; Routine to allow the user to select a new image for a button
;
in req a_name ,a ;Name of the button
external common
tbid ,int ;Toolbar ID
record ;Place to save off button information
x ,int
y ,int
cx ,int
cy ,int
image ,a256
tooltip ,a256
proc
x = %tb_info(tbid, TBI_LEFT, a_name)
y = %tb_info(tbid, TBI_TOP, a_name)
cx = %tb_info(tbid, TBI_WIDTH, a_name)
cy = %tb_info(tbid, TBI_HEIGHT, a_name)
tb_info(tbid, TBI_TYPE, a_name, image)
tb_info(tbid, TBI_TOOLTIP, a_name, tooltip)
if (%u_getfilename(image, "Choose a new image",,,, image))
begin
;User selected a new image, so first delete the old button
tb_button(tbid, TBB_DELETE, a_name)
;Then add it back using the new image
tb_button(tbid, TBB_LOAD, a_name, x, y, cx, cy, TBLOAD_TYPE_BMAP,
& image, %atrim(tooltip),,,"m_signal",,,,,, "mod_button")
end
m_signal("O_UPDT") ;Force an update
freturn TRUE
end
status = %TB_BUTTON(id, TBB_LOAD, name, [left], [top], width, height, type_spec, type_arg, & [tooltip], [left_vk_code], [left_string], [left_method], [mid_vk_code], [mid_string], & [mid_method], [right_vk_code], [right_string] [, right_method])
or
xcall TB_BUTTON(id, TBB_LOAD, name, [left], [top], width, height, type_spec, type_arg, & [tooltip], [left_vk_code], [left_string], [left_method], [mid_vk_code], [mid_string], & [mid_method], [right_vk_code], [right_string] [, right_method])
Return value
status
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button (maximum 30 characters). “#NUMBER” is a reserved name that will load the numeric bar. (a)
left
(optional) The pixel location of the left edge of the button relative to the top left corner of the toolbar. (n)
top
(optional) The pixel location of the top edge of the button relative to the top left corner of the toolbar. (n)
For horizontal toolbars, if left or top are not specified, the button will be placed automatically, following a left-to-right, top-to-bottom pattern.
For vertical toolbars, if left or top are not specified, the button will be placed automatically, following a top-to-bottom, left-to-right pattern.
width
The width of the button in pixels. (n)
height
The height of the button in pixels. (n)
type_spec
The button face type: TBLOAD_TYPE_TEXT for text or TBLOAD_TYPE_BMAP to graphic. (n)
type_arg
The button type data: If type_spec is TBLOAD_TYPE_TEXT, the text string to load on the face of the button. If type_spec is TBLOAD_TYPE_BMAP, the filename for the graphic to be placed on the face of the button. (See Toolkit button graphics.) (a)
tooltip
(optional) The text of a ToolTip to be displayed if the mouse rests over the button. (a)
left_vk_code
mid_vk_code
right_vk_code
(optional) “Virtual keys” generated when the left, middle, and right mouse buttons are used to select this toolbar button. For example, VK_LBUTTON listed in toolbar.def. (n)
left_string
mid_string
right_string
(optional) Strings generated when the left, middle, and right mouse buttons are used to select this toolbar button. The strings generated will precede any virtual key generation that may be defined for this button. (a)
left_method
mid_method
right_method
(optional) The names of the subroutines invoked when the left, middle, and right mouse buttons are used to select this toolbar button. (a)
The TBB_LOAD subfunction of %TB_BUTTON adds a button to the toolbar. If you don’t specify a position for the button and no other button have been added, the button will be placed at the leftmost position on the toolbar. If you don’t specify a position for the button but other buttons have been added, the button will be placed to the right of the last specified button—even if the last specified button has been deleted (which will create a gap before the new button on the toolbar.)
When a mouse button is clicked while on a toolbar button, the specified method routine is called. This method routine is passed one argument, the name of the button. If the method returns a value of false, the action sequence terminates and no further actions are taken on that keypress. If the method returns a value of true, any string is posted, followed by any VK_xxx virtual key.
See also
status = %TB_BUTTON(id, TBB_GROUP, name1[, name2, ...])
or
xcall TB_BUTTON(id, TBB_GROUP, name1[, name2, ...])
Return value
status
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name1
The name of the button in the group that will initially receive the down state. (a)
name2, …
(optional) The name of one or more buttons that define the rest of the group. (a)
Discussion
The TBB_GROUP subfunction of %TB_BUTTON is used to define a button group. A button group is a set of buttons on a toolbar. When a button is selected, it exhibits a down state. If that button is part of a group, all other buttons in the group exhibit an up state. At all times, one and only one button in a group will exhibit a down state. Regardless of state, all buttons are always selectable if enabled.
When specified, all button name arguments given in TBB_GROUP must be successfully loaded by TBB_LOAD prior to the TBB_GROUP call. An error will result if a TBB_GROUP button name argument is not a loaded button. A button can only be a member of one group. You cannot delete a group directly, but you can use TBB_DELETE to delete buttons from the group. When the last button in the group is deleted, the group is deleted. See the TBB_DELETE Discussion for more information on deleting buttons in a group.
status = %TB_BUTTON(id, TBB_SELECT, name, option)
or
xcall TB_BUTTON(id, TBB_SELECT, name, option)
Return value
status
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button. (a)
option
One of the following toolbar button-state options: (n)
Forces the button to appear in the down state until TBBS_RELEASE is called for that button. The down state indicates that a selection is currently being processed.
Releases a TBBS_HOLD button from its forced down state. The up state indicates that the selection being processed is now completed.
Simulates a left mouse button press on a toolbar button. All events defined for the button with TBB_LOAD are executed.
Simulates a middle mouse button press. All events defined for the button with TBB_LOAD are executed.
Simulates a right mouse button press. All events defined for the button with TBB_LOAD are executed.
Discussion
The TBB_SELECT subfunction of %TB_BUTTON forces a button to appear in either an up or down state. It can also simulate a user mouse-press on a button. If a method, string, or virtual key is defined for the toolbar button, the actions are invoked in the sequence described under TBB_LOAD.
return = %TB_BUTTON(id, TBB_DELETE, name)
or
xcall TB_BUTTON(id, TBB_DELETE, name)
Return value
return
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button. (a)
The TBB_DELETE subfunction of %TB_BUTTON removes a toolbar button from the toolbar. You can delete a button that’s part of a group. If the button is the selected member of a group, the first remaining member (in the order the members were specified when the group was created) becomes the selected member, and its left click event is signaled. If the button is the only remaining button in the group, the group is deleted.
return = %TB_BUTTON(id, TBB_ENABLE, name)
or
xcall TB_BUTTON(id, TBB_ENABLE, name)
Return value
return
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button. (a)
Discussion
The TBB_ENABLE subfunction of %TB_BUTTON enables a disabled toolbar button.
return = %TB_BUTTON(id, TBB_DISABLE, name)
or
xcall TB_BUTTON(id, TBB_DISABLE, name)
Return value
return
The status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button. (a)
Discussion
The TBB_DISABLE subfunction of %TB_BUTTON disables a toolbar button. The toolbar button remains on the screen, but nothing happens if it is selected. When a button is disabled, it is grayed out.
return = %TB_BUTTON(id, TBB_STATE, name)
or
xcall TB_BUTTON(id, TBB_STATE, name)
Return value
return
The state of the specified button. Down (selected) returns 1; up (not selected) returns 0. (^VAL)
Arguments
id
The toolbar identifier, the value of which is returned from the TB_CREATE subfunction of %TB_TOOLBAR. (n)
name
The name of the button. (a)
Discussion
The TBB_STATE subfunction of %TB_BUTTON returns the up or down state of a toolbar button. The state is returned as the value of the %TB_BUTTON function.
