Difference between revisions of "ToolBar Gadget Class"

Revision as of 13:31, 31 October 2020

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)

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 gadget's button text labels (if they are used).; Defaults to 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 layers 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_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.; Defaults to and currently only supports 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 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.; 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): 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.

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

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 one or more of the attributes 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, prefer to use SetAttrs() instead of SetGadgetAttrs() to avoid an unnecessary redraw (WM_RETHINK will perform the redraw for you).; The method returns 0 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, MEMBER_ID,
               TBMEMBER_Disabled, TRUE,
             TAG_END);

 // To hide a member:
 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->SetAttrs(toolbar,
             TOOLBAR_SetMember, MEMBER_ID,
               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, GROUP_ID,
               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 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);

NOTES

BUGS

SEE ALSO