MUI Autodocs: Window.mui

Copyright © 1998, Stefan Stuntz




Window.mui Background

        Objects of window class are used to generate windows and
        supply a place where MUI gadgets feel well. It handles
        the complicated task of window resizing fully automatic,
        you don't need to worry about that.

        Windows are children of an application, you cannot use
        a window object without having a parent application
        object. On the other side, the gadgets in a window
        are children of the window, you cannot use MUI gadgets
        without having a parent MUI window.

        Creating a window object does not mean to open it
        instantly. This is done later by setting the window's
        MUIA_Window_Open attribute. If your application has
        several windows, the usual way is to create them all
        at once at startup time and open/close it later
        just by setting MUIA_Window_Open.

        There is no difference in talking to gadgets whether
        their parent window is open or not. If you e.g. set
        the contents of a string gadget in an open window,
        the gadget will refresh immediately. If the window is
        closed, the gadget just remembers its new setting
        and displays it later.



Window.mui Attributes

    Attribute                           Ver ISG Type
    ----------------------------------- --- --- --------------------
    MUIA_Window_Activate                V4  ISG BOOL
    MUIA_Window_ActiveObject            V4  .SG Object *
    MUIA_Window_AltHeight               V4  I.G LONG
    MUIA_Window_AltLeftEdge             V4  I.G LONG
    MUIA_Window_AltTopEdge              V4  I.G LONG
    MUIA_Window_AltWidth                V4  I.G LONG
    MUIA_Window_AppWindow               V5  I.. BOOL
    MUIA_Window_Backdrop                V4  I.. BOOL
    MUIA_Window_Borderless              V4  I.. BOOL
    MUIA_Window_CloseGadget             V4  I.. BOOL
    MUIA_Window_CloseRequest            V4  ..G BOOL
    MUIA_Window_DefaultObject           V4  ISG Object *
    MUIA_Window_DepthGadget             V4  I.. BOOL
    MUIA_Window_DisableKeys             V15 ISG ULONG
    MUIA_Window_DragBar                 V4  I.. BOOL
    MUIA_Window_FancyDrawing            V8  ISG BOOL
    MUIA_Window_Height                  V4  I.G LONG
    MUIA_Window_ID                      V4  ISG ULONG
    MUIA_Window_InputEvent              V4  ..G struct InputEvent *
    MUIA_Window_IsSubWindow             V4  ISG BOOL
    MUIA_Window_LeftEdge                V4  I.G LONG
    MUIA_Window_Menu                    V4  I.. struct NewMenu * (OBSOLETE)
    MUIA_Window_MenuAction              V8  ISG ULONG
    MUIA_Window_Menustrip               V8  I.G Object *
    MUIA_Window_MouseObject             V10 ..G Object *
    MUIA_Window_NeedsMouseObject        V10 I.. BOOL
    MUIA_Window_NoMenus                 V4  IS. BOOL
    MUIA_Window_Open                    V4  .SG BOOL
    MUIA_Window_PublicScreen            V6  ISG STRPTR
    MUIA_Window_RefWindow               V4  IS. Object *
    MUIA_Window_RootObject              V4  ISG Object *
    MUIA_Window_Screen                  V4  ISG struct Screen *
    MUIA_Window_ScreenTitle             V5  ISG STRPTR
    MUIA_Window_SizeGadget              V4  I.. BOOL
    MUIA_Window_SizeRight               V4  I.. BOOL
    MUIA_Window_Sleep                   V4  .SG BOOL
    MUIA_Window_Title                   V4  ISG STRPTR
    MUIA_Window_TopEdge                 V4  I.G LONG
    MUIA_Window_UseBottomBorderScroller V13 ISG BOOL
    MUIA_Window_UseLeftBorderScroller   V13 ISG BOOL
    MUIA_Window_UseRightBorderScroller  V13 ISG BOOL
    MUIA_Window_Width                   V4  I.G LONG
    MUIA_Window_Window                  V4  ..G struct Window *



Window.mui Methods

    Method                              Ver
    ----------------------------------- ---
    MUIM_Window_AddEventHandler         V16 
    MUIM_Window_Cleanup                 V18 
    MUIM_Window_GetMenuCheck            V4   (OBSOLETE)
    MUIM_Window_GetMenuState            V4   (OBSOLETE)
    MUIM_Window_RemEventHandler         V16 
    MUIM_Window_ScreenToBack            V4  
    MUIM_Window_ScreenToFront           V4  
    MUIM_Window_SetCycleChain           V4   (OBSOLETE)
    MUIM_Window_SetMenuCheck            V4   (OBSOLETE)
    MUIM_Window_SetMenuState            V4   (OBSOLETE)
    MUIM_Window_Setup                   V18 
    MUIM_Window_Snapshot                V11 
    MUIM_Window_ToBack                  V4  
    MUIM_Window_ToFront                 V4  


