MUI Autodocs: Area.mui

Copyright © 1997, Stefan Stuntz




Area.mui Background

        Area class is a super class for every other MUI class
        except windows and applications. It holds information
        about an objects current position, size and weight
        and manages frames, fonts and backgrounds.

        Additionally, area class handles the user input. By
        setting an objects MUIA_InputMode, you can make it
        behave like a button or like a toggle gadget. That's
        why MUI doesn't offer an extra button class. A button
        is simply a text object with a raised frame and a relverify
        input mode. Since especially group class is a subclass
        of area, you can create rather complex buttons consisting
        of many other display elements.



Area.mui Attributes

    Attribute                           Ver ISG Type
    ----------------------------------- --- --- --------------------
    MUIA_Background                     V4  IS. LONG
    MUIA_BottomEdge                     V4  ..G LONG
    MUIA_ContextMenu                    V11 ISG Object *
    MUIA_ContextMenuTrigger             V11 ..G Object *
    MUIA_ControlChar                    V4  ISG char
    MUIA_CycleChain                     V11 ISG LONG
    MUIA_Disabled                       V4  ISG BOOL
    MUIA_Draggable                      V11 ISG BOOL
    MUIA_Dropable                       V11 ISG BOOL
    MUIA_ExportID                       V4  ISG ULONG (OBSOLETE)
    MUIA_FillArea                       V4  IS. BOOL
    MUIA_FixHeight                      V4  I.. LONG
    MUIA_FixHeightTxt                   V4  I.. STRPTR
    MUIA_FixWidth                       V4  I.. LONG
    MUIA_FixWidthTxt                    V4  I.. STRPTR
    MUIA_Font                           V4  I.G struct TextFont *
    MUIA_Frame                          V4  I.. LONG
    MUIA_FramePhantomHoriz              V4  I.. BOOL
    MUIA_FrameTitle                     V4  I.. STRPTR
    MUIA_Height                         V4  ..G LONG
    MUIA_HorizDisappear                 V11 ISG LONG
    MUIA_HorizWeight                    V4  ISG WORD
    MUIA_InnerBottom                    V4  I.G LONG
    MUIA_InnerLeft                      V4  I.G LONG
    MUIA_InnerRight                     V4  I.G LONG
    MUIA_InnerTop                       V4  I.G LONG
    MUIA_InputMode                      V4  I.. LONG
    MUIA_LeftEdge                       V4  ..G LONG
    MUIA_MaxHeight                      V11 I.. LONG
    MUIA_MaxWidth                       V11 I.. LONG
    MUIA_Pressed                        V4  ..G BOOL
    MUIA_RightEdge                      V4  ..G LONG
    MUIA_Selected                       V4  ISG BOOL
    MUIA_ShortHelp                      V11 ISG STRPTR
    MUIA_ShowMe                         V4  ISG BOOL
    MUIA_ShowSelState                   V4  I.. BOOL
    MUIA_Timer                          V4  ..G LONG
    MUIA_TopEdge                        V4  ..G LONG
    MUIA_VertDisappear                  V11 ISG LONG
    MUIA_VertWeight                     V4  ISG WORD
    MUIA_Weight                         V4  I.. WORD
    MUIA_Width                          V4  ..G LONG
    MUIA_Window                         V4  ..G struct Window *
    MUIA_WindowObject                   V4  ..G Object *



Area.mui Methods

    Method                              Ver
    ----------------------------------- ---
    MUIM_AskMinMax                      V4  
    MUIM_Cleanup                        V4  
    MUIM_ContextMenuBuild               V11 
    MUIM_ContextMenuChoice              V11 
    MUIM_CreateBubble                   V18 
    MUIM_CreateShortHelp                V11 
    MUIM_DeleteBubble                   V18 
    MUIM_DeleteShortHelp                V11 
    MUIM_DragBegin                      V11 
    MUIM_DragDrop                       V11 
    MUIM_DragFinish                     V11 
    MUIM_DragQuery                      V11 
    MUIM_DragReport                     V11 
    MUIM_Draw                           V4  
    MUIM_DrawBackground                 V11 
    MUIM_HandleEvent                    V16 
    MUIM_HandleInput                    V4  
    MUIM_Hide                           V4  
    MUIM_Setup                          V4  
    MUIM_Show                           V4  


MUIA_Background


    NAME
        MUIA_Background -- (V4 ) [IS.], LONG

    FUNCTION
        Adjust the background for an object.

        Every MUI object has its own background setting.
        The background is displayed "behind" the actual
        object contents, e.g. behind a the text of a
        text object or behind the image of an image object.

        This attribute takes the same values as MUIA_Image_Spec,
        please refer to autodocs of image class for a complete
        description.

        An object without a specific background setting will
        inherit the pattern from its parent group. The default
        background for a window and many other background
        patterns are adjustable with the preferences program.

        Only a few MUII_xxxxxxx tags make sense as background.
        Important are:

        MUII_ButtonBack:
           You have to set this when you create a button gadget.
           Thus, your button will be displayed in the users
           preferred style.

        MUII_TextBack:
           Set this when you create a text object with a TextFrame,
           e.g. some kind of status line. Do *not* use MUII_TextBack
           for simple text without frame (e.g. gadget labels).

        MUII_BACKGROUND
        MUII_SHADOW
        MUII_SHINE
        MUII_FILL
        MUII_SHADOWBACK
        MUII_SHADOWFILL
        MUII_SHADOWSHINE
        MUII_FILLBACK
        MUII_FILLSHINE
        MUII_SHINEBACK
        MUII_SHINEBACK2:
           One of MUI's predefined pattern. These are not
           configurable by the user and will always look the
           same.

        Note: It is *important* that you test your programs with
              a fancy pattern configuration. With the default
              setting you won't notice any errors in your backgrounds.


