Amiga Developer CD 2.1

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / window_cl.doc < prev

Wrap

Text File | 1999-10-29 | 21.8 KB | 609 lines

TABLE OF CONTENTS window_cl/--datasheet-- window_cl/WINDOW_GetClass window_cl/WM_CLOSE window_cl/WM_HANDLEINPUT window_cl/WM_ICONIFY window_cl/WM_OPEN window_cl/--datasheet-- window_cl/--datasheet-- NAME window_cl -- create Intuition Window objects SUPERCLASS rootclass REQUIRES layout.gadget, drawlist.image DESCRIPTION This class creates standard Intuition Windows, and intelligently handles some ReAction house keeping for KeyBoard Control, Defer Layout processing, etc. Window class properly handles processing messages using shared window message ports as well as safely closing intuition windows. Window class will also intialize your window's parent layout group properly. All windowclass methods and the callback hooks you provide it are ran in the context of the task you call windowclass 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 windowclass will automatically choose 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 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 by window.class, 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 -- Locks default pub screen if needed, domains child layout group min/max size, opens window, attaches layout to window. WM_CLOSE -- Closes the intuition window, but does not dispose the layout group. WM_ICONIFY -- Create AppIcon, and invokes 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. WM_NEWPREFS -- Handles update and visual refresh of new preference settings. WM_RETHINK -- Re-evaluate layout requirements and adjust window size if needed in support of dynamicly changing layout groups.. eg, adding, replacing and removing objects. 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 You may set any of these at any time, NewObject() or SetAttrs(); WA_Top WA_Left WA_InnerWidth WA_InnerHeight WA_Width WA_Height WA_Title (NOTE: Calls SetWindowTitles() if the window is open) WA_IDCMP (NOTE: Calls ModifyIDCMP() if needed) WA_BusyPointer (NOTE: Creates/Removes a NULL requester) You may GetAttr() these at any time; WA_Top WA_Left WA_InnerWidth WA_Height WA_Width WA_InnerHeight WA_PubScreen WA_CustomScreen WA_Title WA_ScreenTitle WA_Zoom Note well, WA_InnerHeight, and WA_InnerWidth will be 0 unless previously set until the window has been opened atleast once. These values are not computed until the first window open. 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. See Also, WINDOW_RefWindow. WPOS_CENTERSCREEN - Center in visible screen clip. WPOS_CENTERMOUSE - Center under mouse. WPOS_TOPLEFT - Open Top/Left, just below screen bar. WPOS_CENTERWINDOW - Center in some other window. WPOS_FULLSCREEN - Open Top/Left, and fill the screen clip. If WINDOW_RefWindow is set, WPOS_CENTERSCREEN will center in the refwindow, not the screen. As of 42.42, WPOS_FULLSCREEN remains broken, window will open a minimum size. 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. Please note that currently windowclass detects the iconify gadget being pressed by using the gadget ID 0xfffe. Do not use this ID in your application. Defaults to FALSE. Applicability is (OM_NEW, OM_SET) WINDOW_BackFillName (STRPTR) Name for the custom backfill to use instead of global CAPrefs 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. WA_BusyPointer (BOOL) Set the window to a busy state. It will set busy pointer on the window. Setting the busy state will also clear the DeferLayout state, clearing the busy state restores the DeferLayout state to its last value. This is done since, its a logical assumption if the application is busy enough that a pointer change is waranted, then its probably busy to respond to defer requests in a timely fashion. Note, the window put to sleep creating a NULL requester. In prior versions of window class before V42.40, the layout group was set to readonly, and menu strip removed. 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(). Closing the window via CA_CloseWindow, will remove the menustrip before closing the window. Disposing the window does NOT free the menu strip. Defaults to NULL. Applicability is (OM_NEW, OM_SET) WINDOW_Window (struct Window *) Pointer to the Intuition Window, or NULL when the window is closed. Take care NOT to do a CloseWindow() or you will invalidate window.class's internal pointer and window states. 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. Defaults to ENV:Sys/def_window.info or the default project window. 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 *) Pointer to an Intuition window whose location will be the reference used for WINDOW_Position rather than the screen. Defaults to NULL. Applicability is (OM_NEW, OM_SET) WINDOW_InputEvent (struct InputEvent *) Pointer to an InputEvent structure which will be valid AFTER receiving a WHMI_RAWKEY return code from window class. This is a "fake" event, the structure is filled in based on the IntuiMessage and other data, and is suitable for calling MapRawKey(), infact this is how window class handles managing gadget keyboard control. Applicability is (OM_GET) window_cl/WINDOW_GetClass window_cl/WINDOW_GetClass NAME 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. window_cl/WM_CLOSE window_cl/WM_CLOSE NAME 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. window_cl/WM_HANDLEINPUT window_cl/WM_HANDLEINPUT NAME 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. 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) 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. window_cl/WM_ICONIFY window_cl/WM_ICONIFY NAME 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. window_cl/WM_OPEN window_cl/WM_OPEN NAME WM_OPEN -- Open a 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. window_cl/WM_RETHINK window_cl/WM_RETHINK NAME WM_RETHINK -- Re-evaluate an open window's size requirement SYNOPSIS window = DoMethod( winobj, WM_RETHINK ); FUNCTION This function re-evaluates the layout group's minimum size and adjusts the window size to contain it if needed. RESULTS Non-Zero if implemented.