MUIA_Window_Activate


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

    FUNCTION
        Setting this to TRUE will activate the window.
        Setting this to FALSE has no effect.
        The attribute will change whenever the user
        activates/deactivates the window.

        Specifying FALSE at object creation time will make
        the window open in an inactive state.


MUIA_Window_ActiveObject


    NAME
        MUIA_Window_ActiveObject -- (V4 ) [.SG], Object *

    SPECIAL INPUTS
        MUIV_Window_ActiveObject_None
        MUIV_Window_ActiveObject_Next
        MUIV_Window_ActiveObject_Prev

    FUNCTION
        Set the active object in a window as if the user
        would have activated it with the tab key. The
        object has to be in the cycle chain for this
        command to work.

    EXAMPLE
        set(window,MUIA_Window_ActiveObject,okaybutton);

    SEE ALSO
        MUIM_Window_SetCycleChain


MUIA_Window_AltHeight


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

    SPECIAL INPUTS
        MUIV_Window_AltHeight_MinMax(p)
        MUIV_Window_AltHeight_Visible(p)
        MUIV_Window_AltHeight_Screen(p)
        MUIV_Window_AltHeight_Scaled

    FUNCTION
        Specify the alternate (zoomed) height of a window.
        If not present, the alternate height will be the
        minimum height.

    SEE ALSO
        MUIA_Window_Height, MUIA_Window_AltWidth


MUIA_Window_AltLeftEdge


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

    SPECIAL INPUTS
        MUIV_Window_AltLeftEdge_Centered
        MUIV_Window_AltLeftEdge_Moused
        MUIV_Window_AltLeftEdge_NoChange

    FUNCTION
        Specify the alternate (zoomed) left position of
        a window. This defaults to the standard left
        position.

    SEE ALSO
        MUIA_Window_LeftEdge, MUIA_Window_AltTopEdge


MUIA_Window_AltTopEdge


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

    SPECIAL INPUTS
        MUIV_Window_AltTopEdge_Centered
        MUIV_Window_AltTopEdge_Moused
        MUIV_Window_AltTopEdge_Delta(p)
        MUIV_Window_AltTopEdge_NoChange

    FUNCTION
        Specify the alternate (zoomed) top position of
        a window. This defaults to the standard top
        position.

    SEE ALSO
        MUIA_Window_TopEdge, MUIA_Window_AltLeftEdge


MUIA_Window_AltWidth


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

    SPECIAL INPUTS
        MUIV_Window_AltWidth_MinMax(p)
        MUIV_Window_AltWidth_Visible(p)
        MUIV_Window_AltWidth_Screen(p)
        MUIV_Window_AltWidth_Scaled

    FUNCTION
        Specify the alternate (zoomed) width of a window.
        If not present, the alternate width will be the
        minimum width.

    SEE ALSO
        MUIA_Window_Width, MUIA_Window_AltHeight


MUIA_Window_AppWindow


    NAME
        MUIA_Window_AppWindow -- (V5 ) [I..], BOOL

    FUNCTION
        Setting this attribute to TRUE will make this window an
        AppWindow, the user will be able to drop icons on it.
        You can hear about these events by listening to the
        MUIA_AppMessage attribute.

    SEE ALSO
        MUIA_AppMessage, MUIA_Application_DropObject


MUIA_Window_Backdrop


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

    FUNCTION
        Make the window a backdrop window.


MUIA_Window_Borderless


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

    FUNCTION
        Make the window borderless.


MUIA_Window_CloseGadget


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

    FUNCTION
        Set this to FALSE and your window will not
        have a close gadget.


MUIA_Window_CloseRequest


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

    FUNCTION
        When the user hits a windows close gadget, the
        window isn't closed immediately. Instead MUI only
        sets this attribute to TRUE to allow your application
        to react.

        Usually, you will setup a notification that automatically
        closes the window when a close request appears, but you
        could e.g. pop up a confirmation requester or do some
        other things first.

    EXAMPLE
        /* automagically close a window     */
        /* when the close gadget is pressed */

        DoMethod(window,MUIM_Notify,
           MUIA_Window_CloseRequest, TRUE,
           window,3,MUIM_Set,MUIA_Window_Open,0);

    SEE ALSO
        MUIA_Window_Open


MUIA_Window_DefaultObject


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

    FUNCTION
        The default object in a window receives keyboard input
        as long as no other object is active. Good candidates
        for default objects are e.g. lonely listviews. Making
        such a listview the default object will allow the user
        to control it immediately without the need of several
        tab strokes for activation.

    SEE ALSO
        MUIA_Window_ActiveObject


MUIA_Window_DepthGadget


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

    FUNCTION
        Enable or disable the depth gadget. Defaults to TRUE.
        There is no good reason to use this tag.


