window.class Reference

Comprehensive function reference for window.class, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/window).

This page documents 8 functions of window.class. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

window_cl()

**window_cl -- create Intuition Window objects

SUPERCLASS
    rootclass

DESCRIPTION
    This class creates standard Intuition Windows, and intelligently
    handles some ReAction house keeping for KeyBoard Control, Defer
    Layout & Render processing, etc. The window class properly handles
    processing messages using shared window message ports as well as
    safely closing intuition windows. The window class will also
    initialize your window's parent layout group properly.

    All window class methods and the callback hooks you provide it are
    executed in the context of the task you call window class from.
    Thus if your application is a process, DOS is safe to use. However,
    remember the Intuition rules about DOS and IDCMP VERIFY messages.

    window.class requires layout.gadget.

WINDOW REFRESH
    Usually, when all the graphics in your window are handled by
    ReAction, you should not explicitly set the window refresh method
    to either smart or simple refresh. This is a user preference
    setting, and window class will automatically use it. However, if
    your program, for some reason, requires one or the other refresh
    method and can not use the other, set the refresh type in your
    window object creation taglist.

BACKFILL PATTERNS
    The window.class will install the default backfill pattern on any
    window for which you do not pass a pointer to a custom backfill
    hook. The pattern bitmaps are cached, minimizing memory usage.

    If your windows have elements that look bad or do not work with
    a backfill pattern, install the default NULL backfill to the
    layout group(s) containing them.

    The backfill installed by window.class is NOT a standard, global
    window layer backfill hook. It is in fact passed to each of the
    layout groups of the window, which will install it during
    refreshes. This approach was chosen because datatypes fail to
    render correctly if their background has been backfilled. This
    method has the side effect that a gadget that is not aware of
    ReAction's method to install a backfill will only have a
    backfill during window refresh (GM_RENDER coming through from
    the parent layout), not during GM_HANDLEINPUT. To make the
    class use the backfill during input handling, it should have
    GA_BackFill as a settable attribute, and install that
    backfill hook before erasing its imagery.

METHODS
    OM_NEW -- Passed to superclass first, defaults set, then OM_SET.

    OM_SET -- Passed to superclass first, then custom tags set.

    OM_GET -- Returns requested setting or passed to superclass

    OM_DISPOSE -- Child object disposed then passed to superclass.

    WM_OPEN -- Lock default pub screen if needed, domain child layout
        group min/max size, opens window, attaches layout to window.

    WM_CLOSE -- Closes the intuition window, but does not dispose
        the child object/layout group.

    WM_ICONIFY -- To iconify, puts Icon on WorkBench, and calls WM_CLOSE.

    WM_HANDLEINPUT -- Handles IDCMP input processing, defer layout
        refresh requests, and returns the item ID and Code of
        and selected gadget or menu attached to the window.
        Transparently handles keyboard control.

ATTRIBUTES
    The following standard Intuition Window Tags are supported;

    You may set these while the window is NOT open, at NewObject()
    time or SetAttrs() - between WM_CLOSE and WM_OPEN for example.

        WA_Flags
        WA_NoCareRefresh
        WA_SimpleRefresh
        WA_SmartRefresh
        WA_CloseGadget
        WA_DepthGadget
        WA_SizeGadget
        WA_SizeBRight
        WA_SizeBBottom
        WA_DragBar
        WA_GimmeZeroZero
        WA_Borderless
        WA_Activate
        WA_RMBTrap
        WA_Backdrop
        WA_SuperBitMap
        WA_BackFill
        WA_PubScreen
        WA_CustomScreen
        WA_HelpGroup
        WA_MenuHelp
        WA_Zoom
        WA_NotifyDepth
        WA_MenuHook
        WA_ToolBox

    You may set any of these at any time, NewObject() or SetAttrs();

        WA_Top
        WA_Left
        WA_Width (NOTE: Behaves like WA_InnerWidth)
        WA_Height (NOTE: Behaves like WA_InnerHeight)
        WA_InnerWidth
        WA_InnerHeight
        WA_Title (NOTE: Calls SetWindowTitles() if the window is open)
        WA_IDCMP (NOTE: Calls ModifyIDCMP() if needed)
        WA_BusyPointer (NOTE: Disables Defer Refresh and opens an REQ to

block input) WA_WindowBox WA_Hidden 

    You may GetAttr() these at any time;

        WA_Top
        WA_Left
        WA_InnerWidth
        WA_InnerHeight
        WA_Width
        WA_Height
        WA_PubScreen
        WA_CustomScreen
        WA_Title
        WA_ScreenTitle
        WA_Zoom
        WA_IDCMP

    These are the Window Class specific attributes.

    You may set these while the window is NOT open, at NewObject()
    time or SetAttrs() - between WM_CLOSE and WM_OPEN for example.

    WINDOW_Position (UWORD)
        Set the intial opening position of the window.

            WPOS_CENTERSCREEN - Center on screen
            WPOS_CENTERWINDOW - Center in another window
            WPOS_CENTERMOUSE  - Center under mouse
            WPOS_TOPLEFT      - Open Top/Left, just below screen bar
            WPOS_FULLSCREEN   - Open Top/Left, and fill visible screen cl

