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

@Node Main "button_gc.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" --datasheet--() " Link "--datasheet--()"}
    @{" BUTTON_GetClass() " Link "BUTTON_GetClass()"}
@EndNode

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

@{b}    NAME@{ub}
        button_gc -- create button BOOPSI objects

@{b}    SUPERCLASS@{ub}
        gadgetclass

@{b}    REQUIRES@{ub}
        bevel.image, glyph.image

@{b}    DESCRIPTION@{ub}
        The button gadget class is used to create action buttons that are
        momentary, toggle and sticky.  This class also supports relativity
        and placement within the window border.

        Advantages that this class provides:

         > Centered images.

         > Centered pen-sensitive glyphs.

         > Multi-frame images animation ability (since V42).

         > Ability to change the text and background colors for normal
           and selected buttons.

         > Supports window relativity.

         > Supports OS 3.0 BOOPSI gadget help test.

@{b}    METHODS@{ub}
        @{"OM_NEW" Link "tabs_gc/OM_NEW"} -- Passed to superclass, defaults set, then @{"OM_SET" Link "tabs_gc/OM_SET"}.

        @{"OM_SET" Link "tabs_gc/OM_SET"} -- Passed to superclass, custom tags set.

        @{"OM_GET" Link "tabs_gc/OM_GET"} -- @{"Custom" Link "INCLUDE:hardware/custom.h/Main" 23} tag returned or passed to superclass.

        OM_UPDATE -- Passed to superclass, options set then rendered.

        OM_NOTIFY -- @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28} set then passed to superclass.

        OM_DISPOSE -- MemPool memory freed, then passed to superclass.

        @{"GM_RENDER" Link "tabs_gc/GM_RENDER"} -- Passed to superclass, then button is rendered.

        @{"GM_HITTEST" Link "tabs_gc/GM_HITTEST"} -- Overrides supperclass, returns GMR_HITTEST.

        @{"GM_GOACTIVE" Link "tabs_gc/GM_GOACTIVE"} -- Passed to superclass, button activated.

        GM_HANDLEINPUT -- Overrides supperclass, all input processed.

        GM_GOINACTIVE -- Passed to superclass, button deactivated.

        GM_DOMAIN -- Returns GDOMAIN_MINIMUM and GDOMAIN_MAXIMUM dimensions.

        GM_KEYACTIVE -- Private method for keyboard control.

        GM_KEYINACTIVE -- Private method for keyboard control.