MUIA_Window_DisableKeys


    NAME
        MUIA_Window_DisableKeys -- (V15) [ISG], ULONG

    FUNCTION
        yet undocumented, please complain in mailing list :)

    BUGS

    SEE ALSO


MUIA_Window_DragBar


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

    FUNCTION
        Tell MUI to give your window a dragbar.

        Defaults to TRUE.

        There is no good reason to disable the dragbar!


MUIA_Window_FancyDrawing


    NAME
        MUIA_Window_FancyDrawing -- (V8 ) [ISG], BOOL

    FUNCTION
        OBSOLETE!

        This attribute used to allow a more relaxed way of
        drawing for custom classes. This behaviour is
        discouraged, the attribute is obsolete. The only
        place where a class is allowed to draw something is
        the MUIM_Draw method. Setting a few flags and calling
        MUI_Redraw() on your object is no major performance
        loss.

    OLD AND OBSOLETE DOCUMENTATION
        Usually, the only possible place to do some rendering is
        during a MUIM_Draw method. However, if you have a class
        that really requires very high graphical output speed
        (e.g. a module players scope or a game class), you can
        set MUIA_Window_FancyDrawing to TRUE.

        This allows your class to render anywhere between
        MUIM_Show and MUIM_Hide, e.g. directly after an
        attribute change with OM_SET or from a seperate
        task.

        Note that your rastport etc. is only valid between
        MUIM_Show and MUIM_Hide. Keep that in mind!

        When drawing from a seperate task, you have to clone
        the RastPort and use the copy for your rendering!

        Please use this attribute sparingly. It might prevent
        MUI from doing nice things with your window, e.g.
        building an automatic virtual group when the screen
        is too small.

        MUIA_Window_FancyDrawing is really only necessary for
        very few types of applications. You should use the
        traditional way (MUIM_Draw and MUI_Redraw()) whenever
        and wherever possible!


MUIA_Window_Height


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

    SPECIAL INPUTS
        MUIV_Window_Height_MinMax(p)
        MUIV_Window_Height_Visible(p)
        MUIV_Window_Height_Screen(p)
        MUIV_Window_Height_Scaled
        MUIV_Window_Height_Default

    FUNCTION
        Specify the height of a window. Usually, you won't give
        a pixel value here but instead use one of the following
        magic macros:

        MUIV_Window_Height_Default:
           calculated from objects default sizes.

        MUIV_Window_Height_MinMax(0..100):
           somewhere between the minimum height (0) and the
           maximum height (100) of your window.

        MUIV_Window_Height_Visible(1..100):
           percentage of the screens visible height.

        MUIV_Window_Height_Screen(1..100):
           percentage of the screens total height.

        MUIV_Window_Height_Scaled:
           height will be adjusted so that
           width : height == minimum width : minimum height.
           Note that a windows width and height may not
           both be scaled.

        Default for this tag is MUIV_Window_Height_Default.

        As long as your window has a window id (MUIA_Window_ID),
        choosing a size is not that important. MUI will always
        remember a windows last position and size and these
        values will simply override your settings. Positioning
        and sizing should be completely under user control,
        a programmer doesn't need to worry about it.

    SEE ALSO
        MUIA_Window_Width, MUIA_Window_ID


MUIA_Window_ID


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

    FUNCTIONS
        For most of your windows, you should define a longword
        as id value. Only a window with an id is able to
        remember its size and position.

        Additionally, when you use an ascii id (e.g. 'MAIN'),
        your window can be controlled from ARexx.

        Of course all windows of your application must have
        unique ids.

    SEE ALSO
        MUIA_Window_LeftEdge, MUIM_Window_Snapshot


MUIA_Window_InputEvent


    NAME
        MUIA_Window_InputEvent -- (V4 ) [..G], struct InputEvent *

    FUNCTION
        This attribute gets set whenever your window receives
        an input event. You can react on this by creating
        a notification event containing a standard
        commodities.library input description string.

        Due to performance reasons, only IDCMP_RAWKEY,
        IDCMP_DISKINSERTED and IDCMP_DISKREMOVED events
        are translated to a MUIA_Window_InputEvent
        notification.

        Prior to MUI 3.0, the input description string needed
        to remain valid as long as the notification lasts. MUI 3.0
        converts the string to a struct IX immediately, speeding
        up the comparision and eliminating the need to keep
        the description strings allocated.

    NOTE
        Notification on MUIA_Window_InputEvent is inefficient.
        You should only use this notification for a few keyboard events
        that are "general" to the window, e.g. F-Keys for certain
        program actions. Keyboard control for single user interface
        elements should be implemented by using subclasses and
        requesting rawkey input events from there.

    EXAMPLE
        DoMethod(window, MUIM_Notify,
           MUIA_Window_InputEvent, "-repeat f1",
           txobj, 3,
           MUIM_Set, MUIA_Text_Contents, "f1 pressed/repeated");


