MUI Autodocs: String.mui

Copyright © 1997, Stefan Stuntz




String.mui Background

        String class generates standard string gadgets with
        all editing facilities (clear, undo, etc.) enabled.



String.mui Attributes

    Attribute                           Ver ISG Type
    ----------------------------------- --- --- --------------------
    MUIA_String_Accept                  V4  ISG STRPTR
    MUIA_String_Acknowledge             V4  ..G STRPTR
    MUIA_String_AdvanceOnCR             V11 ISG BOOL
    MUIA_String_AttachedList            V4  ISG Object *
    MUIA_String_BufferPos               V4  .SG LONG
    MUIA_String_Contents                V4  ISG STRPTR
    MUIA_String_DisplayPos              V4  .SG LONG
    MUIA_String_EditHook                V7  ISG struct Hook *
    MUIA_String_Format                  V4  I.G LONG
    MUIA_String_Integer                 V4  ISG ULONG
    MUIA_String_LonelyEditHook          V11 ISG BOOL
    MUIA_String_MaxLen                  V4  I.G LONG
    MUIA_String_Reject                  V4  ISG STRPTR
    MUIA_String_Secret                  V4  I.G BOOL


MUIA_String_Accept


    NAME
        MUIA_String_Accept -- (V4 ) [ISG], STRPTR

    FUNCTION
        A string containing characters allowed as input
        for the string gadget. Whenever the user hits a
        character not found in MUIA_String_Accept, he
        will hear a beep and gadgets contents won't have 
        changed.

    EXAMPLE
        StringObject,
           MUIA_String_Accept, "0123456789-",
           End,

    SEE ALSO
        MUIA_String_Reject


MUIA_String_Acknowledge


    NAME
        MUIA_String_Acknowledge -- (V4 ) [..G], STRPTR

    FUNCTION
        This attribute will be set to the contents of the
        string whenever the user hits return in the gadget. 
        An application can listen with notification and take
        the appropriate action.

        Using the TAB key or a mouse click to deactivate the
        gadget will not trigger MUIA_String_Acknowledge.

    EXAMPLE
        /* two string gadgets str1 and str2, the second should
        /* become active after a return in the first: */

        DoMethod(str1,MUIM_Notify,
           MUIA_String_Acknowledge, MUIV_EveryTime,
           windowobj, 3, MUIM_Set, MUIA_Window_ActiveObject, str2);

    SEE ALSO
        MUIA_String_Contents


MUIA_String_AdvanceOnCR


    NAME
        MUIA_String_AdvanceOnCR -- (V11) [ISG], BOOL

    FUNCTION
        Set this if you want carriages returns in string gadgets
        behave like the TAB key, i.e. pressing CR will activate
        the next/previous gadget in the cycle chain.

    SEE ALSO
        Notify.mui/MUIA_CycleChain


MUIA_String_AttachedList


    NAME
        MUIA_String_AttachedList -- (V4 ) [ISG], Object *

    FUNCTION
        This special attribute can be set to point to
        a valid MUI object of Listview class.
        This enables controlling the lists cursor
        from within the string gadget, all cursor key
        events will be forwarded.

    SEE ALSO
        MUIA_String_Contents, list.mui/MUIA_List_Active


MUIA_String_BufferPos


    NAME
        MUIA_String_BufferPos -- (V4 ) [.SG], LONG

    FUNCTION
        MUIA_String_BufferPos can be used to get and set the
        position of the cursor in the string gadget.
        This attribute is probably not very interesting.

    SEE ALSO
        MUIA_String_Contents, MUIA_String_DisplayPos


