System support for floating windows was introduced with Mac OS 8.5; however, there were bugs in the window activation area which prevented programmers from utilising this inbuilt support. The bugs were eliminated in Mac OS 8.6. Chapter 4B - More on Windows - Mac OS 8.5 Window Manager and the associated demonstration program Windows2 describe and demonstrate system-supported floating windows.

If your application requires floating windows, and is required to run under Mac OS 8.5 or earlier, the application itself will have to provide the necessary support. Application support for floating windows is addressed in this chapter.

Front-To-Back Ordering of On-Screen Objects

• Help balloons.

• Menus.

• System windows.

  System windows are windows which can appear in an application's window list but which are not directly created by the application. These windows appear in front of all windows created by the application. An example of a system window is a notification alert box.

• Modal and movable modal dialog and alert boxes.

• Floating windows.

• Document windows and modeless dialog boxes.

In terms of front-to-back ordering, floating windows, unlike document windows, are all basically equal. Unless they actually overlap each other, there is no visual cue of any front-to-back ordering as there is with normal windows. Because of this equality, floating windows should almost always appear in the active state. The exception is when a modal or movable modal dialog or alert box is presented to the user. When this occurs, the appearance of all floating windows should be changed to reflect the inactive state. As a further refinement, the content of the window should be dimmed to further suggest to the user that the floating windows are irrelevant to operations within the dialog box or alert box.

Implementing Floating Windows - Considerations

The Single Active Window Problem. The Window Manager was written on the assumption that there is only ever one active window. However, this will not be the case in an application which implements floating windows. (See Fig 1, in which two floating windows and one document window are active at the same time.) Accordingly, you will need to work around how the Window Manager generates activate events and how the Toolbox Event Manager reports them to an application.

The Single Deactivate Event Problem. Because the Window Manager works on the principle that only one window is ever active, only one deactivate event is generated for every activate event. This behaviour will not suffice for an application with floating windows when a modal or movable modal dialog receives the activate event. In that case, a deactivate event is required not only for the frontmost document window but for all of the visible floating windows as well.

These two problems mean that you must not use those Window Manager functions, such as SelectWindow, ShowWindow, and HideWindow, which implicitly generate activate and deactivate events. Instead, you must use lower-level functions like BringToFront, ShowHide, and HiliteWindow to simulate the higher-level calls.

Activate Events and Document Windows. Other cases that the Window Manager does not handle well occur when the frontmost document window is closed or when a new document window is created in front of other document windows. If floating windows are present, these document windows do not receive the needed activate and deactivate events, since the application is essentially removing or creating windows in the middle of the window list. Accordingly, your application must itself manage the activation and deactivation of the relevant windows.

Activate Events and Modal Windows. When a modal window is to appear, your application will need to deactivate all visible floating windows and the active document window. When the user dismisses the modal window, your application must re-activate each of those windows.

These considerations require that you subvert the system software's normal window activation/deactivation activities and divide the window list into two sections, specifically, the section occupied by the floating windows (which must always be at the beginning of the overall list) and the section occupied by the document windows.

Opening, Closing, Showing and Hiding

A floating window's close box should simply hide the window, not close it. For that reason, the close box in floating windows should be conceived of as a "hide" box rather than as a go-away box.

Application in the Background. Floating windows should be hidden by the owner application when that application receives a suspend event. This is to avoid user confusion arising from one application's floating windows being visible when another application is in the foreground. The floating windows should be shown again only when the application receives a subsequent resume event.

Implementing Floating Windows - Substitute and Supporting Functions

The following reflects the implementation methodology used in the demonstration program associated with this chapter.

Main Substitute Functions

The names of the replacement and supplementary functions shown are, of course, purely arbitrary. You may use whatever names you like. The names shown are those used in the demonstration program.

Additional Substitute Functions

To compensate for this, a reference constant field is included in the special structure containing information relevant to window management. This field may be used to store the value that you would ordinarily assign to the window structure's refCon field. The following additional substitute functions pertain to assigning a value to, and retrieving that value from, this field:

Supporting Functions

Floating Window Types

Window Definition IDs

Floating Windows Library Functions

OSErr  FW_GetNewCWindow(WindowPtr *windowPtr,SInt16 windResourceID,WindowPtr behind,
       ActivateHandlerUPP activateFunctionUPP,Boolean isFloater)
void   FW_DisposeWindow(WindowPtr windowPtr)
void   FW_SelectWindow(WindowPtr windowPtr)
void   FW_HideWindow(WindowPtr windowPtr)
void   FW_ShowWindow(WindowPtr windowPtr)
void   FW_DragWindow(WindowPtr windowPtr,Point startPoint,const Rect *draggingBounds)

SInt32  FW_GetWRefCon(WindowPtr windowPtr)
void    FW_SetWRefCon(WindowPtr windowPtr,SInt32 refCon)

void       FW_doSuspendEvent(void)
void       FW_doResumeEvent(void)
void       FW_activateFloatsAndFirstDocWin(void)
void       FW_deactivateFloatsAndFirstDocWin(void)
WindowPtr  FW_findFrontNonFloatWindow(void)
void       FW_validateWindowList(void)