MUIA_Window_IsSubWindow


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

    FUNCTION
        Windows with this flag set to TRUE dont get disposed
        when the application object is disposed. You should set
        this if your window belongs to an object placed in another
        window (e.g. popup windows) and you want to dispose the
        window object yourself during the OM_DISPOSE method
        of the parent object.


MUIA_Window_LeftEdge


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

    SPECIAL INPUTS
        MUIV_Window_LeftEdge_Centered
        MUIV_Window_LeftEdge_Moused

    FUNCTION
        Specify the left edge of a window. Usually, you shouldn't
        define a pixel value here but instead use one of the
        following macros:

        MUIV_Window_LeftEdge_Centered:
           window appears centered on the visible area of screen.

        MUIV_Window_LeftEdge_Moused
           window appears centered under the mouse pointer.

        Default for this tag is MUIV_Window_LeftEdge_Centered.

        As long as your window has a window id (MUIA_Window_ID),
        choosing a position is not that important. MUI will always
        remember a windows last position and size and these
        values will simply override your settings. Positioning
        and sizing should be completely under user control,
        a programmer doesn't need to worry about it.

    SEE ALSO
        MUIA_Window_TopEdge, MUIA_Window_ID


MUIA_Window_Menu


    NAME
        MUIA_Window_Menu -- (V4 ) [I..], struct NewMenu * (OBSOLETE)

    SPECIAL INPUTS
        MUIV_Window_Menu_NoMenu

    FUNCTION
        Obsolete, use MUIA_Window_Menustrip instead.

    SEE ALSO
        MUIA_Window_Menustrip


MUIA_Window_MenuAction


    NAME
        MUIA_Window_MenuAction -- (V8 ) [ISG], ULONG

    FUNCTION
        Whenever a menu item is selected, this attribute will be
        set to the corresponding UserData field of the gadtools
        NewMenu structure. This allows reacting on menu items
        via broadcasting.

    SEE ALSO
        MUIA_Window_Menu


MUIA_Window_Menustrip


    NAME
        MUIA_Window_Menustrip -- (V8 ) [I.G], Object *

    FUNCTION
        Specify a menu strip object for this window. The object
        is treated as a child of the window and will be disposed
        when the window is disposed.

        Menustrip objects defined for a window will override an
        applications Menustrip object.

        MUIA_Window_Menustrip replaces the old and obsolete
        MUIA_Window_Menu tag.

        Usually, you will create the menu object with MUI's builtin
        object library from a gadtools NewMenu structure, but its
        also OK to define the menu tree "by hand" using the
        Family class.

        If you have a global menu for all your applications windows
        but you want some windows to have no menu, use the
        MUIA_Window_NoMenus tag.

    SEE ALSO
        MUIA_Window_NoMenus


MUIA_Window_MouseObject


    NAME
        MUIA_Window_MouseObject -- (V10) [..G], Object *

    FUNCTION
        When MUIA_Window_NeedsMouseObject is enabled for this window,
        you can setup notificationns on MUIA_Window_MouseObject to
        find out on which object the mouse pointer is located.

    SEE ALSO
        MUIA_Window_NeedsMouseObject


MUIA_Window_NeedsMouseObject


    NAME
        MUIA_Window_NeedsMouseObject -- (V10) [I..], BOOL

    FUNCTION
        If you want to react on changes of the MUIA_Window_MouseObject
        attribute, you have to set this to TRUE when creating your
        window.

    SEE ALSO
        MUIA_Window_MouseObject


MUIA_Window_NoMenus


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

    FUNCTION
        Temporarily disable the menu strip of a window.

    SEE ALSO
        MUIA_Window_Menu


MUIA_Window_Open


    NAME
        MUIA_Window_Open -- (V4 ) [.SG], BOOL

    FUNCTION
        This little attribute can be used to open and close
        a window. When opening a window, MUI does lots of
        stuff to calculate sizes and positions of all
        gadgets. Minimum and maximum window sizes will be
        adjusted automatically.

        When the minimum size of a window is too big to fit
        on the screen, MUI tries to reduce font sizes and
        does a new calculation. You should always design
        your windows to fit on a 640*200 screen with
        all fonts set to topaz/8.

        When a window is closed (and you specified a
        MUIA_Window_ID), MUI remembers its position
        and size and uses these values during the next
        opening.

        After setting MUIA_Window_Open to TRUE, you should
        test if MUI was able to open the window by getting
        the attribute again. If you don't and if this was
        the only window of your application, the user won't
        be able to do any input and your application will
        seem to hang.

    EXAMPLE
        set(window,MUIA_Window_Open,TRUE);
        get(window,MUIA_Window_Open,&open);
        if (!open)
        {
           MUI_Request(app,0,0,0,"Ok","Failed to open window.");
           exit(20);
        }

    SEE ALSO
        MUIA_Window_RootObject