MUIA_String_Contents


    NAME
        MUIA_String_Contents -- (V4 ) [ISG], STRPTR

    FUNCTION
        Get and set a string gadgets contents. You may not
        modify the returned string.

        MUIA_String_Contents gets updated every time when
        the contents of the string gadget change. When you
        set up a notification on this attribute, you will
        hear about every keystroke.

    NOTE
        If you try to set contents to something larger
        than MUIA_String_MaxLen (including the 0-byte!),
        MUI will silently strip the additional characters.

    EXAMPLE

        /* The given hook will be called after every change */
        /* in the string gadget. It receives a pointer to   */
        /* a pointer to the current contents in register a1 */
        /* (see MUIM_CallHook for details)                  */

        DoMethod(str,MUIM_Notify,
           MUIA_String_Contents, MUIV_EveryTime,
           str, 3, MUIM_CallHook, &hook, MUIV_TriggerValue);

    SEE ALSO
        MUIA_String_Accept, MUIA_String_Reject, MUIA_String_MaxLen


MUIA_String_DisplayPos


    NAME
        MUIA_String_DisplayPos -- (V4 ) [.SG], LONG

    FUNCTION
        MUIA_String_DisplayPos can be used to get and set the
        number of the first character of the string to be
        displayed. This attribute is probably not very
        interesting.

    SEE ALSO
        MUIA_String_Contents, MUIA_String_BufferPos


MUIA_String_EditHook


    NAME
        MUIA_String_EditHook -- (V7 ) [ISG], struct Hook *

    FUNCTION
        When specified, MUI calls this hook as if it was a real
        string edit hook in a real string gadget. It receives
        a pointer to itself in A0, a pointer to a SGWork structure
        in A2 and a pointer to the message in A1.

        The hook will be called before MUI's private edit hook,
        the result is unused.


MUIA_String_Format


    NAME
        MUIA_String_Format -- (V4 ) [I.G], LONG

    SPECIAL INPUTS
        MUIV_String_Format_Left
        MUIV_String_Format_Center
        MUIV_String_Format_Right

    FUNCTION
        Used to adjust the alignment of the input string.

    SEE ALSO
        MUIA_String_BufferPos, MUIA_String_DisplayPos, MUIA_String_Contents


MUIA_String_Integer


    NAME
        MUIA_String_Integer -- (V4 ) [ISG], ULONG

    FUNCTION
        Useful for turning a string gadget into an integer
        gadget. Setting this attribute puts the value
        with "%ld" into the gadget, getting it returns
        a longword containing the string gadgets contents
        as number.

        You should set MUIA_String_Accept to "0123456789"
        or something like that to avoid wrong characters.

    EXAMPLE
        StringObject,
           MUIA_String_Accept , "0123456879",
           MUIA_String_Integer, 42,
           End;


MUIA_String_LonelyEditHook


    NAME
        MUIA_String_LonelyEditHook -- (V11) [ISG], BOOL

    FUNCTION
        If your string object has an edit hook, you can set
        this to TRUE to skip MUI's private edit hook completely.
        Otherwise, your hook will be executed and the MUIs.


MUIA_String_MaxLen


    NAME
        MUIA_String_MaxLen -- (V4 ) [I.G], LONG

    FUNCTION
        Setup the maximum length for the string gadget.
        This attribute is only valid at object creation time.

        Default maximum length is 80.

        NOTE: The maximum length includes the 0-byte at the end
              of the string. To let the user enter e.g. 10 characters,
              you would have to specify a maxlen of 11.

    SEE ALSO
        MUIA_String_Contents


MUIA_String_Reject


    NAME
        MUIA_String_Reject -- (V4 ) [ISG], STRPTR

    FUNCTION
        A string containing characters that should not be
        accepted as input for the string gadget. Whenever
        the user hits such a char, he will hear a beep
        and gadgets contents won't have changed.

    SEE ALSO
        MUIA_String_Accept


MUIA_String_Secret


    NAME
        MUIA_String_Secret -- (V4 ) [I.G], BOOL

    FUNCTION
        This attribute causes the string gadget to display only
        dots instead of the real contents. Useful for password
        requesters.

    SEE ALSO
        MUIA_String_Contents





© 1997, Stefan Stuntz [MUI Homepage] [Autodoc Index] [Feedback] Updated: 29-Mar-97