MUIA_BottomEdge


    NAME
        MUIA_BottomEdge -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_TopEdge, MUIA_Width, MUIA_Height,
        MUIA_RightEdge, MUIA_LeftEdge


MUIA_ContextMenu


    NAME
        MUIA_ContextMenu -- (V11) [ISG], Object *

    FUNCTION
        Specifies a context sensitive popup menu for the current
        object. For MUI, popup menus are nothing else but standard
        intuition menus, so you must specify a pointer to a
        MUI menustrip object (e.g. something returned from
        MUI_MakeObject(MUIO_MenustripNM,...)) here.

        Whenever the user hits the RMB and the mouse is above the parent
        object, MUI will present the popup menu instead of the windows
        menu.

        Note: MUI will *not* dispose the MUIA_ContextMenu object when
        the object is disposed. You must take care of the menustrip
        object yourself. This is because menustrip objects of
        MUIA_ContextMenu do not actually "belong" to their parent
        objects, it's just a "reference". You are allowed to use
        a single menustrip object as MUIA_ContextMenu for different
        objects of the same window. Do *not* share with objects in
        other windows or with the default menu of a window or
        an application!

        If the user selects an item, the object will receive
        a MUIM_ContextMenuChoice method containing the selected
        menuitem object. If you built your menustrip tree with
        MUI_MakeObject(MUIO_MenustripNM,...), you will find the
        nm_UserData of your menu entry in muiUserData(menuitem).
        If you have control over methods because you are a
        subclass, you can immediately take approriate actions 
        when receiving MUIM_ContextMenuChoice.

        If you dont have a subclass or dont override
        MUIM_ContextMenuChoice, the method will finally reach
        area class and will set the attribute MUIA_ContextMenuTrigger
        to the appropriate menuitem object. This allows you to react on
        context menu selections by simple notification and eliminates
        the need of writing a subclass just for this purpose.

        Note: Subclasses are always the better solution!

        There is also a possibility to dynamically create popup menus
        on the fly. See MUIM_ContextMenuBuild for details.

    NOTES
        MUI uses the same tree-like technique as always (e.g. with
        drag&drop) to find out whichs context menu to use on a
        certain mouse position. This allows you to have a context
        menu for a group and different context menus for its
        children. The MUI preferences program makes use of that
        feature by allowing to control a single gadget or a whole
        page of gadgets with popup menus.

    SEE ALSO
        MUIA_ContextMenuTrigger, MUIM_ContextMenuChoice,
        MUIM_ContextMenuBuild


MUIA_ContextMenuTrigger


    NAME
        MUIA_ContextMenuTrigger -- (V11) [..G], Object *

    FUNCTION
        Allows reacting on context menus with notificaton.
        When the MUIM_ContextMenuChoice method reaches area class
        because you did not override it in a subclass, it sets
        MUIA_ContextMenuTrigger to the received paremeter which
        is a pointer to the user-selected menuitem object.

        See MUIA_ContextMenu for details.

    SEE ALSO
        MUIA_ContextMenu, MUIM_ContextMenuChoice, MUIM_ContextMenuBuild


MUIA_ControlChar


    NAME
        MUIA_ControlChar -- (V4 ) [ISG], char

    FUNCTION
        Pressing the control char will have the same effect
        as pressing return if the object was active.
        
        This can be used to create old style key shortcuts.

        Note: Using an uppercase control char will force
              the user to press shift.

    SEE ALSO
        mui.h / KeyButton() macro


MUIA_CycleChain


    NAME
        MUIA_CycleChain -- (V11) [ISG], LONG

    FUNCTION
        MUI 3 introduces a new keyboard cycle chain system. All you 
        have to do is to set  MUIA_CycleChain to 1 for every object 
        that you want to have in your chain, MUI does the rest 
        automatically. The old MUIM_Window_SetCycleChain will continue 
        to work but is considered obsolete.

    SEE ALSO
        Window.mui/MUIM_Window_SetCycleChain


MUIA_Disabled


    NAME
        MUIA_Disabled -- (V4 ) [ISG], BOOL

    FUNCTION
        Disable or enable a gadget. Setting this attribute
        causes a gadget to become disabled, it gets a ghost
        pattern and doesn't respond to user input any longer.

        Disabled gadgets cannot be activated with the TAB key.

        Using MUIA_Disable on a group of objects will disable
        all objects within that group.

    EXAMPLE
        /* we have a radio button gadget with three         */
        /* entries, the third should enable a string gadget */
        /* with additional parameters                       */

        DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 0,
           string, 3, MUIM_Set, MUIA_Disabled, TRUE);

        DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 1,
           string, 3, MUIM_Set, MUIA_Disabled, TRUE);

        DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 2,
           string, 3, MUIM_Set, MUIA_Disabled, FALSE);


MUIA_Draggable


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

    FUNCTION
        Set this if you want the complete object to be
        dragable for D&D operations.


MUIA_Dropable


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

    FUNCTION
        Only objects with this attribute set to TRUE will be asked
        if they want to become an active Drag & Drop destination
        at all. Though this attribute defaults to TRUE, this doesnt
        mean that every object automatically aceppts D&D actions,
        because the MUIM_DragQuery method is answered FALSE when
        it arrives at area class.

    SEE ALSO
        MUIM_DragQuery