MUIA_Window_PublicScreen


    NAME
        MUIA_Window_PublicScreen -- (V6 ) [ISG], STRPTR

    FUNCTION
        Force the window to appear on the public screen who's name
        is specified by this attribute. This tag overrides the
        user preferences setting and is overridden by
        MUIA_Window_Screen.

        Please use this tag sparely, overriding user prefs is
        not a good idea!

    SEE ALSO
        MUIA_Window_Screen


MUIA_Window_RefWindow


    NAME
        MUIA_Window_RefWindow -- (V4 ) [IS.], Object *

    FUNCTION
        Setting MUIA_Window_RefWindow to another MUI window
        object will make the left and top position relative
        to this reference window. Using
        MUIA_Window_LeftEdge, MUIV_Window_LeftEdge_Centered or
        MUIA_Window_TopEdge, MUIV_Window_TopEdge_Centered tag,
        you can easily open one window within another.

        Note that if your window has an id, the window will
        remember its last position and reopen there. Thus,
        this tag is only useful if you omit MUIA_Window_ID,
        maybe for some small requester windows.

    SEE ALSO
        MUIA_Window_ID, MUIA_Window_LeftEdge


MUIA_Window_RootObject


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

    FUNCTION
        This is a pointer to a MUI object and defines the
        contents of your window. Usually, this root object
        will be of class MUIC_Group since you surely want to
        have more than one gadget.

        The root object is treated as child of a window
        and will be disposed when the window is disposed.
        Note that windows can only have one child.

    NOTES
        Although you may create a window without root object,
        you have to set one before the window is openend!

        You can *only* use MUIA_Window_RootObject in a SetAttrs()
        call if your window is not open yet!

    EXAMPLE
        win = WindowObject, MUIA_Window_RootObject,
           VGroup,
              Child, ...,
              Child, ...,
              End,
           End;

    SEE ALSO
        MUIA_Window_Open


MUIA_Window_Screen


    NAME
        MUIA_Window_Screen -- (V4 ) [ISG], struct Screen *

    FUNCTION
        You can get a pointer to the parent screen of a window by 
        getting this attribute. The result will be NULL when the
        window is currently closed.

        Specifying MUIA_Window_Screen at object creation time or
        with a SetAttrs() call allows you to explicitly tell MUI
        on which screen the window should be opened. You normally
        won't need this feature and leave the decision about
        screens to the users preferences setting.

    SEE ALSO
        MUIA_Window_PublicScreen, MUIA_Window_Window


MUIA_Window_ScreenTitle


    NAME
        MUIA_Window_ScreenTitle -- (V5 ) [ISG], STRPTR

    FUNCTION
        This text will appear in the screens title bar
        when the window is active.

    SEE ALSO
        MUIA_Window_Title


MUIA_Window_SizeGadget


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

    FUNCTION
        Tell MUI if you want a sizing gadget for this window.
        Usually you won't need this attribute since MUI
        will automatically disable the sizing gadget when
        your window is not sizeable because of your gadget
        layout.


MUIA_Window_SizeRight


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

    FUNCTION
        When set to TRUE, the size gadget will reside
        in the right window border.


MUIA_Window_Sleep


    NAME
        MUIA_Window_Sleep -- (V4 ) [.SG], BOOL

    FUNCTION
        This attribute can be used to put a window to sleep.
        The window gets disabled and a busy pointer appears.

        The attribute contains a nesting count, if you tell
        your window to sleep twice, you will have to tell
        it to wake up twice too.

        A sleeping window cannot be resized.

    SEE ALSO
        MUIA_Application_Sleep


MUIA_Window_Title


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

    FUNCTION
        Specify the title of a window.

    SEE ALSO
        MUIA_Window_ScreenTitle


MUIA_Window_TopEdge


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

    SPECIAL INPUTS
        MUIV_Window_TopEdge_Centered
        MUIV_Window_TopEdge_Moused
        MUIV_Window_TopEdge_Delta(p)

    FUNCTION
        Specify the top edge of a window. Usually, you shouldn't
        define a pixel value here but instead use one of the
        following macros:

        MUIV_Window_TopEdge_Centered:
           window appears centered on the visible area of screen.

        MUIV_Window_TopEdge_Moused
           window appears centered under the mouse pointer.

        MUIV_Window_TopEdge_Delta(p)
           window appears p pixels below the screens title bar.

        Default for this tag is MUIV_Window_TopEdge_Centered.

        As long as your window has a window id (MUIA_Window_ID),
        choosing a position is not that important. MUI will always
        remember a windows last position and size and these
        values will simply override your settings. Positioning
        and sizing should be completely under user control,
        a programmer doesn't need to worry about it.

    SEE ALSO
        MUIA_Window_LeftEdge, MUIA_Window_ID


