• Support for:

  • Floating windows.

    Note Although system support for floating windows was introduced with the Mac OS 8.5 Window Manager, Apple subsequently advised that there were significant bugs in the window activation area and that the Application Programming Interfaces (APIs) relating to floating windows should not be used until further notice. These bugs were eliminated in Mac OS 8.6. The upshot of all this is that, if your application uses floating windows, and if it is required to run under Mac OS 8.5 or earlier, your application will itself have to include the code necessary to support floating windows. (See Chapter 21 - Floating Windows - Mac OS 8.5 and Earlier.)

  • Window proxy icons.

  • Window path pop-up menus.

  • Transitional window animations and sounds.

• New functions for:

  • Creating and storing windows.

  • Accessing window information.

  • Zooming, moving, re-sizing, and positioning windows.

  • Associating data with a window.

  • Adding and removing rectangles and regions to and from a window's update region.

  • Setting the colour or pattern of a window's content region.

Front-To-Back Ordering of On-Screen Objects

• Help balloons.

• Menus.

• System windows.

• Modal and movable modal dialog and alert boxes.

• Floating windows.

• Document windows and modeless dialog boxes.

In Mac OS 8.5 and later, support for floating windows is built into the Window Manager, meaning that, amongst other things, the system now supports the activation of more than one window at a time.

Floating Window Types

Floating windows should be created at application launch and should remain open until the application is closed. However, your application should provide the user with a means to hide or show each individual floating window as and when required. Ordinarily, it should do this by providing items in an appropriate menu which allow the user to toggle each floating window between the hidden and showing states.

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.

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 application's floating windows should be shown again only when the application receives a subsequent resume event.

Mac OS 8.5 Functions Relating to Floating Windows

Window Proxy Icons

Proxy icons:

• May be dragged, in the same way that the document's icon in the Finder may be dragged, so as to move or copy the document file.

• Provide visual feedback to the user on the current state of the document. For example, when the document has unsaved changes, your application should cause the proxy icon to be displayed in the disabled state, thus preventing the user from dragging it. (Unsaved documents should not be capable of being moved or copied.)

• Provide visual feedback to the user indicating that the document window is a valid drag-and-drop target. In this case, your application should cause the proxy icon to appear in the highlighted state.

At Fig 2, note that, in the drag and drop operation depicted at the right, the window's content area is highlighted along with the proxy icon. Applications typically call the Drag Manager function ShowDragHilite to indicate, with this highlighting, that a window is a valid drag-and-drop target. Under Mac OS 8.5 and later, ShowDragHilite and HideDragHilite highlight and unhighlight the proxy icon as well as the content area.

Changing the State of a Proxy Icon

A document's proxy icon is much more prominent to the user than the document's Finder icon. Thus, when proxy icons are used, there is an even a greater possibility that the user will move the file represented by the proxy icon to a different folder while the document is open. The provision of a file synchronisation function is therefore imperative when proxy icons are implemented.

File synchronisation functions should be called after every call to WaitNextEvent and, for each of the application's document windows, should update the application's internal data structures to match that of the document file as it exists on disk. The function should also ensure that, where necessary, the name of the document window is changed to match the current name of the document file on disk and close the document window if the document file has been moved to the Trash folder.

Mac OS 8.5 Functions Relating to Window Proxy Icons

Note that SetPort should be called to set the relevant window's colour graphics port as the current port before calling SetWindowProxyCreatorAndType, SetWindowProxyFSSpec, SetWindowProxyAlias, and SetWindowProxyIcon.

Window Path Pop-Up Menus

Displaying and Handling a Window Path Pop-Up Menu

When FindWindow returns the inProxyIcon part code, and TrackWindowProxyDrag returns errUserWantsToDragWindow, your application should proceed on the assumption that the inDrag part code was returned by FindWindow.

When FindWindow returns the inDrag part code, your application should call IsWindowPathSelectClick to determine whether the mouse-down event should activate the window path pop-up menu. If IsWindowPathSelectClick returns true, WindowPathSelect should be called to display the menu.

