window.class

WINDOW_GetClass	WM_CLOSE	WM_HANDLEINPUT	WM_ICONIFY	WM_NEWPREFS
WM_OPEN	WM_RETHINK

rootclass

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.

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) (see note below)
  
  
• WA_BusyPointer (NOTE: Disables Defer Refresh and opens an REQ to block input)
  
  
• WA_WindowBox
  
  
• WA_Hidden
  
  

Note about WA_IDCMP: when creating a new window, window.class will generally ask Intuition for any necessary IDCMP bits (eg. IDCMP_GADGETUP), even if you don't specify them. When setting this attribute for an existing window, this is not done for you. Therefore if you need to modify the IDCMP bits later, it is safest to use GetAttr() first and then modify the necessary bits, eg.:

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 clip

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 *)

same as

WINDOW_ParentLayout

same as

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. The maximum tooltip height is 20 lines of text from V48.12 onwards, and 10 lines on previous versions (and OS4). (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)