MUIA_Window_UseBottomBorderScroller


    NAME
        MUIA_Window_UseBottomBorderScroller -- (V13) [ISG], BOOL

    FUNCTION
        If set to TRUE, the window will feature a scrollbar in its
        bottom border. You must set this for the window object if
        any children are going to use this window border scroller,
        e.g. prop gadgets with the MUIA_Prop_UseWinBorder attribute.

    NOTES
        Obviously, scroll gadgets in window borders wont look good
        with borderless or non-resizable windows.

    SEE ALSO
        MUIA_Window_UseLeftBorderScroller, 
        MUIA_Window_UseRightBorderScroller
        Prop.mui/MUIA_Prop_UseWinBorder,
        Scrollgroup.mui/MUIA_Scrollgroup_UseWinBorder


MUIA_Window_UseLeftBorderScroller


    NAME
        MUIA_Window_UseLeftBorderScroller -- (V13) [ISG], BOOL

    FUNCTION
        If set to TRUE, the window will feature a scrollbar in its
        left border. You must set this for the window object if
        any children are going to use this window border scroller,
        e.g. prop gadgets with the MUIA_Prop_UseWinBorder attribute.

    NOTES
        Obviously, scroll gadgets in window borders wont look good
        with borderless or non-resizable windows.

    SEE ALSO
        MUIA_Window_UseBottomBorderScroller,
        MUIA_Window_UseRightBorderScroller
        Prop.mui/MUIA_Prop_UseWinBorder,
        Scrollgroup.mui/MUIA_Scrollgroup_UseWinBorder


MUIA_Window_UseRightBorderScroller


    NAME
        MUIA_Window_UseRightBorderScroller -- (V13) [ISG], BOOL

    FUNCTION
        If set to TRUE, the window will feature a scrollbar in its
        right border. You must set this for the window object if
        any children are going to use this window border scroller,
        e.g. prop gadgets with the MUIA_Prop_UseWinBorder attribute.

    NOTES
        Obviously, scroll gadgets in window borders wont look good
        with borderless or non-resizable windows.

    SEE ALSO
        MUIA_Window_UseLeftBorderScroller,
        MUIA_Window_UseBottomBorderScroller
        Prop.mui/MUIA_Prop_UseWinBorder,
        Scrollgroup.mui/MUIA_Scrollgroup_UseWinBorder


MUIA_Window_Width


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

    SPECIAL INPUTS
        MUIV_Window_Width_MinMax(p)
        MUIV_Window_Width_Visible(p)
        MUIV_Window_Width_Screen(p)
        MUIV_Window_Width_Scaled
        MUIV_Window_Width_Default

    FUNCTION
        Specify the width of a window. Usually, you won't give
        a pixel value here but instead use one of the following
        magic macros:

        MUIV_Window_Width_Default:
           calculated from objects default sizes.

        MUIV_Window_Width_MinMax(0..100):
           somewhere between the minimum width (0) and the
           maximum width (100) of your window.

        MUIV_Window_Width_Visible(1..100):
           percentage of the screens visible width.

        MUIV_Window_Width_Screen(1..100):
           percentage of the screens total width.

        MUIV_Window_Width_Scaled:
           width will be adjusted so that
           width : height == minimum width : minimum height.
           Note that a windows width and height may not
           both be scaled.

        Default for this tag is MUIV_Window_Width_Default.

        As long as your window has a window id (MUIA_Window_ID),
        choosing a size is not that important. MUI will always
        remember a windows last position and size and these
        values will simply override your settings. Positioning
        and sizing should be completely under user control,
        a programmer doesn't need to worry about it.

    SEE ALSO
        MUIA_Window_Height, MUIA_Window_ID


MUIA_Window_Window


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

    FUNCTION
        When your window is open, you can obtain a pointer
        to the intuition Window structure with this tag
        and use it e.g. in an asl.library requester call.

        Since the user can close your window any time
        (e.g. iconification), you must be prepared to
        receive a NULL pointer as result.

    SEE ALSO
        MUIA_Window_Screen


