You typically create a new window every time the user creates a new document, opens a previously saved document, or issues a command that triggers a dialog box.
Prior to the Mac OS 8.5 Window Manager, you could create a window in two ways:
With the Mac OS 8.5 Window Manager, you can still create a window by passing parameter data, but there is an updated function for this purpose, CreateNewWindow , which allows you to specify Mac OS 8.5 window features. Listing 2-1 provides an example of using CreateNewWindow as part of an application-defined function, MyCreateAndShowNewDocumentWindow , that creates and displays a document window.
Because the window being created is a document window, MyCreateAndShowNewDocumentWindow calls the function SetWindowProxyCreatorAndType to establish a proxy icon for the window. See Supporting Window Proxy Icons for more on working with proxy icons in your document windows.
Note that because CreateNewWindow creates the specified window invisibly--as do the other Mac OS 8.5 window-creation functions-- MyCreateAndShowNewDocumentWindow also includes a call to the function TransitionWindow to display the window. The TransitionWindow function displays an animation and plays the theme-appropriate sound for a window when it is shown or hidden. Your application may use TransitionWindow instead of the pre-Mac OS 8.5 Window Manager functions ShowWindow and HideWindow . Like these earlier functions, TransitionWindow generates the appropriate update and active events when it shows and hides windows.
Listing 2-1 Creating and displaying a document window
static pascal OSStatus MyCreateAndShowNewDocumentWindow
(const Rect *bounds,
OSType fileCreator,
OSType fileType,
SInt16 vRefNum,
WindowPtr *window)
{
OSStatus err;
// Create an invisible window
err = CreateNewWindow ( kDocumentWindowClass,
kWindowStandardDocumentAttributes,
bounds,
window);
if ( err == noErr )
{
// Since this is a document window, give it a proxy icon
err = SetWindowProxyCreatorAndType (*window,
fileCreator,
fileType,
vRefNum);
// Make the window visible (with animation and sound)
if ( err == noErr )
{
err = TransitionWindow ( *window,
kWindowZoomTransitionEffect,
kWindowShowTransitionAction,
nil);
}
// Destroy the window if TransitionWindow returned an error
// (the most likely cause for error being that the
// application is out of memory)
if ( err != noErr )
{
DisposeWindow (*window);
}
}
return err;
}
Additionally, with the Mac OS 8.5 Window Manager, there are two new ways to create a window:
A collection is an abstract data type, defined by the Collection Manager, that allows you to store multiple pieces of related information. For purposes of the Window Manager, however, a collection might best be understood as an intermediate state between a live window and a 'wind' resource. Using the function StoreWindowIntoCollection , your application can store any window, even those not created with Mac OS 8.5 Window Manager functions, into a collection. You can also store data associated with the window into the same collection. This provides a quick way for your application to save a simple document.
From a collection, your application can create a flattened collection--that is, a stream of address-independent data--using the Collection Manager. Because the 'wind' resource consists of an extensible flattened collection, your application can store a flattened collection consisting of a window and its data into a 'wind' resource using the Resource Manager. Storing a Document Window Into a Collection provides an example of how your application might store a window and its data as a single flattened collection in an extended 'wind' resource.