@database "button_gc"
@master "Work:V42/src/workbench/classes/gadgets/button/button_gc.doc"

@Node Main "button_gc.doc"
    @{" --datasheet-- " Link "--datasheet--"}
    @{" GM_GOACTIVE " Link "GM_GOACTIVE"}
    @{" GM_GOINACTIVE " Link "GM_GOINACTIVE"}
    @{" GM_HANDLEINPUT " Link "GM_HANDLEINPUT"}
    @{" GM_HITTEST " Link "GM_HITTEST"}
    @{" GM_LAYOUT " Link "GM_LAYOUT"}
    @{" GM_RENDER " Link "GM_RENDER"}
    @{" OM_NEW " Link "OM_NEW"}
    @{" OM_SET " Link "OM_SET"}
@EndNode

@Node "--datasheet--" "button.gadget/--datasheet--"
 
@{b}     NAME@{ub}
        button.gadget--Action button                            (V42)
 
@{b}     SUPERCLASS@{ub}
        gadgetclass
 
@{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.
 
        An advantage that this class provides that the system buttongclass
        doesn't support fully is:
 
         o Centered images.
 
         o Centered pen-sensitive glyphs.
 
         o Ability to change the text and background colors for normal
           and selected buttons.
 
@{b}     METHODS@{ub}
        OM_NEW--Create the button gadget.  Passed to superclass, then @{"OM_SET" Link "OM_SET"}.
 
        OM_SET--Set object attributes.  Passed to superclass first.
 
        OM_UPDATE--Set object notification attributes.  Passed to superclass
            first.
 
        GM_LAYOUT--Calculate gadget imagry positioning.  Passed to superclass
            first.
 
        GM_RENDER--Renders the gadget imagry.  Overrides the superclass.
 
        GM_HITTEST--Determines if mouse is within the gadget rectangle.  Over-
            rides the superclass.
 
        GM_GOACTIVE--Handles activation, toggle-select and button-select.
            Overrides the superclass.
 
        GM_HANDLEINPUT--Handles input events once active.  Handles cycle
            buttons, repeat and RMB abort.  Overrides the superclass.
 
        GM_GOINACTIVE--Deselects the button.  Overrides the superclass.
 
        All other methods are passed to the superclass, including OM_DISPOSE.
 
@{b}     ATTRIBUTES@{ub}
        GA_ToggleSelect (BOOL) -- Indicate that the gadget is a toggle button.
            Defaults to FALSE.
 
        GA_Selected (BOOL) -- Determines whether the button is selected or
            not.  Changing selection state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  Setting
            selected causes BUTTON_Current to go to 1.  Clearing selected
            causes BUTTON_Current to go to 0.  Defaults to FALSE.
 
        GA_Disabled (BOOL) -- Determines whether the button is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  A disabled
            button's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern that is rendered in SHADOWPEN.
            Defaults to FALSE.
 
        GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
            as the text for the gadget.  The @{"Text()" Link "graphics/Text()"} function is used to draw
            the text.  The class does not currently support underlining of
            the keyboard shortcut character.  NULL is valid input.  Changing
            the label will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        GA_Image (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for the
            label of the gadget.  The @{"DrawImage()" Link "intuition/DrawImage()"} function is used to draw
            the image.  NULL is valid input.  Changing the label will invoke
            @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        GA_TextAttr (struct @{"TextAttr" Link "TEXT_INCLUDE:graphics/text.h/Main" 63} *) -- Text attribute for the font to
            use for the labels.
 
        GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
            Defaults to FALSE.
 
        BUTTON_Glyph (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for
            the label of the gadget.  The @{"BltTemplate()" Link "graphics/BltTemplate()"} function is used to
            draw each plane of the image.  NULL is valid input.  Changing the
            label will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        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.
 
        BUTTON_Array (LONG) -- Indicates that the label is an array, and
            indicates the number of elements in the array.  This allows the
            gadget to be used as a checkbox or a cycle gadget without the
            cycle glyph.  Defaults to 1.
 
        BUTTON_Current (LONG) -- Used to select the current image from the
            BUTTON_Array.  Changing the current image will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"}
            and then @{"GM_RENDER" Link "GM_RENDER"}.  Defaults to zero.
 
        BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
            IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
            Defaults to -1.
 
        BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
            the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
            is used.  Defaults to -1.
 
        BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
            the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
            used.  Defaults to -1.
 
        BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
            IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
        .
            Defaults to -1.
 
@EndNode

@Node "GM_GOACTIVE" "button.gadget/GM_GOACTIVE"
 
@{b}     NAME@{ub}
        GM_GOACTIVE--Activate a gadget.                         (V42)
 
@{b}     FUNCTION@{ub}
        The GM_GOACTIVE method is used to indicate to a gadget that it has
        become active.  This method overrides the superclass.
 
        GA_ToggleSelect:  Toggles selection state.
 
        BUTTON_PushButton:  If not selected, then becomes selected and sets
            BUTTON_Current to 1.  If selected and BUTTON_Array is greater than
            one, then will cycle through the array, while staying selected,
            with 1 being the lower bounds.
 
        BUTTON_Array: Sets selection state and cycle through the array with 0
            being the lower bounds.
 
        Otherwise: Sets selection state.
 
        Invokes @{"GM_RENDER" Link "GM_RENDER"} with GREDRAW_REDRAW set.
 
@{b}     RESULT@{ub}
        For GA_ToggleSelect returns GMR_VERIFY | GMR_NOREUSE.
 
        For BUTTON_PushButton returns GMR_VERIFY | GMR_NOREUSE when the
        state changes, otherwise returns GMR_NOREUSE.
 
        All other cases returns GMR_MEACTIVE.
 
        Sets the *msg->gpi_Termination field to BUTTON_Current, which in turn
        fills in the IntuiMessage->Code field.
 
@EndNode

@Node "GM_GOINACTIVE" "button.gadget/GM_GOINACTIVE"
 
@{b}     NAME@{ub}
        GM_GOINACTIVE--Button has lost activation.              (V42)
 
@{b}     FUNCTION@{ub}
        The GM_GOINACTIVE method is used to indicate that the button has
        become inactive.  This method overrides the superclass.
 
        For momentary buttons, this will cause the GFLG_SELECTED flag to be
        cleared and the @{"GM_RENDER" Link "GM_RENDER"} method to be called with GREDRAW_REDRAW.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "GM_HANDLEINPUT" "button.gadget/GM_HANDLEINPUT"
 
@{b}     NAME@{ub}
        GM_HANDLEINPUT--Handle input events.                    (V42)
 
@{b}     FUNCTION@{ub}
        The GM_HANDLEINPUT method is used to handle the input events of an
        active button gadget.  This method overrides the superclass.
 
        This method correctly handles RMB abort.
 
@{b}     RESULT@{ub}
        This method returns GMR_MEACTIVE as long as the gadget is active.
 
@EndNode

@Node "GM_HITTEST" "button.gadget/GM_HITTEST"
 
@{b}     NAME@{ub}
        GM_HITTEST--Is gadget hit.                              (V42)
 
@{b}     FUNCTION@{ub}
        The GM_HITTEST method is used to determine if the given mouse
        coordinates are within the domain of the button.  This method
        overrides the superclass.
 
@{b}     RESULT@{ub}
        This method returns GMR_GADGETHIT if within the domain, otherwise
        zero is returned.
 
        If the gadget is GA_ReadOnly, then zero is always returned.
 
@EndNode

@Node "GM_LAYOUT" "button.gadget/GM_LAYOUT"
 
@{b}     NAME@{ub}
        GM_LAYOUT--Calculate the positioning of the imagry.     (V42)
 
@{b}     FUNCTION@{ub}
        The GM_LAYOUT method is used to calculate the domain of the button
        and to center the label within the domain.  This method is passed to
        the superclass first.
 
        @{"Gadget" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 213} relativity is fully supported.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "GM_RENDER" "button.gadget/GM_RENDER"
 
@{b}     NAME@{ub}
        GM_RENDER--Render the visuals of the button.            (V42)
 
@{b}     FUNCTION@{ub}
        The GM_RENDER method is used to render the visuals of the button.
        This method overrides the superclass.
 
        The border of the gadget is drawn first.  Disabled gadgets get a
        border that is drawn completely in SHADOWPEN.  A selected or
        read-only button gets SHADOWPEN for the left and top sides, and
        SHINEPEN for the right and bottom sides.  A normal button gets
        SHINEPEN for the left and top sides, and SHADOWPEN for the
        right and bottom sides.
 
        The inside of the button is then drawn.  A normal button gets
        filled with BUTTON_BackgroundPen.  A selected button gets filled
        with BUTTON_FillPen.
 
        Then the label is drawn.
 
            GA_Text:  @{"Text()" Link "graphics/Text()"} is used to render the text.  BUTTON_TextPen
            is used for a normal button and BUTTON_FillTextPen is used for a
            selected button.
 
            GA_Image:  @{"DrawImageState()" Link "intuition/DrawImageState()"} is used to render the image.  Note
            that the background pen color is already set appropriately for
            the image state.
 
            BUTTON_Glyph:  @{"BltTemplate()" Link "graphics/BltTemplate()"} is used to render each of the planes
            of the image.  BUTTON_TextPen is used for a normal button and
            BUTTON_FillTextPen is used for a selected button.  The second
            and higher planes are render using SHADOWPEN.
 
        If the button is disabled, then the ghosting pattern is applied.
 
@{b}     RESULT@{ub}
        This method returns 0.
 
@EndNode

@Node "OM_NEW" "button.gadget/OM_NEW"
 
@{b}     NAME@{ub}
        OM_NEW--Create a button.gadget object.                  (V42)
 
@{b}     FUNCTION@{ub}
        The OM_NEW method is used to create an instance of the button.gadget
        class.  This method is passed to the superclass first.
 
@{b}     ATTRIBUTES@{ub}
        The following attributes can be specified at creation time.
 
        GA_ToggleSelect (BOOL) -- Indicate that the gadget is a toggle button.
            Defaults to FALSE.
 
        GA_Selected (BOOL) -- Determines whether the button is selected or
            not.  Defaults to FALSE.
 
        GA_Disabled (BOOL) -- Determines whether the button is disabled or
            not.  Defaults to FALSE.
 
        GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
            as the text for the gadget.
 
        GA_Image (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for the
            label of the gadget.
 
        GA_TextAttr (struct @{"TextAttr" Link "TEXT_INCLUDE:graphics/text.h/Main" 63} *) -- Text attribute for the font to
            use for the labels.
 
        GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
            Defaults to FALSE.
 
        BUTTON_Glyph (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for
            the label of the gadget.
 
        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.
 
        BUTTON_Array (LONG) -- Indicates that the label is an array, and
            indicates the number of elements in the array.  This allows the
            gadget to be used as a checkbox or a cycle gadget without the
            cycle glyph.  Defaults to 1.
 
        BUTTON_Current (LONG) -- Used to select the current image from the
            BUTTON_Array.  Defaults to zero.
 
        BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
            IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
            Defaults to -1.
 
        BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
            the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
            is used.  Defaults to -1.
 
        BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
            the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
            used.  Defaults to -1.
 
        BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
            IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
        .
            Defaults to -1.
 
@{b}     RESULT@{ub}
        If the object was created then a pointer to the object is returned,
        otherwise NULL is returned.
 
@EndNode

@Node "OM_SET" "button.gadget/OM_SET"
 
@{b}     NAME@{ub}
        OM_SET--Set the attributes of a button.gadget object.   (V42)
 
@{b}     FUNCTION@{ub}
        The OM_SET method is used to set the attributes of a button.gadget.
        This method is passed to the superclass first.
 
@{b}     ATTRIBUTES@{ub}
        The following attributes can be changed at OM_SET or OM_UPDATE.
 
        GA_Selected (BOOL) -- Determines whether the button is selected or
            not.  Changing selection state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  Setting
            selected causes BUTTON_Current to go to 1.  Clearing selected
            causes BUTTON_Current to go to 0.  Defaults to FALSE.
 
        GA_Disabled (BOOL) -- Determines whether the button is disabled or
            not.  Changing disable state will invoke @{"GM_RENDER" Link "GM_RENDER"}.  A disabled
            button's border and label are all rendered in SHADOWPEN and then
            dusted in a ghosting pattern that is rendered in SHADOWPEN.
            Defaults to FALSE.
 
        GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
            as the text for the gadget.  The @{"Text()" Link "graphics/Text()"} function is used to draw
            the text.  The class does not currently support underlining of
            the keyboard shortcut character.  NULL is valid input.  Changing
            the label will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        GA_Image (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for the
            label of the gadget.  The @{"DrawImage()" Link "intuition/DrawImage()"} function is used to draw
            the image.  NULL is valid input.  Changing the label will invoke
            @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        GA_TextAttr (struct @{"TextAttr" Link "TEXT_INCLUDE:graphics/text.h/Main" 63} *) -- Text attribute for the font to
            use for the labels.
 
        GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
            Defaults to FALSE.
 
        BUTTON_Glyph (struct @{"Image" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 704} *) -- Used to specify the image to use for
            the label of the gadget.  The @{"BltTemplate()" Link "graphics/BltTemplate()"} function is used to
            draw each plane of the image.  NULL is valid input.  Changing the
            label will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"} and then @{"GM_RENDER" Link "GM_RENDER"}.
 
        BUTTON_Current (LONG) -- Used to select the current image from the
            BUTTON_Array.  Changing the current image will invoke @{"GM_LAYOUT" Link "GM_LAYOUT"}
            and then @{"GM_RENDER" Link "GM_RENDER"}.  Defaults to zero.
 
        BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
            IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
            Defaults to -1.  Changing the pen will invoke @{"GM_RENDER" Link "GM_RENDER"}.
 
        BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
            the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
            is used.  Defaults to -1.  Changing the pen will invoke @{"GM_RENDER" Link "GM_RENDER"}.
 
        BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
            the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
            used.  Defaults to -1.  Changing the pen will invoke @{"GM_RENDER" Link "GM_RENDER"}.
 
        BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
            IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
        .
            Defaults to -1.  Changing the pen will invoke @{"GM_RENDER" Link "GM_RENDER"}.
 
@{b}     RESULT@{ub}
        The class will update the attributes of object.  Changing some
        attributes will result in @{"GM_LAYOUT" Link "GM_LAYOUT"} and/or @{"GM_RENDER" Link "GM_RENDER"} being called.
 
        The return value will be non-zero if the gadget needs to be refreshed.
 
@EndNode