MUIM_Window_AddEventHandler


    NAME
        MUIM_Window_AddEventHandler (V16)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_AddEventHandler,struct MUI_EventHandlerNode *ehnode);

    FUNCTION
        Event handlers introduced in muimaster.library V16 offer a
        new way for custom classes to receive user input. They work
        a little like the previously introduced input handlers
        (MUIM_Application_AddInputHandler). You fill out a struct
        MUI_EventHandlerNode (preferably located somewhere in the
        instance data of your custom class) with the type of events
        you wish to receive and then call MUIM_Window_AddEventHandler
        to add your node to a windows event handler queue.

        Whenever an input event arrives, MUIs window class iterates
        through the list of event handlers. The class of the input
        event is matched against the event handlers class field and
        in case of a match, the method MUIM_HandleEvent is invoked on
        the specified object.

        Each event handler may decide to "eat" the input event, this
        means window class will abort iterating the handler queue
        after calling this handler.

        MUI follows certain priority rules when iterating through
        the handler queue of a window. If there are handler entries
        for the active object (MUIA_Window_ActiveObject) or for the
        default object (MUIA_Window_DefaultObject), their nodes are
        checked before all other nodes. Active objects are checked
        before default objects. If there was no active and no
        default object or if none of them ate the event, the rest
        of the handler queue is checked according to their
        ehn_Priority field.

        A good place to add/remove event handlers is the
        MUIM_Setup/MUIM_Cleanup method pair of your custom class.

        If you wish to change certain fields (e.g. ehn_Events)
        in an active handler (one that is currently added to a
        windows), you must deactivate (remove) the handler, make 
        your changes and then add it again. Do not change fields
        of an active handler without removing it first!

    INPUTS
        Pointer to an initialized struct MUI_EventHandler node:

        ehn_Priority - event handlers are inserted according to their
                       priority. 0 is fine in almost all cases.

        ehn_Flags    - no flags are defined yet. Always use 0 here!

        ehn_Events   - Exclusive OR of all IDCMP_* flags you want this
                       handler to react on.

        ehn_Object   - insert a pointer to yourself here.

        ehn_Class    - if you point this to your class, MUI will invoke
                       MUIM_HandleEvent with CoerceMethod(ehn_Class,...)
                       instead as with DoMethod(obj,...). This will bypass
                       any subclasses you might have and directly hand
                       the input event to the dispatcher. If you dont
                       set ehn_Class, MUIM_HandleEvent is sent like any
                       other method to the true class of your object.

                       Since every class should add a handler itself
                       if it needs some input, MUIM_HandleEvent methods
                       are different from other MUI methods which usually
                       travel from class to class in an objects class
                       tree. MUIM_HandleEvent is more treated like a
                       hook function instead of a method: in almost all
                       cases you will want it to be passed directly to
                       a specific class dispatcher (by setting ehn_Class).
                       Also, this dispatcher will usually not pass the
                       method to its super class but instead return
                       directly.

    RESULT
        MUIM_Window_AddEventHandler cannot fail, the result
        value of the method is currently undefined.

    NOTES
        Event handlers are more flexible and more efficient than the
        pre-V16 functions MUI_RequestIDCMP() and MUI_RejectIDCMP().
        Also, event handlers dont suffer from problems that arise if
        more than one class of an object calls MUI_RequestIDCMP().
        Though the old functions will remain working for
        compatibility reasons, it's suggested that only event
        handlers are used in new code.

        You must match each MUIM_Window_AddEventHandler with
        exactly one MUIM_Window_RemEventHandler method.

    EXAMPLE
        MUIM_Setup:
           data->ehnode.ehn_Object = obj;
           data->ehnode.ehn_Class  = cl;
           data->ehnode.ehn_Events = IDCMP_MOUSEBUTTONS;
           DoMethod(_win(obj),MUIM_Window_AddEventHandler,&data->ehnode);

        MUIM_Cleanup:
           DoMethod(_win(obj),MUIM_Window_RemEventHandler,&data->ehnode);

        Changing the trigger events of an active handler:
           DoMethod(_win(obj),MUIM_Window_RemEventHandler,&data->ehnode);
           data->ehnode.ehn_Events |= IDCMP_MOUSEMOVE;
           DoMethod(_win(obj),MUIM_Window_AddEventHandler,&data->ehnode);

        More examples can be found in the MUI demo source codes that
        deal with custom classes.

    SEE ALSO
        MUIM_Window_RemEventHandler, MUIM_HandleEvent


MUIM_Window_Cleanup


    NAME
        MUIM_Window_Cleanup (V18)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_Cleanup);

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

    INPUTS

    RESULT

    BUGS

    SEE ALSO


MUIM_Window_GetMenuCheck


    NAME
        MUIM_Window_GetMenuCheck (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_GetMenuCheck,ULONG MenuID);

    FUNCTION
        Ask whether a checkmark menu item has its
        checkmark set or cleared.

    INPUTS
        MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    SEE ALSO
        MUIM_Window_SetMenuCheck, MUIA_Window_Menu


MUIM_Window_GetMenuState


    NAME
        MUIM_Window_GetMenuState (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_GetMenuState,ULONG MenuID);

    FUNCTION
        Ask whether a menu item is enabled or disabled.

    INPUTS
        MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

    SEE ALSO
        MUIM_Window_SetMenuState, MUIA_Window_Menu


