TweetFollow Us on Twitter

MACINTOSH C
MACINTOSH C: A Hobbyist's Guide To Programming the Mac OS in C
Version 2.3

© 2000 K. J. Bricknell

Go to Contents

(Chapter 21)

FLOATING WINDOWS

A link to the associated demonstration program listing is at the bottom of this page



Floating Windows

Floating windows are windows which stay in front of all of an application's document windows. They are typically used to display tool, pattern, colour, and other choices to be made available to the user. Examples of floating windows are shown at Fig 1.

(Floating windows - examples)

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

The fact that floating windows always remain in front of an application's document windows leads naturally to a consideration of the correct front-to-back ordering of on-screen interface objects. Within an application, this front-to-back ordering should be as follows:

  • 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.
Note that floating windows should remain behind modal and movable modal dialog and alert boxes, reflecting the fact that, whatever choices the user can make from a floating window, those choices relate only to operations within the application's document windows and not to operations within modal dialogs and alert 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

Activate Events

The most significant aspect of implementing floating windows has to do with activate events.

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

Floating windows should be opened at application launch and should remain open until the application is closed. Since Open... and Close items in the File menu should apply only to document windows, items in some other appropriate menu should be provided to allow the user to toggle each floating window between the hidden and showing state.

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

Implementing floating windows in an application basically involves providing a number of application-defined substitute and supporting functions, many of which perform the necessary subversion of the system software's normal window activation/deactivation activities and treat the window list as comprising separate document windows and floating windows sections.

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

Main Substitute Functions

The substitute functions are those functions used in lieu of the Macintosh Toolbox functions that would ordinarily be used in a non-floating windows environment. The main substitute functions, the actions performed by those functions, and the Toolbox calls they replace, are as follows:

Substitute Replaces Actions Performed
FW_GetNewCWindow GetNewCWindow Create floating and document windows based on a resource template.

When a new floating window is opened, bring that window to the very front of any existing windows.

When a new document window is opened, move that window to immediately behind the last floating window, and in front of any document windows which may already be open.

FW_DisposeWindow DisposeWindow Dispose of document windows.

Activate the next document window in the window list, and call DisposeWindow to remove the specified document window from the screen and the window list and discard all it data storage.

FW_SelectWindow SelectWindow Bring the window (floating or document) in which the mouse-down occurred as far forward in the window list as it should come. If it is a floating window, makes it the absolute frontmost window. If it is a document window, make it the frontmost window behind the floating windows.
FW_HideWindow HideWindow Hide the specified window.

As with HideWindow, if the frontmost (floating or document) window is to be hidden, place it behind the window immediately behind it in its section of the window list so that, when it is shown again, it will no longer be frontmost window in its section.

FW_ShowWindow ShowWindow Show the specified window.

As with ShowWindow, show the window without changing its position in the window list. If the window being shown is the frontmost document window, deactivate the window behind it, and activate the window being shown.

If the specified window is a floating window, and if a modal or movable modal dialog box is present, show the window in the inactive state.

FW_DragWindow DragWindow Drag the specified window around, ensuring that, if it is a document window, it remains behind the floating windows.

As with DragWindow, do not bring the window forward if the Command key is held down during the drag.

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

The demonstration program associated with this chapter uses the refCon field of all document and floating window window structures to store a handle to a special structure containing information relevant to window management in the floating windows environment. This means that the use of the window structure's refCon field is denied to the application for other purposes (such as, for example, storing a handle to a document structure).

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:

Substitute Replaces Actions Performed
FW_SetWRefCon SetWRefCon Assign a value to the reference constant field of a structure whose handle is assigned to the refCon field of a window's window structure.
FW_GetWRefCon GetWRefCon Get the value in the reference constant field of a structure whose handle is assigned to the refCon field of a window's window structure.

Supporting Functions

The main supporting functions, and the actions performed by those functions, are as follows:

Function Actions Performed
FW_doSuspendEvent Hide any floating windows, and unhighlight and deactivate the frontmost document window.

(Call this function when the application receives a suspend event.)

FW_doResumeEvent Show all floating windows which were visible when the application was sent to the background, and highlight and activate the front document window.

(Call this function when the application receives a suspend event.)

FW_deactivateFloatsAndFirstDocWin Unhighlight and deactivate any visible floating windows and the frontmost document window.

(Call this function immediately before a modal or movable modal dialog or alert box is invoked.)

FW_activateFloatsAndFirstDocWin Highlight and activate those windows which were visible and activated before FW_deactivateFloatersAndFirstDocWin was called.

(Call this function immediately after an alert or modal dialog box is dismissed.)

FW_findFrontNonFloatWindow Find the first visible non-floating window in the window list.

(Call this function when you need the pointer to the frontmost document window or when you need to determine whether any document windows are currently open.)

FW_validateWindowList Ensure that all floating windows are in front of all document windows.

(Call this function, as a safety measure, immediately prior to opening and closing document windows.)

Floating Window Types

Figs 2 and 3 show the sixteen available window types for floating windows and the constants that represent those types.

(Window types for floating windows)

(Window types for floating windows (side title bar))

Window Definition IDs

The WDEF resource IDs for the floating window types are 66, and 67. The window definition IDs are as follows:

WDEF
Resource ID
Variation
Code
Window Definition ID (Value) Window Definition ID (Constant)
66 1 66 * 16 + 1 = 1057 kWindowFloatProc
66 3 66 * 16 + 3 = 1059 kWindowFloatGrowProc
66 5 66 * 16 + 5 = 1061 kWindowFloatVertZoomProc
66 7 66 * 16 + 7 = 1063 kWindowFloatVertZoomGrowProc
66 9 66 * 16 + 9 = 1065 kWindowFloatHorizZoomProc
66 11 66 * 16 + 11 = 1067 kWindowFloatHorizZoomGrowProc
66 13 66 * 16 + 13 = 1069 kWindowFloatFullZoomProc
66 15 66 * 16 + 15 = 1071 kWindowFloatFullZoomGrowProc
67 1 67 * 16 + 1 = 1073 kWindowFloatSideProc
67 3 67 * 16 + 3 = 1075 kWindowFloatSideGrowProc
67 5 67 * 16 + 5 = 1077 kWindowFloatSideVertZoomProc
67 7 67 * 16 + 7 = 1079 kWindowFloatSideVertZoomGrowProc
67 9 67 * 16 + 9 = 1081 kWindowFloatSideHorizZoomProc
67 11 67 * 16 + 11 = 1083 kWindowFloatSideHorizZoomGrowProc
67 13 67 * 16 + 13 = 1085 kWindowFloatSideFullZoomProc
67 15 67 * 16 + 15 = 1087 kWindowFloatSideFullZoomGrowProc



Floating Windows Library Functions

In the accompanying demonstration program files, the source code pertaining to implementing a floating windows environment has been compiled as a library. The following are the prototypes for those functions in the library that need to be called from an application.

Main Substitute 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)

Additional Substitute Functions

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

Supporting Functions

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

Go to Demo

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.