Difference between revisions of "ToolBar Gadget Class"

Latest revision as of 14:37, 14 February 2021

Datasheet

NAME: toolbar.gadget -- Create toolbar BOOPSI objects

SUPERCLASS: gadgetclass

REQUIRES: button.gadget, select.gadget, label.image, bevel.image, shared.image

DESCRIPTION: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.

Supported methods

Method ID	Description
OM_NEW	creates the toolbar object, sets attributes and defaults
OM_DISPOSE	disposes of the toolbar object
OM_REMMEMBER	used by the class internally; consider this method private
OM_SET	sets toolbar, member and image attributes (see the OM_SET section below for more information)
OM_GET	retrieves toolbar attributes
TBM_GETMEMBER	retrieves a given member attribute (see the TBM_GETMEMBER section below for more information)
TBM_REFRESHMEMBER	refreshes the imagery of a given member (see the TBM_REFRESHMEMBER section below for more information)

Attributes

Toolbar attributes

GA_ID (uint16): Unique ID number for the gadget.; Defaults to 0; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

GA_ReadOnly (BOOL): If set to TRUE, none of the toolbar buttons will be selectable.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

GA_BackFill (struct Hook *): A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.; Defaults to NULL (the default backfill hook); Applicability is (OM_NEW, OM_SET, OM_UPDATE)

GA_TextAttr (struct TextAttr *): Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.; Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.; Defaults to NULL (will use the system's default public screen font); Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TOOLBAR_Orientation (uint32): The toolbar orientation: horizontal or vertical.; Defaults to TB_ORIENT_HORIZ; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_Spacing (uint32): The spacing between the individual toolbar members, in pixels.; Defaults to 2; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_HorizPadding
TOOLBAR_VertPadding (uint32): The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).; Defaults to 0; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_InnerPadding (uint32): The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.; Defaults to 4; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_HandleOverflow (BOOL): Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_MinVisible (uint32): If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.; Defaults to 1; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_SpacerSize (uint32): The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.; Defaults to 5; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_ButtonStyle (uint32): The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.; Defaults to TB_BUTSTYLE_CLASSIC; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_BevelStyle (uint32): The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:

 BVS_NONE    -- no bevel is drawn around the toolbar
 BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel

When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.

Defaults to BVS_NONE

Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_SeparatorStyle (uint32): Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.; Defaults to TB_SEPSTYLE_NORMAL; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_SelectionStyle (uint32): Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.; This tag is ignored in the classic mode with framed buttons.; Defaults to TB_SELSTYLE_NONE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_BackFill (struct Hook *): A custom backfill hook to provide a background filled with a specific colour or pattern.; This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.; Defaults to NULL (the default backfill hook); Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TOOLBAR_Display (uint32): Specifies what you want to display inside the toolbar button or toggle members. The possible values are:

 TB_DISPLAY_IMAGES -- display only images
 TB_DISPLAY_TEXT -- display only text labels
 TB_DISPLAY_BOTH -- display both images and text labels

Defaults to TB_DISPLAY_IMAGES

Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_TextPen (uint16) (V53.4): A pen to be used for the toolbar members' text.; Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.; Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.; Defaults to dri_Pens[TEXTPEN]; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TOOLBAR_TextStyle (uint8) (V53.4): A font style to be used for the toolbar members' text.; Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.; The styles are defined in the <graphics/text.h> system include file.; Defaults to FS_NORMAL; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TOOLBAR_TextPlace (uint32): Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.; The possible values are:

 TB_PLACETEXT_BELOW
 TB_PLACETEXT_ABOVE (V53.6)
 TB_PLACETEXT_LEFT (V53.6)
 TB_PLACETEXT_RIGHT (V53.6)

Defaults to TB_PLACETEXT_BELOW

Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_LabelArray (STRPTR *): Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.; TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.; Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).; A special string, " ", will create a spacer.; A special string, "_", will create a separator.; Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.; The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.; Defaults to NULL; Applicability is (OM_NEW)

TOOLBAR_EvenSize (BOOL): If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.; If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

TOOLBAR_ImageSet (uint32): If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.; Defaults to 0; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

Method attributes

The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:

TOOLBAR_AddImageSet (uint32): Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.; An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.; This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.; If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.; Applicability is (OM_NEW, OM_SET)

TOOLBAR_AddImage (uint32): Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.; An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.; This tag should be followed by a sequence of TBIMAGE_ tags (see the Image attributes section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").; Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.; Applicability is (OM_NEW, OM_SET)

TOOLBAR_AddMember (uint32): Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.; Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.; You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().; Applicability is (OM_NEW, OM_SET)

TOOLBAR_SetMember: Use this tag in a SetAttrs() call to identify the member you want to modify.; Applicability is (OM_SET)

TOOLBAR_SetGroup: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.; Applicability is (OM_SET)

Member attributes

TBMEMBER_Type (uint32): The type of the toolbar member. The possible values are the following:

 TB_MTYPE_BUTTON -- a normal toolbar button
 TB_MTYPE_TOGGLE -- a toggle (on/off) button
 TB_MTYPE_SPACER -- a spacer
 TB_MTYPE_SEPARATOR -- a separator bar
 TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)

The type is set upon member creation, and cannot be changed.

Defaults to TB_MTYPE_BUTTON

Applicability is (OM_NEW)

TBMEMBER_ImageID (uint32)

The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.

When OM_SET-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:

by setting this attribute via RefreshSetGadgetAttrs(), or
by setting this attribute via SetAttrs() and then invoking the TBM_REFRESHMEMBER method on the respective button/toggle member.

(The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)

Defaults to TB_NO_ID (no image associated with this member)

Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_Text (CONST_STRPTR): The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; TBM_GETMEMBER will always return NULL should you inquire about the TBMEMBER_Text value of such a member.; The text will be used as fallback in case no image is found or provided for a button or a toggle member.; Multi-line text is supported: use "\n" as line separator in the text string.; The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.); If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:

     (1)   IIntuition->SetGadgetAttrs(toolbar, window, NULL,
                       TOOLBAR_SetMember, textboxID,
                          TBMEMBER_Text, "New text",
                       TAG_END);

     (2)   IIntuition->SetAttrs(toolbar,
                       TOOLBAR_SetMember, textboxID,
                          TBMEMBER_Text, "New text",
                       TAG_END);
        
             IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);

The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the TBM_REFRESHMEMBER method.

Defaults to NULL

Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_DomainString (CONST_STRPTR) (V53.4): A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.; The domain string is never rendered in the gadget.; This tag is not relevant to spacers and separators.; Defaults to NULL; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TBMEMBER_TextAttr (struct TextAttr *) (V53.4): Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).; Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.; Defaults to the GA_TextAttr value; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TBMEMBER_TextPen (uint16) (V53.4): A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).; Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.; Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.; Defaults to the TOOLBAR_TextPen value; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TBMEMBER_TextStyle (uint8) (V53.4): A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).; Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.; The styles are defined in the <graphics/text.h> system include file.; Defaults to the TOOLBAR_TextStyle value; Applicability is (OM_NEW, OM_SET, OM_UPDATE)

TBMEMBER_Disabled (BOOL): The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; TBM_GETMEMBER will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_Hidden (BOOL): Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_Selected (BOOL): The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; TBM_GETMEMBER will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.; You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.; Defaults to FALSE; Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)