If the user chooses a menu item for a folder, your application must ensure that the associated window is visible by calling an application-defined function which makes the Finder the frontmost process.

Transitional Window Animation and Sounds

The Mac OS 8.5 Window Manager function TransitionWindow may be used in lieu of the older functions HideWindow and ShowWindow to hide and show windows. TransitionWindow causes a transitional animation to be displayed, a transitional sound to be played, and the necessary update and activate events to be generated.

Creating and Storing Windows

Use of the last three of these functions requires a basic understanding of collections, flattened collections and 'wind' resources.

Collections, Flattened Collections, and 'wind' Resources

A collection is like an array in that it contains a number of individually accessible items. However, unlike an array, a collection allows for a variable number of data items and variable-size items. A collection is also similar to a database, in that you can store information and retrieve it using a variety of search mechanisms.

The internal structure of a collection is private. This means that you must store information into a collection and retrieve information from it using Collection Manager functions.

Using the function StoreWindowIntoCollection, your application can store a window into a collection. This applies to any window, not just those created using Mac OS 8.5 Window Manager functions. You can also store data associated with the window (for example, text) into the same collection. This provides a quick and easy way for your application to save a simple document.

Using the Mac OS 8.5 function CreateWindowFromCollection, you can create a window from collection data. Note that CreateWindowFromCollection creates the window invisibly. After creating the window, you must call the function TransitionWindow to display the window.

Flattened Collections

Using the Mac OS 8.5 function CreateWindowFromResource, you can create a window from a 'wind' resource. Note that CreateWindowFromResource creates the window invisibly. After creating the window, you must call the function TransitionWindow to display the window.

The CreateNewWindow Function

Window Attribute Constants

Note that CreateNewWindow creates the window invisibly. After creating the window, you must call the function TransitionWindow to display the window.

Accessing Window Information

Zooming, Moving, Resizing, and Positioning Windows

• A window should move as little as possible when zooming between the user state and standard state, to avoid distracting the user.

• A window in its standard state should be positioned so that it is entirely on one screen.

• If a window straddles more than one screen in the user state, when it is zoomed to the standard state it should be zoomed to the screen that contains the largest portion of the window's content region.

• If the ideal size for the standard state is larger than the destination screen, the dimensions of the standard state should be that of the destination screen, minus a few pixels of boundary. If the destination screen is the main screen, space should also be left for the menu bar.

• When a window is zoomed from the user state to the standard state, the top left corner of the window should remain anchored in place; however, if the standard state of the window cannot fit on the screen with the top left corner anchored, the window should be "nudged" so that the parts of the window in the standard state that would fall offscreen are, instead, just onscreen.

When ZoomWindowIdeal is used, the Mac OS 8 function IsWindowInStandardState must be used to determine the appropriate part code (inZoomIn or InZoomOut) to pass in ZoomWindowIdeal's partCode parameter.

The following two additional Mac OS 8.5 functions relating to window zooming allow your application to access the window's user-state in a Carbon-compliant manner.

Ordinarily, your application does not need to use these two functions. They are supplied for the sake of completeness.

Moving Windows

MoveWindow repositions a window's content region, whereas MoveWindowStructure repositions a window's structure region. The introduction of the MoveWindowStructure function arises from the fact that, under the Appearance Manager, the size and shape of a window's frame may vary from appearance to appearance (see Chapter 6 - The Appearance Manager). This means that the total dimensions of the window (that is, the window's structure region) may also vary, causing the window's spatial relationship to the rest of the screen to change.

The Mac OS 8.5 function SetWindowBounds provides a means to set the size of a window in addition to simply repositioning it. The size and position of the window are specified in a rectangle passed in the globalBounds parameter. In addition, you may specify whether this rectangle represents the bounds of the content region or the bounds of the structure region by passing either kWindowContentRgn or kWindowStructureRgn in the regionCode parameter. The sister Mac OS 8.5 function GetWindowBounds obtains the size and position of the bounding rectangle of the specified window region.