MUIA_ExportID


    NAME
        MUIA_ExportID -- (V4 ) [ISG], ULONG (OBSOLETE)

    FUNCTION
        Objects with a non NULL MUIA_ExportID export their
        contents during MUIM_Application_Save and import
        them during MUIM_Application_Load.

        You have to use different ExportIDs for your objects!

    NOTE
        This attribute is renamed to MUIA_ObjectID since
        muimaster.library V12.

    SEE ALSO
        MUIM_Application_Save, MUIM_Application_Load


MUIA_FillArea


    NAME
        MUIA_FillArea -- (V4 ) [IS.], BOOL

    FUNCTION
        Set this if you are a custom class and dont want area class to
        clear your background during the DoSuperMethod() in your
        draw method. Note that if you set this, your draw method
        is responsible for filling every pixel of your objects
        rectangle, otherwise some display trash will remain there.


MUIA_FixHeight


    NAME
        MUIA_FixHeight -- (V4 ) [I..], LONG

    FUNCTION
        Give your object a fixed pixel height. This tag is
        absolutely not needed in a general MUI application
        and only present for emergency situations. Please
        think twice before using it!

    EXAMPLE
        /* create an 8x8 pixel rectangle with FILLPEN */

        RectangleObject,
           MUIA_FixWidth  , 8,
           MUIA_FixHeight , 8,
           MUIA_Background, MUII_FILL,
           End;

    SEE ALSO
        MUIA_FixWidth, MUIA_FixWidthTxt, MUIA_FixHeightTxt


MUIA_FixHeightTxt


    NAME
        MUIA_FixHeightTxt -- (V4 ) [I..], STRPTR

    FUNCTION
        Give your object a fixed pixel height. The height
        will match the height of the given string. This tag is
        absolutely not needed in a general MUI application
        and only present for emergency situations. Please
        think twice before using it!

    EXAMPLE
        /* create a fixed size rectangle with FILLPEN */

        RectangleObject,
           MUIA_FixWidthTxt , "00:00:00",
           MUIA_FixHeightTxt, "\n\n",
           MUIA_Background  , MUII_FILL,
           End;

    SEE ALSO
        MUIA_FixHeight, MUIA_FixWidth, MUIA_FixWidthTxt


MUIA_FixWidth


    NAME
        MUIA_FixWidth -- (V4 ) [I..], LONG

    FUNCTION
        Give your object a fixed pixel width. This tag is
        absolutely not needed in a general MUI application
        and only present for emergency situations. Please
        think twice before using it!

    EXAMPLE
        /* create an 8x8 pixel rectangle with FILLPEN */

        RectangleObject,
           MUIA_FixWidth  , 8,
           MUIA_FixHeight , 8,
           MUIA_Background, MUII_FILL,
           End;

    SEE ALSO
        MUIA_FixHeight, MUIA_FixWidthTxt, MUIA_FixHeightTxt


MUIA_FixWidthTxt


    NAME
        MUIA_FixWidthTxt -- (V4 ) [I..], STRPTR

    FUNCTION
        Give your object a fixed pixel width. The width
        will match the width of the given string. This tag is
        absolutely not needed in a general MUI application
        and only present for emergency situations. Please
        think twice before using it!

    EXAMPLE
        /* create a fixed size rectangle with FILLPEN */

        RectangleObject,
           MUIA_FixWidthTxt , "00:00:00",
           MUIA_FixHeightTxt, "\n\n",
           MUIA_Background  , MUII_FILL,
           End;

    SEE ALSO
        MUIA_FixHeight, MUIA_FixWidth, MUIA_FixHeightTxt


MUIA_Font


    NAME
        MUIA_Font -- (V4 ) [I.G], struct TextFont *

    SPECIAL INPUTS
        MUIV_Font_Inherit
        MUIV_Font_Normal
        MUIV_Font_List
        MUIV_Font_Tiny
        MUIV_Font_Fixed
        MUIV_Font_Title
        MUIV_Font_Big
        MUIV_Font_Button

    FUNCTION
        Every MUI object can have its own font, just set it with
        this tag. Objects without an explicit font setting will
        inherit it from their parent group.

        You normally won't need to open a font yourself, just
        use one of the predefined values to get a font from
        the users preferences.

    EXAMPLE
        /* since the text contains tabs,           */
        /* use the fixed width font for displaying */

        msgread = FloattextObject,
           MUIA_Font, MUIV_Font_Fixed,
           ...,
           End;


MUIA_Frame


    NAME
        MUIA_Frame -- (V4 ) [I..], LONG

    SPECIAL INPUTS
        MUIV_Frame_None
        MUIV_Frame_Button
        MUIV_Frame_ImageButton
        MUIV_Frame_Text
        MUIV_Frame_String
        MUIV_Frame_ReadList
        MUIV_Frame_InputList
        MUIV_Frame_Prop
        MUIV_Frame_Gauge
        MUIV_Frame_Group
        MUIV_Frame_PopUp
        MUIV_Frame_Virtual
        MUIV_Frame_Slider
        MUIV_Frame_Count

    FUNCTION
        Define a frame for the current object. Since area class
        is a superclass for all elements in a window, you can
        assign frames to every object you wish.

        You don't adjust the style of your frame directly,
        instead you only specify a type:

        MUIV_Frame_Button
           for standard buttons with text in it.

        MUIV_Frame_ImageButton
           for small buttons with images, e.g. the arrows
           of a scrollbar.

        MUIV_Frame_Text
           for a text field, e.g. a status line display.

        MUIV_Frame_String
           for a string gadget.

        MUIV_Frame_ReadList
           for a read only list.

        MUIV_Frame_InputList
           for a list that handles input (has a cursor).

        MUIV_Frame_Prop
           for proportional gadgets.

        MUIV_Frame_Group
           for groups.

        How the frame is going to look is adjustable via the
        preferences program.

        Four spacing values belong to each frame that tell
        MUI how many pixels should be left free between the
        frame and its contents. These spacing values are also
        user adjustable as long as you don't override them
        with one of MUIA_InnerLeft, MUIA_InnerRight, MUIA_InnerTop,
        or MUIA_InnerBottom.

        Note: The first object in a window (MUIA_Window_RootObject)
              may *not* have a frame. If you need this you will have
              to create a dummy group with just one child.

    EXAMPLE
        strobj = StringObject,
           MUIA_Frame, MUIV_Frame_String,
           End;

    SEE ALSO
        MUIA_InnerLeft, MUIA_InnerRight, MUIA_InnerTop,
        MUIA_InnerBottom


