clicktab.gadget Reference

Comprehensive function reference for clicktab.gadget, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/clicktab).

This page documents 6 functions of clicktab.gadget. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

clicktab.gadget()

**clicktab.gadget -- File folder tabs gadget.

SUPERCLASS
    gadgetclass

REQUIRES
    Chooser.gadget.

DESCRIPTION
    The tabs gadget class provides a custom control that has imagry
    similar in style to the tabs seen in a real world drawer full of
    file folders.

    The action of the gadget is the same as a conventional
    mutual-exclusion control in that only one tab can be active at a
    time and a tab is selected by clicking upon it.

    Tabs may also have an optional close gadget attached to them, which
    can be used to close the relevant item.

    The tabs gadget class is best used in combination with a page.gadget
    so the user can select a tab and the appropriate page is displayed.
    The tab "bar" allows strumming across the selections. The current
    selection is displayed differently according to various GUI
    preferences.

DYNAMIC TABS
    With version 53 and V47, the clicktab.gadget has been updated to allo

w tabs to be added and removed dynamically. Simply detaching the label list from the gadget, adding or removing clicktab nodes, and reattaching the list is sufficient to induce this behaviour.

    When using dynamic tabs it is possible too many tabs are added that
    can possibly fit within the drawing bounds. When this situation
    occurs, clicktab will hide tabs that will not fit and a chooser
    gadget will automatically appear to enable the user to select any
    hidden tabs.

    Dynamic tabs also change the way GM_DOMAIN is handled. Normally,
    there are a fixed number of tabs and the tab labels do not change.
    This means the GM_DOMAIN does not change and any layout gadgets
    can work normally. With dynamic tabs, the GM_DOMAIN changing as
    tabs are added, removed and renamed. The CLICKTAB_AutoFit tag has
    been introduced to handle this situation and should always be set
    when working with dynamic tabs so that the GM_DOMAIN remains
    constant at a reasonable minimal size.

    Do not forget to call WM_RETHINK or equivalent when not using the
    CLICKTAB_AutoFit tag. Otherwise the graphics may render outside of
    the window boundaries due to the changing GM_DOMAIN.

    When using dynamic tabs with a PageGroup attached to the gadget,
    you must make sure to heed the following:
    If CLICKTAB_AutoTabNumbering is set to FALSE, the TNA_Number
    attribute will not be recalculated when the tab list is added
    back to the gadget after removing a tab. This will cause the
    PageGroup object to display the wrong page. This is especially
    important if you are removing the layout object from the PageGroup
    with PAGE_Remove when removing the tab, as it may cause the
    PageGroup to try rendering a layout which has been disposed of.
    If you intend to remove tabs and its associated layout object,
    then make sure the CLICKTAB_AutoTabNumbering is set to TRUE.
    If you do not remove the layouts from the PageObject, then ensure
    that the tabs do not get renumbered, as this will keep the two
    gadgets in synchronisation.

    More details can be found in the SDK examples directory.

METHODS
    OM_NEW -- Create the button gadget.  Passed to superclass, then OM_SE

T.

    OM_GET -- Get an object attribute.  Passed to superclass for unknown
        attributes.

    OM_SET -- Set object attributes.  Passed to superclass first.

    OM_UPDATE -- Set object notification attributes.  Passed to superclas

s first.

    OM_NOTIFY -- Sets  taglist for notification and pass to superclass.

    GM_DOMAIN -- Calculate imagery & positioning, and return
        minimum/maximum domain size.

    GM_RENDER -- Renders the gadget imagry.  Overrides the superclass.

    GM_HITTEST -- Determines if mouse is within the gadget rectangle.
        Overrides the superclass.

    GM_GOACTIVE -- Handles activation, toggle-select and button-select.
        Overrides the superclass.

    GM_GOINACTIVE -- Deactivates object.  Overrides the superclass.

    GM_HANDLEINPUT -- Handles selection input, RMB undo/abort, etc.

    GM_KEYACTIVE -- Activates gadget via keyboard, selects appropriate
        tab based on input key.  Invoked by window.class only.

    GM_KEYINACTIVE -- Deactivates gadget.  Invoked by window.class only.

    GM_HELPTEST -- Handles gadget help. When the mouse is over a tab,
        the method returns GMR_HELPCODE along with the tabindex. Before
        V45 GMR_HELPHIT was the only return value besides 0L, also 
        before V45 this method didn't return a reliable result in all cas

es.

    All other methods are passed to the superclass, including OM_DISPOSE.