Resizing Windows

ResizeWindow informs your application of the new window bounds, so that, if necessary, your application can respond to any changes in the window's position. (This latter possibility arises from the fact that some appearances may allow the window to be resized from any corner, not just the bottom right, as a result of which the window may move on the screen and not simply change size.)

Positioning Windows

The Mac OS 8.5 function RepositionWindow allows you to position a window relative to another window or a display screen. The required window positioning method may be specified by passing one of the following constants in the method parameter.

Window Positioning Constants

These constants should not be confused with the pre-Mac OS 8.5 positioning specification constants (see Chapter 4 - Windows), and should not be used where those older constants are required (for example, in 'WIND', 'DLOG', and 'ALRT' resources, and in the StandardAlert function).

Associating Data With Windows

The Mac OS 8.5 Window Manager provides the following functions relating to associating data with windows:

Adding To and Removing From the Update Region

Setting Content Region Colour and Pattern

These functions do not affect the colour graphics port's background colour or pattern.

Main Window Manager Constants, Data Types and Functions

KAlertWindowClass         = 1L
kMovableAlertWindowClass  = 2L
kModalWindowClass         = 3L
kMovableModalWindowClass  = 4L
kFloatingWindowClass      = 5L
kDocumentWindowClass      = 6L

kWindowNoAttributes               = 0L
kWindowCloseBoxAttribute          = 1L << 0
kWindowHorizontalZoomAttribute    = 1L << 1
kWindowVerticalZoomAttribute      = 1L << 2
kWindowFullZoomAttribute          = kWindowVerticalZoomAttribute |
                                    kWindowHorizontalZoomAttribute
kWindowCollapseBoxAttribute       = 1L << 3
kWindowResizableAttribute         = 1L << 4
kWindowSideTitlebarAttribute      = 1L << 5
kWindowNoUpdatesAttribute         = 1L << 16
kWindowNoActivatesAttribute       = 1L << 17
kWindowStandardDocumentAttributes = kWindowCloseBoxAttribute |
                                    kWindowFullZoomAttribute |
                                    kWindowCollapseBoxAttribute |
                                    kWindowResizableAttribute)
kWindowStandardFloatingAttributes = kWindowCloseBoxAttribute |
                                    kWindowCollapseBoxAttribute

kWindowCenterOnMainScreen                 = 0x00000001
kWindowCenterOnParentWindow               = 0x00000002
kWindowCenterOnParentWindowScreen         = 0x00000003
kWindowCascadeOnMainScreen                = 0x00000004
kWindowCascadeOnParentWindow              = 0x00000005
kWIndowCascadeOnParentWindowScreen        = 0x00000006
kWindowAlertPositionOnMainScreen          = 0x00000007
kWindowAlertPositionOnParentWindow        = 0x00000008
kWindowAlertPositionOnParentWindowScreen  = 0x00000009

kWindowShowTransitionAction       = 1
kWindowHideTransitionAction       = 2
kWindowZoomTransitionEffect       = 1

typedef OSType PropertyCreator;
typedef OSType PropertyTag;

typedef UInt32 WindowClass;
typedef UInt32 WindowAttributes;

typedef UInt32 WindowPositionMethod;

typedef UInt32 WindowTransitionEffect;
typedef UInt32 WindowTransitionAction;

OSStatus  InitFloatingWindows (void);
OSStatus  HideFloatingWindows(void);
OSStatus  ShowFloatingWindows(void);
Boolean   AreFloatingWindowsVisible(void);

OSStatus  SetWindowProxyCreatorAndType(WindowPtr window,OSType fileCreator,
          OSType fileType,SInt16 vRefNum);