MUIA_FramePhantomHoriz


    NAME
        MUIA_FramePhantomHoriz -- (V4 ) [I..], BOOL

    FUNCTION
        Setting this to TRUE causes the specified frame to be
        a horizontal phantom frame. The frame will not appear
        but its vertical components (frame height, inner
        top and inner bottom spacing) will be used to calculate
        positions and dimensions (horizontal components are
        treated as 0).

        This is extremely useful for a correct labeling of objects.
        You would e.g. label a string gadget by using a text object
        with a phantom string frame. Thus, the label text will
        be always on the same vertical position as the string
        gadget text, no matter what spacing values the user
        configured.

    SEE ALSO
        Label() macros in "mui.h".


MUIA_FrameTitle


    NAME
        MUIA_FrameTitle -- (V4 ) [I..], STRPTR

    FUNCTION
        This tag identifies a text string that will be displayed
        centered in the top line of a frame. This can become
        handy if you want to name groups of objects.

        You may not use MUIA_FrameTitle without defining
        a MUIA_Frame.

    EXAMPLE
        VGroup,
           MUIA_Frame     , MUIV_Frame_Group,
           MUIA_FrameTitle, "Spacing",
           ...

    SEE ALSO
        MUIA_Frame


MUIA_Height


    NAME
        MUIA_Height -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_TopEdge, MUIA_Width, MUIA_LeftEdge,
        MUIA_RightEdge, MUIA_BottomEdge


MUIA_HorizDisappear


    NAME
        MUIA_HorizDisappear -- (V11) [ISG], LONG

    FUNCTION
        Objects with a disappear level disappear automatically
        when their parent window gets too small to display them.
        Use this for things that make your GUI look nicer
        (e.g. Imagery) but are not absolutely necessary.

        By using disappearing objects, you can make nice GUIs
        which still work on crappy 640x200 screens.

        You can give horizontal or vertical disappear levels
        to objects which are used for horizontal or vertical
        layout calculations respectively.

        Objects with a small disappear level disappear before
        objects with a big disappear level.

    SEE ALSO
        MUIA_VertDisappear


MUIA_HorizWeight


    NAME
        MUIA_HorizWeight -- (V4 ) [ISG], WORD

    FUNCTION
        Adjust the horizontal weight of an object. Usually
        you can simply use MUIA_Weight instead of this tag
        but in some two-dimensional groups it may become
        handy to have different horizontal and vertical 
        weights.

    SEE ALSO
        MUIA_Weight


MUIA_InnerBottom


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

    FUNCTION
        Adjust the space between an object and its frame.
        Usually you shouldn't use this tag since you will
        override the users preferred default setting.

    SEE ALSO
        MUIA_Frame


MUIA_InnerLeft


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

    FUNCTION
        Adjust the space between an object and its frame.
        Usually you shouldn't use this tag since you will
        override the users preferred default setting.

    SEE ALSO
        MUIA_Frame


MUIA_InnerRight


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

    FUNCTION
        Adjust the space between an object and its frame.
        Usually you shouldn't use this tag since you will
        override the users preferred default setting.

    SEE ALSO
        MUIA_Frame


MUIA_InnerTop


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

    FUNCTION
        Adjust the space between an object and its frame.
        Usually you shouldn't use this tag since you will
        override the users preferred default setting.

    SEE ALSO
        MUIA_Frame


MUIA_InputMode


    NAME
        MUIA_InputMode -- (V4 ) [I..], LONG

    SPECIAL INPUTS
        MUIV_InputMode_None
        MUIV_InputMode_RelVerify
        MUIV_InputMode_Immediate
        MUIV_InputMode_Toggle

    FUNCTION
        Adjust the input mode for an object.

        MUI has no distinct button class. Instead you can make
        every object (even groups) behave like a button by
        setting an input mode for them. Several input modes
        area available:

        MUIV_InputMode_None:
           No input, this is not a gadget.

        MUIV_InputMode_RelVerify:
           For buttons and similar stuff.

        MUIV_InputMode_Immediate:
           Used e.g. in a radio button object.

        MUIV_InputMode_Toggle:
           For things like checkmark gadgets.

        The input mode setting determines how a user action
        will trigger the attributes MUIA_Selected, MUIA_Pressed
        and MUIA_Timer. See their documentation for details.

    EXAMPLE
        /* A traditional button, just a text object with */
        /* a button frame and a relverify input mode:    */

        okbutton = TextObject,
           MUIA_Frame        , MUIV_Frame_Button,
           MUIA_InputMode    , MUIV_InputMode_RelVerify,
           MUIA_Text_Contents, "OK",
           ...

    SEE ALSO
        MUIA_Selected, MUIA_Timer, MUIA_Pressed


MUIA_LeftEdge


    NAME
        MUIA_LeftEdge -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_TopEdge, MUIA_Width, MUIA_Height,
        MUIA_RightEdge, MUIA_BottomEdge


