@database "clicktab_gc"
@master "AMIDEV:NDK/Autodocs/clicktab_gc.doc"

@Node Main "clicktab_gc.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" --datasheet--() " Link "--datasheet--()"}
    @{" AllocClickTabNodeA() " Link "AllocClickTabNodeA()"}
    @{" CLICKTAB_GetClass() " Link "CLICKTAB_GetClass()"}
    @{" FreeClickTabNode() " Link "FreeClickTabNode()"}
    @{" GetClickTabNodeAttrsA() " Link "GetClickTabNodeAttrsA()"}
    @{" SetClickTabNodeAttrsA() " Link "SetClickTabNodeAttrsA()"}
@EndNode

@Node "--datasheet--()" "clicktab_gc/--datasheet--"

@{b}    NAME@{ub}
        clicktab.gadget -- File folder tabs gadget.

@{b}    SUPERCLASS@{ub}
        gadgetclass

@{b}    REQUIRES@{ub}
        Chooser.gadget.

@{b}    DESCRIPTION@{ub}
        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.

@{b}    DYNAMIC TABS@{ub}
        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" Link "window_cl/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.

@{b}    METHODS@{ub}
        @{"OM_NEW" Link "tabs_gc/OM_NEW"} -- Create the button gadget.  Passed to superclass, then OM_SE