OSStatus  SetWindowProxyFSSpec(WindowPtr window,const FSSpec *inFile);
OSStatus  GetWindowProxyFSSpec(WindowPtr window,FSSpec * outFile);
OSStatus  GetWindowProxyAlias(WindowPtr window,AliasHandle *alias);
OSStatus  SetWindowProxyAlias(WindowPtr window,AliasHandle alias);
OSStatus  SetWindowProxyIcon(WindowPtr window,IconRef icon);
OSStatus  GetWindowProxyIcon(WindowPtr window,IconRef * outIcon);
OSStatus  RemoveWindowProxy(WindowPtr window);
OSStatus  TrackWindowProxyDrag(WindowPtr window,Point startPt);

Boolean   IsWindowPathSelectClick (WindowPtr window,EventRecord *event);
OSStatus  WindowPathSelect(WindowPtr  window,MenuHandle menu,SInt32 *outMenuResult);

SStatus  TransitionWindow(WindowPtr window,WindowTransitionEffect effect,
         WindowTransitionAction action,const Rect *rect)

OSStatus  CreateNewWindow(WindowClass windowClass,WindowAttributes attributes,
          const Rect *bounds,WindowPtr *outWindow);
OSStatus  CreateWindowFromResource(SInt16 resID,WindowPtr *outWindow);
OSStatus  CreateWindowFromCollection(Collectioncollection,WindowPtr *outWindow);
OSStatus  StoreWindowIntoCollection(WindowPtr window,Collection collection);

OSStatus  GetWindowClass(WindowPtr window,WindowClass *outClass);
OSStatus  GetWindowAttributes (WindowPtr window,WindowAttributes *outAttributes);
Boolean   IsValidWindowPtr(GrafPtr  grafPort);
WindowPtr FrontNonFloatingWindow(void);

OSStatus  ZoomWindowIdeal(WindowPtr window,SInt16 partCode,Point *ioIdealSize);
Boolean   IsWindowInStandardState(WindowPtr window,Point *idealSize,
          Rect *idealStandardState);
OSStatus  SetWindowIdealUserState(WindowPtr window,Rect *userState);
OSStatus  GetWindowIdealUserState(WindowPtr window,Rect *userState);
OSStatus  MoveWindowStructure(WindowPtr window,short hGlobal,short vGlobal);
OSStatus  SetWindowBounds(WindowPtr window,WindowRegionCode regionCode,
          const Rect *globalBounds);
OSStatus  GetWindowBounds(WindowPtr window,WindowRegionCode regionCode,
          Rect *globalBounds);
Boolean   ResizeWindow(WindowPtr window,Point startPoint,const Rect *sizeConstraints,
          Rect *newContentRect);
OSStatus  RepositionWindow(WindowPtr window,WindowPtr parentWindow,
          WindowPositionMethod method);

OSStatus  SetWindowProperty(WindowPtr window,PropertyCreator propertyCreator,
          PropertyTag propertyTag,UInt32 propertySize,void *propertyBuffer);
OSStatus  GetWindowProperty(WindowPtr window,PropertyCreator propertyCreator,
          PropertyTag propertyTag,UInt32 bufferSize,UInt32 *actualSize,
          void *propertyBuffer);
OSStatus  GetWindowPropertySize(WindowPtr window,PropertyCreator creator,PropertyTag tag,
          UInt32 *size);
OSStatus  RemoveWindowProperty(WindowPtr window,PropertyCreator propertyCreator,
          PropertyTag propertyTag);

OSStatus  InvalWindowRect(WindowPtr window,const Rect *bounds);
OSStatus  InvalWindowRgn(WindowPtr window,RgnHandle region);
OSStatus  ValidWindowRect(WindowPtr window,const Rect *bounds);
OSStatus  ValidWindowRgn(WindowPtr window,RgnHandle region);

OSStatus  SetWindowContentColor(WindowPtr window,RGBColor *color);
OSStatus  GetWindowContentColor(WindowPtr window,RGBColor *color);
OSStatus  GetWindowContentPattern(WindowPtr window,PixPatHandle outPixPat);
OSStatus  SetWindowContentPattern(WindowPtr window,PixPatHandle pixPat);