%TB_BUTTON

Load and manipulate toolbar buttons

WTSupported in traditional Synergy 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)

TBB_LOAD

Add a button to the toolbar.

TBB_GROUP

Define a button group on the toolbar.

TBB_SELECT

Force a button to appear in either an up or down state; or simulate a mouse click.

TBB_DELETE

Delete (and remove) a toolbar button.

TBB_ENABLE

Enable a disabled toolbar button.

TBB_DISABLE

Disable a toolbar button.

TBB_STATE

Return the up or down state of a toolbar button.

arg

One or more arguments, depending on subfunction.

Discussion

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

Examples

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

TBB_LOAD

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)

Discussion

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

Appendix D: Methods.

TBB_GROUP

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.

TBB_SELECT

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)

TBBS_HOLD

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.

TBBS_RELEASE

Releases a TBBS_HOLD button from its forced down state. The up state indicates that the selection being processed is now completed.

TBBS_LEFT

Simulates a left mouse button press on a toolbar button. All events defined for the button with TBB_LOAD are executed.

TBBS_MIDDLE

Simulates a middle mouse button press. All events defined for the button with TBB_LOAD are executed.

TBBS_RIGHT

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.

TBB_DELETE

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)

Discussion

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.

TBB_ENABLE

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.

TBB_DISABLE

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.

TBB_STATE

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.