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

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

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

@{b}    NAME@{ub}
        string_gc -- create string BOOPSI objects

@{b}    SUPERCLASS@{ub}
        gadgetclass

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

@{b}    DESCRIPTION@{ub}
        The string gadget class is used to create single line
        editable strings. This class also supports window relativity.
        This class is a subclass of rom strgclass which automatically
        creates a field bevel and supports GM_DOMAIN for layout groups.

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

        @{"OM_SET" Link "tabs_gc/OM_SET"} -- Passed to superclass, and strgclass is set.

        OM_UPDATE -- Passed to superclass, and strgclass is set then
            rendered.

        OM_DISPOSE -- Disposes strgclass object, then passed to superclass.

        @{"GM_RENDER" Link "tabs_gc/GM_RENDER"} -- Passed to superclass, then strgclass object

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

        @{"GM_GOACTIVE" Link "tabs_gc/GM_GOACTIVE"} -- Passed to superclass, strgclass, string activated

        GM_HANDLEINPUT -- Routes input to strgclass object.

        GM_GOINACTIVE -- Passed to superclass, strgclass, string deactivated.

        GM_DOMAIN -- Returns GDOMAIN_MINIMUM, GDOMAIN_NOMINAL and
            GDOMAIN_MAXIMUM dimensions.

