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

@Node Main "bevel_ic.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" --datasheet--() " Link "--datasheet--()"}
    @{" --styleguide--() " Link "--styleguide--()"}
    @{" BEVEL_GetClass() " Link "BEVEL_GetClass()"}
@EndNode

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

@{b}    NAME@{ub}
        bevel_ic -- create bevel BOOPSI objects

@{b}    SUPERCLASS@{ub}
        imageclass

@{b}    REQUIRES@{ub}
        None.

@{b}    DESCRIPTION@{ub}
        This image class can create a variety of bevel boxes styles
        including those appropriate as gadget borders, titled or
        non-titled grouping boxes and more. This class is very similar
        in function to the frameiclass in OS 3.x ROM, except this class
        supports the newer style bevels under OS 2.04 as well.

@{b}    METHODS@{ub}
        @{"OM_NEW" Link "tabs_gc/OM_NEW"} -- Create the bevel image.  Passed to superclass, then @{"OM_SET" Link "tabs_gc/OM_SET"}.

        @{"OM_GET" Link "tabs_gc/OM_GET"} -- Get object attributes.  Passed to superclass first.

        @{"OM_SET" Link "tabs_gc/OM_SET"} -- Set object attributes.  Passed to superclass first.

        IM_FRAMEBOX -- Get recommended frame position/size around some box.

        IM_DRAW -- Renders the images.  Overrides the superclass.

        IM_DRAWFRAME -- Renders the images at the frame size.
            Any following IM_DRAW will be at this frame size w/o a
            overriding @{"OM_SET" Link "tabs_gc/OM_SET"}. Overrides the superclass.

        IM_ERASE -- Erase the images.  Overrides the superclass.

        IM_ERASEFRAME -- Erase the images at the frame size.
            Overrides the superclass.

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