MUIA_MaxHeight


    NAME
        MUIA_MaxHeight -- (V11) [I..], LONG

    FUNCTION
        Specify a maximum height for an object (in pixels).

    SEE ALSO
        MUIA_MaxWidth, MUIA_FixWidth, MUIA_FixHeight


MUIA_MaxWidth


    NAME
        MUIA_MaxWidth -- (V11) [I..], LONG

    FUNCTION
        Specify a maximum width for an object (in pixels).

    SEE ALSO
        MUIA_MaxHeight, MUIA_FixWidth, MUIA_FixHeight


MUIA_Pressed


    NAME
        MUIA_Pressed -- (V4 ) [..G], BOOL

    FUNCTION
        Learn if a button is pressed (or released).
        The MUIA_Pressed attribute of a gadget is triggered
        by some user action, depending on the input mode:

        MUIV_InputMode_RelVerify:
           - set when lmb is pressed.
           - cleared when lmb is released and the mouse
             is still over the gadget (otherwise it will
             be cleared too, but without triggering a
             notification event).

        MUIV_InputMode_Immediate:
           - undefined, use MUIA_Selected for this.

        MUIV_InputMode_Toggle:
           - undefined, use MUIA_Selected for this.

        Waiting for MUIA_Pressed getting FALSE is the usual
        way to react on button gadgets.

    EXAMPLE
        DoMethod(btcancel,MUIM_Notify,MUIA_Pressed,FALSE,
           app,2,MUIM_Application_ReturnID,ID_CANCEL);

    SEE ALSO
        MUIA_Selected, MUIA_Timer, MUIA_ShowSelState, MUIA_InputMode


MUIA_RightEdge


    NAME
        MUIA_RightEdge -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_TopEdge, MUIA_Width, MUIA_Height,
        MUIA_LeftEdge, MUIA_BottomEdge


MUIA_Selected


    NAME
        MUIA_Selected -- (V4 ) [ISG], BOOL

    FUNCTION
        Get and set the selected state of a gadget.
        This attribute can be triggered by the user
        clicking on the gadget (or using the keyboard),
        depending on the input mode:

        MUIV_InputMode_RelVerify:
           - set when lmb is pressed.
           - cleared when lmb is released.
           - cleared when the gadget is selected and the
             mouse leaves the gadget box.
           - set when the mouse reenters the gadget box.

        MUIV_InputMode_Immediate:
           - set when lmb is pressed.

        MUIV_InputMode_Toggle:
           - toggled when lmb is pressed.

        Of course you may set this attribute yourself, e.g.
        to adjust the state of a checkmark gadget.

        A selected gadget will display its border reverse
        and get the configured MUII_SelectedBack background.
        This can be avoided using the MUIA_ShowSelState tag.

    SEE ALSO
        MUIA_Pressed, MUIA_Timer, MUIA_ShowSelState, MUIA_InputMode


MUIA_ShortHelp


    NAME
        MUIA_ShortHelp -- (V11) [ISG], STRPTR

    FUNCTION
        Specify a string that is to be used as bubble help for this
        object.


MUIA_ShowMe


    NAME
        MUIA_ShowMe -- (V4 ) [ISG], BOOL

    FUNCTION
        Objects with this attribute set are not displayed. You can
        set MUIA_ShowMe at any time, causing objects to appear and
        to disappear immediately. A new layout is calculated whenever
        some objects are shown or hidden. When necessary, MUI will
        resize the parent window to make place for the new objects.

    NOTE
        Currently, MUI does a complete window refresh after
        showing/hiding objects. This behaviour might get improved
        in the future.


MUIA_ShowSelState


    NAME
        MUIA_ShowSelState -- (V4 ) [I..], BOOL

    FUNCTION
        Normally a gadget will reverse its frame and
        display the configured MUII_SelectetBack background
        pattern in its selected state. For some objects
        (e.g. checkmarks) this is not recommended and
        can be supressed by setting MUIA_ShowSelState
        to FALSE.

    SEE ALSO
        MUIA_Selected


MUIA_Timer


    NAME
        MUIA_Timer -- (V4 ) [..G], LONG

    FUNCTION
        MUIA_Timer gets triggered when a relverify button is 
        pressed and (after a little delay) increases every 
        INTUITICK as long as the mouse remains over the gadget.

        This makes it possible to have buttons repeatedly
        cause some actions, just like the arrow gadgets of
        a scrollbar.

    EXAMPLE
        DoMethod(btmore,MUIM_Notify,MUIA_Timer,MUIV_EveryTime,
           app,2,MUIM_Application_ReturnID,ID_MORE);

        DoMethod(btless,MUIM_Notify,MUIA_Timer,MUIV_EveryTime,
           app,2,MUIM_Application_ReturnID,ID_LESS);

    SEE ALSO
        MUIA_Pressed, MUIA_Selected


MUIA_TopEdge


    NAME
        MUIA_TopEdge -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_LeftEdge, MUIA_Width, MUIA_Height,
        MUIA_RightEdge, MUIA_BottomEdge


MUIA_VertDisappear


    NAME
        MUIA_VertDisappear -- (V11) [ISG], LONG

    FUNCTION
        Objects with a disappear level disappear automatically
        when their parent window gets too small to display them.
        Use this for things that make your GUI look nicer
        (e.g. Imagery) but are not absolutely necessary.

        By using disappearing objects, you can make nice GUIs
        which still work on crappy 640x200 screens.

        You can give horizontal or vertical disappear levels
        to objects which are used for horizontal or vertical
        layout calculations respectively.

        Objects with a small disappear level disappear before
        objects with a big disappear level.

    SEE ALSO
        MUIA_HorizDisappear