@{b}    ATTRIBUTES@{ub}
        GA_Disabled (BOOL)
            Determines whether the string is disabled or not.
            Changing disable state will invoke @{"GM_RENDER" Link "tabs_gc/GM_RENDER"}.  A disabled
            string is dusted in a ghosting pattern that is rendered
            in SHADOWPEN.

            Defaults to FALSE.

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

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

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

            Applicability is (OM_NEW)

        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)

        GA_BackFill (struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *)
            A layer backfill hook to provide a more complex
            background pattern. See @{"InstallLayerHook()" Link "layers/InstallLayerHook()"} for
            more details about the backfill hook.

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

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

        STRINGA_LongVal (LONG)
            This attribute tells string.gadget that this
            gadget is an integer string gadget and the new value
            of the integer is this attribute's value.

            It is recommended to use the much more powerful
            integer.gadget instead.

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

        STRINGA_TextVal (STRPTR)
            This attribute tells the string.gadget that this
            gadget is a plain string gadget. The attribute
            points to a string which the object copies into the
            gadget's current string value buffer.

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

            When a string.gadget's value changes (usually because
            the user manipulated the gadget), an OM_NOTIFY
            message will be sent. The message will contain two
            attribute/value pairs, GA_ID and either STRINGA_LongVal
            or STRINGA_TextVal depending on what kind of gadget
            it is.

        STRINGA_Buffer (STRPTR)
            Specifies the buffer used for displaying the
            value to be edited.

            Defaults to an internal buffer of size
            SG_DEFAULTMAXCHARS (currently 128 bytes).

            Applicability is (OM_NEW)

        STRINGA_WorkBuffer (STRPTR)
            Specifies the buffer to be used while the user
            edits the text in the gadget.

            Defaults to an internal buffer of size
            SG_DEFAULTMAXCHARS (currently 128 bytes).

            Applicability is (OM_NEW)

        STRINGA_UndoBuffer (STRPTR)
            Specifies the buffer to be used for undo while
            the user edits the text in the gadget.

            Defaults to an internal buffer of size
            SG_DEFAULTMAXCHARS (currently 128 bytes).

            Applicability is (OM_NEW)

        STRINGA_MaxChars (WORD)
            The maximum number of characters the user can edit.
            This includes the NUL terminator. Eg. to allow 10
            characters, you should pass a STRINGA_MaxChars of 11.
            If you increase this beyond SG_DEFAULTMAXCHARS, you
            will also need to supply large enough display/work/undo
            buffers using the STRINGA_Buffer, STRINGA_WorkBuffer
            and STRINGA_UndoBuffer tags.

            Defaults to SG_DEFAULTMAXCHARS (currently 128 bytes).

            Applicability is (OM_NEW)

        STRINGA_BufferPos (WORD)
            The current position of the cursor within the buffer
            from zero to the current length of the buffer string.

            Defaults to the end of the buffer string.

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

        STRINGA_DispPos (WORD)
            The current position of the cursor within the
            displayed buffer area which can range from zero to
            the current length of the buffer string.

            Defaults to the end of the buffer string.

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

        STRINGA_AltKeyMap (struct @{"KeyMap" Link "INCLUDE:libraries/keymap.h/Main" 19} *)
            Alternative key map to use for this string gadget
            which will be passed to @{"MapRawKey()" Link "keymap/MapRawKey()"}.

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

            Applicability is (OM_NEW, OM_SET)

        STRINGA_Font (struct @{"TextFont" Link "INCLUDE:graphics/text.h/Main" 87} *)
            The font to use for rendering text.

            Defaults to the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} font of the parent @{"Window" Link "INCLUDE:intuition/intuition.h/Main" 942}.

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

        STRINGA_Pens (ULONG)
            Pen numbers packed as two @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} values into a
            single ULONG value for rendering inactive gadget
            text. The upper @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} is the background color and
            the lower @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} is the text color.

            Defaults to TEXTPEN (text) and FOREGROUNDPEN.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_ActivePens (ULONG)
            Pen numbers packed as two @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} values into a
            single ULONG value for rendering active gadget
            text. The upper @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} is the background color and
            the lower @{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} is the text color.

            Defaults to TEXTPEN (text) and BACKGROUNDPEN.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_HookType (UWORD) (V41)
            Use one of the build in string editing hooks:

            SHK_CUSTOM (default)
            SHK_PASSWORD
            SHK_IPADDRESS
            SHK_FLOAT
            SHK_HEXIDECIMAL
            SHK_TELEPHONE
            SHK_POSTALCODE (not implemented)
            SHK_AMOUNT (not implemented)
            SHK_UPPERCASE
            SHK_HOTKEY (V45)

            WARNING: Do NOT use STRINGA_HookType unless string.gadget
            V45 is installed. Some of the hooks were broken before!

            Applicability is (OM_NEW)

        STRINGA_EditHook (struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *)
            @{"Custom" Link "INCLUDE:hardware/custom.h/Main" 23} string gadget edit hook. The hook is called
            with the following paramters:

            result = Edit( hook, sgw, msg )

            @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} Edit(struct Hook* hook,
                      struct SGWork* sgw,
                      ULONG* msg);

            See @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0} for more details on how
            to implement string gadget edit hooks.

            Defaults to no edit hook.

            Applicability is (OM_NEW)

        STRINGA_EditModes (ULONG)
            Value taken from flags defined in
            @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0} for initial editing modes.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_ReplaceMode (BOOL)
            This flag corresponds to the SGM_REPLACE flag
            defined in @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0}.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_FixedFieldMode (BOOL)
            This flag corresponds to the SGM_FIXEDFIELD flag
            defined in @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0}.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_NoFilterMode (BOOL)
            This flag corresponds to the SGM_NOFILTER flag
            defined in @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0}.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_ExitHelp (BOOL)
            This flag corresponds to the SGM_EXITHELP flag
            defined in @{"<intuition/sghooks.h>" Link "INCLUDE:intuition/sghooks.h/Main" 0}.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_Justification (ULONG)
            Takes the values GACT_STRINGCENTER, GACT_STRINGRIGHT
            and GACT_STRINGLEFT.

            Defaults to GACT_STRINGLEFT.

            Applicability is (OM_NEW, OM_SET)

        STRINGA_AllowMarking (BOOL) (V45)
            @{"Enable" Link "exec/Enable()"} or disable marking.

            Defaults to TRUE.

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

        STRINGA_Mark (ULONG) (V45)
            Mark the given block. The upper 16 bits of the longword
            contain the start position and the lower 16 bits contain
            the end position. If one or both values are -1 ($FFFF),
            the current block will be unmarked.

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

        STRINGA_GetBlockPos (ULONG)
            Deprecated tag. Use STRINGA_Mark instead.

            Applicability is (OM_GET)

        STRINGA_MinVisible (WORD) (V41)
            Set the minimum number of characters that should be
            visible for a 'GDOMAIN_MIMIMUM' domain size. Nominal
            domain sizes to twice this minimum. This is a handy
            addition (also present in V40.35) to ensure a minimum
            number of characters will be visible in a string gadget.

            Defaults to 4.

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

@{b}    NOTES@{ub}
        The string class passes all tags to its strgclass child,
        please see strgclass tags & autodocs, and look in
        @{"<intuition/gadgetclass.h>" Link "INCLUDE:intuition/gadgetclass.h/Main" 0} for the STRINGA_ tags.

        WARNING: Upto v45 string.gadget is ROM strgclass wrapper.
        Depending on string.gadget version, passing GA_Text can crash
        strgclass; please use STRING_TextVal as it is intended. STRINGA_Font
        and STRINGA_LongVal are not directly supported; for numeric
        strings use our more powerful integer.gadget class. To specify
        the font for the gadget, use GA_TextAttr which is consistent
        with all other ReAction gadget attributes.

@EndNode

@Node "STRING_GetClass()" "string_gc/STRING_GetClass"

@{b}    NAME@{ub}
        STRING_GetClass -- Gets the pointer to the string class.

@{b}    SYNOPSIS@{ub}
        string_class = STRING_GetClass();
        D0

        Class * STRING_GetClass(VOID);

@{b}    FUNCTION@{ub}
        Obtains the pointer to the string 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}
        string_class - Pointer to the string gadget class.

@{b}    SEE ALSO@{ub}

@EndNode