ip WPOS_ENTIRESCREEN - Open Top/Left, and fill the entire screen (even for autoscroll screens) (V47)

        Applicability is (OM_NEW, OM_SET)

    WINDOW_LockWidth (ULONG)
        If TRUE, lock the width of the window, ie, disallow
        resizing in this orientation.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_LockHeight (ULONG)
        If TRUE, lock the height of the window, ie, disallow
        resizing in this orientation.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_SharedPort (struct MsgPort *)
        Pointer to a custom UserPort this window should share.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET, OM_GET)

    WINDOW_AppPort (struct MsgPort *)
        Pointer to a MsgPort this window should use for AppMessages.
        By passing this tag the window turns into an AppWindow and
        you can use the WM_ICONIFY method. WindowClass must use the
        ID field of the AppMessages to identify the window to which
        the message was intended. You can use the UserData field
        yourself.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_AppWindow (BOOL)
        By providing an AppPort and setting this to TRUE, the window
        will be made a Workbench AppWindow. If you don't set this
        attribute, the AppPort will only be used to support
        iconification.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_IconifyGadget (BOOL)
        Set to TRUE to add an iconification gadget to the window
        titlebar.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_BackFillName (STRPTR)
        Name for the custom backfill to use instead of global prefs
        backfill. If you use this tag, make it a user preference.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    It is legal and safe to set any of these at any time, OM_NEW or
    OM_SET regardless of of the window being open or not, if
    not applicable, the setting will be ignored, or acted on as soon
    as the window opens again...

    WA_BusyPointer (BOOL)
        Set the window to a busy state. If the window is currently
        open, or when is does get opened, the busy pointer is
        set, and a NULL requester is opened to block menu, gadget
        and keyboard input to the parent window.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_Layout (Object *)
    WINDOW_ParentLayout
    WINDOW_ParentGroup
        Pointer to the parent level layout group object which
        will be added to the window.

        Note the tag has 2 aliased definitions which are now
        obsolete but still supported in the include files.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_Zoom (BOOL)
        Cause the window to to be zipped via ZipWindow().

        Applicability is (OM_NEW, OM_SET)

    WINDOW_FrontBack (BOOL)
        Changes window depth arrangement via WindowToFront() or
        WindowToBack(). Accepted settings;

            WT_FRONT - bring window to front.
            WT_BACK  - put window to back

        Applicability is (OM_NEW, OM_SET)

    WINDOW_UserData (APTR)
        Pointer to your user data. Take note, this is *NOT* the
        same pointer as the Intuition Window's UserData.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET, OM_GET)

    WINDOW_GadgetUserData (UWORD)
        Determines how a gadget's UserData should be interpreted.
        If the userdata is non-null, and this setting is not
        WGUD_IGNORE, then the (hook) function will be called
        when the gadget is selected.

        A function gets the hook's "object" argument in a0 and the
        "message" argument in a1.

        Possible values are;

            WGUD_HOOK   - UserData is hook pointer (struct Hook *).
            WGUD_FUNC   - UserData is a pointer to function.
            WGUD_IGNORE - Ignore UserData.

        Defaults to WGUD_IGNORE.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_MenuUserData (UWORD)
        Like the WINDOW_GadgetUserData tag, but for menus. Using
        this implies that WINDOW_MenuStrip has been created with
        GadTools or otherwise has a 32 bit UserData field after
        each menuitem.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_MenuStrip (struct Menu *)
        Pointer to a menu to add to window with SetMenuStrip().

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_NewMenu (struct NewMenu *) (V47)
        Let window.class create and layout the menus for you.
        This is useful for iconification and screenchanges.
        Remember that the NewMenu array must be persistent
        because it will be referenced every time the window opens.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE)

    WINDOW_Window (struct Window *)
        Pointer to the Intuition Window, or NULL when the
        window is closed. Be sure NOT to use this pointer after
        closing or iconifying a window, and if needed, re-get
        the pointer after de-iconify.

        Applicability is (OM_GET)

    WINDOW_SigMask (ULONG)
        Window signal bit mask.

        Applicability is (OM_GET)

    WINDOW_IconTitle (STRPTR)
        The title of the icon when the window is iconified.

        Defaults to window title.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE)

    WINDOW_Icon (struct DiskObject *)
        The icon to use when iconifying. The icon will be disposed
        of along with the window unless the WINDOW_IconNoDispose
        attribute has been set to TRUE.

        Defaults to ENV:Sys/def_window.info or the default project
        window.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE)

    WINDOW_IconNoDispose (BOOL) (V47)
        Set to TRUE to prevent the DiskObject pointed to by the
        WINDOW_Icon tag from being automatically disposed of.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE)

    WINDOW_GadgetHelp (BOOL)
        Set to TRUE to enabled gadget help processing.

        Defaults to FALSE.

        Applicability is (OM_NEW, OM_SET, OM_UPDATE)

    WINDOW_IDCMPHook (struct Hook *)
        Pointer to a Hook that should be called for IDCMP messages.
        When the hook is called, the data argument points to the
        window object and message argument to the IntuiMessage.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_IDCMPHookBits (ULONG)
        If WINDOW_IDCMPHook is set, it will be called for IDCMP
        messages matching this bit mask.

        Defaults to 0L.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_AppMsgHook (struct Hook *)
        Pointer to a hook that should be called for AppMessages.
        When this called, the function data argument will point to
        the window object and data argument to the AppMessage.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_RefWindow (struct Window *)
        This causes WINDOW_Position to be relative to the specified
        window vs the screen. Note this is a Window pointer, NOT a
        window Object pointer. After deiconifiction or any other
        close/open this tag MUST be reset BEFORE trying to open
        this window. IE, each window reference, must be to a valid
        currently OPEN window, and must be set before opening THIS
        window. (V42)

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_InputEvent (struct IEvent *)
        Pointer to a 'fake' input event which is valid *ONLY* immediatly
        after receiving WHMI_RAWKEY. This provided the additional
        information suitable for you to call MapRawKey(). (V42)

        Defaults to NULL.

        Applicability is (OM_GET)

    WINDOW_AppWindowPtr (struct AppWindow *)
        Contains the result of the AddAppWindow() call which is
        used when iconifying the window.

        Applicability is (OM_GET)

    WINDOW_Qualifier (UWORD)
        Current qualifiers from the IntuiMessage.Qualifier field.
        Useful for obtaining the qualifiers after WM_HANDLEINPUT
        has returned. (V47)

        Applicability is (OM_GET)

    WINDOW_HintInfo (struct HintInfo *)
        Pointer to a gadget HintInfo array. This is simular in concept
        to Apple's bubble help or Microsoft's help tips. By providing
        this array of helpinfo, and setting WINDOW_GadgetHelp, TRUE,
        window class will transparently manage the help hints. (V43)

        Defaults to NULL.

        Applicability is (OM_NET, OM_SET)

    WINDOW_PreRefreshHook (struct Hook *)
        When ever the window needs to refresh, this hook will be invoked
        AFTER the gadgets are refreshed. It will be called inside a
        BeginRefresh() and EndRefresh() pair for simple refresh repair.
        It may also be invoked when a preferences change occurs.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)

    WINDOW_PostRefreshHook (struct Hook *)
        When ever the window needs to refresh, this hook will be invoked
        BEFORE the gadgets are refreshed. It will be called inside a
        BeginRefresh() and EndRefresh() pair for simple refresh repair.
        It may also be invoked when a preferences change occurs.

        Defaults to NULL.

        Applicability is (OM_NEW, OM_SET)**