MUIA_VertWeight


    NAME
        MUIA_VertWeight -- (V4 ) [ISG], WORD

    FUNCTION
        Adjust the vertical weight of an object. Usually
        you can simply use MUIA_Weight instead of this tag
        but in some two-dimensional groups it may become
        handy to have different horizontal and vertical
        weights.

    SEE ALSO
        MUIA_Weight


MUIA_Weight


    NAME
        MUIA_Weight -- (V4 ) [I..], WORD

    FUNCTION
        This tag is a shorthand for MUIA_HorizWeight and
        MUIA_VertWeight, it sets both weights at once.

        The weight of an object determines how much room it
        will get during the layout process. Imagine you have
        a 100 pixel wide horizontal group with two string
        gadgets. Usually, each gadget will get half of the
        room and be 50 pixels wide. If you feel the left
        gadget is more important and should be bigger,
        you can give it a weight of 200 (and 100 for
        the right gadget). Because the left gadget is
        twice as "heavy" as the right gadget, it will
        become twice as big (about 66 pixel) as the
        right one (34 pixel).

        Of course giving weights only makes sense if the
        object is resizable. A MUIA_VertWeight for a
        (always fixed height) string gadget is useless.

        An object with a weight of 0 will always stay
        at its minimum size.

        By default, all objects have a weight of 100.

    EXAMPLE
        HGroup,
           StringGadget, MUIA_Weight,  50, End,
           StringGadget, MUIA_Weight, 100, End,
           StringGadget, MUIA_Weight, 200, End,
           End;

    SEE ALSO
        MUIA_HorizWeight, MUIA_VertWeight


MUIA_Width


    NAME
        MUIA_Width -- (V4 ) [..G], LONG

    FUNCTION
        You can use this to read the current position and
        dimension of an object, if you e.g. need it to pop
        up some requester below.

        Of course, this attribute is only valid when the
        parent window of the object is currently open.

    SEE ALSO
        MUIA_TopEdge, MUIA_LeftEdge, MUIA_Height,
        MUIA_RightEdge, MUIA_BottomEdge


MUIA_Window


    NAME
        MUIA_Window -- (V4 ) [..G], struct Window *

    FUNCTION
        This attribute can be used to get a pointer to the
        intuition window structure of the parent window 
        ot the object. This pointer could e.g. be used
        in calls to asl.library.

        The result is only valid when the window is opened.

    SEE ALSO
        MUIA_Window_Window


MUIA_WindowObject


    NAME
        MUIA_WindowObject -- (V4 ) [..G], Object *

    FUNCTION
        You can obtain a pointer to the window object
        that some gadget belongs to by using this attribute.
        Useful mainly within callback hooks if you do not want
        to deal with global variables.

    SEE ALSO
        MUIA_ApplicationObject


MUIM_AskMinMax


    NAME
        MUIM_AskMinMax (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_AskMinMax,struct MUI_MinMax *MinMaxInfo);

    FUNCTION
        see developer documentation.


MUIM_Cleanup


    NAME
        MUIM_Cleanup (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_Cleanup);

    FUNCTION
        see developer documentation.


MUIM_ContextMenuBuild


    NAME
        MUIM_ContextMenuBuild (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_ContextMenuBuild,LONG mx, LONG my);

    FUNCTION
        Allows dynamic creation of context menus.
        When MUI is about to show a new context menu, it does not
        simply use the MUIA_ContextMenu field of area class. Instead,
        it sends a MUIM_ContextMenuBuild to the object in question and
        uses the return value as the new menustrip object.

        When MUIM_ContextMenuBuild reaches area class, it just return
        the contents of MUIA_ContextMenu so you neednt care about this
        method if you only have static, non-changing context menus.

        However, if your context menus depend on some internal states
        of your objects or on the mouse position within your objects,
        you have to have a subclass which overrides
        MUIM_ContextMenuBuild, creates a nice menustrip object and
        returns it.

    INPUTS
        mx - current x position of mouse
        my - current y position of mouse

        Since MUI does (unfortunately) not use relative coordinates 
        at all, these two aren't relative either.

    RESULT
        You must return a pointer to a menustrip object or NULL if
        you failed to create one.

    NOTES
        MUI will never dispose the object you return. You must be
        take care of this yourself, e.g. by storing a pointer somewhere
        in your instance data and killing it on the next invocation
        of MUIM_ContextMenuBuild and on OM_DISPOSE.

        Even when overriding MUIM_ContextMenuBuild, you *must* set
        MUIA_ContextMenu of your object to something different from NULL.
        MUI will find out that your object actually has a popup menu
        by directly checking the contents of MUIA_ContextMenu in the
        instance data of area class due to speed reasons.

    SEE ALSO
        MUIA_ContextMenu, MUIA_ContextMenuTrigger, MUIM_ContextMenuChoice,


MUIM_ContextMenuChoice


    NAME
        MUIM_ContextMenuChoice (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_ContextMenuChoice,Object *item);

    FUNCTION
        Allows reacting on context menus in subclasses.

        See MUIA_ContextMenu for details.

    SEE ALSO
        MUIA_ContextMenuTrigger, MUIM_ContextMenuChoice,
        MUIM_ContextMenuBuild