ATTRIBUTES

    GA_ID (WORD)
        Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY)

    GA_Top (LONG) 
        The top of the gadget.  Typically win->BorderTop + 2 for proper
        placement along the inner top of a window unless used within a
        layout gadget group, then placement is automatic.

    GA_Left (LONG)
        The left edge of the gadget.

    GA_Height (LONG)
        Height of the gadget.  Typically font height plus eight.

    GA_RelHeight (LONG)
        Like all other ReAction gadgets, this attribute is supported.
        However, due to the nature of the classes intended visuals
        it is stylistically a bad thing to do.

    GA_Disabled (BOOL) -- Determines whether the gadget is disabled or
        not.  Changing disable state will invoke GM_RENDER.  A disabled
        gadget's border and label are all rendered in SHADOWPEN and then
        dusted in a ghosting pattern that is rendered in SHADOWPEN.

        This tag did nothing until V47.

        Defaults to FALSE.

    GA_TextAttr (struct TextAttr *)
        Optional text attribute for the font to use for the labels.

        Defaults to NULL.

    GA_Text (STRPTR *) (V45)
        A NULL terminated array of strings to use as labels. New for V45.

1. The array can be allocated on the stack, the text, however needs to stay for the whole lifetime of the object.

        Defaults to NULL.

        Applicability is (OM_NEW)

    CLICKTAB_Labels (struct List *)
        A list of clicktab node structures used to indicate the labels
        for each of the tabs.

        Note this list of nodes is the application's responsibility and
        will not be automatically freed when the clicktab.gadget is
        deleted.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_GET, OM_SET)

    CLICKTAB_Current (LONG)
        Currently selected tab.

        Defaults to 0.

        Applicability is (OM_NEW, OM_GET, OM_SET, OM_NOTIFY)

    CLICKTAB_CurrentNode (LONG)
        Currently selected tab node.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_GET, OM_SET, OM_NOTIFY)

    CLICKTAB_PageGroup (LONG) (V41.43)
        Embedded PageObject child pointer.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    CLICKTAB_PageGroupBorder (BOOL) (V53.7)
        Specify whether to draw a border around the pages of
        the gadget.

        Defaults to TRUE.

        Applicability is (OM_NEW, OM_SET, OM_GET)

    CLICKTAB_PageGroupBackFill (struct Hook *) (V42)
        Embedded PageObject + selected ClickTab backfill pointer.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    CLICKTAB_CloseImage (Object *) (V53.29 and V47)
       Specify the image you want to use as the close gadget. Ideally
       this should be at least a pointer to a dual state BOOPSI image,
       so that it changes visibly when pressed. You may allocate this
       multi-state image using the bitmap.image class. Check the
       CloseTest example program for further information on creating the
       BOOPSI image. In the interests of not confusing the user, you
       should avoid changing images after the gadget has been created, as
       this image applies to all tabs. The image will not be freed when
       the gadget is disposed of, this is your responsibility. This does
       mean, however, that you may share the same image between multiple
       clicktab.gadget instances.
       NB: Only the currently active tab will display the close gadget,
       as closing inactive tabs is not supported.

       Defaults to NULL (no gadget displayed).

       Applicability is (OM_NEW, OM_SET)

    CLICKTAB_ClosePlacement (ULONG) (V53.30 and V47)
       Specify which side of the tab to place the close gadget. Choices
       are PLACECLOSE_LEFT and PLACECLOSE_RIGHT.

       Defaults to PLACECLOSE_LEFT.

       Applicability is (OM_NEW, OM_SET)

    CLICKTAB_NodeClosed (struct Node *) (V53.29 and V47)
       After receiving a GADGETUP event you should check this attribute t

o see if the user selected a tabs close gadget. See CLICKTAB_Closed for further information. You should also check the TNA_CloseGadget attribute documentation in the AllocClickTabNode function to see h ow to set the close gadget for each node. Like the above, this is als o reset once either attribute is read.

       Defaults to NULL.

       Applicability is (OM_GET) and for V47: OM_NOTIFY

    CLICKTAB_AutoFit (BOOL) (V53.20 and V47)
       Enables auto-fit mode which tries to fit as many tabs as
       possible within the current bounds while keeping the GM_DOMAIN
       constant at a reasonable size.

       This is especially important when your application invokes the
       WM_RETHINK method when dynamically adding/removing objects
       in a layout for example.

       Defaults to FALSE.

       Applicability is (OM_NEW, OM_SET)**

Notes

       This class is best suited for use in a ReAction layout group
       and requires receiving GM_DOMAIN prior to the first GM_RENDER
       in order to size & position its imagery correctly.

AllocClickTabNodeA()