MUIM_Window_RemEventHandler


    NAME
        MUIM_Window_RemEventHandler (V16)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_RemEventHandler,struct MUI_EventHandlerNode *ehnode);

    FUNCTION
        Remove an event handler.

    RESULT
        MUIM_Window_RemEventHandler cannot fail, the result
        value of the method is currently undefined.

    INPUTS
        ehnode - event handler node structure you passed to
                 MUIM_Window_AddEventHandler previously.

    NOTES
        Every call to MUIM_Window_AddEventHandler must be matched
        by exactly one call to MUIM_Window_RemEventHandler.

    SEE ALSO
        MUIM_Window_RemEventHandler, MUIM_HandleEvent


MUIM_Window_ScreenToBack


    NAME
        MUIM_Window_ScreenToBack (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_Window_ScreenToBack);

    FUNCTION
        Put the window's screen to back. This command is
        only valid when the window is opened.

    SEE ALSO
        MUIM_Window_ScreenToFront, MUIM_Window_ToFront,
        MUIM_Window_ToBack


MUIM_Window_ScreenToFront


    NAME
        MUIM_Window_ScreenToFront (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_Window_ScreenToFront);

    FUNCTION
        Put the window's screen to font. This command is
        only valid when the window is opened.

    SEE ALSO
        MUIM_Window_ScreenToBack, MUIM_Window_ToFront,
        MUIM_Window_ToBack


MUIM_Window_SetCycleChain


    NAME
        MUIM_Window_SetCycleChain (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_SetCycleChain,Object *obj[1]);

    FUNCTION
        Set the cycle chain for a window. To make MUI's keyboard
        control work, you need to setup a chain of objects that
        should be activatable with the tab key. This can be
        any objects you wish, MUI supports complete keyboard
        handling even for sliders or listviews.

        If you forget to set a cycle chain because you
        are a mouse-man, you certainly will annoy some
        users of your application!

    INPUTS
        One or more objects, terminated with a NULL.

    EXAMPLE
        DoMethod(window,MUIM_Window_SetCycleChain,
           str1,str2,slide1,list,radio,cycle1,cycle2,NULL);

    SEE ALSO
        MUIA_Window_ActiveObject, Area.mui/MUIA_CycleChain


MUIM_Window_SetMenuCheck


    NAME
        MUIM_Window_SetMenuCheck (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_SetMenuCheck,ULONG MenuID, LONG stat);

    FUNCTION
        Set or clear the checkmark of a menu item.

    INPUTS
        MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

        set    - TRUE to set checkmark, FALSE to clear

    SEE ALSO
        MUIM_Window_GetMenuCheck, MUIA_Window_Menu,


MUIM_Window_SetMenuState


    NAME
        MUIM_Window_SetMenuState (V4 ) (OBSOLETE)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_SetMenuState,ULONG MenuID, LONG stat);

    FUNCTION
        Enable or disable a menu item.

    INPUTS
        MenuID - the value you wrote into the
                 UserData field of struct NewMenu.

        set    - TRUE to enable item, FALSE to disable.

    SEE ALSO
        MUIM_Window_GetMenuState, MUIA_Window_Menu,


MUIM_Window_Setup


    NAME
        MUIM_Window_Setup (V18)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_Setup);

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

    INPUTS

    RESULT

    BUGS

    SEE ALSO


MUIM_Window_Snapshot


    NAME
        MUIM_Window_Snapshot (V11)

    SYNOPSIS
        DoMethod(obj,MUIM_Window_Snapshot,LONG flags);

    FUNCTION
        MUIM_Window_Snapshot is the programmer's interface to MUI's
        window position remembering facility.

    NOTES
        Snapshotting a window is only possible if it has a
        non-NULL MUIA_Window_ID.

    INPUTS
        flags - use 0 to unsnapshot the window.
                This is equal to the user doubleclicking
                on the window's snapshot gadget.

              - use 1 to snapshot the window.
                This is equal to the user clicking
                on the window's snapshot gadget.

    SEE ALSO
        MUIA_Window_ID


MUIM_Window_ToBack


    NAME
        MUIM_Window_ToBack (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_Window_ToBack);

    FUNCTION
        Put the window to back. When the window is not currently open,
        this command does simply nothing.

    SEE ALSO
        MUIM_Window_ToFront, MUIM_Window_ScreenToFront,
        MUIM_Window_ScreenToBack


MUIM_Window_ToFront


    NAME
        MUIM_Window_ToFront (V4 )

    SYNOPSIS
        DoMethod(obj,MUIM_Window_ToFront);

    FUNCTION
        Put the window to front. When the window is not currently open,
        this command does simply nothing.

    SEE ALSO
        MUIM_Window_ToBack, MUIM_Window_ScreenToFront,
        MUIM_Window_ScreenToBack





© 1998, Stefan Stuntz [MUI Homepage] [Autodoc Index] [Feedback] Updated: 22-Feb-98