WINDOW_GetClass()

WINDOW_GetClass -- Gets the pointer to the checkbox class.

Synopsis

window_class = WINDOW_GetClass();
D0

Class * WINDOW_GetClass(VOID);

Function

   This function is only available in runtime linked version of the
   class, window.class and is not in the compiler linker library
   window_cl.lib.

   Obtains the pointer to the Window class for use with NewObject().
   This function always returns a valid pointer so you do not
   need to check it.  The reason is that if the library opens
   fine, then the pointer returned is already setup.  (Of course
   this implies that if opening the library fails, you shouldn't be
   calling this.)

   Note that this function does not create the class, that is done
   when the class library is opened.

Inputs

   Nothing.

RESULT window_class - Pointer to the window class.

WM_CLOSE()

WM_CLOSE -- Close a window

Synopsis

DoMethod( winobj, WM_CLOSE );

Function

Close the window of this object. The gadgets are not disposed, only detached of a window. If the window is sharing a message port with another window, the port will be cleaned of message intended for this window. If the window was iconified, the icon will be removed.

WM_HANDLEINPUT()

WM_HANDLEINPUT -- IDCMP input handling method

Synopsis

result = DoMethod( winobj, WM_HANDLEINPUT, &code );

Function

This method is used to handle the IDCMP input of a window. Call this method when the signal bit of the window's UserPort is set. This method will return when it encounters a message that requires notifying your application or when the message port no longer contains messages for the window.