MUIM_CreateBubble


    NAME
        MUIM_CreateBubble (V18)

    SYNOPSIS
        DoMethod(obj,MUIM_CreateBubble,LONG x, LONG y, char *txt, ULONG flags);

    FUNCTION
        Together with MUIM_DeleteBubble, this method provides an
        interface for MUIs bubble mechanism. Applications can use
        bubbles for their own purpose, e.g. for indicating error
        conditions on certain gadgets.

        MUIM_CreateBubble creates a bubble at the specified
        coordinates with the specified (textual) contents. It
        returns a bubble "handle" that has to be passed to
        MUIM_DeleteBubble when the bubble shall disappear.

        There's no limitation on the number of bubbles, you can create
        lots of them at a time if you wish. Also, these custom bubbles
        are completely independant of MUI's bubble help system and won't
        disappear automatically when the mouse is moved.

        Note that bubbles will only show up when the object in question
        is visible. Otherwise MUIM_CreateBubble returns NULL. You are
        responsible for deleting the bubble *before* the object get's
        invisible. Good place to remove a custom bubble is e.g. the
        MUIM_Hide method of your object.

    INPUTS
        - x,y: window-relative coordinates of the bubble.

        - txt: custom text for the bubble. If you pass NULL here, MUI
               will query the object with MUIM_CreateShortHelp method
               for a text (like the automatic help system does).

        - flags: always set to 0 for now!

    RESULT
        This method returns a pointer to a (black box) bubble handle or
        NULL on failure. You have to pass the bubble handle to 
        MUIM_DeleteBubble if you want to delete the bubble later.

    SEE ALSO
        MUIM_DeleteBubble, MUIM_CreateShortHelp, MUIM_DeleteShortHelp


MUIM_CreateShortHelp


    NAME
        MUIM_CreateShortHelp (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_CreateShortHelp,LONG mx, LONG my);

    FUNCTION
        yet undocumented, complain in the beta mailing list :)

    INPUTS

    RESULT

    BUGS

    SEE ALSO


MUIM_DeleteBubble


    NAME
        MUIM_DeleteBubble (V18)

    SYNOPSIS
        DoMethod(obj,MUIM_DeleteBubble,APTR bubble);

    FUNCTION
        Together with MUIM_CreateBubble, this method provides an
        interface for MUIs bubble mechanism. Applications can use
        bubbles for their own purpose, e.g. for indicating error
        conditions on certain gadgets.

        MUIM_DeleteBubble deletes a bubble that was previously
        created with MUIM_CreateBubble. Not that bubbles have to
        be deleted before an object get's invisible!

    INPUTS
        - bubble: pointer to black box bubble handle as returned by
          MUIM_CreateBubble. 

    RESULT
        The bubble will be removed. The return value is undefined.

    SEE ALSO
        MUIM_CreateBubble, MUIM_CreateShortHelp, MUIM_DeleteShortHelp


MUIM_DeleteShortHelp


    NAME
        MUIM_DeleteShortHelp (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DeleteShortHelp,STRPTR help);

    FUNCTION
        yet undocumented, complain in the beta mailing list :)

    INPUTS

    RESULT

    BUGS

    SEE ALSO


MUIM_DragBegin


    NAME
        MUIM_DragBegin (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DragBegin,Object *obj);

    FUNCTION
        Inform an object that it has become the active destination
        of a drag&drop action. An object will only receive this if
        it has responded positively to a previous MUIM_DragQuery.

    SEE ALSO
        MUIM_DragQuery, MUIM_DragFinish, MUIM_DragReport, MUIM_DragDrop


MUIM_DragDrop


    NAME
        MUIM_DragDrop (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DragDrop,Object *obj, LONG x, LONG y);

    FUNCTION
        Indicate that the user dropped something on the current
        object.

    SEE ALSO
        MUIM_DragBegin, MUIM_DragFinish, MUIM_DragReport, MUIM_DragQuery


MUIM_DragFinish


    NAME
        MUIM_DragFinish (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DragFinish,Object *obj);

    FUNCTION
        Indicate that an object is no longer the active destination
        object of a drag&drop action.

    SEE ALSO
        MUIM_DragQuery, MUIM_DragBegin, MUIM_DragReport, MUIM_DragDrop


