ShowWindow( window ); DisposeNibReference( nibRef ); RunApplicationEventLoop(); Book: Mac® OS X Programming Section: Appendix A. Carbon API Summary Window Manager A window is created using the Interface Builder Manager routine CreateWindowFromNib. After that, application control of the window is achieved through Window Manager routines. The function prototypes for the Window Manager routines are located in the MacWindows.h header file. The following sections describe commonly used window-related data types and functions. WindowRef: Referencing a Window A window is referenced by way of a variable of type WindowRef. A WindowRef is a pointer to a window object. Your program obtains such a reference to a window at the time the window is created. Creating a Window A window is created by calling CreateWindowFromNib to unarchive a window resource stored in a nib file. Refer to the "Interface Builder Manager (Nib Files)" section of this appendix for more information. ShowWindow: Showing a Hidden Window A window created by calling CreateWindowFromNib is initially hidden (invisible). In addition, a window that has been the object of a call to HideWindow will be hidden. In either case, call ShowWindow to make the window visible. Pass ShowWindow a reference to the window that it should make visible: WindowRef window; ShowWindow( window ); HideWindow: Hiding a Visible Window A window is made visible by calling ShowWindow. To hide (make invisible) a window, call HideWindow. Pass HideWindow a reference to the window that it should make invisible: WindowRef window; HideWindow( window ); Book: Mac® OS X Programming Section: Appendix A. Carbon API Summary Control Manager A control is created as an item in a window resource in a nib file. Accessing that control from source code is achieved by using Control Manager routines. The function prototypes for the Control Manager routines are located in the Control.h header file. The next sections describe the main control-related types and routines. ControlHandle/ControlRef: Referencing a Control A variable of the type ControlHandle is used to reference a control, such as a radio button. Call the Control Manager routine GetControlByID to obtain a handle to a control: ControlHandle myRadioButtonGroup; Note that the ControlHandle data type is defined as type ControlRef, so your code can use variables of these two types interchangeably. ControlID: Specifying a Control Your project defines a control as an item in a window resource in a nib file. That control is given a control ID, which is the combination of a signature and an ID. Together, the values specify one and only one control. Your code declares a variable of type ControlID to specify one control. Like the control item in the nib resource file, the ControlID variable consists of a signature and an ID. #define kControlSignature 'Xapp' #define kRadioGroupControlID 101 ControlID myRadioGroupControlID = { kControlSignature, kRadioGroupControlID }; GetControlByID: Obtaining a Handle to a Control To obtain a handle to a control, call the GetControlByID routine: OSStatus GetControlByID( WindowRef inWindow, const ControlID * inID, ControlRef * outControl ); The first argument to GetControlByID is a reference to the window that holds the control. The second argument is a pointer to the control's ID, as set up in a variable of type ControlID. The final argument is a control reference that's filled in when GetControlByID returns. Use this ControlRef variable in calls to other Control Manager routines, such as a call to GetControl32BitValue. OSStatus err; WindowRef window; ControlHandle myRadioButtonGroup; ControlID myRadioGroupControlID = { kControlSignature, kRadioGroupControlID }; err = GetControlByID( window, &RadioGroupControlID, &myRadioButtonGroup ); GetControl32BitValue: Obtaining a Control's Value After calling GetControlByID, your program has a handle to one control. Your program can use this handle to access the control. Accessing a control often means getting, or setting, the control's value. A call to GetControl32BitValue is made to obtain the value of a control: SInt32 GetControl32BitValue( ControlRef theControl ); The following snippet obtains the value of a radio group control. For this type of control, the value represents the item number of the radio button that is currently on: SInt32 controlValue; controlValue = GetControl32BitValue( myRadioButtonGroup ); After the control's value is obtained, take the appropriate action based on the returned value. For instance, in the case of a radio button group, a switch statement is used to carry out the task at hand: switch ( controlValue ) { case 1: // handle the first, or top, radio button being the one that's on break; case 2: // handle the second from top radio button being the one that's on break; } Book: Mac® OS X Programming Section: Appendix A. Carbon API Summary Menu Manager A program's menu bar is created using the Interface Builder Manager routine SetMenuBarFromNib. After that, application control of the menu bar and its menus and items is achieved through Menu Manager routines. The function prototypes for the Menu Manager routines are located in the Menus.h header file. The following sections describe the most commonly used menu-related types and functions. MenuRef: Referencing a Menu A menu and its items are referenced by way of a variable of type MenuRef. A MenuRef is the same as the older MenuHandle data type, so these two types can be used interchangeably. Creating a Menu Bar A menu bar is created by calling SetMenuBarFromNib to unarchive a menu bar resource stored in a nib file. Refer to the "Interface Builder Manager (Nib Files)" section of this appendix for more information. GetMenuHandle: Accessing a Menu Before altering the state of a menu or menu item, changing a menu item's characteristics, and performing similar tasks, your program needs a handle or reference to the affected menu. Call GetMenuHandle to obtain a handle or reference: MenuRef GetMenuHandle( MenuID menuID ); When editing the project's menu bar in Interface Builder, assign the menu an ID. Use this ID in the call to GetMenuHandle: #define kCalculateMenuID 106 MenuRef gCalculateMenu; gCalculateMenu = GetMenuHandle( kCalculateMenuID ); Disable/EnableMenuItem: Disabling and Enabling Menus To disable a menu item, call DisableMenuItem. To enable a menu item, call EnableMenuItem. Both are shown in the following code: void DisableMenuItem( MenuRef theMenu, MenuItemIndex item); void EnableMenuItem( MenuRef theMenu, MenuItemIndex item); Pass either routine a handle (reference) to the menu that holds the item to alter. You also pass the number of the item to alter. For instance, to disable the first item in a menu, pass a value of 1 for that item number: #define kCalculateMenuID 106 MenuRef gCalculateMenu; gCalculateMenu = GetMenuHandle( kCalculateMenuID ); DisableMenuItem( gCalculateMenu, 1 ); To disable an entire menu (the menu title and all menu item s in that menu), call DisableMenuItem with a value of 0 as the number of the item to disable. To enable and entire menu, call EnableMenuItem with a value of 0 as the number of the item to enable. The following code shows both actions: DisableMenuItem( gCalculateMenu, 0 ); EnableMenuItem( gCalculateMenu, 0 ); FMGetFontFamilyFontName: Obtaining a Reference to a Family of Fonts To change the font of a menu or menu item, you first need to obtain a reference to the family of the font to use. Note that a font exists as a family in that there are different sizes, and in some cases, different faces, associated with one font.) To get this reference, call FMGetFontFamilyFontName: FMFontFamily FMGetFontFamilyFromName( ConstStr255Param inName ); Pass FMGetFontFamilyName the name of the font of interest (Arial, Geneva, Times, and so forth), and the routine returns the font family reference associated with this name. This reference then is used as an argument to font-altering routines such as SetMenuFont. For legacy reasons, some API routines expect a string argument to be formatted as a Pascal string. FMGetFontFamilyName is such a routine. When passing a font name, preface the name with \p and enclose the string in quotation marks. The following code example returns a reference to the Verdana family of fonts: FMFontFamily fontFamily; fontFamily = FMGetFontFamilyFromName( "\pVerdana" ); SetMenuItemFontID: Changing the Font of a Menu Item The SetMenuItemFontID routine is used to change the font of a single menu item. Use SetMenuFont to change the font of all items in a menu. OSErr SetMenuItemFontID( MenuRef inMenu, SInt16 inItem, SInt16 inFontID ); Pass SetMenuItemFontID a reference (a handle) to the menu that holds the affected menu item. Then, pass the item number of the item. In this case, the first item in a menu will have an item number of 1, the second item will have an item number of 2, and so forth. Finally, pass the font family reference for the font to use. The following snippet sets the second menu item of the File menu to Times: #define kFileMenuID 101 #define kOpenMenuItem 2 MenuRef fileMenu; FMFontFamily fontFamily; fileMenu = GetMenuHandle( kFileMenuID ); fontFamily = FMGetFontFamilyFromName( "\pTimes" ); SetMenuItemFontID( fileMenu, kOpenMenuItem, fontFamily ); SetMenuFont: Changing the Font of an Entire Menu To change the font of all items in a menu, call SetMenuFont, as shown in the following code: OSStatus SetMenuFont( MenuRef menu, SInt16 inFontID, UInt16 inFontSize ); Pass SetMenuFont a menu reference (handle), a font family reference (obtained from a call to FMGetFontFamilyFromName), and a constant specifying the point size of the font. For instance, to change the font of all the items in the File menu to 24 point Arial, you'd use the following code: #define kFileMenuID 2 #define kMenuFontPointSize 24 MenuRef fileMenu; FMFontFamily fontFamily; fileMenu = GetMenuHandle( kFileMenuID ); fontFamily = FMGetFontFamilyFromName( "\pArial" ); SetMenuFont( fileMenu, fontFamily, kMenuFontPointSize ); Book: Mac® OS X Programming Section: Appendix A. Carbon API Summary QuickDraw Drawing to a window involves the Carbon API routines that are grouped in an area called QuickDraw. The function prototypes for the QuickDraw routines are located in the QuickDraw.h header file. The next sections describe commonly used QuickDraw routines. SetPortWindowPort: Specifying the Window to Draw To QuickDraw drawing routines draw to a port, which is a graphics environment capable of maintaining its own set of graphical information. Every window has its own port, as does the screen itself. Before drawing, call SetPortWindowPort to tell QuickDraw in which port (which window) to draw. void SetPortWindowPort(WindowRef window); MoveTo and Move: Specifying the Starting Point for Drawing Before drawing, specify in which window to draw by using SetPortWindowPort, and specify where within that window content area drawing is to take place. Call MoveTo to specify a starting location relative to the upper-left corner of the window in which drawing is about to occur: void MoveTo( short h, short v ); Pass MoveTo the number of pixels to move relative to the left side of the window and the number of pixels to move relative to the top of the window. To specify that drawing start 20 pixels from the left side and 60 pixels from the top of the content area of a window, call MoveTo like this: MoveTo( 20, 60 ); The Move routine is similar to MoveTo in that it specifies a starting point for drawing. Move, though, uses the current starting point as its reference. void Move( short h, short v); Move moves the starting location a number of pixels horizontally and vertically from the current location. Consider this snippet: [...]... appendix Book: Mac OS X Programming Appendix B UNIX and the Terminal IF YOU'RE MOVING TO MAC OS X from a UNIX background, you might have already discovered how to use your Macintosh to use UNIX to enter commands, create source code files, and build applications Someone like you might be able to skip this appendix You should be aware, though, that UNIX in Mac OS X does vary in some ways from other UNIX... happens to be a graphics-based shell rather than a textbased command line shell Most Mac OS X users won't be aware of the UNIX underpinnings of Mac OS X, and they won't be aware of the shell that enables access to the UNIX part of Mac OS X However, many power-users, and many programmers, will know (or will want to know) about UNIX and the shell In Mac OS X, you get to the shell by running the Terminal application... you'll be able to perform command-line UNIX programming, amaze your friends with your cross-platform programming skills, and pad your resume ( "Programming Experience By Platform: Mac OS, UNIX")! Mac OS X and UNIX As discussed in Chapter 1,"System Components and Programming Technologies," BSD is a variant of UNIX In Mac OS X, BSD is an important part of the kernel environment It supports key operating system... Figure B .10, the filename has been changed In addition, as also illustrated in Figure B .10, when I click the Mac OS X Finder window, the Finder window is updated to display the new filename as well Obviously, it's true that the Finder knows UNIX! Figure B .10 A renamed file has its new name displayed in the Aqua Finder Book: Mac OS X Programming Section: Appendix B UNIX and the Terminal UNIX Programming. .. directories, writing source code, and compiling that codeall from the UNIX command line Book: Mac OS X Programming Section: Appendix B UNIX and the Terminal UNIX and the UNIX Shell Darwin is Apple's name for the lowest level, or foundation, of the Mac OS X A big part of Darwin is Berkeley Standard Distribution (BSD) It is a popular version of UNIX BSD provides file system support, network services, multiprocessing... to know the details of the environment You need only know a few simple UNIX commands! Book: Mac OS X Programming Section: Appendix B UNIX and the Terminal UNIX Commands A UNIX shell (the Terminal is a UNIX shell) is a command-line interface that lets a user interact with UNIX by typing commands Knowing commands means knowing UNIX To run a command, you enter it in the shell A command often requires that... filename should have a c extension For g++, this filename should have a cpp extension This appendix's "UNIX Programming" section provides more information about compiling a C or C++ source code file in UNIX Here's the format of both the gcc and g++ commands: gcc -o programname Csourcecodefilename g++ -o programname C++sourcecodefilename Book: Mac OS X Programming Section: Appendix B UNIX and the Terminal... run on the Mac OS X After reading this section, though, you'll also be able to use your Macintosh to create programs that can run on your Mac and on any computer running UNIX These programs are true UNIX applications, so they won't sport the Aqua look, but then, UNIX isn't about a fancy interface anyway Get ready-with just several minutes of work, you'll be able to perform command-line UNIX programming, ... you reach the end of the online manual) apropos This command is especially useful for those new to UNIX Enter the apropos command (apropos being a French word loosely translating to "with regard to or concerning") followed by a keyword of your choosing The Terminal then will return a list of UNIX commands related to the keyword Find the command that most closely matches the action you have in mind, and... this appendix regardless of your level of expertise in UNIX On the other hand, if you're a long-time Macintosh user who is light on UNIX experience, you might never have created or edited a text file in UNIX, and you probably never ran a compiler from the command line You might not even know how to go about using a command line interface If any of this sounds like you, read this appendix In just a . appendix. Book: Mac OS X Programming Appendix B. UNIX and the Terminal IF YOU'RE MOVING TO MAC OS X from a UNIX background, you might have already discovered how to use your Macintosh to. users won't be aware of the UNIX underpinnings of Mac OS X, and they won't be aware of the shell that enables access to the UNIX part of Mac OS X. However, many power-users, and many. won't let a user directly alter OS code. The Finder is a shell. It just happens to be a graphics-based shell rather than a text- based command line shell. Most Mac OS X users won't