ToolBar Gadget Class

From wiki.amiga.org
Revision as of 11:27, 25 October 2020 by Admin (talk | contribs) (Created page with "Toolbar Gadget Class =NAME= toolbar.gadget -- Create toolbar BOOPSI objects =SUPERCLASS= gadgetclass =REQUIRES= button.gadget, select.gadget, label.image, beve...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Toolbar Gadget Class


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.

METHODS

   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

   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


 SEE ALSO
   

toolbar.gadget/OM_SET toolbar.gadget/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
   

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);