TBMEMBER_Group (uint32): Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.; Defaults to TB_NO_ID (not assigned to any group); Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_MXGroup (uint32): MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.; This tag is not relevant to normal buttons, textboxes, spacers and separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.; Defaults to TB_NO_ID (not assigned to any MX group); Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_HintInfo (CONST_STRPTR): The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; TBM_GETMEMBER will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.; Defaults to NULL; Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

TBMEMBER_UserData (APTR): Arbitrary user data associated with this member.; Defaults to NULL; Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)

Image attributes

Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.

TBIMAGE_Image (struct Image *): Custom image to be used for a button or a toggle member.; Defaults to NULL; Applicability is (OM_NEW)

TBIMAGE_ImageFile (CONST_STRPTR): The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.; All images created this way will also be disposed of automatically.; Defaults to NULL; Applicability is (OM_NEW)

TBIMAGE_SelImage (struct Image *): Custom image to display when the member becomes selected.; Defaults to NULL; Applicability is (OM_NEW)

TBIMAGE_SelImageFile (CONST_STRPTR): The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.; All images created this way will also be disposed of automatically.; Defaults to NULL; Applicability is (OM_NEW)

TBIMAGE_Width (uint32)
TBIMAGE_Height (uint32): Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.; Defaults to 0; Applicability is (OM_NEW)

Notes

Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the OM_SET method documentation below to see how to handle such situations.

Bugs

Methods

OM_SET

NAME: OM_SET -- set toolbar attributes

SYNOPSIS: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);; uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);

FUNCTION: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.; To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.; To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.

INPUTS

 toolbar -- the toolbar gadget object
 win -- the window that hosts the toolbar
 req -- requester pointer (use NULL)
 tag1 etc. -- a list of toolbar attribute tags

RESULT: This method will return TB_NEED_RETHINK if the gadget believes that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.; If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).; The method returns 0L if no rethink is needed.

EXAMPLE

 // To set various toolbar attributes:
 if ( IIntuition->SetAttrs(toolbar,
                  TOOLBAR_Orientation, TB_ORIENT_VERT,
                  TOOLBAR_Spacing, 4,
                  TOOLBAR_SpacerSize, 10,
                  TAG_END) == TB_NEED_RETHINK )
  {
   IIntuition->IDoMethod(winObj, WM_RETHINK);
  }

 // To disable a member:
 IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
             TOOLBAR_SetMember, memberID,
                TBMEMBER_Disabled, TRUE,
             TAG_END);

 // To hide a member:
 IIntuition->SetAttrs(toolbar,
             TOOLBAR_SetMember, memberID,
                TBMEMBER_Hidden, TRUE,
             TAG_END);
 IIntuition->IDoMethod(winObj, WM_RETHINK);

 // To modify several member attributes at once:
 IIntuition->SetAttrs(toolbar,
             TOOLBAR_SetMember, memberID,
                TBMEMBER_HintInfo, "My help string",
                TBMEMBER_UserData, anything,
             TAG_END);

 // To disable all members assigned to a group:
 IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
             TOOLBAR_SetGroup, groupID,
                TBMEMBER_Disabled, TRUE,
             TAG_END);

NOTES

BUGS

SEE ALSO

TBM_GETMEMBER

NAME: TBM_GETMEMBER -- obtain the value of a specific member attribute

SYNOPSIS: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);; uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);

FUNCTION

Use this method to obtain the value of a given member attribute.

Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:

We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.
Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)

INPUTS

For IDoMethodA():

 toolbar -- the toolbar gadget object
 msg -- a pointer to an initialized tbGetMember structure

For IDoMethod():

 toolbar -- the toolbar gadget object
 methodID -- this method's identifier, TBM_GETMEMBER
 memberID -- the member identifier (as set in TOOLBAR_AddMember)
 attrID -- the attribute tag identifier
 storage -- a pointer to the variable for storing the attribute value

RESULT: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.

EXAMPLE

 // To query about the selection state of a toggle member:
 uint32 storage;
    
 IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);

NOTES

BUGS

SEE ALSO

TBM_REFRESHMEMBER

NAME: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)

SYNOPSIS: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);; uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);

FUNCTION: Use this method to refresh the imagery of a given button or toggle member.; The method has no effect on spacers and separators.

INPUTS

For IDoMethodA():

 toolbar  -- the toolbar gadget object
 msg      -- a pointer to an initialized tbRefreshMember structure

For IDoMethod():

 toolbar  -- the toolbar gadget object
 methodID -- this method's identifier, TBM_REFRESHMEMBER
 memberID -- the member identifier (as set in TOOLBAR_AddMember)
 window   -- a pointer to the window the toolbar resides in

RESULT: The "result" value will be 1L if the refresh has taken place.

EXAMPLE

 IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);

NOTES

BUGS

SEE ALSO

Difference between revisions of "ToolBar Gadget Class"

Latest revision as of 14:37, 14 February 2021

Contents

Datasheet

Supported methods

Attributes

Toolbar attributes

Method attributes

Member attributes

Image attributes

Notes

Bugs

See also

Methods

OM_SET

TBM_GETMEMBER

TBM_REFRESHMEMBER

Navigation menu

Search