@{b}    ATTRIBUTES@{ub}
        IA_Top (WORD)
        IA_Left (WORD)
        IA_Width (WORD)
        IA_Height (WORD)
            Set bevel image size and position.

            Applicability is (OM_NEW, OM_SET)

        IA_SupportsDisable (BOOL)
            Reports TRUE if the image class can render its own
            disable pattern.

            Applicability is (OM_GET)

        IA_APattern (UWORD *)
            Optional inner fill pattern for SetAfPt() when used in
            conjunction with BEVEL_FillPen. See also BEVEL_FillPattern.
            I missed the OS support of this tag, thus, it is duplicated
            in BEVEL_FillPattern which will remain for backwards
            compatibility.

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

            Applicability is (OM_NEW, OM_SET)

        IA_APatSize (UWORD)
            Set pattern size for the pattern passed via IA_APattern.
            Defaults to 1. With BEVEL_FillPattern, the size was fixed.

            Applicability is (OM_NEW, OM_SET)

        IA_Recessed
            Inverts SHADOW/SHINEPEN and shading rendering pens.

            Applicability is (OM_NEW, OM_SET)

        IA_EdgesOnly
            See BEVEL_Transparent.

            Applicability is (OM_NEW, OM_SET)

        IA_FrameType
            Accepts all frameiclass frame types, and converts them
            the closest matching BEVEL_Style type honoring the
            current user preference settings.

            Applicability is (OM_SET)

        IA_Font (struct @{"TextAttr" Link "INCLUDE:graphics/text.h/Main" 63} *)
            @{"Text" Link "graphics/Text()"} Attribute to use for any label text.

            Applicability is (OM_NEW, OM_SET)

        IA_HighlightPen (UWORD)
        IA_FGPen (UWORD)
            Foreground pen.

            Defaults to SHINEPEN.

            Applicability is (OM_NEW, OM_SET)

        IA_ShadowPen (UWORD)
        IA_BGPen (UWORD)
            Background pen.

            Defaults to SHADOWPEN.

            Applicability is (OM_NEW, OM_SET)

        BEVEL_FillPen (WORD)
            Inner bevel area @{"RectFill()" Link "graphics/RectFill()"} pen number, ~0 means to
            ignore, and not to @{"RectFill()" Link "graphics/RectFill()"}.

            Defaults to ~0.

            Applicability is (OM_NEW, OM_SET)

        BEVEL_FillPattern (UWORD *)
            Optional inner fill pattern for SetAfPt() when used in
            conjunction with BEVEL_FillPen.  See also: IA_APattern

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

            Applicability is (OM_NEW, OM_SET)

        BEVEL_TextPen (WORD)
            Bevel text rendering pen number, ~0 will render
            in TEXTPEN.

            Defaults to ~0.

            Applicability is (OM_NEW, OM_SET)

        BEVEL_Style (BOOL)
            Specifies the bevel box style, may be one of the following;

                BVS_THIN       - thin/small bevel
                BVS_BUTTON     - standard button bevel (thin/thick pref)
                BVS_GROUP      - layout/grouping bevel (thin/thick pref)
                BVS_FIELD      - string/inputfield bevel (thin/thick pref)
                BVS_NONE       - no bevel
                BVS_DROPBOX    - standard dropbox
                BVS_SBAR_HORIZ - horizontal separator bar
                BVS_SBAR_VERT  - vertical separator bar
                BVS_BOX        - plain "black" box bevel
                BVS_STANDARD   - Simular to BVS_BUTTON, but no XEN!

            Defaults to BVS_BUTTON on V47 and later, but earlier versions
            actually defaulted to BVS_GROUP (contrary to autodocs).

            Applicability is (OM_NEW, OM_SET)

        BEVEL_Label (STRPTR)
            Specifies the text label for the bevel box.

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

            Applicability is (OM_NEW, OM_SET)

        BEVEL_LabelPlace (WORD)
            Specifies label location, may be one of the following;

                BVJ_TOP_CENTER
                BVJ_TOP_LEFT
                BVJ_TOP_RIGHT
                BVJ_IN_CENTER
                BVJ_IN_LEFT
                BVJ_IN_RIGHT

            Defaults to BVJ_TOP_CENTER.

            NOTE: BVS_BOTTOM_* settings not yet implemented

            Applicability is (OM_NEW, OM_SET)

        BEVEL_InnerTop (WORD)
            Get only attribute, returns the inside-top offset of the
            bevel box accounting for any BVJ_TOP text label placements.

            Applicability is (OM_GET)

        BEVEL_InnerLeft (WORD)
            Get only attribute, returns the inside-left offset of the
            bevel box.

            Applicability is (OM_GET)

        BEVEL_InnerWidth (WORD)
            Get only attribute, returns the inside-width of the
            bevel box, basically the same as;

                IA_Width - (BEVEL_VertSize * 2) - 1

            Except this also accounts for the BVS_TOP label placements.

            Applicability is (OM_GET)

        BEVEL_InnerHeight (WORD)
            Get only attribute, returns the inside - height of the
            bevel box, basically the same as;

                IA_Height - (BEVEL_InnerTop + BEVEL_HorzSize) - 1

            with the exception that BEVEL_InnerHeight will account for
            any text label for a BVS_GROUP style bevel.

            Applicability is (OM_GET)

        BEVEL_HorizSize (WORD)
            Get only attribute, returns the nominal height (in pixels) of
            the horizontal lines the bevel will draw for the givel style.

            Applicability is (OM_GET)

        BEVEL_VertSize (WORD)
            Get only attribute, returns the nominal width (in pixels) of
            the vertical lines the bevel will draw for the given style.

            Applicability is (OM_GET)

        BEVEL_SoftStyle (WORD)
            Font softstyles to apply.
            See @{"<graphics/text.h>" Link "INCLUDE:graphics/text.h/Main" 0} SoftStyle definitions.

            Defaults to 0.

            Applicability is (OM_NEW, OM_SET)

        BEVEL_Transparent (BOOL)
            If set TRUE, bevel will not attempt to render or erase any
            part of the inner area of the bevel.

            Defaults to FALSE.

            Applicability is (OM_NEW, OM_SET)

        BEVEL_ColorMap (struct @{"ColorMap" Link "INCLUDE:graphics/view.h/Main" 144} *)
            @{"Screen" Link "INCLUDE:intuition/screens.h/Main" 139} viewport colormap pointer, use to obtain additional
            best-match pens for XEN and possibly other future multi-pen
            beveling options. MWB or NI3 palette recommended for best
            results.

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

            Applicability is (OM_NEW, OM_SET)

        BEVEL_Flags (UWORD)
            Intentionally left undocumented! It is used for some hidden
            BVS_BUTTON xen style magic. Class authors inquire as needed.

            Defaults to 0.

            Applicability is (OM_NEW, OM_SET)

@EndNode

@Node "--styleguide--()" "bevel_ic/--styleguide--"

@{b}    BEVEL STYLE@{ub}

        Several ReAction objects allow overriding the default bevel
        style. This is NOT recommended practice for application authors.
        But instead, its provided to add some extra flexability to BOOPSI
        class authors who may wish to sub-class a ReAction gadget or
        utilize it within a larger composite (model class) object.

        When using bevel.image directly be sure to select the appropriate
        bevel for your usage. Do not provide a bevel style override tag
        unless it makes sence to do so. The idea being that all applications
        and BOOPSI objects should be presented using a standard beveling
        style. For example, a button gadget using a BVS_FIELD string bevel
        would be an illogical choice.  Any button should use BVS_BUTTON, a
        text entry field should use BVS_FIELD, and of course a layout group,
        if using a bevel, should use BVS_GROUP, BVS_SBAR_VERT or
        BVS_SBAR_HORIZ.

@EndNode

@Node "BEVEL_GetClass()" "bevel_ic/BEVEL_GetClass"

@{b}    NAME@{ub}
        BEVEL_GetClass -- Gets the pointer to the bevel class.

@{b}    SYNOPSIS@{ub}
        bevel_class = BEVEL_GetClass();
        D0

        Class * BEVEL_GetClass(VOID);

@{b}    FUNCTION@{ub}
        Obtains the pointer to the bevel image 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}
        bevel_class - Pointer to the bevel image class.

@{b}    SEE ALSO@{ub}

@EndNode