AllocClickTabNodeA -- Allocate a ClickTab node.

Synopsis

struct Node * AllocClickTabNode(Tag, ...)
node = AllocClickTabNode(Tag, ...)
struct Node * AllocClickTabNodeA(struct TagItem *)
node = AllocClickTabNodeA(taglist)

Function

    Allocates a node that can be added to the Exec linked list of
    labels in the clicktab.  This is the only way to allocate a
    node for this list, you cannot allocate nodes yourself because
    the ClickTab class uses a private node structure.

Inputs

    taglist - Attributes for the node, passed onto SetClickTabNodeAttrsA(

).

    A full list of attributes is listed in the SetClickTabNodeAttrs
    documentation, attributes below are only applicable when the node
    is first allocated.

TNA_CloseGadget
    This specifies that the node for this tab should have a close gadget
    attached. Space in the tab is reserved for it. See CLICKTAB_CloseImag

e, CLICKTAB_Closed and CLICKTAB_NodeClosed for further information.

RESULT
    node - A node that can be added into the Exec list of labels for
        a ClickTab gadget.

See also

    FreeClickTabNode(), SetClickTabNodeAttrsA()

CLICKTAB_GetClass()

CLICKTAB_GetClass -- Gets the pointer to the clicktab class.

Synopsis

clicktab_class = CLICKTAB_GetClass();
D0

Class * CLICKTAB_GetClass(VOID);

Function

    Obtains the pointer to the ClickTab gadget class for use with
    NewObject().  This function always returns a valid pointer so
    you do not need to check it.  The reason is that if the library
    opens fine, then the pointer returned is already setup.  (Of course
    this implies that if opening the library fails, you shouldn't be
    calling this.)

    Note that this function does not create the class, that is done
    when the class library is opened.

Inputs

    Nothing.

RESULT
    clicktab_class - Pointer to the ClickTab gadget class.

FreeClickTabNode()

FreeClickTabNode -- Free a ClickTab node.

Synopsis

VOID FreeClickTabNode(struct Node *)
FreeClickTabNode(node)

Function

    Frees a ClickTabNode allocated with AllocClickTabNodeA().

Inputs

    node - The node to free.

See also

    AllocClickTabNodeA()

GetClickTabNodeAttrsA()

GetClickTabNodeAttrsA -- Get attributes about a ClickTab node.

Synopsis

VOID GetClickTabNodeAttrs(struct Node *, Tag, ...)
GetClickTabNodeAttrs(node, firsttag, ...)
VOID GetClickTabNodeAttrsA(struct Node *, struct TagItem *)
GetClickTabNodeAttrsA(node, taglist)

Function

    The ClickTab uses a private node structure and all attributes
    are hidden, and must therefore be accessed with this function.

Inputs

    node - The ClickTab node to get the information on.
    taglist - A tag list of attributes to get.  ti_Tag is the attribute
        to get and ti_Data is a pointer to a location to copy the result
        to.  The exception is LBNA_Column, which is used to specify a
        column to get attributes on.

See also

    SetClickTabNodeAttrsA()

SetClickTabNodeAttrsA()

SetClickTabNodeAttrsA -- Set attributes of a ClickTab node.

Synopsis

VOID SetClickTabNodeAttrs(struct Node *, Tag, ...)
SetClickTabNodeAttrs(node, firsttag, ...)
VOID SetClickTabNodeAttrsA(struct Node *, struct TagItem *)
SetClickTabNodeAttrsA(node, taglist)

Function

    Changes attributes for a ClickTab node.  Since the ClickTab
    class uses a private node structure, this is the only way to change
    node attributes.

    You may NOT change node attributes when the node is in a list
    attached to a ClickTab gadget.  You must first detach the list
    with CLICKTAB_Labels, ~0 before you can change attributes, and
    then re-attach the list, and re-render the gadget to reflect
    any changes. This should include re-domaining the gadget.
    If used in a layout group, turn off domain caching for the
    clicktab object if you intend to dynamically alter the tabs
    and refresh the layout group with RethinkLayout().

TAGS
    TNA_Text (STRPTR)

        Text string to appear as a line in the ClickTab menu node.

    TNA_HelpText (STRPTR)

        Text string to use as helptext when tab is hovered.
        It is copied to a local cache and forgotten.

    TNA_Number (WORD)

        ID Number assigned to a ClickTab menu node

    TNA_TextPen (WORD)

        Specifies pen number to use for the label.

        Defaults to pens[TEXTPEN].

Inputs

    node - Node whose attributes you are changing.
    taglist - Tag list of attributes to change.

See also

    GetClickTabNodeAttrsA()