@@ Line 1: / Line 1: @@
-Toolbar Gadget Class
+== Datasheet ==
+; NAME
+: toolbar.gadget -- Create toolbar BOOPSI objects
-=NAME=
+;SUPERCLASS
-    toolbar.gadget -- Create toolbar BOOPSI objects
+: gadgetclass
-=SUPERCLASS=
+; REQUIRES
-    gadgetclass
+: button.gadget, select.gadget, label.image, bevel.image, shared.image
-=REQUIRES=
+; DESCRIPTION
-    button.gadget, select.gadget, label.image, bevel.image, shared.image
+: This class is an easy-to-setup, highly configurable alternative to the standard speedbar.gadget provided by the operating system.
-=DESCRIPTION=
+== Supported methods ==
-    This class is an easy-to-setup, highly configurable alternative to the
-    standard speedbar.gadget provided by the operating system.
-=METHODS=
+{| class="wikitable"
+!Method ID
+!Description
+|-
+|OM_NEW
+|creates the toolbar object, sets attributes and defaults
+|-
+|OM_DISPOSE
+|disposes of the toolbar object
+|-
+|OM_REMMEMBER
+|used by the class internally; consider this method private
+|-
+|OM_SET
+|sets toolbar, member and image attributes (see the [[#OM_SET|OM_SET]] section below for more information)
+|-
+|OM_GET
+|retrieves toolbar attributes
+|-
+|TBM_GETMEMBER
+|retrieves a given member attribute (see the [[#TBM_GETMEMBER|TBM_GETMEMBER]] section below for more information)
+|-
+|TBM_REFRESHMEMBER
+|refreshes the imagery of a given member (see the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] section below for more information)
+|}
-    OM_NEW -- creates the toolbar object, sets attributes and defaults
+== Attributes ==
-    OM_DISPOSE -- disposes of the toolbar object
+=== Toolbar attributes ===
-    OM_REMMEMBER -- used by the class internally; consider this method private
+; GA_ID (uint16)
+: Unique ID number for the gadget.
+: Defaults to 0
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    OM_SET -- sets toolbar, member and image attributes (see the OM_SET
+; GA_ReadOnly (BOOL)
-              section below for more information)
+: If set to TRUE, none of the toolbar buttons will be selectable.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    OM_GET -- retrieves toolbar attributes
+; GA_BackFill (struct Hook *)
+: A backfill hook to provide a background filled with a specific colour or pattern. Please also see notes for TOOLBAR_BackFill below.
+: Defaults to NULL (the default backfill hook)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-    TBM_GETMEMBER -- retrieves a given member attribute (see the TBM_GETMEMBER
+; GA_TextAttr (struct TextAttr *)
-                     section below for more information)
+: Pointer to a TextAttr structure describing the font to be used for the toolbar members' text.
+: Generally, you should use one font for the toolbar, set through this tag. However, you can override the global font and set a different one for individual members if needed; see TBMEMBER_TextAttr below.
+: Defaults to NULL (will use the system's default public screen font)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-=ATTRIBUTES=
+; TOOLBAR_Orientation (uint32)
-    GA_ID (uint16)
+: The toolbar orientation: horizontal or vertical.
-      Unique ID number for the gadget.
+: Defaults to TB_ORIENT_HORIZ
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Defaults to 0
+; TOOLBAR_Spacing (uint32)
+: The spacing between the individual toolbar members, in pixels.
+: Defaults to 2
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_HorizPadding
+; TOOLBAR_VertPadding (uint32)
+: The horizontal/vertical distance, in pixels, between the toolbar members and the gadget border (or outer bevel, if displayed - see TOOLBAR_BevelStyle below).
+: Defaults to 0
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    GA_ReadOnly (BOOL)
+; TOOLBAR_InnerPadding (uint32)
-      If set to TRUE, none of the toolbar buttons will be selectable.
+: The distance, in pixels, between the member contents (image and/or text) and the button frame. Changing this setting will affect the size of the toolbar members.
+: Defaults to 4
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Defaults to FALSE
+; TOOLBAR_HandleOverflow (BOOL)
+: Overflow is a situation when there is not enough space to fit all toolbar members within the current window. If this tag is set to TRUE, all members that don't fit will be moved into a pop-up menu whenever overflow takes place. A selector to invoke the menu will be displayed on the right.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_MinVisible (uint32)
+: If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the specified number of members (including spacers and separators) will always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.
+: Defaults to 1
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    GA_BackFill (struct Hook *)
+; TOOLBAR_SpacerSize (uint32)
-      A backfill hook to provide a background filled with a specific colour
+: The size of the spacer member, in pixels. This value will affect the width (in a horizontal toolbar) or the height (in a vertical toolbar) of the spacer.
-      or pattern. Please also see notes for TOOLBAR_BackFill below.
+: Defaults to 5
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Defaults to NULL (the default backfill hook).
+; TOOLBAR_ButtonStyle (uint32)
+: The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce a traditional-looking toolbar with framed buttons, whereas TB_BUTSTYLE_BORDERLESS will configure a borderless look.
+: Defaults to TB_BUTSTYLE_CLASSIC
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE)
+; TOOLBAR_BevelStyle (uint32)
+: The style of the gadget's outer bevel (frame). The Bevel Image class is used, so the style values from <images/bevel.h> are applicable to this tag (although not all of them make good sense to use with the toolbar). The recommended values are:
-    GA_TextAttr (struct TextAttr *)
+  BVS_NONE    -- no bevel is drawn around the toolbar
-      Pointer to a TextAttr structure describing the font to be used for
+  BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel
-      the gadget's button text labels (if they are used).
-      Defaults to the system's default public screen font.
+: When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar buttons), make sure that you also adjust TOOLBAR_HorizPadding and TOOLBAR_VertPadding, otherwise the outer bevel will interfere with the button frames.
+: Defaults to BVS_NONE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE)
+; TOOLBAR_SeparatorStyle (uint32)
+: Determines the look of the separator member. If you want to change it on the fly while the window is open, call SetGadgetAttrs() rather than SetAttrs() to trigger an immediate redraw.
+: Defaults to TB_SEPSTYLE_NORMAL
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    TOOLBAR_Orientation (uint32)
+; TOOLBAR_SelectionStyle (uint32)
-      The toolbar orientation: horizontal or vertical.
+: Determines how member selection is indicated in the borderless mode. If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the selection: the programmer must provide a select image for each button or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below), otherwise there will be no visual response. If the tag is set to TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around the member to indicate the selection.
+: This tag is ignored in the classic mode with framed buttons.
+: Defaults to TB_SELSTYLE_NONE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Defaults to TB_ORIENT_HORIZ
+; TOOLBAR_BackFill (struct Hook *)
+: A custom backfill hook to provide a background filled with a specific colour or pattern.
+: This tag is meant to replace GA_BackFill because if the toolbar gadget is placed in a layout, the value of GA_BackFill can only be set after the window opens (this is because the Layout Gadget propagates its own backfill to all of its children). TOOLBAR_BackFill is provided as a convenience tag that overrides GA_BackFill, and allows setting your backfill hook even before the window opens.
+: Defaults to NULL (the default backfill hook)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_Display (uint32)
+: Specifies what you want to display inside the toolbar button or toggle members. The possible values are:
-    TOOLBAR_Spacing (uint32)
+  TB_DISPLAY_IMAGES -- display only images
-      The spacing between the individual toolbar members, in pixels.
+  TB_DISPLAY_TEXT -- display only text labels
+  TB_DISPLAY_BOTH -- display both images and text labels
-      Defaults to 2
+: Defaults to TB_DISPLAY_IMAGES
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_TextPen (uint16) (V53.4)
+: A pen to be used for the toolbar members' text.
+: Generally, you should use one text pen for the toolbar, set through this tag. However, you can override the global pen and set a different one for individual members if needed; see TBMEMBER_TextPen below.
+: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.
+: Defaults to dri_Pens[TEXTPEN]
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-    TOOLBAR_HorizPadding
+; TOOLBAR_TextStyle (uint8) (V53.4)
-    TOOLBAR_VertPadding (uint32)
+: A font style to be used for the toolbar members' text.
-      The horizontal/vertical distance, in pixels, between the toolbar
+: Generally, you should use one text style for the toolbar, set through this tag. However, you can override the global style and set a different one for individual members if needed; see TBMEMBER_TextStyle below.
-      members and the gadget border (or outer bevel, if displayed - see
+: The styles are defined in the <graphics/text.h> system include file.
-      TOOLBAR_BevelStyle below).
+: Defaults to FS_NORMAL
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-      Defaults to 0
+; TOOLBAR_TextPlace (uint32)
+: Specifies the placement of the text labels with regard to the toolbar images. This tag is only meaningful when actual text labels are provided via TBMEMBER_Text, and TOOLBAR_Display is set to TB_DISPLAY_BOTH. Plus, it only affects button and toggle members.
+: The possible values are:
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+  TB_PLACETEXT_BELOW
+  TB_PLACETEXT_ABOVE (V53.6)
+  TB_PLACETEXT_LEFT (V53.6)
+  TB_PLACETEXT_RIGHT (V53.6)
-    TOOLBAR_InnerPadding (uint32)
+: Defaults to TB_PLACETEXT_BELOW
-      The distance, in pixels, between the member contents (image and/or text)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      and the button frame. Changing this setting will affect the size of the
-      toolbar members.
-      Defaults to 4
+; TOOLBAR_LabelArray (STRPTR *)
+: Use this tag to create a minimum-configuration, text-only toolbar. You simply pass a NULL-terminated array of strings representing the toolbar button labels. Each label can contain an underscore character to indicate the keyboard shortcut for the respective button.
+: TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.
+: Using this tag, the limitation is that you cannot create toggle or textbox members (only buttons, separators and spacers).
+: A special string, " ", will create a spacer.
+: A special string, "_", will create a separator.
+: Spacers and separators cannot appear as the very first member in the toolbar. Therefore, the label array may not begin with a spacer or a separator string. Also, the array must contain at least one valid string to create a button, otherwise the toolbar creation will fail.
+: The button strings are copied to an internal buffer, so the label array need not remain valid throughout the lifetime of the gadget.
+: Defaults to NULL
+: Applicability is (OM_NEW)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_EvenSize (BOOL)
+: If set to TRUE, this attribute will size all button and toggle members evenly according to the largest member. The attribute has no effect on spacers and separators.
+: If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above) and your toolbar images are all of the same size, keep this attribute at its default FALSE value: the button dimensions will be equal anyway, and you'll spare the gadget some unnecessary calculations. On the other hand, setting this tag to TRUE may produce a visually more plausible result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-    TOOLBAR_HandleOverflow (BOOL)
+; TOOLBAR_ImageSet (uint32)
-      Overflow is a situation when there is not enough space to fit all
+: If more than one image set have been configured via TOOLBAR_AddImageSet (see below), use this tag to determine which set is to be displayed in the toolbar. The value passed to this tag is the image set ID.
-      toolbar members within the current window. If this tag is set to TRUE,
+: Defaults to 0
-      all members that don't fit will be moved into a pop-up menu whenever
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_GET)
-      overflow takes place. A selector to invoke the menu will be displayed
-      on the right.
-      Defaults to FALSE
+=== Method attributes ===
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+The following tags are not attributes but, rather, methods that perform various functions associated with toolbar configuration:
-    TOOLBAR_MinVisible (uint32)
+; TOOLBAR_AddImageSet (uint32)
-      If TOOLBAR_HandleOverflow is TRUE, this tag ensures that at least the
+: Creates a new image set. The value passed to this tag is a numeric ID identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to display the particular image set in the toolbar.
-      specified number of members (including spacers and separators) will
+: An image set must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.
-      always be visible. Ignored if TOOLBAR_HandleOverflow is FALSE.
+: This tag should be followed by a sequence of TOOLBAR_AddImage tags (see below), each creating one image in the given set.
+: If the gadget only uses one set of images, passing TOOLBAR_AddImageSet is not necessary. Each TOOLBAR_AddImage will add the respective image to the default image set identified by an ID of 0.
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])
-      Defaults to 1
+; TOOLBAR_AddImage (uint32)
+: Creates a new image in a given image set. The value passed to this tag is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID (see below) to associate the image with a particular toolbar member.
+: An image must have a valid ID. The value of TB_NO_ID (~0UL) is not applicable here.
+: This tag should be followed by a sequence of TBIMAGE_ tags (see the [[#Image attributes|Image attributes]] section below), each configuring one aspect of the image, including its optional selected variant (referred to as the "select image").
+: Images are added to the default image set unless a preceding TOOLBAR_AddImageSet specifies a different set.
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TOOLBAR_AddMember (uint32)
+: Creates a new toolbar member. The value passed to this tag is a numeric ID identifying the member.
+: Spacers and separators normally don't need an ID, so you can use TB_NO_ID as a value for TOOLBAR_AddMember when creating these members. However, if you want to manipulate spacers/separators in your GUI, an ID will be necessary so that you can pass it to TOOLBAR_SetMember to identify the respective spacer or separator member.
+: You can add members when the toolbar object is being created, i.e. as part of the NewObject() call, or at any time later via SetAttrs().
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]])
-    TOOLBAR_SpacerSize (uint32)
+; TOOLBAR_SetMember
-      The size of the spacer member, in pixels. This value will affect the
+: Use this tag in a SetAttrs() call to identify the member you want to modify.
-      width (in a horizontal toolbar) or the height (in a vertical toolbar)
+: Applicability is ([[#OM_SET|OM_SET]])
-      of the spacer.
-      Defaults to 5
+; TOOLBAR_SetGroup
+: Use this tag in a SetAttrs() call to identify the group of members you want to modify collectively.
+: Applicability is ([[#OM_SET|OM_SET]])
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+=== Member attributes ===
-    TOOLBAR_ButtonStyle (uint32)
+; TBMEMBER_Type (uint32)
-      The look of the toolbar buttons. TB_BUTSTYLE_CLASSIC will produce
+: The type of the toolbar member. The possible values are the following:
-      a traditional-looking toolbar with framed buttons, whereas
-      TB_BUTSTYLE_BORDERLESS will configure a borderless look.
-      Defaults to TB_BUTSTYLE_CLASSIC
+  TB_MTYPE_BUTTON -- a normal toolbar button
+  TB_MTYPE_TOGGLE -- a toggle (on/off) button
+  TB_MTYPE_SPACER -- a spacer
+  TB_MTYPE_SEPARATOR -- a separator bar
+  TB_MTYPE_TEXTBOX -- a read-only box to display text (V53.4)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+: The type is set upon member creation, and cannot be changed.
+: Defaults to TB_MTYPE_BUTTON
+: Applicability is (OM_NEW)
-    TOOLBAR_BevelStyle (uint32)
+; TBMEMBER_ImageID (uint32)
-      The style of the gadget's outer bevel (frame). The Bevel Image class
+: The identifier of the image to be used for the button or toggle member (see TOOLBAR_AddImage above). This tag is not relevant to textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_ImageID value of such a member.
-      is used, so the style values from <images/bevel.h> are applicable to
+: When [[#OM_SET|OM_SET]]-ing this attribute, the method will always return TB_NEED_RETHINK, to be on the safe side. However, invoking WM_RETHINK is really only needed if the size of the new image is different from the original image. If the size is the same, a simple gadget refresh will suffice. You can trigger the refresh:
-      this tag (although not all of them make good sense to use with the
+:* by setting this attribute via RefreshSetGadgetAttrs(), or
-      toolbar). The recommended values are:
+:* by setting this attribute via SetAttrs() and then invoking the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method on the respective button/toggle member.
-        BVS_NONE    -- no bevel is drawn around the toolbar
+: (The difference is that RefreshSetGadgetAttrs() will refresh the entire toolbar, while TBM_REFRESHMEMBER will only refresh the given member.)
-        BVS_DISPLAY -- provides a recessed, SpeedBar-compatible bevel
+: Defaults to TB_NO_ID (no image associated with this member)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      When using a bevel in TB_BUTSTYLE_CLASSIC mode (i.e. with framed toolbar
+; TBMEMBER_Text (CONST_STRPTR)
-      buttons), make sure that you also adjust TOOLBAR_HorizPadding and
+: The text to associate with a button, toggle or textbox member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_Text value of such a member.
-      TOOLBAR_VertPadding, otherwise the outer bevel will interfere with
+: The text will be used as fallback in case no image is found or provided for a button or a toggle member.
-      the button frames.
+: Multi-line text is supported: use "\n" as line separator in the text string.
+: The text string can contain an underscore character (_), indicating the keyboard shortcut for the member. (This doesn't apply to textbox members, as they are read-only and don't respond to the keyboard.)
+: If your toolbar features a textbox member the contents of which is going to change dynamically, it is highly recommended that you also set TBMEMBER_DomainString (see below) at member creation time. This will guarantee a size to accommodate any text, so you won't have to perform WM_RETHINK to recalculate the textbox size each time TBMEMBER_Text changes. Updating the text can be done in one of the following ways:
-       Defaults to BVS_NONE
+       (1)   IIntuition->SetGadgetAttrs(toolbar, window, NULL,
+                        TOOLBAR_SetMember, textboxID,
+                           TBMEMBER_Text, "New text",
+                        TAG_END);
-       Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+       (2)   IIntuition->SetAttrs(toolbar,
+                        TOOLBAR_SetMember, textboxID,
+                           TBMEMBER_Text, "New text",
+                        TAG_END);
+              IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, textboxID, window);
-    TOOLBAR_SeparatorStyle (uint32)
+: The difference is that (1) performs the textbox update immediately, whereas with (2) you can set the value "quietly" and only display it when you're ready, by calling the [[#TBM_REFRESHMEMBER|TBM_REFRESHMEMBER]] method.
-      Determines the look of the separator member. If you want to change it
+: Defaults to NULL
-      on the fly while the window is open, call SetGadgetAttrs() rather than
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      SetAttrs() to trigger an immediate redraw.
-      Defaults to TB_SEPSTYLE_NORMAL
+; TBMEMBER_DomainString (CONST_STRPTR) (V53.4)
+: A text string based on which the minimum size of the member will be calculated. This is useful especially with TB_MTYPE_TEXTBOX members when you want to enforce a minimum size required to fit text of variable length. The domain string ought to be at least as long as the longest text to appear in the textbox.
+: The domain string is never rendered in the gadget.
+: This tag is not relevant to spacers and separators.
+: Defaults to NULL
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TBMEMBER_TextAttr (struct TextAttr *) (V53.4)
+: Pointer to a TextAttr structure describing the font to be used for the member text. This tag overrides GA_TextAttr (see above).
+: Generally, you should use one "global" font for the toolbar, configured via GA_TextAttr. But there are situations where it makes sense to set a particular font at the member level, for example when using textbox members.
+: Defaults to the GA_TextAttr value
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-    TOOLBAR_SelectionStyle (uint32)
+; TBMEMBER_TextPen (uint16) (V53.4)
-      Determines how member selection is indicated in the borderless mode.
+: A pen to be used for the member text. Overrides TOOLBAR_TextPen (see above).
-      If the tag is set to TB_SELSTYLE_NONE, the gadget will not indicate the
+: Generally, you should use one "global" pen for the toolbar, configured via TOOLBAR_TextPen. But there are situations where it makes sense to set a particular pen at the member level, for example when using textbox members.
-      selection: the programmer must provide a select image for each button
+: Prefer to use pens from the dri_Pens[] array in your screen's DrawInfo structure; see the <intuition/screens.h> system include file.
-      or toggle member (see TBIMAGE_SelImage and TBIMAGE_SelImageFile below),
+: Defaults to the TOOLBAR_TextPen value
-      otherwise there will be no visual response. If the tag is set to
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-      TB_SELSTYLE_BEVEL, the gadget will draw a standard button bevel around
-      the member to indicate the selection.
-      This tag is ignored in the classic mode with framed buttons.
+; TBMEMBER_TextStyle (uint8) (V53.4)
+: A font style to be used for the member text. Overrides TOOLBAR_TextStyle (see above).
+: Generally, you should use one "global" style for the toolbar, configured via TOOLBAR_TextStyle. But there are situations where it makes sense to set a particular style at the member level, for example when using textbox members.
+: The styles are defined in the <graphics/text.h> system include file.
+: Defaults to the TOOLBAR_TextStyle value
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE)
-      Defaults to TB_SELSTYLE_NONE
+; TBMEMBER_Disabled (BOOL)
+: The current state (disabled or not disabled) of a member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Disabled value of such a member.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TBMEMBER_Hidden (BOOL)
+: Specifies whether the particular member is displayed in the toolbar or hidden. You can use this tag to create "dynamic" toolbar layouts that adapt the actual member set to various application settings.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-    TOOLBAR_BackFill (struct Hook *)
+; TBMEMBER_Selected (BOOL)
-      A custom backfill hook to provide a background filled with a specific
+: The current selection state of a toggle member. This tag is not relevant to normal buttons (TB_MTYPE_BUTTON), textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return FALSE should you inquire about the TBMEMBER_Selected value of such a member.
-      colour or pattern.
+: You can set a target BOOPSI object for any toggle member, using the standard icclass ICA_TARGET tag. The target will receive an automatic notification of the toggle selection. This way toolbar toggles can easily communicate with other boolean gadgets such as checkboxes.
+: Defaults to FALSE
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, OM_NOTIFY, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      This tag is meant to replace GA_BackFill because if the toolbar gadget
+; TBMEMBER_Group (uint32)
-      is placed in a layout, the value of GA_BackFill can only be set after
+: Member group ID. Several members can be manipulated at once if they are assigned to the same group. Use TOOLBAR_SetGroup with the respective group ID to identify the group to be manipulated.
-      the window opens (this is because the Layout Gadget propagates its own
+: Defaults to TB_NO_ID (not assigned to any group)
-      backfill to all of its children). TOOLBAR_BackFill is provided as
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      a convenience tag that overrides GA_BackFill, and allows setting your
-      backfill hook even before the window opens.
-      Defaults to NULL (the default layers backfill hook).
+; TBMEMBER_MXGroup (uint32)
+: MX group ID. Toggle members can be put in groups of mutually-exclusive buttons. When such a toggle is selected, all other toggles in the same MX group will become deselected.
+: This tag is not relevant to normal buttons, textboxes, spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return TB_NO_ID should you inquire about the TBMEMBER_MXGroup value of such a member.
+: Defaults to TB_NO_ID (not assigned to any MX group)
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE)
+; TBMEMBER_HintInfo (CONST_STRPTR)
+: The help text to be displayed when the user hovers the mouse pointer over the respective member. This tag is not relevant to spacers and separators; [[#TBM_GETMEMBER|TBM_GETMEMBER]] will always return NULL should you inquire about the TBMEMBER_HintInfo value of such a member.
+: Defaults to NULL
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-    TOOLBAR_Display (uint32)
+; TBMEMBER_UserData (APTR)
-      Specifies what you want to display inside the toolbar button or toggle
+: Arbitrary user data associated with this member.
-      members. The possible values are:
+: Defaults to NULL
-        TB_DISPLAY_IMAGES -- display only images
+: Applicability is (OM_NEW, [[#OM_SET|OM_SET]], OM_UPDATE, [[#TBM_GETMEMBER|TBM_GETMEMBER]])
-        TB_DISPLAY_TEXT   -- display only text labels
-        TB_DISPLAY_BOTH   -- display both images and text labels
-      Defaults to TB_DISPLAY_IMAGES
+=== Image attributes ===
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+Note: Images are configured at OM_NEW, i.e. when creating each respective image. Image attributes cannot be changed later.
-    TOOLBAR_TextPlace (uint32)
+; TBIMAGE_Image (struct Image *)
-      Specifies the placement of the text labels with regard to the toolbar
+: Custom image to be used for a button or a toggle member.
-      images. This tag is only meaningful when actual text labels are
+: Defaults to NULL
-      provided via TBMEMBER_Text, and TOOLBAR_Display is set to
+: Applicability is (OM_NEW)
-      TB_DISPLAY_BOTH.
-      Defaults to and currently only supports TB_PLACETEXT_BELOW
+; TBIMAGE_ImageFile (CONST_STRPTR)
+: The full path to the source file to create the image from. The image will be loaded and built using the Shared Image class.
+: All images created this way will also be disposed of automatically.
+: Defaults to NULL
+: Applicability is (OM_NEW)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; TBIMAGE_SelImage (struct Image *)
+: Custom image to display when the member becomes selected.
+: Defaults to NULL
+: Applicability is (OM_NEW)
-    TOOLBAR_LabelArray (STRPTR *)
+; TBIMAGE_SelImageFile (CONST_STRPTR)
-      Use this tag to create a minimum-configuration, text-only toolbar.
+: The full path to the source file to create the select image from. The image will be loaded and built using the Shared Image class.
-      You simply pass a NULL-terminated array of strings representing
+: All images created this way will also be disposed of automatically.
-      the toolbar button labels. Each label can contain an underscore
+: Defaults to NULL
-      character to indicate the keyboard shortcut for the respective button.
+: Applicability is (OM_NEW)
-      TOOLBAR_Display will be set to TB_DISPLAY_TEXT automatically.
+;TBIMAGE_Width (uint32)
+;TBIMAGE_Height (uint32)
+: Image dimensions, in pixels. These tags can only be used in connection with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the respective source file will be scaled to the specified width and height. Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot be resized using these tags.
+: Defaults to 0
+: Applicability is (OM_NEW)
-      Using this tag, the limitation is that you cannot create toggle members
+== Notes ==
-      (only buttons, separators and spacers).
-      A special string, " ", will create a spacer.
+Some of the attributes described above change the sizing requirements of the gadget. If set on the fly (i.e. when the toolbar is already displayed in the window), the gadget domain will need recalculating and a re-layout must take place. Refer to the [[#OM_SET|OM_SET]] method documentation below to see how to handle such situations.
-      A special string, "_", will create a separator.
-      Spacers and separators cannot appear as the very first member in the
+== Bugs ==
-      toolbar. Therefore, the label array may not begin with a spacer or
-      a separator string. Also, the array must contain at least one valid
-      string to create a button, otherwise the toolbar creation will fail.
-      The button strings are copied to an internal buffer, so the label array
+== See also ==
-      need not remain valid throughout the lifetime of the gadget.
-      Defaults to NULL
+== Methods ==
-      Applicability is (OM_NEW)
+=== OM_SET ===
-    TOOLBAR_EvenSize (BOOL)
+; NAME
-      If set to TRUE, this attribute will size all button and toggle members
+: OM_SET -- set toolbar attributes
-      evenly according to the largest member. The attribute has no effect
-      on spacers and separators.
-      If you only intend to use TB_DISPLAY_IMAGES (see TOOLBAR_Display above)
+; SYNOPSIS
-      and your toolbar images are all of the same size, keep this attribute
+: uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);
-      at its default FALSE value: the button dimensions will be equal anyway,
+: uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win, struct Requester *req, Tag tag1, ...);
-      and you'll spare the gadget some unnecessary calculations. On the other
-      hand, setting this tag to TRUE may produce a visually more plausible
-      result when TOOLBAR_Display is set to TB_DISPLAY_BOTH.
-      Defaults to FALSE
+; FUNCTION
+: This method sets the attributes of the toolbar and/or of its members. SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions to invoke this method.
+: To change a member attribute you first need to pass TOOLBAR_SetMember to identify the respective member, and then the member attribute tag(s). See the EXAMPLE section below.
+: To change an attribute collectively for a group of members you first need to pass TOOLBAR_SetGroup to identify the respective group, and then the member attribute tag(s). See the EXAMPLE section below.
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+; INPUTS
+  toolbar -- the toolbar gadget object
+  win -- the window that hosts the toolbar
+  req -- requester pointer (use NULL)
+  tag1 etc. -- a list of toolbar attribute tags
-    TOOLBAR_ImageSet (uint32)
+; RESULT
-      If more than one image set have been configured via TOOLBAR_AddImageSet
+: This method will return TB_NEED_RETHINK if the gadget ''believes'' that one or more of the attributes will change the sizing requirements of the toolbar. Typically, invoking the WM_RETHINK method on the gadget's window object is needed, in order to recalculate the domain and re-layout the contents.
-      (see below), use this tag to determine which set is to be displayed in
+: If you know you will be changing an attribute that requires a WM_RETHINK, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).
-      the toolbar. The value passed to this tag is the image set ID.
+: The method returns 0L if no rethink is needed.
-      Defaults to 0
+; EXAMPLE
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)
+  // To set various toolbar attributes:
+  if ( IIntuition->SetAttrs(toolbar,
-    *** Method attributes ***
+                   TOOLBAR_Orientation, TB_ORIENT_VERT,
+                   TOOLBAR_Spacing, 4,
-    The following tags are not attributes but, rather, methods that perform
+                   TOOLBAR_SpacerSize, 10,
-    various functions associated with toolbar configuration:
+                   TAG_END) == TB_NEED_RETHINK )
+   {
-    TOOLBAR_AddImageSet (uint32)
+     IIntuition->IDoMethod(winObj, WM_RETHINK);
-      Creates a new image set. The value passed to this tag is a numeric ID
+   }
-      identifying the set. Use this ID with TOOLBAR_ImageSet (see above) to
-      display the particular image set in the toolbar.
-      This tag should be followed by a sequence of TOOLBAR_AddImage tags (see
-      below), each creating one image in the given set.
-      If the gadget only uses one set of images, passing TOOLBAR_AddImageSet
-      is not necessary. Each TOOLBAR_AddImage will add the respective image
-      to the default image set identified by an ID of 0.
-      Applicability is (OM_NEW, OM_SET)
-    TOOLBAR_AddImage (uint32)
-      Creates a new image in a given image set. The value passed to this tag
-      is a numeric ID identifying the image. Use this ID with TBMEMBER_ImageID
-      (see below) to associate the image with a particular toolbar member.
-      This tag should be followed by a sequence of TBIMAGE_ tags (see the
-      "Image attributes" section below), each configuring one aspect of the
-      image, including its optional selected variant (referred to as the
-      "select image").
-      Images are added to the default image set unless a preceding
-      TOOLBAR_AddImageSet specifies a different set.
-      Applicability is (OM_NEW, OM_SET)
-    TOOLBAR_AddMember (uint32)
-      Creates a new toolbar member. The value passed to this tag is a numeric
-      ID identifying the member.
-      Spacers and separators normally don't need an ID, so you can use
-      TB_NO_ID as a value for TOOLBAR_AddMember when creating these members.
-      However, if you want to manipulate spacers/separators in your GUI,
-      an ID will be necessary so that you can pass it to TOOLBAR_SetMember
-      to identify the respective spacer or separator member.
-      You can add members when the toolbar object is being created, i.e.
-      as part of the NewObject() call, or at any time later via SetAttrs().
-      Applicability is (OM_NEW, OM_SET)
-    TOOLBAR_SetMember
-      Use this tag in a SetAttrs() call to identify the member you want to
-      modify.
-      Applicability is (OM_SET)
-    TOOLBAR_SetGroup
-      Use this tag in a SetAttrs() call to identify the group of members you
-      want to modify collectively.
-      Applicability is (OM_SET)
-    *** Member attributes ***
-    TBMEMBER_Type (uint32)
-      The type of the toolbar member. The possible values are the following:
-        TB_MTYPE_BUTTON    -- a normal toolbar button
-        TB_MTYPE_TOGGLE    -- a toggle (on/off) button
-        TB_MTYPE_SPACER    -- a spacer
-        TB_MTYPE_SEPARATOR -- a separator bar
-      The type is set upon member creation, and cannot be changed.
-      Defaults to TB_MTYPE_BUTTON
-      Applicability is (OM_NEW)
-    TBMEMBER_ImageID (uint32)
-      The identifier of the image to be used for the button or toggle member
-      (see TOOLBAR_AddImage above). This tag is not relevant to spacers and
-      separators; TBM_GETMEMBER will always return TB_NO_ID should you inquire
-      about the TBMEMBER_ImageID value of such a member.
-      Defaults to TB_NO_ID (no image associated with this member)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_Text (CONST_STRPTR)
-      The label to associate with a button or a toggle member. This tag is not
-      relevant to spacers and separators; TBM_GETMEMBER will always return
-      NULL should you inquire about the TBMEMBER_Text value of such a member.
-      The text label will be used as fallback in case no image is found or
-      provided.
-      The text string can contain an underscore character (_), indicating the
-      keyboard shortcut for this member.
-      Defaults to NULL
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_Disabled (BOOL)
-      The current state (disabled or not disabled) of a member. This tag is
-      not relevant to spacers and separators; TBM_GETMEMBER will always return
-      FALSE should you inquire about the TBMEMBER_Disabled value of such
-      a member.
-      Defaults to FALSE
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_Hidden (BOOL)
-      Specifies whether the particular member is displayed in the toolbar or
-      hidden. You can use this tag to create "dynamic" toolbar layouts that
-      adapt the actual member set to various application settings.
-      Defaults to FALSE
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_Selected (BOOL)
-      The current selection state of a toggle member. This tag is not relevant
-      to normal buttons (TB_MTYPE_BUTTON), spacers and separators;
-      TBM_GETMEMBER will always return FALSE should you inquire about the
-      TBMEMBER_Selected value of such a member.
-      You can set a target BOOPSI object for any toggle member, using the
-      standard icclass ICA_TARGET tag. The target will receive an automatic
-      notification of the toggle selection. This way toolbar toggles can
-      easily communicate with other boolean gadgets such as checkboxes.
-      Defaults to FALSE
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY, TBM_GETMEMBER)
-     TBMEMBER_Group (uint32)
-      Member group ID. Several members can be manipulated at once if they are
-      assigned to the same group. Use TOOLBAR_SetGroup with the respective
-      group ID to identify the group to be manipulated.
-      Defaults to TB_NO_ID (not assigned to any group)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_MXGroup (uint32)
-      MX group ID. Toggle members can be put in groups of mutually-exclusive
-      buttons. When such a toggle is selected, all other toggles in the same
-      MX group will become deselected.
-      This tag is not relevant to normal buttons, spacers and separators;
-      TBM_GETMEMBER will always return TB_NO_ID should you inquire about the
-      TBMEMBER_MXGroup value of such a member.
-      Defaults to TB_NO_ID (not assigned to any MX group)
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_HintInfo (CONST_STRPTR)
-      The help text to be displayed when the user hovers the mouse pointer
-      over the respective member. This tag is not relevant to spacers and
-      separators; TBM_GETMEMBER will always return NULL should you inquire
-      about the TBMEMBER_HintInfo value of such a member.
-      Defaults to NULL
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    TBMEMBER_UserData (APTR)
-      Arbitrary user data associated with this member.
-      Defaults to NULL
-      Applicability is (OM_NEW, OM_SET, OM_UPDATE, TBM_GETMEMBER)
-    *** Image attributes ***
-    TBIMAGE_Image (struct Image *)
-      Custom image to be used for a button or a toggle member.
-      Defaults to NULL
-      Applicability is (OM_NEW)
-    TBIMAGE_ImageFile (CONST_STRPTR)
-      The full path to the source file to create the image from. The image
-      will be loaded and built using the Shared Image class.
-      All images created this way will also be disposed of automatically.
-      Defaults to NULL
-      Applicability is (OM_NEW)
-    TBIMAGE_SelImage (struct Image *)
-      Custom image to display when the member becomes selected.
-      Defaults to NULL
-      Applicability is (OM_NEW)
-    TBIMAGE_SelImageFile (CONST_STRPTR)
+  // To disable a member:
-      The full path to the source file to create the select image from.
+  IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
-      The image will be loaded and built using the Shared Image class.
+              TOOLBAR_SetMember, memberID,
+                 TBMEMBER_Disabled, TRUE,
+              TAG_END);
-      All images created this way will also be disposed of automatically.
+  // To hide a member:
+  IIntuition->SetAttrs(toolbar,
+              TOOLBAR_SetMember, memberID,
+                 TBMEMBER_Hidden, TRUE,
+              TAG_END);
+  IIntuition->IDoMethod(winObj, WM_RETHINK);
-      Defaults to NULL
+  // To modify several member attributes at once:
+  IIntuition->SetAttrs(toolbar,
+              TOOLBAR_SetMember, memberID,
+                 TBMEMBER_HintInfo, "My help string",
+                 TBMEMBER_UserData, anything,
+              TAG_END);
-      Applicability is (OM_NEW)
+  // To disable all members assigned to a group:
+  IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
+              TOOLBAR_SetGroup, groupID,
+                 TBMEMBER_Disabled, TRUE,
+              TAG_END);
-    TBIMAGE_Width (uint32)
+; NOTES
-    TBIMAGE_Height (uint32)
-      Image dimensions, in pixels. These tags can only be used in connection
+; BUGS
-      with TBIMAGE_ImageFile / TBIMAGE_SelImageFile, in which case the
-      respective source file will be scaled to the specified width and height.
+; SEE ALSO
-      Custom images provided via TBIMAGE_Image and TBIMAGE_SelImage cannot
-      be resized using these tags.
-      Defaults to 0
+=== TBM_GETMEMBER ===
-      Applicability is (OM_NEW)
+; NAME
+: TBM_GETMEMBER -- obtain the value of a specific member attribute
-  NOTES
+; SYNOPSIS
-    Some of the attributes described above change the sizing requirements of
+: uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);
-    the gadget. If set on the fly (i.e. when the toolbar is already displayed
+: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, uint32 attrID, uint32 *storage);
-    in the window), the gadget domain will need recalculating and a re-layout
-    must take place. Refer to the OM_SET method documentation below to see
-    how to handle such situations.
-    Images are configured at OM_NEW, i.e. when creating each respective image.
+; FUNCTION
-    Image attributes cannot be changed later.
+: Use this method to obtain the value of a given member attribute.
+: Because of the way OM_GET is implemented in Intuition, getting member attributes is done differently compared to setting them. The difference boils down to the following:
+:* We cannot use a convenience function such as GetAttr() or GetAttrs(), so a dedicated method is provided. Refer to the EXAMPLE section below to see how to invoke the method.
+:* Only one attribute can be queried at a time. (As multiple attributes will rarely be requested in real use, this limitation should not pose a significant problem.)
-  BUGS
+; INPUTS
+For IDoMethodA():
+   toolbar -- the toolbar gadget object
-   SEE ALSO
+  msg -- a pointer to an initialized tbGetMember structure
-toolbar.gadget/OM_SET                                     toolbar.gadget/OM_SET
-  NAME
+For IDoMethod():
-    OM_SET -- set toolbar attributes
-   SYNOPSIS
+   toolbar -- the toolbar gadget object
-    uint32 result = SetAttrs(Object *toolbar, Tag tag1, ...);
+  methodID -- this method's identifier, TBM_GETMEMBER
+  memberID -- the member identifier (as set in TOOLBAR_AddMember)
+  attrID -- the attribute tag identifier
+  storage -- a pointer to the variable for storing the attribute value
-    uint32 result = SetGadgetAttrs(struct Gadget *toolbar, struct Window *win,
+; RESULT
-                                   struct Requester *req, Tag tag1, ...);
+: The "result" value will be 1L if the requested attribute value has been obtained successfully. The attribute value itself is returned in the provided storage variable.
-  FUNCTION
+; EXAMPLE
-    This method sets the attributes of the toolbar and/or of its members.
-    SetAttrs() and SetGadgetAttrs() are Intuition's convenience functions
-    to invoke this method.
-    To change a member attribute you first need to pass TOOLBAR_SetMember
+  // To query about the selection state of a toggle member:
-    to identify the respective member, and then the member attribute tag(s).
+  uint32 storage;
-    See the EXAMPLE section below.
+  IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID, TBMEMBER_Selected, &storage);
-    To change an attribute collectively for a group of members you first need
+; NOTES
-    to pass TOOLBAR_SetGroup to identify the respective group, and then the
-    member attribute tag(s). See the EXAMPLE section below.
+; BUGS
+; SEE ALSO
-  INPUTS
+=== TBM_REFRESHMEMBER ===
-    toolbar   -- the toolbar gadget object
-    win       -- the window that hosts the toolbar
-    req       -- requester pointer (use NULL)
-    tag1 etc. -- a list of toolbar attribute tags
-  RESULT
+; NAME
-    This method will return TB_NEED_RETHINK if one or more of the attributes
+: TBM_REFRESHMEMBER -- refresh the imagery of a given member (V53.3)
-    change the sizing requirements of the gadget. In such a case, the
-    appropriate reaction is to call WM_RETHINK on the gadget's window object
-    to recalculate the domain and re-layout the contents.
-    If you know you will be changing an attribute that requires a WM_RETHINK,
+; SYNOPSIS
-    prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an
+: uint32 result = IDoMethodA(Object *toolbar, struct tbRefreshMember *msg);
-    unnecessary redraw (WM_RETHINK will perform the redraw for you).
+: uint32 result = IDoMethod(Object *toolbar, uint32 methodID, uint32 memberID, struct Window *window);
-    The method returns 0 if no rethink is needed.
+; FUNCTION
+: Use this method to refresh the imagery of a given button or toggle member.
+: The method has no effect on spacers and separators.
-   EXAMPLE
+; INPUTS
+For IDoMethodA():
+   toolbar  -- the toolbar gadget object
+  msg      -- a pointer to an initialized tbRefreshMember structure
-    // To set various toolbar attributes:
+For IDoMethod():
-    if ( IIntuition->SetAttrs(toolbar,
+  toolbar  -- the toolbar gadget object
-                     TOOLBAR_Orientation, TB_ORIENT_VERT,
+  methodID -- this method's identifier, TBM_REFRESHMEMBER
-                     TOOLBAR_Spacing, 4,
+  memberID -- the member identifier (as set in TOOLBAR_AddMember)
-                     TOOLBAR_SpacerSize, 10,
+  window   -- a pointer to the window the toolbar resides in
-                     TAG_END) == TB_NEED_RETHINK )
-     {
-      IIntuition->IDoMethod(winObj, WM_RETHINK);
-     }
-    // To disable a member:
+; RESULT
-    IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
+: The "result" value will be 1L if the refresh has taken place.
-                TOOLBAR_SetMember, MEMBER_ID,
-                  TBMEMBER_Disabled, TRUE,
-                TAG_END);
-    // To hide a member:
+; EXAMPLE
-    IIntuition->SetAttrs(toolbar,
-                TOOLBAR_SetMember, MEMBER_ID,
-                  TBMEMBER_Hidden, TRUE,
-                TAG_END);
-    IIntuition->IDoMethod(winObj, WM_RETHINK);
-    // To modify several member attributes at once:
+  IIntuition->IDoMethod(toolbar, TBM_REFRESHMEMBER, memberID, window);
-    IIntuition->SetAttrs(toolbar,
-                TOOLBAR_SetMember, MEMBER_ID,
-                  TBMEMBER_HintInfo, "My help string",
-                  TBMEMBER_UserData, anything,
-                TAG_END);
-    // To disable all members assigned to a group:
+; NOTES
-    IIntuition->SetGadgetAttrs((struct Gadget *) toolbar, win, NULL,
-                TOOLBAR_SetGroup, GROUP_ID,
-                  TBMEMBER_Disabled, TRUE,
-                TAG_END);
-  NOTES
-  BUGS
+; BUGS
-  SEE ALSO
+; SEE ALSO
-toolbar.gadget/TBM_GETMEMBER                       toolbar.gadget/TBM_GETMEMBER
-  NAME
-    TBM_GETMEMBER -- obtain the value of a specific member attribute
-  SYNOPSIS
-    uint32 result = IDoMethodA(Object *toolbar, struct tbGetMember *msg);
-    uint32 result = IDoMethod(Object *toolbar, uint32 methodID,
-                              uint32 attrID, uint32 *storage);
-  FUNCTION
-    Use this method to obtain the value of a given member attribute.
-    Because of the way OM_GET is implemented in Intuition, getting member
-    attributes is done differently compared to setting them. The difference
-    boils down to the following:
-    - We cannot use a convenience function such as GetAttr() or GetAttrs(),
-      so a dedicated method is provided. Refer to the EXAMPLE section below
-      to see how to invoke the method.
-    - Only one attribute can be queried at a time. (As multiple attributes
-      will rarely be requested in real use, this limitation should not pose
-      a significant problem.)
-  INPUTS
-    For IDoMethodA():
-      toolbar  -- the toolbar gadget object
-      msg      -- a pointer to an initialized tbGetMember structure
-    For IDoMethod():
-      toolbar  -- the toolbar gadget object
-      methodID -- this method's identifier, TBM_GETMEMBER
-      attrID   -- the attribute tag identifier
-      storage  -- a pointer to the variable for storing the attribute value
-  RESULT
-    The "result" value will be 1L if the requested attribute value has been
-    obtained successfully. The attribute value itself is returned in the
-    provided storage variable.
- EXAMPLE
-    // To query about the selection state of a toggle member:
-    uint32 storage;
-    IIntuition->IDoMethod(toolbar, TBM_GETMEMBER, memberID,
-                          TBMEMBER_Selected, &storage);