@{b}    ATTRIBUTES@{ub}

        GA_ID (WORD)
            Unique ID number for the gadget.

            Defaults to 0.

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

        GA_Selected (BOOL)
            Determines whether the button is selected or not.
            Changing selection state will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}.

            Defaults to FALSE.

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

        GA_Disabled (BOOL)
            Determines whether the button is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}.  A disabled
            button's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern.

            Defaults to FALSE.

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

        GA_Text (STRPTR)
            Used to specify the @{"NULL" Link "rexxsupport/NULL"} terminated string to use as the text
            for the gadget.  The @{"Text()" Link "graphics/Text()"} function is used to draw the text.
            @{"NULL" Link "rexxsupport/NULL"} is valid input. Changing the label will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}.
            @{"Text" Link "graphics/Text()"} string is clipped to fit inside the button via the
            @{"TextLength()" Link "graphics/TextLength()"} function. The text string may contain varargs
            format specifiers compatible to @{"RawDoFmt()" Link "exec/RawDoFmt()"} if the varargs data
            is supplied via BUTTON_VarArgs.

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

        GA_Image (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)
            Used to specify the image to use for the label of the gadget.
            The @{"DrawImageState()" Link "intuition/DrawImageState()"} function is used to draw the image.
            Changing the label will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}.

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

            Applicability is (OM_NEW, OM_SET)

        GA_SelectImage (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)
            Used to specify the image to use for the label of the gadget
            in the selected state. The @{"DrawImageState()" Link "intuition/DrawImageState()"} function is used
            to draw the image. Changing the label will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}
            if the gadget is currently selected.

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

            Applicability is (OM_NEW, OM_SET)

        GA_TextAttr (struct @{"TextAttr" Link "INCLUDE:graphics/text.h/Main" 63} *)
            @{"Text" Link "graphics/Text()"} attribute for the font to use for the text labels.

            Defaults to RPort->Font, which is often the screen or
            window preferences font.

            Applicability is (OM_NEW, OM_SET)

        GA_ReadOnly (BOOL)
            Read-only gadgets ignore activation attempts.

            Defaults to FALSE.

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

        BUTTON_AutoButton (UWORD)
            Used to create automatic button with one of the selected
            scaled image glyphs. Accepted settings are:

                BAG_POPFILE     - popup file selection glyph
                BAG_POPDRAWER   - popup drawer selection glyph
                BAG_POPFONT     - popup font selection glyph
                BAG_CHECKBOX    - checkmark glyph (same as checkbox.gadget)
                BAG_CANCELBOX   - NOT IMPLEMENETED!
                BAG_UPARROW     - up arrow
                BAG_DNARROW     - down arrow
                BAG_RTARROW     - right arrow
                BAG_LFARROW     - left arrow
                BAG_POPTIME     - popup time glyph
                BAG_POPSCREEN   - popup screen mode glyph
                BAG_POPUP       - generic popup glyph
                BAG_POPDATE     - popup date glyph (V47)
                BAG_POPCOLOR    - popup colour glyph (V47)

            Defaults to 0.

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

        BUTTON_PushButton (BOOL)
            Used to indicate that the button stays pressed in when the
            user selects it with the mouse.  The button may
            programmatically be deselected using {GA_Selected, FALSE}.

            Defaults to FALSE.

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

        BUTTON_TextPen (LONG)
            Indicate the pen number used to render the IDS_NORMAL text.
            If ~0 is specified, then TEXTPEN is used.

            Defaults to ~0.

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

        BUTTON_BackgroundPen (LONG)
            Indicate the pen number used to render the IDS_NORMAL
            background.  If ~0 is specified, then BACKGROUNDPEN
            is used.

            Defaults to ~0.

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

        BUTTON_FillTextPen (LONG)
            Indicate the pen number used to render the IDS_SELECTED text.
            If ~0 is specified, then FILLTEXTPEN is used.

            Defaults to ~0.

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

        BUTTON_FillPen (LONG)
            Indicate the pen number used to render the IDS_SELECTED
            background.  If ~0 is specified, then FILLPEN is used.

            Defaults to ~0.

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

        BUTTON_BevelStyle (WORD)
            Button bevel box rendering style, passed to bevel.image.
            Supports:

                BVS_NONE
                BVS_THIN
                BVS_BUTTON
                BVS_GROUP

            Defaults to BVS_BUTTON.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_Transparent (BOOL)
            Make button background rendering transparent.
            @{"EraseRect()" Link "graphics/EraseRect()"} is used rather than @{"RectFill()" Link "graphics/RectFill()"} so that
            custom backfill rendering hooks may be utilized.

            Defaults to FALSE.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_Justification    (WORD)
            Justification mode of button text label.
            Supports:

                BCJ_LEFT
                BCJ_CENTER
                BCJ_RIGHT

            Defaults to BCJ_CENTER.

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

        BUTTON_SoftStyle (WORD)
            Set the GA_TextAttr font's soft style, ie. BOLD, ITALIC, etc.
            See @{"<graphics/text.h>" Link "INCLUDE:graphics/text.h/Main" 0} soft style definitions.

            Defaults to 0.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_VarArgs (APTR)
            Varargs data array to supply data for @{"RawDoFmt()" Link "exec/RawDoFmt()"} when
            format specifiers are to be used in GA_Text text strings.
            The internal VarArgs result buffer is presently fixed at
            a maximum of 128 bytes, take care not to exceed this buffer.

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

            Applicability is (OM_NEW, OM_SET)

        BUTTON_DomainString (STRPTR)
            Used to specify the @{"NULL" Link "rexxsupport/NULL"} terminated string to use as the text
            to domain the gadget's minimum size. This string is NEVER
            rendered on screen. This is useful when you need to create
            a button with an empty ("") or @{"NULL" Link "rexxsupport/NULL"} string, but want to enforce
            minimum size in a layout group based on some initializing
            string and the current preferences font, rather than some fixed
            pixel or weighted minimum.  Added by request.

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

            Applicability is (OM_NEW, OM_SET)

        BUTTON_TextPadding (BOOL)  (V47)
            If TRUE, add some horizontal padding around the button's text
            label for aesthetic reasons. The extra space is (currently)
            twice the nominal width of the button's text font.

            Defaults to FALSE.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_Integer (int)  (V42)
            Set an integer value to display a numeric string. Highly useful
            for interconnect notifications from sliders, scrollers, etc.
            Added by request.

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

        BUTTON_BitMap (struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} *)  (V42)
            Specify a @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} to render in button, rather than image or
            text. Added by request, but use of bitmap.image is highly
            recommended for AmigaOS V39 and later.

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

            Applicability is (OM_NEW, OM_SET)

        BUTTON_AnimButton (BOOL)  (V42)
            Is button animatable?  Use to turn animating on or off.

            Defaults to FALSE.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_AnimImages (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)  (V42)
            Sets an array of struct Images for animation

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

            Applicability is (OM_NEW, OM_SET)

        BUTTON_SelAnimImages (struct @{"Image" Link "INCLUDE:intuition/intuition.h/Main" 710} *)  (V42)
            Sets an array of alternate images for a selected state;
            if used, must contain an equal number of images as the
            array used for BUTTON_AnimImages.  It's wise to use the
            same size for the images, too.

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

            Applicability is (OM_NEW, OM_SET)

        BUTTON_MaxAnimImages (LONG)  (V42)
            Number of images available in the arrays.

            Defaults to 0.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_AnimImageNumber (LONG)  (V42)
            Current image number in the array(s) to use the range of
            available frames is 0 .. MaxAnimImages-1

            Defaults to 0.

            Applicability is (OM_NEW, OM_SET)

        BUTTON_AddAnimImageNumber (ULONG)  (V42)
            Value to be added to the current image number counter.
            The counter will wrap around at MaxAnimImages.

            Applicability is (OM_SET, OM_UPDATE)

        BUTTON_SubAnimImageNumber (ULONG)  (V42)
            Value to be subtracted from the current image number counter.
            the counter will wrap around when less than 0.

            Applicability is (OM_SET, OM_UPDATE)

@{b}    BUGS@{ub}
        Unfortunately, this class shares the same filename and tag range
        as the button gadget released by David Junod of C=, released in
        the GI1.lha V42 beta archive on BIX, and later the AT DevCD.
        We admit it, we screwed up... but it's not a majorly serious issue
        as this class is atleast 90% compatible.

        A few rarely, possibly never, used tags of the original are NOT
        currently supported. The usage of BUTTON_PushButton in ReAction is
        not totally compatible to Junod's. Ours acts like GA_ToggleSelect
        of Junod's.

        Please report any incompatibilities immediately.

@EndNode

@Node "BUTTON_GetClass()" "button_gc/BUTTON_GetClass"

@{b}    NAME@{ub}
        BUTTON_GetClass -- Gets the pointer to the button class.

@{b}    SYNOPSIS@{ub}
        button_class = BUTTON_GetClass();
        D0

        Class * BUTTON_GetClass(VOID);

@{b}    FUNCTION@{ub}
        This function is only available in runtime linked version of the
        class, and is not in the compiler linker library button_gc.lib.

        Obtains the pointer to the Button 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}
        button_class - Pointer to the Button gadget class.

@{b}    SEE ALSO@{ub}

@EndNode