The nib file for this project requires two window resources. This example uses a document window and a utility window, but you're free to change the window types. In the nib file, the windows should be named MainWindow and InfoWindow . If you use different names, you'll need to change the arguments to calls to CreateWindowFromNib to match your names. Both windows are empty. Their content will be created in window update routines in the source code. The program doesn't make use of any of the menu items, so you can leave the menu bar resource unchanged. Example 4.7 contains the entire listing for the example program. Here you see an example of the multiple window updating technique described in the previous section: a global variable is declared for each of two window types, and a single event handler is used to invoke the proper update routine for the window that needs to be redrawn. The code that comprises each update routine is similar to the code discussed in the previous example, WindowUpdate. Example 4.7 MultipleWindowUpdate Source Code #include <Carbon/Carbon.h> pascal OSStatus MyWindowEventHandler( EventHandlerCallRef handlerRef, EventRef event, void *userData ); void UpdateMainWindow( void ); void UpdateInfoWindow( void ); WindowRef gMainWindow; WindowRef gInfoWindow; int main(int argc, char* argv[]) { IBNibRef nibRef; OSStatus err; EventTargetRef target; EventHandlerUPP handlerUPP; EventTypeSpec windowEvent = { kEventClassWindow, kEventWindowDrawContent }; err = CreateNibReference( CFSTR("main"), &nibRef ); err = SetMenuBarFromNib( nibRef, CFSTR("MainMenu") ); err = CreateWindowFromNib(nibRef, CFSTR("MainWindow"), &gMainWindow); target = GetWindowEventTarget( gMainWindow ); handlerUPP = NewEventHandlerUPP( MyWindowEventHandler ); InstallEventHandler( target, handlerUPP, 1, &windowEvent, (void *)gMainWindow, NULL ); err = CreateWindowFromNib(nibRef, CFSTR("InfoWindow"), &gInfoWindow); target = GetWindowEventTarget( gInfoWindow ); handlerUPP = NewEventHandlerUPP( MyWindowEventHandler ); InstallEventHandler( target, handlerUPP, 1, &windowEvent, (void *)gInfoWindow, NULL ); DisposeNibReference( nibRef ); ShowWindow( gMainWindow ); ShowWindow( gInfoWindow ); RunApplicationEventLoop(); return( 0 ); } pascal OSStatus MyWindowEventHandler( EventHandlerCallRef handlerRef, EventRef event, void *userData) { OSStatus result = eventNotHandledErr; UInt32 eventKind; WindowRef window; window = ( WindowRef )userData; eventKind = GetEventKind( event ); if ( eventKind == kEventWindowDrawContent ) { if ( window == gMainWindow ) UpdateMainWindow(); else if ( window == gInfoWindow ) UpdateInfoWindow(); } return result; } void UpdateMainWindow( void ) { FMFontFamily fontFamily; SetPortWindowPort( gMainWindow ); fontFamily = FMGetFontFamilyFromName( "\pTimes" ); TextFont( fontFamily ); TextFace( bold + italic ); TextSize( 36 ); MoveTo( 30,60 ); DrawString( "\pMain Window" ); } void UpdateInfoWindow( void ) { FMFontFamily fontFamily; SetPortWindowPort( gInfoWindow ); fontFamily = FMGetFontFamilyFromName( "\pArial" ); TextFont( fontFamily ); TextFace( bold ); TextSize( 18 ); MoveTo( 60,35 ); DrawString( "\pInfo Window" ); } Book: Mac® OS X Programming Section: Chapter 4. Windows Associating Information with Windows You've seen that it's easy to use Interface Builder to define windows that display information such as text or pictures. Using a window resource to define the content of a window is a great technique for creating a window for data input, such as a window used as a spreadsheet, or for creating a window that displays information for the user to view, such as an About window that reveals copyright information about a program. On the other hand, a window resource isn't always useful for defining a window that will have dynamic content. For example, you might use a window resource to define the content of a window that displays a picture of the program's creator (that would be you). However, if your program opens a window that enables the user to add one or more pictures of his or her own choosing, defining that window's content in advance is impossible. For situations in which the user creates window content during program execution, a nonresource solution is in order. Experienced Mac Programmer Of course, it is possible to set up dynamic content display in a window resource. In the past, you might have used a user item in a WIND resource (or a user pane in a window nib resource) to provide a means of adding window content during runtime. That's sidestepping the issue a bit, though. In this section, I'm leading up to a means of creating multiple, complex windows, such as those that would be found in a program that enables the user to add text, numbers, and pictures in various combinations at various locations within each window. A window can display any kind of information. Text, numbers, or pictures are common entities making up the content of a window. A window also can display a QuickTime movie, or it can "hold" a sound. In addition, depending on what features a programmer wants to provide, a program can hold any combination of these entities. A program that supports the display of just one type of content can enable each of its windows to display different forms of that same content. For instance, a text editor that enables only the entry of text will enable each open window to hold different passages of text. Thus, when it comes to associating information with windows, there are a few techniques to master. You'll want to know the simplest technique first: how to associate one piece of information, such as a number, with a single window. Beyond that you'll want to know how to associate different types of information, such as several numbers, a picture, and a string of text, with a single window. Finally, you'll want to know how to make sure that the information associated with different windows is tracked. For instance, when two windows in the text editor program you're developing need updating, you'll want to make sure that the correct text gets displayed in the proper window. In this section, you'll see how your program's windows can include all these features. Associating a Single Variable With a Window To associate data with a window, you'll rely on the Carbon SetWindowProperty routine. To retrieve a window's data, you'll use the corresponding GetWindowProperty routine. Setting a Window's Data The SetWindowProperty routine accepts a pointer to the data to associate with the window; thus, that data can be as trivial as a single variable (such as an int variable that holds a number) or as complex as a large structure (that might have numerous fields to hold text, pictures, movies, and so forth). I'll start out simple by demonstrating how to use SetWindowProperty to associate one piece of information with a window. Here's the prototype for SetWindowProperty: OSStatus SetWindowProperty( WindowRef window, PropertyCreator propertyCreator, PropertyTag propertyTag, UInt32 propertySize, void * propertyBuffer ); The window parameter is a reference to the window with which to associate the data. This parameter is the variable returned by CreateWindowFromNib when the window was created. The propertyCreator is a creator code, which is typically the application's signature. When you build an application, you have the option of providing it with a fourcharacter code. This code is used by the desktop to relate document files created by your application to your application. For instance, if you double-click a Microsoft Word file on the desktop, the system knows to open that file in Microsoft Word. If you don't provide your application with a signature, you can pass 0 as the propertyCreator value. The propertyTag is a four-character identifier that you provide for this one piece of data. Later, when it comes time to retrieve this data (with a call to the GetWindowProperty routine), you'll use the same propertyTag. You can use any four characters you want for this value. The propertySize tells SetWindowProperty the size of the data. This size is in bytes, so you can use sizeof to get this value. For instance, if the data consists of just one integer, you could pass sizeof ( int ) here. If the data is a structure, you'll use sizeof with the structure type, as in sizeof ( MyWindDataStruct). The MoreWindowInfo example program that follows the WindowInfo example program provides an example of using a structure to hold window data. Finally, it's time to consider the data. The propertyBuffer is a generic pointer that points to the memory that holds the data to associate with the window. For a single piece of data, such as an integer, you'll pass the address of the integer variable, as in &theNumber. For a structure, you'll first create a handle to the structure and then pass a pointer to that handle. Don't worry; that process isn't as complicated as it sounds! This chapter's "Associating a Window with a Structure" section provides an example of how to do this. This following snippet of code provides a look at how SetWindowProperty can be used to associate a single value-an integer-to a window: UInt32 windowNumber = 99; WindowRef window; err = CreateWindowFromNib( nibRef, CFSTR("MainWindow"), &window ); SetWindowProperty( window, 0, "test", sizeof( UInt32 ), &windowNumber ); This example associates the number 99 with the window created from the previous call to CreateWindowFromNib. The program isn't using an application signature, so a value of 0 is passed as the second argument. I somewhat arbitrarily chose test as the fourcharacter property tag. The characters that make up the tag aren't important, as long as the exact same characters are used in the GetWindowProperty call that will follow. The UInt32 data type is a commonly used Carbon data type for a variable that's to hold an unsigned integer. Using sizeof with this data type provides the size in bytes of this type. Prefacing the data- holding variable name with & sends the address of the windowNumber variable to SetWindowProperty. Retrieving a Window's Data After associating data with a window, you'll eventually want to retrieve that data. If the data consists of information about the content of the window (such as text or graphics that are displayed in the window), this is when you'll want to update the window. On the other hand, if the data consists of other information, such as user-entered numbers, the time to retrieve the window data might be when the user specifies that some calculation involving the data is to take place. In any case, you'll use the Carbon routine GetWindowProperty to retrieve previously stored window information: OSStatus GetWindowProperty( WindowRef window, PropertyCreator propertyCreator, PropertyTag propertyTag, UInt32 bufferSize, UInt32 * actualSize, void * propertyBuffer ); If you take a look back at the prototype for the SetWindowProperty routine in the "Setting a Window's Data" section, you'll see that most of the parameters for that routine match those of GetWindowProperty. The first parameter, window , is the window to examine for associated data. The propertyCreator and propertyTag are each fourcharacter strings that should match the corresponding arguments previously passed to SetWindowProperty for this same window. The bufferSize is the size, in bytes, of the data to retrieve. This argument should match the propertySize argument passed to SetWindowProperty for this window. actualSize is a pointer to a variable. GetWindowProperty uses this variable to hold the actual size of the data to retrieve. This size should of course match the bufferSize, so if you aren't interested in this actualSize, you can pass a value of NULL here. Finally, the propertyBuffer is a generic pointer to the memory that will, upon completion of GetWindowProperty, hold the window's data. The following snippet shows how to retrieve the data associated with a window. I've included the call to SetWindowProperty to emphasize that a call to SetWindowProperty must precede a call to GetWindowProperty (or else there will be no data to retrieve) and to demonstrate how similar the arguments to the two routines are. After you've figured out how to call SetWindowProperty for your particular situation, you then know how to call GetWindowProperty. UInt32 windowNumber = 99; WindowRef window; UInt32 theNumber; err = CreateWindowFromNib( nibRef, CFSTR("MainWindow"), &window ); // associate the data (99) in variable windowNumber with a window: SetWindowProperty( window, 0, 'test', sizeof( UInt32 ), &windowNumber ); // retrieve the data (99) from the window and store it in theNumber: GetWindowProperty( window, 0, 'test', sizeof( UInt32 ), NULL, &theNumber ); WindowInfo Program The purpose of the WindowInfo program is to demonstrate the use of SetWindowProperty and GetWindowProperty to associate data with a window, and then to retrieve that data from a window. This program associates a single integer value with a window. The next example in this chapter, MoreWindowInfo, demonstrates associating a structure with a window. WindowInfo displays one window with the number 2 written to it. It isn't important what number is used. I'm simply showing how data can be assigned to a window, and then later retrieved during the updating of the window. This program doesn't make use of any menu items, and the window that displays the number is initially empty, so providing details about the project's nib file are unimportant. Simply make sure there's a window named MainWind in the nib file and you're all set to go. Example 4.8 provides the entire source code listing for the WindowInfo program. After creating a new window, the program calls SetWindowProperty to associate the number 2 with the window. The one event the program looks for is an update event, as discussed in this chapter's "Updating Window Content" section. When an update event occurs, MyWindowEventHandler is invoked. That routine calls the application-defined routine UpdateWindow to redraw the window's contents. To do this, the window's data (the number 2) is retrieved and that data is drawn to the window. In previous examples, you've seen that DrawString is used to draw a string of text to a window. Because this program's window has a number associated with it, and because I want to draw that number to the window, a conversion needs to take place. The Carbon routine NumToString accepts an integer as its first argument and returns the string version of that number in the second argument. Here's how variable windowNumber gets its value: UInt32 windowNumber; GetWindowProperty( window, 0, 'test', sizeof( UInt32 ), NULL, &windowNumber ); In the following code, NumToString is called to convert the integer value in the variable windowNumber to a string held in variable numberStr: Str255 numberStr; NumToString( windowNumber, numberStr ); Now DrawString can be called to draw the string, with the result being the number 2 being written to the window: DrawString( numberStr ); Example 4.8 WindowInfo Source Code #include <Carbon/Carbon.h> pascal OSStatus MyWindowEventHandler( EventHandlerCallRef handlerRef, EventRef event, void *userData ); void UpdateWindow( WindowRef window ); int main( int argc, char* argv[] ) { IBNibRef nibRef; OSStatus err; WindowRef window; EventTargetRef target; EventHandlerUPP handlerUPP; EventTypeSpec windowEvent = { kEventClassWindow, kEventWindowDrawContent }; UInt32 windowNumber = 2; err = CreateNibReference( CFSTR("main"), &nibRef ); err = SetMenuBarFromNib( nibRef, CFSTR("MainMenu") ); err = CreateWindowFromNib( nibRef, CFSTR("MainWindow"), &window ); target = GetWindowEventTarget( window ); handlerUPP = NewEventHandlerUPP( MyWindowEventHandler ); InstallEventHandler( target, handlerUPP, 1, &windowEvent, (void *)window, NULL ); SetWindowProperty( window, 0, 'test', sizeof(UInt32), &windowNumber); DisposeNibReference( nibRef ); ShowWindow( window ); RunApplicationEventLoop(); return( 0 ); } pascal OSStatus MyWindowEventHandler( EventHandlerCallRef handlerRef, EventRef event, void *userData) { OSStatus result = eventNotHandledErr; UInt32 eventKind; WindowRef window; window = ( WindowRef )userData; eventKind = GetEventKind( event ); if ( eventKind == kEventWindowDrawContent ) { UpdateWindow( window ); } return result; } void UpdateWindow( WindowRef window ) { FMFontFamily fontFamily; UInt32 windowNumber; Str255 numberStr; SetPortWindowPort( window ); GetWindowProperty( window, 0, 'test', sizeof( UInt32 ), NULL, &windowNumber ); NumToString( windowNumber, numberStr ); fontFamily = FMGetFontFamilyFromName( "\pTimes" ); TextFont( fontFamily ); TextFace( bold + italic ); TextSize( 36 ); MoveTo( 150,60 ); DrawString( numberStr ); } Associating a Structure with a Window Using a single piece of information, such as a number, as the data to associate with a window provides a good look at how SetWindowProperty and GetWindowProperty are used. However, if your program associates data with a window, it's going to associate more than one value with that window. SetWindowProperty and GetWindowProperty each work with only one piece of information. Bundling all your window's data into a single structure is how you get around this apparent limitation. The first thing you need to do is to define a structure that includes the fields appropriate to storing whatever data is to be associated with your program's window. The following snippet defines a structure that holds one integer and one string. The structure your program needs will differ, but the techniques that I'll be describing still apply. typedef struct { UInt32 number; Str255 string; } WindowData, **WindowDataHandle; The preceding structure is given the data type name of WindowData .The code also defines the data type WindowDataHandle, which serves as a handle to the WindowData structure. A handle, which is a pointer to a pointer, is a data type commonly used in Macintosh programming. Before associating a structure with a window, you'll want to declare a structure of type WindowData and then reserve the memory space necessary to hold such a structure. You can do that by using the Carbon routine NewHandle, which specifies the number of bytes to reserve. You can typecast the result so that instead of a generic handle, you have a handle that references a WindowData structure: WindowDataHandle windDataHndl; windDataHndl = ( WindowDataHandle )NewHandle( sizeof( WindowData ) ); With memory reserved for the WindowData structure and a means to reference that memory, it's time to fill the structure's fields with values. For a numerical field like the number field, you dereference the handle twice. Dereferencing a handle once results in a pointer to the structure; dereferencing a handle a second time results in the structure itself. You then access the field of interest. Here the number field of the WindowData structure referenced by the windDataHndl variable is being assigned the value 5: UInt32 theNumber = 5; (**windDataHndl).number = theNumber; Next, you assign a value to the string field of the structure. Assigning a string variable a value at the time of declaration is easy: Str255 theString = "\pCopyright (c) 2001" [...]... kDollar5 kDollar10 kDollar20 kDollar50 1 2 3 4 5 // // // // // dollarValue; switch ( dollarValue ) { case kDollar1: dollarDenomination break; case kDollar5: dollarDenomination break; case kDollar10: dollarDenomination break; case kDollar20: dollarDenomination break; case kDollar50: dollarDenomination break; } = 1; = 5; = 10; = 20; = 50 ; Example 5. 1 RadioButtonGroup Source Code 1st 2nd 3rd 4th 5th radio... generation: http://developer.apple.com/techpubs/macosx/ Carbon/graphics/QuickDraw/QuickDraw_Manager/Functions/Random.html Book: Mac OS X Programming Chapter 5 Controls A CONTROL IS AN ITEM WITH WHICH a program's user can interact By clicking a control such as a push button, a user can initiate some immediate action, as you've seen in several of the example programs in previous chapters Other types... action to take place Examples of such controls are radio buttons, text input fields, and checkboxes In this chapter you'll see how to create and manage controls of these types In learning about these control types, you'll see how a control can be assigned either a command signature (as you've done in previous chapters) or a control ID Book: Mac OS X Programming Section: Chapter 5 Controls Command Signatures... is usually assigned a command This chapter also covers radio button groups, text input fields, and checkboxes Each type of control usually has a control ID assigned to it Book: Mac OS X Programming Section: Chapter 5 Controls Buttons Some types of controls have more than one state For such a control, the program needs to examine the control to determine its state This need to know about the particular... window ); GetWindowProperty( window, 0, 'test', sizeof( SInt16 ), NULL, &windowNumber ); NumToString( windowNumber, numberStr ); fontFamily = FMGetFontFamilyFromName( "\pTimes" ); TextFont( fontFamily ); TextFace( bold + italic ); TextSize( 36 ); MoveTo( 110,60 ); DrawString( numberStr ); } Book: Mac OS X Programming Section: Chapter 4 Windows For More Information The following web site offers more... variables, your program can use the window data For example, the content of the window (such as text or pictures) could be associated with the window and then used in updating the window's contents Such an example is discussed next MoreWindowInfo Program The purpose of the MoreWindowInfo program is to expand on the technique demonstrated in the previous example,WindowInfo In this program, a structure, rather... application-defined BeepCommandHandler routine to call SysBeep Book: Mac OS X Programming Section: Chapter 5 Controls Radio Buttons Radio buttons are small, round buttons that come in groups Unlike a checkbox, which is used to turn on or off an option, a radio button never appears without at least one other such button This is because radio buttons are used to choose one (and only one) option from a set of two or more... of code: SInt16 x; for ( x = 1; x . "pArial" ); TextFont( fontFamily ); TextFace( bold ); TextSize( 18 ); MoveTo( 60, 35 ); DrawString( "pInfo Window" ); } Book: Mac OS X Programming Section: Chapter. "pTimes" ); TextFont( fontFamily ); TextFace( bold + italic ); TextSize( 36 ); MoveTo( 110,60 ); DrawString( numberStr ); } Book: Mac OS X Programming Section: Chapter. has executed. The final argument is the number of bytes to copy, which are the bytes in the source string. As mentioned, an Str 255 is an array. It's an array that can hold up to 255 characters,