In most cases you will have to also have to request the appropriate IDCMP flags via the WA_IDCMP tag, or you will not hear the WMHI_#? events.

The return value is two-part. The upper word describes the class of the event the value represents, and the lower word is a modifier that describes the event.

Defined class return codes are:

WMHI_IGNORE Ignore this event WMHI_LASTMSG No more messages WMHI_CLOSEWINDOW Close gadget hit WMHI_GADGETUP Gadget hit. WMHI_INACTIVE Window went inactive. WMHI_ACTIVE Window was activated. WMHI_NEWSIZE Window was resized. WMHI_MENUPICK A menu item was selected. WMHI_MENUHELP Help was pressed in a menu. WMHI_GADGETHELP A gadget sends a help message. WMHI_ICONIFY Window should be iconified. WMHI_UNICONIFY Window was deiconified. WMHI_RAWKEY Raw key code WMHI_VANILLAKEY Vanilla key code WMHI_CHANGEWINDOW Window moved (or depth arranged) WMHI_INTUITICKS IDCMP IntuitiTick message WMHI_MOUSEMOVE IDCMP MouseMove message WMHI_MOUSEBUTTONS IDCMP MouseButtons message

The value of the lower word is defined for WMHI_GADGETUP and WMHI_GADGETHELP as the ID of the gadget, and for WMHI_MENUPICK and WMHI_MENUHELP as the menu code. WMHI_GAGDETHELP uses the special values 0 and WMHI_GADGETMASK as messages "pointer not over your window" and "pointer over your window but not over a gadget".

WMHI_RAWKEY returns the raw key ID of the key being pressed (to get the qualifiers also, you have to use the IDCMP hook), and WMHI_VANILLAKEY returns the ASCII value of the key. WMHI_VANILLAKEY is only returned when you set IDCMP_VANILLAKEY. Windowclass itself does not need vanilla key IDCMP.

WMHI_NEWSIZE returns some extra information in the low word: if WMF_ZOOMED is set, the window is now in zoomed state. If WMF_ZIPWINDOW is set, this resize was caused by either a click of the zoom gadget or a call to ZipWindow().

WMHI_CHANGEWINDOW is returned when the window is moved. For resizing of the window, listen to WMHI_NEWSIZE. By setting WA_NotifyDepth, this event will also be returned for depth arranging. The lower word contains CWCODE_DEPTH in this case.

WMHI_CLASSMASK masks the lower word of the result code out, while WMHI_GADGETMASK and WMHI_MENUMASK mask out the high word, leaving only the ID part of the result value.

A generic application side of WM_HANDLEINPUT looks like this:

GetAttr( WINDOW_SigMask, winobj, &wsig );

mask = Wait(wsig); // maybe other signals

if (mask & wsig) while ((result = DoMethod( winobj, WM_HANDLEINPUT, &code )) != WMHI_LASTMSG) switch (result & WMHI_CLASSMASK) { case WMHI_CLOSEWINDOW: close = TRUE; break;

    case WMHI_GADGETUP:
        switch (result & WMHI_GADGETMASK)
        {
        // handle the gadgets here
        }

    // handle whatever other events you want here
    }

if (close) DisposeObject( winobj ); // destroy the window

If you have set up the window to use a shared message port, you can simply call this method on each of the windows:

if (mask & wsig) { WmHandleInputWin1(); WmHandleInputWin2(); WmHandleInputWin3(); }

Inputs

code -- A pointer to a WORD that should be set to contain the Code value from the IntuiMessage.

Results

Windowclass will automatically respond with an appropriate action to many input events. When it does not know what to do with an event, it will return with a value as descibed above.

WM_ICONIFY()

WM_ICONIFY -- Hide this window to an icon

Synopsis

DoMethod( winobj, WM_ICONIFY );

Function

Close the window and put an icon on the Workbench for it.

WM_NEWPREFS()

WM_NEWPREFS -- Update window prefs and refresh window.

Synopsis

window = DoMethod( winobj, WM_NEWPREFS );

Function

Re-evaluate prefs settings, and relayout window.

Results

Returns non-zero if method is implemented and succeeds.

WM_OPEN()

WM_OPEN -- Open an intuition window.

Synopsis

window = DoMethod( winobj, WM_OPEN );

Function

This function opens the window the object should be handling. If the window is already open, it does nothing. If no shared message port is set, a message port will be created for this window.

Results

window -- a pointer to the struct Window for this window, or NULL if the window could not be opened.

WM_RETHINK()

WM_RETHINK -- Rethink an open window layout limits

Synopsis

window = DoMethod( winobj, WM_RETHINK );

Function

Re-evaluate layout limits, and relayout window.

Results

Returns non-zero if method is implemented and succeeds.