T.

        @{"OM_GET" Link "tabs_gc/OM_GET"} -- Get an object attribute.  Passed to superclass for unknown
            attributes.

        @{"OM_SET" Link "tabs_gc/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" Link "tabs_gc/GM_RENDER"} -- Renders the gadget imagry.  Overrides the superclass.

        @{"GM_HITTEST" Link "tabs_gc/GM_HITTEST"} -- Determines if mouse is within the gadget rectangle.
            Overrides the superclass.

        @{"GM_GOACTIVE" Link "tabs_gc/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.

@{b}    ATTRIBUTES@{ub}

        GA_ID (WORD)
            Applicability is (OM_NEW, @{"OM_SET" Link "tabs_gc/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" Link "tabs_gc/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" Link "INCLUDE:graphics/text.h/Main" 63} *)
            Optional text attribute for the font to use for the labels.

            Defaults to @{"NULL" Link "rexxsupport/NULL"}.

        GA_Text (STRPTR *) (V45)
            A @{"NULL" Link "rexxsupport/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" Link "rexxsupport/NULL"}.

            Applicability is (OM_NEW)

        CLICKTAB_Labels (struct @{"List" Link "INCLUDE:exec/lists.h/Main" 19} *)
            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" Link "rexxsupport/NULL"}.

            Applicability is (OM_NEW, @{"OM_GET" Link "tabs_gc/OM_GET"}, OM_SET)

        CLICKTAB_Current (LONG)
            Currently selected tab.

            Defaults to 0.

            Applicability is (OM_NEW, @{"OM_GET" Link "tabs_gc/OM_GET"}, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_NOTIFY)

        CLICKTAB_CurrentNode (LONG)
            Currently selected tab node.

            Defaults to @{"NULL" Link "rexxsupport/NULL"}.

            Applicability is (OM_NEW, @{"OM_GET" Link "tabs_gc/OM_GET"}, @{"OM_SET" Link "tabs_gc/OM_SET"}, OM_NOTIFY)

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

            Defaults to @{"NULL" Link "rexxsupport/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" Link "tabs_gc/OM_SET"}, OM_GET)

        CLICKTAB_PageGroupBackFill (struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *) (V42)
            Embedded PageObject + selected ClickTab backfill pointer.

            Defaults to @{"NULL" Link "rexxsupport/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" Link "rexxsupport/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" Link "INCLUDE:exec/nodes.h/Main" 21} *) (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" Link "rexxsupport/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" Link "window_cl/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" Link "tabs_gc/GM_RENDER"}
           in order to size & position its imagery correctly.

@EndNode

@Node "AllocClickTabNodeA()" "clicktab_gc/AllocClickTabNodeA"

@{b}    NAME@{ub}
        AllocClickTabNodeA -- @{"Allocate" Link "exec/Allocate()"} a ClickTab node.

@{b}    SYNOPSIS@{ub}
        struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} * AllocClickTabNode(Tag, ...)
        node = AllocClickTabNode(Tag, ...)

        struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} * AllocClickTabNodeA(struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        node = AllocClickTabNodeA(taglist)

@{b}    FUNCTION@{ub}
        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.

@{b}    INPUTS@{ub}
        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.

@{b}    TNA_CloseGadget@{ub}
        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.

@{b}    RESULT@{ub}
        node - A node that can be added into the Exec list of labels for
            a ClickTab gadget.

@{b}    SEE ALSO@{ub}
        @{"FreeClickTabNode()" Link "FreeClickTabNode()"}, @{"SetClickTabNodeAttrsA()" Link "SetClickTabNodeAttrsA()"}

@EndNode

@Node "CLICKTAB_GetClass()" "clicktab_gc/CLICKTAB_GetClass"

@{b}    NAME@{ub}
        CLICKTAB_GetClass -- Gets the pointer to the clicktab class.

@{b}    SYNOPSIS@{ub}
        clicktab_class = CLICKTAB_GetClass();
        D0

        Class * CLICKTAB_GetClass(VOID);

@{b}    FUNCTION@{ub}
        Obtains the pointer to the ClickTab gadget class for use with
        @{"NewObject()" Link "intuition/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.

@{b}    INPUTS@{ub}
        Nothing.

@{b}    RESULT@{ub}
        clicktab_class - Pointer to the ClickTab gadget class.

@{b}    SEE ALSO@{ub}

@EndNode

@Node "FreeClickTabNode()" "clicktab_gc/FreeClickTabNode"

@{b}    NAME@{ub}
        FreeClickTabNode -- Free a ClickTab node.

@{b}    SYNOPSIS@{ub}
        VOID FreeClickTabNode(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *)
        FreeClickTabNode(node)

@{b}    FUNCTION@{ub}
        Frees a ClickTabNode allocated with @{"AllocClickTabNodeA()" Link "AllocClickTabNodeA()"}.

@{b}    INPUTS@{ub}
        node - The node to free.

@{b}    SEE ALSO@{ub}
        @{"AllocClickTabNodeA()" Link "AllocClickTabNodeA()"}

@EndNode

@Node "GetClickTabNodeAttrsA()" "clicktab_gc/GetClickTabNodeAttrsA"

@{b}    NAME@{ub}
        GetClickTabNodeAttrsA -- Get attributes about a ClickTab node.

@{b}    SYNOPSIS@{ub}
        VOID GetClickTabNodeAttrs(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...)
        GetClickTabNodeAttrs(node, firsttag, ...)

        VOID GetClickTabNodeAttrsA(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        GetClickTabNodeAttrsA(node, taglist)

@{b}    FUNCTION@{ub}
        The ClickTab uses a private node structure and all attributes
        are hidden, and must therefore be accessed with this function.

@{b}    INPUTS@{ub}
        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.

@{b}    SEE ALSO@{ub}
        @{"SetClickTabNodeAttrsA()" Link "SetClickTabNodeAttrsA()"}

@EndNode

@Node "SetClickTabNodeAttrsA()" "clicktab_gc/SetClickTabNodeAttrsA"

@{b}    NAME@{ub}
        SetClickTabNodeAttrsA -- Set attributes of a ClickTab node.

@{b}    SYNOPSIS@{ub}
        VOID SetClickTabNodeAttrs(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...)
        SetClickTabNodeAttrs(node, firsttag, ...)

        VOID SetClickTabNodeAttrsA(struct @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *)
        SetClickTabNodeAttrsA(node, taglist)

@{b}    FUNCTION@{ub}
        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()" Link "layout_gc/RethinkLayout()"}.

@{b}    TAGS@{ub}
        TNA_Text (STRPTR)

            @{"Text" Link "graphics/Text()"} string to appear as a line in the ClickTab menu node.

        TNA_HelpText (STRPTR)

            @{"Text" Link "graphics/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].

@{b}    INPUTS@{ub}
        node - @{"Node" Link "INCLUDE:exec/nodes.h/Main" 21} whose attributes you are changing.
        taglist - @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28} list of attributes to change.

@{b}    SEE ALSO@{ub}
        @{"GetClickTabNodeAttrsA()" Link "GetClickTabNodeAttrsA()"}

@EndNode