MUIM_DragQuery


    NAME
        MUIM_DragQuery (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DragQuery,Object *obj);

    FUNCTION
        MUI offers complete drag & drop capabilities for every object.
        If enabled, the user is able to grab an object, drag it around
        and drop it on another object. Currently, D&D is limited to
        single applications, i.e. you cannot take an object from one
        program and drop it into another one. D&D between different
        windows of the same application, however, is fine.

        MUI controls the D&D actions with a set of five methods:
        MUIM_DragQuery, MUIM_DragBegin, MUIM_DragReport, MUIM_DragDrop
        and MUIM_DragFinish. Basically things work this way:

        Lets assume the user has taken an object (called the source
        object) and is now starting to drag it around. During
        dragging, MUI will find out which object is currently under
        the mouse pointer and if it found one, send it the
        MUIM_DragQuery method. An object that receives MUIM_DragQuery
        can now determine it it wishes to accept drops from the source
        object or not. If it responds positively, the object will
        become the current destination object.

        Due to the nature of MUIs layout system, a specific x,y pair
        of coordinates cannot be bound to a specific object
        immediately. Instead, the coordinates belong to a whole tree
        of objects, for example some cycle gadget, its parent group,
        the parent group of the parent group and so on until the tree
        reaches the windows root object. To allow complete groups of
        objects to participate in D&D business, the MUIM_DragQuery is
        first sent to the deepest nested object (the cycle gadget in
        the above example). If this one doesn't respond, MUI sends a
        MUIM_DragQuery to its parent group and so on until it either
        finds some object who accepts the drop or reaches the end of
        the tree. If there is an accepting object, it will become the
        current destination, if there isnt, no destination will be
        set.

        Objects becoming active destinations of a drag process learn
        about their current state by receiving a MUIM_DragBegin
        method. This method, when reaching area class, e.g. draws a
        special frame around the object to indicate the current state
        to the user.

        The opposite of MUIM_DragBegin is MUIM_DragFinish will be sent
        as soon as the object stops being destination of the drag
        process, i.e. because the user aborted the drag or moved out
        of the bounding box. MUIM_DragFinish will also be sent after a
        successful drop, you cant count on receiving a MUIM_DragFinish
        if you received a MUIM_DragBegin before. Furthermore, only one
        object will be between MUIM_DragBegin and MUIM_DragFinish at
        any time.

        Active destination objects (between MUIM_DragBegin and
        MUIM_DragFinish) receive MUIM_DragReport methods as long as
        the user moves the mouse within the object. MUIM_DragReport
        contains the mouse coordinates, so the object can update its
        display according to the position of the source object. A
        listview would e.g. indicate the insert position to give the
        user an idea where the source would be inserted in case of a
        drop.

        All the method mentioned above are just interim messages that
        help visualizing the drag process. When the user actually
        decides to drop its source object, the current destination
        object (if any) receives a MUIM_DragDrop method and can
        perfrom whatever operatoin it thinks is suited to handle a D&D
        action from the source object.

        You probably have noticed that D&D is controlled by methods.
        This means that you need to write subclasses if you intend to
        use it. However, you neednt implement all the above mentioned
        things to reach your goal. In fact, MUIM_DragQuery and
        MUIM_DragDrop are enough for almost all D&D invocations.
        Here's a little example of how MUI implements D&D between
        objects of Pendisplay class. These few lines allow the user to
        take any Pendisplay (or subclasses from Pendisplay like e.g.
        Poppen class) and drop it onto another one:

        ULONG mDragQuery(cl,obj,struct MUIP_DragQuery *msg)
        {
                char *spec;

                /* refuse to drop on ourselves */
                if (msg->obj==obj)
                        return(MUIV_DragQuery_Refuse);

                /* if the source object offers the attribute */
                /* we want, show that we would accept it. */
                if (get(msg->obj,MUIA_Pendisplay_Spec,&spec))
                        return(MUIV_DragQuery_Accept);

                /* refuse otherwise */
                return(MUIV_DragQuery_Refuse);
        }


        ULONG mDragDrop(cl,obj,struct MUIP_DragDrop *msg)
        {
                char *spec;

                /* copy the attribute from the source object */
                get(msg->obj,MUIA_Pendisplay_Spec,&spec);
                set(obj,MUIA_Pendisplay_Spec,spec);

                return(0);
        }

    SEE ALSO
        MUIM_DragBegin, MUIM_DragFinish, MUIM_DragReport, MUIM_DragDrop


MUIM_DragReport


    NAME
        MUIM_DragReport (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DragReport,Object *obj, LONG x, LONG y, LONG update);

    FUNCTION
        Interim messages from MOUSEMOVEs and INTUITICKs sent as long
        as an object is active destination of a drag&drop action.

    SEE ALSO
        MUIM_DragQuery, MUIM_DragFinish, MUIM_DragBegin, MUIM_DragDrop


MUIM_Draw


    NAME
        MUIM_Draw (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_Draw,ULONG flags);

    FUNCTION
        see developer documentation.


MUIM_DrawBackground


    NAME
        MUIM_DrawBackground (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_DrawBackground,LONG left, LONG top, LONG width, LONG height, LONG xoffset, LONG yoffset, LONG flags);

    FUNCTION
        If you decided to use MUIA_FillArea, FALSE for your custom
        class, i.e. if you care about background rendering yourself,
        you can use this method to draw a specific part of your
        objects background with the defined MUIA_Background.

    INPUTS
        - left, top, right, bottom: rectangle to draw, be sure to
          add your objects _mleft and _mtop coordinates.

        - xoffset, yoffset: offset to use when background is a pattern.

        - flags: always set to 0 for now!

    RESULT
        The result value of this method is currently undefined.

    SEE ALSO
        MUIA_Background


MUIM_HandleEvent


    NAME
        MUIM_HandleEvent (V16)
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_HandleEvent,struct IntuiMessage *imsg, LONG muikey);

    FUNCTION
        This method is invoked whenever one of an event handlers
        trigger signals arrives. It's described in area class
        context but does not really belong here.

    INPUTS
        imsg - pointer to a struct IntuiMessage that caused the event.
               note well that this may be NULL in which case you
               simply not parse imsg.

        muikey - if the imsg translates to a predefined keystroke,
                 this parameter holds the corresponding MUIKEY_XXXX
                 value. Otherwise it will be MUIKEY_NONE.

    NOTES
        You must not rely on imsg being non-NULL, regardless whether
        muikey is set or unset.

    RESULT
        The result is a bitfield. Currently, only one bit is defined:

        - MUI_EventHandlerRC_Eat
          Set this if this event was for you and you want MUI to stop
          calling other event handlers in the chain.

        All other bits are reserved for future use and must be zero!

    SEE ALSO
        window.mui/MUIM_Window_AddEventHandler


MUIM_HandleInput


    NAME
        MUIM_HandleInput (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_HandleInput,struct IntuiMessage *imsg, LONG muikey);

    FUNCTION
        see developer documentation.


MUIM_Hide


    NAME
        MUIM_Hide (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_Hide);

    FUNCTION
        see developer documentation.


MUIM_Setup


    NAME
        MUIM_Setup (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_Setup,struct MUI_RenderInfo *RenderInfo);

    FUNCTION
        see developer documentation.


MUIM_Show


    NAME
        MUIM_Show (V4 )
        [For use within custom classes only]

    SYNOPSIS
        DoMethod(obj,MUIM_Show);

    FUNCTION
        see developer documentation.





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