Cocoa® Programming

By Scott Anguish, Erik M. Buck, Donald A. Yacktman

Publisher: Sams Publishing
Pub Date: September 20, 2002
ISBN: 0-672-32230-7
Pages: 1272

Copyright

About the Authors

Acknowledgments

We Want to Hear From You!

Reader Services

Introduction

Intended Audience

Conventions

Learn By Example

Part I: Overview

Chapter 1. Cocoa and Mac OS X

Understanding When to Use Cocoa

Understanding Cocoa's Role in Mac OS X

What You Need to Use Cocoa

What's Included in Cocoa

Summary

Chapter 2. Cocoa Language Options

Object Orientation

Java

Objective-C

Other Languages

Choosing a Language for Use with Cocoa

The Use of Objective-C in This Book

Summary
 Chapter 3. Using Apple's Developer Tools

Obtaining Apple's Developer Tools

Project Builder

Interface Builder

Frameworks

Samples

Terminal

Other Tools

Summary

Chapter 4. Objective-C

Why Learn Objective-C?

Additions to C

Apple's Extensions

The NSObject Base Class

Runtime Functions

Objective-C++

Summary

Chapter 5. Cocoa Conventions

Naming

Initializers

Managing Memory

Accessors

Using Memory Zones

Encoding and Decoding

Summary

Chapter 6. Cocoa Design Patterns

Understanding Design Patterns

A Catalog of Cocoa Design Patterns

Summary

Part II: The Cocoa Frameworks

Chapter 7. Foundation Framework Overview

Mutability

Class Clusters

Typed Storage

Collections

Property Lists
 Run Loops and Timers

Support Types

String Processing

Bundles

File System Access

Defaults System

Notifications

Related Core Foundation

Summary

Chapter 8. The Application Kit Framework Overview

Events and the Run Loop

Responders

NSApplication Overview

NSWindow Overview

NSView Overview

Delegates

Target-Action Paradigm

Archived Objects and Nibs

NSWindowController Overview

Multidocument Applications

Undo and Redo

Menu Validation

Spell Checking

Summary

Chapter 9. Applications, Windows, and Screens

The New Image Viewer

Working with NSWindow

Working with NSApplication

Modal Loops

Working with Sheets

Working with Drawers

Working with Screens

Working with Panels

Summary

Chapter 10. Views and Controls

Controls

Simple Views and Controls

Container Views and Controls

 Compound Controls

Summary

Chapter 11. The Cocoa Text System

Using the High-Level Text Classes

The Text System Architecture

Managing Fonts

Text Input

Summary

Chapter 12. Custom Views and Graphics Part I

The Quartz Graphics Model

Quartz Graphics Via the Application Kit

Using the NSBezierPath Class

Modifying Drawing

Summary

Chapter 13. Custom Views and Graphics Part II

Using NSGraphicsContext

Coordinate System Transformations

Drawing Points and Rectangles

Optimizing Drawing

Summary

Chapter 14. Custom Views and Graphics Part III

Images and Bitmaps

Drawing Text

Summary

Chapter 15. Events and Cursors

Event Handling in Custom NSView Subclasses

Managing Cursors

Summary

Chapter 16. Menus

Standard Menu Layouts

NSMenu Class

NSMenuItem Class

Menu Validation

Contextual Menus

Dock Menus

Deprecated Functionality
 Summary

Chapter 17. Color

NSColor Class

Color Wells

Color Panels

Customizing the Color Panel

NSColorList Class

Summary

Chapter 18. Advanced Views and Controls

NSTableView, NSOutlineView, and NSBrowser Concepts

Table Views

Outline Views

Browsers

Combo Boxes

Custom Controls

Toolbars

Status Bars

NSQuickDrawView Class

Summary

Chapter 19. Using Pasteboards

Pasteboard Concepts

Implementing Cut, Copy, and Paste

Implementing Drag and Drop

Implementing Services

Summary

Chapter 20. Adding Online Help

Apple Help

ToolTips

Context-Sensitive Help (NSHelpManager)

Summary

Chapter 21. Multimedia

Sound

QuickTime

3D Graphics

Summary

Chapter 22. Integrating with the Operating System

 Getting System Information

Authentication and Security

Communicating with the Workspace

Summary

Chapter 23. Networking

NSURL and NSURLHandle

Email Messages

Directory Services

Interapplication Programming

Summary

Chapter 24. Subprocesses and Threads

Choosing Between Subprocesses and Threads

Using the NSTask Class

Using the NSThread Class

Locking

Threading Issues

Summary

Chapter 25. Printing

Basic Printing

Overview of the Printing Classes

NSView's Printing Support

Printing and Pagination Example

Printing in NSDocument-Based Applications

Summary

Part III: Cocoa Techniques

Chapter 26. Application Requirements, Design, and Documentation

Designing an Application with Requirements

Designing TransparentTetris

Implementing the Design

Using AutoDoc

Summary

Chapter 27. Creating Custom Frameworks

Creating and Using a Framework

Header Files

Providing Backward Compatibility

Debugging Frameworks
 Summary

Chapter 28. Distributing Applications

Package Directories

Using Disk Images

Application Installation

Summary

Part IV: Appendixes

Appendix A. Unleashing the Objective-C Runtime

Objective-C Objects

Messaging with IMPs and Selectors

Common Runtime Functions

Forwarding, Distributed Objects, and Proxies

Examples

Summary

Appendix B. Optimizing and Finding Memory Leaks

Optimizing Applications

Finding Memory Leaks

Summary

Appendix C. Finding Third-Party Resources

Apple-Provided Documentation

Example Code

Web Sites

Mailing Lists

Summary

Appendix D. Cocoa Additions in Mac OS X Version 10.2

Quartz Extreme

Handwriting Recognition

Address Book and vCard

Universal Access

Updated Tools

Framework Enhancements

Summary

Index
Book: Cocoa® Programming

Copyright
Copyright © 2003 by Sams Publishing

All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or
transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise,
without written permission from the publisher. No patent liability is assumed with respect
to the use of the information contained herein. Although every precaution has been taken in
the preparation of this book, the publisher and author assume no responsibility for errors or
omissions. Nor is any liability assumed for damages resulting from the use of the
information contained herein.

Library of Congress Catalog Card Number: 2001089381

Printed in the United States of America

First Printing: September 2002

05 04 03 02 4 3 2 1

Trademarks

All terms mentioned in this book that are known to be trademarks or service marks have
been appropriately capitalized. Sams Publishing cannot attest to the accuracy of this
information. Use of a term in this book should not be regarded as affecting the validity of
any trademark or service mark.

Warning and Disclaimer

Every effort has been made to make this book as complete and as accurate as possible, but
no warranty or fitness is implied. The information provided is on an "as is" basis. The
author(s) and the publisher shall have neither liability nor responsibility to any person or
entity with respect to any loss or damages arising from the information contained in this
book.

Credits

Executive Editor
Jeff Schultz

Acquisitions Editor

Betsy Brown

Development Editor

Susan Hobbs

Managing Editor

Charlotte Clapp

Project Editors

Elizabeth Finney

Katelyn Cozatt

Copy Editor

Chip Gardner

Indexer

Chris Barrick

Proofreaders

Andrea Dugan

Jody Larsen

Technical Editors

John Ray

Steve Munt

Team Coordinator
Amy Patton

Interior Designer

Gary Adair

Cover Designer

Alan Clements

Page Layout

D&G Limited, LLC

Book: Cocoa® Programming

About the Authors

Scott Anguish ([email protected]) started developing for the Macintosh in 1984.
Upon seeing the NeXT development environment in 1992 he was hooked on the
possibilities of a unified imaging model and a pure object-oriented system. In 1994, after
several years of NeXT development, he created Stepwise, a portal for information related
to NeXT technologies. Today, Stepwise serves as a hub for Apple's Mac OS X technology
platform as well as Cocoa and WebObjects development. During the day he works to build
better technology for the Center for Educational Technology at Middlebury College using
Cocoa and WebObjects, of course.

Erik M. Buck ([email protected]) is President of EMB & Associates, Inc., a

technology leader in the aerospace and entertainment software industries. He is a
contributor to Stepwise and has been developing software with Cocoa and its predecessor
technologies, OPENSTEP and NeXTSTEP, professionally since 1989. Mr. Buck holds a
BS in Computer Science from the University of Dayton.

Donald A. Yacktman ([email protected]) has been using Cocoa and its predecessor
technologies, OPENSTEP and NeXTSTEP, professionally since 1991. He is currently the
Vice President of Development at illumineX, inc. illumineX is both an independent
software vendor of Cocoa-based Mac OS X software and a WebObjects consulting firm.
Mr. Yacktman is a member of the Stepwise editorial staff and the principal contributor to
the MiscKit, a premier source of information and reusable software for the OPENSTEP
and Cocoa communities. He holds BS and MS degrees in Electrical and Computer
Engineering from Brigham Young University and has been programming professionally
since 1981.
Book: Cocoa® Programming

Acknowledgments
Scott Anguish

I would like to thank my wife Dorothy and my kids, Simon and Tori, for their love and
support while I was working on this project. This book would have been much thinner if
not for the heroic efforts of Don and Erik. I'd also like to thank the folks who contribute to
the community and Stepwise in particular. I too have a long list of Cocoa programmers and
developers who should be thanked both outside of Apple and within. I hope that we can
continue this journey of Cocoa development for years to come.

Erik M. Buck

I would like to thank my wife Michelle and family for their support, which made writing
the book both possible and enjoyable. I would also like to thank Don Yacktman, Scott
Anguish, and the many supportive people who contribute to Stepwise and the community
of Cocoa developers. Finally, I would like to thank the Cocoa programmers and enthusiasts
for whom this book was written. It is my sincere hope that this book will both accelerate
the process of learning Cocoa and help make using Cocoa fun.

Don Yacktman

I would like to thank my wife Marcie for her patience and support during the writing of this
book. The support of my entire family is also greatly appreciated. I would also like to thank
my co-workers at illumineX, especially CEO Gary Longsine, for their patience and
understanding. Without the support of Marcie and Gary, this book would not have been
possible. Many thanks are offered to the numerous friends at Apple who have taken time to
verify facts in this book. Finally, I would like to thank all the people who helped me learn
the skills used and described in this book. The people who have offered help and guidance
over the years are too numerous to list, but this book exists in part because of their
contributions.
Book: Cocoa® Programming

We Want to Hear From You!

As the reader of this book, you are our most important critic and commentator. We value
your opinion and want to know what we're doing right, what we could do better, what areas
you'd like to see us publish in, and any other words of wisdom you're willing to pass our
way.

You can email or write me directly to let me know what you did or didn't like about this
book-as well as what we can do to make our books stronger.

Please note that I cannot help you with technical problems related to the topic of this book,
and that due to the high volume of mail I receive, I might not be able to reply to every
message.

When you write, please be sure to include this book's title and authors as well as your name
and phone or email address. I will carefully review your comments and share them with the
authors and editors who worked on the book.

Email: [email protected]

Mail: Mark Taber

Associate Publisher
Sams Publishing
201 West 103rd Street
Indianapolis, IN 46290 USA
Book: Cocoa® Programming

Reader Services
For more information about this book or others from Sams Publishing, visit our Web site at
www.samspublishing.com. Type the ISBN (excluding hyphens) or the title of the book in
the Search box to find the book you're looking for.
Book: Cocoa® Programming

Introduction
Software development for Mac OS X can be a great joy. The advanced programming tools
and frameworks now provided by Apple astound many programmers. When programmers
delve into the object-oriented technology called Cocoa, which is part of every Mac OS X
system, they often describe the experience as life-changing. Claims of massive productivity
increases are common. Developers describe Cocoa as eye-opening. Cocoa demonstrates the
true power of object-oriented programming in a way that few programmers have
experienced when using other technologies. Cocoa enables programmers to focus on the
unique value of their applications by eliminating almost all the drudgery traditionally
necessary when making complex graphical applications. The Cocoa technology
exemplifies some of the best software design ever seen. Beyond providing tremendous
functionality out of the box, the Cocoa technology inspires programmers to follow Apple's
example and design excellent software.

Apple acquired much of the Cocoa technology in the last days of 1996 when Apple merged
with a company called NeXT. When first seen publicly in 1988, the technology was called
NeXTSTEP. Over the years NeXTSTEP became OPENSTEP, then Rhapsody, then Yellow
Box, and finally Cocoa. Each name change brought additional features and maturity. Apple
has significantly expanded and enhanced Cocoa for Mac OS X.

Although there are many ways to program an Apple computer, this book focuses on the
Cocoa environment. Using Cocoa is the most advanced and arguably the most productive
way to program a Macintosh-it's also the most fun. In presentations to developers, Apple
representatives describe Cocoa as the future. Apple recommends that all new software
development for the Mac use Cocoa.

This book contains all of the information necessary to build complex Cocoa applications.
The major Cocoa concepts are explained and demonstrated with example code. With this
book, an experienced developer can become immediately productive with Cocoa and Mac
OS X.
Book: Cocoa® Programming
Section: Introduction

Intended Audience

This book is intended for intermediate and advanced programmers who are familiar with C
programming and many of the concepts of object-oriented programming. No prior
experience with Mac OS X or other Apple products is required, but the reader must have
access to a computer running Mac OS X and the Apple-provided development tools to use
the example programs. Object orientation and a small set of object-oriented extensions to
the C language are explained in this book, but this book is not a substitute for a
comprehensive language reference or books solely dedicated to object technology. The two
computer languages that Apple suggests for use with Cocoa are Java and Objective-C. Java
is discussed, but the examples in this book are primarily implemented with Objective-C.
Objective-C is the language in which Cocoa was written, and the reasons for choosing
Objective-C are presented in the book.

Programmers familiar with other development technology including PowerPlant, Mac App,
MFC/Win32, and Java Swing might experience culture shock when first learning Cocoa.
Even though the core of Cocoa has been in use for more than a decade, it is still
revolutionary. Revolutions do not always occur without discomfort, but few programmers
ever look back after experiencing Cocoa. A common question posed after learning Cocoa
is "why haven't we been doing it this way all along."
Book: Cocoa® Programming
Section: Introduction

Conventions

The following typographical conventions are used throughout this book.

Italic type is used for introducing new terms and usage notes.

Monospace type is used for code examples, command-line output, filenames and file
system paths, data types, URLs, and symbolic constants.

Bold Monospace type is used for required user input in examples.

Italic Monospace type is used to designate a placeholder for user input.

Book: Cocoa® Programming
Section: Introduction

Learn By Example

Each major topic in this book is accompanied by a self-contained example. Examining and
modifying the examples is often the best way to learn a new development environment and
technology. Readers are encouraged to play with example code, experiment, and test their
understanding. In many cases, the code in the examples can be copied into a new project to
provide a jump-start. The authors have more than 30 years of collective experience with
this technology. The examples embody the best practices, common programming idioms,
and wisdom acquired by the authors.

There is a web site associated with this book at http://www.cocoaprogramming.net/. All the
example code found in this book and more can be obtained from the Web site. The code is
organized on the Web site by chapter and example name. Any updates to the material in
this book, including errata, can be found there.
Book: Cocoa® Programming

Part I: Overview
IN THIS PART

1 Cocoa and Mac OS X

2 Cocoa Language Options
3 Using Apple's Developer Tools
4 Objective-C
5 Cocoa Conventions
6 Cocoa Design Patterns
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 1. Cocoa and Mac OS X

IN THIS CHAPTER

● Understanding When to Use Cocoa

● Understanding Cocoa's Role in Mac OS X
● What You Need to Use Cocoa
● What's Included in Cocoa

Cocoa is a collection of software objects that implements almost all features common to
Mac OS X applications. Programmers extend the Cocoa objects to implement application-
specific features. The Cocoa objects are reused in every Cocoa application so that
programmers can concentrate on adding unique value with each line of code rather than
constantly reimplementing common features or struggling to access operating system
services. Significant applications can be built with very little code.

Cocoa is the result of continuous evolution from the software development environment of
NeXTSTEP, which was first released to the public in 1988. Cocoa takes advantage of
common object-oriented design patterns and best practices. In fact, many of the common
design patterns were first recognized in NeXTSTEP. Cocoa design patterns are described
in Chapter 6, "Cocoa Design Patterns."

Cocoa is distinguished from other object-oriented development environments in several

ways: Cocoa is mature, consistent, and broad. Cocoa is based on a cross-platform
specification and has evolved from a cross-platform implementation. Cocoa is
extraordinarily extensible, flexible, and dynamic in part because of Objective-C, the
language used to implement it. Objective-C is described in Chapter 4, "Objective-C."
Cocoa emphasizes the reuse of objects, dynamic loading of objects, and messaging
between objects.

Many developers enjoy huge programmer productivity improvements by using Cocoa

instead of other technologies. Several ground-breaking applications were originally
developed with NeXTSTEP, including Apple's own Interface Builder, Lotus Improv, and
the first World Wide Web browser. The initial implementations of the famous games
Doom and Quake, and the custom development tools for the games were written using the
predecessors to Cocoa. Developers such as Tim Berners-Lee, who invented the World
Wide Web, claim that they could not have created cutting edge applications as easily if
they had to use other technologies. The obstacles to overcome in other environments would
have hampered the innovations.
NOTE

Screen shots of the first Web browser and commentary from Berners-Lee are
available at http://www.w3.org/People/Berners-Lee/WorldWideWeb.html.
Book: Cocoa® Programming
Section: Chapter 1. Cocoa and Mac OS X

Understanding When to Use Cocoa

To understand why you would choose to use Cocoa, it is necessary to briefly explain the
alternatives. Apple supports three principal software development environments for
producing Mac OS X applications. The supported environments are Cocoa, Carbon, and
100% Pure Java. Each environment has strengths and weaknesses, and a developer's choice
of environment is influenced by many factors.

Carbon

Carbon consists primarily of a subset of the traditional procedural Application

Programming Interfaces (API)s used to program Mac computers. Apple updated, and in
some cases, enhanced the C libraries used to program Macs before OS X. Carbon provides
access to the modern and powerful features of OS X in a way that preserves compatibility
with most of the software written for earlier Mac operating systems. Applications written
using Carbon work on Mac OS 8 or Mac OS 9 with compatibility libraries installed, and on
Mac OS X. Apple provides a free application called CarbonDater that analyzes software
for compatibility with Carbon. In many cases, programmers can easily convert old
applications written for the Mac to work with Carbon on OS X.

Cocoa applications do not work with Mac operating systems prior to OS X. If compatibility
with Mac OS 8 or 9 is required, Carbon might be the best choice. On OS X, one advantage
of Cocoa is that Cocoa programs written with the Objective-C language can freely call the
C-based Carbon APIs. It is much more difficult for Carbon applications to benefit from
Cocoa features. In some cases, Apple has already implemented Cocoa objects that shield
programmers from underlying Carbon implementations.

The difficulty accessing Cocoa features from Carbon is expected to decline over time.
Carbon is slowly gaining access to traditional Cocoa features. Cocoa solutions to common
programming problems are preferred, and Apple has already exposed some parts of Cocoa
to Carbon programs. For example, the Core Foundation API is used extensively in Carbon
applications. Core Foundation is a procedural interface to the features of Cocoa objects. In
some cases, Core Foundation functions are derived from previously private internal
implementations of Cocoa objects.

Java

Java is both programming language and a set of cross-platform libraries. Mac OS X comes
with a complete implementation of Sun's Java 2 Standard Edition version 1.3.1. Apple's
Java Virtual Machine was developed in cooperation with Sun and uses many Sun
technologies including Sun's Hot Spot JIT (Just In Time) compiler. 100% Pure Java
applications can be developed on OS X using Apple's developer tools or third-party tools.

100% Pure Java applications are portable to many different operating systems. If
portability is the primary requirement for a software project, 100% Pure Java might be the
best development technology.

Java can be used to develop Cocoa applications, but the resulting applications only work on
Mac OS X. The objects that comprise Cocoa are written in Objective-C, but Apple
provides a technology called the Java Bridge that enables relatively seamless use of Cocoa
objects from Java code and vise versa. Objective-C was one of the major influences that
shaped the design of the Java language. Java and Objective-C have many similarities under
the surface. Using Java to write Cocoa applications is explained in more detail in Chapter
2, "Cocoa Language Options."

Cocoa

Cocoa is the most mature development environment for OS X, as well as the most
productive technology for implementing many types of applications. The cheapest, fastest,
and most bug-free lines of code in any application are the lines a programmer didn't have to
write. Cocoa's pervasive use and reuse of objects dramatically reduces the number of lines
of code in applications. By following the example set by Cocoa, many developers achieve
high levels of reuse with their own custom objects.

A simple comparison is the TextEdit application shipped with OS X versus the SimpleText
Carbon example that Apple provides with their developer tools. TextEdit is a Cocoa
application implemented in 1354 lines of code, whereas SimpleText is implemented in
5231 lines of code. TextEdit has many more features and fewer limitations than
SimpleText, yet TextEdit requires approximately 1/4 the number of lines of code. Cocoa
programmers often claim a 5-1 productivity advantage over alternative technologies,
however, the TextEdit verses SimpleText comparison indicates a much greater advantage
than 5-1.

Cocoa is the most flexible software development technology for Mac OS X. Cocoa is
written in Objective-C, and that provides several advantages. Objective-C is a small
superset of ANSI C. Objective-C programs can seamlessly use all the C libraries available
in OS X, including Carbon and traditional Unix libraries. A variant of Objective-C called
Objective-C++ includes support for direct use of C++ libraries along with Cocoa. Apple's
Java bridge technology enables Java programs to use Cocoa, and allows Objective-C
Cocoa applications to use existing Java libraries. Apple has even provided access to Cocoa
from AppleScript, therefore, it is possible to write full-featured applications using
AppleScript and Cocoa. Cocoa is the only development environment for Mac OS X that
directly enables use of all other system components.

Cocoa is the most extensible software-development technology for Mac OS X. It is

possible to add features to the objects provided by Cocoa without access to the source code
for Cocoa. All Cocoa applications can take advantage of the addition without even being
recompiled. It is possible to selectively replace Cocoa objects with custom versions. Cocoa
provides powerful features for dynamically loading objects such as plug-ins. The dynamic
loading capabilities of Cocoa are only partly available to Carbon programs. It is even
possible to completely change the user interface of a Cocoa application without access to
the application's source code.
Book: Cocoa® Programming
Section: Chapter 1. Cocoa and Mac OS X

Understanding Cocoa's Role in Mac OS X

Mac OS X traces its heritage to earlier Mac operating systems and to versions of Unix.
Mac OS X melds the two operating systems into one.

Mac OS X uses the layered architecture shown in Figure 1.1. Cocoa is implemented to
enable access to all the features of OS X. Cocoa applications can use the Quartz, OpenGL,
and QuickTime graphics systems supported by Mac OS X. Cocoa provides high-level,
object-oriented components that use Quartz and advanced font rendering capabilities built
on top of Quartz. Cocoa objects exist to access OpenGL and QuickTime. Traditional Mac
features are accessed through objects that internally use the Carbon API. Cocoa directly
uses features provided by Darwin.

Figure 1.1. Mac OS X uses a layered architecture.

Cocoa contains objects that use the networking and file system features of Darwin. Many
Cocoa objects are implemented to use the Core Foundation components of Darwin. The
Objective-C language runtime used by Cocoa is implemented in Darwin.

Quartz

Quartz is the term used to collectively identify the advanced 2D graphics capabilities of OS
X, which are built on top of Darwin. Quartz consists of a window server process and a
powerful library of 2D drawing functions based on Adobe's PDF imaging model.
The window server is a process that runs in the background and controls display access by
applications. The window server provides device-independent color capabilities and color
correction for displays. The window server manages the layering of windows owned by
different applications and implements features such as translucency and live-window
dragging. The window server can reposition windows, apply translucent drop shadows, and
layer translucent windows without interrupting other applications. The window server also
provides limited direct access to the video frame buffer for games, OpenGL, and
QuickTime.

In addition to the window server, Quartz provides a graphics-programming API called

Core Graphics. Core Graphics provides functions and data types that can be used from any
of the programming environments supported by Mac OS X. In essence, Core Graphics is
an API for producing graphics compatible with the powerful cross-platform Portable
Document Format (PDF) standard from Adobe.

Core Graphics provides device-independent vector and bitmap graphics operations with
support for antialiasing and transparency. Core graphics has set a new high standard for the
presentation quality of graphics on a computer screen. Almost any graphics drawn with
Core Foundation can be saved as PDF files for viewing on any computer with a PDF
viewer. PDF is rapidly becoming the preferred format for What You See Is What You Get
(WYSIWYG) printing and publishing.

Cocoa's use of Quartz and 2D graphics is described in Chapter 12, "Custom Views and
Graphics: Part I," through Chapter 15, "Events and Cursors."

OpenGL

OpenGL is a standard cross-platform API for hardware accelerated 2D and 3D graphics.

Mac OS X features optimized OpenGL drivers, and every recent Mac computer ships with
hardware accelerated 3D graphics support. OpenGL is one of the most widely adopted
graphics standards. It is available for Unix and Microsoft Windows in addition to OS X.
Code that uses OpenGL can be very portable and produces consistent results across many
platforms. OpenGL is frequently used to implement games, medical imaging software, and
engineering applications. Cocoa includes an object for interfacing with OpenGL.

QuickTime

QuickTime is an Apple proprietary cross-platform technology for creating and presenting

video, animation, sound, music, and virtual reality environments. QuickTime is extensible
and supported for versions Mac OS 8 and higher, as well as all recent versions of Microsoft
Windows. Mac OS X provides up-to-date QuickTime support including programming
APIs, real-time streaming, and viewers.
QuickTime supports common graphics file formats for still images and video. QuickTime
can be used with popular Internet protocols for streaming media, and plug-ins exist for
most Web browsers including Internet Explorer, Netscape Navigator, and America Online.
Cocoa provides an object that enables the use of QuickTime from Cocoa applications.
Apple provides sample reusable objects that extend Cocoa's built-in support for QuickTime
and enable the creation of simple movie editors without writing any code at all.

Darwin

Darwin is Apple's name for the lowest-level components in Mac OS X. Cocoa is

implemented using the features of Darwin. Darwin consists of components that provide
core essential services. The Mach kernel is the heart of Darwin. Device drivers, file
systems, networking, Unix APIs, support for kernel extension, the Objective-C language
runtime, and key programming APIs are all part of Darwin.

Darwin source code is available from Apple under the terms of Apple's flexible open-
source license. By registering with Apple, any developer can download the Darwin source
code. Ports of Darwin already exist for the Intel x86 family of processors. By making
Darwin open source, Apple has empowered the broad community of Unix developers to
inspect and enhance the lowest-level core of Mac OS X. Third-party developers have
already contributed security enhancements and other features back to Apple.

Mach

Mach is the core of Mac OS X, and every software development technology in Mac OS X
uses the features of Mach. The version of Mach used in OS X is based on Mach 3.0. Mach
schedules CPU usage, supports symmetric multiprocessing with multiple CPUs, provides
memory protection and dynamic virtual memory, provides real-time features, and
implements an interprocess messaging system used by higher-level components to
interface with the kernel.

Cocoa objects that manage processes, threads, and interprocess communication use
features of Mach directly in their implementations. All Cocoa objects benefit from the
memory protection, dynamic virtual memory, and real-time features provided by Mach.

Device Drivers

In some cases, Cocoa objects use the features of operating system device drivers directly.
For example, Cocoa provides support for digital graphic tablets, mouse scroll wheels, and
multiple mouse buttons by interoperating with the relevant device drivers. Device drivers
for OS X are built as Mach kernel extensions. New device drivers can be dynamically
loaded into a running Mach kernel. There is no need to recompile the kernel or even shut
down the machine to install new device drivers.

BSD
Many Cocoa objects use traditional Unix features in their implementation on Mac OS X.
The Darwin component called Berkley Standard Distribution (BSD) refers the University
of California-Berkley standard distribution of Unix. The Berkley variant is one of the
major branches on the Unix family tree. Several free implementations of BSD Unix are
available. Apple uses code from some of the free versions in OS X and has contributed
back to them as well. Mac OS X's Unix features are principally based on standard BSD 4.4
with networking components from FreeBSD 3.2.

Networking

Cocoa provides objects that enable seamless access to networking features of the operating
system. Darwin includes networking support implemented as extensions to the Mach
kernel. Most of the networking components are based on the network support architecture
implemented in FreeBSD 3.2. Most of the POSIX standard API to access networking
features via sockets is supported. Sockets-based communication originated with early
versions of BSD Unix and has since become the most common technique. Sockets are
supported by every recent version of Unix and Microsoft Windows.

File Systems

Cocoa relies on Darwin for file system support. Cocoa provides objects that abstract file
system-specific issues. Cocoa programs work regardless of the underlying file system. The
abstraction is particularly important because modern operating systems such as Mac OS X
support so many different file systems. Avoiding the need to write code to handle different
file system issues is an advantage of Cocoa.

Darwin includes advanced file system support implemented in a layer outside the Mach
kernel. Mac OS X already supports Unix File System (UFS), Hierarchical File System plus
(HFS+), ISO 9660, File Allocated Table (FAT), Network File System (NFS), Web-based
Distributed Authoring and Versioning (WebDAV), and Universal Disk Format (UDF).
UFS is a common Unix file system. HFS+ is the native file system used by prior Mac
operating systems. HFS+ is the file system recommended by Apple because it best
preserves compatibility with software written for prior Mac operating systems. The ISO
9660 file system is standard and commonly used on CD-ROMS. The FAT file system is
used by Microsoft DOS and some Microsoft Windows installations. NFS implements a
standard protocol for accessing file systems on one machine from another over a network.
WebDAV is the file system implemented as extensions to the HTTP protocol. Apple uses
WebDAV to provide remote access to each user's iDisk. An iDisk is simply storage
allocated on a hard disk on a server at Apple. Mac users can use the storage to share files
with other people over the Internet. UDF is a file system intended to replace the ISO 9660
file system. UDF is primarily used on DVDs.

Objective-C Runtime
One of the most critical features of Darwin that is used by Cocoa is Apple's Objective-C
runtime. Cocoa is written in Objective-C. Apple uses the open source GNU Compiler
Collection (gcc) compiler and provides the basic compiler and development tools for use
with Darwin as a free download in source code or binary form. gcc is part of the Free
Software Foundation's GNU project. The gcc compiler collection comes with Objective-C
support, and a GNU Objective-C runtime that is slightly different from the one shipped
with Apple's Darwin. Apple has stated plans to keep their own version of gcc synchronized
with the standard GNU version and possibly unify the two Objective-C runtimes in the
future.

Parts of Core Foundation

Darwin includes part of the implementation of the Core Foundation procedural APIs. Core
Foundation is used by many of the higher-level APIs of Mac OS X includ-ing Cocoa.
Chapter 7, "Foundation Framework Overview," includes a brief introduction to the Core
Foundation. The fact that some source code for Core Foundation is available with Darwin
opens opportunities for third parties to inspect and enhance key elements of OS X's
software development infrastructure.
Book: Cocoa® Programming
Section: Chapter 1. Cocoa and Mac OS X

What You Need to Use Cocoa

Apple provides everything needed to develop Cocoa applications for Mac OS X. Apple's
developer tools are shipped on a CD-ROM in the same box with the Mac OS X operating
system CD-ROM. Cocoa can be used with Java, AppleScript, C++, and other languages,
but knowledge of C is required in most cases. The Cocoa objects are written in Objective-C.

This book provides an introduction to Objective-C for programmers who are already
familiar with C. Objective-C consists of a small set of extensions to ANSI standard C. C
programmers with experience using one or more object-oriented languages can learn
Objective-C very quickly. When Objective-C is familiar, the more daunting task of
learning the large and sometimes complex Cocoa frameworks begins.

The Cocoa frameworks are an excellent example of the power of object-oriented

programming and Objective-C. Even though Cocoa is large and provides many features, it
is consistent. The consistency helps programmers learn new parts of Cocoa by extending
knowledge already gained. After a while, programmers often find themselves reusing
Cocoa designs and programming idioms in their own code. Many programmers reaction to
Cocoa is "why was software ever written another way?"
Book: Cocoa® Programming
Section: Chapter 1. Cocoa and Mac OS X

What's Included in Cocoa

Cocoa is composed of frameworks that contain libraries of objects and related resources,
data types, functions, header files, and documentation. The two major Cocoa frameworks
are the Foundation framework and the Application Kit framework. Figure 1.2 shows the
Cocoa frameworks and the Mac OS X system components used by the frameworks.

Figure 1.2. Cocoa contains layered frameworks of objects.

The Foundation framework, shown in Figure 1.2, contains nongraphical objects that are
useful in every Cocoa application. The Foundation framework uses the services provided
by Darwin, and provides a foundation for other frameworks and applications to extend.

The Application Kit framework is built using the Foundation framework and OS X's
graphics services that are, in turn, built on top of Darwin. The Application Kit provides
graphical objects and graphical user interface elements. The Application Kit framework
provides the look and feel of Mac OS X Cocoa applications. The Yellow Box version of
the Application Kit provided Microsoft Windows, OpenStep, or traditional Mac OS looks
on each platform, but the Application Kit on OS X only supports Apple's Aqua look and
feel.

Cocoa is implemented in Objective-C. Objective-C is a dynamic language that supports a

style of flexible programming well-suited to creating reusable objects and accommodating
evolutionary change. Cocoa applications consist of interconnected objects. Apple provides
some of the objects, and others are provided by other vendors. Finally, applications contain
custom application-specific objects. The objects communicate with each other by sending
messages, and all objects are equal. The objects that Apple provides are not special in any
way. Custom objects, third-party objects, and Apple's objects all work together even
though they are developed independently.
Apple provides several applications that contribute to the productivity of Cocoa
programmers. Not surprisingly, most of Apple's own developer tools are Cocoa
applications. Mac OS X is built using Cocoa applications. Even the Apple tools used to
write Carbon and Java programs are Cocoa applications.
Book: Cocoa® Programming
Section: Chapter 1. Cocoa and Mac OS X

Summary

Cocoa is an advanced, mature, flexible, and extensible software development technology

that uses frameworks of objects and related resources. Cocoa has a legacy of cross-
platform support. Cocoa applications have access to all features of Mac OS X. Cocoa
provides large programmer productivity advantages compared to other technologies
available for software development on Mac OS X, but Cocoa applications only run on Mac
OS X. Carbon and 100% Pure Java are alternative technologies that support multiple
platforms.

The rest of this book explores Cocoa software development in detail. You'll start with
Chapter 2, "Cocoa Language Options," which covers the range of languages used to
develop Cocoa applications.
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 2. Cocoa Language Options

IN THIS CHAPTER

● Object Orientation
● Java
● Objective-C
● Other Languages
● Choosing a Language for Use with Cocoa
● The Use of Objective-C in This Book

Cocoa is a collection of object-oriented components written in the Objective-C language.

Objective-C is a flexible and dynamic language that adds object-oriented extensions to
ANSI standard C. Because of the flexibility of Objective-C, the Cocoa components can be
used by a wide variety of languages besides Objective-C. The key language elements
needed to use Cocoa are support for dynamic object orientation and compatibility with the
C programming language.

This chapter describes the general features of all languages that can be used with Cocoa,
and a brief overview of object-oriented terminology. Details about the most common
languages used with Cocoa are provided. The available language options are explained
along with some of the advantages and disadvantages of different languages. This book
primarily uses the Objective-C language, and this chapter explains why.

Java and many scripting languages provide the required language features to use Cocoa
directly. Other languages such as C and C++ are not sufficiently dynamic to use Cocoa
objects directly. C and C++ programs can access Cocoa in two ways: They can use Cocoa
indirectly via the C-based Objective-C runtime, or they can be recompiled using the
Objective-C and Objective-C++ language compilers.

Details about using the Objective-C runtime from C or C++ without using the Objective-C
language syntax are provided in Appendix A, "Unleashing the Objective-C Runtime."
Because Objective-C is an extension of standard C and can compile all C programs, the
best way to use Cocoa from C code is to actually use Objective-C. Parts of a program can
be standard C (perhaps for portability reasons), whereas other parts can use Objective-C's
object-oriented extensions to access Cocoa. A variant of Objective-C called Objective-C++
provides the same object-oriented extensions to C++ that Objective-C provides to standard
C. The best way to mix C++ code and Cocoa is to use Objective-C++.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Object Orientation

Cocoa is a collection of objects. To understand how various languages use Cocoa, a brief
explanation of objects and object orientation is needed. Object-oriented languages must use
objects in a way that is compatible with Cocoa to be integrated with Cocoa. For example,
Java is an object-oriented language that interfaces well with Cocoa. C++ is an object-
oriented language that provides a model of objects incompatible with Cocoa.

The goals of object orientation are to make writing software easier, cheaper, and faster. The
principal way that object orientation achieves its goals is through software reuse. The idea
is that software can be organized into objects that are individually reusable. Each time a
new software project begins, substantial parts of the project can be implemented using
existing software objects. In theory, the only new code that is written for a project is the
code that is truly unique to that project and cannot be shared by other projects.

By reusing objects, programmers hope to reduce the amount of new code written for each
project and, therefore, finish the project faster. Reused objects are already well-tested in
other projects. By reusing objects, programmers avoid bugs that might be created in new
code. Existing objects that implement complex logic are used to make creating software for
a new project easier. The idea is that the most complex and difficult to write code is
provided by existing objects. Reusing objects is simpler than rewriting the logic
implemented by the objects.

Encapsulation

Encapsulation is one of the principal ideas of object orientation. Encapsulation means that
data and the logic that operates on the data are grouped together. Data is only modified via
the operations encapsulated with the data. Encapsulation aids reuse and simplifies software
maintenance. Encapsulation also ensures that related data and logic can be easily identified
in one project and reused in another. Because data and logic are encapsulated together, it is
not necessary to grab a line of code here and a data structure definition there, or search all
the source code in a project for necessary lines of code to reuse just one feature of a
project. Encapsulation aids software maintenance by localizing problem solutions. If a bug
is detected, or a new feature must be added, encapsulation ensures that there is only one
place in the code where changes are made. Without encapsulation, fixing a bug, or adding a
feature might require changes to many different parts of a software project.

Modularity

Modularity is related to encapsulation. Modularity is the practice of implementing a

software project in multiple modules. A module is a self-contained input to a compiler. The
idea is that modules of code and data can be developed and compiled independently. The
separately compiled modules are brought together to complete a project. In many cases,
each module encapsulates some data and logic. Apple's Objective-C compiler enables the
use of multiple modules to encapsulate one set of data and operations. It is also possible to
implement multiple units of encapsulation in one module, but it is usually a bad practice.

Classes

In most object-oriented languages, something called a class is the basis of encapsulation.

Each class encapsulates some data and all operations upon that data. Operations on data are
sometimes called behaviors. Classes are implemented in one or more modules. Classes
formalize the ideas of encapsulation, and in some languages the compiler enforces that
encapsulation. The compiler prevents code that is not part of a class from modifying the
data managed by the class. Classes are related to instances and inheritance.

Instances

A class is in some respects an abstract idea. A class describes data and operations on that
data, but a class by itself is usually just an idea. For example, imagine a class called
Control that describes certain characteristics of all graphical user interface elements.
Those characteristics might include color and position. The class Control is not any
particular user interface element, it describes all user interface elements. A particular
button is an "instance" of the class Control. An instance of the class Control has a
color and a position as described by the Control class.

A class describes data and behavior. An instance actually stores the data described by a
class. There can be any number of instances of a class. The behaviors defined in a class are
applied to instance's data.

NOTE

You will learn more about abstract classes and abstract Cocoa classes in
Chapters 4 and 7. Chapter 4 also introduces the details of Objective-C as well
as class methods versus instance methods. If these concepts are confusing to
you now, you'll get more details in these two chapters.

Objects

Both classes and instances can be called objects. Classes are objects that describe instances.
Instances are objects that store data described by a class. Object is a general term that
applies to encapsulated data and logic and has different implications in different languages.
Almost every object-oriented language endows objects with capabilities beyond just
encapsulation, such as support for specialization.

Specialization

Object orientation promotes software reuse. Software objects from one project can be used
in another project. But what happens when a new project needs an object similar to one that
already exists, but needs just a few changes? The existing object can be specialized rather
than starting from scratch to create a new object that meets the exact needs of the new
project. Specialization is a technique for altering parts of the data and behavior of an
existing object while reusing other parts. There are two types of specialization: instance-
based and class-based. Cocoa uses both class-based specialization and instance-based
specialization extensively.

Instance-based specialization is a technique for changing the behavior of just one instance
object without necessarily modifying the behavior of other instances of the same class.

Class-based specialization applies changes to classes. The most common technique is to

create a new class that includes all the data and operations of another class while adding
additional data and new behaviors. Instances of the new class store the additional data and
have the additional behaviors along with the data and behaviors of instances of the original
class.

Inheritance

Inheritance is the most common form of class-based specialization. If a class called

Button includes the data and behaviors of class Control, class Button is said to
inherit from class Control. The terms subclass and superclass describe the inheritance
relationship. Button is a subclass of Control. A subclass inherits all of the data and
behavior of its superclass. In this example, Control is Button's superclass. If class
Button inherits from class Control, an instance of Button can be used in any context
that an instance of Control is required.

Some languages such as C++ support multiple inheritance. Multiple inheritance means that
a class has all the data and behavior described by two or more super classes. Java and
Objective-C do not support multiple inheritance, and Cocoa does not use multiple
inheritance.

Messages

Messages are one way that objects can communicate with each other. Messages enable
objects to request that other objects invoke behaviors. A user interface object might send
the isEnabled message to a Control instance as a way to request that the Control
instance returns a YES or NO value. A message is an abstract idea and few assumptions are
made about messages. For example, a message can be sent to an anonymous object. The
sender of the message might not know the class of the receiver. The receiver might not
even be in the same program as the sender. Messages promote object reuse by minimizing
the dependencies between objects. The less one object knows about another, the better
chance the objects can be reused separately. Messaging enables communication between
objects without dependencies.

Many object-oriented languages do not directly support messaging. Messaging is one of the
dynamic features of Objective-C that are essential to the implementation of Cocoa.
Messaging is described in Chapter 4, and the technical implementation of messaging is
described in Appendix A.

Polymorphism

Polymorphism is another technique that enables the reuse of software objects.

Polymorphism allows the software that uses an object to work regardless of the specific
class of the object. In other words, polymorphism enables an object to send the same
message to different receivers without knowing precisely what behavior will be invoked by
the message when it is received.

All messages in Objective-C use polymorphism. In many cases it is not possible for the
sender of an Objective-C message to know the class of the object that receives the
message. Each receiver will invoke different behaviors upon receipt of the message. Java
and C++ also support polymorphism to various degrees. Along the spectrum of flexibility,
C++ compilers require detailed knowledge about all objects whose behaviors are used.
Objective-C does not require any knowledge about the objects that are used at compile
time. Java falls between the two extremes.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Java

Java is one of the most popular programming languages used today. The designers of Java
credit Objective-C as one of the influences that led to the creation of Java. In addition to
the Java language syntax, Java provides standard libraries of objects and a standard runtime
environment called the Java Virtual Machine (JVM). Apple supports the use of Java when
creating Cocoa applications. Java implements classes, inheritance, and polymorphism in
ways that are compatible with Cocoa. Java has several compelling features not shared by
other languages used with Cocoa.

Automatic Garbage Collection

Dynamic memory management is one of the most difficult aspects of programming. The
Java language and the JVM include technology called automatic garbage collection.
Automatic garbage collection is a technique for automatically reusing dynamically
allocated memory that is no longer being used by the objects that reserved it. Java
programmers can usually ignore the issues of dynamic memory management because the
language and JVM take care of that for them. However, to get the best possible
performance with Java applications, programmers must still be sensitive to dynamic
memory allocation issues. Objective-C does not have the same degree of support for
automatic garbage collection.

Interfaces

Java includes a language feature called an interface. An interface specifies a set of

behaviors that an object can invoke. Objects can have multiple interfaces. To promote
reuse of objects, it is important that each object depend as little as possible on other
objects. Java interfaces can be used to minimize the dependencies between objects. A Java
object can be constructed so that it works with any other object that implements a particular
interface without needing to know the class or other information about the other object.
The less an object knows about other objects, the less likely it is to depend on the other
objects.

Java interfaces are similar to Objective-C protocols. Cocoa uses protocols extensively.
When Java is used with Cocoa, many of Cocoa's protocols are accessed with equivalent
Java interfaces.

Security and Safety

Security was one of the design goals of Java. The JVM ensures that Java objects
downloaded over the Internet cannot directly harm the computer on which they are run.
Most computer languages do not have any security features and, therefore, it is not as safe
to download and use objects written with other languages.

The Java Bridge

Apple provides a technology called the Java Bridge. The Java Bridge enables seamless
interaction between Java objects and the Objective-C-based Cocoa objects. Java objects
can specialize Objective-C objects. The Java Bridge handles issues such as the different
dynamic memory management conventions between Java and Objective-C. Java programs
that use Cocoa objects only run on Mac OS X.

100% Pure Java

Java is a cross-platform language because of the Java Virtual Machine. Any computer with
a recent version of the JVM can run Java programs even if the programs were written on a
different type of computer. Mac OS X includes an up to date JVM implementation and
standard libraries.

Java programs that only use Java's standard libraries are called 100% Pure Java programs.
Such programs run on any computer with an up to date Java implementation. Mac OS X is
an excellent platform for writing 100% Pure Java applications. However, if a Java program
uses Cocoa, it will not work on operating systems other than Mac OS X.

JavaBeans

The Java language includes JavaBeans, which are a standard for loading objects into
running programs. The standard Java libraries include features for loading JavaBeans as
well as identifying the interfaces and behaviors that the loaded JavaBeans support.
JavaBeans have many features in common with a Cocoa technology called bundles.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Objective-C

Cocoa is implemented with Objective-C. Chapter 4, "Objective-C," describes Objective-C's

object-oriented additions to the standard C language. This chapter provides information
intended to help developers select a language to use with Cocoa. Some of the features of
Objective-C not shared by the other languages used with Cocoa are presented here to aid
the comparison of languages. The details are not presented until Chapter 4.

Categories

Categories are an Objective-C feature that enables the specialization of classes without
using inheritance. Categories can be used to add behaviors to existing classes without
recompiling them. The instances of specialized classes gain the new behaviors. Even pre-
existing instances and instances created and used entirely within the implementations of
Cocoa classes gain the new behaviors. Categories and their many advantages are used and
described throughout this book. Chapter 26, "Application Requirements, Design, and
Documentation," includes detailed analysis of the use of categories when designing an
application.

Protocols

Objective-C protocols are similar to Java interfaces. Protocols specify the behaviors
provided by objects independent of the class of the objects. Cocoa contains many protocols.

Perform

Objective-C objects can be asked to invoke behaviors in a dynamic way. For example, a
program can accept input from a user that specifies a behavior to invoke in a running
application. The capability to ask an object to invoke a behavior without the aid of a
compiler contributes to the integration of Cocoa with scripting languages.

Posing

Posing is the capability to universally substitute one class for another. Every time an
attempt is made to create an instance of a class, an instance of the posing class is created
instead. Posing classes even work with compiled libraries such as Cocoa. If a Cocoa
application includes an object that poses as a Cocoa object, the posing class is used instead
of the original class in every case. Posing is a feature of Objective-C that conflicts with
Java's security features and should not be used in Java Cocoa applications.
Runtime

Objective-C includes a runtime system similar in many ways to the Java Virtual Machine.
Objective-C's runtime provides many of the dynamic features of Objective-C and enables
the dynamic loading of Objective-C objects. Unlike the JVM, Objective-C's runtime is
small and does not provide cross-platform support or security features. Objective-C's
runtime is written in standard C and can be used from C or C++ programs even if those
programs are not compiled with an Objective-C or Objective-C++ compiler.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Other Languages

Objective-C and Java are the two languages most commonly used with Cocoa, but many
other languages operate with Cocoa to varying degrees. The languages used with Cocoa
fall into two major categories: languages based on C and scripting languages.

ANSI C and C++

As mentioned previously, Cocoa is written in Objective-C, which is based on ANSI C. As

a result, other languages that are based on C can be used with Cocoa. There are two
strategies for using languages based on C with Cocoa. One strategy is to use only the C
interface to the Objective-C runtime and a standard C or C++ compiler. The other is to use
an Objective-C or Objective-C++ compiler to compile C or C++ code.

It is possible to write an ANSI C program that uses most features of Cocoa, and compile
that program with a standard C compiler. The Objective-C runtime's C interface includes
functions for creating and sending messages to Cocoa objects. As a superset of C, the C++
language can use the same techniques to access Cocoa objects.

The easiest way to use Cocoa from C programs is to use the Objective-C compiler to
compile the standard C code along with modules containing Objective-C code. Apple
provides an Objective-C++ compiler that enables the mixture of C++ code and Objective-C
code in the same module.

Scripting Languages

Scripting languages usually have a runtime that can be interfaced with Cocoa. The most
popular scripting languages used with Cocoa are AppleScript, TCL, and Python. Apple
provides AppleScript Studio along with their other developer tools. AppleScript Studio
enables the creation of full-featured Cocoa applications using AppleScript.

A product called Joy from AAA+ Software (http://www.aaa-plus.com) is used to integrate

TCL, JavaScript, and other languages with Cocoa. An open source interface between
Objective-C and TCL is available at http://www-sfb288.math.tu-berlin.de/oorange/
interpretedOC/interpretedOC.html. The Usenix organization provides a technical paper
discussing the integration between TCL and Objective-C at http://www.usenix.org/
publications/library/proceedings/tcl95/bogdanovich.html.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Choosing a Language for Use with Cocoa

Cocoa can be used with many different languages, so how does a programmer choose the
language to use? As always, the answer depends on many factors, including the
programmer's familiarity with the languages and the special features of different languages
that are applicable to the problem's solution. The pros and cons of the most common
language choices for using Cocoa are described in this section. The bottom line is that any
of the languages presented here can be used, and different programmers will make different
choices.

Java Pros and Cons

Java is a powerful and modern language that emphasizes portability and security before
performance and flexibility. Java is ideal for writing long-running server processes that
heavily use network resources and databases. Java is well-suited for use in Web browsers
where security is a concern. Java's use of automatic garbage collection simplifies
application development and avoids whole classes of potential dynamic memory
management errors. Java's standard libraries contain a broad range of features that provide
a head start when developing many types of applications.

Java supports object orientation in a way that is compatible with Cocoa. Java applications
can use Cocoa if portability is not important. Cocoa and the standard Java libraries have
many features in common, but each contains objects that the other does not. Cocoa and
standard Java libraries can be used well together.

Unlike Objective-C, Java is widely taught at universities and elsewhere. Many

programmers who are learning Cocoa are already experienced with Java. For an
experienced Java programmer, using Java with Cocoa might seem like less work than using
Objective-C with Cocoa, but learning Objective-C takes little time for most programmers
experienced with C and at least one object-oriented language. Because Cocoa is written in
Objective-C, Cocoa programmers inevitably encounter Objective-C code even if that
encounter is limited to example programs and documentation. Learning Objective-C makes
learning Cocoa easier in the long run.

Java has several disadvantages for desktop applications. The cross-platform support and
security features that make Java ideal for some applications can get in the way of others.
The Java Virtual Machine that provides cross-platform support and security is large and
takes a long time to load. When a Java desktop application is first started, the Java Virtual
Machine must also be started and initialized. The JVM slows application start-up and
consumes resources. For long-running server applications, the startup cost is negligible
when averaged over the months or years that the program runs. Desktop applications are
started and quit much more often.
Java Cocoa applications pay the price for the JVM, but they don't reap the benefits. When
Cocoa is used, the Java application no longer has cross-platform support. Cocoa provides
access to features that circumvent Java's security restrictions, which are probably
inappropriate for a desktop application anyway.

Java is a popular language. Many libraries of Java objects are available, but it is
inconvenient to use Java with most existing libraries that were written in different
languages. To maximize the benefits of Java's portability and security, it is necessary to
avoid existing non-Java libraries. The fact that it is inconvenient to reuse the millions of
lines of existing C code and libraries from Java is a disadvantage.

Objective-C Pros and Cons

An advantage of Objective-C is its easy integration with existing C code. As a superset of

ANSI C, Objective-C can be used with existing C libraries including traditional Mac and
Unix libraries. The Objective-C++ compiler provided by Apple makes integration with
existing C++ code convenient.

Objective-C is the implementation language of Cocoa, and some features unique to

Objective-C are used by Cocoa. When Cocoa is used with different languages, small
incompatibilities and features that do not translate well are exposed. Objective-C provides
the most natural interface to Cocoa.

Objective-C is one of the most dynamic and flexible object-oriented languages, and Cocoa
programming often benefits from these advantages. When Cocoa is used by less flexible
languages, features and benefits of Cocoa are compromised to some degree. Java is also a
flexible and dynamic language but not quite as flexible and dynamic as Objective-C.

Most existing Cocoa sample code and training resources use Objective-C. Familiarity with
Objective-C maximizes the resources available to programmers who are learning to use
Cocoa. Some of the features of Cocoa are based on unique features of Objective-C.
Understanding how and why to use such Cocoa features is easier with an understanding of
Objective-C.

Objective-C is a small extension of ANSI standard C. Unlike C++, which attempted to

create a better C while adding a certain type of static strongly typed object support to C,
Objective-C adds the minimum features necessary to support dynamic weak typed object
support. Objective-C makes no attempt to improve the underlying C language. Objective-C
is usually easy for C and C++ programmers to learn. The essential additions that Objective-
C makes to C can be described in minutes.

Compared to existing implementations of the Java Virtual Machine, Objective-C's runtime

makes more efficient use of system resources. For desktop applications and applications
that occasionally need to resort to low-level system features and even assembly language,
Objective-C is a better choice than Java. When performance is critical, the C subset of
Objective-C can always be used to maximize performance.

There are two general types of applications: closed world and open world. Objective-C's
flexibility and power are generally inappropriate for closed-world applications, but much
more suited for open-world applications, as described in the following sections.

Closed-World Applications

The engine compartment of an automobile is analogous to closed-world applications. It is

desirable to know in advance every component that will be inside the engine compartment
and how they will fit together. Engines are carefully designed and their design is seldom
modified after they leave the factory. Any variation in the connections between engine
components is probably a manufacturing error. Languages such as C++ and to a lesser
extent Java provide language-level features that are well-suited to solving closed-world
problems. The static strong typing used by C++ and Java enables the compiler to verify
that all components fit together as planned at the cost of making variation, redesign, and
modification of existing applications more difficult. Some applications require the
verifiability of static strong typing and can overcome the reduction in flexibility. Some
programmers are just more comfortable solving closed-world style problems and might
never be satisfied with Cocoa because it is designed to solve open-world problems.

Open-World Applications

The passenger compartment of an automobile is analogous to open-world applications.

Any constraints on the type or number of people and things that can be placed in the
passenger compartment detract from the utility of the automobile. Some constraints are
inevitable, but the designer of a passenger compartment must strive for maximum
flexibility. The price of that flexibility is that the designer cannot anticipate everything that
might be put in the passenger compartment. The designer must work with incomplete
information. Objective-C provides language-level support for solving open-world
problems. Objective-C objects can operate with anonymous objects in different
applications. It is possible to send messages to objects even though the receiver might not
understand the message. It is possible to add behaviors to existing compiled objects
without recompiling them. The flexibility provided by Objective-C aids the development
and life-cycle modification of most desktop applications, but the cost is that the compiler
cannot always verify that the components fit together. In some cases, errors that might have
been caught by a compiler with a different language cannot be caught until an Objective-C
application is running.

Most graphical user interfaces are examples of open-world applications. Restrictions on the
type and number of graphical components available reduce the utility of user interfaces.
Sometimes it is necessary to create new user interface components that were not
anticipated by the original designers and still be able to integrate the new components with
the old components. Plug-ins and context menus are other examples of open-world
applications.

It is certainly possible to create open-world applications with static strongly typed

languages, but it is more difficult. It is also possible to use strong static typing with
Objective-C and gain many of the benefits at the cost of flexibility. Cocoa and Objective-C
emphasize flexibility at the expense of compile time verifiability. Much of the increased
programmer productivity attributed to using Cocoa results from Objective-C's flexibility.

Scripting Language Pros and Cons

Scripting languages are usually interpreted rather than compiled. Even scripting languages
that can be compiled often also operate in an interpreted mode. In most cases, scripting
languages promote rapid application development and programmer productivity before
runtime performance and compile time verifiability. Scripting languages are often easy to
learn and accessible to programming novices.

To access system resources that are only available from compiled languages, scripting
languages almost always provide a mechanism to extend the language for use with
compiled software written in other languages.

The extensibility of scripting languages combined with the power of Objective-C's runtime
makes using Objective-C objects from within scripting languages possible. Details about
allocating Objective-C objects and sending messages to them are provided in Appendix A.
As long as a scripting language can call a small number of Objective-C runtime functions,
Cocoa can be used in its entirety from the scripting language.

Scripting languages usually exhibit inferior performance and make producing large
applications difficult in comparison to compiled languages. When the performance and
scalability of scripting languages are acceptable, scripting languages can be an ideal way to
use Cocoa.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

The Use of Objective-C in This Book

Objective-C is used to present Cocoa in this book because Objective-C is the

implementation language of Cocoa. Learning it is not a large obstacle to learning Cocoa.
Understanding how and why to use Cocoa features is easier with an understanding of
Objective-C. Cocoa is so large that the benefits derived from using Objective-C when
explaining Cocoa outweigh the need for many readers to learn Objective-C. Programmers
learn new languages all the time.
Book: Cocoa® Programming
Section: Chapter 2. Cocoa Language Options

Summary

Cocoa can be used with many programming languages. For a language to use Cocoa, that
language must support a degree of flexibility and a model of object orientation that is
compatible with Cocoa. Objective-C, Java, and many scripting languages integrate well
with Cocoa. Other languages such as standard C and C++ can use Cocoa either by using
only the C functions provided by the Objective-C runtime or by using Objective-C and
Objective-C++ compilers to mix Objective-C code with the standard C and C++ code.

Now that the languages used to write Cocoa applications have been explained, the next step
is to learn the tools used to create Cocoa applications. Chapter 3, "Using Apple's Developer
Tools," introduces the tools that Apple provides for creating Cocoa applications. Apple's
developer tools can be used with C, C++, Java, Objective-C, Objective-C++, and
AppleScript.
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 3. Using Apple's Developer Tools

IN THIS CHAPTER

● Obtaining Apple's Developer Tools

● Project Builder
● Interface Builder
● Frameworks
● Samples
● Terminal
● Other Tools

It is not possible to describe every feature of Apple's tools in one chapter, and the bulk of
this book is dedicated to unleashing the power of Cocoa. Apple's tools have many features
in common with other developer tools. This chapter describes the major tools that Apple
provides and some introductory step-by-step ways to use them. Most developers become
familiar with the tools quickly and discover features not mentioned here. Some of Apple's
tools use unusual paradigms for development tasks. This chapter mentions some of those
unusual aspects and assumes that the common aspects will be self-explanatory and second
nature by the time several examples have been completed. Apple's own introductory
documentation about the developer tools is available at http://developer.apple.com/
techpubs/macosx/DeveloperTools/devtools.html.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Obtaining Apple's Developer Tools

Apple ships Mac OS X on one CD-ROM, and provides a second CD-ROM that contains
developer tools. The Mac OS X Developer CD-ROM provides everything needed to write
Cocoa applications using Apple's tools.

NOTE

The developer tools can also be downloaded from Apple's site for free at
http://developer.apple.com/tools/macosxtools.html.

Apple's developer tools are high quality. They are competitive with similar tools from other
vendors. The fact that Apple distributes the tools with Mac OS X at no extra cost is not an
indication that the tools are not valuable. Quite the contrary, the tools are powerful and in
some cases indispensable for Cocoa development. Prior to the release of Mac OS X,
Apple's tools had to be purchased separately at a cost of several thousand dollars.
According to Apple, Mac OS X itself is built using Apple's tools.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Project Builder

The primary Cocoa development tool is called Project Builder. It provides an Integrated
Development Environment (IDE) for writing, compiling, and debugging Cocoa
applications using Objective-C, Objective-C++, AppleScript, or Java. Apple uses a
modified version of gcc, the Gnu Compiler Collection, to compile Objective-C and
Objective-C++. A modified version of gdb, the Gnu debugger, is used to debug
applications. Project Builder wraps the Gnu tools and hides their command line nature
from developers. Project Builder users do not need to use the Gnu tools directly. Project
Builder integrates most development activities including editing code into one application.

NOTE

The Gnu project is a prominent open-source project. Details are available at

http://www.gnu.org/.

Creating a New Project

To get familiar with Project Builder, create a new project to build a version of the classic
"Hello World" program which is commonly the first program written in a new language.
This example is so small that it barely uses features of Cocoa. It just shows how to create a
new project and later how to edit, compile, and test code with Project Builder. The same
techniques are used to create large Cocoa projects.

To get started, double-click the Project Builder icon in the /Developer/

Applications folder. When Project Builder starts, select File, New Project from the
menu bar to open the Assistant window. The Assistant window is used to select the type of
new project to create. For this example, select the Foundation Tool project type, as shown
in Figure 3.1. A Foundation Tool is a program that uses only nongraphical Cocoa objects.
Tool programs do not have graphical user interfaces.

Figure 3.1. The Assistant window used to create new projects shows the Foundation
Tool project type selected.
Click the Next button in the Assistant window. Project Builder requests the name and
location of the new Foundation Tool project as shown in Figure 3.2. Type Hello World
into the Project Name text field.

Figure 3.2. Specify the name and location of the new project.

Click the Finish button. Project Builder opens a new window for the Hello World project.
Select the main.m file inside Project Builder's Source folder as shown in Figure 3.3. Each
project document is divided into four main parts: Toolbar, Project pane, Editor pane, and
Tool pane.
 Figure 3.3. Each Project Builder document represents a project and has four main
parts.

The Toolbar is user-configurable and accelerates access to frequently used Project Builder
features. Every feature accessible with the Toolbar is also accessible through menus. The
Project pane has several uses. Figure 3.3 shows the files that are used to build the Hello
World program. The file main.m in the Source folder is selected. The contents of the
main.m file are shown in the Editor pane. Figure 3.3 also shows the Tool pane closed, so
that only tabs to access its features are visible.

The .m extension on the main.m file indicates that it contains Objective-C code. In this
example, the Objective-C language is used to output the string Hello, World!. Don't worry
if you are not yet familiar with the Objective-C language. Chapter 4, "Objective-C,"
introduces the language. It is not necessary to write any code for this trivial example
because by default, when Project Builder creates a new Foundation Tool project, it includes
the file main.m exactly as shown in Figure 3.3. It even contains the following line that
outputs the Hello, World! string.

NSLog(@"Hello, World!");

Building the Hello World Project

To build the Hello World example, use the Build, Build menu item or Cmd-b. Figure 3.4
shows Project Builder in the middle of compiling the Hello World program. The Tool pane
shows the output from a variety of command-line tools used to build the project, including
the gcc Objective-C compiler. If there are any errors or warnings generated during the
build, they are displayed above the divider in the Tools pane.

Figure 3.4. Project Builder shows the output from command-line build tools in the
Tools pane.

Running Hello World

After the project has been built, it can be run. To run the Hello World program inside
Project Builder, use the Build, Build and Run menu item, or Cmd-r. Figure 3.5 shows the
output from Hello World in the Run tab of the Tools pane. The Cocoa NSLog() function
used to output the string Hello, World!, prints information such as the date and program
that produced the output followed by the output itself. The Hello World program outputs
2002-02-22 19:34:05.813 Hello World[567] Hello, World!. The rest
of the text in the Run tab of the Tools pane indicates that the process named Hello World
exited with status 0, meaning that there were no errors.

Figure 3.5. The output from running the Hello World program is shown in the Run
tab of the Tools pane.
Exploring the Project Pane

Two components are used to create the Hello World program; the main.m file has already
been shown. The other component is Foundation.framework shown in the Project
pane. The Foundation.framework is a collection of objects, functions, and resources
used in Cocoa applications. For example, the NSLog() function used to output Hello,
World! is implemented in Foundation.framework. Figure 3.6 shows all the folders in
the Project pane expanded to reveal their contents.

Figure 3.6. The components used to build the example are shown in the Project pane.
The folder labeled Products in the Project pane shown in Figure 3.6 lists the files that are
created by building the project. In this example, the Hello World program is the only
product that results from building the project.

There are five tabs that reveal different information in the Project pane. Figure 3.7 shows
the tabs with the Targets tab selected.

Figure 3.7. The Targets tab lists the products that are built by a project, and the build
style used to produce the targets.
The tabs provide the following information:

● The Files tab organizes the components used to build the project and the output
products from the project.
● The Classes tab lists the hierarchy of Cocoa classes available for use in
applications. The Classes are introduced throughout the rest of this book.
● The Bookmarks tab shows and organizes the list of bookmarks set by the user.
Bookmarks help users quickly jump to positions of interest within files.
● The Targets tab, shown in Figure 3.7, lists the applications, libraries, frameworks,
and other products built by a project. A single project can have any number of
targets, but there is usually only one. The Targets tab also lists available build
styles that are described later in this chapter.
● The Breakpoints tab lists the places where the debugger should stop execution
when debugging code. The previously set breakpoints can be disabled or deleted
from within the Breakpoints tab.

A build style specifies the options that are passed to various command-line tools used by
Project Builder to build projects. The two build styles shown in Figure 3.7 are
Development and Deployment. The Development build style specifies build options that
result in programs containing maximum debugging information. The Deployment build
style specifies less debugging support, but produces smaller, faster programs. It is possible
to create custom build styles and add them to the list as described in Project Builders online
help.
Debugging with Project Builder

To start debugging an application, select the Build, Build and Debug menu item, or Cmd-y.

Figure 3.8 shows the Hello World program stopped on a breakpoint while running in
Project Builder's integrated gdb debugger. Breakpoints can be added to a program by
clicking in the margin to the left of a line of code in the Editor pane. Breakpoints that have
been set are listed in the Breakpoints tab of the Project pane shown selected in Figure 3.8.
Breakpoints are removed from the Breakpoints tab of the Project pane, or by dragging the
Breakpoint icon out of the margin in the editor window.

Figure 3.8. The Hello World program is stopped on a breakpoint while running in
Project Builder's integrated gdb debugger. The Breakpoints tab of the Project pane
is selected.

NOTE

An online manual for the gdb debugger titled Getting Started with GDB is
available at http://developer.apple.com/technotes/tn/tn2032.html

The Project Builder toolbar contains icons on the right side to control the basic functions of
the debugger. The icons that look like VCR controls pause and resume execution of a
program. The remaining icons enable various techniques for single stepping through code.
Using Project Builder's Find Tool

Another Project Builder feature that can be demonstrated with the Hello World example is
the integrated Find tool. Figure 3.9 shows the Find tool in the Tools pane. Project Builder
searches for strings within the files of a project and within online documentation and
frameworks. One handy technique is to select an unfamiliar term in the Editor pane and use
the Find, Find Selected Text menu, or Cmd-7, to search for the term in the online
documentation. Figure 3.9 shows the results of searching for information about the selected
word NSAutoreleasePool. Be sure to select the Find tab of the Tools pane to see the
results of the find operation.

Figure 3.9. Project Builder's integrated Find tool searches for terms within a project
or in the online documentation.

Project Builder has a related automatic symbol completion feature that reduces the amount
of typing necessary. After the first few letters of a programming term have been typed,
press the F5 function key, and Project Builder looks up the term with the Find tool and
completes it, if possible. Typing NSAutore followed by pressing F5 completes the half-
typed work to produce NSAutoreleasePool.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Interface Builder

Interface Builder is invaluable for Cocoa development. Interface Builder is a tool for
positioning graphical Cocoa objects and connecting graphical and nongraphical objects
together. Interface Builder is arguably the best and most flexible user-interface design tool
available today for any platform. That is particularly impressive considering the fact that
Interface Builder is more than 12 years old, and its basic features have not evolved much in
that time. Interface Builder itself is a great example of a Cocoa application. It demonstrates
the power and flexibility of Cocoa while helping developers create new Cocoa
applications. Interface Builder can be extended and used with new reusable objects.

Interface Builder provides access to the full power and flexibility of the objects in the
Cocoa frameworks. Without detailed descriptions of the objects and their interactions, there
are limits to the amount of information that can be presented regarding the use of Interface
Builder. In this section, the general features of Interface Builder and its idioms are
presented without much explanation. Instead the role Interface Builder plays in Cocoa
development is introduced.

The following example describes how to build a simple image-viewer application without
writing or compiling any code at all. The example is similar in spirit to the nongraphical
Hello World program. In the Image Viewer example, standard Cocoa objects are
configured to allow drag and drop of image files from the file system and display the
images in a window.

One of the features of Interface Builder that the following example demonstrates is the
absence of required code. Interface Builder simply configures and connects existing objects
such as windows, menus, and image-viewer widgets. The objects are stored in a file on the
hard disk. When the file is read the objects and all their connections are restored and can be
run immediately.

Creating a New Interface with Interface Builder

The first step in this example is to launch Project Builder from the /Developer/
Applications folder. Next, select File, New Project to open the Assistant window, as
shown in Figure 3.10. Select the Cocoa Application option and click Next.

Figure 3.10. Select Cocoa Application in the Assistant window used to create new
projects.
As shown in Figure 3.11, type the name Image Viewer into the Project Name text field,
leave the default location in the Location text field unmodified, and click the Finish button.

Figure 3.11. Name the new project Image Viewer.

Project Builder creates a new project with the name Image Viewer.pbproj in a folder
called Image Viewer at the location specified. The new project is represented by the
Image Viewer.pbproj document shown in Figure 3.12. Make sure that the Files tab
of the Project pane is selected. Select the MainMenu.nib file in the Resources folder of
the Project pane, as shown in Figure 3.12.
 Figure 3.12. Select the MainMenu.nib file in the expanded Resources folder.

Double-click the MainMenu.nib file to start Interface Builder. When Interface Builder
starts, select the Interface Builder, Hide Others menu to hide all applications except
Interface Builder. Interface Builder is shown with the MainMenu.nib document open in
Figure 3.13. By default, the MainMenu.nib document already contains several objects
including a menu and an empty application window. Figure 3.13 shows Interface Builder
configured with four open windows: one titled MainMenu.nib, another window titled
MainMenu.nib-MainMenu, a window titled Window, and a window titled Cocoa-
Other that contains a palette of reusable objects. The window titled Cocoa-Other in Figure
3.13 might have a different title and show different contents when Interface Builder starts.
This window provides access to Cocoa objects that are used to build applications. Several
different groups of objects exist. Each group is called a palette and can be shown by
selecting one of the icons in a row just below the window's title bar. The last palette
accessed in a previous session using Interface Builder is shown when Interface Builder is
started. The title of the window changes based on the palette shown.

Figure 3.13. Four windows are open when Interface Builder starts and loads the
MainMenu.nib file.
If the Interface Builder palette does not already show the collection of objects labeled
Cocoa-Other, as shown in Figure 3.13, select the Cocoa-Other palette by clicking on the
icon that depicts a slider and a progress indicator. It is third from the left in the window
titled Cocoa-Other in Figure 3.13.

Drag an NSImageView object from the Cocoa-Other palette into the empty application
window. Figure 3.14 shows the NSImageView being dragged from the palette.

Figure 3.14. An NSImageView object is being dragged from the palette to the empty
application window.
Figure 3.15 shows the NSImageView object that was dragged into the empty application
window and selected. When the NSImageView object was dropped into the window, a
copy of the object dragged from the palette was made, and then was added to the content of
the window. The little boxes around the object in Figure 3.15 are control points that
indicate the selected object. Selected objects can be moved and resized with the control
points.

Figure 3.15. An NSImageView object is added to the content of the application

window and selected.
Resize the NSImageView object so that it almost fills the window. As the
NSImageView is resized, Interface Builder shows dashed guidelines that indicate
suggested placement of objects to conform to Apple's user-interface conventions. Figure
3.16 shows the NSImageView resized to extend to the guidelines.

Figure 3.16. Interface Builder automatically shows guidelines for the placement and
size of objects.
Configuring Objects

In this example, images are viewed by dragging them into the NSImageView object when
the Image Viewer application is run. After resizing the NSImageView, the next step is to
configure it to accept images dropped onto the NSImageView. Select Interface Builder's
Tools, Show Info menu item or choose Cmd-1 to open the Show Info window. The Show
Info window is used to inspect and change the attributes of selected objects. When first
opened, the Show Info window's Attributes mode is visible. If the Show Info window does
not look like the window labeled NSImageView Info, as seen in Figure 3.17, make sure
that the newly positioned NSImageView is selected. The pop-up button labeled Attributes
in Figure 3.17 is used to select the type of information shown in the window.

Figure 3.17. The Show Info window is used to inspect and change attributes of
selected objects. It has the title NSImageView Info to indicate that it is showing
information about a selected NSImageView object.
The NSImageView that was placed in the application window is an instance of a Cocoa
class named NSImageView. Instances of the NSImageView class have many attributes
that can be set, but for now the only attribute of interest is the Editable check box at the
bottom of the Show Info window titled NSImageView Info in Figure 3.17. Select the
Editable check box so the selected NSImageView is editable at runtime, as shown in
Figure 3.18. Editable NSImageView's accept dropped files, but noneditable ones do not.

Figure 3.18. Make sure that the selected NSImageView is editable by selecting the
Editable check box.
Next, configure the NSImageView to automatically resize when its window is resized.
Select the Size mode of the Show Info window titled NSImageView Info using the pop-up
button as shown in Figure 3.19, or use Cmd-3 to select the Size mode without using the
pop-up button.

Figure 3.19. Change the Show Info window titled NSImageView Info to Size mode.
Click both of the lines within the inner box of the Autosizing area of the Show Info
window until its similar to Figure 3.20. Most graphical Cocoa objects can be configured to
automatically resize when the object that contains them changes size. By clicking the inner
lines in the Autosizing area, the selected NSImageView is configured to always expand
and contract to fill available space while leaving constant margins around the object. The
outer lines in the Autosizing area control whether the margins can grow or shrink. Many
different resizing behaviors can be set with the various springs and struts that look like
coils and lines in the Autosizing area.

Figure 3.20. Set the Autosizing springs and struts for the selected NSImageView as
shown.
 NOTE

The size values shown in Figure 3.20 may be different if the window
containing the NSImageView has been resized. The exact size specified
does not matter.

The new interface can now be tested to determine if it is configured correctly. Select File,
Test Interface, or use Cmd-r to put Interface Builder into Test Interface mode. When
Interface Builder is in Test Interface mode, it copies the objects in the .nib file being
edited, hides Interface Builder's user interface, and enables the copied objects to start
running as if they were in a standalone application. When Interface Builder is put into Test
Interface mode, the Image Viewer interface created looks like the one shown as in
Figure 3.21.

Figure 3.21. The interface being tested has its own menu and a single window titled
Window that contains an editable NSImageView.
The interface being tested behaves just like it will in a standalone application. The window
can be resized, and the NSImageView will resize with it. The interface has all the
standard menus. To test the NSImageView, drag an image file from the Finder into the
NSImageView. Image files can be found in the /Library/Desktop Pictures
folder on most Mac OS X installations. Many types of images can be viewed including
JPEG, TIFF, GIF, and BMP. Figure 3.22 shows an image file being dragged from the
Finder to the NSImageView.

Figure 3.22. An image file is being dragged from the finder to the NSImageView
being tested.

Figure 3.23 shows the image centered and scaled proportionally in the NSImageView.
The default behavior of NSImageView is to proportionally scale images to fit within the
view, and the default was not changed in Interface Builder's Show Info window.

Figure 3.23. The interface being tested shows a ladybug image centered and scaled
within the NSImageView.

As the window containing the NSImageView is resized, the image grows and shrinks to
fit within the NSImageView. Try dropping other images on the NSImageView. The
NSImageView can even be printed within the Interface Builder's test interface mode. Just
select Cmd-p or the File, Print menu of the interface being tested.

To stop testing the interface and return to Interface Builder's normal mode, select the
NewApplication, Quit NewApplication menu item, or use Cmd-Q. When Interface Builder
is in its normal mode, make some additional changes to the MainMenu.nib interface.
Change the title of the application's one window from Window to Dropped Image by
selecting the Window icon in Interface Builder's MainMenu.nib window, and editing
the name in the Show Info window's Attributes mode.

NOTE

When the Window icon is selected, the Show Info window is titled
NSWindow Info. The Show Info window's title changes to reflect the selected
object.

Select the Attributes mode of the Show Info window titled NSWindow Info. Enter the new
title in the Window Title text field. Figure 3.24 shows the Window icon selected, and the
title of the window being changed.

Figure 3.24. Change the application window's title to Dropped Image.

Change the name of the application's main menu by editing the menu as shown in Figure
3.25. Double-click the NewApplication menu in the window titled MainMenu.nib-
Mainmenu. Menu names can be edited by double-clicking them. Change the
NewApplication menu to the Image Viewer menu.

Figure 3.25. Change the application name in the main menu to Image Viewer.
Next, single-click the Image Viewer menu to show the menu's items. Change the item
labeled About NewApplication to About Image Viewer by double-clicking the About
NewApplication menu item or using the Title text field in the NSMenu Info window.
Change the item labeled Quit NewApplication to Quit Image Viewer. Change the item
labeled Hide NewApplication to Hide Image Viewer. Figure 3.26 shows the edited menu
items.

Figure 3.26. Edit the menu item labels as shown.

Change Hide NewApplication to Hide Image Viewer.

Select File, Save or Cmd-s to save the modified interface. Quit Interface Builder and single-
click the Project Builder icon in the Dock to make Project Builder the frontmost
application. Use the Build, Build and Run menu item, or Cmd-r to build the project as
shown in Figure 3.27. Project Builder builds the project and copies the edited MainMenu.
nib file into the resulting application. The .nib file does not need to be compiled as part
of the build process because it is just a resource. The main.m file that was automatically
created for the new project must be compiled before the first time the new project is run,
however. When Project Builder has finished compiling main.m and copied all necessary
resources, the Image Viewer application is run.

Figure 3.27. Project Builder compiles main.m and copies the MainManu.nib file as
part of the build process.
Figure 3.28 shows the running standalone Image Viewer application with a displayed
image and a standard Print panel accessed from the File, Print menu item.

Figure 3.28. The Image Viewer application already supports printing and print
preview.
Interface Builder Paradigms

Interface Builder has many features that have not yet been touched, but one of the key
features has already been shown. The edited objects are live objects that can be run within
Interface Builder's Test Interface mode. Minimal Cocoa applications support all standard
menus and features such as live resize and printing. Interface Builder does not usually
generate any code. Instead, the live objects being edited in Interface Builder are saved to
a .nib file. Project Builder copies the .nib file into an already built application. When
the application is run, the objects in the .nib file are loaded to create the application's user
interface.

Interface Builder comes with several standard palettes and can be extended with more
palettes. Palettes can contain nongraphical objects as well as graphical objects. Apple's
developer tools include three sample custom Interface Builder palettes that demonstrate
how to create new palettes. The samples are stored in the /Developer/Examples/
Interface Builder directory. The bMoviePalette sample builds a palette that
contains components useful for making a simple QuickTime movie editor within Interface
Builder. The BusyPalette sample includes a variety of novel user-interface objects. The
ProgressViewPalette sample is an introduction to creating new palettes. It demonstrates
how to create a simple palette with minimal effort.

Most advanced features of Interface Builder are introduced in other parts of this book, but
there are a few Interface Builder paradigms that must be understood now to effectively use
the tool in examples. First, dragging an object from a palette creates a copy of the object.
The copied object is configured with the Show Info window. So far, only the Attributes
mode and the Size mode of the Show Info window have been used. There are usually six
modes available, but under certain circumstances there can be more. Continuing the
Image Viewer example, a few more changes are made to expose another paradigm
employed by Interface Builder: nested views.

Nested Views

Start Interface Builder again by double-clicking the MainMenu.nib item in Project

Builder's Resources folder. When Interface Builder has started, select the NSImageView
that was previously added to the application's window. Choose Tools, Show Info, or Cmd-
1 to open the Show Info window with the Attributes pane visible.

In the box labeled Border in the Show Info window titled NSImageView Info, select the
button with the dashed outline icon. That specifies that the selected NSImageView does
not have a border. In the box labeled Scaling, select the option labeled None. Figure 3.29
shows the NSImageView properly configured.

Figure 3.29. The NSImageView is selected and its attributes are shown in the
window titled NSImageView Info.
This example is being modified to place the NSImageView inside a scroll view. In the
modified example, the images that are dropped onto the NSImageView are shown at full
size. If it is not possible to see the whole image at once, the scroll view is used to see other
parts of the image.

To place the NSImageView in a scroll view, make sure it is selected and choose Layout,
Make Subviews Of, Scroll View, as shown in Figure 3.30.

Figure 3.30. The Layout, Make subviews Of, Scroll View menu item is used to nest the
selected objects inside a scroll view.
Using Layout, Make Subviews Of, Scroll View creates a new NSScrollView object,
and nests the selected objects within the NSScrollView. The selected objects become
the content that is scrolled. This capability to nest objects and make some views into
subviews of other views is an important Interface Builder paradigm. Many powerful
features are enabled by this paradigm. In addition to scroll views, objects can be nested
inside box objects, split views, tab views, and even custom view objects. Scroll views,
boxes, split views, tab views, and custom views are introduced in Chapter 8, "Application
Kit Framework Overview," and further explained in Chapter 10, "Views and Controls."

After the NSImageView is nested within a NSScrollView, resize the

NSScrollView so that it fills the window, as shown in Figure 3.31.

Figure 3.31. Resize the NSScrollView containing an NSImageView as shown.

Next, configure the automatic resizing behavior of the NSScrollView, so that is grows
and shrinks with the window. Make sure the NSScrollView is selected and use Cmd-3
to reveal the Show Info window Size mode, or select the Size option in the Info Window's
pop-up button. Figure 3.32 shows the NSScrollView configured to automatically fill
available space and preserve constant margins.

Figure 3.32. Set the NSScrollView's automatic resize behavior to fill available
space and preserve constant margins.
The modified interface can now be tested in Interface Builder's Test Interface mode. Save
the modified .nib file using Cmd-s, or File, Save and quit Interface Builder. In Project
Builder, use Build, Build and Run or Cmd-r to build and run the application. Project
Builder does not have to compile anything to complete the build. It just copies the
modified .nib file into the existing Image Viewer application and runs the application.
Figure 3.33 shows the modified Image Viewer application displaying the Dew Drop (Wide
Screen) .jpg image. The image is shown full size, but it is possible to scroll to reveal
hidden parts of the image. As the Dropped Image window is resized, the scroll view resizes
and the scrollbar elements automatically change size to reflect the proportion of the image
that is visible. Experiment with dropping different images in the Image Viewer window to
see the scroll behavior.

Figure 3.33. The modified Image Viewer application now enables scrolling to view full-
sized images.
Two more important Interface Builder paradigms are presented next: Objects can be
grouped to form a collection of cooperating objects arranged in a grid pattern called a
matrix, and objects can be interconnected within Interface Builder.

Creating a Matrix

To create a matrix of objects, press the Alt key on the keyboard while dragging a selected
object's control points.

NOTE

The Alt key is pressed by holding the Shift key and the Option key,
simultaneously.

Figure 3.34 shows a matrix of buttons being created. The objects in a matrix are
automatically configured to work together and resize as a group. Radio buttons, forms
created from multiple text fields, and other groups of objects are implemented using a
matrix in Interface Builder. Chapter 10 introduces the NSMatrix object. There is no need
to experiment with creating a matrix in Interface Builder at this time, but it is important to
know that the feature exists.

Figure 3.34. Drag the control points of a selected object while pressing the Alt key to
create a matrix of objects.
In Project Builder, save the Image Viewer project, and then quit.

Interconnecting Objects

To briefly explore connections between objects, start Interface Builder and create a new
empty interface. The Interface Builder application is located in the /Developer/
Applications folder. Interface Builder shows a window titled Starting Point. If the
Starting Point window is not visible, select File, New. Choose the option labeled Empty
inside the Cocoa folder displayed in the Starting Point window. Then click the New button
at the bottom of the Starting Point window to create a new empty user interface.

No windows are in the empty user interface yet. Select Interface Builder's Cocoa-Windows
palette and drag a window object out of the palette and onto the desktop. A new empty-
window object is created. Next, select the Cocoa-Other palette and drag a vertical slider
object into the new window. Figure 3.35 shows a slider placed in the new window. Select
the Cocoa-Views palette and drag a text-field object into the new window.

Figure 3.35. A slider and a text field are connected in Interface Builder so they show
the same value.
The slider's default configuration is to represent values from 0.0 to 100.0, and initially
shows the value 50.0. If you are comfortable configuring objects with the Show Info
window, configure the slider so its Continuous option is on, and its Marker Values Only
option is off. These configuration options are not essential to the connections that will be
made between the slider and the text field objects.

To make a connection from the slider to the text field, make sure the slider is selected.
Press the Control key, and use the mouse to drag from the slider to the text field. A gray
line will follow the mouse pointer to show the connection line being made. Release the
mouse button over the text field. The Show Info window opens if it is not already and
shows its Connections pane. A browser labeled Outlets is visible in the Connections pane,
as shown in Figure 3.46. Select the target item in the browser, and then select the
takeFloatValueFrom: item that appears in the browser's second column. Click the Connect
button to make the connection.

The slider has just been configured to send a message to the text field whenever the slider's
value changes. The message that is sent tells the text field to take its floating-point value
from the slider's current value. If the slider has not been configured to be Continuous, the
message is not sent until the slider is released after it is moved.

Next, connect the text field to the slider. Select the text field and Control-drag a connection
line from the text field to the slider. Release the mouse over the slider. Select the target
item in the Show Info window's Outlets browser, and then select the takeFloatValueFrom:
item that appears. Click the Connect button to make the connection.
Put Interface Builder into Test Interface mode using Cmd-R, or File, Test Interface. Type a
value between 0.0 and 100.0 into the text field being tested and press Return. The slider
will move to show the entered value. Move the slider and the text field is updated with the
slider's value. If the slider is configured to show Marker Values Only, as it was when
originally dragged from the palette, the slider will hop from marker to marker as it moves.
If the slider is not in Continuous mode, the value of the text field will not change until the
slider is released after it is moved.

Objects are alive and can send messages to each other even in Interface Builder's Test
Interface mode. The example barely touches on the power and flexibility of connections
made in Interface Builder. It is possible to create significant applications entirely visually
within Interface Builder. Menu items are connected to objects, and objects in different
windows can be connected. Nongraphical objects that implement application logic can be
connected to user interface objects.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Frameworks

In addition to tools, the developer CD contains frameworks and samples. Frameworks are
directories full of compiled software libraries, header files, documentation, and resources.
Frameworks keep related development information together. The libraries are present on
all OS X installations so that Cocoa applications can run, but the developer CD-ROM
provides alternate versions of the libraries to aid debugging and performance analysis. The
header files are required to compile Cocoa applications.

A framework is a collection of libraries, header files, documentation, and resources

organized so that Apple's developer tools can access the information. Apple's OS X
developer CD-ROM contains frameworks for Carbon, 100% Pure Java, Cocoa,
AppleScript, Perl, and more. Developer components of Apple technologies such as
QuickTime and Text to Speech are also provided as frameworks on the CD-ROM.

When Apple's developer tools are installed, the frameworks that are stored in /System/
Library/Frameworks on all OS X machines are extended. Additional versions of the
libraries are added to support code profiling. Code profiling enables application developers
to determine how many times functions are called and what percentage of an application's
time is spent in each function.

Frameworks can contain multiple versions of libraries and resources at the same time.
Apple might release beta libraries or new test frameworks to registered developers as they
have in the past. In certain cases, such new components are added to existing frameworks
rather than replacing the frameworks. By adding components rather than replacing them,
backwards compatibility can be preserved, and applications that depend on the behavior of
obsolete framework versions can continue to run.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Samples

When Apple's developer tools are installed, a wide range of sample applications with
source code are copied into the /Developer/Examples directory. Samples that use
Carbon, 100% Pure Java, and Mac OS services such as Text to Speech are installed along
with Cocoa specific examples.

Most Cocoa related examples are located in the /Developer/Examples/AppKit, /

Developer/Examples/Foundation, and /Developer/Examples/
InterfaceBuilder folders. Additional samples that use Cocoa are found in the /
Developer/Examples/AppleScript Studio and /Developer/Examples/
Java/AppKit folders.

Most topics demonstrated by the samples will not make any sense without a prior
introduction to Cocoa programming. This book contains the information needed to gain
maximum value from the samples that Apple provides. After Cocoa concepts are explained
in this book, refer to Apple's examples along with this book's examples to see
implementations of the concepts. The examples are an invaluable resource when learning
Cocoa. Many developers prefer to learn new technology from complex examples. The
Cocoa examples are presented here so that developers who are eager to jump into advanced
topics can find suitable examples immediately and refer back to topics in this book for
explanations.

Application Kit Framework Samples

The /Developer/Examples/AppKit directory contains the following samples:

CompositeLab This example uses the NSView, NSBezierPath,

NSAffineTransform, NSImage, and
NSColorWell classes to demonstrate different
compositing modes and transparency supported by the
Quartz-graphics model and accessed with Cocoa's
Application Kit framework. This example also uses drag
and drop.

CircleView This example creates a simple subclass of NSView to

demonstrate drawing, event handling, coordinate
systems, and text layout.
DotView This example subclasses NSView to implement custom
event handling and drawing. This is a good introductory
example.

DragNDropOutlineView This example implements drag-and-drop support in a

NSOutlineView.

DrawerMadness This example demonstrates the NSDrawer class.

HexInputServer This example uses the NSInputManager class to

create a custom input manager.

MenuMadness This example demonstrates a wide range of features

involving Mac OS X menus and the NSMenu class.

OutlineView This example produces a simple file viewer using the

NSOutlineView and NSFileManager classes. This
is a good introduction that explains how to provide a data
source for a NSOutlineView and how to access the
file system using Cocoa.

Rulers This example demonstrates custom units, rulers, and ruler

drawing using the NSRulerView class.

Sketch This is a complex example that builds a modest vector

drawing application using the NSDocument,
NSWindowController, NSUndoManager, and
NSBezierPath classes. Sketch is a realistic
application that provides most features that users expect
from every application including AppleScript support.

SimpleBrowser This example shows how to provide a data source for a

NSBrowser. The NSBrowserCell and
NSFileManager classes are also demonstrated.

SimpleComboBox This example explains how to use the NSComboBox and

NSUndoManager classes.
SimpleImageFilter This example demonstrates the Cocoa Filter Service
concept using the NSBitmapImageRep class.

SimpleService This example explains the Cocoa Services menu.

SimpleToolbar This example demonstrates a simple user-configurable

toolbar using the NSToolbar and NSDocument
classes.

TextEdit This is the complete source code to the TextEdit

application shipped with Mac OS X. TextEdit is a
large application that provides mid-level word processing
features. TextEdit uses many features of Cocoa and
highlights Cocoa's text handling classes. This is an
excellent example of a realistic full-featured application
built with Cocoa.

TextSizingExample This example demonstrates the interaction of the

NSTextView, NSTextContainer, and
NSTextStorage classes.

UserDefaults This example shows how to store users preferences and

default values using the NSUserDefaults class.

Foundation Framework Samples

The /Developer/Examples/Foundation folder contains the Authenticator,

ForwardInvocation, and MultiThreadedDO samples. All these samples are built
with a tool called ProjectBuilderWO that has not previously been mentioned.

ProjectBuilderWO is a version of Project Builder that predates the Project Builder

application normally used with Mac OS X. WO refers to Apple's WebObjects product.
ProjectBuilderWO is primarily used with older WebObjects applications, but is
included with the other developer tools from Apple.

The Foundation samples have not been updated in many years. The concepts demonstrated
are still relevant on OS X, but they are too esoteric to describe in detail here. Each of the
examples deals with an aspect of inter-process communication. The Authenticator example
shows how one process can authenticate requests from another process to make sure the
requesting process has authority to make requests. The ForwardInvocation sample
explores the low-level details of sending Objective-C messages between processes. The
MultiThreadedDO sample shows how to use Distributed Objects to safely send
messages between different threads in one process.

Interface Builder Samples

The /Developer/Examples/InterfaceBuilder folder contains sample custom

Interface Builder palettes. The Interface Builder application can be extended in a variety of
ways. These examples show how to create custom palettes of objects for reuse within
Interface Builder.

One particularly interesting Interface Builder palette is created by the bMoviePalette

sample. This palette contains components useful for making a simple QuickTime movie
editor. The palette includes a custom NSFormatter object for time display and a novel
user-interface element called a SoundFileWell that is used to add sounds to a movie via
drag and drop.

Additional Samples

The /Developer/Examples/AppleScript Studio folder contains samples that

demonstrate AppleScript Studio. AppleScript Studio is built with Cocoa and used the
Cocoa objects. These samples explain many aspects of Cocoa programming from the
perspective of a script writer. AppleScript Studio exposes Cocoa objects to AppleScripts
and makes it possible to create Cocoa applications with logic implemented in scripts.

The /Developer/Examples/Java/AppKit folder contains several examples that

show how to use Cocoa with Java. The Mac OS X developer tools can be used to create
100% Pure Java applications or use Java with the Cocoa frameworks. These samples
examine Cocoa objects from the perspective of Java programmers.

Additional samples are provided at http://developer.apple.com/samplecode/Sample_Code/

Cocoa.htm and http://developer.apple.com/samplecode/Sample_Code/Graphics_3D.htm.
Apple updates the site regularly, so check it for new samples. A few important samples that
are available from Apple's site include the following:

RoundTransparentWindow This sample shows how to create windows that have

transparent backgrounds and simulate windows that
are not rectangular.
Cocoa InitGL This sample shows how to initialize OpenGL for use
with Cocoa applications.

NSGL Teapot This sample demonstrates advanced OpenGL features

accessed from a Cocoa application.

Simple AppKit This sample shows how to interact with OpenGL

using Cocoa from within Interface Builder.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Terminal

Mac OS X includes an application called Terminal in the /Applications/Utilities folder.

Terminal provides access to a traditional Unix command line. Several developer tools that
don't have graphical user interfaces use the command line. The command line is sometimes
the most efficient way to use tools that do have a graphical user interface.

Project Builder is used from the command line to build the install version of an application.
Normally, Project Builder preserves at least minimal debugging information in the
applications that it builds. The command-line version of Project Builder is called
pbxbuild. The command pbxbuild -install builds the project in the current
directory using options appropriate for a final install version of the application. All
debugging information is stripped out of the resulting application. The application built is
optimized, and its resources are stored in the most compact form available. Using
pbxbuild install produces the smallest and fastest applications. The pbxbuild tool is
located in the /usr/bin folder.

NOTE

Finder hides the /usr/bin folder and other traditional Unix folders by
default. The /usr/bin folder can be accessed from the Terminal application or
by using Finder's Go, Go to Folder… menu and typing /usr/bin in text
field presented.

The pbxbuild command is often used from automated scripts that build libraries and
applications at night while nobody is present to push the buttons in a graphical user
interface. pbxbuild can use any of the build styles defined in Project Builder. For
example, the command pbxbuild clean cleans the project in the current directory and
removes all intermediate files.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Other Tools

Several additional tools are provided on Apple's developer CD-ROM.

Concurrent Versions System This is a common open-source tool for text file
(CVS) version control. More information about CVS is
available at http://www.gnu.org/software/cvs/cvs.
html. CVS is installed with Apple's developer tools.
Source code for many large projects, including Mac
OS X itself, is controlled with CVS. The Concurrent
in the name is a reference to the fact that unlike
many other version control tools, CVS allows
multiple developers to edit the same file at the same
time. If conflicts arise between the different versions,
a tool like the FileMerge application described in this
section is used to reconcile the differences. CVS is
installed in /usr/bin.

Project Builder has limited built-in support for using

CVS. Many of the less common, but important CVS
tasks, must be performed using the command line
unless additional software that is not provided by
Apple is used. One free application that provides a
graphical user interface for CVS is CVL available at
http://www.sente.ch/software/cvl/#Download.

nibtool This is a command-line program to convert Interface

Builder .nib files to and from text files. It also
verifies the correctness of .nib files. It is
particularly useful when localizing an application for
different languages and cultures. The list of strings
used in a .nib file can be extracted with the
nibtool simplifying translation. nibtool can
also be used to produce textual descriptions of .nib
files so that different versions can be compared with
a tool like FileMerge. nibtool is installed in /usr/
bin.
otool This command-line tool shows information about
compiled binary files. Lots of information is
available, but otool is particularly handy for
showing the install locations of all dynamic libraries
needed by an application executable. The otool
program can be used to list all Objective-C classes in
a library or application. Otool is installed in /usr/
bin.

Quartz Debug This application highlights any drawing

inefficiencies in OS X applications. Quartz Debug
briefly flashes a yellow rectangle indicating each
area of pixels that is being redrawn, each time it is
redrawn. By watching the yellow flashes while an
application is running, it is possible to detect
unnecessary or redundant drawing. Quartz Debug is
installed in /Developer/Applications.

Sampler This is a noninvasive tool for profiling applications

to determine where they are spending processor
cycles. Sampler works with any Cocoa application. It
can even attach itself to an already running
application to find out what the application is doing.
Sampler interrupts the execution of an application at
regular intervals, records the current stack back-trace
at an instant, and then resumes the execution of the
application. Sampler then uses statistical analysis to
provide a rough approximation of the percentage of
program time spent in each function or method.
Sampler is an alternative to using specialized profile
libraries, when statistical sampling is a sufficient
measure. Sampler is installed in /Developer/
Applications.
FileMerge This Cocoa application is used to compare and merge
different versions of text files. FileMerge uses a nice
graphical interface to show differences between files.
The differences are then resolved in any of a variety
of ways and a file optionally containing elements
from both versions is saved. This is an outstanding
Cocoa application that quickly becomes invaluable to
developers. FileMerge is installed in /Developer/
Applications.
Book: Cocoa® Programming
Section: Chapter 3. Using Apple's Developer Tools

Summary

Apple provides world-class developer tools for Mac OS X at no extra cost to Mac
developers. Many of Apple's tools use open-source components that are common on other
platforms, such as Linux. The Gnu gcc, gdb, and CVS tools are used from Apple's project
Builder IDE. Interface Builder is an invaluable tool for Cocoa application development.
Interface Builder configures and connects reusable objects. In some cases, entire
applications can be created in Interface Builder without writing any code. Apple's
developer tools include a rich collection of utilities that simplify application development
and help with tasks such as performance profiling, version control, and file merging.

So far, the architecture of Mac OS X and the languages that are used for Cocoa
development have been described. This chapter provided an overview of the tools used to
create Cocoa applications. Chapter 4, "Objective-C," introduces the Objective-C language
that was used to write Cocoa. Most of Apple's examples and documentation about Cocoa
programming use Objective-C. Objective-C is a simple, small, and powerful extension to
ANSI C that directly enables many of the features of Cocoa.
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 4. Objective-C
IN THIS CHAPTER

● Why Learn Objective-C?

● Additions to C
● Apple's Extensions
● The NSObject Base Class
● Runtime Functions
● Objective-C++

This chapter introduces the Objective-C language, and explains how Objective-C
represents the concepts of object-oriented programming that were described in Chapter 2,
"Cocoa Language Options." This book focuses on intermediate and advanced techniques
that unleash the power of Cocoa; as a result, there is only room for a brief introduction to
Objective-C. The information presented in this chapter and the next is sufficient for an
experienced C++ or Java programmer to become immediately productive with Objective-
C. Familiarity with C and at least one object-oriented language is a prerequisite for this
chapter. The conventions described in Chapter 5, "Cocoa Conventions," are also essential
to understanding how Objective-C is actually used in conjunction with Cocoa.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Why Learn Objective-C?

The Objective-C language is the implementation language for Cocoa itself. Because of this,
an understanding of Objective-C is an important part of understanding Cocoa. It will help
you better comprehend the design philosophies underlying Cocoa. Many of the available
Cocoa code examples are implemented in Objective-C.

Objective-C is a superset of the ANSI C programming language. As a result, Objective-C

code can be integrated with exiting C code. The ability to conveniently reuse C code makes
Objective-C an ideal language for implementing modern object-oriented applications that
use operating system features made available only as C code. Objective-C applications are
capable of using every feature provided by the Mac OS X operating system.

Apple's rationale for selecting Objective-C is presented in the introduction to Apple's book,
Object-Oriented Programming and the Objective-C Language. Cocoa includes an
extremely flexible, extensible, and dynamic set of classes that can only be created with a
flexible and dynamic language like Objective-C. Apple's engineers note that Cocoa could
not have been written with a less dynamic language. The dynamism and flexibility of
Objective-C contribute to the high degree of code reuse and productivity that Cocoa
programmers enjoy.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Additions to C

Because Objective-C is an extension of the C language, you can use everything you know about C
when programming in Objective-C. Parts of the C language are used less often in Objective-C, but
they are all still available to anyone who wants to use them. On top of the C language, Objective-C
adds a few new types, several keywords, and some new idioms. It is designed to be simple yet
powerful. Because of this, it is easy to learn the key points in just a few minutes, if you already know
the C language and have a basic understanding of object-oriented concepts.

The principal new idiom that Objective-C adds to C is the concept of messaging between objects.
Objective-C includes the language elements needed to declare objects, specify the messages that the
objects understand, and send messages to objects.

Messaging

Messaging is the reason that Objective-C is so dynamic. A message is a request for an object to do
something. In Objective-C, the syntax for sending a message looks like this:

[someObject doSomething]

The square brackets ([ and ]) indicate the start and end of a message block. The variable
someObject is the receiver of the message. The variable doSomething is called a selector and
specifies the message to send. Messaging always takes the following form:

[receiver selector]

Messages can include arbitrary arguments and can return values. Any message can be sent to any
receiver. If the receiver does not understand a message that is sent to it, a runtime error occurs.
However, errors are easily avoided because at runtime it is possible to determine whether a particular
receiver can understand a particular message before the message is sent.

The message sending syntax might look foreign at first. One of the reasons messaging syntax is so
distinct from function calling syntax in Objective-C is that messaging is a very different operation
from a function call. The two concepts are so different that representing them with the same syntax
would be misleading.

Messaging is flexible and dynamic because both the receiver and the selector are variables. The
determination of exactly which message is sent to which receiver is deferred until the program is
running. At the time a program is compiled, it might not be possible to know what object or type of
object will be the receiver. At compile time, the selector might be unknown. The selector might not
even exist in the program at the time it is compiled. The selector could be added by dynamically
loaded objects or typed in by a user. Because of messaging, it is relatively simple to integrate
Objective-C with other dynamic languages as well as scripting languages.
The messaging system is so dynamic that the receiver might not even be in the same application as the
code that sends the message. Messages sent between processes on the same or different computers are
called distributed messages. The syntax for sending a distributed message is exactly the same as the
stntax for local messages. In fact, the compiler cannot determine if a message is distributed or not at
compile time.

Messaging is implemented by a simple, small, and efficient runtime. Most languages have a runtime
to initialize the program stack and heap and call a program entry point like the main() function used
in C. In Objective-C the runtime has a much more pervasive role. The Objective-C runtime is active
throughout the running life of a program and is much more than just an initializer.

File Naming and Importing

Objective-C files are stored in the file system with the .m extension rather than the traditional .c
extension used for C code. The .m extension tells the compiler to expect Objective-C code rather than
standard C code. The source code of an Objective-C application is usually composed of header files
with the .h extension, and implementation files with the .m extension, just as C uses .h and .c.

Objective-C files can include header files by using the standard C #include preprocessor directive
or by using the #import preprocessor directive. The #import directive is similar to the
#include directive. #import assures that no file is imported more than once. Objective-C header
files that are imported don't need to be surrounded by "guards" (usually implemented with #define,
#ifndef, and #endif) to keep them from being included multiple times. You must use the
#import directive to import Cocoa headers because the Cocoa headers don't contain guards.

NOTE

In addition to the #import preprocessor directive, the Objective-C preprocessor

understands // style comments. As with C++ and some dialects of C, the // symbol is
used to start a comment that continues to the end of the line.

The id Type

As already mentioned, Objective-C is an object-oriented language. In the most general sense,

Objective-C defines an object as anything that can receive messages. The receiver of an Objective-C
message does not need to be known at compile time. The specific type of the receiver does not even
need to be known. When sending a message, the only requirement is that receiver is an object.

Objective-C introduces a new type, id, that is a pointer to an object. A variable with the id type can
be used as the receiver of any message. The id type is similar to the standard C void * type in the
sense that the compiler knows very little about the memory being referenced.

The id type is used the same way as any other C type. The following code declares a variable of type
id.
id anObject;

As declared, the variable anObject is a pointer to any object. In C, any pointer can be set to the
constant value, NULL. In Objective-C, any pointer to an object can be set to the constant nil.
Messages sent to nil are not errors. The only caution is that the value returned from a message to
nil is undefined in some cases.

Static Typing

The id type should only be used when very little information is known about an object and the
maximum flexibility allowed by the language is needed. The compiler should be given as much
information about objects as possible. When details about an object are known, static typing is used to
convey the details to the compiler.

To use static typing, simply declare a pointer to an instance of a particular class of object. For
example, given an existing class called NSString, a variable that stores a pointer to an instance of
NSString is declared as follows:

NSString *theString;

When the compiler subsequently encounters theString as the receiver of a message, the compiler
can use the specified type information to verify that theString is an object that can understand the
message being sent. If the compiler cannot find any appropriate declaration of the message being sent,
a warning is generated. The compiler generates a warning rather than an error because the compiler
cannot be certain that the message will not be understood. It is possible that the receiver does
understand the message, but the message has not been declared in a way that the compiler can verify.

The following types are defined by the Objective-C runtime, and can be used in programs.

SEL: used to store selectors

IMP: used to store pointers to the C functions that implement messages

Class: used to store pointers to Objective-C class objects

id: used to store pointers to arbitrary Objective-C objects

BOOL: used to store the Boolean constants YES and NO

Static typing of objects may be used even when the class of the object is not fully declared. The
@class keyword is used to inform the compiler that a type is a class as follows:

@class NSArray, NSString, NSNumber;

@class NSDictionary;

The declarations specify that NSArray, NSString, NSNumber, and NSDictionary are all valid
class names that can be used for static typing. This form of class declaration is called forward
declaration and is used in the same situations in which standard C structures are forward declared.

Declaring a Class

Declaring a class specifies the values that instances of the class will store, as well as the messages that
the class itself and instances of the class will understand. It is not necessary to specify all the messages
that can be understood by a class in the class declaration. Support for messages can be deliberately
hidden or even added at runtime. The class declaration is only a hint to the compiler regarding
messages, but the declaration is the only place that instance variables can be defined.

A class consists of two parts, an interface and an implementation. As described in Chapter 2, "Cocoa
Language Options," classes are used to encapsulate data and behavior. The complexity of an
implementation is hidden behind an interface through which the class is used.

Several new keywords exist to declare a class interface. Class interfaces begin with the @interface
keyword and end with the @end keyword as follows:

@interface MYObject : NSObject

{
}

@end

In the example, a new class called MYObject is declared to be a subclass of the NSObject class.
The NSObject class is part of Cocoa. Almost every class in Cocoa is directly or indirectly a subclass
of NSObject. More information about NSObject is provided later in this chapter. At this time, it is
only important to note that because MYObject is a subclass of NSObject, MYObject inherits all
the NSObject class's instance variables and understands all the messages that NSObject
understands. Objective-C does not allow multiple inheritance. It is only possible to declare at most one
super class. A new class can be declared with no super class by omitting the colon (:) character and
the superclass name.

Instance Variables

In the MYObject class interface, no instance variables beyond those inherited from NSObject are
defined. If MYObject had additional instance variables, they would be defined between the curly
braces ({ and }) in the interface declaration. The general form of a class interface declaration follows:

@interface CLASS-NAME : SUPER-CLASS-NAME

{
INSTANCE VARIABLE DECLARATIONS
}

METHOD DECLARATIONS

@end
The instance variables can have any previously defined type. For example, the following class
interface declaration defines a class that encapsulates circles in a hypothetical drawing program:

@interface MYCircle : NSObject

{
NSPoint _myCenter; // NSPoint is a Cocoa C structure
float _myRadius; // float is a standard C type
BOOL _myIsFilled; // BOOL is a Boolean type
NSColor *_myColor; // NSColor is a Cocoa class
id _myExtraData; // this can be any kind of object
}

@end

The @public, @private, and @protected keywords can be used to restrict the use (scope) of
instance variables. Public instance variables can be accessed directly by any code. Protected instance
variables can be accessed directly by instances of the class that declares the protected variables, and
also subclasses of that class. Private instance variables can only be directly referenced by instances of
the class that declares the private variables. When not otherwise specified, instance variables are
protected. The MYCircle class could be modified as follows to use the instance variable scope
keywords:

@interface MYCircle : NSObject

{
NSPoint _myCenter; // NSPoint is a Cocoa C structure
@public
float _myRadius;
@private
BOOL _myIsFilled; // BOOL is a Boolean type
@public
NSColor *_myColor; // NSColor is a Cocoa class
id _myExtraData; // this can be any kind of object
}

@end

All instance variables declared after one of the scope modifying keywords have that specified scope
until another scope modifying keyword is specified. In the MYCircle example, _myCenter is
protected because no scope is specified prior to its declaration. The _myRadius, _myColor, and
_myExternalData instance variables have public scope, whereas the _myIsFilled instance
variable has private scope.

It is seldom a good idea to puncture the encapsulation of instance variables by declaring them public.
Public instance variables can be accessed just like the members of a C structure. For example, given a
pointer to an existing instance of MYCircle, the _myRadius instance variable could be accessed
from any code as follows:
MYCircle *anInstance = someObject;
anInstance->_myRadius = 13.5f;

You should rarely use the private scope. When an instance variable is declared private, subclasses
cannot directly use the instance variable they inherited. Not all uses of a class can be foreseen. Using
the private scope might restrict valid uses of the variable in unanticipated future subclasses.

The protected scope is usually the best compromise between encapsulation and flexibility.

Methods

In Objective-C, an object is loosely defined as anything that can receive messages. Different objects
can react in different ways upon receipt of the same message. In other words, different objects can
have different methods of responding to a message. When declaring a class, it is possible to declare
the methods that will be used to react to messages. Methods have the same name as the message they
handle, and the terms message and method are sometimes used interchangeably when describing the
behavior of an object. There is usually a correspondence between the set of methods that an object
implements and the messages an object can understand. The phrase, "calling a method" is
interchangeable with the phrase "sending a message."

When declaring a class interface, methods implemented by the class can be specified. Some, all, or
none of the class's methods can be declared in the interface. The methods declared in the class
interface aid the compiler when static typing is used, but they are just a hint. Methods that were never
declared in a class interface can nevertheless be implemented and might even be added to a class
dynamically at runtime.

Methods a class implements might be deliberately excluded from the class interface to discourage
their use. In Objective-C, there is no way to declare a method private or protected. All methods are
public. However, methods that should not be called in certain situations should not be declared in the
class interface. If static typing is used, the compiler will generate a warning whenever a method that
was not declared is used. The warning is a hint to programmers that they should not be calling that
method. A technique for declaring methods so that the compiler generates the correct warnings for the
use of methods in some situations and not others is presented when Objective-C categories are
described later in this chapter.

Two types of methods can be declared in a class interface: instance methods and class methods.
Instance methods are invoked when an instance of the class receives a message. Class methods are
invoked when the class itself receives a message. Class methods are sometimes called factory methods
alluding to the fact that most class methods are used to build new instances.

NOTE

In Objective-C, each class is represented at runtime by an object. Class objects can

receive messages. Class objects are sometimes called Meta-Objects because they contain
information about other objects. A class object encapsulates the definition of instance
objects and is used to construct instances.
Method declarations occur after the closing curly brace of the instance variable declarations and
before the @end that ends the interface declaration as follows:

@interface CLASS-NAME : SUPER-CLASS-NAME

{
INSTANCE VARIABLE DECLARATIONS
}

METHOD DECLARATIONS

@end

Instance methods are declared with a leading minus (-) as follows:

- (int)count;

The -count method handles any count messages that are received by an instance of the class that
declares the -count method.

Class methods are declared with a leading plus (+) as follows:

+ (void)setVersion:(int)number;

The +setVersion: method handles any setVersion: messages that are received by the class
itself.

The method's return type is after the plus or minus symbol in a method declaration. This looks like a C-
language cast because it is written as a C type in parentheses. The return type is optional, however. If
you don't provide it, the default return type assumed by the compiler is id. A method that doesn't
have a return value should return void.

The method's name follows the return type and extends to the semicolon (;) that ends the method
declaration. In the preceding examples, the -count method does not take input parameters. The
+setVersion: method accepts a single integer parameter. Input parameters are always denoted by
the presence of colons (:) in the method name.

The colon itself is part of the method name, so the methods -init and -init: are considered to be
two different methods, each with a unique implementation. After each colon in a method name is a
type, in parentheses, that specifies the type of the input parameter, and the variable name used inside
the method's implementation code to refer to the input parameter. If no type is specified for an input
parameter, the compiler assumes that the parameter has the type id.

The colons in method names enable the naming of parameters. Consider the following method
declarations:
- (void)setArgument:(void *)argumentLocation atIndex:(int)index;
- (BOOL)lockWhenCondition:(int)condition beforeDate:(NSDate *)limit;
- (NSString *)descriptionWithCalendarFormat:(NSString *)format
timeZone:(NSTimeZone *)aTimeZone locale:(NSDictionary *)
locale;

Although these method declarations look complex, they all follow a simple pattern. After each
parameter there is some space followed by another name, colon, type declaration, and input variable
name. Any number of parameters of any type can be added to the method declaration this way.

Just as the colons are considered part of the method name, Objective-C method names include all the
text before each input parameter. Therefore, the actual method names for the three previous methods
are setArgument:atIndex:, lockWhenCondition:beforeDate:, and
descriptionWithCalendarFormat:timeZone:locale:.

By interspersing parameter names with parts of a method name, it is possible for code to read almost
as if it were natural language. This provides an advantage for code readability, maintainability, and
clarity. Of course, badly chosen names can still lead to incomprehensible code. You cannot reorder the
segments of a method name. The following are two different methods:

descriptionWithCalendarFormat:timeZone:locale:
descriptionWithCalendarFormat:locale:timeZone:

It is possible to leave out the text between the colons. Objective-C doesn't require anything other than
a colon to specify a new parameter to a method, but it is usually poor style to not use some kind of
brief explanatory text. The method declaration, - (void)moveTo:(int)x :(int)y;, is valid
and declares the method named moveTo::, which takes two integer parameters, x and y, and returns
nothing.

A method's name is the same as the message it handles. Methods are invoked upon the receipt of a
message. The name of the message is used to select which method to execute. Message names are
called selectors. Message names can be stored in variables with the type SEL defined by the Objective-
C runtime. A method name can be converted into a SEL value by the compiler with the @selector
keyword as follows:

SEL aSelector;
aSelector = @selector(setObject:forKey:);

The value of the aSelector variable is set to the selector that represents the method named
setObject:forkey:.

Selectors can be passed as arguments to methods and functions. For example, the -(void)
performSelector:(SEL)aSelector withObject:(id)anObject method can be called
to ask the receiver to execute the method identified by aSelector using anObject as an input
parameter.

It is also possible to ask an object to provide a pointer to the function that implements a method
identified by a selector. Such function pointers are stored in variables with the type IMP, which is
defined by the Objective-C runtime. IMPs are only used as an optimization in rare cases. The use of
IMPs is described in the optimization section of this chapter.

Implementing a Class

Class implementations begin with the @implementation keyword and end with the @end
keyword. Class implementations contain the implementations of methods. Defining method
implementations is done much the same as implementing C functions. The code that implements a
method is defined after the method name and enclosed in curly braces. Consider the following class
interface for the MYAverager class:

#import <Foundation/Foundation.h>

@interface MYAverager : NSObject

{
float _myValueArray[10];
}

- (float)avarageValue;
- (void)setValue:(float)aValue atIndex:(int)anIndex;

@end

The MYAverager class is simple. It stores ten floating-point values, each of which can be set by
calling the -setValue:atIndex: method. The average of the ten stored values is returned from
the -average method. The MYAverager class can be implemented as follows:

#import " MYAverager.h"

@implementation MYAverager

- (float)avarageValue
{
int i;
float sum = 0.0f;

// sum the values

for(i = 0; i < 10; i++) {
sum = sum + _myValueArray[i];
}

// return the average

return sum / 10.0f;
}

-(void)setValue:(float)aValue atIndex:(int)anIndex
{
// set the value with the specified index
if(anIndex >= 0 && anIndex < 10) {
_myValueArray[i] = aValue;
}
}

@end

self and super

When writing implementation code, sometimes it is helpful for an object to be able to send messages
to itself, or to use itself as a parameter in a message to another object. To make this possible,
Objective-C methods have a hidden parameter called self. In an instance method, self is a pointer
to the instance object that received the message being handled by the method. In a class method,
self is a pointer to the class object that received the message being handled.

The self variable can occur in any context that allows variables. It can be the receiver of a message
such as [self setValue:10.0f atIndex:4]. The value of self can be assigned and it can
be returned from methods. self is often passed as a parameter to other methods.

NOTE

All Objective-C methods also have another less-used hidden parameter, _cmd, which
stores the selector that was used to invoke the method.

Objects often implement methods that are also implemented by a superclass. The super keyword can
be used to invoke a superclass's implementation of a method. super is not a variable, and can only be
used as the receiver of a message. The super keyword can only be used within a method
implementation.

An -init method can be added to the MYAverager class previously declared. The following
method demonstrates the use of self and super:

-(id)init
{
int i;

// set the self variable to the value returned from the

// inherited implementation of -init
self = [super init];

// initialize the stored values by sending messages to self

for(i = 0; i < 10; i++) {
[self setValue:0.0f atIndex:i];
}
 // return self
return self;
}

Creating Instances

After a class has been implemented, instances of the class are created by calling the +alloc class
method declared in the NSObject class. The need to inherit the +alloc method is one of the main
reasons that almost all classes are subclasses of NSObject. After an instance is created it must be
initialized by calling an instance method. The section about the NSObject base class in this chapter
describes the role of the NSObject class in instance creation. The process of allocating and
initializing instances is handled by conventions explained in the next chapter.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Apple's Extensions

No standard exists for the Objective-C language and runtime. The Apple and Gnu implementations of Objective-C
include some powerful extensions to the language. The principal extensions are categories, protocols, type encoding,
and constant string objects. The extensions are used throughout Cocoa and enable much of the power and flexibility that
Cocoa programmers enjoy. The Apple and GNU compilers support the same extensions.

Categories

Categories enable the addition of methods to any class and can be used as an organizational tool or as an alternative to
subclassing. Categories are declared to extend existing classes. The name of the category is specified in parentheses
after a class name. The following category declaration extends the previously introduced MYAverager class to be able
to add a -max method:

#import "MYAverager.h"

@interface MYAverager (SampleCategory)

- (float)max;

@end

The -max method can be implemented to return the maximum value stored in a MYAverager instance:

@implementation MYAverager (SampleCategory)

- (float)max
{
int i;
int result = myValueArray[0];

for(i = 1; i < 10; i++) {

if(myValueArray[i] > result) {
result = myValueArray[i];
}
}
return result;
}

@end

When categories were first introduced, NeXT recommended that they be used to break large implementation files into
several smaller files so they could be used to organize the methods. For example, all the private methods that should not
be called except by the class's author can be organized into a category that is concealed from other programmers. There
is no way to restrict which methods of a class can be called in which contexts, but methods can be hidden from the users
of a class. The extra effort to find out which hidden methods exist is usually enough to discourage their use.

Categories containing private methods are often added within implementation files so that there is no header file that
declares the methods, and they can still be used within the object's own implementation without warnings. In fact,
category declarations do not need an interface at all. Only the implementation is necessary.

Categories are useful for organizational purposes, but that barely touches the power and flexibility enabled by them.
Methods can be added to any class without needing the source code for the class that is extended, or recompiling.
Categories are an alternative to subclassing with some limitations. One limitation is that categories cannot be used to
add instance variables to a class the way a subclass can. Nevertheless, using categories is preferable to subclassing in
many situations. For example, suppose your application calls a method implemented by a Cocoa framework class to
obtain an object. The class of the object returned by the framework was determined when the framework was written.
Subclassing the returned object won't help because there might not be a way to get the framework to return your
subclass instead of the class that was compiled into the framework. The class returned by the framework can be
extended by a category implemented in your code to add the methods you need.

Methods added by a category can override existing implementations, and it is possible to patch bugs in classes to which
you have no source code. To do so, replace the offending method with a correct implementation in a category. A
restriction when replacing methods is that there is no convenient way to call the original implementation from the
overriding implementation. The overriding method must duplicate the entire functionality of the replaced method. Also,
if more than one category implements the same method, then it is unpredicitable which method will be chosen for use
by the runtime.

Methods that are implemented in a category can access all the extended class' instance variables directly. At runtime,
methods that are declared in a category are no different from methods declared in the class interface. All subclasses of
the extended class also gain the category's methods. Even preexisting instances gain the category's methods when code
containing a category is dynamically loaded during a program's execution. It is possible to have an object that does not
understand certain messages when the application starts, but does understand them after a plug-in containing a category
has been loaded.

Categories are a powerful feature that can be easily abused. A good practice is to add a unique prefix to the start of any
method names defined in categories that modify framework classes. The prefix reduces the chance of an accidental clash
with a hidden framework method or a method in another category, which can happen easily. After a while, programmers
get in the habit of naming methods according to the conventions used in Cocoa. If you think of a method to add to a
Cocoa class, there is a good chance someone else has thought of the same method and given it the same name. Another
danger is that Apple will add the same method in a future release, but the method will be masked by a preexisting
category. Even if a method added via a category does not create a conflict now, it may in a future version of Cocoa.

Protocols

Protocols enhance static-type checking and help optimize distributed messaging. An Objective-C class inherits all the
methods and instance variables implemented by its superclass. This type of inheritance is sometimes called
implementation inheritance. Protocols embody the related concept called interface inheritance. Interface inheritance
means that method declarations are inherited, but not method implementations. A protocol declares a set of methods but
does not provide any implementations. Protocols can be used in combination with static typing to assure the compiler
that an object can understand the messages that are sent to it.

NOTE

An Objective-C protocol is analogous to a Java interface. An Objective-C interface is a different concept,

and this terminology difference can be a point of confusion between Java and Objective-C programmers.

Declaring and Adopting Protocols

Working with protocols consists of two aspects. First, a protocol must be declared, and is then adopted by one or more
objects. A protocol declaration defines methods, somewhat similar to an object interface, but it does not define instance
variables or implementations for the methods. There are no implementation files for protocols.

A protocol is defined using the @protocol keyword. For example, a simple protocol defining two methods looks like
this:
@protocol UpDown
- (void)increment;
- (void)decrement;
@end

The protocol's name follows the @protocol keyword. Between the @protocol and @end keywords are the
protocol's method declarations. If our sample class, MYAverager, were to adopt the protocol, we would change the
MYAverager class interface declaration to the following:

#import <Foundation/Foundation.h>
#import "UpDown.h"

@interface MYAverager : NSObject <UpDown>

{
float _myValueArray[10];
}

- (float)avarageValue;
- (void)setValue:(float)aValue atIndex:(int)anIndex;

@end

First, the header file that declares the UpDown protocol is imported so the compiler knows the protocol's details. Next,
the protocol name is enclosed in angle brackets (< and >) and placed after the object's name and superclass declarations.
To specify the adoption of more than one protocol, list the protocol names inside the angle brackets, separated by
commas. The general form of a class interface that adopts protocols follows:

@interface CLASSNAME : SUPERCLASSNAME <PROTOCOL-LIST>

Category declarations can adopt protocols using the following syntax:

@interface CLASSNAME (CATEGORYNAME) <PROTOCOL-LIST>

One way of describing that a class is guaranteed to implement all the methods of a protocol is to say that the class
conforms to the protocol. If a class adopts a protocol then that class conforms to the protocol. If a loaded category of a
class adopts a protocol then that class conforms to the protocol. Finally, all the classes that inherit from a class that
conforms to a protocol also conform to the protocol. Conforming to a protocol just means that all the methods declared
in the protocol have been implemented either directly or through inheritance or a category.

After a class or category declares that it adopts a protocol, the compiler will require that all the methods found in the
protocol are actually implemented. There is no requirement to place a protocol's method declarations in the class or
category interface file because the protocol already declares them. Because categories can be loaded dynamically to add
methods to existing classes at runtime, and protocols can be adopted by categories, it is possible to dynamically add
protocol conformance to classes at runtime also.

NOTE

Protocol names have their own name space and do not conflict with class or function names. For example,
the Cocoa frameworks declare the NSObject class and there is also an NSObject protocol.

Static-Type Checking with Protocols

Type declarations for variables, method parameters, method return types, function parameters, and function return types
can include protocol conformance requirements to refine static-type checking. The following examples show several
ways in which protocol conformance can be included in a type:

id <SomeProtocol> aVariable;
NSObject <SomeProtocol, AnotherProtocol> *anotherVariable;
id <NSObject> SomeFunction();
- (id <SomeProtocol>)methodThatReturnsAnObject;
- (void)methodThatAcceptsAnObjectParameter:(MYAverager <SomeProtocol> *)
anObject;

Static type checking enables the compiler to verify correct type usage based on protocol conformance, class, and
inheritance in any combination.

Types based on protocols uncouple the concept of class from the set of messages that can safely be sent to an object.
Often, the only important information about an object is the set of messages it understands. Specifying that an object
conforms to a protocol asserts that it doesn't matter what class is used as long as it responds to a set of messages.
Information about the specific class and inheritance of an object constitutes implementation details. Protocols used in
types enable the compiler to check type safety, and verify support for particular messages without unnecessary
dependence on a particular class hierarchy.

Multiple-Interface Inheritance

Objective-C does not allow multiple-implementation inheritance, but multiple-interface inheritance is supported through
protocols. A class can adopt any number of protocols, and protocols themselves can adopt other protocols. To declare
that one protocol adopts another, just include the adopted protocol names in angle brackets (< and >) after the protocol
declaration using the following syntax:

@protocol PROTOCOLNAME <PROTOCOL-LIST>

Any object that conforms to PROTOCOLNAME also conforms to all the protocols in PROTOCOL-LIST.

Protocol Objects

Protocols are similar to classes because they both declare methods. The Objective-C runtime encapsulates class
definitions with class objects. Protocols are encapsulated by protocol objects. Apple's Objective-C runtime encapsulates
protocols with a class called Protocol. The compiler creates class objects automatically from class declarations, and
creates protocol objects automatically from protocol declarations.

References to class objects can be stored in variables and passed as arguments to methods. References to instances of
the Protocol class can be used in the same ways. The @protocol() compiler directive accesses the instances of
the Protocol class that are stored in the runtime as follows:

Protocol *aProtocol = @protocol(UpDown);

The variable, aProtocol, is a pointer to an instance of the Protocol class, and is initialized to reference the
protocol called UpDown.

Protocols in Distributed Messaging

Another important use of protocols is to optimize distributed messaging. Messages can be sent to objects in a different
process on a different computer. The Objective-C runtime routinely sends messages between anonymous objects, and
has little knowledge about either the sender of the message or the receiver. Nothing special is done with the parameters
and return values of messages sent to objects in the same process, but the runtime must package the messages'
arguments and return value for network transport.
If the runtime does not know enough information about the receiver of a distributed message to correctly package the
parameters and return value, the runtime must interrogate the remote object to get that information. The interrogation
consumes some of the network bandwidth and performance.

Protocols can be used to optimize distributed messaging. The runtime can ask the remote object if it conforms to a
particular protocol. Subsequent distributed messages that are defined by the protocol can be efficiently packaged and
sent over the network. The protocol conformance only needs to be checked once, and that one check verifies the
existence and types of all the methods declared in the protocol.

Type Encoding

Type encoding is used by the runtime to aid the dispatching of messages to objects. The encoding is essential when
distributed messages are sent so that parame-ters and return types can be packaged and sent over a network. Type
encoding is also a convenience that helps programmers avoid mistakes.

The Objective-C runtime encodes parameter types and return types as C strings. Each character in the string specifies a
property of the type. The specific format of the encoded type strings is not important in this introduction. Details about
type encoding are provided in Apple's online document at http://developer.apple.com/techpubs/macosx/Cocoa/
ObjectiveC/4MoreObjC/index.html.

Encoded type information can be useful outside the Objective-C runtime, and is obtained by the @encode() compiler
directive. The @encode() directive works in much the same way as the ANSI C sizeof() operator works, and can
accept the same arguments as sizeof(). The value returned from @encode() can be assigned to a char * as
follows:

char *aTypeString = @encode(int **)

Type encoding is particularly useful for encoding and decoding the instance variables of objects, as described in Chapter
5. The methods used to encode variables require a C string parameter that specifies the types to encode. The C string can
be created as a constant string or via the @encode() directive. It is relatively easy to make mistakes when constructing
type strings by hand. Therefore, the use of @encode() to automate the task is preferred.

Constant-String Objects

The Cocoa frameworks include the NSString class to encapsulate strings. The details of the NSString class are not
important in this chapter, but using NSString instances instead of C strings has many advantages. However, C-string
constants can be allocated by the compiler and stored as bytes within an executable program. Objective-C instances are
typically dynamically allocated at runtime. It is possible to programmatically create an NSString instance that is
initialized with a particular constant string at runtime. However, it is cumbersome to litter an application with hundreds
of lines of code just to convert constant C strings into constant NSString instances.

Apple's Objective-C compiler includes an extension to enable the compiler to generate constant NSString instances.
Constant string objects are both an optimization and a convenience for programmers. Programmers do not have to write
code to explicitly create constant NSStrings at runtime. The CPU cycles and memory allocations needed to create the
constant string objects at runtime are avoided.

To use constant strings in code, declare the strings as follows:

@"This is a constant string"

The leading @, before the quotes, informs the compiler that an NSString instance should be stored in the executable
instead of storing a C string. Strings created with the @"" syntax can occur in any context that an NSString instance
is allowed. It is safe to send messages to constant strings or return them from methods or functions.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

The NSObject Base Class

The Objective-C language allows the creation of any number of base classes, sometimes
called root classes. A base class is a class that does not have a superclass. However, Cocoa
depends on the fact that almost all classes have a common base class. In Cocoa, the common-
base class is NSObject.

The NSObject class is an abstract class meaning that programs use instances of classes that
inherit from NSObject, but rarely use instances of NSObject itself. NSObject is a
powerful class and a complete description of all its features is beyond the scope of this
chapter. The NSObject class documentation that comes with the Apple developer tools is
excellent and complete. Some key features of NSObject that enable much of the power and
flexibility of Cocoa are described here.

There are many advantages to using a common-base class. Almost all the objects used in
Cocoa inherit directly or indirectly from NSObject. As a result, messages that are
understood by NSObject are understood by almost every Cocoa object. The NSObject
class includes many powerful features that are ubiquitous because the common-base class
provides them. Furthermore, methods can be added to the NSObject class via categories.
Adding methods to NSObject effectively adds those methods to every Cocoa object.

NOTE

Methods that are added to the NSObject class by a category are sometimes
called an informal protocol. Such methods are similar to the methods declared
in a protocol because the programmer can safely assume that the methods are
available in an anonymous object.

The NSObject class encapsulates much of the Objective-C runtime's functionality, and
gives all objects basic, introspective abilities. NSObject conforms to the NSObject
protocol, and declares only one instance variable called isa. This variable points to the class
object that encapsulates the instance's class. The isa variable enables the runtime to
determine the class of an instance. The isa variable is almost never accessed directly by
code. The class of an object can be determined by sending it the -class message.

The NSObject class provides methods for dynamically allocating memory for new
instances and initializing the newly created instances. The specific allocation and
initialization techniques used by Cocoa are not part of the Objective-C language definition.
Instead Cocoa introduces conventions, and NSObject implements the methods needed to
support Cocoa's conventions. In Cocoa, an instance is allocated by sending the +alloc
message to a class object. The instance that is returned from +alloc still needs to be
initialized using a variant of the -init message. The +alloc, and -init methods are
described in Chapter 5. Few classes override the +alloc method inherited from the
NSObject class. As a result, NSObject's +alloc method focuses almost all dynamic
memory allocation into just one place in code, and that can be a useful attribute of Cocoa
programming.

In addition to methods that allocate and initialize instances, the NSObject class provides
methods for deallocating, copying, comparing, archiving, and sending objects to other
computers over networks. NSObject has methods that interact with the Objective-C
runtime to forward messages to other objects. NSObject also provides methods that
implement one of the most powerful features of Cocoa, the capability to ask objects for
information about themselves.

Object Introspection

The NSObject class includes methods that provide information about objects and expose
runtime details about objects. For example, to find out if an anonymous object understands a
particular message, send the -respondsToSelector: message with the selector for the
message in question as a parameter. If -respondsToSelector: returns the BOOL value
YES, then it is safe to send the message in question. The capability to obtain information
about objects is called introspection because the objects look into themselves to provide the
information.

To find out if an object responds to a message, use the following methods:

+ (BOOL)instancesRespondToSelector:(SEL)aSelector
- (BOOL)respondsToSelector:(SEL)aSelector

NSObject provides the -class method to determine the class of an object at runtime. A -
superclass method returns the receiver's superclass as well. Two more introspective
methods are -isKindOfClass: and -isMemberOfClass:.

- (BOOL)isKindOfClass:(Class)aClass
- (BOOL)isMemberOfClass:(Class)aClass

Both -isKindOfClass: and -isMemberOfClass: return YES if the receiver's class

matches aClass exactly. The -isKindOfClass: method will also return YES if the
receiver is a subclass of aClass. As a result, -isKindOfClass: is usually preferred.
The need to use the more restrictive -isMemberOfClass: is relatively rare.

Beyond methods to determine the class of an object, whether an object can respond to a
message, and whether an object inherits from a certain class, NSObject provides the -
conformsToProtocol: method to determine if the receiver conforms to a particular
protocol. The -conformsToProtocol: method is commonly used as follows:

If([someObject conformsToProtocol:@protocol(SomeProtocol)]) {
// Safely send methods declared in SomeProtocol to
someObject
}

The Introspective Format

C programmers are familiar with the idea of formats in functions such as printf(). Many
Cocoa classes, such as NSString, and functions, such as NSLog(), use formats as well.
Cocoa formats support most printf() formats and add an extra code, %@, to mean an
object. The following example demonstrates the use of a Cocoa format used with the NSLog
() function:

NSLog(@"Log the description of an object: %@", someObject);

NSLog() prints text messages to an error log. In this example, the constant string "Log
the description of an object: " is output followed by a description of
someObject. How should an object be rendered as text? Only the object itself knows.
Whenever the %@ format is used, one of the following methods will be used to determine
how to print the corresponding object by asking it to describe itself:

+ (NSString *)description
- (NSString *)description

Optimization

Although the Objective-C message dispatcher is extremely fast, when a message must be sent
multiple times to the same object in a tight loop, the messaging overhead might become
significant. It is possible, in very specific circumstances, to bypass the message dispatcher to
gain a slight boost in speed. This is dangerous and is discouraged, but if you feel you must do
it, start by obtaining a pointer to the function, which implements the method for a given
object by using one of these methods:

+ (IMP)instanceMethodForSelector:(SEL)aSelector
- (IMP)methodForSelector:(SEL)aSelector

The IMP is a pointer to a C function, which takes as its arguments self (a pointer to the
instance), _cmd (the selector you used to obtain the IMP), and then whatever parameters the
method itself requires. As an example of how you would use this, suppose we have an object
which implements the method -incrementBy: and you want to call the method 100,000
times as quickly as possible with the loop variable as the parameter. It could be done this way:
SEL theSelector = @selector(incrementBy:);
IMP theIMP = [someObject methodForSelector:theSelector];
int i;

for (i=0; i<100000; i++) {

theIMP(someObject, theSelector, i);
}

This use of IMPs is dangerous. Suppose you were cycling over an array of receivers. In that
case, unless the receivers are instances of the same class, the IMP you should be using would
vary from one instance to another. Furthermore, some classes might respond to a particular
message, but not have a valid IMP. An example is presented later in this chapter where this
can happen because of the use of forwarding. The Objective-C runtime takes care of all these
details automatically for messages, but you must take care of them when using an IMP.
Misuse of IMPs leads to strange, difficult-to-diagnose bugs.

Object Comparison

NSObject provides some basic facilities for comparing objects in the form of these two
methods:

- (BOOL)isEqual:(id)object
- (unsigned)hash

Your subclasses probably need to reimplement these methods so that the suitable
comparisons are performed. The default implementations simply use the pointer to the object
as a comparison value; if the pointers are the same, the objects must be equal because they
are the same object. However, your subclass's instances might be equal, even when the
objects are different instances. Your implementation of -isEqual should reflect that.

The -hash method simply returns a value based on the value of a pointer to the receiving
object. If you create a string class, or some other type of class for which a hashing function
exists, you should probably reimplement the -hash method. The main idea of hashing is to
provide some number that can be used to identify an object.

Cocoa imposes some rules that must be observed if the -isEqual method is overridden.
First, if -isEqual: returns YES when comparing two objects then the -hash methods of
the two compared objects must also provide equal values. Second, if -isEqual: returns NO
then the return value of -hash may or may not be equal (the better the hashing, the less
likely that they will be equal). Hashing in general is a complex subject and is beyond the
scope of this book.

NOTE
 If you want to learn more about hashing, check out Sams Teach Yourself Data
Structure and Algorithms in 24 Hours. Part V of this book covers hash tables.

Runtime Integration

Many of the features of the Objective-C runtime can be accessed via NSObject methods.
The NSObject class encapsulates most of the interaction between programs and the runtime.

Class Initialization

Two class methods are declared by NSObject, which the runtime calls automatically to
initialize classes:

+ (void)load
+ (void)initialize

The first method, +load, is called when a class is linked into a running program. It is
possible for programs to load new program code as they run (see the NSBundle class
described in Chapter 7, "Foundation," for more information). If a class is loaded in this way,
the +load method is called, offering the class an opportunity to take special actions. More
commonly, +initialize is used for setting up a class object. This method is treated in a
slightly special way: it will be called once and only once for each class object in the program.
It will be called just before the program uses that object for the first time. Subclasses that
implement this method should never call the super implementation of the method.

Posing

It is possible to have a particular class stand in for another class. This technique, known as
posing, can be used to patch system classes or alter their behavior across the whole program.
If you want one class to pose as another, use this method implemented by NSObject:

+ (void)poseAsClass:(Class)aClass

There are a few rules you absolutely must follow for posing to succeed. First, posing must be
initiated before aClass is instantiated for the first time. If there are any instances of
aClass already, then it is too late to pose. Second, the receiving class object must be a
subclass of aClass, which adds no instance variables. Because of these restrictions, it is
often much easier to use a category to add or patch some of a class's methods, instead of
attempting to create a new object and have it pose as the class in question.

Performing
The Objective-C runtime also enables you to send a message that was not predetermined at
compile time. There are three methods declared in NSObject that can be used to do this:

- (id)performSelector:(SEL)aSelector
- (id)performSelector:(SEL)aSelector withObject:(id)object
- (id)performSelector:(SEL)aSelector withObject:(id)object1
withObject:(id)object2

A few other methods also do this, allowing for an optional delay in sending the message.
These methods differ only in the arguments they accept. Which one you should use depends
on aSelector. If aSelector takes no arguments, use the first. If it takes a single
argument, use the second. If it takes two arguments, use the third. The arguments must all be
of type id, or convertible to id, and the return value is id.

As an example of using these methods, suppose you have an instance variable that is a
selector (SEL type) called action, and another that points to an object called target. Further
assume that the selector is always known to have a single parameter, an id called sender.
You might send the action message to target like this:

[target performSelector:action withObject:self];

See Chapter 8, "The Application Kit Architecture," for examples of targets and actions in use.

Forwarding Messages

The Objective-C compiler does not guarantee a given object will be able to respond to a
given message. More importantly, the compiler cannot guarantee that a receiver can't respond
to a message. As previously shown, methods can be added dynamically by categories, but an
even more powerful facility exists. The Objective-C runtime and the NSObject class
provide a way of trapping messages. Some objects can respond to a message and not yet have
an implementation in machine code for that message. Messages can be transparently
forwarded to another object.

Messages need to have a transport to get them from one place to another. In Objective-C the
default transport is to use the underlying function call semantic, of the C language. However,
it is possible to insert your own transport via forwarding. Here's how it works:

The Objective-C message dispatcher looks at the receiver of a message and checks to see if it
can respond to the message using the default function call semantic. If it can, that will be
used. If not, it asks the instance to attempt to deal with the message by calling this method:

- (void)forwardInvocation:(NSInvocation *)anInvocation

If the object cannot forward the message, or refuses to deal with it, this method is called to
alert the runtime that the object simply refuses to receive the message:

- (void)doesNotRecognizeSelector:(SEL)aSelector

Given this process, you can override -forwardInvocation: so that it will handle
methods for which the class has no implementation. Thus, even though a class might not
handle a method, it can forward the message to another object. Perhaps the class has a pointer
to an object in an instance variable, and that object can indeed handle the message. The -
forwardInvocation: can be implemented to pass the message on to the object that can
handle it.

Handling -forwardInvocation: can be as simple as reinvoking the message using a

different receiver, or as complex as packaging up the message and sending it over a
network connection. The possibilities are endless. Because any object can tap into the
messaging resolution and sending process, Objective-C programmers should never make too
many assumptions about what message will be delivered, to whom, or when. All the default
behaviors can be changed simply by implementing -forwardInvocation:.

The -forwardInvocation: method can be used to simulate multiple implementation

inheritance. Forwarding is also used by Cocoa's built-in undo mechanism, and implemented
by the NSUndoManager class to capture messages and use them later during undo. The
NSUndoManager class is described in Chapter 8. Messages to one object can be re-sent to
multiple receivers, as implemented by the MiscTee class, available at www.misckit.org.

The -doesNotRecognizeSelector: method declared by NSObject is used

whenever an object needs to tell the runtime "I don't want to respond to that message." For
example, because NSObject defines the -copy method, almost all objects inherit an
implementation of -copy. Suppose you have a subclass of NSObject for which -copy
makes no sense. Perhaps the object encapsulates a system resource that cannot be copied. It
might be best if attempts to copy that object triggered an exception or runtime error. In a case
such as this, you would override the -copy method like this:

- (id)copy
{
[self doesNotRecognizeSelector:_cmd];
}

This is exactly what the default implementation of -forwardInvocation: does, unless

you override it.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Runtime Functions

The Apple Objective-C runtime provides many C functions for interacting with the
runtime. Most of the runtime functions are described in Appendix A. However, four
runtime functions are used commonly and deserve explanation here.

Class NSClassFromString(NSString *aClassName)

NSString *NSStringFromClass(Class aClass)
NSString *NSStringFromSelector(SEL aSelector)
SEL NSSelectorFromString(NSString *aSelectorName)

The first two methods convert from a string to a reference to the class named by the string
and back. Uses of NSClassFromString() include allowing a user to input the name of
a class to use. For example, an application could parse a text configuration file that
specifies which classes to use in the application.

The NSStringFromSelector() and NSSelectorFromString() functions

convert to and from strings containing message names and selectors.
NSSelectorFromString() can be used to convert user input into messages to
objects. Many scripting languages can be integrated with Cocoa just by converting the
commands in the scripting language into similarly named messages in Objective-C.
NSStringFromSelector() is useful when generating debugging or error output.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Objective-C++

Objective-C is a small set of extensions to ANSI C. Objective-C++ is the same set of

extensions applied to C++. Apple's Objective-C compiler is also an Objective-C++
compiler.

One of the advantages of Objective-C is that, as a super-set of ANSI C, it can be easily

mixed with the millions of lines of existing C code in the world. Objective-C++ can be
mixed with the millions of lines of C++ code that already exist. C++ features, such as name
mangling, are fully supported by Objective-C++ so that direct linkage between Objective-C
++ code and existing C++ code is possible.

Objective-C source code files are identified by the .m extension. Apple's compiler treats
files with the .M or .mm extensions as Objective-C++ source code. Additionally, the -x
compiler option can be used to instruct Apple's compiler to treat any input file as Objective-
C++ source code.

Apple's online documentation describes the features and limitations of Objective-C++ at

http://developer.apple.com/techpubs/, and in the release notes that come with Apple's
developer tools. In general, Objective-C classes and C++ classes can be intermixed so that
an Objective-C method can call a C++ member function and visa versa or a C++ class can
include a pointer to an Objective-C object as a member variable. Objective-C classes
cannot inherit from C++ classes or the other way around. The two class hierarchies must
remain distinct. The semantics regarding instance creation and deletion are dramatically
different between C++ and Objective-C. As a result, mixing them can be tricky, but the
benefit of reusing existing C++ code in new Objective-C projects outweighs the
complications that it introduces.
Book: Cocoa® Programming
Section: Chapter 4. Objective-C

Summary

Being able to cover the most important elements of the Objective-C language in a single
chapter is a tribute to the language's simplicity. More details about the Objective-C runtime
are presented in Appendix A. The appendix will help you harness the full power of
Objective-C's runtime, and advanced techniques. In the meantime, with the information
presented in this chapter and the next, you have all the language tools you need to start
Cocoa programming.

Libraries of reusable code are needed to really take advantage of any language. Objective-
C is a very rich language and the Cocoa frameworks comprise one of the most powerful
libraries of reusable objects ever created. Just as libraries are needed to take full advantage
of a language, conventions are often needed to take maximum advantage of the libraries.
The need for conventions is nothing new. The Microsoft Foundation Classes library used
with Microsoft Windows has its own conventions and rules for correct use. Many of the
traditional Mac libraries require conventions such as Pascal style strings and specialized
memory management. Chapter 5 introduces the conventions of the Cocoa frameworks that
are required to use Cocoa effectively.
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 5. Cocoa Conventions

IN THIS CHAPTER

● Naming
● Initializers
● Managing Memory
● Accessors
● Using Memory Zones
● Encoding and Decoding

Several conventions are used throughout the Cocoa frameworks. Awareness of the
conventions greatly enhances the readability of code and documentation that references the
frameworks. Conventions exist within most software environments. The conventions soon
become second nature to programmers. Because of consistency with which the conventions
are applied within the Cocoa frameworks, programmers can often guess the name of a class
or method without needing the documentation.

These conventions are not part of the Objective-C language. Some of the conventions, such
as variable naming, were originally arbitrary, but have become standard and expected after
many years of use. Many conventions, such as memory management of objects distributed
over a network, are pragmatic solutions to problems. The conventions exist to reinforce the
best programming practices. Adherence to the conventions can enhance the power and
reusability of your code. In some cases, use of the conventions is not optional. For
example, the memory-management conventions used by Cocoa unavoidably influence the
code that you write. No Cocoa application will work correctly unless it follows the
memory-management conventions.

This chapter describes the common Cocoa conventions and notes whether each convention
is optional or not.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Naming

Naming conventions are used within the Cocoa frameworks. These conventions are optional, but they are
a good standard to follow. The conventions indicate the intended scope and usage of the item being
named. Scope refers to the region of a program in which a name is known, and is usually enforced by the
compiler. Usage refers to the intended use of the named item. Even in cases where the compiler does not
enforce the usage limitations, the usage clues should be respected.

If you do not follow Cocoa's naming conventions, your code will look odd when intermixed with code
that uses Cocoa objects. Other programmers might be misled or confused about the meaning of your code.

Prefixes

Many symbol names in the Cocoa frameworks begin with the prefix NS. As long as other programmers
do not create names that start with NS, Apple is free to create new names that begin with NS without fear
of inadvertently using a name used by a third party and creating a conflict with existing code. Each
company or programmer should adopt a unique two- or three-letter prefix for names. For example, the
classes in the popular OmniFoundation Framework from Omni Development Corp. all begin with the
prefix OF.

Use the prefix for all names that have global scope, and for all private instance variables.

At the time of this writing there is no way to register a prefix or find out if someone else is already using
a prefix. Try to pick a prefix that is unlikely to be used by someone with whom you will need to share
code, including the vendors of libraries and frameworks that you want to use. The need for unique
prefixes is common in the C language, and languages derived from C, such as Objective-C. Java and C++
avoid the need for prefixes by providing a language construct called a Name Space. Future
implementations of Objective-C may also support name spaces.

Capitalization and Scope

Items that have global scope should start with a capital letter or an underscore followed by a capital
letter. Global scope means that the item named will be accessible anywhere in the program. In Objective-
C all class names have global scope; therefore all class names should begin with a capital letter. For
example, NSObject is a class name. In Objective-C, the following language constructs have global
scope; names of classes, names of protocols, names of categories, names of types, names of enumeration
constants, names of global variables, the names of C functions that are not declared static, and structure
and union tag names.

Items that do not have global scope should begin with a lowercase letter, or an underscore followed by a
lowercase letter. In Objective-C, method names do not have global scope. Methods only have meaning
within the context of a particular class. All method names should begin with a lowercase letter. For
example, +initialize and -replaceObject:atIndex: are two method names. In Objective-C,
the following language constructs do not have global scope: names of class/factory methods, names of
instance methods, names of instance variables, names of C functions that are declared static, names of
method and function arguments, names of local variables, and the names of individual structure and
union elements.

Underscores and Usage

A leading underscore character in a name conveys usage information. Any name that begins with an
underscore character refers to an item that should only be used by the programmers who maintain the
module in which the item is referenced. Names that begin with an underscore are part of private
application programming interfaces (APIs) and are subject to change without notice. In most cases, the
Objective-C compiler will not enforce usage rules. For example, _MYPrivateClass is the name of a
class that should not be used by programmers other than the maintainers. MY is the prefix, and like all
class names, the first letter of the first word in _MYPrivateClass is capitalized because class names
have global scope. The objective-C compiler will not prevent a programmer from creating an instance of
_MYPrivateClass, but it is still a bad idea to do so.

In Objective-C classes, private instance variables should begin with an underscore and a unique prefix.
The prefix is essential for private instance variables because Apple reserves the right to add or change
instance variables that begin with a single underscore character and no prefix. Using a prefix ensures that
your instance variable names will not conflict with the names of any private instance variables that Apple
uses. For example:

int _myPrivateVariable; // private instance variable with prefix

"my"

Names that do not begin with an underscore refer to items that are intended for use by all programmers.
For example, all programmers should use the NSString class.

Additional Capitalization

The second and subsequent words in each name should be capitalized. For example
NSCaseInsensitiveSearch is the name of an enumeration constant. Some method names contain
multiple name fragments separated by colon (:) characters. The first word in each fragment starts with a
lowercase letter. For example, in the method -makeObjectsPerformSelector:withObject:,
Objects, Perform, Selector, and Object are all capitalized. The word make is not capitalized because it is
the first word in the name of a method, and methods do not have global scope. The word with is not
capitalized because it is the first word in the second name fragment.

Nouns and Verbs

Class and object names should usually consist of nouns. For example: In class names, NSNumber,
NSArray, and NSWindow, as well as the words number, array, and window are all nouns.

Method and function names should usually start with a verb. For example, in the method names, -
makeObjectPerformSelector:, -compare:, +initialize, and -isSelected, the words
make, compare, initialize, and is are all verbs.

Class Names
Most class names should include the name of the immediate super class. For example, NSScrollView
is a subclass of NSView. There are a few exceptions to this convention. Most objects used with Cocoa
are assumed to inherit from NSObject, and therefore it is never necessary to include Object in a class
name. For example, the class NSDocument is not called NSDocumentObject even though it inherits
directly from NSObject. Most of the classes in Cocoa follow this convention, but because the
convention was adopted in the middle of the evolution of Cocoa, many of the oldest classes are not
named this way. According to this convention, NSControl should have been called NSControlView
and NSTextField should have been called NSTextFieldControl. Nevertheless, this is a wise
convention and programmers should adhere to it when creating new classes.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Initializers

Instance methods that initialize a newly allocated instance are called initializers and, by
convention, begin with the word init. The Objective-C compiler does not ensure correct
initialization of object instances, therefore initialization must be handled by convention.
The initialization convention is not optional for existing Cocoa classes or for most
subclasses of Cocoa classes. By convention, object instances are created in two steps. First,
memory for the new instance is reserved by calling the +alloc or +allocFromZone:
class methods provided by the NSObject class. Almost all classes in the Cocoa
frameworks inherit directly or indirectly from NSObject. After memory is reserved, the
memory is initialized by calling an initializer. A class can provide any number of
initializers.

In practice, this reliance on a mere convention for such an important aspect of using the
language and the frameworks is not a problem. Programmers quickly become accustomed
to the two-part creation of instances and the use of initializers. In fact, the most common
way to create an instance of a class is to combine the allocation and initialization in one
line as follows:

[[SomeClass alloc] init];

A class can provide any number of initializers. If there are multiple initializers, one should
be the designated initializer. The designated initializer for the NSObject class is -init.
The designated initializer for the NSView class is -initWithFrame:. Any initializer
method can be the designated initializer for a class, but it must be clearly identified in
documentation. When a class provides multiple initializers, the designated initializer is
usually the one with the most arguments and options. Any other initializers are
implemented to call the designated initializer with calculated or default arguments.

Documenting the designated initializer simplifies the creation of subclasses. Users of a

class can call any of the initializers provided by the class, including all the initializers
declared in that class's superclass. Without a documented designated initializer, the
programmer creating a subclass cannot know which initializer a user will call. If the
programmer creating a subclass does not know which initializer will be called then the new
subclass must be implemented to override all the inherited initializers. That is the only way
to be sure the instances of the new class will be correctly initialized. However, if there is a
designated initializer, the programmer can override just the designated initializer in the
subclass. The programmer can be confident that all other initializers are implemented to
call the designated initializer.

When writing an initializer, it is important to call the superclass's designated initializer.

Assuming that the superclass's designated initializer is -init, it should be called as
follows:

self = [super init];

The assignment of self to the result of the superclass's designated initializer is important.
In some rare cases, the inherited initializer can return a different instance from the one that
received the message. In that case, an error will result if the assignment to self is not
made.

When reading the Cocoa documentation provided by Apple, be sure to identify which
initializer is the designated initializer for each class. When subclassing a class in the Cocoa
frameworks, be sure to override the designated initializer if your subclass requires any
special initialization. If a new class provides multiple initializers, be sure to document
which initializer is the designated initializer, and make sure that the other initializers all
call the designated initializer.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Managing Memory

Large portions of the errors in computer programs are byproducts of dynamic memory
allocation. Dynamic-memory allocation enables a program to allocate as much memory as it
needs on a case-by-case basis. When an application dynamically allocates memory, the
operating system provides the requested memory as long as it is possible. The total memory
allocated can be as large as the computer's physical memory, virtual memory, and addressing
conventions will allow. The theoretical limit to the amount of memory that can be allocated by
one application on Mac OS X is approximately four Gigabytes.

The difficulty with dynamic-memory allocation is that the application and/or the operating
system have to keep track of memory that has been allocated, and remember to deallocate it
(free it). When dynamically allocated memory is no longer being used, and has not been
deallocated, the memory is called a memory leak. Memory leaks are wasteful and can cause
serious performance problems as the program runs. If a program continues leaking memory,
eventually it will drain the system of all its memory.

There are other ways of mishandling memory in addition to leaks. For example, in C, it is
possible to have a pointer overrun or underrun. When memory is dynamically allocated, the
program is given a pointer that tells it where the new memory is located. C allows a program to
access data at some offset from a pointer. If the offset is larger than the amount of memory
allocated, a pointer overrun occurs. The results are unpredictable and range from strange,
unexpected program behaviors to crashes. As expected, attempting to access data that is in
memory before the pointer (a negative offset) is a pointer underrun, and can have results
similar to an overrun.

Automatic Garbage Collection

Because problems with memory handling are common, and mistakes are easily made, many
programmers prefer to have the computer handle the memory automatically and flawlessly. As
might be suspected, this is not easily done. One solution that has become popular is automatic
garbage collection. Smalltalk, Java, and many other modern computer languages use automatic
garbage collection. The basic idea is that there is an invisible garbage collector that
periodically scans memory to see if it is still in use. If the garbage collector determines that the
memory is no longer being used it frees up the memory. The programmer doesn't need to do
anything special; automatic garbage collecting handles everything behind the scenes
automatically.

The Objective-C Cocoa libraries don't use automatic garbage collection. By convention, Cocoa
uses a form of garbage collection known as reference counting. The disadvantage to this is the
programmer has to do a little bit of work to properly use reference counting; it isn't automatic.
An advantage is reference-counting techniques can be more efficient than automatic garbage
collection, and give the programmer more control. Additionally, Cocoa's Distributed Objects
would not work well with automatic garbage collection, yet reference-counting works very
well with remote distributed objects. Several other considerations are involved in deciding
which type of garbage collecting to use, but they aren't germane to understanding how to use
Cocoa's reference-counting technique. Correct use of the Cocoa memory-management
conventions is essential.

Reference Counting

Reference counting is a simple idea. Every object has a reference count that indicates how
many other objects are currently keeping a reference to it. When object A wants to reference
object B, A increases B's reference count by one. When object A is done referencing object B, A
decreases B's reference count by one. When no objects reference object B, its reference count
will reach zero and B will be deallocated, thus freeing up memory for some other use. The
process of deallocating B might decrease reference counts on objects used by B, perhaps
causing them to be deallocated, too.

With Cocoa, newly allocated objects have a reference count of one. When a class is sent a
+alloc or +allocWithZone: message, memory for a new instance is reserved and the
new instance implicitly has a reference count of one. If this new instance is referenced by
another object, then the reference count should be incremented. This is done by sending the -
retain message:

[object retain];

Every -retain message causes the receiver's reference count to be increased by one. When
code obtains a reference to an object through some means other than allocation and the code
needs to keep a reference to the object, then the object should be sent a -retain message. If
the code neglects to retain the object, it is likely that the object will be deallocated sometime in
the future and it will be invalid when the code references it causing an error.

Now, when code is done using an object, the code should tell it by sending a -release
message:

[object release];

The -release message decreases the object's reference count by one. If decreasing the
reference count causes the count to reach zero, the object is immediately deallocated. It is a
good idea at this point to reassign the reference to the object. A good strategy is to assign nil
to the reference:

object = nil;

It is not a good idea to keep references to objects that might have been deallocated after being
released. By assigning nil you are making sure that code doesn't erroneously attempt to send
a message to an invalid object.

Your program can determine the reference count of an object at any time by sending the -
retainCount message. -retainCount returns an integer count of the number of times
the receiver has been retained including the initial value of one set when the object was
allocated. There is seldom a need to call -retainCount in a working program. When using
an object, the programmer should not care how many other ways the object is used. However,
knowing the retain count of an object can be an invaluable debugging aid in some
circumstances.

At this point, it should make sense that the number of release messages sent to an object over
its lifetime should be equal to the number of -retain messages sent to the same object plus
one. The extra one is for the initial +alloc or +allocWithZone: message that created the
object in the first place. Also keep in mind that the -copy, -mutableCopy, -
copyWithZone: and -mutableCopyWithZone: messages are like a +alloc message,
so they need a matching -release.

This might seem complex, but it really isn't. You simply send one -release to match up
with each +alloc, +allocWithZone, -copy, -mutableCopy, -copyWithZone:, -
mutableCopyWithZone:, or -retain that you have sent.

Unfortunately, reference counting doesn't remain that simple. For example, suppose that we are
writing a method that is expected to return a reference to an object. The following example
shows one incorrect implementation:

-(NSObject *)incorrectMethod1
{
NSObject *result = [[NSObject alloc] init];
return result;
}

The method, -incorrectMethod1, allocates a new instance of the NSObject class. The
new instance has a retain count of one. The new instance is then returned. There is a serious
problem with this method. First, the convention that we must send a -release message to
balance the +alloc message has not been followed. The code that calls -
incorrectMethod1 can ignore the object returned, at which point memory has been
leaked. After return, the -incorrectMethod1 method no longer references the object. If
the calling code ignores the value returned, there will not be any remaining reference to the
object and no way to ever release it. The caller will not release the returned object because the
caller did not explicitly call one of the alloc or copy methods that must be balanced with a
release.

Another incorrect implementation calls -release inappropriately, as shown in the following

code:
-(NSObject *)incorrectMethod2
{
NSObject *result = [[NSObject alloc] init];

[result release];

return result;
}

The method, -incorrectMethod2, adheres to the convention of sending a -release to

balance the +alloc. Unfortunately, after sending the -release message, result can be
deallocated. If the calling code relies on the reference returned, it might crash. The calling code
is being given a reference to an invalid (deallocated) object.

How can an object reference be returned from a method without resulting in a memory leak,
and without returning a potentially invalid reference?

The answer is very clever. Cocoa applications contain an auxiliary object called a release pool,
which is a temporary holding place for objects during the short time in limbo between the end
of one method and the point in the caller's code where the object is retained (if it is retained).
When an object is added to a release pool, it is registered to receive a -release message at a
later time. After an object has been added to a release pool, the object can be returned from the
method without creating a leak or returning an invalid object. If the caller wants to keep a
reference to the object, the caller will send a -retain message. At some later point, the
release pool will be deallocated, and at that time it will release all the objects it contains. If the
reference counts any of the objects in the release pool reach zero, those objects are then
deallocated.

Figure 5.1 shows how an object can be allocated in a method and safely returned by adding the
object to a release pool. Two timelines are shown. In Timeline 1, the caller retains the object
returned from a method and the object is not deallocated when the release pool is deallocated.
Because the caller retained the object, the caller must eventually release the object or else it
will be a memory leak. In Timeline 2, the caller does not retain the returned object. As a result,
when the release pool is deallocated, the object will also be deallocated. Because the caller did
not retain the object, the caller does not ever need to release it.

Figure 5.1. This Timeline illustrates the sequence in which an object is allocated,
autoreleased, returned from a method, optionally retained by a caller, and released by a
release pool.
The property of delaying a release message to a returned object until after the calling code has
had a chance to retain the object allows for objects returned from a method to correctly handle
reference counting.

In Cocoa, the NSAutoreleasePool class implements release pools. All the details of
adding objects to a release pool are handled by a single method, -autorelease, declared in
the NSObject class. To place an object in a release pool and thereby schedule the object's
release at a later time, simply call -autorelease as follows:

[object autorelease];

The following code illustrates one correct way of returning an object from a method:

-(NSObject *)correctMethod
{
NSObject *result = [[NSObject alloc] init];

[result autorelease];

return result;
}

In the correct implementation, an object is allocated, initialized, and a reference to it is

assigned to result. The object referenced by result has a reference count of one. When
result is autoreleased, it is added to a release pool. After result is autoreleased, it still has
a reference count of one and has not yet been deallocated.

If the code that calls -correctMethod does not retain the returned object, then the object's
reference count will reach zero and the object will be deallocated when the release pool is
eventually deallocated. If the calling code does retain the returned object, then object's
reference count will temporarily be two. When the release pool is finally deallocated, the
object's reference count will drop to one and the object will not be deallocated. The reference
kept by the calling code remains valid.

The complete rules for using -release and -autorelease follow: Send one -release
or -autorelease message to match up with each +alloc, +allocWithZone, -copy,
-mutableCopy, -copyWithZone:, -mutableCopyWithZone:, or -retain
message that you have sent.

A question might arise at this point. Who creates the release pool and how often does it get
deallocated? It turns out that in Cocoa applications that use the Application Kit framework, a
release pool is created automatically at the start of the internal event loop, and is cleared out at
the end. Of course, you can always create your own pool and dispose of it as described in the
NSAutoreleasePool class documentation. This can be done in special circumstances to
enhance performance and reduce a program's memory requirements. If you are writing a
command-line program that doesn't use the Application Kit framework, then you will have to
create your own pool. It is really easy to do. The following line creates a pool:

NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

That's all you need to do; the -autorelease method will find it automatically. At the end of
your run loop or when you want to clean out the pool simply release the pool:

[pool release];

One thing to be careful of is expecting an autoreleased object to be valid for too long.
Normally, an autoreleased object will remain valid within the current scope (that is, current
method) and can safely be returned from a method. It is wise, however, to send a -retain
message as soon as you know you want to keep a reference to an object that was not obtained
by calling one of the +alloc, +allocWithZone, -copy, -mutableCopy, -
copyWithZone:, -mutableCopyWithZone: messages. Of course, if you don't need to
keep a reference to an object don't send -retain, and it will go away automatically when the
release pool is deallocated.

The -release method is much more efficient than -autorelease. Therefore, unless you
need the special functionality of -autorelease, use -release. Applications that overuse
-autorelease tend to run very slowly.

NOTE
 Follow these guidelines religiously to avoid memory leaks and attempts to access
deallocated objects:

● If you allocated, copied, or retained an object you are responsible for

releasing the object with either -release or -autorelease when
you no longer need it. If you did not allocate, copy, or retain an object you
should not release it.
● When you receive an object by some means other than an alloc or copy
method, the object will normally remain valid until the end of your
method and it can be safely returned as a result of your method. You must
either retain or copy the object if you need it to live longer than this (for
example, if you plan to store it in an instance variable).
● Use -autorelease rather than -release when you want to return
an object that you will no longer reference. Use -release rather than -
autorelease wherever you can for performance reasons.

The online documentation that comes with the Cocoa development tools includes
an excellent and detailed explanation of the NSAutoreleasePool class, as
well as an analysis of the implications of nested release pools.

Retain Cycles

There is one final problem the preceding rules do not address: retain cycles. A retain cycle is a
special kind of memory leak that can occur with a reference counting scheme. The problem
occurs when two or more objects reference each other. For example, if object A is retaining
object B and object B is retaining object A, the two objects never reach a zero-reference count
because each references the other. If neither A nor B is referenced anywhere else in the
program, then the memory used by A and B constitutes a memory leak. It is possible to have
very complex retain cycles where the minimum reference count is higher than one (multiple
objects depending upon each other), and also cases where a long chain of objects retain each
other in what looks like a circular linked list.

The best solution to the retain-cycle problem is to avoid it. Be careful with your designs.

Tracking Memory Problems

By now it is obvious that reference counting, although a simple solution, also has its quirks and
difficulties. Careful thought while designing objects can solve the difficulties, but even so, we
all make mistakes. The Mac OS X development environment provides several tools to help you
track down memory problems. Here is a brief synopsis to get you started:

● gdb- The debugger for the Cocoa environment that enables you to look at stack frames
 and variable values and trace execution of your program

● ObjectAlloc.app- An application that enables you to watch a graph showing the

number of objects in a running application dynamically

● MallocDebug.app- Measures an application's use of dynamic memory

● Sampler.app- Displays the amount of time your application spends in each function
and method

Understanding reference counting is fundamental to Objective-C Cocoa development. No

Cocoa program is running correctly until it is following the reference counting rules.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Accessors

Accessors are methods used to query or change the internal state of an object. The internal state of objects
is usually stored in instance variables. There is commonly a one-to-one correspondence between instance
variables and accessor methods. The convention of using accessors is an extremely good practice that is
ubiquitous in the Cocoa frameworks, but is optional.

The following simple class declaration shows how accessors are used.

@interface MYClass : NSObject

{
NSRect _myRect;
}

- (void)setRect:(NSRect)aRect;
- (NSRect)rect;
- (void)getRect:(NSRect *)aRectPtr;

@end

NSRect is a C structure defined in NSGeometry.h. The -setRect: method passed the aRect
argument by value even though NSRect is a structure. Similarly, the -rect method returns an NSRect
value. By convention, accessor methods accept nonobject arguments by value, and return nonobject values
even when the values have complex types like the NSRect structure.

An accessor method that sets a value begins with the word set, as in -setRect:. An accessor that returns
a value is named after the value like -rect.

In some cases, an accessor method that returns a value by reference is provided. Accessors that return
values by reference begin with the word get, as in -getRect: in this example. This type of accessor is
very rare, and they are easy to spot because they begin with get. One example is the method -(void)
getBytes:(void *)buffer in the NSData class, which returns bytes by reference in the buffer
argument.

In this example of accessors for nonobject values, the accessors can be implemented as follows:

@implementation MYClass
/* Simple class to encapsulate _myRect */

- (void)setRect:(NSRect)aRect
/* Set _myRect */
{
_myRect = aRect;
}

- (NSRect)rect
/* Return _myRect by value */
{
return _myRect;
}

- (void)getRect:(NSRect *)aRectPtr
/* Return the value of _myRect by reference in the memory at aRectPtr
*/
{
if(NULL != aRectPtr) {
*aRectPtr = _myRect;
}
}

@end

Consistent use of accessors in your own classes might seem like a chore, but it will simplify and promote
reuse of your classes. Accessors are even more important when the values being accessed are objects.

Accessing Objects

The following code demonstrates a standard way to implement accessors for object-instance variables. The
code provided here can be used as a template every time you write object accessors. Using this example
and following the memory management conventions will prevent memory errors. Consistent use of object
accessor methods can help localize the reference counting within your code.

@interface MYClassWithObjectAccessors : NSObject

{
NSObject *_myObject;
}
- (void)setObject:(NSObject *)anObject;
- (NSObject *)object;

@end

@implementation MYClassWithObjectAccessors
/* Simple class to encapsulate _myObject */

- (void)setObject:(NSObject *)anObject
/* Set _myObject the safe way */
{
[anObject retain];
[_myObject release];
_myObject = anObject;
}

- (NSObject *)object
/* Return _myObject */
{
return _myObject;
}
- (void)dealloc
/* Clean-up */
{
[self setObject:nil];
[super dealloc];
}

@end

Almost all memory management can be handled within the accessors. The -setObject: method sets
the _myObject instance variable. Because the _myObject reference must remain valid indefinitely, the
object to be referenced must be retained or copied. The objects referenced by instance variables should be
retained or copied to make sure they are not deallocated while the instance is still using them. The object
previously referenced by the _myObject instance variable will no longer be referenced after the
assignment, so the obsolete object must be released. Finally, the assignment is made.

The order in which the new value is retained and the old value is released is very important. The new value
must be retained before the old value is released. This order of operations assures correct behavior in all
the circumstances in which the accessor might be used.

An accessor that sets an object value can be called in three general circumstances:

It can be called with a nil argument;

It can be called with an argument that is different from the receiver's existing value, or

It can be called with an argument that is identical to the receiver's existing value.

In any of the circumstances, the existing value could be nil.

When it's called with a nil argument, the nil argument is harmlessly retained. It is safe to send any
message to nil as long as you do not count on any return value. The object that will no longer be
referenced by the _myObject instance variable is released, and _myObject is set to nil. The instance
variable ends up being set to nil as requested.

When it's called with an argument that's different from the receiver's existing value the new value is
retained, the old value is released, and the instance variable references the new value as requested.

When its called with an argument that is identical to the receiver's existing value, the order of operations
that is used is required. First, the argument, anObject, is retained causing its reference count to rise to at
least two. Remember that anObject is the same as _myObject and has a retain count of at least one
because _myObject was retained when it was initially set. Then _myObject is released causing its
retain count to drop to no less than one. Finally, the argument is assigned to _myObject, which is a
harmless operation because _myObject and anObject are the same. _myObject is left with the same
retain count and value that it had before -setMyObject: was called. If retain and release are reversed,
_myObject will be released and possibly deallocated. Therefore, the attempt to retain anObject will
fail because anObject is the same as _myObject and has already been deallocated.
Finally, accessors can be used to confine the reference counting memory management of instance variables
to just one method, the set accessor. A good strategy is to make sure that the only method that sends -
retain and -release messages to instance variables is the set accessor. Instance variables are
commonly released in a class's -dealloc method, but even that can be accomplished indirectly using set
accessors. The following is an example of a dealloc method implementation that releases an object
instance variable by calling an accessor with a nil argument:

- (void)dealloc
{
[self setName:nil]; // accessor will release instance
// variable and set it to nil
[super dealloc];
}
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Using Memory Zones

Memory zones are a technique that can be used to improve application performance. Memory zones
optimize the location of memory for objects that are used together. The use of memory zones is the final
wrinkle to Cocoa memory management.

Each application for Mac OS X has a very large amount of addressable memory. Each time an application
requests more memory, the operating system provides memory even if all available RAM in the computer is
already in use. To accommodate the application's request for memory, the operating system copies the
contents of some RAM to the computer's hard disk. The operating system then makes the copied RAM
available to the requesting application to reuse. When the memory that was copied to disk is needed again,
the operating system chooses a different block of memory to copy to the disk, and brings the old memory
back into RAM. The capability for applications to use more memory than the available RAM is called
virtual memory. The process of copying the contents of memory to and from the hard disk is called paging
or swapping. Accessing the hard disk and copying memory is time consuming. Too much swapping
degrades system performance and is called thrashing.

In an application that allocates memory for many objects over time, the various objects might be far apart in
memory. If two or more objects are used together, but stored far apart in memory, an inefficient situation
can arise. When the memory for one object is needed, that memory is swapped into RAM from the hard
disk. The object then needs to access another object that is still not in RAM, and even more memory must
be swapped into RAM. In the worst case, the memory swapped in for the second object might force the
memory for the first out of RAM. All the swapping dramatically slows the application.

One solution to this problem is to request locality of storage. In other words, store objects that are used
together close in memory. When one of the objects is needed, the chances are good that all the needed
objects will be swapped into memory at the same time. When the objects are not needed, they are swapped
out together as well.

Cocoa provides a mechanism for requesting that objects are stored close together in memory. Cocoa
provides functions for creating memory zones and allocating memory from specific zones. All the objects
allocated from a specific zone will be close to the other objects in the same zone. Memory zones are
represented by the NSZone type. NSZone and the functions for managing them are described briefly here.
More details are available in the online Cocoa reference documentation. Zones are a very low level and
somewhat esoteric topic. It is worthwhile to know that zones exist and can be used, but the Cocoa classes
hide most of the details and make them work seamlessly without programmer intervention. The use of
memory zones should be one of the last concerns of a Cocoa application developer. Get your code working
and only then consider the use of zones as an optimization if and only if they are needed.

The function to create a memory zone is NSCreateZone(). To recycle a zone and make its memory
available to other applications, use the NSRecycleZone() function. Arbitrary memory can be allocated
from a zone with the NSZoneMalloc(), NSZoneCalloc(), or NSZoneRealloc() functions. These
functions work like the traditional Unix memory-management functions, malloc(), calloc(), and
realloc() to allocate uninitialized memory, allocate memory initialized to all zeros, and change the
amount of the memory allocated respectively. Memory allocated with the NSZoneMalloc(),
NSZoneCalloc(), or NSZoneRealloc() functions can be freed with NSZoneFree(), which is
similar to the standard Unix free() function.
Cocoa objects are always allocated in a zone. The +alloc class method defined in NSObject actually
calls the +allocWithZone: class method specifying a default zone. The default zone can be obtained by
calling the NSDefaultMallocZone() function. Programmers can specify that an object instance should
be allocated from a particular zone by using +allocWithZone: and providing the zone as an argument.
A zone can also be specified when an object is copied. The -copy method declared in the NSCopying
protocol is usually implemented to call -copyWithZone:.

You can determine the zone in which an object was allocated by sending the object a -zone message. If
you decide to use zones explicitly in you application, it is a good idea to make sure objects that allocate
other objects do so using the same zone. For example, the -init method of a custom class might allocate
an instance of another class for use as the value of an instance variable, as shown here:

- (id)init
{
self = [super init];
_myInstanceVariable = [[MYHelperClass allocWithZone:[self zone]]
init];

return self;
}

_myInstanceVariable will be an instance of MYHelperClass that is allocated from the same

memory zone as the object being initialized.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Encoding and Decoding

The Cocoa frameworks provide a convention for initializing an object instance by decoding data that
has previously been encoded. Encoding and decoding object-instance data is the basis for storing
objects on disk, and copying objects to different address spaces. Each class is responsible for encoding
and decoding its own state by implementing two methods, -encodeWithCoder: and -
initWithCoder:, which are declared in the NSCoding protocol. These methods are automatically
called, under certain circumstances, by Cocoa framework classes such as NSCoder, NSArchiver,
and NSUnarchiver. Almost all classes in the Cocoa frameworks conform to the NSCoding protocol
and implement the two coding methods.

A file or block of memory that contains encoded objects is sometimes called an archive. The
NSArchiver and NSUnarchiver classes are used to write and read archives, and they manage
most of the details of the encoding and decoding process. For example, an object that is encoded more
than once will only be stored once in an archive. When the objects in the archive are decoded, all the
objects that referenced a shared object will be restored to reference a shared object that was decoded.
Complex graphs of interconnected objects can be encoded and decoded, preserving all the
interconnections. Encoded data is stored in a compact platform independent format.

Making your own classes conform to the NSCoding protocol is optional. In most cases, if your class
inherits from a class in the Cocoa frameworks, your class will inherit the coding methods. You can
override the inherited methods to call the inherited implementations, and then encode or decode the
unique state of instances of your class.

The NSObject class does not conform to the NSCoding protocol. To add encoding and decoding
support to a class that does not inherit NSCoding conformance, the class must adopt the NSCoding
protocol and implement the -encodeWithCoder: and -initWithCoder: methods.

NOTE

Encoding and decoding are both used by Interface Builder. Interface Builder .nib files
contain encoded objects. Instances loaded from nib files are sent the -
initWithCoder: method so that they can reconstruct themselves from the encoded
data. To use custom classes with Interface Builder, they must implement the NSCoding
protocol.

Encoding Types

The methods -encodeWithCoder: and -initWithCoder: are called with an NSCoder

argument. When an object receives an -encodeWithCoder: message, the object should encode its
state using the methods of the NSCoder instance provided. Almost all types that can be represented by
the @encode Objective-C compiler directive can be encoded. Objects, scalars, C arrays, C structures,
C strings, and pointers to these types can all be encoded and decoded. C unions, void pointers, and
function pointers cannot be encoded or decoded.

For example, consider the following class that stores a mixture of objects and other data types using
instance variables:

@interface MYGrapnic : NSObject <NSCoding>

{
NSString *_myLabel;
NSFont *_myLabelFont;
NSPoint _myLabelPosition;
id _myExtraData;
float _myLineWidth;
NSMutableArray *_myStyles;
NSColor *_myColor;
}

/* NSCoding methods */
- (void)encodeWithCoder:(NSCoder *)coder;
- (id)initWithCoder:(NSCoder *)coder;

@end

The MYGraphic class is a subclass of NSObject, which does not conform to the NSCoding
protocol. Therefore, the MYGraphic class must adopt the NSCoding protocol explicitly to enable
encoding and decoding. The -encodeWithCoder: method for the MYGraphic class might
implement its -encodeWithCoder: method like this:

- (void)encodeWithCoder:(NSCoder *)coder
{
[coder encodeObject:_myLabel];
[coder encodeObject:_myLabelFont];
[coder encodeValueOfObjCType:@encode(NSPoint) at:
&_myLabelPosition];
[coder encodeObject:_myExtraData];
[coder encodeValueOfObjCType:@encode(float) at:&_myLineWidth];
[coder encodeObject:_myStyles];
[coder encodeObject:_myColor];
}

The MYGraphic class encodes all its instance variables, but classes that do not encode all their
instance variables are possible also. There is no reason to encode the values of instance variables that
can be computed from other data. There is no reason to encode the values of instance variables that are
not important when the object is decoded.

Data that is encoded must be decoded in the same order using the same types with which it was
encoded. Given the preceding implementation of -encodeWithCoder:, the corresponding -
initWithCoder: method must be implemented as follows:

- (id)initWithCoder:(NSCoder *)coder
{
self = [super init];
_myLabel = [[coder decodeObject] reatin];
_myLabelFont = [[coder decodeObject] reatin];
[coder decodeValueOfObjCType:@encode(NSPoint) at:
&_myLabelPosition];
_myExtraData = [[coder decodeObject] reatin];
[coder decodeValueOfObjCType:@encode(float) at:&_myLineWidth];
_myStyles = [[coder decodeObject] reatin];
_myColor = [[coder decodeObject] reatin];

return self;
}

There are two key requirements for the implementation of -initWithCoder:. It must return self,
and it must decode the same types in the same order that they were encoded. If - initWithCoder:
is implemented in a class that does not inherit NSCoding conformance from its superclass, -
initWithCoder: should then be implemented to call the superclass's designated initializer and
assign the result to the self variable.

A class that overrides inherited -encodeWithCoder: and -initWithCoder: methods must call
the inherited versions. The following class shows one correct technique for overriding the coding
methods. The MYCircleGraphic class is a subclass of the MYGraphic class and is declared as
follows:

@interface MYCircleGraphic : MYGraphic

{
NSPoint _myCenter;
int _myRadius;
}

/* NSCoding methods */
- (void)encodeWithCoder:(NSCoder *)coder;
- (id)initWithCoder:(NSCoder *)coder;

@end

There is no need for the MYCircleGraphic class declaration to explicitly adopt the NSCoding
protocol because MYCircleGraphic inherits conformance from the MYGraphic class. The
MYCircleGraphic class might implement its -encodeWithCoder: and -initWithCoder:
methods like this:

@implementation MYCircleGraphic

/* NSCoding methods */
- (void)encodeWithCoder:(NSCoder *)coder
{
[super encodeWithCoder:coder];
[coder encodeValueOfObjCType:@encode(NSPoint) at:&_myCenter];
 [coder encodeValueOfObjCType:@encode(int) at:&_myRadius];
}

- (id)initWithCoder:(NSCoder *)coder
{
self = [super initWithCoder:coder];
[coder decodeValueOfObjCType:@encode(NSPoint) at:&_myCenter];
[coder decodeValueOfObjCType:@encode(int) at:&_myRadius];

return self;
}

@end

The key to these implementations is that they call their superclass, so that it has a chance to encode or
decode its state. After the superclass's state is handled, the variables added by the subclass are encoded
or decoded. Another detail is the assignment of self to the result of the superclass's -
initWithCoder: method. In some rare cases, the inherited -initWithCoder: might substitute a
different instance from the one that received the message. In that case an error will result if the
assignment to self is not made.

Retaining Decoded Objects

Decoding objects follows the Cocoa reference counting conventions. If you obtain an object via
decoding and you want to keep a reference to the decoded object, then you must retain it. Decoded
objects that are not retained will be deallocated when the coder that provided them is deallocated.
Objects can be decoded and retained in one line as follows:

_myName = [[coder decodeObject] retain];

If a class provides set accessors for its object instance variables, the set accessors can be used in
conjunction with decoding as follows:

[self setName:[coder decodeObject]];

Using the accessors when they exist has advantages. Any logic applied to values when they are set can
be implemented in one place, the accessor, rather than in two places, the accessor and also the -
initWithCoder: method. Logic implemented by a set accessor can be arbitrarily complex, but at a
minimum the set accessor will manage the reference count of the decoded instance variable, thus
confining all reference counting of instance variables to just the accessors.

Conditional Encoding

The NSCoder class includes a method, -encodeConditionalObject:, to enable conditional

encoding of objects. Conditional encoding means that a placeholder for the object being encoded is
encoded instead of the object itself. When both classes are decoded they will be restored with a
reference to the same object if the object conditionally encoded in one class is unconditionally encoded
by another. If no class unconditionally encodes the object, then when the classes that conditionally
encoded the object are decoded, they will decode a reference to nil.

Use conditional encoding to avoid encoding too many objects under certain circumstances. For
example, if your application includes many interconnected objects in a complex data structure,
conditional encoding can be used to enable the encoding and decoding of individual objects without
inadvertently encoding all the interconnected objects. Figure 5.2 illustrates a possible configuration of
interconnected objects using solid arrows to indicate which objects unconditionally encode references
to other objects.

Figure 5.2. Interconnected objects can unconditionally encode referenced objects.

It is not possible to encode just one of the interconnected objects depicted in Figure 5.2 because each
will encode all the others. Figure 5.3 shows an alternate configuration that uses conditional encoding
and makes it possible to encode the entire graph of interconnected objects or encode individual objects.
In Figure 5.3, solid arrows are used to indicate unconditionally encoded references and dashed arrows
are used to indicate conditionally encoded references.

Figure 5.3. Interconnected objects can use both conditional and unconditional encoding.

If object A in Figure 5.3 is encoded, objects B and C, and all their interconnections, will also be
encoded. When A is decoded, the entire graph of objects is restored. If either object B or object C is
encoded by itself, just one object will be encoded. Due to the use of conditional encoding, when that
object is restored, its references to other objects will be nil.

Using Version Numbers

The values that are encoded in -encodeWithCoder: must be decoded within -initWithCoder
using the same order and the same types. What happens if a class is modified to store additional values
or use different types? How can the modified class decode values that were encoded by prior versions
of the class?

The Cocoa frameworks include a class versioning system that can be used to enable backward
compatibility when decoding values. The version number of a class can be set with the
+setVersion: method declared in the NSObject class. A good time to set the version of a class is
in its +initialize method as follows:

@implementation MYClass
+ (void)initialize
{
[MYClass setVersion:3];
}
@end

The +setVersion: message should be sent to the class itself using the class name rather than self
because an inherited +initialize might be called by a subclass in which case self will be the
subclass. You should not set the version of the subclass inadvertently.

The version number of a class can be obtained by sending the +version message to the class.

When decoding objects, you can obtain the version number of the object when it was encoded by
calling the -versionForClassName: method of the coder. Based on the version of the class that
was encoded, different decoding sequences can be used. For example, if the MYCircleGraphic
class, which was previously introduced, is modified to store its radius as a float rather than an
integer, backward compatibility can be maintained, as shown here:

@interface MYCircleGraphic : MYGraphic

{
NSPoint _myCenter;
float _myRadius; // Changed to float
}

+ (void)initialize;
/* NSCoding methods */
- (void)encodeWithCoder:(NSCoder *)coder;
- (id)initWithCoder:(NSCoder *)coder;

@end

@implementation MYCircleGraphic

+ (void)initialize
{
[MYCircleGraphic setVersion:1]; // Default is version 0
}

/* NSCoding methods */
- (void)encodeWithCoder:(NSCoder *)coder
{
[super encodeWithCoder:coder];
[coder encodeValueOfObjCType:@encode(NSPoint) at:&_myCenter];
[coder encodeValueOfObjCType:@encode(float) at:&_myRadius];
}

- (id)initWithCoder:(NSCoder *)coder
{
self = [super initWithCoder:coder];
[coder decodeValueOfObjCType:@encode(NSPoint) at:&_myCenter];
if([coder versionForClassName:@"MYCircleGraphic"] < 1) {
// Versions prior to 1 saved an integer radius
int temp;

[coder decodeValueOfObjCType:@encode(int) at:&temp];

_myRadius = (float)temp;
} else {
[coder decodeValueOfObjCType:@encode(float) at:&_myRadius];
}

return self;
}

@end

Using Memory Zones When Decoding

By default, objects that are decoded are created in the default memory zone. In most cases, the default
behavior is fine. If you need to decode objects using a different memory zone, set the zone to use via
the coder's -setObjectZone: method before any objects are decoded. You can obtain the memory
zone that a coder is using by sending the -objectZone message.

Substituting Objects

During encoding, the object being encoded can substitute a replacement class or instance for itself.
Similarly, after an object is decoded, it can substitute another object for itself. The NSCoder class and
its subclasses, NSArchiver and NSUnarchiver, call certain methods that are declared in the
NSObject class to enable substitutions.

The -classForCoder method is called as an object is encoded. Override -classForCoder to

return a different class that should be stored in the encoded data.

Next, the -replacementObjectForCoder: method of the object being encoded is called.

Override -replacementObjectForCoder: to substitute a different instance for the instance
being encoded.
After an object has been decoded, the -awakeAfterUsingCoder: method is called. Override -
awakeAfterUsingCoder: to return a different instance than the one just decoded.

Using Alternative Techniques

The encoding support provided by the NSCoder class and its subclasses is powerful and flexible, but it
has some shortcomings.

The binary data format of encoded values is compact and cross platform, but not documented by Apple.
The encoded data cannot be decoded easily without using the Cocoa frameworks. As a result, using
encoded values to store the document data of your custom applications is not a good choice. Users on
other platforms will not be able to read your documents, even to import them into applications. Other
Cocoa applications will not be able to read the document data unless the other applications include all
the classes that can be encoded.

Although class versioning can be used to maintain backward compatibility when reading objects that
were encoded by prior versions of the class, there is no way to reliably support forward compatibility.
In other words, version 2 of a class can decode version 1, but version 1 cannot decode version 2.

Finally, because encoded values are stored in a cryptic binary format, there is no easy way to
troubleshoot problems with encoded data. If an error was made encoding values, it might be impossible
to ever decode the values.

Fortunately, freely available alternative coding techniques exist. One alternative is property-list
encoding, which is available at www.misckit.com. Each object is encoded in a human-readable format.
Both backward and forward compatibility is possible. Conditional encoding, substitutions, versioning,
and memory zones are all supported. Objects that are encoded multiple times are only stored once in the
encoded data. Property lists can be stored as XML data.

The disadvantage of property list encoding is that the encoded data can be large and slower to encode
and decode than Apples binary implementation. Also, if your class supports both NSCoder encoding
and property list encoding, you will have to implement the NSCoding methods as well as the property
coding methods. Interface Builder and Cocoa's distributed objects technology only use the binary
format.
Book: Cocoa® Programming
Section: Chapter 5. Cocoa Conventions

Summary

Although this chapter describes the major conventions used throughout the Cocoa
frameworks, there are many other conventions and examples of good practices to be found
in the frameworks. An awareness of the conventions clarifies the frameworks. When the
conventions are observed in use consistently, they become familiar and even comforting. In
some cases, awareness of the conventions is essential for correct use of the frameworks.

A trend toward accentuation and documentation of conventions, best practices, and

programming wisdom has swept the software industry. Best practices are sometimes called
design patterns. Many of the design patterns used by the Cocoa frameworks are described
in the next chapter.
Book: Cocoa® Programming
Section: Part I: Overview

Chapter 6. Cocoa Design Patterns

IN THIS CHAPTER

● Understanding Design Patterns

● A Catalog of Cocoa Design Patterns

Design patterns are a popular way to describe an object-oriented design. A pattern usually
doesn't include actual code. Instead, it describes general program elements (objects), and
how they can interact to solve a particular type of problem. The key elements of a design
pattern are the pattern's name, the problem it solves, the solution it presents, and the
consequences of using the pattern.

Many class names and concepts are introduced in this chapter that might not yet be
familiar. This chapter does not explain the use of any classes in detail, or even fully explain
the design patterns; instead it provides an overview and terminology. The classes that are
mentioned briefly in this chapter are described in detail throughout this book. One goal of
this chapter is to enable effective use of additional references by correlating standard
industry terminology with Cocoa's terminology. At a minimum, this chapter provides the
definition of terms and patterns that recur throughout the Cocoa frameworks, and this book.
Book: Cocoa® Programming
Section: Chapter 6. Cocoa Design Patterns

Understanding Design Patterns

In general, patterns offer a vocabulary of design solutions to software developers. Systems

that use well-known patterns in their design are easier to comprehend. Having a collection
of named patterns handy serves as a toolbox for developers. You can use these tools
instead of being forced to create a new set of tools for every design you create.

A pattern's name offers a common vocabulary that can be used between developers. The
details of the pattern, and all that it implies, can be communicated rapidly using the name.
Cocoa has its own special set of terms to represent the key concepts around which it is
built. Being familiar with these terms will make it easier to understand and use Cocoa, as
well as make it easier to describe designs to other developers.

Each pattern might apply to a range of situations, which can represent several different
design problems. Part of understanding a particular pattern is to know when to use it and
when not to. Because that is largely a matter of experience, documenting the problems a
pattern is meant to solve enables that experience to be shared with other developers.

The core of a pattern is the solution it offers. This includes the various program elements
(usually objects) that participate in the pattern. How elements collaborate, and the
responsibilities of each element, are also a part of the solution. Patterns don't include actual
code, except perhaps as an example of how a pattern might be applied. Instead, they offer a
generic template that can be modified to best match a particular problem. When a
developer thoroughly understands a pattern she can usually implement it quickly and
efficiently, even though she might not have specific code to cut and paste.

Most pattern definitions list the consequences of using the pattern. Every design decision
includes trade-offs, and choosing whether to use a pattern is like every other design
decision in this respect. Obviously, knowing the consequences of a decision enables you to
make better decisions.

The Cocoa frameworks are remarkably self-consistent. The designers used and reused
several common patterns, and even created a few of their own. Because these patterns recur
throughout the frameworks, it is useful to describe the patterns before diving into the
frameworks themselves. References to named patterns simplify the descriptions of the
frameworks. When a pattern is identified, the problem being solved and the consequences
of the solution are efficiently conveyed.

Design Pattern Terminology

Cocoa tends to use specific terms, which differ from the names that you might find in
object-oriented design texts, for many of its underlying design patterns. It is useful to learn
Cocoa's vocabulary and how it relates to these other terms. Sometimes the term is different
because there really are subtle differences between the concepts. In other cases, they mean
the same thing but the ideas were developed independently, and thus have different names.

The patterns listed here are presented using terminology that is common among Cocoa
developers. Sometimes the patterns are unique to Cocoa, but in many cases, they are found
by other names in other literature.

NOTE

If you want to know more about patterns in general, an excellent starting

point is the seminal "Gang of Four" (GOF) book, Design Patterns: Elements
of Reusable Object-Oriented Software by Erich Gamma, Richard Helm,
Ralph Johnson, and John Vlissides (Addison-Wesley, ISBN 0-201-63361-2).
Patterns from that book are commonly referred to as "GOF patterns" Many of
the patterns found in Cocoa are also found in the GOF book and are presented
in greater detail there. The name of the GOF pattern is provided along with
the name used by Cocoa when this is the case. You don't need to know the
GOF patterns to read this chapter or use Cocoa, but understanding them
might help you to learn Cocoa more quickly.
Book: Cocoa® Programming
Section: Chapter 6. Cocoa Design Patterns

A Catalog of Cocoa Design Patterns

The meat of this chapter is a catalog of common design patterns found in Cocoa. This
catalog includes industry standard patterns and patterns unique to Cocoa. While this
catalog is not comprehensive, it does present the most commonly encountered Cocoa
patterns.

Model-View-Controller

Model-View-Controller, or MVC for short, is considered an architecture more than a

pattern. This is because it is a general way of organizing an application, and is an
architectural feature at a higher, more abstract level than most patterns. Because this
approach to application design permeates Cocoa, it makes sense to discuss it as a part of
the patterns and design philosophies encountered when working with Cocoa.

The MVC architecture was first used with the Smalltalk language in the 1970s, and has
proven to be one of the most successful and commonly used top-level application designs.
Every application has different architectural needs. MVC will not apply in every case, but
it is well-suited to most graphical applications.

MVC divides an application into three major parts or layers. Each part is composed of
many objects, and within the MVC paradigm their responsibilities and functions are well
defined. The pattern is named for its layers.

Model: This is the heart of an application. It contains all the application-

specific data structures and core logic.

View: Views are responsible for providing output to the user and collecting
input. Views are generally graphical, but they can be textual, Web-based,
and even script-based.

Controller: This handles synchronization between the model and views, as

well as some input from the user. The purpose of the controller layer is to
isolate the model and view, so that each can be changed independently of
the other.

If you consider an application to be an "editor" for some well-organized chunk of data, then
MVC becomes a natural means of internal-program organization. The data is all contained
within the model, and the view is the window, or interface, to the data that the application
presents to the user. The controller layer ties the two together.
Cocoa's emphasis on this type of application structure makes it valuable to offer more
details about each layer.

Model

The model should contain the central algorithms and data structures of the application. The
model is the core of the application, contains the application's internal state, and contains
most of the code that is unique to a particular application. It should be possible to reuse a
model with any number of different controller and view subsystems. To enable that reuse,
it is best if the code in the model has no dependencies on the controller or view.

View

The view contains the user interface for an application. In most graphical applications, the
purpose of the user interface is to enable users to view and modify the model's data via its
algorithms. Remember this when a user interface seems to be the most critical and complex
part of an application: A particular user interface has no value without a model to view and
modify, but a model can be used with any number of different user interfaces. Furthermore,
the historic necessity of designing applications around their user interfaces was the result of
inflexibility and inherent complexity in the user interface development tools that were
available. The user interface of a Cocoa application should not be more complex than the
model being viewed. In many Cocoa applications, the view might not contain any code at
all. For example, an application to view the file system might represent the file system as a
columnar browser, an outline, a table, or as scrolling text like a terminal. None of those
views of the file system necessarily require any custom code in the view subsystem of the
application because of the rich classes in the Cocoa frameworks and Interface Builder.

The view should not contain any application state other than state that is intrinsic to a
particular user interface. For example, the percentage of a document that is visible depends
on the nature of the view of the document. The appearance of a button depends on the
purpose of the button in the user interface. Those attributes are naturally part of the view.
However, the information displayed by a document and the value set by a button should be
stored in the model.

Ideally, the view subsystem and the model subsystem should have no interdependence.
However, if avoiding dependence is impractical, the dependence should be entirely from
the view to the model, and not the other way. Dependencies between subsystems result in
the situation where a change to one subsystem necessitates a change in the other. The code
in the model usually becomes stable and mature over time, but the user interface
continually evolves. If a change in the model requires a change in the view, the cost of the
change is mitigated by the fact that the view would likely change anyway. Furthermore,
many changes in the view can be accomplished with Interface Builder, and do not require
any code at all. A change in the model that is required by a change in the view can incur
costs that would otherwise be avoided.
Controller

Ideally, the view subsystem and the model subsystem should have no interdependence. The
controller subsystem exists to reduce the dependencies between the model and the view.
The controller is a layer of insulation between the other subsystems. The controller's
purpose is to prevent changes in the view subsystem from necessitating changes in the
model, and visa versa.

Any change to either the model or the view usually necessitates changes in the controller.
Therefore, the controller should be kept as small and simple as possible to reduce the cost
of those changes. The controller should not contain any application state. For example, if a
user presses a button to delete some information stored in the model, the action of the
button is in the controller subsystem. The controller's action should be implemented to call
the API of the model to delete the information. Then, the controller should use the API of
the view to reflect the deletion, perhaps by requesting that the view redraw. If the controller
is used in this way, the user interface to delete information can be changed to use a menu or
a script command, or both, without impact on the model. Similarly, the model can be
changed to disable the deletion of certain information without any change to the user
interface.

MVC in Cocoa

By making this separation into three layers, an application's interface and internal data
structures are decoupled. As a result, the potential for object reuse between applications is
enhanced. A generic view object, such as a text field, could be created and then reused in
many different, unrelated applications. A model could be used in different applications that
provide different ways to access or modify the model's data. For example, perhaps you
have a desktop application for manipulating some data and a secondary command line or
Web interface that allows access to the same data. Just like generic-view classes and
specialized-model classes can be reused, generic-controller classes can also be reused
across unrelated applications.

The Foundation Kit offers many data structures that provide a basis upon which a model
can be built. This allows you to concentrate on what makes your model special as opposed
to reimplementing yet another standard data structure. In theory, this layer is where most of
your code-writing time should be spent because the model is the part of your application,
which makes it truly unique.

Cocoa supplies a wide variety of views in the Application Kit, therefore, many applications
will not need to create their own custom views. This is a huge time saver, and one of the
ways that Cocoa can improve your productivity.

If you are creating a document-centric application, then the various classes surrounding the
NSDocument class will provide much of the controller logic you need. The
NSDocument class is described in Chapter 9, "Applications, Windows, and Screens."
Sadly, in other parts of the controller layer, Cocoa does not yet provide much help. The
Application Kit focuses on the view layer, whereas the Foundation Kit focuses on the
model. There is no generic "controller framework."

The lack of a controller framework is one area that could stand improvement. Note that
Apple does have some generic controller objects that would help. They are in the
EOInterface framework, which is a part of the Enterprise Objects Framework.
Unfortunately, this is not a part of Cocoa, so it isn't something every Cocoa developer can
use. Perhaps sometime in the future these classes, or something similar to them, will
become a part of Cocoa.

Until that time, however, there is no controller framework that is a part of Cocoa itself. As
a result you will often spend time writing code for your application's controller layer. Most
developers don't design and create reusable, generic-controller classes because it is difficult
to do well and takes much more time to create the objects. Few developers have the time
and resources to "do it right," so most Cocoa application developers create their own
controller classes each time. This is reasonable, especially given the time constraints of
most projects. Unfortunately, very few of these custom classes are reusable from one
application to the next.

Cocoa applications often have two features that do not fit well into the MVC architecture:
undo and user preferences/defaults. Each can reasonably be implemented in the controller
or the model, but each should be exclusively in one or the other. For example, setting and
getting user preferences/defaults can be implemented in the controller on the grounds that
the user defaults system is just another view, and the controller should communicate
between the user defaults view and the model. On the other hand, user defaults often
contain data (Application State) that is part of the model. Similarly, undo can be regarded
as recorded commands to modify the model, and therefore just another view that is like a
scripting system that communicates with the model via the controller. On the other hand,
undo can be considered preserved application state, and therefore best implemented in the
model.

A lot more could be said about how to design using the MVC approach, but it would
require a complete book. Any good book on object-oriented design will give more
information about it, so we recommend that you read a few books on design if you aren't
comfortable with the concepts behind MVC. While working in the other sections of this
book, keep MVC in mind to help you remember the proper uses of the various classes you
encounter.

Class Clusters

Class clusters are a means of hiding complexity in the inheritance hierarchy. The general
idea is similar to the GOF Facade pattern, which attempts to hide a complex graph of
objects behind a single object. Instead of hiding a group of interacting objects, a class
cluster hides several different classes behind one abstract superclass. Instead of knowing
anything about the subclasses, you only interact with the API defined by the abstract
superclass. The actual instances you manipulate will always be subclasses of the abstract
superclass, but you never know the actual class you are dealing with, and you don't need to
know.

The biggest impact of class clusters is that you'll see some unfamiliar class names in the
debugger, usually with the word "Concrete" in the name. For example, you might see
something like NSConcreteArray when you are working with an NSArray. A large
portion of the classes in the Foundation Kit are actually class clusters. The collection
classes and NSString are the ones you are most likely to encounter.

In the most general terms, you can write Cocoa programs without ever worrying about the
details of a class cluster. Just don't be thrown if you see unexpected class names when
running the debugger. The other important detail is that creating a subclass of a class
cluster is a tricky proposition and should be undertaken with utmost care. For the gory
details of class clusters, including how to subclass them, you should refer to Appendix A,
"Unleashing the Objective-C Runtime."

Shared Objects

One of the simplest patterns seen in Cocoa is called the "shared object" in Cocoa's
documentation. In GOF terms, this is known as a "Singleton." A shared object is used in
cases where a particular class should be instantiated once and only once. One of the most
obvious examples of a shared object is the central application object. Every Cocoa
application has a single NSApplication instance. This makes sense; an object that
represents a running application should only appear once per application.

Several other Cocoa classes you will learn about are also shared objects. NSWorkspace
represents the Mac OS X Finder and is a shared object. Some of the standard panels Cocoa
offers, such as the font and color panels, are also shared. Some of the scripting objects use
the shared object pattern.

To implement this pattern, the class object provides a method that is globally accessible
and can be used to obtain the shared-object instance. At the same time, the +alloc
method is disabled to prevent you from creating extra instances. The single, shared instance
is created the first time you ask for it, and then the same instance is returned every time
thereafter. Usually, the method used to obtain a shared instance includes the word "shared"
and the name of the class minus the "NS" prefix as in these examples:

From NSWorkspace.h:

+ (NSWorkspace *)sharedWorkspace;

From NSApplication.h:
+ (NSApplication *)sharedApplication;

You might also see this more generic method used sometimes:

+ (id)sharedInstance;

Finally, shared instances can sometimes be obtained by calling the +new class method.
This use of the +new method is left over from prior versions of the frameworks and is
deprecated. The +new method plays a crucial role in the earliest frameworks that were
developed for Objective-C, but should not be used with Cocoa.

For some classes it is also possible to find out whether or not the shared instance has
already been created. For example:

From NSSpellChecker.h:

+ (NSSpellChecker *)sharedSpellChecker;
+ (BOOL)sharedSpellCheckerExists;

Because Cocoa is object oriented, it is important that developers be able to subclass a

shared object and, instead of the original, use an instance of the subclass as the shared
instance. It turns out that, thanks to Objective-C, this is easy. Simply create your subclass,
and then call the appropriate accessor method, but with your subclass's class object as the
receiver instead of the superclass. For instance, suppose you have a special subclass of
NSSpellChecker. Before any other part of your application asks for a spell checker,
you would ask for it yourself, like this:

[MySpellchecker sharedSpellChecker];

This should return an instance of your subclass even if you haven't overridden the
+sharedSpellChecker method itself.

Enumeration

Cocoa's Foundation Kit offers enumerators for all its collection classes. This pattern is
similar to the GOF Iterator pattern. Enumerators provide a way to loop through any
collection of objects and do something with each object. Rather than requiring you to write
a specialized loop for each kind of collection, you can enumerate all objects from any type
of collection the same way. You simply ask the collection for an enumerator object, and
then ask the enumerator for the next object in the sequence until it stops returning objects.
Code to do this for an arbitrary collection class, myCollection, looks like this:

id instance;
id enumerator = [myCollection objectEnumerator];
while (instance = [enumerator nextObject]) {
// do something with instance
}

The code first obtains an enumerator from the collection class. Next, the enumerator is
asked for the next object in the sequence. When the enumerator runs out of objects, it will
return nil and then the loop will exit.

Every collection class in the Foundation Kit offers some kind of enumerator. Some other
objects offer enumerators, too, when it makes sense. The only thing that changes is the
method you call to obtain the enumerator itself. This changes because sometimes more
than one kind of enumerator is available. For example, NSArray enables you to pass over
all its objects in forward or reverse order. The two methods available for this have obvious
names:

From NSArray.h:

- (NSEnumerator *)objectEnumerator;
- (NSEnumerator *)reverseObjectEnumerator;

In the case of an unordered collection, only one enumerator may be available because
there's no concept of forward or reverse. Other collections, such as an NSDictionary,
might have more than one group of objects to enumerate over. A dictionary associates pairs
of objects with one object being the key, and the other being the value. You can enumerate
over just the keys or just the values:

From NSDictionary.h:

- (NSEnumerator *)keyEnumerator;
- (NSEnumerator *)objectEnumerator;

However, no matter how you get the enumerator, you always use it the same way.
Sometimes it is also useful to work in the other direction and create a collection containing
all the objects that would be returned by an enumerator. To do this, simply ask the
enumerator for an NSArray containing all the objects it would have returned:

myArray = [myEnumerator allObjects];

Target/Action

When a user manipulates one of Cocoa's user interface objects, it will send a specific
message to a specific object. This differs from many other application frameworks on other
platforms that insert an event into the application's event loop for later interception and
decoding. In Cocoa, this process of sending a direct message in response to a user action is
known as target/action. Using this terminology, the target is the object that receives the
message, whereas the action is the message that is sent.

Actions are invoked when buttons are clicked, when editing finishes on a text field, when a
slider is moved, and so on. Each interface object can have its own unique target and action.
Usually, only one interface object will send a particular action. This means there is rarely a
need to test to see what happened or which interface item was activated. Sometimes an
action might be sent by more than one object. For example, perhaps a particular button
triggers the same action as an item in the application's main menu. In a case like this, you
might want to know which control sent the action message. This is easy because all actions
have a single parameter: the message's sender.

To make use of target/action, you must do two things. First, create objects that implement
action messages. An action message will have a prototype that looks like this:

- (IBAction)someAction:(id)sender;

The name -someAction: will change depending on what your action method is
supposed to accomplish. When you have implemented your action method, you can use
InterfaceBuilder.app to connect an interface object with an instance of the class that
implements the action method. When that interface is used in your application, the action
message is sent to the target you selected in Interface Builder every time that the control is
activated.

It is also possible to create a target/action connection between objects programmatically.

Here's the code you would use to do it:

[myControl setAction:@selector(someAction:)];
[myControl setTarget:myTargetObject];

To determine what a control's target or action is, simply ask it using the -target or -
action methods. If you are implementing a control of your own, you don't even have to
know how to send an action because the NSControl class implements a method you can
use to send action messages:

- (BOOL)sendAction:(SEL)theAction to:(id)theTarget;

You can invoke this on any control subclass to get it to send an arbitrary action message to
an arbitrary target.

Commands

Those who are familiar with the GOF patterns might note that target/action seems to be an
implementation of the Command pattern. Although the command pattern, or something
like it, could be used to implement something like target/action, it is not needed in
Objective-C. The command pattern is used in more static object-oriented languages to
simulate the dynamic facilities that are missing. For an object to send a message that it has
never seen before in a static language would be generally impossible. To get around this,
you would create an abstract superclass called Command, which would implement a virtual
method such as invoke. Then, you would create a subclass for every method that you might
need to send. Finally, the sender would be handed an instance of some arbitrary Command
subclass and call invoke on that object when it needs to send the message. By doing this,
one object can send a message to another object even though the message was unknown
when the sender class was compiled.

Because Objective-C is more dynamic, however, there is no need to jump through all these
hoops to send an arbitrary message. Instead, selectors are passed to the sending object to
specify which message should be sent. The sender then uses the -performSelector:
method or, if appropriate, a variant such as -performSelector:withObject: to
invoke the method.

Selectors only specify the message to be sent and not the receiver. In some cases this is
desirable, but not always. If you need to specify both the message and the receiver with a
single object, the NSInvocation class can be used. An NSInvocation encapsulates a
message, a receiver, and all the parameters of the message. The NSInvocation class is
the closest Cocoa equivalent to the GOF Command pattern.

Delegates

One of the most common mistakes made by a new Cocoa developer is to subclass a Cocoa
object without really needing to. Normally, they want to change the object's behavior, and
that's why they make a subclass. In most other object-oriented- application frameworks,
subclassing is the only way to alter the behavior of a class. Instead, Cocoa introduces the
concept of delegation as an alternative to subclassing. No specific GOF pattern describes
delegation exactly; delegation is something of a hybrid of the Observer and the Chain of
Responsibility GOF patterns.

Delegation is a way for a framework designer to defer design choices. Instead of doing
everything one way and that way only, many Cocoa classes are equipped to ask some other
object what they should do in a given situation.

For example, if the user clicks the close button in a window's title bar, the default action
would be to close the window. But what if the window contains an altered document and
the application needs to enable the user to save their changes before the window is closed?
In Cocoa, the window will ask another object, "I want to close now, is that OK?" The
object can then respond yes or no, perhaps after presenting a sheet to ask the user whether
to save the document or cancel the window close. No subclassing is required to change the
window's behavior. Instead, another object is provided that can answer the question in an
application and context specific way.

This other object that gets to participate in the decision is known as the delegate. The
messages sent by an object to its delegate are known as delegate messages. No standard
terminology exists for the object that sends delegate messages to a delegate. For lack of a
better term, this book will use the word delegator to identify such an object. Typically, the
documentation and header for every delegator class describes all the messages that might
be sent to its delegate.

Many of the more complex Application Kit classes, such as NSApplication,

NSWindow, NSTableView, and NSToolBar, are delegators.

Some messages to delegates don't require a response from the delegate and are just sent to
let the delegate do something before or immediately after a particular event has happened.
For example, a delegate can receive a message just before and just after a window is placed
onto the screen. This offers the delegate the opportunity to perform any special
initialization or other operations at the appropriate time.

A delegate is not required to implement any particular delegate messages. It only needs to
implement the messages that are interesting to it. The delegator will always check to see if
its delegate responds to a particular message before trying to send the message. If the
delegate doesn't respond to a given message, it simply won't be sent.

NOTE

Checking to see if a delegate responds to a message before sending the

message might seem inefficient. The Cocoa implementation is actually a bit
smarter. When a delegate is set, Cocoa will determine the messages it can
handle and cache that information for use when a delegate message needs to
be sent.

One limitation of delegates is the fact that there is only a specific set of delegate messages
known to a delegator. If the designer of a delegator didn't send out a delegate message for
some event that you want to catch or influence, a delegate won't work. In that case a
subclass of the object might be the only solution. Luckily, there are not many places in
Cocoa where a subclass is required. The existing sets of delegate messages provide a rich
collection that covers nearly everything you'll need.

Another limitation of delegates is that objects usually have only one delegate. There is no
way, for example, for an NSApplication instance to have multiple delegates. If there is
a need to have more than one object receive delegate messages from a single delegator then
have your delegate pass messages on to other delegates.
In the case of messages that require a response, such as "do I close the window?"
forwarding the message to other objects is the only solution. On the other hand, if the other
delegates only require notification of events, such as "the window closed," and they don't
need to participate in any decisions, then the next pattern can be used to solve the multiple
delegates problem.

Notifications

Cocoa often uses notifications to tell objects in an application that something important has
happened. For any given notification, there can be multiple receivers of the message.
Multiple objects can send or post a given notification, as well. Some notifications come
with extra information detailing the event that they represent, and others do not.

The central figure of the notification pattern is the NSNotificationCenter, which is

described in Chapter 7. In GOF terms, the objects that register for a notification would be
known as observers. The NSNotificationCenter and NSNotification classes
provide a generic, flexible, and reusable implementation of the GOF Observer pattern.
Therefore, it should never be necessary for you to implement the pattern yourself.

To receive a notification, an object must register with a notification center. Usually, an

application has only one notification center, known as the default center, although you can
create more if necessary. When registering for a notification, an object can specify the
details of how it wants to receive the notification. It is also possible to specify the objects
from which a receiver accepts notifications.

When it is time to send out a notification, the sender "posts" the notification to the
notification center. The notification is automatically passed on to all the objects that
registered to receive it. Some notifications carry extra information about the event they
represent in a user info parameter. It is up to the object posting a notification whether to
add that information prior to posting.

Unlike delegates, notifications enable multiple objects to receive notification of a given

event. There can be any number of observers. Another benefit of notifications is that an
object can register for a notification without knowing who the sender is and the sender
doesn't have to know anything about objects that observe the notifications it posts. As
objects register and post notifications, the interactions between objects can emerge
dynamically. This reduces the need for global variables to help an object find other objects
it needs to communicate with.

One limitation of notifications is that the implementation is slower than that of delegate
methods because the notification center adds a layer of indirection. Furthermore, objects
that observe a notification cannot send a response directly back to the object that sent the
notification in the same way a delegate can.
Proxies

Cocoa's Distributed Objects technology includes the concept of a proxy, which is more
specific than the GOF Proxy pattern. This can be a point of confusion for those new to
Cocoa. Because the same term can mean two different things depending on context, this
section will take care to explicitly say "GOF Proxy," if that is what is meant.

In Cocoa, a proxy is a stand-in for another object that is in a different process or different
thread. Sending messages to the proxy is the same as sending them to the actual object. The
proxy transparently bundles the message, and sends it to the object in the other process.
The programmer doesn't have to worry about whether or not a proxy is involved, or
whether the ultimate receiver of a message is in the same process as the sender. Just send it
a message and the right thing will happen. Some designers call this an Ambassador.

The GOF Proxy pattern includes this function. It can also serve other functions. Therefore,
a Cocoa proxy is a GOF Proxy, but a GOF Proxy is not necessarily what Cocoa calls a
proxy. The other types of GOF Proxy do appear in Cocoa. Some have different names
while others have no specific name.

Another job of a GOF Proxy might be to allow for the lazy allocation and loading of an
expensive resource. The NSImage class is an example of this kind of proxy. In this case,
the object has two parts: The external part of the image, which is the interface you
normally access, and the actual image data, which is an NSImageRep or image
representation in Cocoa terms. The image can tell you information about itself without
needing to load and decode all the data. In fact, the data can be kept on disk until it is
actually used. This approach helps reduce memory usage in the case where some images
might never be displayed.

NSImage takes this a bit further, however, and actually can act as a proxy for multiple
image representations, choosing the best for a particular context. In this respect, the object
acts as a GOF Facade. A Facade is an object that presents a single, simple interface to a
more complex graph of underlying, cooperating objects.

Another Cocoa example that combines the Proxy and Facade patterns is the
NSWindowController, which usually acts as a cover for the graph of objects inside
one of Interface Builder's .nib files. It won't load the .nib itself until it absolutely has
to. At the same time, a window controller subclass usually acts as the application's
connection to the objects inside the .nib. In the process, it can also perform another
potential proxy duty: managing access to the object(s) it is covering.

A final example of Proxy behavior is not yet found in Cocoa proper, but is found in Apple's
Enterprise Objects Framework (EOF). Some proxies stand in for an object that hasn't yet
been created and might never actually be needed. In the Enterprise Objects Framework, an
EOFault performs this duty. It stands in for objects that are still in a database so that there
is no need to fetch a large chunk of a database's contents as a result of fetching an object
with references pointing all over the database. Because those references might never be
touched by the application, a fault object is put in place to stand in for the real object and
data. If the application ever tries to access the object, then the fault will automatically
transform itself into the real object and fetch the requested data.

Although Cocoa has nothing like this at present, it might have a class with similar behavior
in the future. Such fault objects can be useful for dealing with any type of object
persistence, and not just for databases.

In general, the GOF Proxy and Facade patterns are used extensively throughout Cocoa, and
often you will find both patterns in use together.

Facades

As explained in the previous sections on class clusters and proxies, a Facade is an object
that presents a single, simple interface to a complex graph of cooperating objects. It is
common throughout Cocoa to find the Facade pattern used in conjunction with other
patterns.

Many of the Application Kit objects you use, especially the more complex ones, are
Facades. Two of the Facades are the NSText and NSImage classes.

The way NSText is used is a great example of this; most Cocoa developers can just use
NSText itself and not worry about what happens inside. This is easy for the developer and
good enough for many situations. The trade-off is that you lose some flexibility,
configurability, and extensibility in exchange for that ease of use. A few developers will
want, or need, to make specific customizations and will pull back the Facade. In doing so,
they expose themselves to a large collection of new classes that they have to learn in
conjunction with a complex graph of objects that takes time to fully understand. The power
and customizability comes with a huge price in complexity.

Prototypes

Some of Cocoa's objects make direct use of the GOF Prototype pattern. A prototype is an
instance that is not used directly. Instead, it is used as a sort of template for creating new
instances. When a new instance is needed, the prototype is cloned. This is very useful for
generic containers such as the NSMatrix. When a matrix grows in size and needs more
elements, it copies a prototype to obtain the new elements.

The Prototype pattern enables you to create any appropriate instance and configure it
however you like. Because of this flexibility, the NSMatrix class doesn't need to know
anything about the instances it contains, and can simply create and install them
automatically, as needed, without requiring your intervention.
This is also useful for incorporating dynamically loaded code from bundles into your
application. A developer could use this pattern with multiple prototypes to create a palette
of preconfigured objects in their programs, too. The objects on an Interface Builder palette
are all prototypes.

In the case of NSMatrix, it is even possible to edit the prototype itself in Interface
Builder. Being able to control this from Interface Builder saves a lot of code when setting
up new dynamic interfaces.

Some of the other views provided in the Application Kit use a slightly different kind of
prototype. These prototypes are actually both shared and used between objects. Reuse of
instances in this way is common throughout Cocoa, especially for input, input validation,
and output formatting.

As an example, consider the NSTextField class. It presents a simple, editable field of

text to the user. However, it uses an NSText object to handle the editing itself. Since
NSText objects are heavyweight classes because of all the internal objects they use behind
the Facade, it is inefficient to create an NSText object for every single field in the
interface. Instead, all the text fields share a single NSText object, known as the field
editor.

In another example, the NSTableView object has an internal object that formats the rows
of a table for display. It is shared between the rows. The way this object is configured will
determine the look of all the rows that it formats.

Archiving and Coding

Cocoa's Foundation Kit offers a way to "freeze dry" an object, so that it can be brought
back to life at a later time. The object, when frozen, could be stored in memory, on a disk,
in a database, or by some other means. The process of freezing an object is known as
archiving or object serialization, and is performed by the NSCoder class. A coder can
freeze any object that conforms to the very simple NSCoding protocol. It can also
unfreeze any objects it or any other coder has frozen.

Encoding and decoding are described in Chapter 5, "Cocoa Conventions."

The frozen data produced by a coder contains the complete state of an object, and therefore
is similar to the GOF Memento pattern. Archiving is a little different from Memento,
though, because it is not usually used to restore an existing instance to a previous state.
Instead, it is used to store an object so that the live object can be destroyed and later re-
created exactly as it was. Another use for archiving is to create duplicate instances, or
move an instance from one process to another.

NOTE
 Another example of the Memento pattern in Cocoa is the undo system.
Cocoa's undo system usually doesn't do archiving to save and restore the state
of object, but archiving could be used as part of a brute-force undo
implementation.

Nearly all Cocoa objects conform to the NSCoding protocol. This enables live objects to
be manipulated and edited by Interface Builder. When the objects are saved into a .nib
file by Interface Builder, they are first frozen by an NSCoder instance so that they can be
written out as a part of the file. Coders are smart enough to freeze an entire graph of
objects, even if it has cycles in it. They keep track of both the objects in the graph and the
connections between the objects.

When an object is unfrozen, the coder will also send it a "wake up" message so that the
object can take care of any special tasks it might need to perform to become fully "alive"
again.

Subviews

In Cocoa, every area of screen real estate inside of a window is controlled by a subclass of
the NSView object. Although views should not be laid out so they overlap each other, one
view can completely enclose another. In this case, the enclosing view is known as a
superview, and the view that is enclosed is called a subview. Often the superview will add
some drawing around the subview or tile several subviews together to create a complex
user interface element. This is a hybrid implementation of the GOF Composite and
Decorator patterns, and not a specific pattern by itself.

The Composite pattern is a way for one view to build itself out of several others. An
example of a composite view would be an NSTableView object. This object uses
different objects to represent the table column headers, the cells, and the scrollbars. All
these views are assembled and controlled by the enclosing table view.

The Decorator pattern is a way for one view to add extra "decorations" around another
view. For example, the NSScrollView object can take any view and add vertical and
horizontal scrollbars to it. The most common view to put inside a scroll view is an
NSText instance, to create a scrollable text area. Any view could be put inside, though.
Another decorator is the NSBox class, which can optionally add a border and/or title
around a group of views.

All Cocoa views can have subviews and superviews, so they all can potentially be a
composite, decorator, or both.

Responder Chain
The responder chain is not a pattern, but rather another implementation of a pattern. It is
fully explained in Chapter 8, "Application Kit Framework Overview." It is mentioned here
because it is a concrete implementation of the GOF Chain of Responsibility pattern. In
short, the responder chain handles input from the user. Its job is to route input events to the
right place.

For example, if the user chooses the Copy command from the Edit menu, what should the
target for the menu item's -copy: action be? Whatever view currently has the focus and
active selection is given the first opportunity to handle the message. If the focused view
doesn't handle the message, it will be passed along to the control's window, and then, if it's
still not handled, the application object. A message like -quit: will usually make it all
the way to the application object. If an event isn't handled and drops off the end of the
chain, the application will beep at the user to alert him that his action wasn't understood.

The Application Kit has created a chain of objects that might be able to respond to the
event, and it includes the currently focused interface control at the start and the application
at the end. The Application Kit updates and manages this chain as the user moves from
control to control and window to window. In effect, the dispatching and routing of an
application's input events becomes automatic. By design it happens as a consequence of the
object graph's structure.

When a control's target is set to nil, it knows to send its action to whichever object is at
the head of the chain. This allows targets to be dynamically updated in a contextual
manner. Thus, you don't need to write any code to retarget your menu items. In fact, it is
even possible to determine if any object in the responder chain will handle a given message
or not. By making use of this information, Cocoa can automatically enable and disable
menu items as the user changes focus.
Book: Cocoa® Programming
Section: Chapter 6. Cocoa Design Patterns

Summary

With the responder chain, the target/action and the Chain of Responsibility patterns have
been tied together in Cocoa's design. Several other examples of patterns being combined by
Cocoa have been shown throughout this chapter. This type of interaction between the
patterns is common. Because Cocoa consistently applies the patterns, you will probably
find it easy to learn despite the huge size of the APIs. You will find that things tend to
work the way you would expect when you are comfortable with the underlying patterns.

As you become more proficient, you'll even be able to guess at method names without ever
having read an object's documentation. You will also find that if you try to use these same
patterns as you write code, your objects will be better able to leverage the Cocoa's power.

This discussion of patterns in Cocoa is just an overview. This chapter offers only brief
descriptions of the most common, most reused patterns found in the Cocoa frameworks,
while focusing more on their application within the frameworks than on theory.

Keep in mind that entire books have been written to describe patterns. This chapter is just a
starting point.

This chapter concludes the section of the book dedicated to background information,
languages, conventions, and patterns. The background information presented so far will be
essential for understanding the frameworks. Beginning in the next chapter, details about the
Cocoa frameworks, and techniques to unleash their power, are presented.
Book: Cocoa® Programming

Part II: The Cocoa Frameworks

IN THIS PART

7 Foundation Framework Overview

8 The Application Kit Framework Overview
9 Applications, Windows, and Screens
10 Views and Controls
11 The Cocoa Text System
12 Custom Views and Graphics Part I
13 Custom Views and Graphics Part II
14 Custom Views and Graphics Part III
15 Events and Cursors
16 Menus
17 Color
18 Advanced Views and Controls
19 Using Pasteboards
20 Adding Online Help
21 Multimedia
22 Integrating with the Operating System
23 Networking
24 Subprocesses and Threads
25 Printing
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 7. Foundation Framework Overview

IN THIS CHAPTER

● Mutability
● Class Clusters
● Typed Storage
● Collections
● Property Lists
● Run Loops and Timers
● Support Types
● String Processing
● Bundles
● File System Access
● Defaults System
● Notifications
● Related Core Foundation

The Foundation framework contains the classes, functions, and data types that are used by
all Cocoa applications. The Foundation framework is the foundation on which other Cocoa
frameworks are built. Much of the power of the Cocoa frameworks results from the
consistent use of foundation classes. Functions and methods throughout Cocoa use features
provided by the Foundation framework. For example, methods that use strings use
instances of the foundation NSString class.

The Foundation framework can be used for both nongraphical and graphical applications. It
contains a wide range of classes including classes that implement strings, values,
collections, dates, and timers. Operating system features such as file system access,
networking, process information, threads, command-line arguments, and even user
preferences are encapsulated by foundation classes. The Foundation framework is present
in every copy of Mac OS X. A more or less complete reimplementation of the Foundation
framework exists as part of the open source GNUstep project for Linux available at www.
gnustep.org.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Mutability

Many of the classes in the Foundation framework are immutable meaning that instances are
created with a particular value or content, and the value does not change for the life of the
instance. If another value is needed or different information must be stored, a new instance
is created with the new value rather than changing the value of an existing instance. The
value stored by an immutable object never changes after the object is initialized.

In contrast to immutable objects, the value or content of mutable objects can be changed
any number of times. In most cases, when the Foundation framework includes an
immutable class, a mutable variant is also available. Mutable classes are commonly
implemented as subclasses of immutable ones. The mutable classes extend their respective
superclasses by adding methods to change the value or contents of instances. Many
immutable classes also provide a -mutableCopy: method that returns a mutable copy of
the immutable object.

NOTE

A common mistake made by programmers is the over use of mutable classes.

Use mutable classes only when necessary to simplify an algorithm. Mutable
classes do not share many of the optimizations of memory and performance
that benefit immutable classes.

Immutable classes are implemented to enable efficient memory use. For example, when an
instance of the immutable NSString class is initialized with a value, the exact storage
needed for the string is allocated. When a mutable string is used, undesirable inefficiencies
results from the need to handle changes in the length of the stored string. The same storage
issues and optimizations apply to other classes that store arbitrary amounts of data
including collection classes.

Common operations such as copying are optimized when immutable classes are used.
Because the value of an instance of an immutable class cannot change, there is no need to
allocate any new storage for a copy. Copying is implemented to return another pointer to
the original instance. One instance can be safely shared.

Mutable Instance Variables

If a pointer to a mutable instance variable is returned from a method, the encapsulation of

the class that owns the instance variable might be violated. In such cases, other code might
change the value stored by the mutable object without using methods of the class that owns
it. However, when a class uses an immutable instance variable, the class can safely return a
pointer to the instance variable from accessor methods. There is no danger that the returned
object will be modified without its owner's knowledge. Returning immutable objects from
accessor methods simplifies implementation, promotes efficiency, and preserves the
encapsulation of the object that implements the accessor methods.

In the following example, a simple class stores an immutable string using the NSString
class described later in this chapter. The immutable string is safely returned from an
accessor method:

@interface MYSimpleClass
{
NSString *_myStringValue;
}

- (NSString *)safeStringValue;

@end

@implementation MYSimpleClass

- (NSString *)safeStringValue
{
// The instance variable can be safely returned
return myStringValue;
}

@end

However, if MYSimpleClass is implemented with a mutable string and provides access

to that mutable string, the encapsulation of the class might be violated:

@interface MYSimpleClass
{
NSMutableString *_myStringValue;
}

- (NSMutableString *)unsafeStringValue;

@end

@implementation MYSimpleClass
- (NSMutableString *)unsafeStringValue
{
// The instance variable can not be safely returned
// because it may be modified externally and violate the
// encapsilation of MYSimpleClass
return myStringValue;
}

@end

The mutable instance variable cannot be directly returned from an accessor method without
inviting violations of MYSimpleClass's encapsulation. The value stored by the mutable
variable could be modified outside MYSimpleClass.

Two techniques are used to return a mutable object from a class without violating that
class's encapsulation. A mutable instance variable is safely returned by a method typed to
return an immutable object. Programmers might take advantage of the fact that the returned
object is actually mutable, but a determined programmer can circumvent any protection.
Programmers should respect the return type specified by a method and not assume that the
returned value is actually a subclass of the specified type. Also, if it is necessary to return a
mutable object with the intention that programmers will modify the returned object, return
a mutable copy of the instance variable.

@interface MYSimpleClass
{
NSMutableString *_myStringValue;
}

- (NSString *)safeStringValue1;
- (NSMutableString *)safeStringValue2;

@implementation MYSimpleClass

- (NSString *)safeStringValue1
{
// The instance variable can be safely returned.
// The caller will have to cast the return value
// to violate MYSimpleClass's encapsulation
return myStringValue;
}

- (NSMutableString *)safeStringValue2
{
// A mutable copy of the instance variable is returned
return [[myStringValue mutableCopy] autorelease];
}

@end
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Class Clusters

The Foundation framework and other Cocoa frameworks contain several class clusters.
Class clusters consist of multiple hidden classes that are accessed through an abstract
public superclass. In Objective-C, when an object is described as abstract it means that
programs use instances of classes that inherit from the abstract class, but rarely use
instances of the abstract class itself. Concrete subclasses of the abstract class are used.
Chapter 6 introduced the class cluster design pattern. Apple provides excellent
documentation about class clusters and the reasons for using them at http://developer.apple.
com/techpubs/macosx/Cocoa/TasksAndConcepts/ProgrammingTopics/Foundation/
Concepts/ClassClusters.html , and in the online documentation that comes with Apple's
developer tools.

The primary motivation for using class clusters in a framework is to simplify the use of
multiple complex classes. Simple concepts might sometimes require complex
implementations for reasons of flexibility or optimization. Class clusters attempt to present
simple class interfaces that match simple concepts and hide the true complexity of
implementations from users of a framework. Having a few classes that conceal a multitude
of hidden classes reduces the number of classes that must be learned to use a framework.

Prominent Foundation class clusters are accessed via the NSArray, NSCharacterSet,
NSData, NSDictionary, NSNotification, NSScanner, NSSet, and NSString
abstract classes. These classes are commonly used but seldom subclassed.

The class clusters in the Foundation framework simplify complex multiclass

implementations, but the price of that simplification is increased difficulty when
subclassing a member of a class cluster. An example of a custom subclass of a class
cluster's abstract superclass is provided in Appendix B.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Typed Storage

Many programming languages provide built-in data types for the storage of common values. The C language contains
only the bare minimum of built-in types that map well to the hardware limitations of almost every CPU family. The
philosophy of the C language is to implement as little as possible in the language itself and execute complex ideas in
libraries. As a small extension of C, Objective-C adheres to the same philosophy. Objective-C adds only a small
number of standard data types, and they are all defined in terms of C built-in types such as char * and pointers to
structures. Apple's Foundation framework contains classes that enhance the basic capabilities of Objective-C and
manage data types that are more complex and powerful than the built-in types.

In some cases, the classes in the Foundation framework act as simple object wrappers around standard data types. The
object wrappers encapsulate data along with the available operations on the data. The wrappers also aid memory
management and storage of data in XML documents or other contexts. Storing simple data types as objects enables the
use of those types in conjunction with collection classes.

Foundation classes that provide powerful features far beyond the limits of the built-in types are available. Strings with
numerous encodings including 7-bit ASCII and Unicode are supported. Date and time management classes prevent the
types of problems encountered with the year 2000 roll over. Classes that encapsulate large blocks of binary data in
efficient ways are available. For example, arbitrary data from files on disk is mapped into virtual memory so that it can
be accessed in random order without the need to load it all into memory at once.

Strings

Strings are one of the most common types used in any program. The C language does not have a built-in string data
type. Strings are usually simulated via pointers and arrays. The Foundation framework provides classes that manage
almost every detail of string manipulation including memory management, encoding systems including Unicode,
searching, truncating, concatenating, and more.

NSString

The NSString class is the public face of a class cluster. Private subclasses exist to efficiently handle 7-bit ASCII
strings, constant strings compiled into a program, Unicode strings, and gigantic strings that are mapped into virtual
memory.

When an instance of NSString is initialized, an instance of one of the private subclasses is created based on the
encoding and size of the requested string instance. NSString instances are immutable. They are initialized with a
particular value that never changes. The immutability enables several optimizations in the implementation and usage
of strings.

One of the most common ways to create NSString instances is the use of the @"" construct provided as an
extension to the Objective-C language in Apple's compiler and runtime. The open source Gnu implementation of
Objective-C and the Gnu runtime include the same support. Any string declared between the quotes of a @""
expression is created at compile time as a constant instance of NSString using 7-bit ASCII encoding. Such strings
might be stored along with executable code in the resulting application's binary.

Constant strings created with @"" are full objects and are used in any context that NSString instances created other
ways are used. For example, messages can be sent to constant string objects as follows:

[@"This is a 7 bit ASCII string" length];

[@"The quick brown fox" stringByAppendingString:@" jumped over the log"];
Convenience allocators provide another common way to create NSString instances. Following the Cocoa
conventions, class methods that include a variation of the class name return new autoreleased instances. The simplest
convenience allocator for NSString is -stringWithString:. It accepts a string argument and returns a new
immutable string instance with the same contents as the argument. The -stringWithString: method is used to
copy strings and serves as an example of the power that class clusters provide. The subclass of NSString that is
returned from -stringWithString: depends on the argument. If the argument is a multimegabyte string that is
partially stored on the hard disk, an NSString implementation optimized for that case is used. If the argument is a
short constant string compiled into the application, the string returned from -stringWithString: might just be
another pointer to the same string contents.

Many convenience allocators and corresponding initializer methods are provided. The guidelines for using the
convenience allocators versus the combination of +alloc and an initializer are the same as for other classes. If the
instance that is being created is intended to be returned from a method and is not stored by the object that is creating
the string, the convenience allocators should be used. Otherwise use +alloc and an initializer.

The online class documentation describes each of the available initializers and the convenience allocators, but three
groups of methods deserve special recognition here. First, the NSPathUtilities category of NSString provides
methods that manage file system paths. Methods such as -stringByDeletingLastPathComponent: are very
handy, but they are frequently overlooked. Second, string objects are created from C pointers to characters via -
initWithCString:, and the -lossyCString method returns a pointer to any 7-bit ASCII characters stored by
the receiving string object, performing conversions as necessary. Third, NSString provides the following methods
that accept formats and arguments similar to the printf() function in the standard C libraries: -
initWithFormat:... and -stringWithFormat:... . For example, the following code produces a new
instance of NSString containing a formatted string, a number, and a new line character:

[[NSString alloc] initWithFormat:@"Name: %s Number: %d\n",

"John Smith", 42];

Most of the standard format string arguments are supported, but Mac OS X v. 10.1.2 and earlier versions contain some
errors and omissions from the ANSI standard. Bug reports have been submitted and Apple is aware of the problems.
They are not severe and will probably be resolved in future releases of the operating system and libraries.

An additional format beyond those supported by standard printf() is also available. The %@ format uses the object
argument's description. For example, the following code is similar to the previous format example, but it uses a
constant string object instead of a C string constant:

[[NSString alloc] initWithFormat:@"Name: %@ Number: %d\n",

@"John Smith", 42];

The distinction is subtle. Whenever a %@ is encountered in a format string, the corresponding object argument is sent a
-description message. The -description message returns an NSString instance, and that string is used to
produce the formatted string. Because the NSString class implements -description to return itself, the format
that uses a C string constant and the format that uses a string object both produce the same result. However, object
descriptions enable many powerful uses. For example, the following code creates an instance of NSString
containing the name of a private subclass of NSString:

[[NSString alloc] initWithFormat:@"Class name: %@", [@"Constant string"

class]];

In the example, when the -class message is sent to the constant string instance, its class object is returned and used
as the argument in the formatted string. The -description method is implemented by class objects to return the
name of the receiving class. In this case, the name of the private subclass of NSString that was created by the
compiler is returned.

NOTE
 Objective-C class objects are true objects and can respond to any messages defined for the NSObject
class. Because the NSObject class declares the +description message, all class objects can
respond to it. The -description and +description methods are also used by Apple's version of
the gdb debugger when the debugger's print-object (po) command is invoked.

Objects return arbitrary strings from their -description methods. In some cases, the strings are long and complex.
For example, the foundation collection classes implement -description to return a string containing the
descriptions of all the contained objects. When collections contain other collections, tremendous amounts of
information might be revealed by one -description message.

The NSString class inherits the -compare: method from the NSObject class. The -compare: method is used
to compare strings with arbitrary objects, but NSString also provides the -isEqualToString: method to
perform optimized comparisons when the object being compared is known to be another string. Use -
isEqualToString: instead of -compare: whenever possible.

Methods for searching strings and obtaining substrings are available. The online documentation that comes with
Apple's developer tools lists available NSString operations. String objects are used extensively throughout the
Cocoa frameworks, and the most common NSString methods quickly become second nature to Cocoa programmers.
NSString's -length method returns the number of stored Unicode characters in the string. The -
characterAtIndex: method returns the Unicode character at a particular index in the range 0 to (length -
1).

NSMutableString

NSMutableString is a subclass of NSString and therefore inherits all NSString's capabilities.

NSMutableString adds methods to change the contents of existing instances. Use mutable strings when they
simplify an algorithm, or when it is necessary to make several small changes to a single string without varying its
length very much. Mutable strings do not share many of the optimizations of memory and performance that benefit
immutable instances.

Raw Data

Strings are one of the most common types used in programs. Because the ANSI C language does not provide any high-
level abstractions for strings, they are usually implemented as pointers to bytes or as arrays of bytes in ANSI C. The
Foundation framework provides the NSString class to encapsulate true strings whether they store bytes or complex
multibyte character encodings, but many programs still need to store and manipulate arbitrary bytes. Examples of
arbitrary data stored as bytes include images, archived objects, and data received over a network connection.
Traditional C programs commonly store such data the same way they store strings. Arrays of characters are used, and
values are accessed via pointers to characters. The Foundation framework provides the NSData class to store and
access arbitrary data that might not be correctly interpreted as strings.

NSData

The NSData class cluster encapsulates arbitrary bytes. No special meaning or significance is applied to the stored
bytes. The data might represent a compressed TIFF format image, a sound loaded from the hard disk, or a complex
graph of archived objects. The NSData class manages the memory used to store the bytes and controls access to the
bytes. The NSData object is immutable.

Instances of the NSData class are used throughout the Cocoa frameworks. Some of the hidden classes in the NSData
class cluster use virtual memory features of Mac OS X to optimize storage of large amounts of data. When NSData
objects are initialized with the contents of large files on disk via methods such as -initWithContentsOfFile:,
the files are mapped into the process's virtual memory address range and portions of the files are brought in and out of
memory on demand. This behavior enables random access to the bytes stored by NSData objects without requiring
that every byte be loaded into memory at once. Mapping existing files into virtual memory also avoids the need to ever
load bytes that are not accessed. If an NSData object is initialized with the contents of a 100MB file, but only a few
bytes of the file are ever read, only a small part of the file is ever loaded into memory.

NSData's -bytes method returns a pointer to the data stored. The -length method returns the number of bytes
stored. All other NSData methods are implemented using these two methods.

NSMutableData

The NSMutableData class extends the NSData class to enable modification of the stored data. The storage
allocated by NSMutableData objects grows and shrinks automatically as bytes are added or removed. The
NSMutableData class is used to avoid manual memory allocation using functions such as malloc() and
realloc(). NSMutableData encapsulates memory management of arbitrary data using the standard Cocoa
memory conventions and helps avoid dynamic memory allocation errors.

The decision to use mutable or immutable data is similar to the decision to use mutable or immutable strings.
Immutable data objects benefit from many optimizations that are not possible with mutable objects, but some
algorithms might require mutable data. Use the immutable NSData class to maximize operating system optimizations
when very large amounts of memory are stored, or when the bytes stored are read only. Use NSMutableData in
situations where dynamic memory allocation is required and when there is a need to modify the bytes that are stored.

NSMutableData's -mutableBytes method returns a pointer to the bytes stored. The stored bytes are modified
via the pointer. The -setLength: method expands or reduces the number of bytes stored. If the storage is increased,
the new bytes are initialized to zero.

Values

The Foundation framework provides object wrappers for nonobject data types. The NSValue class, and its subclasses
NSNumber and NSDecimalNumber, encapsulate nonobject types within objects so that they can be managed using
Cocoa's memory management conventions and stored within collections such as NSArray and NSDictionary that
only store objects.

NSValue

The NSValue class is immutable and provides an object wrapper around fixed-size, nonobject data types. NSValue
only wraps values of fixed-size types such as int, float, pointers, and structures. NSValue does not store variable
length arrays of values or arbitrary numbers of bytes. NSString and NSData are better suited to storing large or
variable amounts of data.

NSValue instances are created and initialized with the value of a nonobject data type. The initializers and
convenience allocators used to create an NSValue instance require a pointer to the value to be stored and a string that
defines the type of the value being stored. The type of the data being stored can be obtained by using the @encode()
compiler directive described in Chapter 4. For example, the following code creates an instance of NSValue that stores
a double value and another one that stores a structure.

typedef struct _MYSampleStruct

{
int anInt;
_MYSampleStruct *nextStruct;
} MYSampleStruct;

{
 double doubleValue = 5.5;
MYSampleStruct sampleStruct = {10, NULL};

NSValue *aDoubleValue = [NSValue valueWithBytes:&doubleValue

objCType:@encode(doubleValue)];
NSValue *aStructValue = [NSValue valueWithBytes:&sampleStruct
objCType:@encode(sampleStruct)];
}

The +valueWithBytes:objCType: convenience allocator is used in the example and returns autoreleased
instances. The NSValue class provides additional dedicated convenience allocators for many of the data types
commonly wrapped including pointers. If NSValue is used to store pointers, remember that only the pointer is stored.
Do not deallocate the values referenced by the pointer before the NSValue instance is deallocated or the NSValue
instance will be left storing an invalid pointer.

NSNumber

NSNumber extends the NSValue class with a set of methods for storing and accessing numeric values. The
following standard C data types are directly supported by NSNumber in both signed and unsigned variants: BOOL,
char, short int, int, long int, long long int, float, and double. NSNumber overrides the -
compare: method inherited from NSObject to enable standard numeric ordering of NSNumber instances. The
number stored by an NSNumber instance can be a obtained in any of the supported types, and standard numeric
conversions are applied. For example, when the int value of an NSNumber that is storing a double value is
requested, a conversion from double to int is performed using the same conversion rules as standard C. The
NSNumber instance continues to store a double, the conversion only applies to the returned value.

NSDecimalNumber

NSDecimalNumber is a subclass of NSNumber that stores numbers in a format that reduces cumulative errors that
occur when performing decimal arithmetic on binary values. Binary numbers stored in a computer do not have infinite
precision and therefore must approximate some values that are stored. Decimal numbers stored in a computer do not
have infinite precision either, but the two different number systems have different limitations. Each number system is
forced to approximate different values. It is usually best to store decimal numbers, such as the balance of a bank
account, in an encoding that preserves the expected precision of decimal numbers rather than converting back and
forth to standard binary encoding.

NSDecimalNumber uses a decimal encoding and stores values with 38 digits of precision in the range from 10-128 to
10127. Like NSNumber, NSDecimalNumber is an immutable class. Different rounding schemes and error handling
behaviors are used with NSDecimalNumber. The NSDecimalNumberBehaviors protocol defines the available
behaviors and is described in the online documentation that comes with Apple's developer tools.

Dates

The Foundation framework provides rich capabilities for storing dates and times, and comparing them. Dates are
represented as seconds and fractions of seconds since a reference date, and can be output in a variety of forms
including as a month within a year or a day within a week. Dates and times are represented by several different objects
with different capabilities, but all dates are immutable and represent a single instant in time.

Dates and times are stored as time intervals from a reference time. Cocoa uses the first instant of January 1, 2001 GMT
as its system-wide, absolute reference date. Double precision, floating-point values storing seconds provide greater
than millisecond accuracy for dates 10,000 years apart.

NSTimeInterval
NSTimeInterval is the type used to store time intervals within Cocoa. NSTimeInterval is not a class. It is a
type that refers to double precision, floating-point values. Time intervals are often obtained by calling the
+timeIntervalSinceReferenceDate class method of the NSDate class. The returned time interval is the
interval between the system's absolute reference date and the current date and time. After January 1, 2001, all time
intervals returned from +timeIntervalSinceReferenceDate are positive.

One way to time the execution of code is to obtain NSTimeIntervals before and after the code executes and
compare the intervals. For example, the following code calculates the number of seconds needed to execute a long-
running calculation and provides better than millisecond accuracy:

NSTimeInterval startInterval;
NSTimeInterval stopInterval;
NSTimeInterval elapsedInterval;

startInterval = [NSDate timeIntervalSinceReferenceDate];

// execute some long lasting calculation here
stopInterval = [NSDate timeIntervalSinceReferenceDate];

// calculate the time elapsed in seconds with

// sub-millisecond precision
elapsedInterval = stopInterval - startInterval;

NSDate

NSDate is the abstract public interface of a class cluster. When an instance of NSDate is initialized, an instance of
one of the private subclasses of NSDate is returned. NSDate provides the foundation for all time storage within
Cocoa.

NSDate provides an interface for creating and comparing dates. Time intervals between dates are computed. The
private subclasses of NSDate are implemented to be efficient and immutable. Different subclasses of NSDate might
use different reference dates and different calendar systems. The public NSCalendarDate subclass of NSDate
provides dates using the Gregorian calendar and international time zones.

NSCalendarDate

NSCalendarDate extends NSDate to represent dates using the Gregorian calendar. NSCalendarDate uses an
associated time zone to control the way times are displayed and interpreted. Like NSDate, NSCalendarDate stores
a time interval from the system's absolute reference date. The time interval stored is independent of time zone, and
NSCalendarDate can be compared with other NSDate objects without concern for time zone differences. The
associated time zone only affects how dates are initialized and output.

NSCalendarDate instances are initialized with dates provided as strings or by values corresponding to year, month,
day, hour, minute, and second. NSCalendarDate instances can also be initialized as offsets from other dates.

NSCalendarDate instances provide a string description of themselves using different location, language
information, and formats. A wide range of output options are available for dates, and NSFormatter objects are used
to fine-tune the way dates are presented to users.

NSTimeZone

NSTimeZone is an abstract class that helps date objects reflect time zone-related, location-specific information. The
NSTimeZone class stores the name of a time zone, but it does not store a temporal offset from GMT for the zone.
The Foundation framework includes subclasses of NSTimeZone that store offsets from GMT and Daylight Savings
Time information.
Time zone objects are obtained by calling the +timeZoneWithName:, +timeZoneWithAbbreviation:, and
+timeZoneForSecondsFromGMT: class methods of the NSTimeZone class. The default time zone in effect for
the computer can be obtained via the +defaultTimeZone method.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Collections

Collections are an essential component of most applications, and the Foundation framework
provides rich collection classes to meet most needs. All the collection classes take advantage
of Cocoa's reference-counted memory management conventions and the power of Objective-
C. The Foundation collection classes are able to store any type of object that conforms to the
NSObject protocol. The collections even store heterogeneous objects. In other words, a
single collection object stores many different classes of objects at the same time.

The Foundation framework includes classes for arrays, dictionaries, and sets. Arrays provide
ordered storage that enables random access to stored elements via an index specifying a
position within the collection. Dictionaries provide unordered associative storage. Each
stored object has an associated key object. The stored objects are accessed via the keys. Sets
provide unordered storage, which guarantees that no object is stored within the collection
more than once.

The collection classes only store objects. It is possible to store nonobject values within a
collection by wrapping the values within an object such as NSValue or NSNumber. It is not
possible to store nil within the collections.

The Foundation collection classes are intended to solve common problems. They are highly
optimized and handle a wide variety of uses. The collection classes are implemented as class
clusters, and various private subclasses exist to optimize different uses. For example, a
private subclass of NSMutableArray exists to optimize insertion at either the beginning or
end of the collection. Nevertheless, some programs might have specific needs that are not
well-suited to solutions using the standard collections. The Foundation collection classes are
handy, but do not hesitate to write new classes if there is a specific need.

One consequence of the implementation of collection classes as class clusters is that they are
difficult to subclass. An example of subclassing a class cluster is provided in Appendix B.

Arrays

Arrays provide ordered indexed storage. The objects stored in an array are accessed by index.
The Foundation framework implements arrays using the NSArray class cluster. NSArray
and NSMutableArray are abstract public interfaces. When an array is initialized, a private
subclass of NSArray is created.

The Foundation framework provides array classes that are used extensively throughout
Cocoa. Arrays are used to store the list of files in a directory, the list of documents open in an
application, the list of file types that an application can open, and much more. Arrays can be
loaded and saved from files and stored as property lists.

NSArray

NSArray is an immutable class. The array is initialized with certain contents and the
contents do not change during the life of the collection. Each object stored in an array is
automatically sent a -retain message and therefore is not deallocated until after the array
is deallocated. NSArray's -count method returns the number of objects stored in an array.
The -objectAtIndex: method provides access to the object at a particular index in an
array. Valid indexes are in the range 0 to count - 1. If an object at an invalid index is
requested, -objectAtIndex: raises a NSRangeException exception.

A new autoreleased array with the sorted contents of an existing array is obtained by using
the -sortedArrayUsingFunction:context: or -
sortedArrayUsingSelector: methods. All the objects in an array can be asked to
perform a particular method by calling NSArray's -makeObjectsPerformSelector:
or -makeObjectsPerformSelector:withObject: methods. Arrays can also be
written to files via -writeToFile:atomically: or converted to strings via -
description or -componentsJoinedByString:.

NSMutableArray

NSMutableArray extents the NSArray class to enable modifications to an existing array.

As objects are added to a mutable array, additional storage is allocated as necessary, and the
added objects are retained. As objects are removed from a mutable array, the objects are
released. If an object removed from an array is not retained by any other object, the object is
immediately deallocated when the array releases it.

Mutable arrays are sorted using either the -sortUsingFunction:context: method or

the -sortUsingSelector: method.

Dictionaries

Dictionaries store associated key value pairs. Dictionaries provide an efficient way to retrieve
data associated with a key. Each key is unique within a dictionary, but any number of
different keys can be associated with the same value. The keys and values stored in a
dictionary are not ordered.

NSDictionary

The NSDictionary class implements an immutable dictionary using a hash table. Because
NSDictionary instances are immutable, they must be initialized with their key value
pairs. The internal use of a hash table provides efficient access to values. Similar to all the
Foundation collection classes, NSDictionary retains the objects that it stores.
The NSDictionary class is used extensively throughout Cocoa. For example, dictionaries
are passed as arguments to notifications. User defaults and preferences are stored as
dictionaries. Dictionaries can be stored in files and represented as strings in a variety of
formats including XML.

NSDictionary's -count method returns the number of key value pairs stored in the
collection. The -objectForKey: method returns the object associated with a specified
key or nil if the key is not stored in the dictionary. The -keyEnumerator method returns
an enumerator object that can be used to iterate through all the keys stored in the dictionary.

NSMutableDictionary

The NSMutableDictionary class extends the NSDictionary class to enable

modifications to the contents of an existing dictionary. When keys and values are added and
removed from mutable dictionaries, the storage for the objects grows and shrinks
automatically. If -setObject:forKey: is called with an existing key, the object
associated with that key is replaced by the new object. Each key is only stored once in each
dictionary.

The objects (values) that are added to a mutable dictionary are retained by the dictionary and
released when they are removed. NSMutableDictionary stores copies of the keys
specified when objects are added. Therefore, objects used as keys must conform to the
NSCopying protocol. Any object that conforms to NSCopying may be used as a key as
long as an additional constraint is met. The NSObject class declares the methods -
isEqual: and -hash. If two keys are considered equal by the -isEqual: method, those
two keys must also return the same value from their -hash methods.

NOTE

The NSCopying protocol, the -isEqual: method, and the -hash method
are all defined in NSObject.h within the Foundation framework. NSObject
provides many powerful methods that can be used with almost any object.
NSObject's methods support Cocoa conventions described in Chapter 5,
"Cocoa Conventions."

Although any object that has the capability to be copied might be used as a key in a mutable
dictionary, dictionaries can only be used in property lists if all keys are NSString
instances. Similarly, dictionaries can only be represented as property lists if all the values
stored can be represented in a property list.

Sets
In the Foundation framework, a set is an unordered collection of objects with the property
that each object is stored only once. That concept contrasts arrays and dictionaries, which
store any number of references to the same object. Sets are used to efficiently determine if a
particular object is contained within a collection. Sets are an alternative to arrays when the
order of the contained objects is not important, but determining if an object is contained
needs to be fast.

NSSet

NSSet is the public abstract interface to a class cluster. Its -count method returns the
number of objects in the set. The -member: method returns non-nil if and only if the
specified object is contained by the set. The -objectEnumerator method returns an
enumerator that is used to access all the objects in the set.

The objects stored in a set must implement the inherited NSObject methods -isEqual:
and -hash so that any two objects that are equal according to -isEqual: also return the
same value from their -hash methods.

NSMutableSet

NSMutableSet extends the NSSet class to enable modifications to the contents of a set.
Objects that are added to a set are retained, and objects that are removed are released. The
storage for a mutable set grows and shrinks as needed. Objects are added with the -
addObject: method and removed with the -removeObject: method.

NSNull

The Foundation collection classes cannot store nil values. When there is a need to store a
placeholder value in a collection, the NSNull class is used. A single shared instance of the
NSNull class is obtained by calling the +null class method.

Enumerators

An enumerator is an object that enables flexible access to the contents of a collection.

Enumerators are called iterators in other frameworks. The Foundation framework provides
the abstract NSEnumerator class. Foundation collection classes have methods that provide
instances of concrete NSEnumerator subclasses to meet a variety of needs.

The following code shows one way to access all the objects stored in a preexisting collection
referenced by aCollection:

NSEnumerator *enumerator = [aCollection objectEnumerator];

id object;
// loop to obtain each object in aCollection
while (nil != (object = [enumerator nextObject])) {
// object is a pointer to one of the objects in
aCollection
}

One of the key aspects of this example is the fact that the specific type of collection
referenced by aCollection is not specified. The code works equally well if
aCollection is an NSArray, NSDictionary, or NSSet. When an enumerator is
initialized it is ready to return the first object in the associated collection. The first time -
nextObject is called, the first object is returned. Each subsequent time -nextObject is
called, another object in the collection is returned. When all the objects in the collection have
been returned, the -nextObject method returns nil.

Do not modify mutable collections while an enumerator is in use. Addition, removal, and
reordering of the contained objects corrupts the enumerator object. Enumerators retain their
associated collection so that collections are not deallocated while an enumerator is in use.

All the Foundation collection classes implement the -objectEnumerator method to

return an initialized and autoreleased instance of an NSEnumerator subclass. Some of the
collection classes are also capable of providing specialized enumerators. For example, the
NSArray class implements the -reverseObjectEnumerator method to enumerate
the contents of the array in reverse order. The NSDictionary class provides the -
keyEnumerator method for enumerating the keys used to store the objects enumerated by
the -objectEnumerator method.

Enumerators provide a general mechanism for accessing all the elements in a collection
regardless of the specific type of collection. In many cases, using an enumerator requires
fewer lines of code than an alternative approach. Enumerators decouple the uses of a
collection from the type of the collection and therefore enable the flexibility to change
collection types later without breaking code all over an application. Enumerators also take
advantage of optimizations that might not be obvious or practical when the contents of a
collection are accessed in a different way.

Deep Versus Shallow Copying

Two different approaches to copying collections exist. A shallow copy is a copy of the
collection itself, but not its contents. In other words, when a collection is shallow copied, the
result is a second collection containing references to the same objects contained by the first.
A deep copy copies the objects within the collection as well. When a deep copy is used, the
result is two collections containing references to different objects.

By default, the Foundation collection classes all implement shallow copying. One technique
for obtaining deep copies of collections is to use the NSArchiver and NSUnarchiver
classes. Archiving is described in Chapter 5. If all the objects stored in a collection conform
to the NSCoding protocol, the collection is copied using code like the following:

id MYDeepCopyObject(id <NSCoding> anObject)

// This function accepts an object conforming to
// the NSCoding protocol and returns a deep copy
{
return [NSUnarchiver unarchiveObjectWithData:[NSArchiver
archivedDataWithRootObject:anObject]];
}

The MYDeepCopyObject function accepts any object that conforms to the NSCoding
protocol and returns a deep copy of that object. If anObject is a collection, the entire
collection and all the contained objects are copied. In fact, anObject can be the root of an
arbitrary graph of interconnected objects and the entire graph is copied.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Property Lists

Property lists enable convenient storage of application data without the need to write a lot of code or
invent a new file format every time. Property lists are used extensively by Cocoa applications. User
defaults and preferences are stored as property lists. Information such as the icon to use for a
particular document type is stored in a property list. The Project Builder application uses property lists
to store information about the project being built, such as which files to include in the build and which
compiler options have been specified.

NOTE

Apple's developer tools come with a PropertyListEditor application that helps

users graphically edit a property list. The PropertyListEditor application can be
used to edit any property list including the user's preferences and defaults. When
property lists are stored in files, the extension .plist is often used.

Property lists are a textual representation of NSString, NSArray, NSDictionary, and NSData
objects. In fact, the -description method is implemented by each of these classes to return a
string containing the property list representation of the receiver and any objects contained by the
receiver. Almost any combination of NSString, NSArray, NSDictionary, and NSData objects
can be read or written as a property list. For example, it is possible to store an array of dictionaries that
each map string keys to data values in a property list.

There are two encoding styles for property lists. One is formatted to be very easy to read. The other
uses industry standard XML formatting. Only NSString, NSArray, NSDictionary, and
NSData objects are directly supported for use in both styles of property list. An additional constraint
is that the keys used in a dictionary must be strings for the dictionary to be stored in a property list.
XML property lists also store NSNumber and NSDate objects that cannot be directly stored in the
other property list style.

Property lists obtained via the -description message use the more readable format. One reason
for this is that the -description method is used within Apple's gdb debugger to show the contents
of objects. XML data would be hard to read in that context. An existing string containing a property
list can be used to recreate the objects described by the property list using NSString's -
propertyList method.

The NSArray and NSDictionary classes implement the -initWithContentsOfFile:

method to read an XML property list stored in a file at a specified path. In each case, the property list
read must define an array or dictionary as appropriate. If the file being read to initialize an array or
dictionary contains errors, the NSParseErrorException exception is raised.

Convenience allocators are also available. NSArray implements

+arrayWithContentsOfFile:, and NSDictionary implements
+dictionaryWithContentsOfFile:. In each case, if the file being read to initialize an array
or dictionary contains errors, nil is returned. An array or dictionary that contains only objects suitable
for property lists is written to an XML property list file using the -writeToFile:atomically:
method.

Using the non-XML property list style, numbers can be converted to and restored from strings easily
by using NSString methods such as -doubleValue and -intValue. With both property list
styles, many classes and structures are converted to and restored from strings. For example, the
NSStringFromRect() and NSRectFromString() functions exist to convert rectangle
structures to and from strings. Rectangle structures are briefly described in this chapter and in Chapter
12, "Custom Views and Graphics Part I." Objects that are not easily represented as strings are stored
in property lists as data. Any object or graph of objects that all conform to the NSCoding protocol
might be archived into an NSData instance. The following example demonstrates how an existing
NSColor instance is encoded into data:

// Obtain an autoreleased NSData object initialized by encoding an

// existing instance of the NSColor class.
NSData *tempData = [NSArchiver archivedDataWithRootObject:
aColor];

When an object or graph of objects has been encoded as NSData, the data can be stored in a property
list. This technique is used to store colors in each user's preferences property list.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Run Loops and Timers

Run loops are described with more detail in Chapter 8, "The Application Kit Framework
Overview," because most features of run loops apply to applications with graphical user
interfaces. However, run loops are implemented within the Foundation framework by the
NSRunLoop class, and some features of the Foundation framework such as timers rely
upon run loops. Each thread in a Cocoa application has one corresponding NSRunLoop
instance that helps the thread communicate with the operating system. The run loop for the
main thread in each application is created automatically. Other threads need to create an
NSRunLoop instance in code.

NSRunLoop

An instance of the NSRunLoop class monitors a set of possible input sources from the
operating system. The NSRunLoop class shields applications from requiring detailed
knowledge of the underlying operating system to operate effectively. NSRunLoop
simplifies the implementation of many common application features such as nonblocking
file system access and timers.

NSTimer

The NSTimer class is used in conjunction with the NSRunLoop class to schedule delayed
or periodic events. An NSTimer instance is created and initialized with the time interval
of the delay, a selector that identifies a message to send when the interval has elapsed, and
the object that should receive the message. Timers can be configured to send messages at
repeating intervals.

NSTimer is used as an alternative to multithreading in some cases. Different processing

jobs can be scheduled to execute at different times by using NSTimer to simulate
concurrent execution. For example, a find panel in an application is used to start a
repeating timer, which sends a message to search through the application's data structures a
few at a time. The user can continue to use the application during the search while
progressive results are displayed in the find panel.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Support Types

In addition to classes, the Foundation framework includes several functions and types
based on C structures. The NSTimeInterval type has already been mentioned.
NSTimeInterval is implemented using the C double type. Structures that store
points, sizes, and rectangles are defined in the Foundation framework. Another type used
extensively is NSRange.

NSRange

NSRange is a C structure used to identify a location and a length. For example, an

NSRange can be used to specify a range of characters to delete from a mutable string
using NSMutableString's -deleteCharactersInRange: method. The location
is the index of the first character to delete. The length is the number of characters to delete.
The NSRange structure is used by many Cocoa classes. NSRange is defined as follows:

typedef struct _NSRange {

unsigned int location;
unsigned int length;
} NSRange;

The Foundation framework contains a category that extends the NSValue to class to enable
storage of NSRange values as follows:

@interface NSValue (NSValueRangeExtensions)

+ (NSValue *)valueWithRange:(NSRange)range;
- (NSRange)rangeValue;

@end

Ranges are converted to and from strings with the NSStringFromRange(NSRange

range) and NSRangeFromString(NSString *aString) functions.
NSMakeRange(unsigned int loc, unsigned int len) is used to obtain a
new range. Ranges can be compared, intersected, and combined. The
NSLocationInRange(unsigned int loc, NSRange range) function is used
to determine if a location is within a range.

NSGeometry

The NSGeometry.h header file that is part of the Foundation framework defines several
data types that are useful for drawing and geometric operations. These types are part of the
Foundation framework because they are used even in nongraphical applications. The
NSPoint type is a C structure that stores the floating point X and Y coordinates of a point.
The NSSize type is a structure that stores floating point width and height values. The
NSRect structure consists of a point called the origin and a size:

typedef struct _NSPoint {

float x;
float y;
} NSPoint;

typedef struct _NSSize {

float width; /* should never be negative */
float height; /* should never be negative */
} NSSize;

typedef struct _NSRect {

NSPoint origin;
NSSize size;
} NSRect;

The Foundation framework contains the constant NSZeroPoint, NSZeroSize, and

NSZeroRect global values that are useful for initializing geometric structures.
NSMakePoint(float x, float y), NSMakeSize(float w, float h), and
NSMakeRect(float x, float y, float w, float h) are also used to
initialize structures. These types and functions are described and used in Chapter 12.

Just like the NSValue class is extended to store NSRange values, the Foundation
framework contains a category that extends NSValue to store NSPoint, NSSize, and
NSRect structures. A category also extends the NSCoder class to enable encoding and
decoding of geometric types:

@interface NSCoder (NSGeometryCoding)

- (void)encodePoint:(NSPoint)point;
- (NSPoint)decodePoint;
- (void)encodeSize:(NSSize)size;
- (NSSize)decodeSize;

- (void)encodeRect:(NSRect)rect;
- (NSRect)decodeRect;

@end

Finally, the geometric types are converted to and from strings using
NSStringFromPoint(NSPoint aPoint), NSStringFromSize(NSSize
aSize), NSStringFromRect(NSRect aRect), NSPointFromString
(NSString *aString), NSSizeFromString(NSString *aString), and
NSRectFromString(NSString *aString). When converted to strings, the
geometric types can be used in property lists.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

String Processing

The Foundation framework contains powerful string processing capabilities. Some are implemented directly by
NSString methods such as -rangeOfString: and -componentsSeparatedByString:. The Foundation
framework provides the NSCharacterSet and NSScanner classes that are used together to enable additional
types of string processing. A character set defines a set of Unicode characters, and a scanner is used to find patterns
involving characters from a set.

NSCharacterSet

The NSCharacterSet class encapsulates a set of Unicode characters. NSCharacterSet is the public interface
to a class cluster containing private classes optimized for different situations. For example, a character set composed
solely of the ASCII subset of Unicode characters has different performance characteristics than a character set
representing an Asian language using Unicode-composed character sequences. Character sets are primarily used
when scanning for patterns in a string. NSMutableCharacterSet is a subclass of NSCharacterSet that adds
methods to modify the contents of an existing set.

NSCharacterSet instances are usually obtained via convenience allocators such as

+alphanumericCharacterSet, +decimalDigitCharacterSet,
+lowercaseLetterCharacterSet, and +characterSetWithCharactersInString:. In many cases,
the easiest way to generate a character set is to invert an existing set. NSCharacterSet implements the -
invertedSet method to return an autoreleased NSCharacterSet instance containing all Unicode characters
except the ones in the original set. The following example initializes the nonWhiteSpaceSet variable to a set
containing all Unicode characters except spaces, tabs, and other white space characters:

NSCharacterSet *nonWhiteSpaceSet = [[NSCharacterSet

whitespaceCharacterSet] invertedSet];

NSCharacterSet is a CPU and memory resource intensive class. Profiling reveals that NSCharacterSet
methods such as -invertedSet consume a large share of the processing time in applications that use
NSScanner or perform a lot of complex operations with NSString. As with any powerful high-level technology,
the best practice is to implement Cocoa applications using the most straightforward and simplest techniques
available. Use NSCharacterSet and NSScanner when they save even a little work. When the application is
working correctly, profile it, and determine where any performance problems exist. In most cases, slight changes to
algorithms yield more performance improvements than avoiding NSCharacterSet, but NSCharacterSet is a
common source of performance problems.

NSScanner

The NSScanner class is used to scan strings for patterns and return substrings or numeric values. NSScanner
instances are usually initialized with a string to scan via +scannerWithString: or -initWithString:. The
scanner can be configured to be case sensitive or not via -setCaseSensitive:. The -isAtEnd method can be
used to determine that all characters from a string have been scanned.

The following example uses NSScanner's -scanUpToCharactersFromSet:intoString: and -

scanCharactersFromSet:intoString: methods to scan a string for substrings separated by punctuation
and white space characters, and then stores the substrings in a mutable array.

#import <Foundation/Foundation.h>
int main (int argc, const char * argv[]) {
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
NSMutableArray *resultArray = [NSMutableArray array];
NSString *testString = @"{Bush, George, W.},{Clinton, William, J.}";
NSCharacterSet *nameCharacterSet = [NSCharacterSet
alphanumericCharacterSet];
NSScanner *nameScanner;

// Initialize a scanner with the string to scan

nameScanner = [[NSScanner alloc] initWithString:testString];

while(![nameScanner isAtEnd])
{
// Skip characters that can not be in a name and
// discard the sub-string that does not include a name
[nameScanner scanUpToCharactersFromSet:nameCharacterSet
intoString:nil];

// if there are any characters left they must be part of a name

if(![nameScanner isAtEnd])
{
NSString *foundName; // this variable will hold pointer
// to autoreleased string created
// by the scanner
[nameScanner scanCharactersFromSet:nameCharacterSet
intoString:&foundName];

// Store the name in an array

[resultArray addObject:foundName];
}
}

[nameScanner release];

// Output the description of resultArray

NSLog(@"%@", [resultArray description]);

[pool release];
return 0;
}

The example code stores the strings Bush, George, W, Clinton, William, and J in resultArray.

NSScanner provides methods for extracting various numeric values from a string. The -scanDecimal:, -
scanDouble:, -scanFloat:, -scanInt:, -scanHexInt:, and -scanLongLong: methods convert
strings into numbers and store the numbers using the specified type. These methods return YES if a number was
successfully scanned. The argument to each method is a pointer to storage of the correct type. Scanned values are
stored at the specified address. In each case, excess digits are skipped so that the next character scanned is beyond the
last digit in the number. If the scanner cannot find a string representation of a number, the methods for extracting
numeric values return NO, and the value stored in the memory referenced by the argument is undefined.

Regular Expressions

The Foundation framework does not directly support string processing via regular expressions. Regular expressions
describe complex patterns within strings and are used with many languages including Perl and shell scripts.
NSString supports multiple-string encoding systems including Unicode. Implementing regular expressions for
complex encoding systems is very difficult. Unicode in particular is problematic. Even though NSString does not
support regular expressions directly, the C Regex functions that are part of Mac OS X's BSD subsystem can be used
with C strings obtained from the NSString class. In addition, several third-party libraries extend the NSString
class via categories to directly support regular expressions with certain constraints.

Both the Omni Foundation framework available at http://www.omnigroup.com/ftp/ pub/software/Source/MacOSX/

Frameworks and the MOKit framework at http://www.lorax.com/FreeStuff/MOKit.html provide regular expression
features for Foundation framework-based applications.

Formatters

Formatters format strings for presentation in a user interface. For example, formatters represent currency and dates
using formats appropriate for different countries and languages. Formatters also validate user input to ensure that
input values conform to specified formats. Formatters convert textual user input into objects such as NSNumber or
NSDate instances.

The NSFormatter class is part of the Foundation framework, but it is used in combination with the Application
Kit's NSCell class. NSFormatter is an abstract class. Subclasses such as NSNumberFormatter and
NSDateFormatter exist to handle specific formatting needs. The NSFormatter class is described in more
detail in Chapter 10, "Views and Controls." An example subclass of NSFormatter is provided in Chapter 11, "The
Cocoa Text System."
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Bundles

A bundle is a collection of executable code and resources such as images, sounds, strings, and user
interface elements. The code and resources are stored together within a directory structure. Each
resource is stored in its own file. In fact, bundles store multiple versions of resources to enable
localization. Localization refers to the ability to use one set of executable code with different resources
based on the language or culture preferences of the user. The different user interface elements, strings,
images, and so on, appropriate for different languages and cultures are stored separately within a bundle.

Within the code that programmers write, bundles are commonly loaded into running applications to
implement plug-ins. An application programmatically loads any number of bundles that contain
Objective-C objects and resources. Bundles containing Objective-C categories are even used to extend
existing classes within an application.

Bundles are implemented in several different forms within Mac OS X. Many bundles are loaded
automatically without any programmer intervention. For example, each application is itself
implemented as a bundle. The application bundle contains the application executable and the resources
needed to launch the application. The application bundle is called the main bundle. Frameworks are
bundles, which contain executable code that is automatically loaded into applications when they start.
Frameworks can also contain resources such as user interface elements and strings. The Foundation
framework itself is a bundle.

All types of bundles contain a file that stores a property list identifying important information about the
bundle. The property list can be read and interpreted as an NSDictionary containing keys and values.

NSBundle

Every Cocoa application has at least one bundle for the application itself, and that bundle contains the
application's main() function. Bundles are encapsulated by the NSBundle class. The application's
bundle is called the main bundle. It is accessed from within any application by using the NSBundle
class method, +mainBundle.

The bundle that contains the implementation of an Objective-C class is obtained using NSBundle's
+bundleForClass: method. The +bundleForClass method is usually used to access
framework bundles. For example, [NSBundle bundleForClass:[NSString class]] returns
the bundle for the Foundation framework itself because the NSString class is implemented in the
Foundation framework.

Bundles in the file system are loaded using NSBundle's -initWithPath: or

+bundleWithPath: methods. There is never more than one instance of NSBundle for each bundle
loaded. If an attempt is made to load the same bundle more than once, the -initWithPath: and
+bundleWithPath: methods return the existing instance. Loaded bundles cannot be unloaded, but
future support for unloading could be provided by Apple.
When a bundle is first loaded, code contained within the bundle is not yet linked into the loading
application. The NSBundle class waits until a request to use code within the bundle is made. One way
to force that code to be linked into a running application is to call NSBundle's -load method. The -
principalClass method also forces the linkage of loaded code. The -principalClass method
returns a class object for the "principal class" within the bundle. The principal class can be specified
when building a bundle with Apple's developer tools. If the principal class is not specified, the first
class found within the executable code for the bundle is returned.

If the principal class for a bundle is specified when the bundle is built, the name of the principal class is
stored in the bundle's info property list. All bundles contain an info property list containing information
about the bundle. A NSDictionary initialized with the contents of the info property list can be
obtained by calling NSBundle's -infoDictionary method. The NSPrincipalClass key
within the info dictionary is used to obtain the name of the bundle's principal class.

When a bundle has been loaded, any class defined within the bundle can be accessed using
NSBundle's -classNamed: method. For example, the class object for a hypothetical class named
MYApplicationPlugin can be loaded by calling [someBundle classNamed:
@"MYApplicationPlugin"].

It is not necessary to explicitly load the application's main bundle or any framework bundles. Those are
loaded automatically when the application starts. However, it is often necessary to use the main bundle
and framework bundles to access their resources. The -pathForResource:ofType: method
returns the path to a resource within the directory that stores a bundle. The following example initializes
a string with the contents of a text file resource named localizedText.txt within the main bundle:

NSString *resourcePath;
NSString *result = nil;

resourcePath = [[NSBundle mainBundle] pathForResource:

@"localizedText"
ofType:@"txt"];
if(nil != resourcePath)
{
result = [NSString stringWithContentsOfFile:resourcePath];
}

The -pathForResource:ofType: method automatically selects the resource with the specified
name using the user's preferred localization. If the user's preferred language is German and a German
language version of localizedText.txt exists within the bundle, the path to that version is
returned. If no German language version is present, the user's preferences for other languages are used
to determine which version's path is returned. The automatic support for localized resources applies to
all resources regardless of their type. Different user interface components, images, sounds, and so on
can be stored for each localization.

A bundle's resources can be loaded without loading any code from the bundle by using NSBundle's
+pathForResource:ofType:inDirectory: class method and specifying a directory that
contains an unloaded bundle. Localized resources are searched according to the user's language
preferences until the specified resource is found. If the specified resource does not exist, -
pathForResource:ofType: and +pathForResource:ofType:inDirectory: both
return nil.

When a bundle is loaded, the NSBundleDidLoadNotification is automatically sent to the

application's default notification center.

The NSBundle class is declared in the Foundation framework, but the Application Kit framework
extends NSBundle in several ways using categories. The Application Kit adds methods for loading
user interfaces, images, and other resources directly. The capability to extend classes that are declared
in one framework with methods that depend on features of another framework is very powerful.
Categories enable elegant designs. Methods are declared and implemented where they make the most
sense. Unfortunately, spreading the commonly used methods of one class across multiple frameworks
makes documenting the class very difficult. It does not make sense to describe how user interface
objects are loaded from bundles before introducing user interface objects in a chapter about the
Application Kit. Nevertheless, NSBundle is part of the Foundation framework. When reading Apple's
documentation, always be sensitive to the fact that important methods might be documented separately
from the main class documentation.

Localization

Resource files that are specific to a particular language or culture are grouped together. Each set of
localized resources is stored within a different directory inside the bundle directory. The bundle's
executable code works with any of the resources in the bundle. All versions of the same resource have
the same name so that they can be found regardless of the directory that contains them.

NSBundle automatically selects the most appropriate resources when methods such as -
pathForResource:ofType: are used. Each user's language preferences determine which
resources are used in a running application. User preferences are stored in property lists and are edited
using Mac OS X's System Preferences application. User language preferences are ordered. The user's
most preferred language is stored first in an array, followed by the second most preferred, and so on.
NSBundle's -localizations method returns an array of all available localizations within a
bundle. The +preferredLocalizationsFromArray: class method returns an ordered array of
localizations based on the user's preferences.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

File System Access

File system access is one of the most common aspects of application development. Mac OS X includes
file systems and APIs from Unix as well as the traditional Mac OS. The Foundation framework
provides classes that encapsulate file system differences. An application written using the Foundation
framework seamlessly accesses all of the available file systems on Mac OS X and can even access
Windows file systems via Mac OS X's built in network file system support. All file system differences
are hidden within the implementation of the Foundation framework.

In Mac OS X, the classes of the Foundation framework partially support features unique to Apple's HFS
+ file system. The integration of the long-standing Unix file system support and the traditional Mac file
system conventions is not yet complete in OS X version 10.1.3. As a result, many operations specific to
the HFS+ file system must be accomplished using Apple's procedural Carbon APIs. However, most
common file system operations, and all operations that are similar between traditional Unix file systems
and HFS+, are supported by classes in the Foundation framework.

NSFileHandle

The NSFileHandle class encapsulates files and communications channels regardless of their
underlying implementation. NSFileHandle is the public interface of a class cluster. Private
subclasses of NSFileHandle are optimized for different operations.

Instances of NSFileHandle are initialized to use an existing file descriptor using the -
initWithFileDescriptor: method. File descriptors are a Unix convention. Standard POSIX
APIs exist to open files and communications channels for reading, writing, or both. When opened, the
file descriptor for the file or communications channel is used with NSFileHandle. NSFileHandle
takes care of closing the file descriptor when appropriate.

On Mac OS X, NSFileHandle's convenience allocators +fileHandleForReadingAtPath:,

+fileHandleForWritingAtPath:, +fileHandleForUpdatingAtPath:,
+fileHandleWithStandardError, +fileHandleWithStandardInput,
+fileHandleWithStandardOutput:, and +fileHandleWithNullDevice: avoid the
need to use POSIX procedural APIs directly. These methods completely hide differences between file
systems. The paths passed as arguments to these methods are usually obtained from a NSBundle
instance's -pathForResource:ofType: method. Paths are also constructed using NSString's
path related methods such as -stringByAppendingPathComponent: and functions within the
Foundation framework such as NSHomeDirectory() or NSTemporaryDirectory().

After an NSFileHandle instance is created, data is read or written using the associated file or
communications channel. In some cases, NSFileHandle enables random access to the contents of a
file. Files can be truncated, and it is possible to read or write to specific locations within a file.
NSFileHandle also works with communications channels such as pipes and sockets. Pipes are a
Unix mechanism for using the output of one program as the input for another. Sockets provide cross-
platform support for bidirectional network communications. The set of operations that work with a
NSFileHandle instance depends on the type of file or communications channel being used.
The Foundation framework provides many different ways to access file systems. For example, some
Foundation classes provide methods to directly write or read files. The -writeToFile:
atomically: method is implemented by NSArray, NSData, NSDictionary, and NSString
among others. NSFileHandle is a lower-level class that provides more flexible, but less convenient
access to files and their contents.

Data is read from a file that is handled by a NSFileHandle instance using the -
readDataOfLength: method. When -readDataOfLength: is called, data from the current
position within the file is read up to the specified length or the end of the file (whichever comes first).
To determine if all data has been read from a file, call NSFileHandle's -availableData method.
It returns YES if data is available and NO otherwise. However, if the NSFileHandle represents a
communications channel, the -availableData method will block until data becomes available.
That means an application cannot perform any more computations until data becomes available.

Blocking while waiting for data to become available is not usually acceptable in a Cocoa application.
When users see the "spinning beach ball" cursor indicating that an application is not responding to user
input, the usual cause is that the application is blocked waiting for data.

One solution for avoiding the "spinning beach ball" cursor is to perform file operations in a different
thread from the one that controls the user interface. The separate thread for I/O blocks without harm to
other threads. Multiple threads are sometimes the best solution, but they unavoidably make applications
more complex.

NSFileHandle is optionally used to implement asynchronous background communication without

the need to explicitly create multiple threads in an application. NSFileHandle's -
readInBackgroundAndNotify returns immediately. When data becomes available,
NSFileHandle sends the NSFileHandleReadCompletionNotification to the default
notification center. The notification includes the data read as an argument.

After receiving the NSFileHandleReadCompletionNotification, the object that received

the notification must call -readInBackgroundAndNotify again to receive more data. Data is
written to a file using NSFileHandle's -writeData: method. The current position in an open file
is changed with the -seekToFileOffset: method. Files are truncated with the -
truncateFileAtOffset: method. Finally, an open file is closed with the -closeFile method.

NSFileManager

The NSFileHandle class encapsulates operations on a specific open file or communications channel.
The NSFileManager class is used to manipulate file systems. NSFileManager encapsulates file
system management operations and abstracts many file system differences. By using
NSFileManager, an application manipulates the file system regardless of whether the file system is
based on Windows, Unix, or traditional Mac HFS+.

NSFileManager provides methods to create directories and change the current working directory.
NSFileManager is used to copy, move, delete, or link files and directories. The attributes of files and
directories are obtained and changed. The contents of files and directories can be read or compared.
Finally, file system links and aliases can be evaluated.
One key to the implementation of NSFileManager is that it manages conversions between
application string and file system string encodings. For example, if an attempt is made to create a file
with a Unicode name in a file system that does not support Unicode, the name is automatically
converted to an encoding suitable for the file system.

There is at least one instance of NSFileManager called the default manager in every Cocoa
application. The default manager instance is obtained with NSFileManager's +defaultManager
class method. The following example fills an existing mutable array with strings that each contain the
name of a file or directory in the current working directory:

void getNamesInCurrentDirectory(NSMutableArray *resultArray)

{
NSString *fileName;
NSFileManager *fileManager = [NSFileManager
defaultManager];
NSDirectoryEnumerator *enumerator = [fileManager enumeratorAtPath:
[fileManager currentDirectoryPath]];

while (nil != (fileName = [enumerator nextObject]))

{
[resultArray addObject:fileName];
}
}

NSFileWrapper

The NSFileWrapper class is part of the Application Kit framework and cannot be used by
Foundation framework applications that do not also use the Application Kit framework. Nevertheless, it
is worth mentioning here because it is closely related to the NSFileManager and NSFileHandle
classes. NSFileWrapper provides a higher level and more abstract representation of files than
NSFileHandle. NSFileWrapper is used with whole directories of files and provides high-level
capabilities that would otherwise be implemented using lower-level NSFileManager methods.

NSFileWrapper is described in Chapter 8. NSFileWrapper helps an application treat files and

whole directories of files as if they were all simultaneously present in the application's memory.
NSFileWrapper encapsulates operations on the files and information such as the icon associated
with a file. NSFileWrapper also synchronizes changes made to the portions of files stored in
memory and changes files on disk.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Defaults System

Mac OS X provides rich support for storage of user preferences and application defaults.
Traditional user preferences and defaults are both called defaults in Cocoa. Every user has
a defaults database which is created automatically. Defaults are stored in several different
domains. For example, a user can have defaults that apply to only one application or
defaults that apply to all applications run by the user. Defaults domains are accessed by
name. Mac OS X defines the following domains: argument, global, registration,
application, and languages. The first three are referenced in code using the
NSArgumentDomain, NSGlobalDomain, and NSRegistrationDomain constants
respectively. The application domain uses the application's bundle identifier as its name.
The languages domain uses the name of the user's preferred language as set in Preferences.
It is seldom necessary to access defaults domains explicitly by name because the
NSUserDefaults class uses domains automatically.

Values in each domain are stored in property lists that define dictionaries of key value
pairs. Because defaults are stored in property lists, only object types supported for use in
property lists can be stored. Types not directly supported are usually converted into
NSString or NSData instances for storage.

Standard keys are used in each domain. The domain used to store a default value depends
on the value's use. For example, the argument domain contains default values specified on
the command line when an application is started. Applications can add new keys and
values to any domain, but changes to the argument domain are not saved. When an
application looks up a default value, the domains are searched in the following order:
argument, application, global, languages, and registration. As a result, defaults stored in the
application domain supercede defaults stored in the global domain. Default values
specified on the command line supercede all other defaults. Default values are specified on
the command line and added to the argument by preceding a default name with a hyphen
and following it with a value. For example, adding the following argument to the command
line when launching a Cocoa application will change the default units of measurement used
by the application during that session:

-NSMeasurementUnit Inches

Even if the user's default value set with Apple's System Preferences application is
"Centimeters," running an application from the command line and specifying "Inches" will
supercede the default value for one execution session.

Apple's System Preferences application is used to graphically set many default values. In
addition, each application can contain its own user interface for setting default values in
any domain. Many default values such as default window positions are stored
automatically by the relevant classes. Finally, a command-line tool called defaults is
used to read or write default values. The following command typed into a terminal will set
the user's default measurement unit for all applications:

defaults write -globalDomain NSMeasurementUnit Centimeters

The dictionary for the argument domain is constructed from command-line arguments. In
contrast, the dictionary for the application domain is read from a property list of default
values stored for each user. Application defaults apply to just one application. Each
application can have different user specific default keys and values. Changes that an
application makes to application defaults are automatically stored in a user's defaults
property list when the application is quit.

The dictionary for the global domain is read from each user's defaults database. Default
values in this domain apply to all applications that a user runs. Values such as the default
units of measurement are usually set for all applications. The languages domain is also
stored in a persistent property list. The languages domain stores preferences that depend on
the user's preferred language. For example, the Foundation framework class,
NSCalendarDate, uses values stored in the languages domain to determine how dates
should be presented. Finally, the registration domain is used by applications to make sure
that every expected default value exists. Defaults in the registration domain are not saved.
When an application starts, it can initialize the values of all defaults that it requires to
factory settings in the registration domain. If a user has set the same default in any other
domain, the user's value is used. By setting all factory defaults in the registration domain
when an application starts, the code that uses default values in the rest of the application is
simplified. Using the registration domain eliminates the need to verify that a default value
exists before each time it is used.

NSUserDefaults

The NSUserDefaults class encapsulates all operations involving Mac OS X's defaults
domains. A single shared instance of the NSUserDefaults class is obtained by calling
the +standardUserDefaults class method. The standard user defaults instance is
created and initialized with all the user's default values from all the standard domains. The
default values are cached to minimize the number of times the defaults database is accessed
on disk.

To obtain the default value associated with a particular key, send the -objectForKey:
message to the standard user defaults instance. The following function returns a string
containing the user's preferred currency symbol:

NSString *GetPreferredCurrencySymbol()
{
return [[NSUserDefaults standardUserDefaults]
objectForKey:@"NSCurrencySymbol"];
}

A dictionary of all default values in effect is obtained by calling the standard user defaults
object's -dictionaryRepresentation method. The returned dictionary contains
key value pairs from all the domains. Values set in domains that are searched first
supercede values set in lower priority domains.

Apple's online documentation for the NSUserDefaults class provides a partial list of
default keys such as the NSCurrencySymbol key. Many others are used by Cocoa
applications but aren't documented anywhere. For example, the NSWindowResizeTime
key changes the number of seconds used to animate window resizing in Cocoa
applications. Valid values are greater than 1.0. One reason that Apple has not documented
many default keys might be that they are considered part of private APIs or deprecated
APIs. There is no guarantee that undocumented keys will continue to work in new versions
of Mac OS X.

Set default values by calling the -setObject:forKey: method of

NSUserDefaults. When a default value is changed programmatically in a running
application, the NSUserDefaultsDidChangeNotification is posted to the
default notification center. Observers of this notification can check the defaults dictionaries
to determine what changed. Apple's online documentation provides an example of an
application domain default for setting whether backup files should be automatically deleted.

Use the -synchronize method of NSUserDefaults to copy any values set

programmatically into to defaults database on disk. The -synchronize method is called
automatically when an application quits. There is no reason to call -synchronize
explicitly in application code unless changed values need to be saved prior to the automatic
save that occurs when the application quits. The +resetStandardUserDefaults
class method invalidates previously cached default values. The next time
+standardUserDefaults is called, the returned instance contains only the default
values actually stored in the user's defaults database on disk. Code for an application-
specific preferences panel can call +resetStandardUserDefaults to reset all
default values to the ones stored on disk.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Notifications

Notifications are a flexible mechanism that enables multiple objects to communicate with
each other without tightly coupling the objects together. An object called a notification
center is used to register objects that need to be notified under certain circumstances. The
objects registered to receive notifications are called observers. When objects post
notifications with the notification center, the notification center distributes the posted
notifications to interested observers by sending Objective-C messages to them. The
notifications design pattern is described in Chapter 6.

The observers know about the notification center, but don't need to know anything about
the objects that post notifications. The objects that post notifications don't need to know
which objects, if any, observe the notification. The objects that post notifications and the
observing objects are decoupled.

NOTE

As a general design goal, coupling between classes should be avoided.

Another term for coupling is dependency. Coupling reduces the reusability of
objects. Coupling makes designs inflexible and difficult to maintain.

Any number of objects can be observers for any notification. Any number of objects can
post notifications. Notifications enable extremely flexible application designs. For
example, when objects and resources are dynamically loaded into an application, the
NSBundleDidLoadNotification is sent to registered observers. The observers
might use the notification to gain access to the loaded resources or send messages to the
loaded objects. The key is that the NSBundle class used to dynamically load objects and
resources is not modified in each application that uses it. Instead, application specific logic
is implemented in the objects that observe the notification. NSBundle is reusable and
does not have dependencies on objects in particular applications, and applications can still
perform specific processing when a bundle is loaded.

Many Foundation framework classes post notifications. Notifications posted by

NSBundle, NSFileHandle, and NSUserDefaults classes have already been
mentioned in this chapter. Notifications are also used extensively in the Application Kit
framework. Notifications are posted in many situations including when a window is closed
or an application has finished launching.

NSNotificationCenter
Instances of the NSNotificationCenter class enable communication between
objects that don't know about each other. NSNotificationCenter instances receive
posted NSNotification instances and distribute them to appropriate observer objects.

Every Cocoa application contains at least one instance of NSNotificationCenter

called the default notification center. The default notification center is obtained using the
NSNotificationCenter's +defaultCenter class method. Most notifications
posted by Foundation framework and Application Kit framework objects are posted to the
default notification center.

An application can contain any number of NSNotificationCenter instances.

Specialized communication between custom objects in an application might use
notification centers created just for that purpose, but most application needs are met by the
default notification center.

Notifications are posted by calling the -postNotification: method of an

NSNotificationCenter instance such as the default notification center. The
argument to -postNotification: is a NSNotification instance. The
NSNotification class is described in this chapter. The -
postNotificationName:object:userInfo: method is used to indirectly create
and post an NSNotification instance. The first argument is the notification name. The
second argument is the object posting the notification. The third argument is a dictionary
that is passed as an argument when observers are notified.

Objects register as observers for particular notifications based on several criteria. The
standard way to register for a notification is to call NSNotificationCenter's -
addObserver:selector:name:object: method. The first argument is the object
that will observe notifications. The second argument is a selector that identifies the
Objective-C message that is sent to the observer when an appropriate notification is posted.
The selector must specify a method that takes one argument. The third argument is the
name of the notification that is being observed. If the third argument is nil, the observer is
registered to receive all notifications posted by the object specified in the fourth argument.
The fourth argument is an object that posts notifications and can be used to restrict the
notifications received by the observer to only those notifications posted by the specified
object. If the fourth argument is nil, all notifications with the specified name are observed.

The method called to notify an observer must have exactly one argument. The argument is
the userInfo dictionary that is provided when a notification is posted. The userInfo
dictionary can contain any objects and must be interpreted based on the notification being
received.

Notification centers do not retain the observer objects. When an object registered to
observe notifications is deallocated, it must remove itself from all notification centers.
NSNotificationCenter's -removeObserver: method removes a specified
observer completely, no matter how many notifications are being observed. The -
removeObserver:name:object: method is used to selectively remove a registered
observer for a particular notification or notification posting object.

NOTE

The Foundation framework provides the

NSDistributedNotificationCenter class to enable notifications
between objects in different applications. Notifications can be delayed or
queued with the NSNotificationQueue class so that multiple redundant
notifications are coalesced and sent to observers only once.

NSNotification

NSNotification instances store a name that identifies the notification, a reference to

the object that posted the notification, and a dictionary that is passed as an argument to the
methods registered by observers of the notification.

NSNotification instances are created with the +notificationWithName:

object:userInfo: convenience allocator and posted with a notification center.
Notifications are also indirectly created by NSNotificationCenter's -
postNotificationName:object:userInfo: method. The only reason to create
instances with +notificationWithName:object:userInfo: is to keep an
instance around so that it can be posted multiple times with exactly the same name,
object, and userInfo dictionary.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Related Core Foundation

With the release of Mac OS X, Apple has extended and documented much of the low-level code used to
implement the Foundation framework. The code is included in a standard C library that Apple calls Core
Foundation. The Core Foundation library consists of a set of procedural APIs and data structures that can be used
from Cocoa or Carbon applications. In some cases, Foundation framework classes are internally implemented
using Core Foundation functions. In other cases, there is effectively no difference between Core Foundation data
structures and corresponding Foundation framework objects. Such objects are said to be "toll free bridged,"
meaning that Core Foundation just provides a procedural API for accessing objects.

One toll free bridged object is NSString. Core Foundation defines a data structure called CFStringRef and a
set of C functions for manipulating CFStringRefs. In fact, CFStringRef and a pointer to NSString are the
same and can be safely cast from one to the other. In the following example, a CFStringRef is created and
initialized. Then it is further manipulated using Objective-C messages. Finally, the NSString pointer is cast
back to CFStringRef.

CFStringRef authorNames = CFSTR("Scott Anguish, Erik Buck, Don

Yacktman");
CFStringRef credits;

credits = (CFStringRef)[@"Authors: " stringByAppendingString:

(NSString *)authorNames];

Not all Core Foundation data types that seem to be toll free bridged to a Foundation object actually are.
CFArray, CFCharacterSet, CFData, CFDate, CFDictionary, CFRunLoopTimer, CFSet,
CFString, and CFURL are toll free bridged to NSArray, NSCharacterSet, NSData, NSDate,
NSDictionary, NSTimer, NSSet, NSString and NSURL, respectively. Other Core Foundation types might
be used in the implementation of Foundation objects or might be completely unrelated. In either case, they cannot
be used interchangeably with the Foundation framework objects that have similar names.

Parts of the implementation of Core Foundation are available in source code as part of Apple's open source
Darwin project. Several data structures that are supported by Core Foundation have no equivalent in the
Foundation framework. The CFBinaryHeap type stores values sorted using a binary search algorithm and
implements priority queues. The CFBitVector data type can be used to efficiently store large numbers of
Boolean values. The CFTree data type implements a tree data structure. CFStorage uses a balanced tree to
provide O(log n) or faster access to arrays of arbitrary but uniformly sized data structures.

The open source CFSocket functions can be used instead of standard Unix socket functions to abstract potential
differences between operating systems. Unix sockets might not be available on all platforms that support Core
Foundation in the future. CFSocket can be implemented using the native interprocess communication API on
each target platform.

CFBundle and CFPlugIn provide similar features to the NSBundle class, but neither is toll free bridged to
NSBundle. CFURL and CFURLAccess provide platform independent ways to read and write files and other
resources from remote machines. CFPreferences provides a procedural API for accessing the keys and values
stored in a user's defaults database. CFPreferences is not bridged to NSUserDefaults. CFUUID is used to
produce universally unique 16-byte identifiers. The same identifier will not be produced twice regardless of the
platform or machine. CFUUID provides features similar to the NSProcessInfo class's -
globallyUniqueString method defined in the Foundation framework. CFUserNotification provides
procedural access to notifications and enables the registration of call back functions that are called when a
notification is posted. CFPropertyList provides procedural access to property lists. CFMessagePort and
CFMachPort wrap low-level Mach messaging and interprocess communication.

Core Foundation contains data types and functions for reading and extracting data from XML documents.
CFXMLParser and CFXMLNode are used together to procedurally manage nonverified XML structured
documents. CFXMLParser is used to read XML property lists including the user defaults database.
Book: Cocoa® Programming
Section: Chapter 7. Foundation Framework Overview

Summary

This overview could hardly cover every topic of interest regarding the Foundation
framework. The information provided in this chapter conveys the breadth of classes
available and indicates where to look for more information. It identifies the practical
implications of some Cocoa conventions including the ideas of mutability, immutability,
and class clusters. Many of the public Foundation classes are abstract interfaces to class
clusters, and that fact can have huge impacts on their use. Additional classes such as
NSHost and NSProcessInfo, exist but are not described in this overview. Such classes
are indispensable in certain circumstances, but are seldom used in practice. Before writing
code, be sure that there is no existing Foundation class or function to solve the problem.

The next chapter provides an overview of the Application Kit framework that is built on
top of the Foundation framework. Just as the Foundation framework provides a foundation
for all Cocoa applications, the Application Kit contains the classes needed for graphical
applications and graphical user interfaces. Neither this chapter nor the next contains the
kind of in-depth information needed to really unleash the power of the frameworks. These
chapters are truly overviews. The information introduced is expanded throughout the rest
of this book in examples and explanations, but the conceptual grounding provided in this
chapter and the next provide an essential foundation.
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 8. The Application Kit Framework Overview

IN THIS CHAPTER

● Events and the Run Loop

● Responders
● NSApplication Overview
● NSWindow Overview
● NSView Overview
● Delegates
● Target-Action Paradigm
● Archived Objects and Nibs
● NSWindowController Overview
● Multidocument Applications
● Undo and Redo
● Menu Validation
● Spell Checking

The Application Kit contains most of the classes that provide user interfaces and graphics
for Cocoa applications. The Application Kit uses the Foundation framework extensively,
and is very large. Much of the rest of this book is dedicated to unleashing its power. This
chapter focuses on the key concepts and techniques employed to provide Cocoa user
interfaces. These key concepts might be unfamiliar even to experienced developers
accustomed to other user-interface toolkits. The Application Kit takes advantage of the
dynamic nature of Objective-C and the Foundation framework to implement an extremely
flexible and powerful framework of cooperating classes.

The information presented in this chapter is essential for understanding how to use the
Application Kit and how the pieces fit together. It is often necessary to recognize the
interaction of multiple classes to use the kit effectively. This chapter presents the big
picture architecture of the Application Kit, the key classes, and details of a few key
concepts used to implement the Application Kit. This chapter covers broad concepts and
does not provide enough information to make effective use of most Application Kit
features. It can be difficult to understand a complex framework when too many details are
provided up front. There is always the danger of not seeing the forest because of all the
trees. The Application Kit provides many classes to implement core concepts, and the
classes interoperate in ways that are difficult to see without a big-picture overview. This
chapter provides the big picture at the expense of details.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Events and the Run Loop

Most graphical user interface toolkits, including the Application Kit, use an event-driven
model. That simply means applications react to events that are sent to the application by
the operating system. The events can result from the user typing on a keyboard, or moving
a mouse. Timer events can be sent at periodic intervals. The arrival or availability of any
new data from a monitored input source is also conceptually an event.

Cocoa applications receive events from the operating system with the help of the
NSRunLoop class. Every Cocoa application contains at least one instance of the
NSRunLoop class. A run loop is created automatically for each thread in the application.
In most cases, the programmer does not need to access the run loop directly. The run loop
for each thread monitors input sources that are part of the operating system. If no
monitored input sources have available data, the run loop does not consume CPU
resources. In other words, the run loop blocks on pending I/O.

When data becomes available, the run loop recognizes the new data as an event and sends
Objective-C messages to various objects notifying them of the event. The receivers of the
messages and the messages that are sent depend on the type of data that becomes available.

The purpose of the run loop is to enable efficient communication between the operating
system and an application. The implementation of the NSRunLoop class is platform
specific. The implementation for Mac OS X uses Mach ports and the Unix select()
function to detect and manage I/O. NSRunLoop abstracts the differences between various
operating systems. If Apple ever renews cross-platform support for Cocoa technology, the
NSRunLoop class will certainly be reimplemented for each platform.

Application code seldom interacts with the run loop directly. Many user interface toolkits
make the run loop a key focus for developers, but in Cocoa, the run loop plays a minor role
in an application. Graphical Cocoa applications wrap the functionality of the NSRunLoop
class within the NSApplication class. One of the purposes of the NSApplication
class is to manage the run loop on behalf of the entire application. The NSApplication
class is a key component of the Application Kit's architecture, and is described in this
chapter.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Responders

When keyboard events, mouse events, timer events, or other events are detected by the run
loop and the NSApplication instance that manages the run loop, those events are
converted into instances of the NSEvent class and dispatched to other objects using
Objective-C messages. The use of messaging is an important difference from other user
interface toolkits and results in much of the power and flexibility of Cocoa. The
Application Kit does not use C-language switch statements or explicit tables of function
pointers. The messaging capabilities built into the Objective-C runtime are ideally suited to
event dispatching.

An object that can receive event messages is called a responder. Figure 8.1 illustrates the
relationships and communications between the operating system, the run loop, an instance
of the NSApplication class, and a responder.

Figure 8.1. The operating system, the run loop, an instance of the NSApplication
class, and a responder interact.

What Is a Responder?

Cocoa encapsulates the role of responders within the NSResponder class.

NSResponder is an abstract class. Abstract classes are not intended for direct use by
application programmers. Instead, abstract classes provide functionality that is used by
subclasses. NSResponder provides the foundation on which some of the most prominent
Cocoa classes are built. Subclasses of NSResponder include NSView, NSWindow, and
NSApplication. These subclasses collaborate to manage the flow of events within an
application.

The collaboration between the various subclasses of NSResponder within a Cocoa

application is so powerful that many applications can be written without any custom event
handling code at all. The event processing within the Application Kit framework takes care
of almost all events automatically.
When application-specific, custom-event handling is needed, one or more of
NSResponder's event-processing methods can be overridden in a subclass. For example,
to perform processing in response to a mouse button-press event, override
NSResponder's -mouseDown: method.

Each of NSResponder's event-processing methods accepts a single argument, which is

an instance of the NSEvent class. Within the event processing methods, the NSEvent
instance can be interrogated to obtain more information about the event such as the
location of the mouse or which modifier keys were pressed. The NSEvent class
documentation describes all the information obtainable.

The following event-processing methods are declared in the NSResponder class:

- (BOOL)performKeyEquivalent:(NSEvent *)theEvent;
- (void)mouseDown:(NSEvent *)theEvent;
- (void)rightMouseDown:(NSEvent *)theEvent;
- (void)otherMouseDown:(NSEvent *)theEvent;
- (void)mouseUp:(NSEvent *)theEvent;
- (void)rightMouseUp:(NSEvent *)theEvent;
- (void)otherMouseUp:(NSEvent *)theEvent;
- (void)mouseMoved:(NSEvent *)theEvent;
- (void)mouseDragged:(NSEvent *)theEvent;
- (void)scrollWheel:(NSEvent *)theEvent;
- (void)rightMouseDragged:(NSEvent *)theEvent;
- (void)otherMouseDragged:(NSEvent *)theEvent;
- (void)mouseEntered:(NSEvent *)theEvent;
- (void)mouseExited:(NSEvent *)theEvent;
- (void)keyDown:(NSEvent *)theEvent;
- (void)keyUp:(NSEvent *)theEvent;
- (void)flagsChanged:(NSEvent *)theEvent;

These methods are presented here to provide a sense of the range of methods available. The
uses for each of NSResponder's event processing messages are described in the class
documentation for NSResponder. Many of the methods are used and described in
examples within this chapter and the rest of this book.

The NSEvent passed to each event-processing method is only valid within that method's
implementation. The Cocoa frameworks reserve the right to reuse existing NSEvent
instances or otherwise tamper with their contents. To preserve the information in an
NSEvent instance, copy it or store the information in a separate data structure. Simply
retaining the NSEvent instance for later use is not sufficient.

The Responder Chain

Each instance of the NSResponder class stores a pointer to another instance of

NSResponder called the next responder. NSResponder provides methods for setting
and getting the next responder. Responders are chained together from next responder to
next responder, and form a data structure called the responder chain. If an instance of
NSResponder does not process a message that it receives, the message can be passed on
to the next responder. The message travels along the chain until the message is processed
or there is no next responder. Figure 8.2 shows event message processing including the
responder chain.

Figure 8.2. Event message processing includes the responder chain.

The responder chain plays a crucial role in applications that use the Application Kit. Many
powerful features such as automatic menu validation, context sensitive menus, text entry,
and automatic spell checking depend on the responder chain. The responder chain also
provides opportunities for programmers to insert context-sensitive custom logic and event
handling into applications. The responder chain is Cocoa's implementation of the "Chain of
Responsibility" design pattern described in Chapter 6, "Cocoa Design Patterns."

The First Responder

The responder that gets the first chance to respond to an event message is called the first
responder. The first responder is the first link in the responder chain. One of the keys to
using the responder chain is the understanding of which responder will be the first
responder in any circumstance. The first responder determines the chain that a message
follows.

The responder chain and the first responder are managed by three NSResponder
subclasses: NSApplication, NSWindow, and NSView. Applications contain exactly
one instance of the NSApplication class, and that instance receives events from the
operating system. The events are either sent on to a window represented by an NSWindow
instance or consumed by the application object itself. Every window in an application
stores a pointer to a first responder. The first responder for a window can change based on
user actions or program code. The initial first responder in each window can be set in
Interface Builder or through a NSWindow instance method. Sometimes the first responder
for a window is the window itself. When a window receives an event from the application
object, the event is either forwarded to a responder within the window or consumed by the
window itself. The responders within a window are typically instances of NSView
subclasses.

The first responder to receive an event message depends on the application object, the
window that is most appropriate for the event, and a responder (view) within the window.
Figure 8.3 expands the diagram of event-message processing to include windows and the
responders within the windows.

Figure 8.3. The first responder to receive an event message depends on the application
object, a window, and the responders within the window.

The programmatic way to change a window's first responder is to call NSWindow's -

makeFirstResponder: method passing the responder that should become the new
first responder as the argument. A sequence of messages are automatically sent when the
first responder is changed via -makeFirstResponder:. First, the -
resignFirstResponder message is sent to the current first responder asking it to
accept the change in its status. If the current first responder returns NO, the first responder
is not changed. If the current first responder returns YES from -
resignFirstResponder, the argument to -makeFirstResponder: is sent a -
becomeFirstResponder message. If the object that receives the -
becomeFirstResponder message returns NO, the window that received the -
makeFirstResponder: becomes the first responder.

Different types of events are dispatched to different first responders. For example, the first
responder to receive an event message might be different for keyboard events and mouse-
click events. The full implications of the first responder and the responder chain cannot be
described without more information about the NSApplication, NSWindow, and
NSView classes. In this chapter there is an overview of each of these classes which
includes information about their roles in the responder chain.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

NSApplication Overview

Each Application Kit-based application contains a single instance of the

NSApplication class that extends the event handling capabilities of NSResponder to
communicate with the operating system. NSApplication is a subclass of
NSResponder and is implemented as a shared object or Singleton as described in
Chapter 6, "Cocoa Design Patterns." The shared instance can be accessed with
NSApplication's +sharedApplication method or through the NSApp global
variable provided by the Application Kit framework.

NSApplication provides the interface between an application and the operating system.
The NSApplication instance manages a run loop that receives events from the
operating system. NSApplication converts events into instances of the NSEvent class
and sends the events to responders. The NSApplication object also maintains the
application's connection to the operating system for drawing, scripting, and notification of
system-wide events such as the launch of other applications or the pending shutdown of the
computer.

NSApplication stores the application's icon, manages all the application's windows,
and provides access to the application's menus. NSApplication implements the
standard behaviors of Mac OS X applications automatically. As a result, Cocoa
applications behave consistently. Applications obtain many powerful features for free by
using the NSApplication class.

The NSApplication class is seldom subclassed. Instead, the behavior of an application

can be modified through the use of an application delegate and notifications. Delegation is
a powerful technique that is described in the Delegation Versus Notifications section later
in this chapter and also in Chapter 6.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

NSWindow Overview

The NSWindow class is a subclass of NSResponder and extends the capabilities of

responders to provide an area of the display for drawing as well as aid event dispatching. In
Cocoa applications, every window onscreen is an instance of the NSWindow class or one
of its subclasses such as NSPanel. A window is needed to display the output from an
application on the display.

Windows are composed of three major parts: an optional title bar, the content view, and an
optional resize control. Figure 8.4 indicates the parts of a window. The title bar might
contain a title and controls to minimize, maximize, or close the window. The window
automatically manages these controls. The application can be notified when one of the
controls is activated, but the controls are not directly accessible from within a Cocoa
application. The resize control is also managed automatically by the window itself. Every
window has a content view. The content view is the portion of a window that is controlled
by code unique to each application.

Figure 8.4. Windows are composed of an optional title bar, an optional resize control,
and a content view.

Windows have a position and size onscreen. The position that is stored is the lower-left
corner of the window, and it is stored as integer coordinates corresponding to pixels on the
display. The size is stored as the integer width and height of the window in pixels.

Windows uses the NSApplication object's connection to the operating system to draw
onscreen. The pixels drawn by a window are stored in memory that can be shared by the
operating system and the window. Because the operating system has direct access to the
memory, the operating system can move and uncover windows without intervention by the
application that owns the window. For example, a window can be dragged while the
application that owns it is busy performing other computations. The shared memory is also
used by the operating system to implement transparency effects.

Backing Store

The shared memory is called the backing store for the window. The Application Kit
supports three different configurations for backing store: buffered, retained, and
nonretained.

Buffered backing store is the default. With buffered backing store, all pixels of the window
are stored once in a buffer drawn by the window and again in a separate buffer used by the
operating system. The pixels drawn by the window are copied or "flushed" into the buffer
used by the operating system automatically. This style of buffering is often called double
buffering because two separate buffers are used. Buffered windows provide the best
presentation to users. Users do not see any partial drawing or delayed updates because the
pixels of a window are not displayed until the window has been completely redrawn. The
disadvantage of buffered windows is that they require memory to store two buffers.

Retained backing store uses one buffer to store the visible pixels of a window and a
separate buffer to store pixels that are offscreen or obscured by other windows. Retained
backing store uses less memory than buffered backing store because each pixel is only
stored in one buffer. When a window is moved to reveal pixels that were formerly
obscured, the operating system can transfer the pixel data from one buffer to the other
without intervention by the application that owns the window. However, partial drawing of
the portions of a window that are visible onscreen may be seen by users. Retained backing
store is a compromise between memory usage and the quality of presentation to users.

Nonretained backing store uses only one buffer. Pixels that are not visible are just
discarded. Nonretained backing store uses the least memory and provides the worst
presentation to users. Each time the window is redrawn, users see partial drawing. If an
area of the window that was obscured becomes visible, the application that owns the
window must be alerted to redraw the newly visible pixels. If the application is busy with
other computations and is not multithreaded, the user might see delays between when the
window is uncovered and when it is redrawn. Use of nonretained backing store is
discouraged.

NOTE

In many versions of Mac OS X, including version 10.1, only buffered

backing store is supported. Apple might restore support for other backing
store types in future releases.
The backing-store type for each window can be set in Interface Builder or
programmatically. The backing store type is set when a window is initialized and via
NSWindow's -setBackingType: method.

Key Window and Main Window

The NSApplication class manages all the windows in an application. In addition to a

list of all the application's windows, NSApplication also keeps track of which window,
if any, is the key window and which is the main window. The key window and the main
window are the windows in which the user is currently working. The key window receives
keyboard events. The main window is the window that is effected by actions in the key
window. The key window and the main window are usually the same, but in some cases
they might be different. Figure 8.5 shows a typical situation in which the key window and
the main window are different. In Figure 8.5, the Find panel is the key window because
keyboard events are only sent to the key window and the user must be able to type the
string to find into the Find panel's text field. The README.rtf window is the main window
and contains the text that is searched. The user's actions in the Find panel are applied to the
contents of the main window. The Untitled window is neither key nor main.

Figure 8.5. An application with separate key and main windows as well as a window
that is neither key nor main.
The key window and main window have opaque window title bars. All other windows have
translucent title bars. The key window is the only window to which keyboard events are
sent.

Windows become the key window and main window automatically as the result of the user
actions. If the main window and key window are different, the main window becomes key
if the current key window is closed or minimized. In most cases, the user can make a
window become the key by clicking the mouse within the window. Application developers
can prevent a window from becoming the key window by subclassing NSWindow and
overriding NSWindow's -canBecomeKeyWindow method to always return NO.
However, NSWindow is seldom subclassed for this purpose because the NSPanel class
already provides the desired behavior when configured as a utility window in Interface
Builder. A window can also be made the key or main window by calling NSWindow's -
makeKeyWindow or -makeMainWindow methods, respectively. The -
makeKeyAndOrderFront: method is available to make a window the front-most or
topmost window, and also the key window in one operation.

Windows in the Responder Chain

NSWindow is a subclass of NSResponder and can be part of a responder chain. The role
that a window plays in the responder chain depends on the state of the application that
owns the window. Windows are also integral to event distribution. Most events received by
the application are sent on to a window. NSApplication selects the window to receive
an event based on the type of the event.

Events outside the window's content view are handled automatically by the window. No
programmer intervention is required to resize windows or manage the controls in the
window's title bar. The NSWindow class handles all those details automatically and
notifies the application of any changes so that the application can perform operations such
as constraining the window's size or saving the contents of the window before it closes.

Mouse-down and mouse-move events are sent from the application object to the top-most
window under the mouse pointer. The NSWindow class then distributes received mouse
events to a responder within the window, or consumes the events itself. Mouse-up and
mouse-drag events are sent to the window that received the corresponding mouse-down
event. The window sends the mouse-up and mouse-drag events on to the same responder
that received the mouse-down event. Keyboard events are sent to the first responder in the
key window
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

NSView Overview

The NSView class extends the event-handling capabilities of NSResponder to enable

drawing and printing. NSView is an abstract class meaning that instances of NSView are
seldom used directly. Instead, many subclasses of NSView exist to implement particular
combinations of event handling and drawing behavior. Almost everything drawn in a
Cocoa application is drawn by a subclass of NSView. For example, buttons, text fields,
sliders, and even the backgrounds of windows are directly or indirectly subclasses of
NSView. The most prominent subclasses of NSView include NSControl, NSText,
NSTabView, NSSplitView, NSScrollView, and NSBox.

The NSView class cannot draw without the help of a window. When a view is drawn, it
writes the data for pixels into memory. A window is needed to provide the memory that
stores the pixel data. NSWindow and NSView cooperate to implement user interfaces.
Every NSWindow instance has at least one associated NSView instance called the content
view. The content view is used to draw the content of the window.

View Hierarchy

Views exist in a hierarchy. A view can contain any number of subviews. Views are
normally added to the content of a window by making them subviews of the window's
content view. Each view has a reference to the view that contains it. The reference to the
containing view is called the superview. Complex user interfaces are composed of many
views arranged in a hierarchy of superviews and subviews. Figure 8.6 shows a
representative user interface composed of a window, the window's content view, and
subviews within the content view. The hierarchy of nested views in the window on the
right is shown on the left.

Figure 8.6. Views exist in a hierarchy in which views contain subviews.

Subviews are always drawn after their superview resulting in subviews always appearing
on top of their superview graphically. Views clip their subviews so that no part of a
subview can be drawn outside its superview. The order in which views with the same
superview are drawn is not defined. As a result, sibling views should not be overlapped. If
they are overlapped, changes in drawing order could result in incorrect display.

Each view can have its own coordinate system. By default, a window's content view has its
origin in the lower-left corner, and has a width and height equal to the width and height of
the window's content area in pixels. The positive-X axis is to the right, and the positive-Y
axis is up. Views store two rectangles to define both the area of the view in its superview's
coordinate system, and the area of the view in its own coordinate system. The area of a
view in its superview coordinate system is called its frame. The same area stored in the
view's coordinate system is called the bounds. Figure 8.7 depicts the relationship between a
view's frame and its bounds.

Figure 8.7. A view's frame is stored in its superview's coordinate system, and its
bounds are stored in its coordinate system.
The view's frame, its bounds, and a transformation matrix define the coordinate system
used by a view. The coordinate systems used by views are described in detail in Chapter
13, "Custom Views and Graphics Part II."

Views in the Responder Chain

As a subclass of NSResponder, NSView instances participate in the responder chain.

Most responders in an application are actually subclasses of NSView. The next responder
of a view is usually the view's superview. Arbitrary responders can be added to the
responder chain by calling NSResponder's -setNextResponder: method, and that
technique can be used to insert responders in the responder chain between a view and its
superview. If an event-processing message is sent to a view that does not handle the
message, the message is sent to the view's next responder and its next and so on until the
window's content view, the ultimate superview of all views in a window, receives the
message. Figure 8.8 shows a view hierarchy in which a text field is the first responder. The
responder chain, up to the window object, is depicted with arrows.

Figure 8.8. A responder chain consisting of views within a window is depicted.

The first view to receive an event-processing message depends on the type of the event.
The first mouse-down event within a window that is not the key window is usually
consumed by the window itself to make the window into the key window and bring it to the
front. This behavior can be modified in several ways. For example, a subclass of NSView
can override the -acceptsFirstMouse: method to return YES, meaning that it uses
the first mouse click in an inactive window.

NSWindow sends mouse-down and mouse-move event messages to the top-most view
under the mouse. Subviews are drawn after their superview. The top-most view under the
mouse is, therefore, usually the most deeply nested view under the mouse. Mouse-move
events occur frequently and are seldom used. NSWindow does not send mouse move event
messages to views by default. If a subclass of NSView needs to receive mouse-move
events, it must tell NSWindow to send them. NSWindow's -
setAcceptsMouseMovedEvents: method is used to tell the window to send mouse-
move event messages to views. Mouse-drag and mouse-up event messages are sent to the
view that received the corresponding mouse-down event. Keyboard event messages are
sent to the first responder within the window.

The NSView class implements the -acceptsFirstResponder method to always

return NO. As a result, most views never become the first responder within a window.
Subclasses of NSView that implement text processing or allow the user to make selections
usually override the -acceptsFirstResponder method to return YES. If a view
accepts becoming the first responder, the first mouse-down event within the view
automatically makes that view the first responder, unless the current first responder refuses
to resign its status.

Details of handling events in subclasses of NSView are provided in Chapter 15, "Events
and Cursors." The information presented here is just an overview to describe the roles of
views in the Application Kit. Applications often include one or more custom subclasses of
NSView. The NSApplication, NSWindow, and NSView classes cooperate and form
the core of the Application Kit architecture. A detailed understanding of NSView and its
relationships with other classes is needed to unleash the power of Cocoa.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Delegates

Delegates and delegate methods are used throughout the Application Kit. Delegates
provide an alternative to subclassing when the behavior of classes must be refined to meet
an application's needs. Application Kit classes such as NSApplication, NSWindow,
NSBrowser, and NSMatrix are seldom subclassed. Delegation enables all the
customization that most applications need.

A delegate is an object that is able to influence the behavior of another object by

responding to delegate messages. A class that uses a delegate has a delegate instance
variable and defines a number of delegate methods. An instance of that class sends delegate
messages to its delegate for help deciding how to behave. For example, the NSWindow
class has a delegate and declares the -windowShouldClose: delegate method. Before
a window closes, the window sends the -windowShouldClose: message to its
delegate. If the delegate returns NO, the window does not close.

The object that acts as a window's delegate might implement -windowShouldClose:

to determine if a document represented by the closing window has been edited, and if so
give the user a chance to save the changes or cancel the close. If the user cancels the close
then -windowShouldClose: returns NO, and the window does not close.

Delegates are not compulsory, nor do they have to implement all delegate methods that
might be called. If a delegate has not been set for an instance of NSWindow, the window
simply closes when the user clicks the Close button. If a delegate has been set, the window
checks to see if the delegate implements the -windowShouldClose: method. If the
delegate does not implement -windowShouldClose:, the message is not sent and the
window closes. The default behavior of the window is changed only if the window has a
delegate and the delegate implements the -windowShouldClose: method to return NO.

Delegates can be part of an extended version of the responder chain. The NSWindow and
NSApplication classes give their delegates a chance to handle messages that are sent
up the responder chain. This important use of delegates is described in this chapter as part
of the Target-Action paradigm.

Delegates can often be set within Interface Builder. Most classes that can have a delegate
also provide a -setDelegate: method. Delegate messages are documented at the end
of the online class documentation for each class that can have a delegate. Before attempting
to subclass an Application Kit object, make sure that the desired behavior cannot be
achieved with a delegate. Using a delegate is almost always preferred over subclassing.

Delegation Versus Notifications

Delegation is a powerful and dynamic feature of Cocoa. Delegation and notifications as
described in Chapter 7, "The Foundation Framework Overview," are closely related. In
fact, many delegate methods accept a notification as an argument. Delegate messages and
notifications share many of the same benefits. Both decouple the sender of a message from
the receiver. Objects know very little about their delegates. The determination of the
messages that a delegate understands is made at runtime, just before the messages are sent.

The principal difference between a delegate and the receiver of notifications is that the
delegate can affect behavior that the receiver of notifications can only observe. Delegate
messages are sent directly to one object. Notifications are sent to a notification center that
forwards the messages to any number of observers. The return value, if any, from a method
that handles a notification is ignored. The returned values from methods that handle
delegate messages can often modify the sender's behavior.

Methods that handle notifications accept exactly one argument, and that argument is a
notification object. Delegate methods can have any number and type of arguments.
Notifications are inherently slower than delegate messages. Delegate messages take direct
advantage of the Objective-C runtime for fast dispatch. Notifications are processed through
a hash table to determine which objects should be notified in any given situation.

Specialization of Behavior and Coupling

One of the lauded virtues of object-oriented software design is the potential for code reuse
through specialization. The idea is that when a programmer tries to solve a new problem
she can start from an existing solution to a similar problem and "specialize" that solution to
solve the new one. Reusing all or part of someone else's work is better than starting from
scratch each time, and the capability to "specialize" facilitates code reuse.

The most-common technique for specializing and achieving code reuse is subclassing of
existing classes. Subclassing is arguably the most powerful and flexible way to specialize
behavior. Subclassing enables a programmer to directly modify practically any detail of the
behavior of the superclass. The code that is written in the subclass can be tightly integrated
with the superclass implementation. Often that tight integration is necessary or desirable.
Sometimes, however, loose integration and a loose coupling are better. Although
subclassing is a powerful reuse tool, it is ironic that subclassing can also increase one of the
most common obstacles to reuse, namely the unnecessarily tight coupling of code.

Delegation enables the specialization of a class without subclassing. The primary

advantages of delegation over subclassing are loose coupling and code partitioning
(modularization). The primary disadvantage of delegation is the sacrifice of some
flexibility and power. The following illustrates loose coupling.

In a multidocument application that displays Web pages, each page is represented onscreen
as a NSWindow instance that contains objects for displaying Web content. If the last open
window is closed, the user should be asked if the current Internet connection should be
closed. This can be handled by creating a class that implements the -
windowWillClose: delegate method, and using an instance of that class as the delegate
for each document window. NSWindow sends the -windowWillClose: message to its
delegate just before closing. The delegate can determine if the last window is being closed,
ask the user if the Internet connection should be closed, and close the connection if the user
agrees.

The use of delegation in the example provides loose coupling in the following ways.
Knowing if the window that is closing is the last window requires knowledge of (coupling
with) all other open document windows. Knowing how to close an Internet connection
requires coupling with that subsystem. If the behavior is implemented by subclassing
NSWindow rather than using a delegate, the subclass is coupled to all other document
windows and the Internet-connection subsystem. With delegation, a class that already
knows about Internet connections can be used as the delegate of the windows. With
delegation, the NSWindow class does not need to be extended to know about the Internet
connection closing, and the class for managing Internet connections does not have to know
anything about the NSWindow class. It just has to respond to the -windowWillClose:
method.

The example also illustrates code partitioning. In the typical Model-View-Controller

partitioning, the NSWindow that represents Web documents is clearly part of the View
subsystem. The class that manages Internet connections is probably part of either the
Model or the Controller partitions. Extending the NSWindow class via subclassing creates
a class that is part of the View subsystem by virtue of being a window and simultaneously
part of the Model subsystem because it manages Internet connections. In most cases, an
object that acts as a delegate is part of the controller layer, acting as intermediary between
the model and the view. The Model-View-Controller system is described in Chapter 6, and
in Chapter 26, "Application Requirements, Design, and Documentation."

Delegation Versus Multiple Inheritance

Multiple implementation inheritance is not supported by Objective-C. Delegation can

eliminate one of the common arguments in favor of multiple inheritance. Consider a
subclass of NSTextView called MYSquiggleTextView for drawing squiggles under
words, and a class called MYSpeller that can check the spelling of a word. Using
multiple inheritance, a text view that draws squiggles under misspelled words can be
created by inheriting from both MYSquiggleTextView and MYSpeller.
Alternatively, an instance of MYSpeller can be attached to an instance of
MYSquiggleTextView as a delegate.

Using a delegate is a more powerful and flexible technique than the proposed multiple
inheritance. Subclassing requires a high degree of coupling. The delegate is loosely
coupled enabling the optional use of a MYEmphasiseTechnicalWords instance as a
delegate without any change to the MYSquiggleTextView class. There is no need to
create one subclass of MYSquiggleTextView just for technical-word emphasis and
another just for spelling emphasis. A user interface can even be provided so users can
dynamically change the reason for drawing squiggles.

Delegation results in sufficiently loose coupling that many instances of

MYSquiggleTextView can be specialized in different ways simply by having a
different delegate. If MYSquiggleTextView is subclassed in the future, the changes
need not affect either the MYSpeller or the MYEmphasiseTechnicalWords classes.
The classes can all change independently.

Delegation avoids a tendency toward combinatorial classes. Consider

MYSquiggleTextView mixed with MYScientificSpeller and
MYSquiggleTextView mixed with TheOtherGuysLegalSpeller. Similarly, mix
MYSpeller with an ordinary NSTextView, MYStraightUnderlineTextView, or
some other class. If the only technique available is subclassing, there will be an awful lot of
classes after a while.

Limitations of Delegation

The biggest limitation of delegation is that it is only possible if the need for specialization
has been anticipated. The developers at NeXT and Apple were able to anticipate that
programmers would want to do something special when a window is closed. They provided
the -windowWillClose: delegate method and many others. Had they not anticipated
the need, there would probably be no alternative but to subclass NSWindow. There are
limits to the extent a delegate method can change the behavior of a class. A subclass is free
to change anything.

Delegation and notification are two techniques pervasive in the Cocoa frameworks. Both
offer alternatives to subclassing, but operate at the level of instances rather than of classes.
Delegation typically allows one object to effect the behavior of another. Notification serves
as a mechanism for informing an arbitrary number of observers of the actions of another.
Delegation provides a means of specializing behavior without subclassing, and therefore
allows loose coupling between objects. This facilitates object reuse, and sidesteps one of
the common reasons for multiple inheritance.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Target-Action Paradigm

One of the most powerful features of the Application Kit is its use of the target-action
paradigm. Objective-C messages that have one object argument are called actions. The one
argument is usually the sender of the action message. A target is an object that can receive
action messages. Targets and actions can be defined programmatically or in Interface
Builder. The target-action paradigm is a key mechanism with which user interface elements
respond to user actions. The target-action paradigm is implemented with four parts, the
NSControl class, the NSActionCell class, the NSApplication class, and the
responder chain. User interface elements such as menu items, buttons, and text fields are
implemented as subclasses of either NSControl or NSActionCell.

For example, buttons in a user interface are represented by instances of the NSButton
class, which is a subclass of NSControl. NSControl is a subclass of NSView so that it
inherits the capability to handle events as well as draw. When a user presses a button, the
button sends its action message to its target object. Because both the target and action are
variables, button instances can be very flexibly configured. A button can be configured to
send the -selectAll: action message to a target object that displays editable text.
Another button might be configured to send the -deleteSelectedText: action
message to the same text object target.

One of the strengths of the target-action implementation in the Application Kit is that
actions are sent as Objective-C messages using the standard Objective-C messaging
system. Other user interface toolkits use integer event IDs along with large switch
statements or tables of function pointers. Another approach used by other toolkits is to use
specialized command classes that must be subclassed for each different command and
receiver combination. The Objective-C runtime eliminates the need for extra code and
tables. Even more importantly, the target-action system used by the Application Kit takes
advantage of the responder chain to enable a tremendous amount of flexibility.

When a user interacts with a user interface element that is derived from the NSControl
class or the NSActionCell class, the user interface element asks the shared
NSApplication object to send an action to a target by calling NSApplication's -
sendAction:to:from: method. When an action is sent using -sendAction:to:
from:, the to: argument is the target of the action and the from: argument is the object
that is sending the action. The -sendAction:to:from: method sends the action
message to the target passing the sender as the argument. The target of an action message
can use the sender argument to obtain additional information. For example, when the user
moves a slider, the slider sends an action message to its target with the slider itself as the
argument. The receiver of the action message can ask for more information such as the
current value of the slider.
The role of the shared NSApplication object in the target-action implementation is
important. If the target of a user interface element is specified, the shared application object
just sends the action message to the target directly. However, if no target is specified (the
to: argument is nil), -sendAction:to:from: uses an expanded version of the
responder chain to select the object that receives the action message. Setting the target of a
user interface element to nil makes the target context sensitive.

If the to: argument to -sendAction:to:from: is nil, the method searches the

responder chain for an object that can respond to the action message. The search begins
with the first responder in the key window. If the first responder cannot respond to the
action message, the next responder is checked and so on until the key window itself is
reached. After the key window gets a chance, the key window's delegate is checked. If the
key window's delegate cannot respond to the action message, and the main window is
different from the key window, the first responder in the main window is checked. The
search for an object that responds to the action continues up the main window's responder
chain to the main window itself, and then the main window's delegate. If no target has been
found, the application object is tried. Finally, if the application object cannot respond to the
action, the application object's delegate is given a chance. Figure 8.9 enumerates the order
of the search for the target of an action message sent to nil.

Figure 8.9. The extended responder chain is searched in the indicated order for the
target of actions sent to nil.
 NOTE

When the target of a user interface element is set to the First Responder in
Interface Builder, the target is actually set to nil, so that the expanded
responder chain is used to select the target at runtime.

The responder chain enables flexible, dynamic message processing that is context sensitive
in conjunction with the target-action paradigm. For example, the target of a -copy: action
sent from a menu item depends on the current first responder. If the first responder in the
key window is an editable text object with selected text, pressing the Copy menu item
places the selected text on the application's pasteboard. If the first responder has selected
graphics, the graphics are placed on the pasteboard. The result of pressing the Copy menu
item depends on the user's current selection identified by the first responder.

The EventMonitor.app application described in Chapter 15, "Events and Cursors," and
provided at www.cocoaprogramming.net demonstrates the responder chain.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Archived Objects and Nibs

The encoding and decoding of objects is briefly described in Chapter 5, as one of the
conventions used by the Cocoa frameworks. Most objects defined in Apple's frameworks
can be encoded and decoded whether they are nongraphical objects from the Foundation
framework, or graphical objects like windows and buttons from the Application Kit.
Encoding and decoding are frequently used to implement copy-and-paste operations, drag-
and-drop operations, and distributed-object messaging. When interconnected objects are
encoded as data into a block of memory or a file, the data is called an archive. One key to
using the Application Kit effectively is the knowledge that user interface elements and their
interconnections can be stored in just such an archive.

The objects stored in an archive are conceptually freeze dried. A freeze-dried object is an
actual software object including data and code. It was running in memory at one time, but
is now in cold storage. It can be decoded from an archive and revived, so that it begins
running from right where it left off at the time it was frozen. In fact, when a user interface
is designed in Interface Builder, the file that is saved is an archive of freeze-dried objects.
Interface Builder names files that contain such archives with the extension .nib. Nib
originally stood for Next Interface Builder, but the term has become generic and now just
refers to an archive of user interface objects. When an application loads a .nib file, the
objects are decoded to the same state they where in when encoded.

Most object-oriented environments include a visual tool for laying out user interfaces. Such
tools usually generate code and resources, which much be edited and compiled. Cocoa's
Interface Builder generates freeze-dried objects instead of code. This is an important
distinction. Generating code is a static approach, whereas the freeze-dried objects present a
dynamic solution. The static solution mimics the dynamic solution, but lacks much of its
underlying power. Freeze dried objects retain all their interconnections including delegates,
targets, actions, superviews, current displayed values, and so on. It is possible to create
nontrivial applications entirely with Interface Builder, and run them in Interface Builder's
Test Interface mode without ever compiling.

Interface Builder could have been called Object Connector because in addition to
positioning and sizing graphical objects, Interface Builder enables the interconnection of
objects. Interface Builder is not limited to editing the objects that Apple provides with
Cocoa. New objects can be edited and connected within Interface Builder with varying
degrees of sophistication. Any object can be instantiated and have outlets and actions that
are set within Interface Builder. New Interface Builder palettes can be created to enable
more complex editing and configuration as well.

It is possible to write Cocoa applications without using Interface Builder or any .nib files,
but loading .nib files is so convenient and powerful that almost every application uses
them. Unless the programmer intervenes, Cocoa applications automatically load a main nib
file when launched. The main nib file contains the objects that define the application's
menu bar. The main nib file for an application can be set in Project Builder's Application
Settings tab.

Nib Awaking

A problem can arise when objects that have been encoded into a .nib file are decoded. As
an object is decoded, it might need to access a reference to an object that has not yet been
decoded. How does an object know when during decoding it is safe to access the objects to
which it is connected? The answer is the -awakeFromNib method.

When objects are decoded from a .nib file, the Application Kit automatically sends the -
awakeFromNib message to every decoded object that can respond to it. The -
awakeFromNib message is only called after all the objects in the archive have been
loaded and initialized. When an object receives an -awakeFromNib message, it's
guaranteed to have all its outlet instance variables set. The -awakeFromNib message is
also sent to objects when Interface Builder enters Test Interface mode because Interface
Builder actually copies the interface before it is run. Interface Builder encodes objects into
a nib archive in memory, and then immediately decodes them to create a fully functional
copy, ready to test.

Implement -awakeFromNib to perform any initialization that needs to occur after all an
object's outlets have been reconnected after decoding from a .nib.

.nib files can be loaded into an application multiple times to create multiple copies of the
objects within the .nib. The multidocument architecture described in this chapter loads
the .nibs that define document windows as many times as needed to create as many
documents as needed.

The File's Owner

When direct communication between objects within a .nib and objects outside the .nib
is required, the .nib file's owner provides that communication. The file's owner represents
an object that is not in the .nib file. Figure 8.10 shows the Interface Builder icon that
represents the file's owner of the nib being edited. Connections to the outlets and actions of
the file's owner can be set in Interface Builder, but the actual object that is used as the file's
owner is only specified when the .nib is loaded.

Figure 8.10. Interface Builder uses an icon labeled File's Owner as a placeholder for
an object that is not in the .nib.
In many cases, direct connections between objects can be avoided by using notifications
and the responder chain. For example, an object decoded from a .nib can register to
receive notifications from within its -awakeFromNib implementation. Objects can also
send notifications to anonymous receivers or to the current first responder. Objects within
a .nib can use the shared NSApplication instance in every application by referring to the
NSApp global variable or calling [NSApplication sharedApplication].

.nibs are explicitly loaded into an application by calling the -loadNibNamed:

owner: method declared in a category of the NSBundle class. The category is part of
the Application Kit. As a result, .nibs cannot be loaded by programs that do not link to
the Application Kit, even if the .nib that is loaded does not contain any objects that
depend on the Application Kit.

The owner argument to -loadNibNamed:owner: is the object that is used as the file's
owner for the nib. Any connections made to the file's owner within the .nib are made to
the owner, specified when the .nib is loaded. Connections that cannot be made because
of inconsistencies between the owner used when the .nib is loaded and the outlets and
actions specified for the file's owner when the .nib was created are discarded. The -
awakeFromNib method is also sent to the file's owner specified with -
loadNibNamed:owner:. The file's owner is not technically part of the .nib, but a .
nib's owner can implement -awakeFromNib to perform any logic needed after a nib
has been loaded. If several .nibs are loaded using the same owner, that owner's -
awakeFromNib method is called multiple times.

The application's main .nib is loaded automatically by the NSApplication object

when the application is launched. The NSApplication object itself is the file's owner of
the main .nib.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

NSWindowController Overview

The NSWindowController class is often used as the file's owner when loading a .nib
containing the definition of a window. The NSWindowController class can be used to
customize a window's title, preserve the window's position and size in the user's defaults
database, cascade windows onscreen, and manage the window's memory when the window
is closed. Unlike NSApplication, NSWindow, and NSView, the
NSWindowController class is not a core part of the Application Kit architecture.
NSWindowController is provided as a convenience to help implement a common
feature of applications, the dynamic loading of windows from nibs and their subsequent
management.

NSWindowController can be used to manage windows that are created

programmatically as well as windows loaded from .nibs. The NSWindowController
class can be used along with other classes to implement flexible multidocument support in
applications. NSWindowController is not used in every Application Kit-based
application, but it is available for use when appropriate and can eliminate lines of code that
would otherwise be repeated in many applications.

NSWindowController can be subclassed to manage complex documents in an

application. Custom subclasses of NSWindowController are a handy place to
implement logic that ties the documents of an application to the application itself,
particularly if other dedicated multidocument support classes are not used. The
NSWindowController class is usually part of the Controller in the common Model-
View-Controller application architecture as described in Chapter 6.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Multidocument Applications

Applications that enable users to open and manipulate multiple documents simultaneously are very
common. Examples of multidocument applications include word processors, spreadsheets, and drawing
programs. Because multidocument applications are so common, the Application Kit contains classes that
automate most of the work needed to manage multiple documents simultaneously.

The following five classes interoperate to aid in the implementation of multidocument applications:
NSApplication, NSDocumentController, NSDocument, NSWindowController, and
NSFileWrapper. Every application contains an instance of NSApplication, but the other classes
are strictly optional. NSDocumentController, NSDocument, NSWindowController, and
NSFileWrapper are powerful classes that implement code that would otherwise be duplicated in many
applications. Figure 8.11 shows the relationships between these classes used in a complex multidocument
application.

Figure 8.11. The NSApplication, NSDocumentController, NSDocument,

NSWindowController, and NSFileWrapper classes interoperate to implement multidocument
applications.

Apple's documentation on the Application Kit's multidocument support is excellent and comprehensive.
An overview of multidocument application design using the provided classes is provided in online
documentation at http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/
ProgrammingTopics/AppArchitecture/. The TextEdit.app sample application that is distributed with
Apple's Cocoa developer tools is an example of a multidocument application that does not use the
multidocument-support classes. The Sketch.app sample does use the built-in multidocument support.
Examining TextEdit.app's source code and comparing it to Sketch.app is a good way to contrast the
different approaches to multidocument support.

As a general rule, the built-in classes save a lot of work and ensure a high degree of compatibility and
consistency with other applications. Using the NSDocument and NSDocumentController classes
can also simplify the implementation of scripting and undo features in applications.

NSApplication Support

A certain amount of support for multidocument applications is built into the NSApplication class.
NSApplication provides delegate methods that enable customization of standard application
behaviors regarding multiple documents. For example, Mac OS X applications that support multiple
documents are expected to open a new untitled document under some circumstances. The -
applicationShouldOpenUntitledFile: delegate method can be implemented in an
application object's delegate to control that behavior. The following delegate methods are provided to
enable the application object's delegate to control multidocument behavior without using the built-in
multidocument support classes:

-(BOOL)application:(NSApplication *)anApp
openFile:(NSString *)filename

-(BOOL)application:(NSApplication *)anApp
openFileWithoutUI:(NSString *)filename
-(BOOL)application:(NSApplication *)anApp
openTempFile:(NSString *)filename

-(BOOL)application:(NSApplication *)anApp
printFile:(NSString *)filename

-(BOOL)applicationOpenUntitledFile:(NSApplication *)anApp

-(BOOL)applicationShouldHandleReopen:(NSApplication *)anApp
hasVisibleWindows:(BOOL)flag

-(BOOL)applicationShouldOpenUntitledFile:(NSApplication *)anApp

-(NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication
*)anApp

-(BOOL)applicationShouldTerminateAfterLastWindowClosed:(NSApplication
*)anApp

The NSApplication class implements most of the standard behaviors expected of multidocument
classes without intervention by its delegate. The delegate methods should only be used when there is a
need to deviate from the standard behaviors. If the Application Kit's classes for supporting
multidocument applications are used, the delegate methods are almost certainly unnecessary
NSDocumentController Overview

NSDocumentController class assists with the creation of new documents and opening existing
documents. It also plays a role in saving, printing, and closing documents. There should be at most an
instance of NSDocumentController in any application. The use of NSDocumentController is
optional, but it provides many of the features of multidocument applications that must be tediously hand
coded if it is not used.

When the multidocument application is created with Project Builder and Interface Builder, an instance of
NSDocumentController is automatically created and added to the application's responder chain.
Standard menu items such as New and Open in the File menu send actions to the first responder. The
actions travel up the responder chain until handled. NSDocumentController handles many standard
document-related actions including the actions sent by default from the New and Open menu items. If no
object preceding the document controller in the responder chain handles such actions then the document
controller will.

NSDocumentController handles the actions sent from the New menu item by creating a new
instance of a NSDocument subclass and initializing it with the -init method. The subclass that is
instantiated can be set within Project Builder by selecting the Edit Active Target menu item in the Project
menu. Project Builder displays various properties of the current target including its Application Settings.
Within the Application Settings tab, type the name of a NSDocument subclass into the Document Class
field.

When NSDocumentController receives the action to open an existing document, it displays the
Open panel, gets the user's selection, creates a new instance of a subclass of NSDocument as
appropriate, and initializes the new document object by calling -initWithContentsOfFile:
ofType:. The subclass of NSDocument that is instantiated might depend on the type of file being
opened. The associations between file types and NSDocument subclasses are made in Project Builder's
Application Settings tab.

Values entered via Project Builder's Application Settings interface are stored in a human-readable text
file named project.pbxproj within the *.pbproj directory created by Project Builder for each project.
When an application is built by Project Builder, a file named Info.plist is created based on the project's
application settings and stored in the *.app directory which contains the resulting application executable.
Both can be edited in any text editor if some care is taken to preserve the formatting.

NOTE

*.pbproj and *.app directories as well as many others are depicted as individual files in
Apple's Finder. The contents of these folders can be revealed by selecting the Show
Package Contents option of Finder's contextual menu. The contextual menu is shown if the
Control key is held down when clicking on the folder.

NSDocumentController is rarely subclassed. It is included in the responder chain for action

messages automatically if it is included in an application. NSDocumentController also registers for
and receives notifications that are sent when documents might be affected by system events. For
example, NSDocumentController responds when an application is notified that the system is
shutting down so that unsaved documents can be saved. NSDocumentController does not do
anything that cannot be done by other classes. In particular, the application's delegate can fill most of the
roles of the document controller. If custom behavior not provided by NSDocumentController is
needed, it is usually easier to create a custom class and use it as the application's delegate than it is to
subclass NSDocumentController. A custom application delegate and NSDocumentController
can both be used in the same application. NSDocumentController defers to the application delegate
whenever both respond to the same delegate message or notification.

NSDocument Overview

NSDocument is an abstract class. Subclasses of NSDocument are used to encapsulate the data
associated with documents. Subclasses of NSDocument can be used in multidocument applications and
in other types of applications. A subclass of NSDocument is appropriate any time an application
manipulates persistent data that is stored in the file system.

The NSDocument class provides methods that implement the standard actions sent by the Save, Save
As, Print, Revert, and Close menu items and others. NSDocument handles most of the logic needed by
all applications, such as showing the Save panel when the action message associated with the Save As
menu item is received. The NSDocument class even provides partial support for undo, redo, and
scripting features that can be expanded to meet the needs of particular applications. Subclasses inherit the
standard behaviors and only have to override a handful of methods to enable application-specific data
manipulation. Like with the NSDocumentController class and the NSWindowController class,
using NSDocument is optional, but it provides standard behaviors that must be hand coded if it is not
used.

A subclass of NSDocument is typically used in conjunction with one or more instances of

NSWindowController to implement a user interface for documents. The NSDocument subclass
stores the data that is represented by the document and has references to any window controllers
associated with windows that display the data. The typical relationships between document controllers,
documents, and window controllers are shown in Figure 8.11. Although the relationships might seem
complex, each class has a narrowly defined role. They cooperate to provide a complete solution for
document management and presentation.

Unlike NSApplication, NSDocumentController, and NSWindowController,

NSDocument must be subclassed to be used in an application. The details of subclassing NSDocument
and using the Application Kit's multidocument support classes are provide in Apple's documentation that
comes with the developer tools. Several examples in this book use the multidocument classes, but the
emphasis is unleashing the power of advanced features. The multidocument classes are presented as part
of the infrastructure used to delve into more advanced topics. Detailed introductory tutorials for creating
document-based applications with Apple's developer tools are available on the Internet. One good tutorial
is at www.stepwise.com/Articles/VermontRecipes/index.html. The interoperation of the multidocument
classes might seem complex or mysterious at first, but in reality they provide straightforward
implementations that can be readily replicated as shown by the TextEdit.app sample application that
comes with the developer tools. Working with the multidocument classes might be the first task when
coding a new Cocoa application, but the task is highly automated by the tools and consumes a tiny
fraction of the time invested in coding.

NSFileWrapper Overview
One additional class that aids the implementation of multidocument applications is NSFileWrapper.
The NSDocument class is used to encapsulate the data stored by a document and the relationship
between that data and its graphical presentation in one or more windows. The NSFileWrapper class is
often used within the implementation of a NSDocument subclass. NSFileWrapper encapsulates the
relationship between the data stored by a document and that data's representation in a file system. For
example, many applications store the data for one document within many related files in a directory
called a package. The package and all contained files appear to be a single file to users.

The use of packages provides a way for developers to store document data in the number of files and
formats that is most convenient without inadvertently increasing the user's perception of complexity.
Packages provide multiple-streams of data for one document and are conceptually similar to HFS
resource forks. Packages can contain any number of different files and even other packages. One reason
to use a package to store document data is so that document settings for page size and margins might be
stored in one file, and document content in another. For example, in an application that displays standard
image data formats, the standard format image data can be stored separately from application-specific
data. To the user, the whole package appears to be a single file that can be copied and moved as a unit.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Undo and Redo

The Application Kit includes a powerful and flexible system to implement undo and redo
operations by taking advantage of the Objective-C runtime to record the messages sent to
objects and play them back later. Many Application Kit classes including the text
management views already implement undo and redo.

Each instance of the NSDocument class optionally includes an instance of

NSUndoManager. The NSUndoManager class stores recorded messages and works
with the standard Undo and Redo menu items. NSUndoManager is actually part of the
Foundation framework because nongraphical applications might include undoable
operations. The NSUndoManager class can be used without the NSDocument class and
visa versa, but using them together automatically provides several benefits. Each document
can have its own list of undoable and redoable operations. The NSDocument class can use
the undo manager to provide information about the state of the document, such as whether
there have been any unsaved changes made before a document is closed.

NSUndoManager uses instances of the NSInvocation class to store Objective-C

messages and their arguments. By default, all the messages that are stored in an undo
manager, within one iteration of the run loop, are grouped into a single undoable operation.
This is a sensible policy because all the messages that result from a single user action
should be undoable by a single user action. Redo is automatically supported whenever an
operation is undone. Just as messages for undo are recorded when an operation is originally
performed, undoing the operation records messages that enable redo. Redo is essentially
implemented as undoing undo.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Menu Validation

The Application Kit implements menus with the NSMenu class. After each user event,
visible menu items are automatically validated. By default, a menu item is valid, and
therefore enabled, if its target can respond to its action. If no object that responds to the
menu item's action is found, the menu item is invalid and disabled.

When the target for a menu item is a specific object, default validation is simple. The target
either responds to the action or it does not. When the target of a menu item is nil the
expanded responder chain is searched to validate the menu item. If any object in the
expanded responder chain responds to the action the menu item is valid. Otherwise, it is
invalid.

The default validation can be enhanced by implementing the -validateMenuItem:

method in object within the responder chain. When NSMenu has found an object that
responds to a menu item's action, an additional check is made to determine if that object
also implements -validateMenuItem:. If so, NSMenu calls -
validateMenuItem: with the menu item being validated as the argument. If -
validateMenuItem: returns YES, the menu item is the validated.

The -validateMenuItem: method enables fine control of a menu item's status. For
example, a view in the responder chain might respond to the -copy: action message, but
the Copy menu item should still be disabled if the view that contains no selection to be
copied is the menu item's target. The view can implement -validateMenuItem: to
return YES only if the user's selection within the view can be copied.

Automatic menu validation is disabled by calling NSMenu's -

setAutoenamblesItems: method. Menu items must be validated manually using the
-setEnabled: method implemented by NSMenuItem if automatic validation is
disabled. The -setEnabled: method should not be used in conjunction with automatic
validation because the automatic validation might unpredictably reset any status set with -
setEnabled:.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Spell Checking

The Application Kit contains support for spell checking of any selectable text. A single instance
of the NSSpellChecker class provides access to system-wide, spellchecking services that can
be used with the Application Kit's text objects. A standard panel for spell checking is also
provided to let users select alternate spellings or add words to the system-wide dictionaries.
Spelling in multiple languages is supported, but Mac OS X only ships with an American English
dictionary. When additional dictionaries are added to a system, NSSpellChecker uses them
automatically, based on user language preferences.

The text classes provided by the Application Kit already support spell checking, and a Spelling
submenu is provided by default in every Application Kit based application. The menu items in the
Spelling submenu send actions using the responder chain. The text classes already respond to the
appropriate actions. The programmer must implement methods for the relevant action messages
to enable spell checking in custom classes.

Enabling Spell Checking

The details of enabling spell checking in custom classes are provided here primarily to highlight
another example of the way applications use dynamic features. Spell checking is implemented
using the responder chain. Any class that responds to the necessary messages can benefit from
built-in Application Kit features.

The Check Spelling menu item of the standard Spelling submenu is configured to send the -
checkSpelling: action message using the responder chain. Enable spell checking in a
custom class by implementing the -checkSpelling: method to implement the following
code:

[[NSSpellChecker sharedSpellChecker] checkSpellingOfString:

aString
startingAt:0];

The -sharedSpellChecker method returns the shared instance of NSSpellChecker. The

aString argument contains the string to be checked. An optional index into the string can be
supplied to start checking at some position other than the start of the string. The -
checkSpellingOfString:startingAt: method returns the range of the first word that
is misspelled. The more complex -checkSpellingOfString:startingAt:language:
wrap:inSpellDocumentWithTag:wor dCount: method can be used to fine tune the
spell checking by specifying a language and a set of words to ignore.

When the range of the first misspelled word is found, the spelling can be corrected via the -
changeSpelling: action. Implement -(void)changeSpelling:(id)sender to
replace the misspelled word with the string provided by the sender argument. If -
changeSpelling: is not implemented, NSSpellChecker can identify spelling errors but
cannot fix them.

If a custom object conforms to the NSIgnoreMisspelledWords protocol then

NSSpellChecker enables the Ignore button in the standard-spelling panel.
Book: Cocoa® Programming
Section: Chapter 8. The Application Kit Framework Overview

Summary

This chapter provides an overview of the most prominent features built into the Application
Kit, and the architecture used to provide those features. The Application Kit contains a core
set of classes that all Application Kit-based applications must use. Those classes are the
NSResponder and three of its subclasses, NSApplication, NSWindow, and
NSView. Features that are common to most applications are implemented by classes that
are optionally included to avoid work that would otherwise be repeated in many
applications. Optional classes such as NSDocumentManager, NSDocument, and
NSWindowController cooperate to enable many powerful features and save many
lines of code. Each of the optional classes are integrated into the responder chain
constructed by the core classes. Spell checking, undo, redo, and automatic menu validation
all take advantage of the responder chain to simplify their implementation and enhance
their value.

Concepts, overviews, language options, conventions, architecture, and design patterns have
been covered so far. Starting with Chapter 9, "Applications, Windows, and Screens," the
details of Cocoa programming with Objective-C are the primary focus. The conceptual
information presented in the first eight chapters provides the information needed to
understand where the upcoming details fit into the over all system. Pay attention to the
recurring patterns and conventions. Programmers familiar with the idioms and conventions
of other development environments should take note of the areas where Cocoa differs from
other frameworks. In particular, the dynamic features of Objective-C are used extensively.
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 9. Applications, Windows, and Screens

IN THIS CHAPTER

● The New Image Viewer

● Working with NSWindow
● Working with NSApplication
● Modal Loops
● Working with Sheets
● Working with Drawers
● Working with Screens
● Working with Panels

This chapter builds on information about the principal Application Kit framework classes
introduced in Chapter 8, "The Application Kit Framework Overview." To show how
classes such as NSWindow and NSApplication are used in applications, this chapter
extends the Image Viewer application started in Chapter 3, "Using Apple's Developer
Tools." The Image Viewer application in Chapter 3 has many compelling features even
though it does not contain a single line of custom code. In this chapter, custom classes are
written to make Image Viewer into a multidocument application similar to Apple's Preview
application. The complete implementation of Image Viewer is available at www.
cocoaprogramming.net.

In addition to showing typical uses of the NSWindow and NSApplication classes, the
new Image Viewer application uses Cocoa standard Open, Save, and Alert panels, and a
technique for using panels as Aqua sheets is shown.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

The New Image Viewer

Two custom classes are used to convert the Image Viewer application created in Chapter 3
into a multidocument application with the features that users expect: MYDocument and
MYDocumentManager.

Cocoa includes the NSDocument and NSDocumentController classes that have

many features in common with MYDocument and MYDocumentManager. Most
multidocument Cocoa applications should use the existing NSDocument and
NSDocumentController classes because they save work. In fact, they save so much
work that they completely hide their interaction with other classes such as NSWindow and
NSApplication. Because one of the purposes of this example is to show how
NSWindow and NSApplication are used, this example does more work than is usually
necessary.

The NSDocument and NSDocumentController classes are used in an example in

Chapter 18, "Advanced Views and Controls." A side benefit of implementing
MYDocument and MYDocumentManager in this chapter is that they dispel much of the
mystery about how NSDocument and NSDocumentController work. Project
Builder and Interface Builder simplify the creation of multidocument applications by
hiding most of the configuration and communication that takes place between the
document-related classes. This example makes the communication explicit.

In addition to requiring more work than necessary, the MYDocument and

MYDocumentManager classes lack many features of NSDocument and
NSDocumentController. For example, NSDocument handles undo, redo, and
AppleScript support, whereas NSDocumentController maintains a persistent Recent
Documents menu and supports the HFS file system's unique features. These features can be
added to MYDocument and MYDocumentManager, but that is beyond the scope of this
chapter.

NOTE

Apple's TextEdit sample shows another way to implement multidocument

applications without using NSDocumentController. TextEdit supports
undo, redo, AppleScript, the Recent Documents menu, and HFS file system
features.

The Role of the MYDocument Class

The Image Viewer application built in Chapter 3 has one window for displaying images. It
is necessary to modify Image Viewer so that it can have any number of open documents
each represented visually by a window that contains an NSImageView.

The MYDocument class is created to encapsulate documents. Each MYDocument

instance has an outlet connected to an NSImageView instance and stores information
about the document such as its path in the file system. The MYDocument class is
responsible for saving documents and giving users a chance to save unsaved documents
when their associated windows are closed.

The Role of the MYDocumentManager Class

A single instance of the MYDocumentManager class creates new MYDocument

instances and manages open documents. MYDocumentManager also cascades document
windows and allows review and saving of unsaved documents when the application quits.

By convention, the use of the word "manager" in a class name implies that the class is
responsible for allocating, storing, and releasing instances of some other class. For
example, the NSFontManager class stores information about existing NSFont instances.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with NSWindow

The NSWindow class encapsulates windows in Cocoa. Each instance of MYDocument has an associated window
that represents the document on the screen. Instances of MYDocument need to be informed when the user uses the
standard File, Save and File, Save As menu items. MYDocument also needs to know when its associated window is
closed so that it can prompt the user to save unsaved documents.

It is not necessary to subclass NSWindow to get it to interoperate with MYDocument. Classes such as NSWindow
are seldom subclassed because they provide delegate methods that enable customization of behavior without the need
to subclass.

The NSWindow class provides delegate methods to inform a delegate object when attributes of the window change.
Delegate methods are able to influence the behavior of a window. For example, NSWindow calls its delegate's -
windowShouldClose: method to ask permission to close. If the delegate's -windowShouldClose: returns
NO, the window does not close.

Each instance of MYDocument is the delegate of its associated window.

NSWindow's Delegate

Each Cocoa class that sends delegate messages includes a section titled "Methods Implemented By the Delegate" in
its class documentation. The NSWindow class documentation lists the following delegate methods:

- (void)windowDidResize:(NSNotification *)notification;
- (void)windowDidExpose:(NSNotification *)notification;
- (void)windowWillMove:(NSNotification *)notification;
- (void)windowDidMove:(NSNotification *)notification;
- (void)windowDidBecomeKey:(NSNotification *)notification;
- (void)windowDidResignKey:(NSNotification *)notification;
- (void)windowDidBecomeMain:(NSNotification *)notification;
- (void)windowDidResignMain:(NSNotification *)notification;
- (void)windowWillClose:(NSNotification *)notification;
- (void)windowWillMiniaturize:(NSNotification *)notification;
- (void)windowDidMiniaturize:(NSNotification *)notification;
- (void)windowDidDeminiaturize:(NSNotification *)notification;
- (void)windowDidUpdate:(NSNotification *)notification;
- (void)windowDidChangeScreen:(NSNotification *)notification;
- (void)windowWillBeginSheet:(NSNotification *)notification;
- (void)windowDidEndSheet:(NSNotification *)notification;
- (BOOL)windowShouldClose:(id)sender;
- (id)windowWillReturnFieldEditor:(NSWindow *)sender toObject:(id)client;
- (NSSize)windowWillResize:(NSWindow *)sender toSize:(NSSize)frameSize;
- (NSRect)windowWillUseStandardFrame:(NSWindow *)window defaultFrame:
(NSRect)newFrame;
- (BOOL)windowShouldZoom:(NSWindow *)window toFrame:(NSRect)newFrame;
- (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;

The delegate methods that do not require any return value have a single argument that is an NSNotification
instance. In each case, the NSWindow instance that sent the delegate message is obtained by sending the -object
message to the notification argument. The delegate methods that return a value all include the NSWindow instance
that sent the delegate message as an argument. Apple's class documentation describes how each delegate method is
used and when it is called.

The MYDocument class implements only the following three NSWindow delegate methods:

/*" Window delegate methods "*/

- (BOOL)windowShouldClose:(id)sender;
- (void)windowWillClose:(NSNotification *)notification;
- (void)windowDidBecomeKey:(NSNotification *)notification;

Cocoa classes check to see if their delegate responds to each delegate message before sending it. As a result, it is
common for delegates to implement only the methods they need. In the case of the MYDocument class, only three of
the available delegate methods are needed.

Because each MYDocument instance is a window's delegate, each instance becomes part of the responder chain and
can receive action messages. As explained in the "Target-Action Paradigm" section of Chapter 8, NSWindow
instances include their delegates in the responder chain for actions. MYDocument handles the -saveDocument:,
-saveDocumentAs:, and -noteImageWasDropped: action messages. Each MYDocument instance receives
these action messages when user interface objects, such as menu items, send the actions up a responder chain that
starts with the document's associated window.

The responder chain is also used to validate menu items. The -validateMenuItem: method is called
automatically before menu items become visible. When a menu item is about to be displayed, the menu item searches
the responder chain for an object that responds to its action. When a suitable object is found, the menu item sends the
-validateMenuItem: message to that object passing the menu item to be validated as an argument.
MYDocument implements -validateMenuItem: to enable or disable menu items that send the -
saveDocument: or -saveDocumentAs: actions. For example, if a document has not been modified, the menu
item that sends -saveDocument: can be disabled because there are no changes to save.

Configuring the Document's Window

Each MYDocument instance needs its own associated window and other objects used to represent the document.
MYDocument gets its window by loading a .nib file that defines the interface for documents. Each time the .nib
file that defines documents is loaded, new instances of the objects inside the .nib are unarchived. By loading the .
nib file, each MYDocument instance gets its own instances of the user interface objects.

To make the Image Viewer interface ready to support multiple documents, the following changes must be made:
Start Project Builder and open the project for the Image Viewer application developed in Chapter 3. Open Image
Viewer's MainMenu.nib file by double-clicking it within the Resources folder in the Files tab of Project Builder's
Project pane. Figure 9.1 shows the MainMenu.nib file selected in Project Builder.

Figure 9.1. The MainMenu.nib file for Image Viewer is selected in the Files tab of Project Builder's Project
pane.
The MainMenu.nib file contains only one window for displaying images. To provide the capability of having any
number of open document windows, the interface for document windows needs to be stored separately from the other
objects in MainMenu.nib. By putting the definition of the document window in a separate .nib file, it becomes
possible to load the document .nib file over and over to create as many windows as needed without also creating
new copies of the main menu and other objects in MainMenu.nib.

In Interface Builder, create a new empty interface by using the File, New menu item. When Interface Builder
displays the panel titled Starting Point, select an Empty Cocoa interface as shown in Figure 9.2 and click the New
button. Interface Builder displays a window titled Untitled that represents the new empty .nib file. The new
interface is used to define the interface for documents in the new Image Viewer application.

Figure 9.2. The Starting Point panel enables selection of the type of interface to create.

Two .nib files are now open at once: the MainMenu.nib file and the new empty .nib file represented by an
Interface Builder window titled Untitled. In the Instances tab of the window titled MainMenu.nib, select the icon
for the window that contains the NSImageView instance. Cut the window with Interface Builder's Edit, Cut menu
item. Make the window titled Untitled key by clicking in its title bar, and then paste the cut window using Interface
Builder's Edit, Paste menu item. Figure 9.3 shows the window containing the NSImageView cut from the
MainMenu.nib and pasted into the Untitled .nib.

Figure 9.3. The window titled Dropped Image has been cut from the MainMenu.nib and pasted into Untitled.

Save MainMenu.nib and close it for now. It will be edited more in the later example.

The next step is to create the MYDocument class. Select the Classes tab in the window titled Untitled and select the
NSObject class as shown in Figure 9.4. Create a new subclass of NSObject using Interface Builder's Classes,
Subclass NSObject menu item and name the new class MYDocument.

Figure 9.4. The NSObject class is selected in MainMenu.nib's Classes tab.

With the MYDocument class selected in the Classes tab of the window titled Untitled, use Interface Builder's
Classes, Add Outlet to the MYDocument menu item. If it is not already visible, Interface Builder displays the Show
Info window titled MYDocument Class Info. In the window titled MYDocument Class Info, set the name of the
new outlet to imageView and set its type to NSImageView as shown in Figure 9.5.

Figure 9.5. MYDocument's new outlet is named imageView and has the type NSImageView.

Select the tab labeled 0 Actions in the Show Info window titled MYDocument Class Info. Use the Add button in the
lower-right corner to add an action method to the MYDocument class. Name the new action saveDocument:.
Next, add two more actions. Name one saveDocumentAs: and the other noteImageWasDropped:.

Make sure the MYDocument class is still selected in the Classes tab of the window titled Untitled and use Interface
Builder's Classes, Create Files for the MYDocument menu item to create the files that will contain the interface and
implementation of the MYDocument class. Interface Builder displays a sheet asking where to store the new files.
Select the folder that contains the Image Viewer project and click the Choose button at the bottom of the sheet.

Switch to the Instances tab in the window titled Untitled and select the Icon labeled File's Owner. The Show Info
window's title changes to File's Owner Info. The File's Owner Info window shows a list of classes. Select the
MYDocument class in the list. Interface Builder now knows that an instance of MYDocument will be the File's
Owner of the .nib when the .nib is loaded.

Draw a connection line from the File's Owner icon to the area inside the scroll view in the Dropped Images window.
Connection lines are drawn by pressing Ctrl and dragging the mouse. Connect the imageView outlet of the File's
Owner to the NSImageView instance that is already inside the scroll view. Figure 9.6 shows the connection line
from the File's Owner icon to the NSImageView instance inside the scroll view.

Figure 9.6. Click the Connect button to connect the imageView outlet of the File's Owner to the
NSImageView instance inside the scroll view.
Draw a connection line from the icon for the window titled Dropped Image to the File's Owner icon. Make the File's
Owner the window's delegate, as shown in Figure 9.7.

Figure 9.7. Make File's Owner the window's delegate.

Select the icon for the window titled Dropped Image. If the Show Info window titled NSWindow Info is not already
visible, use Interface Builder's Tools, Show Info menu item to make it visible. In the Options section of the
NSWindow Info window, make sure that the option Visible at launch time is off. For .nib files other than
MainMenu.nib, the Visible at launch time options specifies whether the window should be visible when the .nib
file that contains the window is loaded. In Image Viewer, it is better to have the windows that represent documents
invisible at first so that the MYDocument class can make them visible at the right time.

Save the Untitled .nib as ImageViewerDocument.nib inside the English.lproj directory of the Image
Viewer project. If Interface Builder displays a sheet asking if it should add the .nib file to the Image Viewer
project, click the Add button on the sheet. Now close ImageViewerDocument.nib, hide Interface Builder, and
return to working in Project Builder.

Implementing MYDocument

If the Image Viewer project does not already contain the MYDocument.h and MYDocument.m files created in
Interface Builder, select the Classes folder in the Files tab of Project Builder's Project pane. Use Project Builder's
Project, Add Files menu item to add MYDocument.h and MYDocument.m to the project. Project Builder displays
a sheet asking how to reference the files added to the project. Click the Add button to accept the default reference
style.

Edit the MYDocument.h file so that it defines the interface to MYDocument class as follows:

File MYDocument.h:

#import <Cocoa/Cocoa.h>

@interface MYDocument : NSObject

{
IBOutlet NSImageView *imageView;

NSString *_myDocumentPath; /*" Document's path "*/

BOOL _myHasEverBeenSaved; /*" YES iff document has ever been saved "*/
}

/*" Supported document extensions "*/

+ (NSArray *)documentExtensions;

/*" Designated Initializer "*/

- (id)initWithPath:(NSString *)aPath;

/*" Alternate Initializer "*/

- (id)init;

/*" Document management methods "*/

- (NSString *)documentPath;
- (BOOL)safeClose;

/*" Access document's Window "*/

- (id)documentWindow;

/*" Document status "*/

- (BOOL)hasEverBeenSaved;
- (BOOL)isDocumentEdited;

/*" Actions "*/

- (IBAction)saveDocument:(id)sender;
- (IBAction)saveDocumentAs:(id)sender;
- (IBAction)noteImageWasDropped:(id)sender;

/*" Window delegate methods "*/

- (BOOL)windowShouldClose:(id)sender;
- (void)windowWillClose:(NSNotification *)notification;
- (void)windowDidBecomeKey:(NSNotification *)notification;

@end

The implementation of the MYDocument class begins here and is developed in the next few sections of this chapter
as the Cocoa features used by the implementation are described. The first lines in MYDocument.m import the class
interface and start the implementation of MYDocument.
#import "MYDocument.h"

@implementation MYDocument
/*" This class encapsulates documents in a multi-document application. "*/

The next part of the implementation defines some localizable strings that are presented to users and used to report
errors that are detected when Image Viewer is run.

Localizable Strings

Localization is described in the Localization section of Chapter 7, "Foundation Framework Overview." When an
application is localized for a particular language or culture, every string that is ever presented to users needs to be
translated to the appropriate language. Even error messages need to be translated, so users can read them when they
are displayed.

Many of the strings that users see are defined in .nib files. Cocoa applications are able to use different .nib files
for every localization. When Cocoa applications load .nib files, they automatically load the available .nib files
that best match the user's language preferences.

Any number of .nib files can be created to support localization without the need to edit or compile code for each
one, but strings are also commonly defined in code. There needs to be a way to localize strings in code without
having to edit and recompile the code for every localization. Cocoa provides the NSLocalizedString() macro
that aids the localization of strings in code.

NSLocalizedString() accepts two arguments. The first is constant NSString containing words that need to
be translated for each localization. The second argument is a short phrase that explains the meaning of the first
argument. The second argument is intended to help translators make accurate translations. The
NSLocalizedString() macro is explained in more detail at http://developer.apple.com/techpubs/macosx/Cocoa/
Reference/Foundation/ObjC_classic/Functions/FoundationFunctions.html. Apple provides a program called
genstrings in /usr/bin that is capable of reading source code and generating a file named Localizable.
strings containing strings that need to be translated.

NOTE

Finder hides the /usr/bin folder and other traditional Unix folders by default. The /usr/bin
folder can be accessed from the Terminal application or by using Finder's Go, Go to Folder menu and
typing /usr/bin in text field presented.

Different versions of the Localizable.strings file are stored for each language along with the different .nib
files. When a Cocoa application that uses NSLocalizedString() is run, it automatically uses the translated
strings based on the user's language preferences. The same source code can be used with every localization without
the need to edit or recompile the source code for each one. More information about genstrings is available at
http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/ProgrammingTopics/Internationalization/
Tasks/GeneratingStringsFiles.html.

The following localizable strings are used in MYDocument.m:

/*" Constant local strings "*/

#define MYDEFAULT_DOC_PATH NSLocalizedString(@"~/Untitled", @"")
#define MYCANCEL NSLocalizedString(@"Cancel", @"")
#define MYSAVE_CHANGES NSLocalizedString(\
 @"%@ has been edited. Do you want to save changes?", @"")
#define MYDEFAULT_CLOSE_ACTION NSLocalizedString(@"Close", @"")
#define MYSAVE NSLocalizedString(@"Save", @"")
#define MYDONT_SAVE NSLocalizedString(@"Don't Save", @"")
#define MYFILE_SAVE_ERROR NSLocalizedString(@"Document Save Error", @"")
#define MYFILE_SAVE_ERROR_MSG NSLocalizedString(@"Unable to save <%@>.", @"")
#define MYFILE_OPEN_ERROR NSLocalizedString(@"Document Open Error", @"")
#define MYFILE_OPEN_ERROR_MSG NSLocalizedString(@"Unable to open <%@>.", @"")

Document File Types

The MYDocument class adds the +documentExtensions class method to the class methods inherited from
NSObject. The +documentExtensions method returns an array of file extensions for file types that can be
used by an instance of MYDocument. The Image Viewer application can display any image file type supported by
the NSImage class. The NSImage class is described in Chapter 14, "Custom Views and Graphics Part III."
NSImage's +imageFileTypes method returns an array containing all the file types understood by NSImage.

+ (NSArray *)documentExtensions
/*" Returns the extensions supported by NSImage "*/
{
return [NSImage imageFileTypes];
}

The Document's Path

Each instance of MYDocument stores the path to the file that it represents. A standardized version of the path is
stored so that comparisons between paths provide accurate results. It is possible for any number of paths to refer to
the same file due to file system links in the paths. Standardized paths expand all links. Two standardized paths can be
compared with a simple string comparison to determine if they refer to the same file.

MYDocument's -_mySetDocumentPath: method is not declared in any class interface and is, therefore,
considered private to the implementation of MYDocument.

- (void)_mySetDocumentPath:(NSString *)aPath
/*" Set the document's path by expanding tilde characters in aPath and
standardizing aPath. Also sets the title of the document window. "*/
{
NSString *standardPath = [aPath stringByExpandingTildeInPath];

standardPath = [standardPath stringByStandardizingPath];

[standardPath retain];
[_myDocumentPath release];
_myDocumentPath = aPath;
[[self documentWindow] setTitleWithRepresentedFilename:_myDocumentPath];
}

In addition to storing the path to the file represented by the document, the -_mySetDocumentPath: method sets
the title of the document's window. The expression [self documentWindow] is explained in Document
Management Methods section of this chapter. It returns the window associated with the document. NSWindow's -
setTitleWithRepresentedFilename: sets the window's title to an easily readable variant of the document's
path.

Loading Images and Using NSRunAlertPanel()

The private _myLoadDocumentWithPath: method loads the image data, if any, at a specified path and tells the
document's image view to display the image.

This method uses the NSAssert() macro to perform error checking in the debug build of Image Viewer. The
NSAssert() macro has two arguments. The first is a Boolean expression, and the other argument is an error
message that is passed along with an exception that is raised if the first argument does not evaluate to YES. The
NSAssert() macro is used to raise an NSInternalInconsistencyException exception and output an
error message if some condition that should always be true turns out to be false.

In the -_myLoadDocumentWithPath: method, NSAssert() is used to assert that no attempt is made to load
an image into a document that already has an image. The NSAssert() macro is automatically disabled in release
builds. The NSAssert() macro helps programmers find errors when debugging and does not have any
performance impact on released applications.

- (void)_myLoadDocumentWithPath:(NSString *)aPath
/*" Sets documents image to the image stored aPath. "*/
{
NSImage *imageData;

NSAssert(![self hasEverBeenSaved],
@"Attempt to load document that is already loaded.");

if([[NSFileManager defaultManager] fileExistsAtPath:aPath])

{
imageData = [[NSImage alloc] initWithContentsOfFile:aPath];

if(nil == imageData)
{
// Unable to load image data
NSRunAlertPanel(MYFILE_OPEN_ERROR, MYFILE_OPEN_ERROR_MSG,
nil, nil, nil, aPath);
}
else
{
[imageView setImage:imageData];
[imageData release]; // imageData retained by imageView

// Make the image view a reasonambe size for the image displayed
[imageView setFrameSize:[[imageView image] size]];

// Set the path and remeber that documnet has been saved
_myHasEverBeenSaved = YES;
[self _mySetDocumentPath:aPath];
}
}
else
{
// The specified path does not exist.
// Set the document window's title but don't set its path
[[self documentWindow] setTitleWithRepresentedFilename:aPath];
}
}

The expression [self hasEverBeenSaved] is explained in the "Document Status Methods" section of this
chapter. It returns YES if the document has ever been saved and, therefore, has a valid path to the image data
displayed. For now it is enough to know that NSImage's -initWithContentsOfFile: method initializes a
new NSImage instance with the image data in a specified file. The -initWithContentsOfFile: method
releases the new image and returns nil if it is unable to load the image data.

If -_myLoadDocumentWithPath: is unable to initialize an NSImage with the image data at aPath, and alert
panel is displayed with NSRunAlertPanel() to tell the user that the document could not be opened with the
image at aPath.

NSRunAlertPanel()creates an alert panel, displays it onscreen, and runs it in a modal loop that requires the user
to acknowledge the panel by clicking a button. The use of a modal loop means that all events received by the
application are directed to Alert panel until the panel is closed. Modal loops are described in more detail in the
"Modal Loops" section of this chapter. Each alert panel has a short title, some explanatory text, and up to three
buttons. NSRunAlertPanel() is declared as follows:

int NSRunAlertPanel(NSString *title, NSString *msg, NSString *defaultButton,

NSString *alternateButton, NSString *otherButton, ...);

NSRunAlertPanel() accepts a variable number of arguments. The msg argument that provides explanatory text
can include printf-style formatting characters that are supported by NSString's -stringWithFormat:...
method. The arguments used to replace the formatting characters are specified after the titles of the buttons at the end
of NSRunAlertPanel() arguments list. NSRunAlertPanel() is documented at http://developer.apple.com/
techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Functions/AppKitFunctions.html.

NSRunAlertPanel() does not return until the user acknowledges the panel by clicking a button or closing the
panel. It returns one of the following constants: NSAlertDefaultReturn, NSAlertAlternateReturn, or
NSAlertOtherReturn. If the user clicked the button labeled with the defaultButton argument to
NSRunAlertPanel(), NSAlertDefaultReturn is returned. If the user clicked the button titled by the
alternateButton argument, NSAlertAlternateReturn is returned. Otherwise NSAlertOtherReturn
is returned. If the defaultButton title is nil, the default button is titled OK. If any of the other button titles are
nil, the corresponding button is not shown.

If -_myLoadDocumentWithPath: is able to load the image data at the specified path, the document's image
view is told to display the image with [imageView setImage:imageData]. The allocated image is released
because every method that allocates an object is responsible for releasing or autoreleasing the object. In this case, the
document's image view already retains the image, so releasing it in -_myLoadDocumentWithPath: does not
cause it to be deallocated immediately. The image view is responsible for releasing the image it retains. The fact that
the document has a valid path is noted by setting the _myHasEverBeenSaved instance variable to YES. Finally,
the document's path is set to the path of the image.

Initializing MYDocument Instances

The instances of the MYDocument class are initialized with the designated initializer, -initWithPath:. All
other initializers must call the designated initializer. In the case of MYDocument, the only other initializer is -init
inherited from NSObject. The -initWithPath: and -init methods are implemented as follows:

- (id)initWithPath:(NSString *)aPath
/*" Designated Initializer: Loads the objects that represent the document from
a nib file, configures the objects, and then loads the data at aPath. Sets
the document's path to a standardized version of aPath. If aPath is nil, an
untitled document is created. "*/
{
self = [super init];
if(self)
{
 // Load the user interface objects defined in a nib file using self as the
// File's owner of the nib
[NSBundle loadNibNamed:@"ImageViewerDocument.nib" owner:self];

// Configure the loaded objects

[imageView setTarget:self];
[imageView setAction:@selector(noteImageWasDropped:)];
[imageView setAutoresizingMask:NSViewNotSizable];
[[imageView window] setReleasedWhenClosed:YES];

if(nil != aPath)
{
[self _myLoadDocumentWithPath:aPath];
}
else
{
[self _mySetDocumentPath:MYDEFAULT_DOC_PATH];
}
}

return self;
}

- (id)init
/*" Alternate Initilaizer: calls [self initWithPath:nil]. "*/
{
return [self initWithPath:nil];
}

The key to the implementation of -initWithPath: is the [NSBundle loadNibNamed:

@"ImageViewerDocument.nib" owner:self] expression. Each MYDocument instance gets its associated
user interface objects by loading the .nib file that defines the objects and specifying the MYDocument instance as
the File's Owner of the .nib. Connections that were made to the File's Owner in Interface Builder are automatically
made to the MYDocument instance when the .nib file is loaded. As a result, the MYDocument instance becomes
the delegate of its associated window, and MYDocument's imageView instance variable is connected to the
NSImageView instance inside the document's window.

The -initWithPath: method makes the document instance the target of the associated NSImageView and sets
the action to -noteImageWasDropped:. As a result, the image view calls the document's -
noteImageWasDropped: method whenever the user drags and drops an image onto the image view. This target/
action connection could have been made in Interface Builder, but it is made here to show an alternative technique.
The target of the image view could also have been set to nil. In that case, the image view would use the responder
chain to find a target for its action. Unless another object earlier in the responder chain responds to the
noteImageWasDropped: message, the document object would still receive the message when the user drags and
drops an image onto the image view.

Another crucial part of the configuration of the document's user interface objects is the [[imageView window]
setReleasedWhenClosed:YES] expression. The NSView class provides the -window method that returns
the window containing the view. As a subclass of NSView, NSImageView inherits the -window method. In this
case, the window that contains the image view is the window that represents the document. By telling the document's
window to release itself when it is closed, the MYDocument class takes care of memory management for the user
interface objects loaded from the .nib. When the window is closed, it releases itself. When the window is
deallocated, it releases all the objects inside the window. The - setReleasedWhenClosed: property of the
window can also be set in Interface Builder.
The -init method calls the designated initializer specifying a nil path. When -initWithPath: is called with
a nil path, it initializes the document as an untitled document that has never been saved.

Document Management Methods

The MYDocument class provides several methods that are used by MYDocumentManager to manage open
documents. The first document management method is -documentPath.

/*" Document management methods "*/

- (NSString *)documentPath
/*" Returns the document's path or nil. "*/
{
return _myDocumentPath;
}

MYDocumentManager can use this method to identify documents. For example, if a user double-clicks an image
file that is already represented by an open document, NSDocumentManager can make the existing document key
instead of creating a second document instance that represents the same file. It is critical that the document's path is
stored as a standardized path so that MYDocumentManager can simply determine if an open document represents a
particular image file.

The document manager needs to be capable of closing open documents, and MYDocument provides the -
safeClose method for that purpose. The -safeClose method calls [self _myShouldClose] to confirm
that the user wants to close the document. If the document being closed has unsaved changes, an alert panel is
displayed giving the user a chance to save the document, close the document anyway, or cancel the close. If the user
cancels the close, -_myShouldClose returns NO and the document is not closed.

- (bool)_myShouldClose
/*" Gives users a chance to save edited documents before closing the document.
Returns NO if the user cancels the close. Returns YES otherwise. "*/
{
BOOL result = YES;

if([self isDocumentEdited])
{
int userChoice;
NSString *documentName = [self documentPath];

if(nil == documentName)
{
// document has no path so use its window's title instead
documentName = [[self documentWindow] title];
}

// the document has been edited

userChoice = NSRunAlertPanel(MYDEFAULT_CLOSE_ACTION,
MYSAVE_CHANGES, MYSAVE, MYDONT_SAVE, MYCANCEL, documentName);

switch(userChoice)
{
case NSAlertDefaultReturn:
{
// User chooses to save changes
[self saveDocument:nil];
result = YES;
 break;
}
case NSAlertAlternateReturn:
{
// User chooses NOT to save changes
result = YES;
break;
}
case NSAlertOtherReturn:
{
// User chooses to CANCEL close
result = NO;
break;
}
}
}

return result;
}

- (BOOL)safeClose
/*" Gives users a chance to save edited documents before closing the document.
Returns NO if the user cancels the close. Returns YES otherwise. "*/
{
BOOL result = [self _myShouldClose];

if(result)
{
// the user agrees to close the window
// close the document window immediately without
// letting the window call its -windowShouldClose: delegate
// method.
[[self documentWindow] close];
}

return result;
}

The window that represents each document is returned by the -documentWindow method. The MYDocument
class could be implemented with an outlet that is directly connected to the associated window, but that is
unnecessary. MYDocument already has an outlet for an image view, and the image view's window is the window
that represents the document.

- (id)documentWindow
/*" Returns document's window "*/
{
return [imageView window];
}

Document Status Methods

The MYDocument class uses the _myHasEverBeenSaved instance variable to store YES if the document has
ever been saved. Knowing if the document has ever been saved is important because the results of opening and
saving documents differ for documents that have been previously saved and documents that have never been saved.
For example, documents that have been previously saved or opened from a file in the file system have a valid path,
but unsaved untitled documents don't. MYDocument's -hasEverBeenSaved method returns the value of the
_myHasEverBeenSaved instance variable.

- (BOOL)hasEverBeenSaved
/*" Returns YES iff document has ever been saved and has a valid path. "*/
{
return _myHasEverBeenSaved;
}

MYDocument does not define a _myHasBeenEdited instance variable because each document already has
access to an associated window, and NSWindow provides the -setDocumentEdited: and -
isDocumentEdited methods to store information about whether the document has been edited since it was last
saved. The value returned from NSWindow's -isDocumentEdited method is used to determine if the user
should be given a chance to save changes before a document window is closed.

- (BOOL)isDocumentEdited
/*" Returns YES iff document has been edited since it was last saved. "*/
{
return [[self documentWindow] isDocumentEdited];
}

Document Actions and the Save Panel

Because each MYDocument instance is the delegate of its associated window, document instances receive action
messages that are sent up the responder chain. Two of the action messages handled by MYDocument are
saveDocument: and saveDocumentAs:, which are sent up the responder chain by the File, Save and File,
Save As menu items, respectively.

The private -_mySaveDocumentData method is called by both -saveDocument: and -saveDocumentAs:

to actually save the document's image in a file specified by the document's path. If writing the file to the document's
path fails for any reason, an alert panel is displayed with NSRunAlertPanel(). If the document's image is
successfully saved, [[self documentWindow] setDocumentEdited:NO] is called to tell the window that
the document has not been edited since it was saved. The _myHasEverBeenSaved instance variable is set to YES.

- (void)_mySaveDocumentData
/*" Save the document's image to the document's path. Displays an alert panel
if the image is not saved correctly. "*/
{
NSData *imageData = [[imageView image] TIFFRepresentation];

if(![imageData writeToFile:[self documentPath] atomically:YES])

{
// The image was not saved correctly
NSRunAlertPanel(MYFILE_SAVE_ERROR, MYFILE_SAVE_ERROR_MSG,
nil, nil, nil, [self documentPath]);
}
else
{
// The image was saved correctly
[[self documentWindow] setDocumentEdited:NO];
_myHasEverBeenSaved = YES;
}
}

The primary difference between -saveDocument: and -saveDocumentAs: is that -saveDocumentAs:

displays a standard Cocoa Save panel that gives the user a chance to specify the path at which the document is saved
or the save is cancelled.

The -saveDocument: method checks to make sure the document's path specifies an existing file and not a
directory. If the document's path does not exist or is a directory or the document has never been saved, -
saveDocument: calls -saveDocumentAs: so that the user has a chance to specify a path. If there is no
problem with the document's path, -saveDocument: calls -_mySaveDocumentData to save the document's
image.

- (IBAction)saveDocument:(id)sender
/*" Save the image data displayed by the document "*/
{
BOOL pathExists;
BOOL pathIsDirectory;

// check to see if a directory exists at document path

pathExists = [[NSFileManager defaultManager] fileExistsAtPath:
[self documentPath] isDirectory:&pathIsDirectory];
if(![self hasEverBeenSaved] || pathIsDirectory || nil == [self
documentPath])
{
// The image has never been saved or it has no path or there is a
directory
// at its path. Use -saveDocumentAs: because is shows a Save panel to find
// out where the user wants to save the image.
[self saveDocumentAs:sender];
}
else
{
// Save the image data
[self _mySaveDocumentData];
}
}

The -saveDocumentAs: method displays the standard Cocoa Save panel encapsulated by the NSSavePanel
class. The Save panel enables users to specify a file system path by browsing in the file system. The Save panel can
be configured with a custom accessory view. The accessory view is used to extend the Save panel without the need to
subclass NSSavePanel or edit the .nib file that defines the Save panel. There is normally only one instance of
NSSavePanel in each application, and that instance is accessed by calling [NSSavePanel savePanel].

NSSavePanel supports many configuration options documented at http://developer.apple.com/techpubs/macosx/

Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSSavePanel.html#//apple_ref/occ/instm/NSSavePanel/
setAccessoryView. NSSavePanel's -filename and -URL methods return the full path to the file that the user
selected. The -directory method returns the path to the directory that contains the file that the user selected.

MYDocument's -saveDocumentAs: method uses NSSavePanel's -setRequiredFileType: method to

set the file type to tiff. It also uses NSSavePanel's -setTreatsFilePackagesAsDirectories: to
configure the panel so that users are not able to select paths inside file packages that do not look like directories in
Finder.

The Save panel is displayed and run in a modal loop using NSSavePanel's -runModalForDirectory:
file: method. Modal loops are described in more detail in the "Modal Loops" section of this chapter.

If the user selects a path and clicks the Save panel's default button, the document's path is set to the selected path, and
the document is saved using -_mySaveDocumentData.

- (IBAction)saveDocumentAs:(id)sender
/*" Displays a Save panel to find out where the user wants to save the
document's image data. If the user does not cancel the save, this method saves
the image data at the specified location. "*/
{
NSSavePanel *savePanel;
NSString *documentDirectory = [[self documentPath]
stringByDeletingLastPathComponent];
NSString *documentName = [[self documentPath] lastPathComponent];

savePanel = [NSSavePanel savePanel];

[savePanel setRequiredFileType:@"tiff"];
[savePanel setTreatsFilePackagesAsDirectories:NO];

if (NSOKButton == [savePanel runModalForDirectory:documentDirectory

file:documentName])
{
[self _mySetDocumentPath:[savePanel filename]];
[self _mySaveDocumentData];
}
}

The last action method implemented by MYDocument is - noteImageWasDropped:. MYDocument's -

initWithPath: method makes each document instance the target of the corresponding image view. The image
view calls the document's -noteImageWasDropped: method when an image is dragged and dropped on the
image view. The - noteImageWasDropped: is implemented to tell the document's window that the document
has been edited.

- (IBAction)noteImageWasDropped:(id)sender
/*" Called by document's image view when the image changes. "*/
{
// The image has changed so note that the document has been edited.
[[self documentWindow] setDocumentEdited:YES];

// Make the image view a reasonable size for the image displayed
[imageView setFrameSize:[[imageView image] size]];
}

Menu Validation

MYDocument implements the -validateMenuItem: method to validate the menu items that send the
saveDocument: and saveDocumentAs: actions. Menu validation is explained in Chapter 8.

- (BOOL)validateMenuItem:(NSMenuItem *)aMenuItem
/*" Validate menu items that send the saveDocument: and
saveDocumentAs: actions. "*/
{
SEL action = [aMenuItem action];
BOOL enableMenuItem = NO;

if (action == @selector(saveDocument:))
{
// If the document has never been saved or has been edited since it was
 // saved then enable the menu item that sends saveDocument:
enableMenuItem = [self isDocumentEdited] || ![self hasEverBeenSaved];
}
else if (action == @selector(saveDocumentAs:))
{
// Always enable the menu item that sends saveDocumentAs:.
enableMenuItem = YES;
}

return enableMenuItem;
}

Using NSWindow Delegate Methods

MYDocument implements three window delegate methods: - windowShouldClose:, -

windowWillClose:, and -windowDidBecomeKey:.

The -windowShouldClose: method is called by NSWindow when the window is about to close because the
user clicked the Close button on the window's title bar. It is implemented to give users a chance to save unsaved
documents before closing and returns the result of calling -_myShouldClose.

The -windowWillClose: method is called by NSWindow just before a window is closed. By the time -
windowWillClose: is called, it is too late to cancel the close. MYDocument implements -
windowWillClose: to set the document's imageView instance variable to nil and send the
documentWillClose: action message using the responder chain. The argument to the
documentWillClose: method is the document that is closing. Objects in the responder chain can implement -
documentWillClose: to update references they might have to the document being closed. For example, when a
MYDocumentManager instance receives the documentWillClose: message, it removes the document from
an array of open documents.

The -windowDidBecomeKey: method sends the makeDocumentActive: action message up the responder
chain with the document as the argument. When a MYDocumentManager instance receives the
makeDocumentActive: message, it makes the document the active document.

- (BOOL)windowShouldClose:(id)sender
/*" Give users a chance to save edited documents before they close and/or
cancel the close. "*/
{
return [self _myShouldClose];
}

- (void)windowWillClose:(NSNotification *)notification
/*" Tell document manager that document is closing. "*/
{
imageView = nil; // don't keep reference to closed window
[NSApp sendAction:@selector(documentWillClose:) to:nil from:self];
}

- (void)windowDidBecomeKey:(NSNotification *)notification
/*" Tell document manager to make the receiver the active document "*/
{
[NSApp sendAction:@selector(makeDocumentActive:) to:nil from:self];
}
The -windowWillClose: and -windowDidBecomeKey: methods use the responder chain to keep the
document manager informed of changes in managed documents. These methods could have been implemented to
send notifications that are observed by the document manager instead of using the responder chain. Messages could
also have been sent directly to the application's delegate by calling [[NSApp delegate]
documentWillClose:self] and [[NSApp delegate] makeDocumentActive:self] after first
checking to make sure that the application's delegate responds to the messages. The choice to use the responder chain
was arbitrary in this case. The responder chain, notifications, and delegates are all techniques for loosely coupling the
sender of a message to the receiver. The "Delegation Versus Notifications" section of Chapter 8 describes some of
the tradeoffs of using different techniques. The responder chain offers yet another option.

Concluding MYDocument's Implementation

Most classes that store object instance variables need to implement the -dealloc method to release the instance
variables. MYDocument has the imageView and _myDocumentPath object instance variables.

There is no need to release imageView because it is set when the document's .nib file is loaded and
MYDocument never explicitly retains it. When the window that contains the image view closes, it releases all the
objects it contains. If no other object retains the image view, it is deallocated. MYDocument implements -
windowWillClose to set imageView to nil when the window closes so that MYDocument does not have a
reference to a possibly deallocated object.

MYDocument does retain its _myDocumentPath instance variable and, therefore, must release it in -dealloc.

- (void)dealloc
/*" Clean-up "*/
{
[_myDocumentPath release];
[super dealloc];
}

The MYDocument implementation is concluded with the @end compiler directive.

@end

Saving Window Frames in User Defaults

The Image Viewer application does not explicitly save the frames of any windows in the user's defaults database, but
it is described here because NSWindow supports that feature. When a window's frame is saved in the defaults
database, the window's position and size become persistent. The user can quit the application and when it is launched
again, the windows are restored with the same position and size they had when the application was last quit. Because
each user has a different defaults database, each user can store different window frames for the same windows.

NSWindow's -(void)saveFrameUsingName:(NSString *)name method saves the window's frame

rectangle in the user's defaults database. The defaults database is described in Chapter 7. The name argument to -
saveFrameUsingName: is the key used to retrieve the saved default value.

NSWindow's -(BOOL)setFrameUsingName:(NSString *)name method retrieves the window frame

previously stored in the default database with the key name and sets the window's frame to the stored value. The -
setFrameUsingName: method returns YES if the stored frame was successfully read and NO otherwise.

Windows can be configured to automatically save its frame in the user's defaults database by calling NSWindow's -
(BOOL)setFrameAutosaveName:(NSString *)name method. After a window is given an autosave name,
it automatically updates its frame stored in the defaults database when the window is moved or resized. The -
setFrameAutosaveName: returns YES if the frame is successfully saved by using name as the key and NO
otherwise.

Document windows shouldn't save their frames in the user's defaults database. If every window saves its frame, the
defaults database will become very large, and users have no easy way to remove window frames from their defaults
database. Reserve the use of saved frames for windows that benefit most from the feature. For example, Interface
Builder stores the frames of its Palette window and Show Info window. Utility windows such as palettes and tool
windows are good candidates for the frame saving feature because there are usually not very many of them and each
user probably has a preferred arrangement and size for them.

Transparent Windows

Cocoa windows can be transparent, and Cocoa can simulate nonrectangular windows. Apple provides the
RoundTransparentWindow sample at http://developer.apple.com/samplecode/Sample_Code/Cocoa/
RoundTransparentWindow.htm. The key features of the sample show how to change the shape of a window and how
to recalculate the window's drop shadow.

NSWindow's -setOpaque: method is used to make the background behind a window show through the window's
transparent portions. The -setAlphaValue: method sets the overall transparency of the window. Calling -
setAlphaValue: with 1.0 as the argument makes the parts of the window that are not drawn in a transparent
color fully opaque. Setting the window's alpha value to zero makes the entire window invisible. The -
setBackgroundColor: method is used to set the background to a transparent color. Finally, -
setHasShadow: enables or disables the drawing of the window's drop shadow.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with NSApplication

The NSApplication class is the primary interface between Cocoa applications and the operating system. Each
Cocoa application has exactly one instance of the NSApplication class. NSApplication is seldom subclassed.
It provides delegate methods and notifications that enable customization of application behavior without the need to
subclass.

To show how NSApplication's delegate methods are used, the MYDocumentManager class is created. An
instance of MYDocumentManager is the application's delegate in the new Image Viewer application and manages
open documents. MYDocumentManager also allows review and saving of unsaved documents when the
application quits.

NSApplication's Delegate

The MYDocumentManager class needs to know when an application is terminating so that it can prompt the user
to save unsaved documents. It also needs to know when users have double-clicked a document in Finder or dragged a
document onto its application's icon.

An instance of the NSApplication class sends messages to its delegate informing the delegate when the
application is terminating. Delegate methods are called when the application has finished launching, when files need
to be opened or printed, and when AppleScript events are received.

The "Methods Implemented By the Delegate" section of NSApplication's class documentation lists the following
delegate methods:

- (void)applicationWillFinishLaunching:(NSNotification *)notification;
- (void)applicationDidFinishLaunching:(NSNotification *)notification;
- (void)applicationWillHide:(NSNotification *)notification;
- (void)applicationDidHide:(NSNotification *)notification;
- (void)applicationWillUnhide:(NSNotification *)notification;
- (void)applicationDidUnhide:(NSNotification *)notification;
- (void)applicationWillBecomeActive:(NSNotification *)notification;
- (void)applicationDidBecomeActive:(NSNotification *)notification;
- (void)applicationWillResignActive:(NSNotification *)notification;
- (void)applicationDidResignActive:(NSNotification *)notification;
- (void)applicationWillUpdate:(NSNotification *)notification;
- (void)applicationDidUpdate:(NSNotification *)notification;
- (void)applicationWillTerminate:(NSNotification *)notification;
- (void)applicationDidChangeScreenParameters:(NSNotification *)notification;
- (NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication *)sender;
- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
- (BOOL)application:(NSApplication *)sender openTempFile:(NSString *)filename;
- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender;
- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;
- (BOOL)application:(id)sender openFileWithoutUI:(NSString *)filename;
- (BOOL)application:(NSApplication *)sender printFile:(NSString *)filename;
- (BOOL)applicationShouldTerminateAfterLastWindowClosed:
(NSApplication *)sender;
- (BOOL)applicationShouldHandleReopen:(NSApplication *)sender
hasVisibleWindows:(BOOL)flag;
- (NSMenu *)applicationDockMenu:(NSApplication *)sender;
- (BOOL)application:(NSApplication *)sender delegateHandlesKey:(NSString *)
key;

The delegate methods that do not require any return value have a single argument that is an NSNotification
instance. In each case, the NSApplication instance that sent the delegate message is obtained by sending the -
object message to the notification argument. The delegate methods that return a value all include the
NSApplication instance that sent the delegate message as an argument. Apple's class documentation describes
how each delegate method is used and when it is called.

The MYDocumentManager class implements the following application delegate methods:

- (NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication *)sender;
- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender;
- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

The -applicationShouldTerminate: method is implemented to check for any unsaved documents and give
users a chance to save them. The -application:openFile: method is implemented to open documents when
they are double-clicked in Finder or dropped on an application icon. Finally, the -
applicationShouldOpenUntitledFile: and -applicationOpenUntitledFile: methods control
how the application handles untitled documents.

The MYDocumentManager class works closely with the NSApplication class to implement features that users
expect from multidocument applications. Because an instance of the MYDocumentManager class is the delegate of
the NSApplication instance, the document manager is automatically added to the responder chain and can
receive action messages sent up the responder chain. MYDocumentManager implements three actions that are sent
by user interface objects such as menu items: -newDocument:, -openDocument:, and -
saveAllDocuments:. The MYDocumentManager instance receives these action messages when user interface
objects send them up the responder chain and no other object handles them. MYDocumentManager also
implements the -documentWillClose: and -makeDocumentActive: actions that are sent up the responder
chain by NSDocument instances.

The -validateMenuItem: method implemented by MYDocumentManager is called automatically before

menu items become visible. When a menu item is about to be displayed, it searches the responder chain for an object
that responds to its action. When a suitable object is found, the menu item sends the -validateMenuItem:
message to that object passing the menu item to be validated as an argument. MYDocumentManager implements -
validateMenuItem: to enable or disable menu items that send the -newDocument:, -openDocument:, or
-saveAllDocuments: actions.

Creating and Configuring MYDocumentManager

To add the MYDocumentManager class to the Image Viewer project and make an instance of
MYDocumentManager the application's delegate, Open Image Viewer's MainMenu.nib file in Interface Builder
by double-clicking it within the Resources folder in the Files tab of Project Builder's Project pane. Figure 9.1 shows
the MainMenu.nib file selected in Project Builder.

After Interface Builder has loaded Image Viewer's MainMenu.nib file, select the Classes tab in Interface Builder's
window titled MainMenu.nib and select the NSObject class. Create a new subclass of NSObject using
Interface Builder's Classes, Subclass NSObject menu item.

Name the new subclass MYDocumentManager. Make sure the MYDocumentManager class is selected and uses
the Classes, Instantiate MYDocumentManager menu to create an instance of the MYDocumentManager class.
When the new instance is created, Interface Builder automatically displays the Instances tab shown in Figure 9.8.
Make sure the MYDocumentManager instance is selected as shown.

Figure 9.8. A new MYDocumentManager instance is selected in MainMenu.nib's Instances tab.

Drag a connection line from the icon labeled File's Owner to the new instance of MYDocumentManager as shown
in Figure 9.9. Hold the Ctrl key while dragging with the mouse to draw connection lines. When the mouse button is
released after drawing a connection line, Interface Builder automatically displays a Show Info window in
Connections mode. Figure 9.9 shows the Show Info window titled File's Owner Info.

Figure 9.9. A connection line is drawn from File's Owner to the MYDocumentManager instance, and the
File's Owner Info window is displayed ready to make a connection.

Select the delegate outlet displayed in the Outlets column of the window titled File's Owner Info and click the
Connect button. The File's Owner of the MainMenu.nib file is the application object. The instance of
MYDocumentManager is now the application's delegate.

Switch to the Classes tab of the MainMenu.nib window and select the MYDocumentManager class. Use
Interface Builder's Classes, Create Files for MYDocumentManager menu item to create the files that will contain
the interface and implementation of the MYDocumentManager class. Interface Builder displays a sheet asking
where to store the new files within the Image Viewer project. Select the folder that contains the Image Viewer project
and click the Choose button at the bottom of the sheet.

The next step is to make connections between the Image Viewer's menu items and the First Responder.

NOTE
 The First Responder icon in Interface Builder is just a placeholder for whichever object is actually the
first responder at any given moment while an application is running.

The user interface-related actions that MYDocumentManager implements are standard. Interface Builder already
knows that newDocument:, openDocument:, and saveAllDocuments: are messages that can be sent to the
First Responder. It is possible to add actions to First Responder so that custom actions can be used with the responder
chain, but that is not necessary yet in this example.

Select Image Viewer's File, New menu item in the window titled MainMenu.nib - Main menu, which is shown
in Figure 9.10. Draw a connection line from the File, New menu item to the First Responder Icon.

Figure 9.10. A connection line from the File, New menu item to the First Responder icon is shown with the
target outlet and the newDocument: action selected.

Connect the target outlet to the newDocument: action, as shown in Figure 9.10. When Image Viewer is running
and the File, New menu item is clicked, the newDocument: action will be sent up the responder chain. If no other
object in the responder chain responds to newDocument:, MYDocumentManager's -newDocument: method
will be called.

NOTE

If Project Builder's Multi-Document Cocoa application project template is used when a project is
created, Project Builder automatically makes the connections from standard File menu items to the First
Responder. The connections are made manually in this example to show how the connections work.

Use the same technique to connect Image Viewer's File, Open menu item to the First Responder's openDocument:
action. Connect the File, Save menu item to the First Responder's saveDocument: action. Connect the File, Save
As menu item to the First Responder's saveDocumentAs: action. Next, add a new menu item to Image Viewer's
File menu by dragging a menu item from Interface Builder's Cocoa-Menus palette, as shown in Figure 9.11.

Figure 9.11. A new menu item is added to Image Viewer's File menu.

Name the new menu item Save All. Connect the File, Save All menu item to the First Responder's
saveAllDocuments: action.

NOTE

The -saveDocument: and -saveDocumentAs: methods are implemented by MYDocument not

MYDocumentManager. The connections made to the First Responder work for documents as well as
the document manager because instances of both classes are in the responder chain when Image Viewer
is run.

Save Image Viewer's MainMenu.nib and hide Interface Builder, and then return to Project Builder.

Implementing MYDocumentManager

The project for Viewer needs to contain the MYDocumentManager.h and MYDocumentManager.m files that
were created with Interface Builder's Classes, Create Files for MYDocumentManager menu item. If they are not in
the project, add them now using Project Builder's Project, Add Files menu item. Edit the MYDocumentManager.h
file in Project Builder so that it contains the following code for the MYDocumentManager class interface.

File MYDocumentManager:

#import <Cocoa/Cocoa.h>
@interface MYDocumentManager : NSObject
{
NSMutableArray *_myOpenDocuments; /*" Array of open documents "*/
NSPoint _myWindowCascadePoint; /*" Used to cascade windows "*/
}

/*" Designated initializer "*/

- (id)init;

/*" Document class "*/

- (Class)documentClass;

/*" Document loading "*/

- (NSArray *)documentExtensions;

/*" Accessing open documents "*/

- (NSArray *)existingOpenDocuments;
- (id)existingOpenDocumentWithPath:(NSString *)aPath;
- (id)activeDocument;

/*" Document actions "*/

- (IBAction)openDocument:(id)sender;
- (IBAction)newDocument:(id)sender;
- (IBAction)saveAllDocuments:(id)sender;

/*" Document communication actions "*/

- (void)documentWillClose:(id)sender;
- (void)makeDocumentActive:(id)sender;
/*" Application delegate methods "*/
- (NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication *)sender;
- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender;
- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

@end

The implementation of MYDocumentManager begins by importing the class interfaces in

MYDocumentManager and MYDocument.

#import "MYDocumentManager.h"
#import "MYDocument.h"

@implementation MYDocumentManager
/*" A single instance of this class is used as the application's delegate and
manages documents in a multi-document application.

There is a single "active" document at any time. The "active" document is

usually the document that controls that last key window, but the active
document can be set programmatically.
"*/

The following localizable strings are used in MYDocumentManager.m:

/*" Constant local strings "*/
#define MYQUIT NSLocalizedString(@"Quit", @"")
#define MYOPEN NSLocalizedString(@"Open Error", @"")
#define MYOPEN_DOCUMENT_ERROR_MSG NSLocalizedString(\
@"Unable to open document.", @"")
#define MYNEW_DOCUMENT_ERROR_MSG NSLocalizedString(\
@"Unable to create new document.", @"")
#define MYUNSAVED_DOCS_MSG NSLocalizedString(\
@"There are unsaved documents.\nReview them?", @"")
#define MYCANCEL NSLocalizedString(@"Cancel", @"")
#define MYQUIT_ANYWAY NSLocalizedString(@"Quit Anyway", @"")
#define MYREVIEW_UNSAVED NSLocalizedString(@"Review", @"")
#define MYUNTITLED NSLocalizedString(@"Untitled", \
@"The name of untitled documents")

Initializing the MYDocumentManager Instance

The one and only instance of MYDocumentManager in the Image Viewer application is instantiated inside the
MainMenu.nib file. Because the MYDocumentManager instance is never initialized programmatically, its
designated initializer is never called. Instead, its -awakeFromNib method is called after it is loaded from
MainMenu.nib. Objects that are instantiated in Interface Builder often need similar initialization logic in both -
awakeFromNib and the designated initializer.

Instead of duplicating initialization code in both -init and -awakeFromNib, MYDocumentManager

implements the private -_myInitInstanceVariables method that is called from -init and -
awakeFromNib.

The -_myInitInstanceVariables method allocates and initializes a mutable array to store the open
documents. It also initializes the _myWindowCascadePoint instance variable to the upper-left corner of the
visible area of the main screen obtained by using the NSScreen class. NSScreen is described in the "Working
with Screens" section of this chapter.

- (void)_myInitInstanceVariables
/*" Initialize instance variables: called by -init and -awakeFromNib. "*/
{
NSRect screenVisibleFrame = [[NSScreen mainScreen] visibleFrame];

// Create array of open documents

_myOpenDocuments = [[NSMutableArray allocWithZone:[self zone]] init];

// Set initial cascade point

_myWindowCascadePoint = NSMakePoint(0, NSMaxY(screenVisibleFrame));
}

- (id)init
/*" Designated initializer "*/
{
self = [super init];

if(nil != self)
{
[self _myInitInstanceVariables];
}
 return self;
}
- (void)awakeFromNib
/*" Called automatically after receiver is fully loaded from a nib file. "*/
{
[self _myInitInstanceVariables];
}

Document Information Methods

The -documentClass and -documentExtensions methods provide information about the types of
documents managed by MYDocumentManager. The -documentClass method returns the class that is used to
create document instances. It is currently hard coded to return the MYDocument class, but it could be reimplemented
to return different document classes in different applications.

- (Class)documentClass
/*" Returns the class used to encapsulate documents "*/
{
return [MYDocument class];
}

The -documentExtensions method returns an array of file extensions that identify files that can be opened by
Image Viewer. It is implemented to return the array of extensions supported by the document class or an empty array.
When the array returned by this method is used to limit files that can be opened with an Open panel, an empty array
means that any file type can be opened.

- (NSArray *)documentExtensions;
/*" Returns an array of NSString file extensions for documents that can be
opened. This implementation returns an array containing elements obtained
by calling [[self documentClass] documentExtensions]. Override this method
to provide more sophisticated behavior and support multiple document classes.
To allow any opening of documents with any extension or no extension,
override this method to return an empty array. "*/
{
NSMutableArray *supportedExtensions = [NSMutableArray array];
Class documentClass = [self documentClass];

if([documentClass respondsToSelector:@selector(documentExtensions)])
{
[supportedExtensions addObjectsFromArray:
[documentClass documentExtensions]];
}
return supportedExtensions;
}

Accessing Open Documents

The -existingOpenDocuments method returns an array of open document instances. The -

existingOpenDocumentWithPath: method returns the open document with the specified path or nil if no
open document has that path. The use of standardized paths means that different paths that reference the same file
through file system links are considered to be the same path. The -activeDocument method returns the current
active document or nil. The active document is the usually the document associated with the last document window
that was the key window.

- (NSArray *)existingOpenDocuments
/*" Returns an array of open documets. "*/
{
return _myOpenDocuments;
}

- (id)existingOpenDocumentWithPath:(NSString *)aPath
/*" Returns the open document with the specified path or nil. "*/
{
NSString *standardPath = [aPath stringByStandardizingPath];
id result = nil;
id currentDocument = nil;
NSEnumerator *enumerator = [_myOpenDocuments objectEnumerator];

while(nil == result && nil != (currentDocument = [enumerator nextObject]))

{
if([currentDocument respondsToSelector:@selector(documentPath)])
{
// the current document has a path
if([[currentDocument documentPath] isEqualToString:standardPath])
{
// currentDocument has aPath
result = currentDocument;
}
}
}

return result;
}
- (id)activeDocument
/*" Returns the active document or nil. The active document is usually the
last document who's window was key. "*/
{
// The last object in _myOpenDocuments is assumed to be the active document
return (0 < [_myOpenDocuments count]) ? [_myOpenDocuments lastObject] : nil;
}

Creating Document Instances

When new untitled documents are created, it is important that they do not inadvertently have the same name as an
existing file in the file system. If a new document has the same name as an existing file, the user might be misled to
think that the new document shows the contents of the existing file when in fact it is a document that has never been
saved.

The private -_myNextUntitledDocumentName method returns a variant of the path, ~/Untitled, that does
not reference an existing file in the file system.

- (NSString *)_myNextUntitledDocumentName
/*" Returns an NSString with a unique untitled document name by appending an
integer to the string "Untitled" and the first document extension in the array
returned by -documentExtensions. "*/
{
static int lastUntitledIndex = 1;
NSString *result = nil;
NSString *extension = @"";
NSArray *documentExtensions = [self documentExtensions];
 if(0 < [documentExtensions count])
{
// documentExtensions has at least 1 element so use last element as
// default untitled document extension
extension = [documentExtensions lastObject];
}

do
{
[result release]; // release string from previous iteration
// (nil on first iteration)

result = [[NSString alloc] initWithFormat:@"~/%@%d.%@", MYUNTITLED,

lastUntitledIndex++, extension];
}
while([[NSFileManager defaultManager] fileExistsAtPath:
[result stringByStandardizingPath]]);

[result autorelease];

return result;
}

The private -_myRegisterDocument: method is called by the -_myOpenDocumentWithPath: and -

newDocument: methods. This method adds a document to the array of open documents, positions the document's
window so that it cascades nicely with other document windows, and makes the document's window the key window.
A side effect of making the document's window key is that the associated document becomes the active document.

The _myWindowCascadePoint instance variable is initialized to the top-left corner of the visible area of the
main screen in -_myInitInstanceVariables. The first open document window is positioned at
_myWindowCascadePoint. Then, _myWindowCascadePoint is set to a new position down and to the right
so that the next window's position is offset enough not to obscure the title of the previous window.

- (void)_myRegisterDocument:(id)aDocument
/*" Adds aDocument to the receiver's array of open documents, makes
aDocument's window visible on screen, and makes aDocument the active
document. "*/
{
[_myOpenDocuments addObject:aDocument];

if([aDocument respondsToSelector:@selector(documentWindow)])
{
id documentWindow = [aDocument documentWindow];

// Cascade the registered document's window

_myWindowCascadePoint = [documentWindow cascadeTopLeftFromPoint:
_myWindowCascadePoint];

// make registered document's window visible and key

[documentWindow makeKeyAndOrderFront:self];
}
}

The private -_myOpenDocumentWithPath: method checks to see if an existing open document already
represents the specified path. If so, the window associated with the open document is made key and ordered front,
which indirectly causes the open document to become the active document. If no open document references the
specified path, a new document instance is created with the [[[self documentClass] allocWithZone:
[self zone]] initWithPath:aPath] expression. MYDocumentManager's -documentClass method
returns the MYDocument class. MYDocument implements the -initWithPath: method to load the image data
at the specified path.

- (void)_myOpenDocumentWithPath:(NSString *)aPath
{
id newDocument = [self existingOpenDocumentWithPath:aPath];

if(nil != newDocument)
{ // an existing open document already has currentPath
[[newDocument documentWindow] makeKeyAndOrderFront:self];
}
else
{ // no open document already has currentPath
newDocument = [[[self documentClass] allocWithZone:[self zone]]
initWithPath:aPath];
if(nil == newDocument)
{
NSLog(@"%@", MYOPEN_DOCUMENT_ERROR_MSG);
}
else
{
[self _myRegisterDocument:newDocument]; // Retains newDocument
[newDocument release];
}
}
}

The - openDocument: action method displays the standard Cocoa Open panel encapsulated by the
NSOpenPanel class. The Open panel enables users to select one or more file system paths by browsing in the file
system. The Open panel can be configured with a custom accessory view. The accessory view is used to extend the
Open panel without the need to subclass NSOpenPanel or edit the .nib file that defines the Open panel. There is
normally only one instance of NSOpenPanel in each application, and that instance is accessed by calling
[NSOpenPanel openPanel].

NSOpenPanel supports many configuration options documented at http://developer.apple.com/techpubs/macosx/

Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSOpenPanel.html. NSOpenPanel's -filenames
method returns an array of the full paths selected by the user. The -directory method returns the path to the
directory that contains the files selected by the user.

- (IBAction)openDocument:(id)sender
/*" Displays an open panel that allows selections of multiple paths and opens
the selected files. In this implementation, individual files can be selected
and directories can not. The paths that are selected must have one of the
extensions in the array returned by -documentExtensions. If the array
returned from -documentExtensions is empty, any path is accepted. "*/
{
NSArray *typesArray;
NSOpenPanel *openPanel;
NSString *directory;
id activeDocument;

typesArray = [self documentExtensions];

 if(0 == [typesArray count])
{
// Set fileTypesArray to nil so that any type is accepted
typesArray = nil;
}
activeDocument = [self activeDocument];

if(nil != activeDocument && [activeDocument respondsToSelector:

@selector(documentPath)])
{
// Use active document's directory as initial directory
directory = [[activeDocument documentPath]
stringByDeletingLastPathComponent];
} else {
directory = @"";
}

// Configure the open panel

openPanel = [NSOpenPanel openPanel];
[openPanel setAllowsMultipleSelection:YES];
[openPanel setTreatsFilePackagesAsDirectories:NO];
[openPanel setDirectory:directory];
[openPanel setCanChooseDirectories:NO];
[openPanel setCanChooseFiles:YES];
[openPanel setResolvesAliases:YES];

if (NSOKButton == [openPanel runModalForTypes:typesArray])

{
NSArray *selectedPaths = [openPanel filenames];
NSEnumerator *enumerator = [selectedPaths objectEnumerator];
NSString *currentPath;

while(nil != (currentPath = [enumerator nextObject]))

{
[self _myOpenDocumentWithPath:currentPath];
}
}
}

The -newDocument: action method creates a new document with an ~/Untitled path.

- (IBAction)newDocument:(id)sender
/*" Creates a new instance of the class returned from the -documentClass.
The new document is given a unique title and made the active document. "*/
{
id newDocument;
NSString *newDocumentPath = [self _myNextUntitledDocumentName];

newDocument = [[[self documentClass] allocWithZone:[self zone]]

initWithPath:newDocumentPath];
if(nil == newDocument)
{
NSLog(@"%@", MYNEW_DOCUMENT_ERROR_MSG);
}
else
{
 [self _myRegisterDocument:newDocument]; // Retains newDocument
[newDocument release];
}
}

Saving All Open Documents

The -saveAllDocuments: action method could not be simpler. It just sends the saveDocument: message to
every open document.

- (IBAction)saveAllDocuments:(id)sender

/*" This method sends the saveDocument: message to all open documents. "*/

[[self existingOpenDocuments] makeObjectsPerformSelector:

@selector(saveDocument:) withObject:sender];

Messages Sent by Documents

MYDocument instances send the documentWillClose: action message up the responder chain when the
document's window is about to be closed. The -documentWillClose: method is received by the
MYDocumentManager instance because it is the application's delegate. MYDocumentManager implements -
documentWillClose: to remove the document that is closing from the array of open documents. The array of
open documents releases the document instance that is removed from the array. If the array of open documents is the
only object that retained the removed document, the document is immediately deallocated.

/*" Document communication actions "*/

- (void)documentWillClose:(id)sender
/*" Removes sender from receiver's open documents array "*/
{
[_myOpenDocuments removeObject:sender];
}

MYDocument instances send the makeDocumentActive: action message up the responder chain when the
document's window becomes the key window. MYDocumentManager implements -makeDocumentActive:
to make the sender of makeDocumentActive: the active document.

- (void)makeDocumentActive:(id)sender
/*" Sets the receiver's active document to sender if possible. If sender is
not an open document, this method does nothing. This method does not make
sender's window key. "*/
{

if(0 < [_myOpenDocuments count])

{
// There is at least 1 open document
int index = [_myOpenDocuments indexOfObject:sender];

if(index != NSNotFound)
 {
// anObject is an open document
// Swap positions in _myOpenDocuments: the last object in
// _myOpenDocuments is assumed to be the active document
[sender retain];
[_myOpenDocuments replaceObjectAtIndex:index withObject:
[_myOpenDocuments lastObject]];
[_myOpenDocuments removeLastObject];
[_myOpenDocuments addObject:sender];
[sender release];
}
}
}

Menu Validation

MYDocumentManager implements -validateMenuItem: to validate menu items that send the

openDocument:, newDocument:, and saveAllDocuments: actions.

/*" Menu validation "*/

- (BOOL)validateMenuItem:(NSMenuItem *)aMenuItem
/*" Validate menu items that send the openDocument:, newDocument:, or
saveAllDocuments: actions. "*/
{
SEL action;
BOOL enableMenuItem = NO;

action = [aMenuItem action];

// The -open:, -new: and -saveAll: actions are provided by this calss and
// therefore validated by this class.
if (action == @selector(openDocument:) || action == @selector(newDocument:))
{
enableMenuItem = YES;
}
else if (action == @selector(saveAllDocuments:))
{
enableMenuItem = (0 < [_myOpenDocuments count]);
}

return enableMenuItem;
}

Using NSApplication Delegate Methods

When user quits a graphical Cocoa application, NSApplication sends the

applicationShouldTerminate: message to its delegate. The values that can be returned from -
applicationShouldTerminate: are the constants NSTerminateNow, NSTerminateCancel, and
NSTerminateLater. Returning NSTerminateNow gives the application permission to terminate immediately.
Returning NSTerminateCancel cancels the termination. Returning NSTerminateLater postpones the
decision to terminate or not until NSApplication's -replyToApplicationShouldTerminate: method is
called with a YES or NO argument.

MYDocumentManager implements -applicationShouldTerminate: to give users a chance to save

unsaved documents before the application terminates.
/*" Application delegate methods "*/
- (NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication *)sender
/*" Implemented to Give user a chance to review and save any unsaved documents
before terminating "*/
{
NSEnumerator *enumerator;
id currentDocument;
int choice;
NSApplicationTerminateReply result = NSTerminateNow;
BOOL foundUnsaved = NO;

// Catch exception during review and save

// Determine if theer are any unsaved documents

enumerator = [_myOpenDocuments objectEnumerator];
while(!foundUnsaved && nil != (currentDocument = [enumerator nextObject]))
{
if([currentDocument respondsToSelector:@selector(isDocumentEdited)])
{
// Found at least one unsaved document
foundUnsaved = [currentDocument isDocumentEdited];
}
}

if(foundUnsaved)
{
// Find out of the user wants to review and possibly save the unsaved
// documents, cancel the termination, or terminate anyway
choice = NSRunAlertPanel(MYQUIT, MYUNSAVED_DOCS_MSG, MYREVIEW_UNSAVED,
MYQUIT_ANYWAY, MYCANCEL);
if (choice == NSAlertOtherReturn)
{ // User selected Cancel
result = NSTerminateCancel;
}
else if (choice != NSAlertAlternateReturn)
{ // User selected Review Unsaved
// Give the user the chance to review the edited document(s). */
enumerator = [_myOpenDocuments objectEnumerator];
while(result == NSTerminateNow &&
nil != (currentDocument = [enumerator nextObject]))
{
if([currentDocument respondsToSelector:@selector(safeClose)])
{
// Cause unsaved documents to show a save panel
if(![currentDocument safeClose])
{ // User selected Cancel
result = NSTerminateCancel;
}
}
}
}
else
{ // User chooses to quit without saving
}
}
 return result;
}

When a user double-clicks a file in Finder, the user's default application for the file is launched, if it is not already
running, and notified that it should open the file that was double clicked. When that happens, NSApplication
sends the application:openFile: message to its delegate. The application:openFile: message is
also sent to the application's delegate when files are dragged and dropped onto the application's icon.

MYDocumentManager implements -application:openFile: to verify that the file to open is a supported

type, and then calls -_myOpenDocumentWithPath: to open the file. If the file is opened, -application:
openFile: returns YES; otherwise it returns NO. The value returned is sent back to Finder, which displays a short
animation if files are not opened after a drag and drop.

- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename

/*" Called automatically when application is requested to open a document
either by drag and drop or double clicking in finder. Returns YES if the
file is successfully opened, and NO otherwise "*/
{
int result = NO;

if([[self documentExtensions] containsObject:[filename pathExtension]])

{
// Filename has an accepted extension
[self _myOpenDocumentWithPath:filename];
result = YES;
}

return result;
}

According to Apple's user interface guidelines, when a document-based application is activated by the user, the
application must display a document window. If there are no open document windows, a new untitled document must
be created. NSApplication already implements most of that behavior. When Apple's guidelines require the
creation of an untitled document, NSApplication calls its delegate's -
applicationShouldOpenUntitledFile: method. If - applicationShouldOpenUntitledFile:
returns YES, NSApplication calls the delegate's -applicationOpenUntitledFile: method to open the
untitled file.

- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender
/*" Called automatically: returns YES meaning that it is OK to open an
untitled document. "*/
{
return YES;
}

- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender
/*" Called automatically when application is requested to open an untitled
document. This method is implemented to call [self newDocument:nil] "*/
{
[self newDocument:nil];

return YES;
}
Concluding MYDocumentManager's Implementation

MYDocumentManager implements the -dealloc method to release the _myOpenDocuments instance

variable. When _myOpenDocuments is deallocated, it releases all the objects it contains.

- (void)dealloc
/*" Claen-up "*/
{
[_myOpenDocuments release];
_myOpenDocuments = nil;

[super dealloc];
}

@end

Build and test the Image Viewer application. Drag image files from Finder and drop them in open Image Viewer
document windows. Test the automatic creation of untitled documents by closing all open Image Viewer documents,
making another application active, and then switching back to Image Viewer. Image Viewer now has almost all the
features of Apple's Preview application. Image Viewer could have been implemented with more features and fewer
lines of code by using Cocoa's NSDocument and NSDocumentController classes, but this implementation
shows how the NSApplication, NSWindow, NSSavePanel, and NSOpenPanel classes are used. The
NSDocument and NSDocumentController classes completely hide their interaction with NSApplication,
NSWindow, NSSavePanel, and NSOpenPanel.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Modal Loops

A modal loop is a loop that consumes all events so that it is not possible for the user to
interact normally with an application until the modal loop terminates. Modal loops are used
when the user's attention is required before the application can continue processing. For
example, modal loops are used when the user must acknowledge an error message before
continuing or when input is required.

Modal loops consume all events in an application, but users can use other applications,
move application windows, and hide applications even when modal loops are running.

Modal loops are started in two general ways: either an entire window is run in a modal loop
controlled by the NSApplication class, or an individual view implements its own
modal loop in code.

Using Modal Windows

To run an entire window in a modal loop, call NSApplication's -

runModalForWindow: method sending a window as the argument. The -
runModalForWindow: method does not return until the modal loop terminates. When -
runModalForWindow: is called, NSApplication sends all events to the modal
window until one of the NSApplication's -stopModal, -abortModal, or -
stopModalWithCode: methods is called to terminate the loop. The -stopModal
method is called to end a modal loop normally. For example, use -stopModal to end a
modal loop with the user clicking an OK button to acknowledge an error message. The -
abortModal method is called when abnormal termination is required. For example, -
abortModal should be called if the user closes a modal window by clicking the
window's close button in the title bar. Both -stopModal and -abortModal call -
stopModalWithCode:. The argument passed to -stopModalWithCode: is the
value that is ultimately returned from the call to -runModalForWindow: that started
the loop. The -stopModal method calls -stopModalWithCode: with the
NSRunStoppedResponse constant, and -abortModal calls -
stopModalWithCode: with the NSRunAbortedResponse constant.

NOTE

Modal windows normally consume all events received by the application.

However, NSWindow subclasses that override NSWindow's -
worksWhenModal method to return YES are able to receive events even
when a modal window is active. This capability should be used sparingly.
The NSRunAlertPanel() function used in Image Viewer is a convenience function
that calls NSApplication's -runModalForWindow: method. Many standard Cocoa
panels such as NSSavePanel, NSOpenPanel, and NSPrintPanel provide methods
that start modal loops using NSApplication's -runModalForWindow:. For
example, Image Viewer uses NSSavePanel's -runModalForDirectory:file:
method that starts a modal loop and does not return until the user selects a path or closes
the panel.

Apple provides a detailed explanation of modal loops controlled by the NSApplication

class at http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/
ProgrammingTopics/WinPanel/Concepts/UsingModalWindows.html. Apple's class
documentation for the NSApplication class includes sample code for starting and
ending modal loops. Apple's guidelines for when to use modal loops are provided at http://
developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/AHIGDialogs/
Types_of_Di_to_Use_Them.html.

Using Modal Views

Individual views can create their own modal loops that consume all events until the loop
terminates. This technique is described in Chapter 15, "Events and Cursors," with an
example. Apple also provides an example at http://developer.apple.com/techpubs/macosx/
Cocoa/TasksAndConcepts/ProgrammingTopics/BasicEventHandling/Tasks/
HandlingMouseEvents.html.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with Sheets

Modal windows normally consume all events received by the application and prevent users for working in other
windows within the same application. Modal windows require the user's undivided attention before the user can
continue working with the application. However, users can switch to other applications even when another
application is displaying a modal window. Modal windows are, therefore, called application modal windows
because each window can only affect one application.

A sheet is a document modal window. Each sheet is attached to another window. When a sheet is visible, it
consumes all events received by its associated window, but users can continue to use other windows in the same
application. Using sheets instead of application modal windows gives users more flexibility. In addition, when a
sheet displays an error or requires input for a particular document window, the association between the sheet and
the effected window is clear. Application modal windows that display errors or required input related to a particular
document can confuse users who lose track of which document is effected.

Only one sheet can be attached to a window at a time. Sheets emerge from another window's title bar with an
animation to catch the user's eye. Sheets should not be used with windows that do not have a title bar.

Sheets work best when there is a clear association between the information presented by the sheet and the
associated window. For example, a sheet for saving a document makes sense. The association between the sheet and
the document window makes it clear to the user which document is being saved.

Apple provides guidelines for when to use sheets at http://developer.apple.com/techpubs/macosx/Essentials/

AquaHIGuidelines/AHIGDialogs/Document_Mo_ogs_Sheets_.html.

To show how sheets are used with Cocoa, the Image Viewer application is modified to use sheets instead of
application modal windows when appropriate.

Changes to MYDocument to Support Sheets

The first change is made to the MYDocument class interface. An addition instance variable is needed to keep track
of whether the document's window should close when the user is finished with a Save sheet. Edit the
MYDocument.h file so that it has the following instance variable section:

@interface MYDocument : NSObject

{
IBOutlet NSImageView *imageView;

NSString *_myDocumentPath; /*" Document's path "*/

BOOL _myHasEverBeenSaved; /*" YES iff document has ever been saved
"*/
BOOL _myShouldCloseAfterSave; /*" YES iff document is being closed "*/
}

Several changes must be made to MYDocument's implementation. The -_myShouldClose method currently
displays a modal alert panel that asks users if they want to save changes made to a document before closing the
document. The following implementation of -_myShouldClose uses the NSBeginAlertSheet() function
instead of NSRunAlertPanel() to ask users if they want to save changes.
- (bool)_myShouldClose
/*" Gives users a chance to save edited documents before closing the
document.
Returns NO if the document has unsaved changes. Returns YES otherwise. "*/
{
BOOL result = YES;

_myShouldCloseAfterSave = NO; // set to deafult value

if([self isDocumentEdited])
{
NSString *documentName = [self documentPath];

if(nil == documentName)
{
// document has no path so use its window's title instead
documentName = [[self documentWindow] title];
}

// the document has been edited

NSBeginAlertSheet(MYDEFAULT_CLOSE_ACTION, MYSAVE,MYDONT_SAVE, MYCANCEL,
[self documentWindow], self,
nil, @selector(_mySaveChangesSheetDidEnd:returnCode:contextInfo:),
NULL, MYSAVE_CHANGES, documentName);

result = NO;
}
return result;
}

NSBeginAlertSheet() is similar to NSRunAlertPanel(). NSBeginAlertSheet() is declared in

Apple's header files as follows:

void NSBeginAlertSheet(NSString *title, NSString *defaultButton,

NSString *alternateButton, NSString *otherButton, NSWindow *docWindow,
id modalDelegate, SEL didEndSelector, SEL didDismissSelector,
void *contextInfo, NSString *msg, ...)

The title, msg, defaultButton, alternateButton, and otherButton arguments all have the same
meaning as the corresponding arguments to NSRunAlertPanel(). The docWindow argument specifies the
window that the sheet references. The additional arguments, modalDelegate, didEndSelector,
didDismissSelector, and contextInfo, exist because of the most important difference between
NSRunAlertPanel() and NSBeginAlertSheet(): NSRunAlertPanel() does not return until the user
acknowledges the panel, but NSBeginAlertSheet() returns immediately.

Because NSBeginAlertSheet() returns before getting input from the user, the alert sheet needs a way to tell
the application what user input is received at some later time. The didEndSelector and
didDismissSelector arguments to NSBeginAlertSheet() specify the messages that are sent when the
user clicks a button on the alert sheet and when the alert sheet is closed, respectively. The modalDelegate
argument specifies the object that will receive the messages identified by the didEndSelector and
didDismissSelector selectors. The contextInfo argument is used to specify arbitrary data that is passed
along as an argument to the didEndSelector and didDismissSelector messages.

When NSBeginAlertSheet() is called in the implementation of -_myShouldClose, the

modalDelegate argument is self. The didEndSelector argument is nil, which means don't send any
message to modalDelegate when the user clicks a button. The contextInfo argument is NULL, and the
didDismissSelector is -_mySaveChangesSheetDidEnd:returnCode:contextInfo:.

Both didEndSelector and didDismissSelector must specify selectors that take three arguments. The
first and last arguments are pointers. The second argument is an integer return code, which will be one of the
NSAlertDefaultReturn, NSAlertAlternateReturn, or NSAlertOtherReturn constants when the
message is sent to modalDelegate.

MYDocument implements -_mySaveChangesSheetDidEnd:returnCode:contextInfo: as follows:

- (void)_mySaveChangesSheetDidEnd:(id)sheet returnCode:(int)returnCode
contextInfo:(id)contextInfo
{
switch(returnCode)
{
case NSAlertDefaultReturn:
{
// User chooses to save changes
[self saveDocument:nil];
_myShouldCloseAfterSave = YES; // note fact that close is pending
break;
}
case NSAlertAlternateReturn:
{
// User chooses NOT to save changes
[[self documentWindow] close];
break;
}
case NSAlertOtherReturn:
{
// User chooses to CANCEL close
break;
}
}
}

The private -_mySaveChangesSheetDidEnd:returnCode:contextInfo: method is added to the

MYDocument class implementation right above the implementation of -_myShouldClose in MYDocument.m
so that the compiler does not warn that -_mySaveChangesSheetDidEnd:returnCode:contextInfo:
has not been declared when it is used in -_myShouldClose. If the returnCode argument that the alert sheet
sends when it calls -_mySaveChangesSheetDidEnd:returnCode:contextInfo: is
NSAlertDefaultReturn, the _myShouldCloseAfterSave instance variable is set to YES, which means
that the document should be closed after the user has finished saving it. The instance variable is needed because the
document cannot be closed until some time in the future. If returnCode is NSAlertAlternateReturn, the
document can be closed immediately because the user does not want to save changes. Finally, if returnCode is
NSAlertOtherReturn, the method does not do anything because the user has canceled the close.

The -_myShouldCloseAfterSave method is added to MYDocument to return the value of the

_myShouldCloseAfterSave instance variable. If _myShouldCloseAfterSave is YES, the document is
going to be closed after it is saved.

- (BOOL)_myShouldCloseAfterSave
/*" Returns YES if the document should be closed after it is saved.
NO otherwise. "*/
{
return _myShouldCloseAfterSave;
}

MYDocument now uses an alert sheet instead of an alert panel when asking users to save changes to documents.
The next step is to make the Save panel, which is used to select paths to save unsaved documents, is run as a sheet.
NSSavePanel already provides the -beginSheetForDirectory:file:modalForWindow:
modalDelegate: didEndSelector:contextInfo: method to run it as a sheet.

The first two arguments are the same directory and file paths used with -runModalForDirectory:file:.
The modalForWindow argument is the associated document window. The didEndSelector argument
specifies the message to send to the modalDelegate, and the contextInfo argument is passed to the modal
delegate as an argument to the didEndSelector message.

The -_mySavePanelDidEnd:returnCode:contextInfo: method is called when the user clicks a button

on the Save sheet. The returnCode argument is NSOKButton if the user saved the document and
NSCancelButton if the user clicked the Cancel button on the Save sheet.

If the user canceled the save, the _myShouldCloseAfterSave variable is set to NO. The document should not
be closed if it was not saved. An action message is sent up the responder chain to inform the document manager that
the close was canceled. The need for the action message is explained in the "Changes to MYDocumentManager to
Support Sheets" section of this chapter.

If returnCode is NSOKButton, the document is saved at the path selected by the user. After the save, if -
_myShouldCloseAfterSave returns YES, the document is closed. The document cannot be closed before -
_mySavePanelDidEnd:returnCode:contextInfo: is called because the save sheet is still active until
then.

- (void)_mySavePanelDidEnd:(id)sheet returnCode:(int)returnCode
contextInfo:(id)contextInfo
/*" Called when Save sheet is being closed. "*/
{
if (NSOKButton == returnCode &&
[sheet respondsToSelector:@selector(filename)])
{
// Cast is safe because we just verified that sheet responds to filename.
[self _mySetDocumentPath:[sheet filename]];
[self _mySaveDocumentData];

if([self _myShouldCloseAfterSave])
{
[[self documentWindow] close];
}
}
else
{
// User canceled save
[NSApp sendAction:@selector(cancelPendingTerminate:) to:nil from:self];
_myShouldCloseAfterSave = NO;
}
}

The -saveDocumentAs: method is modified to use NSSavePanel panel as a sheet instead of a modal panel.
- (IBAction)saveDocumentAs:(id)sender
/*" Displays a Save panel to find out where the user wants to save the
document's image data. If the user does not cancel the save, this method
saves the image data at the specified location. "*/
{
NSSavePanel *savePanel;
NSString *documentDirectory = [[self documentPath]
stringByDeletingLastPathComponent];
NSString *documentName = [[self documentPath] lastPathComponent];

savePanel = [NSSavePanel savePanel];

[savePanel setRequiredFileType:@"tiff"];
[savePanel setTreatsFilePackagesAsDirectories:NO];

[savePanel beginSheetForDirectory:documentDirectory file:documentName

modalForWindow:[self documentWindow] modalDelegate:self
didEndSelector:@selector(_mySavePanelDidEnd:returnCode:contextInfo:)
contextInfo:NULL];
}

Changes to MYDocumentManager to Support Sheets

An additional instance variable must be added to the MYDocumentManager class interface to keep track of
whether the application is in the process of terminating. Edit the MYDocument.h file so that it has the following
instance variable section:

@interface MYDocumentManager : NSObject

{
NSMutableArray *_myOpenDocuments; /*" Array of open documents "*/
NSPoint _myWindowCascadePoint; /*" Used to cascade doc windows "*/
BOOL _myApplicationIsTerminating; /*" YES iff application is
terminating "*/
}

The logic for terminating the Image Viewer application needs to be changed to accommodate MYDocument's use
of Save sheets. The problem is that when -applicationShouldTerminate: is called, the user is given a
chance to save unsaved documents. The documents are saved with a sheet, which means that the application must
wait an indeterminate amount of time before terminating so that the user can interact with the sheets.

The following implementation of -applicationShouldTerminate: returns NSTerminateLater if there

are any unsaved documents and sets the _myApplicationIsTerminating instance variable to YES.
NSApplication interprets NSTerminateLater to mean that it should wait until its -
replyToApplicationShouldTerminate: is called to tell it whether the termination is canceled or should
proceed. The behavior of -applicationShouldTerminate: is provided by NSApplication specifically
to enable the use of sheets during application termination.

- (NSApplicationTerminateReply)applicationShouldTerminate:
(NSApplication *)sender
/*" Implemented to Give user a chance to review and save any unsaved
documents
before terminating "*/
{
NSEnumerator *enumerator;
id currentDocument;
 int choice;
NSApplicationTerminateReply result = NSTerminateNow;
BOOL foundUnsaved = NO;

// Determine if theer are any unsaved documents

enumerator = [_myOpenDocuments objectEnumerator];
while(!foundUnsaved && nil != (currentDocument = [enumerator nextObject]))
{
if([currentDocument respondsToSelector:@selector(isDocumentEdited)])
{
// Found at least one unsaved document
foundUnsaved = [currentDocument isDocumentEdited];
}
}

if(foundUnsaved)
{
// Find out of the user wants to review and possibly save the unsaved
// documents, cancel the termination, or terminate anyway
choice = NSRunAlertPanel(MYQUIT, MYUNSAVED_DOCS_MSG, MYREVIEW_UNSAVED,
MYQUIT_ANYWAY, MYCANCEL);
if (choice == NSAlertOtherReturn)
{ // User selected Cancel
result = NSTerminateCancel;
}
else if (choice != NSAlertAlternateReturn)
{ // User selected Review Unsaved

// Give the user the chance to review the edited document(s). */

enumerator = [_myOpenDocuments objectEnumerator];
while(result != NSTerminateCancel &&
nil != (currentDocument = [enumerator nextObject]))
{
if([currentDocument respondsToSelector:@selector(safeClose)])
{
// Cause unsaved documents to show a save panel
if(![currentDocument safeClose])
{ // User selected Cancel
result = NSTerminateLater;

// Note the fact that termination is still in progress

_myApplicationIsTerminating = YES;
}
}
}
}
else
{ // User chooses to quit without saving
}
}

return result;
}

The -documentWillClose action method is called by MYDocument instances when their associated window
is closed. The following implementation of -documentWillClose checks to see if the last open document has
closed and the application is waiting to terminate. If so, the [NSApp
replyToApplicationShouldTerminate:YES] expression tells NSApplication to go ahead and
terminate now.

- (void)documentWillClose:(id)sender
/*" Removes sender from receiver's open documents array "*/
{
[_myOpenDocuments removeObject:sender];

if(_myApplicationIsTerminating && 0 == [_myOpenDocuments count])

{
[NSApp replyToApplicationShouldTerminate:YES];
}
}

The -cancelPendingTerminate: method is needed so that documents can cancel application termination if
the user clicks the Cancel button on a sheet. If MYDocumentManager receives the -
cancelPendingTerminate: action, the [NSApp replyToApplicationShouldTerminate:NO]
expression tells NSApplication to cancel termination. The _myApplicationIsTerminating instance
variable is set to NO so that the application does not terminate when the last document is closed.

- (void)cancelPendingTerminate:(id)sender
/*" Cancels the pending termination of the application. If no termination is
pending, this method does nothing. "*/
{
if(_myApplicationIsTerminating)
{
[NSApp replyToApplicationShouldTerminate:NO];
_myApplicationIsTerminating = NO;
}
}
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with Drawers

A drawer is similar to a sheet in some ways. A drawer is a window that is attached to, and
associated with, another window. Unlike sheets, drawers are not modal. Drawers slide out
of the sides of other windows instead of sliding down from a window's title bar.

Drawers are documented at http://developer.apple.com/techpubs/macosx/Cocoa/

TasksAndConcepts/ProgrammingTopics/Drawers/index.html and http://developer.apple.
com/techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSDrawer.
html.

Drawers are usually created in Interface Builder and stored in a .nib file along with their
associated window called the parent window. Interface Builder includes an NSDrawer
object already on a palette. No code is needed to manage drawers. In Interface Builder,
drag a drawer from the palette into the Instances tab of a .nib. Connect the drawer's
parentWindow outlet to the parent window. Place a button somewhere in the parent
window. Use Interface Builder to make the drawer the button's target and set the button's
action to toggle:. Each time the button is clicked, the drawer opens or closes.

The contents displayed in a drawer can also be set in Interface Builder. NSDrawer
provides a contentView outlet that can be connected to any view. Create a view in
Interface Builder including views with subviews, scroll views, tables, and so on. Connect
the drawer's contentView outlet to the view created in Interface Builder. Each time the
drawer opens, it shows its contentView. Views are described in detail in Chapter 10,
"Views and Controls."

Drawers should not be larger than their parent window. While opening and closing, the
drawer slides behind the parent window. If the drawer is too big, it will emerge from the
opposite side of its parent as it slides in or out.

Apple provides guidelines on when to use drawers at http://developer.apple.com/techpubs/

macosx/Essentials/AquaHIGuidelines/AHIGWindows/index.html.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with Screens

The NSScreen class encapsulates the attributes of a computer display such as its size in
pixels and the number of supported colors. Each computer can have more than one attached
display, and each display can have different attributes. The NSScreen class provides the
+screens class method that returns an array of NSScreen instances that each
encapsulate a display connected to the computer. The +deepestScreen method returns
an NSScreen instance that encapsulates the display that supports the highest color
fidelity. The +mainScreen method returns an NSScreen instance for the display that is
currently showing the key window.

NSScreen's -visibleFrame method was already used in the implementation of Image

Viewer. NSScreen only has a few methods, and they are documented at http://developer.
apple.com/techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/
NSScreen.html.
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Working with Panels

Panels are special windows that have auxiliary purposes in applications. Example of panels
include the Save panel, Open panel, and Alert panels used in Image Viewer.

Panels have slightly different behavior than standard windows. Most panels are hidden
when their application is not the user's current active application. The panels automatically
reappear when the user switches to their application. Panels can float above other windows.
For example, alert panels are always visually on top of other application windows. Panels
can become the key window, but not the main window. The key and main windows are
described in the "Key Window and Main Window" section of Chapter 8. Panels can be
prevented from becoming the key window, and panels can be configured to receive events
even when another window is being run in a modal loop.

The NSPanel Class and Subclasses

The NSPanel class encapsulates Cocoa panels. NSPanel is a subclass of NSWindow

and, therefore, panels inherit all the attributes of windows.

NSPanel only adds the following public methods to the ones inherited from NSWindow:

- (BOOL)becomesKeyOnlyIfNeeded
- (BOOL)isFloatingPanel
- (void)setBecomesKeyOnlyIfNeeded:(BOOL)flag
- (void)setFloatingPanel:(BOOL)flag
- (void)setWorksWhenModal:(BOOL)flag
- (BOOL)worksWhenModal

NSPanel is documented at http://developer.apple.com/techpubs/macosx/Cocoa/Reference/

ApplicationKit/ObjC_classic/Classes/NSPanel.html.

Cocoa includes several subclasses of NSPanel that implement features common to most
graphical applications. Cocoa's NSPanel subclasses include the NSOpenPanel and
NSSavePanel classes used in Image Viewer and other examples in this book. The other
standard subclasses of NSPanel are NSPrintPanel, NSFontPanel,
NSColorPanel, and NSPageLayout.

The NSApplication class provides the -orderFrontColorPanel: and -

runPageLayout: methods for displaying the standard NSColorPanel, and
NSPageLayout instances, respectively.
The NSFontPanel class is described in Chapter 11, "Text Views." The
NSPrintPanel and NSPageLayout classes are described in Chapter 25, "Printing,"
and the NSColorPanel class is introduced in Chapter 17, "Color."
Book: Cocoa® Programming
Section: Chapter 9. Applications, Windows, and Screens

Summary

This chapter covered two of the three most prominent classes in Cocoa's Application Kit
framework: NSApplication and NSWindow. The NSApplication, NSWindow,
and NSView classes collaborate to form the basis of every graphical Cocoa application.
The Image Viewer example used most of the features provide by NSApplication and
NSWindow, but it hardly touched the surface of the capabilities of NSView subclasses
such as NSImageView.

The Application Kit framework includes subclasses of NSWindow such as NSPanel, but
neither NSWindow nor NSApplication are commonly subclassed by Cocoa
programmers. In contrast, NSView is subclassed in almost every Cocoa application.
NSView is designed to be subclassed to implement application-specific features, custom
drawing, and custom-event management. The next chapter describes many of the NSView
subclasses provided by the Application Kit framework, but views are such a large subject
that Chapters 10 through 15 all deal with aspects of views. Views are used in almost every
chapter from here on because they play such a central role in Cocoa application
development.
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 10. Views and Controls

IN THIS CHAPTER

● Controls
● Simple Views and Controls
● Container Views and Controls
● Compound Controls

This chapter focuses on using the wide array of user interface objects, or widgets, found in
the Application Kit. Interactive widgets, such as sliders, buttons, and text fields, are known
as controls in Cocoa because they all descend from the NSControl class, which is a
subclass of NSView. Passive widgets, such as progress bars, are usually just known as
views because they descend from NSView. This chapter covers nearly all the simpler
Cocoa controls and views. A discussion of the remaining control and view classes, which
are all considerably more complex than those in this chapter, can be found in Chapter 18,
"Advanced Views and Controls."

Most of the Application Kit widgets are relatively simple and tend to work in a similar
fashion. Most respond to a nearly identical set of methods, with only a few unique methods
for each different kind of widget. Before diving into the details of these objects, it is
imperative to understand all the concepts explained in Chapter 8, "Application Kit
Framework Overview." This chapter assumes a basic understanding of the responder chain,
target/action, overall Cocoa application structure, and the NSResponder and NSView
classes as described in Chapter 8.
Book: Cocoa® Programming
Section: Chapter 10. Views and Controls

Controls

All Cocoa controls are subclasses of the NSControl class, which is in turn a subclass of
NSView. The NSControl class is an abstract class and should not be instantiated.
Understanding it is necessary to effectively use its subclasses, however.

The NSControl class performs three key functions. It must be able to draw the user
interface element that it represents. The machinery to support this task is inherited from
NSView. It also needs to be able to respond to user input, in particular from the mouse and
keyboard. This capability is inherited from the NSResponder class. Finally, a control
needs to be able to send arbitrary action messages to arbitrary targets. This capability is
added in the NSControl class itself.

NSControl Class

The NSControl class adds several methods to the NSView class. Because all interactive
Cocoa user interface elements inherit from NSControl, all these methods are valid for
such user interface objects. Some of these methods might not make sense for certain user
interface elements. In those cases, these methods usually do nothing.

Methods to Define a Control's Appearance

Many controls display some text. Text fields are an obvious example of this. There are
several NSControl methods to adjust how the control displays text. These methods are
rarely used in program code. In most cases, the values altered by these methods are set in
Interface Builder's inspector and stored in a .nib file.

The -setFont: method, which takes an NSFont object as its argument, sets the font
used by the control to display text. The -font method returns the font currently in use by
the control. Chapter 11, "Text Views," discusses the NSFont class. In Interface Builder,
the standard font panel is used to change the font of a control.

The text alignment can be altered with the -setAlignment: method. This method takes
one of the five constants NSLeftTextAlignment, NSRightTextAlignment,
NSCenterTextAlignment, NSJustifiedTextAlignment, and
NSNaturalTextAlignment. Many of the Interface Builder inspectors have a control
for setting the alignment. Figure 10.1 shows how the control corresponds to these constants.

Figure 10.1. The alignment control in Interface Builder.

The default alignment for all controls is NSNaturalTextAlignment. This generally
behaves like NSLeftTextAlignment, which renders the text at the left edge of the
control. Multiline text has a jagged right edge. The difference is that natural text alignment
takes localization into account. In a right to left language, natural alignment might imply a
right text alignment. When NSRightTextAlignment is used, the text is rendered at the
right edge of the control. Multiline text has a jagged left edge. Text drawn with
NSCenterTextAlignment is horizontally centered in the control. Both the left and
right edges are jagged if the text is multiline. The NSJustifiedTextAlignment
constant refers to text that is adjusted so that it is flush with both the left and right edges.
Extra space is inserted between words as necessary to justify the text. This is normally only
observable with multiline text because the last line of text will not be stretched to fit.
Figure 10.2 shows how the various text alignment modes are rendered for single line and
multiline text.

Figure 10.2. Demonstration of the five alignment modes supported by Cocoa.

There are several other methods for modifying a control's appearance, but they are
implemented by the NSCell class. Refer to the section "NSCell Class" later in this chapter
for a listing and description of these other methods.

Methods to Implement Target-Action

Several NSControl methods can be used to set up and modify a control's target-action
behavior.

Setting up target-action requires that a control's target and action be defined. The action
should be the selector of an action method (the SEL type). The target should be the id of
an object or nil. If nil, the action is sent to the first responder and down the responder
chain if necessary. The -setAction: and -setTarget: methods are used,
respectively, to set action and target. The -action and -target methods can be used to
determine a control's current action and target.

Usually, the action and target of a control are set up in Interface Builder by control
dragging a connection between two objects. This could be done programmatically with
these methods, but Interface Builder is generally the easier way to set up a target-action
connection. For example, suppose that in Interface Builder a connection is control dragged
from myButton to myControllerObject and the action is set to -
buttonClicked:. This could be done in code as follows:

[myButton setTarget: myControllerObject];

[myButton setAction:@selector(buttonClicked:)];

Using either this code or Interface Builder gives the same result. If the button is clicked,
the -buttonClicked: method of myControllerObject is invoked. Alternatively,
setting the target to nil is the same as connecting to the .nib file's first responder icon.

To programmatically simulate a user clicking a control-such as a button-send the -

performClick: message to the control. This causes the control's action message to be
sent, just as if a user had clicked the control.

Some controls need to send an action message repeatedly. To do this, the -

setContinuous: method is used. Use YES to make the control send multiple action
messages, or NO for a single action message. The -isContinuous method can be used
to obtain this setting. In Interface Builder, a control's inspector has a check box labeled
Continuous that can be turned on and off to change this setting. Because this setting isn't
useful for every type of control, not all controls have this check box.

The meaning of continuous can change from one type of control to another. For example, a
continuous button sends its action message over and over at a fixed rate as long as the
button is being pressed. A continuous slider sends action messages as the slider is moved,
whereas a noncontinuous slider sends a single action message when the slider is released.

NOTE

Control subclasses that send actions periodically, such as buttons, have

 methods for changing how often the action is sent. The repeat speed can also
be controlled by a user's preferences.

There is also an advanced method, -sendActionOn:, which can be used to specifically

define which types of events should trigger sending the action. Common events for this
would be mouse-dragged, mouse-down, or mouse-up. The argument to this method is a
bitwise OR of event mask constants. See Chapter 15, "Events and Cursors," for a list of the
event constants and what they mean. This method can radically alter a control's behavior,
so it is normally best to avoid using it. Each control subclass sets up its action-sending
behavior automatically, based on the Aqua guidelines. That is good enough for most
situations.

Methods to Modify Event Response

Some of the NSControl methods determine how the control responds to mouse and
keyboard events.

The most often used methods are -setEnabled: and -isEnabled. Using the
constants YES or NO, the -setEnabled: method can be used to enable or disable the
control. A disabled control is usually grayed out and will not respond to any user input. It
will also refuse to become the first responder.

When a user double-clicks or triple-clicks a control, that action is usually interpreted as two
or three distinct clicks on the control. To ask a control to ignore all but the first click, send
it a -setIgnoresMultiClick: message with a value of YES. All clicks after the first
will be forwarded to the control's superclass. Normally, the superclass ignores the extra
clicks. The -ignoresMultiClick method can be used to determine whether the
control is ignoring multiple clicks.

Finally, a control can choose to accept or reject first responder status. Use the -
setRefusesFirstResponder: method to change this behavior, and -
refusesFirstResponder to see how it is currently set. Changing this method also
alters how the control responds to the inherited NSView method -
acceptsFirstResponder. Sending a YES to -setRefusesFirstResponder:
will cause -acceptsFirstResponder to return a NO and vice-versa.

Setting and Getting a Control's Value

Most controls have an internal value. For example, the value could be an integer or floating-
point number representing a slider's position, or a text string representing the contents of a
text field. The NSControl class implements many methods to set and get this value.
Most of the methods described in this section are also defined by other Cocoa objects, such
as NSString. This consistency through the frameworks makes it easier to remember what
methods are available.

Several methods can be used to change the value of an NSControl. They are

- (void)setStringValue:(NSString *)aString;
- (void)setIntValue:(int)anInt;
- (void)setFloatValue:(float)aFloat;
- (void)setDoubleValue:(double)aDouble;
- (void)setAttributedStringValue:(NSAttributedString *)obj;
- (void)setObjectValue:(id)obj;

Note that all these methods can be sent to any control. Each control attempts to do the right
thing if a value is sent in a form that isn't native to the control. For example, text fields
display strings. Asking it to set its value to a number causes it to do a number-to-string
conversion so that is has a new string to display.

The -setAttributedStringValue: method is somewhat special because it allows a

string with multiple fonts and styles to be set. Most controls treat this as a regular string,
but text fields use the extra text attributes to modify how the text is displayed.

The -setObjectValue: method is a little different from the others because usually no
type conversion will take place, and the value displayed by the control will not be changed.
Instead, the object is stored by the control and otherwise ignored. This allows a particular
object, which can be retrieved later, to be associated with a given control.

Whenever any of the previous methods are used to change a control's value, the control
immediately ends any in-progress editing and is marked as needing to be redisplayed.

To get the current value of a control, use one of these methods:

- (NSString *)stringValue;
- (int)intValue;
- (float)floatValue;
- (double)doubleValue;
- (NSAttributedString *)attributedStringValue;
- (id)objectValue;

Finally, there is a group of methods that can be used to get one control to take the value
from another object and set itself to that value. The methods are

- (void)takeStringValueFrom:(id)sender;
- (void)takeIntValueFrom:(id)sender;
- (void)takeFloatValueFrom:(id)sender;
- (void)takeDoubleValueFrom:(id)sender;
- (void)takeObjectValueFrom:(id)sender;

There are a couple of things to note. The sender parameter should be an object that can
respond to the previous get methods, such as -intValue, and so on. This is important
because the -take methods will call the correlating accessor method. Usually, the sender
will be an instance of another NSControl subclass, which implicitly guarantees this
condition. Also, notice that there is no method for taking an attributed string value. A
method for attributed strings would be expected for the sake of consistency, but as of Mac
OS X 10.1 there is no such method.

To see how these methods work, try creating an Interface Builder file with a single window
containing a slider and a text field. Drag a connection from the slider to the text field,
setting the action to -takeIntValueFrom:. Enter Interface Builder's Test Interface
mode and drag the slider. The text field will continuously update to show the value of the
slider as the slider is dragged.

Tags

All controls can be assigned a tag. A tag is an arbitrary integer that can be used to identify
the control to program code. The tag for a control can be set programmatically or in the
control's inspector in Interface Builder. The tag is most often used by action methods to
determine which control sent the action message. Often, it is unnecessary to know which
control sent a message, in which case the tag can remain unset. The Interface Builder
default is to set the tag to zero.

To determine a control's tag, use the -tag method, which returns an integer. To change a
control's tag, use the -setTag: method, providing it with a new integer or change the tag
in the Interface Builder inspector. Many advanced Cocoa programmers use a #define
statement or an enumerated type to assign symbolic names to integers used as tags. This
can enhance code readability and maintainability.

NOTE

For controls with titles, the title should not be used to identify the control in
program logic. Titles change with localizations and are, therefore, unreliable.
Tags, which are invisible to the user, are a much better way to identify control
objects.

Relationship Between Controls and Cells

Nearly every Cocoa control is associated with a cell object. A cell is a lightweight object
that behaves much like a view object. Cells don't manage a coordinate system or graphics
context, however. Instead, they rely on a view, typically a control, to perform those tasks.
Most controls use cells to implement the drawing behavior as well as some of the event-
handling behavior. Although most controls are paired with a single cell object, some of the
more complex controls use more than one cell. The extra cells are typically used as labels
or as extra active areas of the control.

One of the most common questions for developers new to Cocoa is "why bother with cells
at all when you can just use views everywhere?" The answer is that this is a performance
enhancement that has the additional benefit of adding some extra flexibility to the design of
control objects.

Using cells is a performance enhancement for a couple of reasons. First, view objects use
much more memory for their instance variables than do cell objects. For controls that use
more than one cell, the memory savings is significant. Second, each view has its own
Quartz drawing context. (Drawing contexts are defined in Chapter 12, "Custom Views and
Graphics Part I," and are described more fully in Chapter 13, "Custom Views and Graphics
Part II.") To render a view, its drawing context needs to become active. For a control with
multiple elements, all these context switches can eat up a lot of CPU cycles. Because a cell
requires its parent view object to handle the context, a control with many cells doesn't need
to switch contexts as each cell is drawn. All the cells use the same context. This makes
drawing significantly faster.

Cells also increase the flexibility of Cocoa controls and reuse throughout the framework.
By laying out several cells of different types, complex controls such as steppers can be
created. A matrix control, which is used to implement radio buttons and other repeated
types of controls, is also a collection of cells. Most controls can be turned into a matrix of
cells in Interface Builder by dragging the resize handles while holding down the option
(alternate) key. The only requirement for this to work is that the control have an associated
NSCell subclass. Thus, the NSButton class has the associated NSButtonCell class,
and so on.

Because cells are so prevalent, before diving into the individual types of controls, it is
important to understand what the NSCell class has to offer.

NSControl Methods for Working with Cells

The NSControl class has a few methods for manipulating its associated cell classes. The
-cell method returns the control's cell. The -setCell: method can be used to change
a control's cell. Both methods are most useful with controls that have only a single
associated cell. Controls that use multiple cells often have their own specific methods that
are better choices to use than these two methods.

Much of a control's appearance is controlled by its cell object. Therefore, when configuring
a control programmatically, most of the work is done by changing settings in the associated
cell. The -cell method is used to obtain a pointer to the cell instance.
When a new control is initialized, it creates a default cell instance for itself. The class of
the cell that is generated can be changed with the class method +setCellClass:. This
method should normally be used with a specific subclass of NSControl. For example, to
set NSSlider to use the custom class MySliderCellSubclass for all sliders, this
code is used:

[NSSlider setCellClass:[MySliderCellSubclass class]];

The +setCellClass: method only changes the cell class for objects initialized after it
has been invoked. Existing controls remain unaffected. It is common to change the class
temporarily while programmatically building a user interface. To restore the previous cell
class, the previous class needs to be obtained and stored. Use the +cellClass method to
see what class a particular control is using at the moment.

NSCell Class

A large majority of the methods implemented by the NSCell class are duplicates of the
methods implemented by the NSControl class. The methods described in the previous
sections "Methods to Define a Control's Appearance," "Methods to Implement Target-
Action," "Setting and Getting a Control's Value," and "Tags," are all implemented by
NSCell.

NOTE

Although the NSCell class defines methods for target-action, it is a passive

object. It doesn't really store targets or actions, nor does it send actions.
Subclasses that use target-action need to define instance variables for storing
the target and action as well as implement the target-action-related methods.
The NSActionCell class does this for most Application Kit cells.

The NSCell class offers many methods for defining its appearance. Some of these
methods don't make sense for cells of a particular type. In such cases, the cell attempts to
do the right thing, whatever that may be. Usually, a parameter that doesn't make much
sense is ignored. Because many of these methods are specific to a particular type of
control, such as a button or text field, they are discussed throughout this chapter in the
appropriate section.

A few parameters apply to all cells, however. The way a cell is initialized determines how
it will be used, favoring images or text. The control size (large or small) and control tint
(aqua blue or graphite) can be changed. The border, highlight, and bezel can be turned on
and off.
When a cell is initialized, it is generally set up to be primarily used for text or for images.
As a result NSCell defines two designated initializers, -initTextCell: and -
initImageCell:. Subclasses of NSCell tend to favor one method over the other.
Because NSCell is abstract and shouldn't be instantiated, having two initializers doesn't
cause any confusion. The initializer favored by a given subclass should be used for that
subclass.

Cells can be converted between the two types of cell with the -setType: method and the
current type is returned with the -type method. Both methods use the constants
NSTextCellType, NSImageCellType, and NSNullCellType. (The null type is a
cell that displays nothing.)

To change the control size of a cell object, use the -setControlSize: method. It takes
either the NSRegularControlSize or NSSmallControlSize constant as its
argument. The -controlSize method returns the current control size.

To change the tint of a cell object, use the -setControlTint: method. It takes either
the NSDefaultControlTint or NSClearControlTint constant as its argument.
The NSDefaultControlTint constant causes the control to be rendered in aqua blue
or graphite, depending on the user's setting in preferences. The -controlTint method
returns the current control tint.

The -setBordered:, -setBezeled:, and -setHighlighted: methods turn a

cell's border, bezel, or highlight on or off, respectively. Each takes YES or NO as a
parameter. These methods only turn these features on or off. Specific methods to change a
cell's border or bezel type are found in the various NSCell subclasses. To see whether a
feature is on or off, use one of the -isBordered, -isBezeled, or -
isHighlighted methods.

Some cells have titles. This is usually the case with a cell that displays both an image and
text, such as some buttons. The accessors for the title are -setTitle: and -title.

NSActionCell Class

Most controls use cells that are designed to manage user events and send an action at the
appropriate time. NSCell objects, although they define target-action methods, are actually
passive. A cell subclassed from NSActionCell actually makes use of the target-action
information. It stores the target-action information and implements all the related methods.
The NSActionCell class doesn't define any significant new methods not already defined
in its superclass, NSCell.
Book: Cocoa® Programming
Section: Chapter 10. Views and Controls

Simple Views and Controls

Most of this chapter is concerned with cataloging the many user interface elements offered by Cocoa.
This section covers the simplest views and controls. Buttons, sliders, and text fields are controls common
to almost any graphical user interface. Passive views for displaying images and progress of a long task
are also common. In Cocoa, each of these objects has a single cell instance associated with it.

These controls are normally laid out and configured in Interface Builder. Many methods can also be used
to modify all Cocoa controls without the need for Interface Builder. It is important to realize that
Interface builder is actually instantiating these objects and editing them. That means that internally
Interface Builder is actually calling the methods described in this chapter. Anything that can be done in
Interface Builder can be done in code. No special magic is involved.

Buttons

A button is a user-interface object that sends an action when it is clicked. Apple's Aqua user interface
supports many different styles of buttons. In Cocoa, all these buttons are implemented by the NSButton
and NSButtonCell classes. Because there are so many options available for buttons, these classes can
at first seem somewhat complex. Normally, a user interface's buttons are configured in Interface Builder,
which simplifies the process a little. It is also possible to change the details programmatically.

NOTE

The terminology between the Cocoa method names and the Interface Builder options is
sometimes different. The programmatic interface is also much more detailed. In most cases,
a single option in Interface Builder actually changes several of the programmatic options
simultaneously. Because of these discrepancies, it is difficult to describe the underlying
methods at the same time the Interface Builder options are being explained. Because of this,
Interface Builder options are described first, and then all the programmatic options are
discussed separately.

The following button-related sections explain the available button options and the methods offered by
NSButton and NSButtonCell to change them. The described methods are technically
NSButtonCell methods, but the NSButton class also implements them as a convenience. The
NSButton implementations simply forward the messages on to the underlying NSButtonCell object.

Button Options in Interface Builder

The first option, which affects a button's appearance the most, is the button's type. Interface Builder
supports six different button types as defined by Aqua: Rounded Bevel Button, Square Button, Push
Button, Check Box, Radio Button, and Round Button. All six buttons are available on the Cocoa-Views
palette in Interface Builder. Click the palette button with a small button and text field on it to open the
Cocoa-Views palette. This palette and the six button types are shown in Figure 10.3.
 Figure 10.3. Buttons on the Cocoa-Views palette.

It is also possible to change the button type using the button inspector. Open the inspector by hitting Cmd-
1 with a button selected. Figure 10.4 shows this inspector.

Figure 10.4. Interface Builder's button/button cell inspector.

To change the button type, use the pop-up list labeled Type. The rest of this section refers back to Figure
10.4 as the other options are described.

NOTE
 In this case, the label Type in Interface Builder is not the same as the word type when seen
in the Cocoa method names. The type pop-up in Interface Builder's inspector actually
changes a button's bezel style, gradient, images, and more. There is a method -
setButtonType:, but it refers to what Interface Builder labels Behavior.

At the top of the inspector are text fields for setting a button's title, image, and sound. The sound is
played whenever the button is clicked. The title and/or image are displayed on the button to identify it to
the user. When the button is in the off state, the normal title and image are displayed. When in the on
state, the alternate title and icon are displayed. Normally, titles should be kept as short as possible while
remaining clear. ToolTips, as described in Chapter 20, "Adding Online Help," can be used if more
information than the title needs to be offered to the user. Images are typically small icons. In the case of
radio buttons and switches (also known as check boxes), a special icon is used for the image and alternate
image to show the button's state.

Buttons can have a key equivalent. When the key equivalent is typed, the button is triggered as if the
mouse had clicked it. If the window doesn't have an active first responder, it acts as the first responder
and looks for buttons that have key equivalents for anything typed at the keyboard. If the key equivalent
uses the Cmd key, the window looks for a button to click even if it has a first responder. Buttons with
Cmd-key equivalents take precedence over menu items with the same key equivalents when the window
containing the button is the key window.

A button's key equivalent can be configured by the row of controls labeled Equiv in Interface Builder.
The key is typed into the text field. Alternatively, special keys, such as Return or Tab, can be selected
with the pop-up list. The two switches determine whether the Option or Cmd keys need to be pressed to
trigger the key equivalent. Refer to Figure 10.4 to see these controls.

The Behavior pop-up controls how a button behaves. This setting varies between the button objects on
the palette and is generally set to be the way a user would expect a button of a particular type to behave.
It is very rarely changed because most changes would violate the Aqua guidelines. To prevent the worst
offenses, this pop-up is disabled for some button types. It offers six options, as described in Table 10.1.

Table 10.1. Button Behaviors

Behavior Name Behavior

Momentary Light Redraws itself between mouse-down and mouse-up to be highlighted.

Momentary Change Redraws itself between mouse-down and mouse-up to show the alternate image
and title.
Momentary Push In Redraws itself between mouse-down and mouse-up to be highlighted and, if
bordered, pushed in.

Toggle The first click turns the button on, the second turns it off. On buttons display their
alternate text and image. Highlighting happens between mouse-down and mouse-
up.

On/Off The first click turns the button on, the second turns it off. On buttons are
highlighted, but don't show alternate text or image.

Push On/Push Off The first click turns the button on, the second turns it off. On buttons are
highlighted and, if bordered, appear pushed in.

The key difference between these modes is whether the button is momentary or toggles state. The other
difference is in whether the alternate title and image are used. The difference between appearing pushed
in or not is actually moot in Mac OS X 10.1.

NOTE

A button that is highlighted and a button that is highlighted and pushed in are actually
drawn the same in Aqua. The difference between the two was more apparent on versions of
Cocoa prior to Mac OS X that implemented the classic Macintosh interface and the NeXT
interface.

The options area of the button inspector controls miscellaneous button options. They can alter a button's
appearance, event handling, and state.

Three check boxes control the appearance of a button. Some buttons have borders. The Border check box
allows this to be changed for buttons that allow it to be changed. Some types of buttons, such as push
buttons, don't allow the border to be turned off. Transparent buttons don't draw anything, but are still
sensitive to being clicked. These buttons can be used to make certain areas of a user interface become
live, even though there's not necessarily anything obvious to click. One use of this is as a secret button
that triggers an Easter egg. The Small check box causes the small version of the button to be drawn, if
such a thing applies. All the button types except for rounded bevel and square have small versions.

Continuous buttons are buttons that repeatedly send their action message while they are in the on state.
The Continuous check box turns this behavior on or off. The Enabled check box can be used to disable a
button. An enabled button can be clicked and sends its action, but a disabled button is grayed out and all
clicks on the button are ignored. The Selected check box changes a button's state. A selected button is a
button that is in the on state. This makes sense only for toggle, on/off, check box, and radio buttons.

The Icon Position buttons determine how buttons display their titles and images. Refer to Figure 10.5 to
see the icons on each of these buttons and how they correspond to Cocoa constants. They behave similar
to radio buttons because only one can be selected at a time. On the buttons, a line represents the text title
and a square represents the image. Select just a line to display only the text title. Selecting the square
displays only the image. The four remaining buttons cause the text and icon to be used, with the text to
the top, bottom, left, or right of the icon. The Pixels Inset pop-up controls the spacing between the image
and the text and is, therefore, only available when image and text are both to be rendered.

Figure 10.5. Icon Position control from Interface Builder's button/button cell inspector.

The final two controls on the inspector, alignment and tag, have already been explained in the previous
sections "Methods to Define a Control's Appearance" and "Tags." The justified option is not available for
buttons, but because buttons only display a single line of text, this is not a problem. Single line justified
text looks just like left justified text.

Configuring a Button's Titles, Images, and Sound

There are methods for setting a button's titles. The two types of titles are the normal and alternate, and
each can be set with a string or attributed string. Thus, there are four methods, the function of each is
obvious from the name:

- (void)setTitle:(NSString *)aString;
- (void)setAlternateTitle:(NSString *)aString;
- (void)setAttributedTitle:(NSAttributedString *)aString;
- (void)setAttributedAlternateTitle:(NSAttributedString *)aString;

Likewise, there are four methods for retrieving a button's title. They are -title, -alternateTitle,
-attributedTitle, and -attributedAlternateTitle.

Use -setImage: and -setAlternateImage: to set a button's image and alternate image. The
image and alternate image can be retrieved with the -image and -alternateImage methods. Both
methods use the NSImage class. This class is explained in Chapter 14, "Custom Views and Graphics
Part III."

The image position can be altered with the -setImagePosition: method. The possible constants
that can be passed to this method are NSNoImage, NSImageOnly, NSImageLeft,
NSImageRight, NSImageBelow, NSImageAbove, and NSImageOverlaps. The first six in that
list correspond to the Icon Position control in Interface Builder's button inspector. The constant
NSImageOverlaps cannot be set from Interface Builder. It can be used to make the image and title
overlap.

Finally, -setSound: sets the sound the button plays when it is triggered. The -sound method returns
the sound. Both methods use the NSSound object, which is described in Chapter 21, "Multimedia."

All the methods for altering a button's titles, images, and sound can be sent to instances of both the
NSButton and the NSButtonCell class.

Configuring a Button's Rendering

Quite a few methods alter the way a button is rendered. Some of these methods correspond directly to
counterparts in Interface Builder's inspector. However, most of the controls in the inspector actually call
several of these methods at once.

To make a button transparent, use the -setTransparent: method. The -isTransparent method
is used to determine if a button is transparent or not. These methods correspond to the Transparent switch
in Interface Builder.

The border around a button is controlled by the -setBordered: and -setBezelStyle: methods.
These values are accessed with the -isBordered and -bezelStyle methods. The border methods
take and return the constants YES and NO. The bezel style constants are NSRoundedBezelStyle,
NSRegularSquareBezelStyle, NSThickSquareBezelStyle,
NSThickerSquareBezelStyle, NSShadowlessSquareBezelStyle, and
NSCircularBezelStyle.

NOTE

For all cells that support borders and bezels, the border and bezel are mutually exclusive.
Setting one turns off the other.

The bezel types loosely correspond to the Type pop-up list in Interface Builder. The
NSRoundedBezelStyle constant corresponds to the Rounded Bevel button. A button using
NSCircularBezelStyle is a Round button. The four square bezel style constants are variants of the
Square button type. Other methods can be used to select the other types. A button using
NSShadowlessSquareBezelStyle can be tiled with other buttons of the same bezel style, which
is useful for tool palettes.

The Type button in Interface Builder sets a button's gradient as well as its bezel. Square buttons display a
gradient that simulates a shadow. This makes them look as though they have a slightly curved surface.
The gradient can be concave or convex and weak or strong. A concave gradient makes the button look
like it curves slightly into the screen, whereas a convex gradient makes the button appear to be curved
out of the screen. Weak versus strong refers to the contrast between the light and dark colors of the
gradient. Strong gradients appear to have more curvature.

To set a gradient, use -setGradientType: with one of the constants NSGradientConcaveWeak,

NSGradientConcaveStrong, NSGradientConvexWeak, or NSGradientConvexStrong.
To use no gradient, use the constant NSGradientNone instead.

It is possible to alter how a button renders itself when it is highlighted with the -setHighlightsBy:
method. The -highlightsBy method returns the current highlight mode. Both methods use a series of
mask constants. The value can be either NSNoCellMask or the bitwise OR of the constants
NSContentsCellMask, NSPushInCellMask, NSChangeGrayCellMask, and
NSChangeBackgroundCellMask.

The NSNoCellMask constant specifies no change between highlighted and nonhighlighted buttons. The
NSContentsCellMask constant causes the alternate title and image to be used. The
NSPushInCellMask constant is supposed to make the button appear to be pushed in, but has no effect
in Mac OS X. The NSChangeGrayCellMask and NSChangeBackgroundCellMask constants
make the button appear to be darker when it is highlighted. The key difference is that
NSChangeBackgroundCellMask is meant for buttons using images that have alpha channel data.

Similar to highlighting, it is possible to change the way a button renders itself when in the on state. The -
setShowsStateBy: method changes this, and the -showsStateBy method returns the current
setting. Both methods use the same set of masks as the -setHighlightsBy: and -highlightsBy
methods.

NOTE

Depending on how a button is configured, it might make a distinction between being

highlighted and being in the on state. Interface Builder sets up both parameters based on a
combination of how the Type and Behavior pop-up lists are set.

A final rendering parameter controls the look of a disabled button. When a button with an image is
disabled, normally the image should be dimmed along with the text. This is generally always the case in
Mac OS X, even for switches and radio buttons. It is possible, however, to have the image remain
undimmed when a button is disabled. In such a case, only the text is dimmed to indicate that the control
is disabled. Sending YES or NO to the -setImageDimsWhenDisabled: method controls whether
the image is dimmed and -imageDimsWhenDisabled returns the current setting.

Configuring a Button's Behavior

It is possible to modify the way a button behaves with the -setType: method. The Interface Builder
pop-up lists Type and Behavior both send this message along with several other messages to modify the
button's rendering. Remember that in the programming API, the word type is not used entirely the same
as it is used in the Interface Builder interface. The various button types and their meanings are shown in
Table 10.2. It might also be useful to refer back to the button behaviors in Table 10.1.

Table 10.2. Button Type Constants

Constant Meaning
NSSwitchButton Same as Switch Button in Interface Builder Type pop up

NSRadioButton Same as Radio Button in Interface Builder Type pop up

NSMomentaryLightButton Same as Momentary Light in Interface Builder Behavior pop up

NSMomentaryChangeButton Same as Momentary Change in Interface Builder Behavior pop up

NSMomentaryPushInButton Same as Momentary Push In in Interface Builder Behavior pop up

NSToggleButton Same as Toggle in Interface Builder Behavior pop up

NSOnOffButton Same as On/Off in Interface Builder Behavior pop up

NSPushOnPushOffButton Same as Push On/Push Off in Interface Builder Behavior pop up

The NSCell methods -setContinuous: and -isContinuous affect NSButtonCell objects.

Continuous buttons send their actions repeatedly until released. The following two methods control the
timing of the repeats:

- (void)setPeriodicDelay:(float)delay interval:(float)interval;
- (void)getPeriodicDelay:(float *)delay interval:(float *)interval;

The delay is the time in seconds before the button starts sending repeated action messages. The interval is
the time between each of the repeated action messages.

When a button is being held down, it normally remains highlighted until the mouse is dragged outside of
the button's bounds. It is possible to make a border-based highlight remain on when the mouse strays
outside of the button with the -setShowsBorderOnlyWhileMouseInside: method. The -
showsBorderOnlyWhileMouseInside method returns the current setting. This only affects the
button's border. It will not cause a button's other highlights to stay on when the mouse leaves the button's
bounds.

Configuring a Button's Key Equivalents

Two methods exist for setting a button's key equivalent. The -setKeyEquivalent: method sets the
actual key equivalent. An NSString containing a single character should be provided. To tell a button
whether modifier keys, such as Cmd and Option, need to be pressed down, use the -
setKeyEquivalentModifierMask: method. It requires the bitwise OR of the modifier key masks
described in Chapter 15. The NSCommandKeyMask and NSAlternateKeyMask refer to the Cmd
and Option keys, respectively, and are the only ones that can be set with Interface Builder. The current
key equivalent setting can be obtained with the -keyEquivalent and -
keyEquivalentModifierMask methods.

When a button is set to display text and an image, but the image has been set to nil, the key equivalent
is shown in place of an image. Although Interface Builder doesn't allow the font used for the key
equivalent to be altered, it can be changed programmatically. The following three methods can be used to
get and set the key equivalent's font:

- (NSFont *)keyEquivalentFont;
- (void)setKeyEquivalentFont:(NSFont *)fontObj;
- (void)setKeyEquivalentFont:(NSString *)fontName size:(float)
fontSize;

NOTE

The three methods for working with a key equivalent's font are only available in the
NSButtonCell class. This differs from the other methods for modifying buttons. The
others can be sent to either NSButton or NSButtonCell.

Configuring a Button's State

Normal buttons, created in Interface Builder, can have one of two states, on or off. The -setState:
method can take the constants NSOnState or NSOffState to change the state. The -state method
returns the current state of a button.

NOTE

The constants YES and NO can be used as synonyms for NSOnState and NSOffState,
respectively, but this is implementation dependent and should be avoided. It is common to
see YES and NO used in older example code, so it is useful to know that this works. It is
stylistically discouraged, however, in part because it doesn't work well with mixed state
buttons.

It is also possible to programmatically create buttons that are capable of displaying a third state, known
as mixed. This is very common for check boxes that are displaying the attributes of a selection. If a
selection contains objects with a particular attribute on, the check box is set to on. It is set off if none of
the objects has the characteristic. But if the selection contains some objects with the setting on and some
with it off, a mixed state is usually used. For example, suppose a check box is showing whether a text
selection is in boldface. The text selection could be all in boldface, all in a nonbold style, or mixed, with
some text in bold and some not.

To enable a button to have a mixed state, use the -setAllowsMixedState: method. The -
allowsMixedState method can be used to see if this is already on or not. The -setState: and -
state methods use the constant NSMixedState to denote the mixed state.
When a mixed state toggle button is clicked, instead of toggling between on and off it cycles through the
three states. The order of the cycle is on, off, mixed, and so on. The -nextState method returns the
next state the button takes on, but doesn't actually change the state. The -setNextState method
moves the button into the next state in the cycle. Of course, -setState: can be used to set a particular
state.

Sliders

A slider is a user interface element that can deal with a range of numeric values. On Mac OS X, sliders
can be horizontal or vertical. Some sliders can be configured to have tick marks on one side or the other,
whereas others can be configured to have no tick marks at all. A slider can be disabled, which causes it to
be grayed out. Sliders also come in large and small forms. Figure 10.6 shows a wide variety of sliders
displaying these various characteristics.

Figure 10.6. A variety of slider configurations.

A slider's knob is moved by clicking and dragging inside the slider. If the user clicks outside of the
slider's knob, the knob jumps to the mouse location and can then be dragged from there. If a slider has
tick marks, the knob movement can optionally be constrained to move in jumps aligned with the tick
marks. Sliders can be configured to send their actions either continuously as the slider is moved or once
when the mouse is released. Several preconfigured sliders are available on the Cocoa-Other palette in
Interface Builder. This palette is shown in Figure 10.7.

Figure 10.7. Sliders on the Cocoa-Other palette.

The NSSlider object implements a single slider. It uses the NSSliderCell object in the same way
NSButton uses NSButtonCell objects. Also like buttons, the methods supported by the
NSSliderCell class can also be sent to the NSSlider class. Most messages to NSSlider are
forwarded to its cell.

Cocoa offers a second object that acts much like a slider, the NSScroller. Scrollers and sliders both
navigate a one-dimensional range, but cannot be used interchangeably. Sliders select a single point from
within their range, whereas a scroller is designed to allow the user to select a fixed-size range within a
range. Because scrollers are usually used indirectly as part of an NSScrollView object, they are
discussed later in this chapter in conjunction with scroll views.

Slider Options in Interface Builder

All the options for configuring a slider can be found in Interface Builder's NSSlider inspector. This
inspector, shown in Figure 10.8, is displayed by using the Cmd-1 key equivalent when a slider or slider
cell is selected.

Figure 10.8. Interface Builder's slider/slider cell inspector.

In the inspector, the minimum and maximum values control the range of the slider. The current value
represents the slider's current position. When the slider's .nib is loaded, the slider will already be set to
this value.

In the inspector, the Options box, with the Continuous, Enabled, and Small switches, and the Tag text
field are all control options defined by NSControl and NSCell. All four of these options are
described previously in this chapter.

The Markers box is used to set tick marks. Set the number of markers to zero for a slider with no tick
marks. If the number is set to 1, there will be a single mark at the slider's center. If there are two or more
marks, there will be a mark at each end of the slider with the remaining marks distributed evenly between
the ends.

The Position radio buttons change their titles depending on whether the slider is vertical or horizontal and
control which side of the slider has the tick marks. Depending on where the slider is located in a user
interface, one layout might look better than another. Although this setting can be changed if there are no
tick marks, doing so won't change the rendering of the slider until tick marks are added.

The Marker Values Only switch forces the slider knob to always be over a tick mark. As the knob is
dragged, it jumps from one tick mark to the next. Although Interface Builder allows this to be turned on
for a slider with a single tick mark, doing so is somewhat useless because it renders the slider immobile.
It can also be turned on for sliders with no tick marks, but there will be no change in the slider's behavior.

Slider Sizes

Some constraints are set by Aqua for NSSlider objects. Sliders dragged from Interface Builder's
palette automatically follow these constraints. Sliders created programmatically should be created so that
the correct sizes are used.

First, determine whether the slider should be horizontal or vertical. The NSSlider class automatically
decides whether it is horizontal or vertical based on its size. A slider that is horizontal should be created
so that it is wider than it is high. A vertical slider should be higher than it is wide. To see how a slider
will be rendered, the -isVertical message can be used.

When the orientation is decided, there are certain limits to the shorter dimension. A horizontal slider's
height should be 25 pixels for a large slider with tick marks or 21 pixels for a large slider without ticks.
Small sliders should be 17 pixels high with tick marks and 15 pixels without.

NOTE

Curious readers will eventually discover that the horizontal slider with tick marks on
Interface Builder's palette is actually 26 pixels in height. This is probably a bug because
turning the ticks off and back on will change the height to 25 pixels. This is true for the
April 2002 Mac OS X Developer tools release, future releases might fix this discrepancy.

For vertical sliders, the width is the constrained dimension. A large vertical slider with ticks should be 25
pixels in width. Without ticks, a large slider should be 21 pixels wide. A small slider with ticks should be
19 pixels wide. A small slider without ticks should be 15 pixels wide.

Configuring a Slider's Range

The range of a slider is set using the -setMinValue: and -setMaxValue: methods, both of which
take a double. The -minValue and -maxValue methods return the current settings. These
correspond to the Interface Builder inspector's minimum and maximum values. The current value setting
in Interface Builder is set using the standard methods for setting a control's value, such as -
setFloatValue:.

If the user holds down the Option key when dragging a slider knob, it is possible to have the knob move
in precise increments instead of smoothly. This is somewhat like constraining a slider to only land on tick
marks, except that it is optional. To set the increment size, use the -setAltIncrementValue:
method. The -altIncrementValue method retrieves the current setting.

Configuring a Slider's Tick Marks

The options for setting tick marks in Interface Builder's inspector have obvious accessor method
counterparts. To set the number of ticks, use the -setNumberOfTickMarks: method. The -
numberOfTickMarks method returns the current setting. To control where tick marks are rendered,
use the -setTickMarkPosition: method with the constants NSTickMarkBelow,
NSTickMarkAbove, NSTickMarkLeft, and NSTickMarkRight. The -tickMarkPosition
method returns the current setting. Finally, the -setAllowsTickMarkValuesOnly: method
controls whether the slider knob is always forced to be over a tick mark or able to move smoothly. The -
allowsTickMarkValuesOnly method returns the current setting.
A few other methods for dealing with tick marks might be useful. For a slider with n tick marks, each
mark is given an index from 0 to n-1. Given an NSPoint, the nearest tick mark can be determined with
the -indexOfTickMarkAtPoint: method. It returns the index of the nearest tick mark or
NSNotFound if the point is too far away to be considered near any tick mark.

Given the index of a tick mark, the double value of the slider at that tick mark can be found using the -
tickMarkValueAtIndex: method. The area of the view where the tick mark is drawn is obtained
with the -rectOfTickMarkAtIndex: method. This is useful when overriding a slider's -
drawRect: to do custom rendering.

Given a particular slider value, it is possible to determine the value represented by the nearest tick mark.
The -closestTickMarkValueToValue: method takes a hypothetical double value and
determines which tick mark is closest to that slider value. It then returns the double value that the slider
would have if its knob were at that mark.

Configuring a Slider's Rendering

Prior to the Aqua user interface in Mac OS X, Cocoa supported two rendering options for sliders. The
first option would alter the size of the slider's knobs, using the -setKnobThickness: and -
knobThickness methods. The other option, using -setImage: and -image, would allow an
image to be laid in the slider's track, much like the sliders in the standard color panel.

As of Mac OS X 10.1.4, neither of these rendering options works, even though the methods for
controlling both can be found in the Cocoa headers. They are mentioned here to avoid frustration.
Although Apple has taken the time to fully document these methods, they do nothing no matter how hard
you try to make them work.

NOTE

It is obvious that images could be put in a slider's track because this is done in the color
panel. The Application Kit actually uses an undocumented NSSlider subclass to
implement this functionality.

Titles for Sliders

The NSSlider and NSSliderCell classes define several methods for drawing a title on the slider. If
they are used, a separate cell is used to draw the slider's title. Unfortunately, the title is drawn in the
middle of the slider, and can be obscured by the knob. Because of this, the title methods should be
avoided for sliders. Instead, it is best to use a separate text field object placed near the slider to act as a
label. This is also how labels should be placed to show the user a slider's range.

Text Fields

Text fields are controls that can display or edit text. A noneditable text field can be used as a text label in
a user interface. It is possible to configure a text field so that the data it displays is given a specific
format. Editable text fields can be used for data entry of string or numeric values. Such fields can be set
up to validate input, rejecting unacceptable values.

Similar to other controls, text fields are implemented by two classes. The NSTextField class is a
subclass of NSControl, and the NSTextFieldCell class is a subclass of NSActionCell. The
NSDateFormatter and NSNumberFormatter classes, both subclasses of NSFormatter, work
with text fields to implement formatting and validation.

The Cocoa-Views palette in Interface Builder contains four instances of NSTextField; three are
configured as labels and one is editable. The palette also has instances of NSDateFormatter and
NSNumberFormatter. Figure 10.9 shows where these objects are located on the Cocoa-Views palette.
There is also an NSForm object on the palette. The NSForm class is more complex than a text field. It is
described in the "Compound Controls" section later in this chapter. The separator objects are discussed in
the "Boxes" section later in this chapter.

Figure 10.9. Text fields on the Cocoa-Views palette.

Text Field Options in Interface Builder

All the options for configuring a text field can be found in Interface Builder's NSTextField inspector.
This inspector, shown in Figure 10.10, is displayed by using the Cmd-1 key equivalent when an
NSTextField or an NSTextFieldCell is selected.

Figure 10.10. Interface Builder's text field/text field cell inspector.

The title field in the inspector can be used to change the text displayed by the view. This can also be
edited by double-clicking the text field in Interface Builder.

The color of the text and the background color of the field can be set with the two color wells. Dragging a
color swatch and dropping it on the text field also changes the text color. The Draws Background switch
can be used to suppress drawing the background for some border types.

The alignment control changes where the text is drawn in the field. The tag field at the bottom of the
inspector is used to set the text field's tag. Both controls are described earlier in this chapter as part of the
discussion of the NSControl class.

The border control selects between three border types. The left button, with the dashed line, is used to
configure a text field to have no border. The middle button, with a solid black line, is for bordered text
fields. The border is drawn as a 1-pixel thick black line. The border's color cannot be changed. The right
button sets the text field to have a bezeled border. Figure 10.11 shows the border control. The setting of
this control enables or disables the Draws Background switch. Bezeled fields always draw their
backgrounds. The background can be turned off for bordered or unbordered text fields.

Figure 10.11. Border control in Interface Builder's text field/text field inspector.

The send action radio buttons control when the text field sends its action. The On end editing setting
causes the action to be sent whenever the text field's editing ends. This happens when the user presses the
Return key, tabs to a new field, or clicks in another field to change focus. This is the default behavior.
The Only on enter setting causes the action to only be sent if the user hits the Return (or Enter) key.

The options box offers four options for text fields. The Editable switch determines whether the text field's
value can be changed by the user. If the field is bezeled, making it noneditable lightens (dims) the color
of the bezel. The Enabled switch can be used to disable a text field, even if it is editable. This setting is
often changed as a program runs. A disabled text field dims its text.

The Selectable switch is always turned on for an editable text field. For noneditable fields, this switch
controls whether the user can select the text and use the Copy command. Usually, text fields used as
labels are not selectable. Making a field noneditable, but selectable is useful primarily to allow the user to
copy data from the field while disallowing modification. For example, some programs use a unique host
ID for generating licenses. The host ID is immutable, so a field displaying it should not be editable.
Usually, such IDs are prone to being mistyped, however, so it is wise to allow the user to copy the value
from the host ID field. It can then be pasted elsewhere, avoiding the possibility of typing mistakes.

The Small switch chooses a smaller version of the text field. It changes both the font and bounds of the
text field object. This can be convenient, but is somewhat redundant because the font of the text field can
be changed with the standard font panel, and the text field itself can be resized to any arbitrary size by
dragging the object's resize handles.

The Layout radio buttons control how the text field renders text that is too wide to fit within its bounds. If
it is set to Scrollable, the text always is a single line in height. As the user types, the text scrolls leftward
to make room for new characters. This is generally the preferred behavior for simple data-entry text
fields. The Wraps setting is used to make the text wrap to multiple lines. In Figure 10.2, shown earlier in
this chapter, the text fields on the right side of the window are all set to wrap instead of scroll.

Configuring an NSTextField

As with all Cocoa controls, the NSTextField and NSTextFieldCell classes define methods that
implement all the functionality accessible from the Interface Builder inspector. These methods can be
used to programmatically configure text views or change their appearance as a program runs. Both
classes implement the same set of methods.

The text field's value can be set using the standard NSControl methods, such as -
setStringValue:. This is labeled as the Title in the Interface Builder inspector.

NOTE

Some of the more complex user interface controls have titles that are distinct from the
values they contain and/or edit. Such controls use the -setTitle: and -title methods
for the titles and the normal value accessors such as -setStringValue: and -
stringValue for the data. Because the Interface Builder inspector's label says Title for a
text field's value, it is common to mistakenly use the -setTitle: and -title methods
instead of the appropriate value accessor methods when working with text fields.
A text field's colors are controlled by three pairs of accessor methods that correspond to the controls in
the Color box of the Interface Builder NSTextField inspector. Set the colors by passing an NSColor
object to the -setTextColor: and -setBackgroundColor: methods. The -textColor and -
backgroundColor methods both return an NSColor. The NSColor class is described in Chapter
17, "Color." For text fields used as labels, it is common to not draw a background color, so that the
window's background shows through. To turn the background color on or off, pass YES or NO to the -
setDrawsBackground: method. The -drawsBackground method returns the current setting.

The text field's border is controlled by the -setBordered: and -setBezeled: methods. The
current setting can be determined with -isBordered and -isBezeled. Only one feature, bezeled or
bordered, can be active at a time. If both are set, the bezel will win out.

To change the way a text field lays out its text, use the -setScrollable: and -setWraps:
methods. Use -isScrollable and -wraps to determine the current settings. The scrollable and
wraps options are mutually exclusive. Setting one causes the other to be unset. These four methods
correlate to the Layout radio buttons in Interface Builder.

Editability of a text field is controlled by the -setEditable: method. Selectability is controlled by

the -setSelectable: method. These methods correlate with the Editable and Selectable switches in
Interface Builder. The current settings are returned by the -isEditable and -isSelectable
methods.

The NSTextField class also responds to the action message -selectText:. Sending this message
attempts to make the text field become the first responder, and then all the text in the field will be
selected. This method is the one to use to programmatically change the keyboard focus to a particular text
field.

Tabbing Between Text Fields

Cocoa supports use of the Tab key to move focus from one text field to another. This process works as a
loop within each window. Continually pressing Tab moves keyboard focus from one field to the next
until it returns to the field where it started. When a window is first brought onscreen, focus will be on the
first field in the loop.

Cocoa sets all this up automatically. The first text field in the loop is the field that is topmost and leftmost
on the window. Focus then moves from left to right, and then from top to bottom across the window.
Tabbing out of the bottommost, rightmost field returns the focus to the first field.

If Cocoa's automatic tab loop in unsuitable, it is possible to manually set up a different tab loop. To do
this, each of the fields must be connected together. Drag a connection from a field to the next field in the
Tab loop and set the connection to the nextKeyView outlet. This should be done for every field in the
loop. To identify the first field in the loop, drag a connection from the window to the first field and set
the connection to the initialFirstResponder outlet.

NSTextField Delegates

Text field objects can have delegates to help modify their behavior. As usual, the delegate accessor
methods -setDelegate: and -delegate are available. NSTextField objects send the following
messages to their delegate:

- (BOOL)textShouldBeginEditing:(NSText *)textObject;
- (BOOL)textShouldEndEditing:(NSText *)textObject;
- (void)textDidBeginEditing:(NSNotification *)notification;
- (void)textDidEndEditing:(NSNotification *)notification;
- (void)textDidChange:(NSNotification *)notification;

The methods returning a BOOL can be used to prevent the start or end of editing. The remaining methods
notify of various changes in the text field's state.

Many text fields don't actually need to have a delegate. Many of the functions that would be performed
by a delegate can be performed by formatter objects instead. To learn about formatter objects, see the
"Validation and Formatters" section later in this chapter.

The Field Editor

Text rendering and editing is an extremely complex task. The NSTextField and
NSTextFieldCell classes are too lightweight to handle all the complexities involved. Rather than
lose functionality or duplicate code, all text fields share a single NSText object called the field editor.

The NSText class is extremely heavyweight and supports all the most advanced features of text
handling Cocoa offers. Sharing a single instance helps to simplify the implementation of the text-field
classes while amortizing the overhead of the NSText class across several NSTextFieldCell
instances.

Normally, developers don't need to worry about the field editor. It remains behind the scenes, doing its
thing. When subclassing NSTextFieldCell, however, it is often necessary to intervene and configure
the field editor for the new subclass. This is usually done by overriding the NSTextFieldCell
method -setUpFieldEditorAttributes:. This method is handed an NSText instance, the field
editor, and should return the same instance after finishing. It is common to call the super
implementation of the method when overriding.

Other methods are related to the field editor, but they are beyond the scope of this book. Refer to the
documentation for the NSControl class for information about these methods. Furthermore, many of the
NSControl delegate methods allow customization of field editor behavior without a need for
subclassing.

Input Managers

All Cocoa text objects make use of input managers to handle complex input tasks. They allow the user to
type characters not available on their keyboards. This is used heavily for oriental languages, but even
European languages take advantage of this facility for adding accents and other diacritical marks to
characters. The NSText class is the primary customer of input managers' services. Because text fields
use an NSText as their field editor, all NSTextField and NSTextFieldCell instances can
implicitly take advantage of this rich functionality.
Input managers are typically separate processes that communicate using RPC. The NSInputManager
and NSInputServer classes implement the actual functionality. Under normal circumstances,
developers never need to work with either class directly. All interation is handled automatically and
transparently by NSText. Menus to allow users to change between input managers are also fully
automatic. Cocoa adds the appropriate menus as necessary without any developer intervention.

Developers wanting to create custom input managers should consult the Cocoa documentation for the
NSInputManager and NSInputServer classes. The developer example at /Developer/
Examples/AppKit/HexInputServer is also very helpful.

Secure Text Fields

The NSSecureTextField and NSSecureTextFieldCell classes implement a special variation

on the standard text field. Secure text fields override the normal field editor behavior so that the field's
value is not displayed when the user types. For added security, it also prevents the standard cut, copy, and
paste operations. This type of text field should always be used for extremely sensitive data such as
passwords.

Unfortunately, all NSSecureTextField objects must be created programmatically because Interface

Builder does not yet have an instance of this class on any of its palettes. A partial workaround for this is
to create an NSTextField object where the secure field is wanted, and then change it to an
NSSecureTextField in the Custom Class inspector (Cmd-5). The cell class is not changed, however,
and there's no way to change it in Interface Builder as of Mac OS X 10.1.4. Therefore, when the .nib is
unarchived, it is necessary to create a new NSSecureTextFieldCell object and pass it to the
NSSecureTextField by using the -setCell: method.

The NSSecureTextFieldCell class can have one of two behaviors. It can echo a user's typing as
either a series of bullets (small, black-filled circles), one per character typed, or by moving the cursor, but
drawing nothing. The -setEchosBullets: method controls which behavior is used and the -
echosBullets method returns the current setting. Unlike most methods used to configure control and
cell pairs, these methods are only implemented by the cell subclass.

Validation and Formatters

Cocoa supports automatic validation and formatting of text field entries. When validation is being used, a
user is not allowed to stop editing a field until it contains a legal value. The computer beeps if they try to
click in another field or Tab to the next field. Formatting concerns how a field displays its values.
Formatting includes instructions such as how many decimal places to display for numeric values or
which separators to use for date strings. The abstract class NSFormatter is designed to perform both
validation and formatting tasks. Cocoa supplies two concrete subclasses, NSNumberFormatter and
NSDateFormatter.

For other types of validation, such as Zip codes, phone numbers, or application-specific validation a
custom subclass of NSFormatter is required. Subclassing NSFormatter is shown in Chapter 11.
The reader should also refer to the third-party frameworks listed in Appendix C, "Finding Third-Party
Resources." Many of these frameworks have very good examples.

The easiest way to configure formatters is to use Interface Builder. There are two ways to attach a
formatter to a text field in Interface Builder. The first is to drag a formatter off the Cocoa-Views palette
and drop it onto a text field. The formatter will automatically be attached to the text field. The second is
to drop the formatter into the main .nib window. Drag a connection from the text field to the formatter
and connect it to the formatter outlet.

The interface between these two approaches is slightly inconsistent in Interface Builder as of the April
2002 developer tools release. When a formatter is dropped onto a text field, it can be adjusted with a
formatter inspector brought up by Cmd-7. The formatter object remains invisible, so although a formatter
is connected to the field, the connection won't be shown in the connections inspector. On the other hand,
dragging an explicit connection between a text field and a formatter gives a connection that shows up in
the text field's connection inspector. But the text field won't have a Cmd-7 format inspector available,
even though there is a formatter attached. To get the formatter inspector, the formatter itself needs to be
selected and its attributes inspector (Cmd-1) should be brought up.

The second approach, dragging an explicit connection to a formatter instance in the main .nib file, is
the only approach that allows a single formatter to be shared between multiple text fields. Because
formatters can be shared, it is a good idea to do so whenever possible.

Program code can use the NSControl/NSCell methods -formatter and -setFormatter: to
retrieve and change the formatter for a given field, respectively.

Both of the formatters provided by Cocoa, for dates and numbers, are easiest to configure with Interface
Builder. When set up, there is rarely a need to change them programmatically. In fact,
NSDateFormatter instances are immutable. The date formatter's inspector in Interface Builder offers
two options. The first is the date format to be used, and the second is whether to allow natural language.
The date formatter inspector is shown in Figure 10.12.

Figure 10.12. Interface Builder's NSDateFormatter inspector.

Clicking one of the preset formats in the table automatically fills the Custom Format field with the right
value. Alternatively, any format can be typed into this field. The format should follow the format
specifiers accepted by the strftime() C function. Type man strftime at the command line to see
the function's manual page, which lists all the options.

Turning on the switch to allow natural language makes it possible for the user to type things like
yesterday, next week, today, and so on. The phrase is parsed, the date is calculated, and the
correct date is put into the text field being formatted. This is very useful, and works remarkably well, but
it isn't perfect. For example, relative terms can be problematic. The phrase "two days ago" doesn't work
at all and "day before yesterday" incorrectly fills yesterday's date into the field. So, although this is a
really neat feature, it might not be acceptable for all uses.

To programmatically create a date formatter, use the designated initializer -initWithDateFormat:

allowNaturalLanguage:. The -dateFormat and -allowsNaturalLanguage methods
return the object's characteristics. NSDateFormatters are immutable, so there are no -set accessor
methods.

The number formatter's inspector in Interface Builder offers several complex options. It is shown in
Figure 10.13.

Figure 10.13. Interface Builder's NSNumberFormatter inspector.

The easiest way to set a number format is to use one of the preset formats available in the table at the top
of the inspector. There are formats for floating-point numbers, integers, money, and percentages. Any
format can be selected from the table by clicking on its row. The relevant settings will be made in the rest
of the inspector panel.

The other way to set a number format is to provide a format for positive, zero, and negative numbers. In
the formats, characters such as spaces, dollar signs ($), and percent signs (%) will be used verbatim in the
output. Zeros are used as placeholders for digits that should always exist. These digits are zero-filled if
necessary, allowing for leading or trailing zeros to be defined. Pound signs (#) are used for optional digits
and repeat as necessary. They are used primarily in formats that have thousands separators. The Add
1000 Separators switch must be on for this to work. To get a better feel for how the formats are defined,
it is best to play with the Interface Builder inspector a bit and watch how the appearance samples change.

The minimum and maximum settings allow the range of numbers to be constrained. This is especially
useful for text fields associated with sliders. The Negative in Red switch can be used to make negative
numbers be displayed in red instead of the field's normal text color. The normal text color is still used
when editing the field, even if it contains a negative value, and the negative color can only be red.

The Add 1000 Separators switch enables and disables the separators, and takes precedence over what the
formats in the fields above it say to do. In some locales, the character used for decimal points and
thousands separators are swapped. In the United States, a period (.) is used as the decimal point, and a
comma (,) is used as the thousands separator. This is reversed in many other countries. The , <-> . switch
swaps the separators. The Localize switch overrides that setting and swaps the separators only when
necessary, depending on the locale. In most cases, using the localize feature is preferred because it should
always do the right thing for the current locale.

The Detach Formatter button in both the date and number formatters' respective inspectors can be used to
delete the formatter instance. Clicking the button causes the formatter object to be deallocated with the
side effect of severing any connections made to the formatter. This button works for both shared and
private formatters, so it should be used with care. To detach a shared formatter from only one text field
instead of all fields, select the field in question and disconnect the formatter outlet.

Dozens of methods can be used to adjust an NSNumberFormatter. Rather than discuss them all here,
refer to the class reference sheet. It can be found as part of the developer documentation at /
Developer/Documentation/Cocoa/Reference/Foundation/ ObjC_classic/
Classes/NSNumberFormatter.html. Many of the methods do not directly correspond to the
controls in the Interface Builder inspector, though all the same functionality is available.

Image Display

Image views are used to display images. For instance, an image view can be used to skin a window's
content area. Image views can also be used as a way for users to select images. When editable, a user can
drag an image to an image view and drop it there. Image views are implemented in Cocoa with the
NSImageView and NSImageCell classes.

NOTE

The class names NSImageView and NSImageCell don't follow the naming convention
established between the other Cocoa control/cell pairings. There is already an NSImage
class for representing images (described in Chapter 14) so that name is not available for this
control. The name NSImageViewCell is cumbersome and misleading because the cell is
not a view, so NSImageCell is used.

Image views are found on the Cocoa-Other Interface Builder palette. (Refer to Figure 10.7 shown earlier
in this chapter to see this palette.) The NSImageView instance is the rectangular object with rounded
corners that is displaying a picture of a mountain.

Image View Options in Interface Builder

All the options for configuring an image view can be found in Interface Builder's NSImageView
inspector. This inspector, shown in Figure 10.14, is displayed by using the Cmd-1 key equivalent when
an NSImageView or an NSImageCell is selected.

Figure 10.14. Interface Builder's image view inspector.

There are five configurable features in the NSImageView class-icon, border, alignment, scaling, and
editability. The icon is the name of the image being displayed. This can be the name of an image in the
project, one of the system bitmap names, or even the full path of an image anywhere in the file system.
The border can be turned on or off. Cocoa actually supports other options for the border, but they are not
Aqua-compliant. To avoid the temptation to use these extra options, they aren't available from within
Interface Builder.

The alignment and scaling determine how the image is displayed. Alignment controls where the image is
placed within the view, and scaling allows the image to be stretched. Each of the scaling options is worth
examining. Proportional scaling means that the image will be shrunk in size if it doesn't completely fit
within the view's bounds. The scaling will be done proportionally, which preserves the image's aspect
ratio. Scaling to fit will expand or shrink the image as necessary to make it cover the entire bounds of the
view. This can seriously distort the image if the view's aspect ratio differs significantly from the image's
aspect ratio. No scaling will always render the image without any size adjustment or distortion. If the
view is too small, the excess parts of the image will be clipped (cropped) so that the image stays within
the bounds of the view.

The editable parameter determines whether the user is allowed to drag and drop new images into the
image view. It is usually best to disable this for borderless image views because the user wouldn't know
that there was an active control without the border to send the necessary visual cues.

Modifying Image View Instances

A few methods are available in NSImageView and NSImageCell to expose the functionality used in
Interface Builder.

The image view's image, labeled Icon in Interface Builder, can be manipulated with the -setImage:
and -image accessors. They take and return an NSImage instance, respectively. Refer to Chapter 14
for an in-depth discussion of NSImage. To make the view editable or not, or see the current setting, use
the standard NSCell methods -setEditable: and -isEditable.

To work with the border of an image view, use the -setImageFrameStyle: and -
imageFrameStyle methods. They take and return the constants NSImageFrameNone,
NSImageFramePhoto, NSImageFrameGrayBezel, NSImageFrameGroove, and
NSImageFrameButton. Only the NSImageFrameNone and NSImageFramePhoto constants
should be used to keep within the Aqua guidelines.

Scaling options are accessed with the -setImageScaling: and -imageScaling methods. The
constants used by these methods are NSScaleProportionally, NSScaleToFit, and
NSScaleNone. Alignment is accessed with the -setImageAlignment: and -imageAlignment
methods. The following constants can be used with the alignment methods:

NSImageAlignCenter

NSImageAlignTop

NSImageAlignTopLeft

NSImageAlignTopRight

NSImageAlignLeft
NSImageAlignBottom

NSImageAlignBottomLeft

NSImageAlignBottomRight

NSImageAlignRight

The default image scaling is NSScaleProportionally. The default image alignment is

NSImageAlignCenter.

Progress Indicators

Progress indicators can be used to provide feedback about long-running processes. There are two types of
indicator: indeterminate and determinate. An indeterminate progress indicator looks like a sideways
barber pole. While a long-running task is being performed, it appears to spin. This animation tells the
user that the program hasn't hung up. Determinate progress indicators start out empty and fill in their
bounds from left to right as a process is completed. The filled-in part of the progress indicator has a
subtle animation that makes it look somewhat like flowing water.

Progress indicators are implemented by the NSProgressIndicator class. This class is a subclass of
NSView, not NSControl, and has no partner NSCell subclass. Because of this, progress indicators
cannot be used in matrices or other objects requiring cells. A progress indicator instance can be found on
Interface Builder's Cocoa-Other palette. (Refer to Figure 10.7 earlier in this chapter to see the palette.) It
is set to be indeterminate, so it looks like a sideways barber pole.
Progress Indicator Options in Interface Builder

All the options for configuring a progress indicator can be found in Interface Builder's
NSProgressIndicator inspector. This inspector, shown in Figure 10.15, is displayed by using the
Cmd-1 key equivalent when an NSProgressIndicator is selected.

Figure 10.15. Interface Builder's progress indicator inspector.

This inspector is very simple. The progress indicator's type, indeterminate or not, is set with the
Indeterminate switch. The Small switch is used to choose a smaller version of the progress indicator.

If the progress indicator is determinate, the range parameters become meaningful. When a long task is
running, it periodically updates the progress indicator's value to show how far the task has proceeded.
The range is set beforehand to tell the indicator the range of values it should expect to see between
starting and completing the task. Then, as the value changes, the progress indicator knows how much of
its bar should be colored in. The default range of zero to 100 nicely matches the idea of percent complete.
Of course, any range will work, so it is best to choose a range that best suits the task reflected by the
progress indicator.

There is no way to set the progress indicator's value in Interface Builder. This must be done through
program code. In general, the NSProgressIndicator class requires some amount of code to be used
properly.

NSProgressIndicator Methods
The basic options offered from Interface Builder are available from a set of self-explanatory accessor
methods. They are

- (BOOL)isIndeterminate;
- (void)setIndeterminate:(BOOL)flag;
- (NSControlSize)controlSize;
- (void)setControlSize:(NSControlSize)size;
- (double)minValue;
- (double)maxValue;
- (void)setMinValue:(double)newMinimum;
- (void)setMaxValue:(double)newMaximum;

The NSControlSize type is enumerated and can be either NSRegularControlSize or

NSSmallControlSize.

If a progress indicator is determinate, its value can be manipulated by using the -setDoubleValue:
and -doubleValue methods. These are the only two value accessors available. Because this class isn't
a control, it doesn't implement other value accessors such as -setIntValue:, and so on. The method
-incrementBy: can be used to move the progress indicator forward by a set amount. It takes a double
as its parameter. The -incrementBy: method is for convenience only, so the following two lines of
code are equivalent:

[myIndicator incrementBy:someDelta];
[myIndicator setDoubleValue:[myIndicator doubleValue] + someDelta];

There are also several methods that can be used to start, stop, and control the animation of an
NSProgressIndicator. To start the animation, use the -startAnimation: action method. The
-stopAnimation: action method stops the animation. To manually advance the animation by one
frame, call the -animate: action method. This method's sender argument is ignored.

The speed of the animation can be adjusted with the -setAnimationDelay: method. The -
animationDelay method returns the current delay. These methods work with the
NSTimeInterval type, which is a floating-point number representing seconds. So, an interval of 0.5
would mean two frames per second.

It is possible to have the animation of the progress indicator be run from an NSTimer in the main thread
or from a separate thread. If the task being monitored runs in the main thread and blocks the main event
loop until it is finished, it is usually best to run the animation from a separate thread. If a background
worker thread is being monitored, running a separate thread might not be necessary. Chapter 24,
"Subprocesses and Threads," describes threads in detail and includes an example that uses an
NSProgressIndicator. To change the threading behavior of an NSProgressIndicator
instance, use the -setUsesThreadedAnimation: method. Use the -
usesThreadedAnimation method to see the current setting.
Book: Cocoa® Programming
Section: Chapter 10. Views and Controls

Container Views and Controls

Several of Cocoa's view subclasses can be wrapped around other Cocoa views. Because of these
behaviors, they are often referred to as containers. Boxes, scroll views, tab views, split views, and
matrices can all be considered containers. Boxes simply draw a pretty border around the views
they contain. A scroll view allows a user to scroll around a view that is much larger than the scroll
view itself. Tab views allow users to switch between several related views. Split views provide a
separator that can be dragged to reallocate screen real estate between two views.

NOTE

Most Cocoa containers use both the GOF Decorator and GOF Facade patterns.
Chapter 6, "Cocoa Design Patterns," briefly discusses these and other patterns found
in Cocoa.

In Interface Builder, the Cocoa-Containers palette, shown in Figure 10.16, has tab view and box
instances on it. These instances can be dragged into any window. Matrices, scroll views, and split
views are not available on any palettes, however. Interface Builder offers an alternative means of
creating these views. First, select one or more views that are to become subviews of the container.
Next, select one of the items in the Layout>Make subviews of> menu. This enables
arbitrary views to be wrapped in a box, scroll view, split view, tab view, or a custom view
subclass.

Figure 10.16. Interface Builder's Cocoa-Containers palette.

After a container instance has been created, double-clicking the container or clicking one of the
container's visible subviews enables the contents of the container to be edited. Items can also be
dragged from the palette into the container.

Boxes

Boxes are used to visually group user interface items. Normally, boxes draw a border around their
bounds and a title at the top. Boxes do not accept user input. Boxes are implemented by the
NSBox class. Figure 10.17 shows three variations of the basic box available in Interface Builder.
There is an NSBox instance on the Cocoa-Containers palette, as shown in Figure 10.16. Refer to
the previous section "Container Views and Controls" for instructions on how to create an NSBox
instance in Interface Builder.

Figure 10.17. NSBox instances created with Interface Builder.

Some boxes are drawn to be very narrow. Look for the vertical and horizontal separator lines in
the Cocoa-Views Interface Builder palette. (The palette is shown in Figure 10.9 earlier in this
chapter.) These separators are actually instances of NSBox. It is not possible to change an NSBox
instance from a rectangular box into a separator or vice-versa, even though they are the same
class. Separators can't be changed between being vertical or horizontal, either. Interface Builder
prevents such changes. Instead of changing existing instances, a new instance of the right kind
would need to be dragged from the palette.

Box Options in Interface Builder

All the options for configuring a box can be found in Interface Builder's NSBox inspector. This
inspector, shown in Figure 10.18, is displayed by using the Cmd-1 key equivalent when an
NSBox is selected.

Figure 10.18. Interface Builder's NSBox inspector.

Interface Builder offers two options for boxes, changing the title and type of the box. The Title is
Visible switch turns the title on or off. The title itself can be changed by modifying the text field
under the switch. It can also be changed by double-clicking the title on the box itself and
modifying the title in place.

NOTE

Setting the title to an empty string is not the same thing as making it invisible. A
box actually obscures part of its border before drawing the title. An empty title still
leaves a small gap in the border. Making the title invisible makes the box border
seamless.

The Box Type control allows the choice between three styles of box, as shown in Figure 10.17.
The rightmost box is actually borderless. Most boxes seen in Aqua are of the leftmost style.

NSBox Methods

It is easiest to configure an NSBox in Interface Builder and be done with it. Several accessor
methods can be used to make changes programmatically, though. Several options that are
available through code are not offered in Interface Builder. These extra options sometimes create
boxes that are not Aqua compliant, so extra care should be taken with these methods to ensure a
user interface that looks like it really belongs on Mac OS X.

To turn the border on or off, use the -setBorderType: method. Use -borderType to see
the current setting. Four constants are available for use with these methods, NSNoBorder,
NSLineBorder, NSBezelBorder, and NSGrooveBorder. The NSNoBorder constant
gives a borderless box. NSGrooveBorder is the default setting for all boxes. To change the
style of the box, use -setBoxType:. Use -boxType to see the current setting. Four constants
can be used with these methods, NSBoxPrimary, NSBoxSecondary, NSBoxSeparator,
and NSBoxOldStyle. The leftmost box shown in Figure 10.17 is a primary style box, whereas
the center box exhibits the secondary style. Separators are thin lines placed between user interface
elements and do not enclose any views. The old style box should be avoided because it is not
Aqua compliant.

The title is manipulated with the -setTitle: method. The current title is returned by the -
title method. The title font is changed with the -setTitleFont: method. The current title
font is returned by the -titleFont method. The title's position can be changed with the -
setTitlePosition: method. The current position is returned by the -titlePosition
method.

The title position methods work with several different constants. Interface Builder uses the
NSNoTitle and NSAtTop constants, controlled by the Title is Visible switch. These are the
only two that are Aqua compliant. The other constants that are available, but should be avoided,
are NSAboveTop, NSBelowTop, NSAboveBottom, NSAtBottom, and NSBelowBottom.
The title position can be at the top or bottom border of the box. A title can also be above, below,
or at the border. Titles at the border interrupt the border, whereas titles above or below the border
do not.

Every box has a content view object. All the views enclosed by a box are subviews of the content
view. To manipulate the content view of a box, use the -setContentView: method. The
current content view is returned by the -contentView method. Using the normal NSView
methods -addSubview: and -replaceSubview:with: will also do the right thing,
adding the views to the content view of the box.

Borderless Boxes

A common use of borderless boxes is to implement inspectors such as the one in Interface
Builder. The inspector changes its user interface based on the current selection. To support this, it
is convenient to define an inspector view for each object that might be selected. An inspector
view will typically be an NSBox instance containing the full user interface for the object's
inspector.

When it comes time to swap one inspector interface with another, a tabless NSTabView or other
appropriate container is used as a container, and the inspector views are swapped in and out. The
container and inspector view are invisible to the user. All the user sees is that one set of controls
has vanished and a new set has appeared. (Tab views are explained in the upcoming "Tab Views"
section.)

Scroll Views

Scroll views allow a large view, such as a document, to be displayed in a much smaller window.
The large view being scrolled is known as the scroll view's document view. By adding scrollbars
around the edges of the document view, it becomes possible to navigate through extremely large
views. Scroll views can also optionally manage rulers and ruler markers.

A scroll view is implemented in Cocoa with the NSScrollView class. A scroll view contains
multiple subviews in addition to its document view. Instances of NSScroller implement the
scrollbars. The content area of the scroll view, called the content view, is actually an
NSClipView instance. The document view being managed by the scroll view is really a
subview of the clip view. The clip view can be thought of as a window that displays only a
portion of the document view at any given time. Scroll views that have rulers use instances of
NSRulerView and NSRulerMarker. Figure 10.19 shows how these views are normally laid
out by a scroll view.

Figure 10.19. The layout of subviews inside an NSScrollView instance.

Refer to the previous section "Container Views and Controls" for instructions on how to create an
NSScrollView instance in Interface Builder.

Scroll View Options in Interface Builder

All the options for configuring a scroll view can be found in Interface Builder's NSScrollView
inspector. This inspector, shown in Figure 10.20, is displayed by using the Cmd-1 key equivalent
when an NSScrollView is selected.

Figure 10.20. Interface Builder's NSScrollView inspector.

The background color is displayed as the scroll view's background if the views it encloses are
transparent or do not cover the entire content area of the scroll view. It is common to set this color
to a shade of gray if the default window background color is unacceptable.

The border setting allows there to be no border, a solid black line, a bezel, or a groove. Most user
interfaces use the bezeled border if the scroll view is not the only user interface element in its
window. If the scroll view is the only element, it is preferable to use no border and size the scroll
view so that it covers the entire window content area. An example of this would be a document
window in TextEdit.

The scrollbars are actually optional. Normally, it is best to have at least one scrollbar visible. It is
entirely possible, though, to use a scroll view as if it were a sliding window over a view. In such a
situation there would be no scrollbars and the application would programmatically move the
scroll view, as necessary. The scrollers can also be set to use small versions. This is handy for
cramped interfaces, but should not be done for full-window scroll views.

The Parameters box controls scrolling behavior. The first parameter, Line Amount, controls how
many pixels the scroll view will move when an arrow is clicked on one of the scrollbars. The
Page Context parameter is trickier. When a scroll arrow is Option-clicked, it asks the scroll view
to scroll by a page instead of a line. The default behavior is to move the scroll view so that
whatever was shown at the bottom of the scroll view before the page scroll is moved to the top of
the scroll view after the scroll. The page context tells the scroll view how many pixels of data
from the bottom (before the page scroll) should remain visible at the top (after the page scroll). A
setting of zero means that the last row of pixels before the scroll will be just off the top of the
screen after the scroll. A positive setting means that slightly less than a screenful will be
considered to be a "page" for scrolling purposes.

Scroll views implement methods to expose all the functionality that is supported by Interface
Builder. There is also a large amount of functionality that is not currently available from Interface
Builder, so it is common to write some set up code to make final tweaks to a scroll view after it is
loaded from a .nib.

Configuring NSScrollView Rendering

The background color of a scroll view is controlled with the -setBackgroundColor: and -
setDrawsBackground:, methods. The current settings are returned by the -
backgroundColor and -drawsBackground methods. In Interface Builder, background
drawing is always turned on. Turning it off makes it possible for views underneath the scroll view
to show through.

The border is manipulated with the -setBorderType: method. The current border type is
returned by the -borderType method. These methods use the same four border type constants
as boxes, NSNoBorder, NSLineBorder, NSBezelBorder, and NSGrooveBorder.

Scrolling Parameters

The scrollers are turned on and off with the -setHasVerticalScroller: and -
setHasHorizontalScroller: methods. The scroller status is returned by the -
hasVerticalScroller and -hasHorizontalScroller methods. To change the
scroller size, it is necessary to manipulate the scroller objects themselves. The accessors for the
scroller objects are -setVerticalScroller:, -verticalScroller, -
setHorizontalScroller:, and -horizontalScroller. All four scroller accessors
either accept or return NSScroller instances.

The NSScroller class implements scrollbars. Normally, there is little need to manipulate this
class directly. The NSScrollView class takes care of all interaction with the class
automatically. Scrollers are controls, so it is possible to use the standard NSControl methods to
configure them. Scrollers do not have an associated cell subclass.

The scrolling parameters for line amount and page context from Interface Builder are controlled
by several methods. All these methods work with float values. The line amount is accessed
with -setLineScroll: and -lineScroll. The page context is accessed with -
setPageScroll: and -pageScroll. These methods treat the horizontal and vertical
scrolling amounts identically. It is possible to treat the horizontal and vertical directions
differently. The following methods control the scrolling parameters precisely in just the
horizontal or vertical direction:

- (void)setHorizontalLineScroll:(float)value
- (void)setVerticalLineScroll:(float)value
- (float)horizontalLineScroll
- (float)verticalLineScroll
- (void)setHorizontalPageScroll:(float)value
- (void)setVerticalPageScroll:(float)value
- (float)horizontalPageScroll
- (float)verticalPageScroll

Rulers in Scroll Views

A scroll view wrapped around an NSText object is already set up to use rulers. To have rulers
available for any other type of scroll view content requires some extra code. By convention, rulers
are turned on and off by sending the -toggleRuler: method down the responder chain. The
NSScrollView class doesn't support the -toggleRuler: action method. Instead, this
method must be implemented by the class that is the scroll view's document view. This may seem
odd because the ruler is actually laid out by the scroll view as one of its subviews. The NSText
object in Interface Builder has the capability to show rulers because it implements the -
toggleRuler: method. A -toggleRuler: method implementation should be written to
cooperate with the enclosing scroll view to manage the rulers.

Prior to making the rulers visible, the ruler objects need to be set up. The -
setHorizontalRulerView:, -horizontalRulerView, -
setVerticalRulerView:, and -verticalRulerView accessors work with
NSRulerView objects to set up and retrieve the rulers. The -setHasHorizontalRuler:
and -setVerticalRulerView: methods can be used to turn the rulers on or off,
individually. Finally, the -setRulersVisible: method causes the enabled rulers to be either
displayed or not. The -rulersVisible method returns the current setting. The scroll view
tries to automatically set up its rulers if possible. How this is done can be altered by telling the
scroll view class which ruler class to use. Use the +setRulerViewClass: and
+rulerViewClass class methods to do this.

Ruler views require a client view. The client view is the view being measured by the rulers. The
scroll view will not automatically connect the document view to the ruler as a client. It is up to the
document view to complete this part of the setup. The document view should use the
NSScrollView -horizontalRulerView and -verticalRulerView accessors to
obtain the rulers from the scroll view. After it has the rulers, the document view can call the
NSRulerView -setClientView: method to set up the client relationship.

Rulers inside of scroll views are implemented by the NSRulerView class. Markers along the
length of the ruler, such as tab stops, are implemented with the NSRulerMarker class. A single
ruler view can have many markers. Both classes are highly configurable and relatively easy to
use. The Sketch example at /Developer/ Examples/AppKit/Sketch shows how to use
rulers in the most basic form. The TextEdit example at /Developer/Examples/AppKit/
TextEdit shows a much more complex ruler.

Using an NSScrollView
When working with the contents of a scroll view, it is important to remember that the content
view is actually a clip view instance. The view that is scrolled is the document view, which is in
turn a subview of the clip view. The clip view, an NSClipView instance, is accessed with -
setContentView: and -contentView. The document view is accessed with -
setDocumentView: and -documentView. The size of the content area is returned by -
contentSize. The part of the document view currently being displayed is returned by -
documentVisibleRect.

NOTE

It is rare to work directly with the NSClipView class because NSScrollView

handles it automatically. It is, therefore, best to stick with the document view
methods instead of using the content view methods.

Usually, the only reason to subclass NSScrollView is to add new controls to the interface. A
common control is a zoom pop-up inside the horizontal scrollbar. The main method to override is
the -tile method. This method is called by Cocoa to lay out the scroll view. Calling the super
implementation, and then adjusting the subviews to make room for the new controls usually
accomplishes the desired result. The TextEdit source code at /Developer/Examples/
AppKit/TextEdit shows one way to do this in its ScalingScrollView class.

Another useful method is defined by the NSView class. The -scrollRectToVisible:

method takes an NSRect and attempts to scroll so that the rectangle becomes visible; it returns
YES if successful. This method should be sent to the document view of a scroll view. This is the
primary means of scrolling programmatically. Search the NSView class reference or header file
for the word "scroll" to find a handful of other methods that are occasionally useful when working
with scroll views.

Sometimes a scroll view's document view implements mouse-dragging and wants to scroll
automatically in response to mouse-dragged events. To do this, it should invoke the enclosing
clipview's -autoscroll: method, passing in the mouse-dragged event. Chapter 15 discusses
events, such as mouse-drags, in detail. For now, it is enough to know that simply adding this line
to a custom view's -mouseDragged: method usually suffices:

[[self superview] autoscroll:event];

It is always safe to call the -autoscroll: method because NSView defines it. The
NSClipView class simply overrides -autoscroll: to work effectively with an enclosing
scroll view. If a view isn't in a scroll view, the method call is ignored.

Adding this call in -mouseDragged: causes the scrolling to only happen when the mouse is
moved. To have the scrolling happen continuously, even when the mouse isn't being moved, use
an NSTimer to send the auto scroll message repeatedly. Doing auto scrolling with a timer often
feels smoother to the user.

Tab Views

Tab views are containers that have multiple content views, but only one is available at any given
time. Across the top is a row of labeled tabs that the user can click to move from one pane to
another. Some tab views are tabless. Such views can still switch from pane to pane under program
control, but the user is unaware that this is the case until they see it change. The Animal example
from Chapter 24, "Subprocesses and Threads," puts a tabless tab view to good use. The tabless
form is usually used to implement a wizard interface, where the user steps through a series of
pages to accomplish a complex task.

Tab views are an economical means of putting many, many user interface controls into a
reasonably sized window. The controls in a tab view should be grouped in a logical manner. Each
grouping should be placed on a single tab. An example of putting tab views to good use is the
System Preferences application. Many of the preferences panes it supports contain tab views.

Tab views are implemented by the NSTabView class. Each individual tab is represented by an
NSTabViewItem instance. A typical NSTabView instance owns many NSTabViewItem
instances. There is an NSTabView instance on the Cocoa-Containers palette, as shown in Figure
10.16 earlier in this chapter. Usually, Interface Builder is used to create tab views. Refer to the
previous section "Container Views and Controls" for instructions on how to create an
NSTabView instance in Interface Builder.

Tab View Options in Interface Builder

Options for configuring a tab view can be found in Interface Builder's NSTabView inspector.
This inspector, shown in Figure 10.21, is displayed by using the Cmd-1 key equivalent when an
NSTabView is selected.

Figure 10.21. Interface Builder's NSTabView inspector.

The most significant attribute is the number of items (tabs). Any number can be used, but there
are some caveats. Tab views don't deal well with having too many tabs. They tend to clip out any
tabs that don't fit within the tab view's bounds. To help this situation, the Allows truncated labels
switch can be turned on to reduce the size of the individual tabs a little bit. The Small Tabs switch
might help a little as well. If after all this the tabs are still too large, they will be clipped
regardless. It is a good idea to make sure everything looks good in Interface Builder. Making the
window larger and setting a relatively large minimum window size might be necessary to keep
the user interface looking good.

The other key option is to choose whether the tab view should have tabs. If yes, the tabs will be at
the top of the view. Even in a tabless view, there can still be an arbitrary number of items.
Because tabless views don't have to worry about drawing tabs, any number of items is usable.

NOTE

There is a disabled pop-up button for tab view that is set to Has Tabs. The pop up
looks like it allows the tabs to be put on a different side of the view, but it cannot be
enabled. Tabs are always at the top. The fact that Apple added this pop up in the
December 2001 developer tools release clearly implies that there are plans to allow
tabs to be in other locations in the future.
Tabless tab views can display with or without a border. The Animal example in Chapter 24 uses a
borderless, tabless tab view to implement its primary user interface. A bordered view looks like a
raised box with drop shadow, floating just a tiny bit above the window containing it.

The Draws Background switch only affects tab views that are tabless and borderless. If it is on,
the tab view's background will be drawn in solid black. There is no way to change this, so
drawing the background isn't a terribly useful option at present.

Tab View Item Options in Interface Builder

Options for configuring a tab view item can be found in Interface Builder's NSTabViewItem
inspector. This inspector, shown in Figure 10.22, is displayed by using the Cmd-1 key equivalent
when an NSTabViewItem is selected.

Figure 10.22. Interface Builder's NSTabViewItem inspector.

There are two settings in this inspector-the label and the identifier. The label is the text that
appears on the tab itself, and can also be edited by double-clicking one of the tabs. The identifier
is like a tag on a typical control except that it can be any string value. It doesn't have to be an
integer. This identifier can be used in program code to find tab view items.

The control Displaying Tab Item: with the field and stepper is a convenient means of switching
between tabs while working on a tab view in Interface Builder. This is especially handy for tab
views that are tabless because, in that case, it is the only way to switch from tab to tab in Interface
Builder. The tabs can be selected like normal to switch around, but only if they are visible.

Configuring an NSTabView

When configuring a tab view in code, the InterfaceBuilder controls for tabs/tabless and border
type are combined into a single pair of accessor methods, -setTabViewType: and -
tabViewType. The constants that can be used with these methods are
NSTopTabsBezelBorder, NSNoTabsBezelBorder, NSNoTabsLineBorder, and
NSNoTabsNoBorder. The NSNoTabsLineBorder constant is not available from Interface
Builder.

NOTE

Three other constants are defined in the NSTabView.h header file:

NSLeftTabsBezelBorder, NSBottomTabsBezelBorder, and
NSRightTabsBezelBorder. A note in Mac OS X 10.1 says that these create a
tab view with the tabs at the top, but implies that they will be supported in the future.

The -setAllowsTruncatedLabels: method controls whether the tab view will truncate
the labels, if necessary, to make the tabs fit. The -setDrawsBackground: method turns the
background on and off, but only for the NSNoTabsNoBorder (borderless) tab view type. The
current settings of these attributes are returned by the -allowsTruncatedLabels and -
drawsBackground methods.

Selecting Tabs

Selecting a tab is done by selecting one of the NSTabViewItem instances managed by the tab
view. Tabs can be selected based on identifier with -
selectTabViewItemWithIdentifier:. Tabs can also be selected by index with the -
selectTabViewItemAtIndex: method. The indices run from zero to the number of tabs
minus one. Both methods raise a range exception if a nonexistent tab is requested. When selecting
by index number, examining the number of tabs first with the -numberOfTabViewItems
method can prevent the exception.

A new tab can also be selected in a relative manner. Tabs are considered to run from left to right,
so the first tab is the leftmost tab. The last tab is rightmost. In relation to the currently selected
tab, the previous tab is to the left and the next tab is to the right. Four obvious action methods can
be used to select tabs. They are -selectFirstTabViewItem:, -
selectPreviousTabViewItem:, -selectNextTabViewItem:, and -
selectLastTabViewItem:. These methods are useful when creating a wizard-like interface
that steps the user through a series of tasks. The next and previous actions correspond directly to
the buttons that would be at the bottom of the wizard to move from page to page.
There are also a few methods for looking up tab view items within the tab view. The -
tabViewItems method returns an NSArray with all the items. This array is immutable, so
tabs are not added and removed by manipulating this array. Refer to the "Adding, Removing, and
Modifying Tabs" section later in this chapter to do that. The -selectedTabViewItem
method returns the currently active tab view item or nil if no tab has been selected.

A particular tab view item can be obtained with the -tabViewItemAtIndex:, which returns
an NSTabViewItem instance. As with the selection methods, exceptions are raised for numbers
that are out of range. The -indexOfTabViewItem:, or -
indexOfTabViewItemWithIdentifier: methods both return indices of the items or
NSNotFound. There is no method to get an item based on its identifier. Instead, two messages
must be sent-one to obtain the index, and another to obtain the item.

Adding, Removing, and Modifying Tabs

There are several methods for adding and removing tab view items. These methods function
similarly to the NSMutableArray methods, but the names are more specific. To add an item to
a tab view, it must first be created. The NSTabViewItem class uses the -
initWithIdentifier: method as its designated initializer.

Add a newly created NSTabViewItem instance to a tab view with either -

addTabViewItem: or -insertTabViewItem:atIndex:. The -addTabViewItem:
method adds the tab at the end of the list. Remove an item with the -removeTabViewItem:
method.

A tab view item can be modified in several ways. The identifier and label can be accessed through
the standard accessor methods -setIdentifier:, -identifier, -setLabel:, and -
label. The label is displayed on the tab itself, whereas the identifier is private to the
application's internals. When set in Interface Builder, both are NSString instances, but
identifiers don't have to be strings. An instance of any class is acceptable, so if something makes
more sense than a string, feel free to use it.

A tab view item has a content view. The -setView: and -view methods allow the content
view to be manipulated. As with windows, a tab item can have an initial first responder. This is
the view that will become first responder when the tab is activated. The initial first responder is
accessed with the -setInitialFirstResponder: and -initialFirstResponder
methods.

NSTabView Delegates

Tab views can havedelegates. The usual accessor methods for delegates, -setDelegate: and -
delegate are available. The tab view sends any of the following four methods to a delegate if it
implements them:
- (BOOL)tabView:(NSTabView *)tabView
shouldSelectTabViewItem:(NSTabViewItem *)tabViewItem;
- (void)tabView:(NSTabView *)tabView
willSelectTabViewItem:(NSTabViewItem *)tabViewItem;
- (void)tabView:(NSTabView *)tabView
didSelectTabViewItem:(NSTabViewItem *)tabViewItem;
- (void)tabViewDidChangeNumberOfTabViewItems:(NSTabView *)
TabView;

The -tabView: shouldSelectTabViewItem: method allows the delegate to prevent the

user from switching tabs. Because there's no way to disable a tab visually, it is not a good idea to
simply return NO without offering the user some feedback as to why the tab can't be changed. An
alert sheet to help the user along is recommended.

Delegates are usually used most often as part of the implementation of a wizard interface.
Delegates can do tricky things such as inserting extra tabs based on user input in other tabs.
Delegates often perform or coordinate input validation tasks as well.

Split Views

Split views lay out two or more views and draw divider bars between them. The user can drag the
divider bars to change the relative sizes of the subviews. Split views lay out the subviews either
horizontally or vertically, but never both ways at once. In other words, the layout is always in one
dimension. Any number of subviews is supported, even though the most common layout is to
have only two views, one atop the other.

The NSSplitView class implements split views in Cocoa. There are no instances on the
palettes in Interface Builder, but it is possible to create an instance by wrapping multiple selected
views in a split view. The menu item Layout, Make subviews of, Split View does this.

Split View Options in Interface Builder

Options for configuring a split view can be found in Interface Builder's NSSplitView
inspector. This inspector, shown in Figure 10.23, is displayed by using the Cmd-1 key equivalent
when an NSSplitView is selected.

Figure 10.23. Interface Builder's NSSplitView inspector.

There are two parameters that can be modified. The first is the orientation of the divider drawn
between the subviews of the split view, and the second is the way that the divider itself is
rendered.

If horizontal orientation is selected, the divider runs horizontally and the subviews are stacked
one atop the other (vertically). A vertical orientation has a vertical divider with the subviews
stacked side by side (horizontally). This can be confusing; it is easiest to remember that this
setting controls how the divider between subviews is drawn.

The type switches change the divider's rendering. The button on the left gives an opaque divider
with a bubbly Aqua look. Split views configured this way are known as pane splitters. If the
divider orientation is vertical, there is no difference between the two types, and there is also no
marking drawn on the divider.

NSSplitView Methods

The two parameters that can be altered in Interface Builder have their own accessor methods. The
-setVertical: and -isVertical methods work with the orientation. The -
setIsPaneSplitter: and -isPaneSplitter methods change the divider's rendering.
Pane splitters draw an opaque divider with a bubbly Aqua look. Split views that aren't pane
splitters draw a wider marking on the divider, and have a background that matches the window's
background pattern.
 NOTE

As of Mac OS X 10.1.4, the NSSplitView class reference says that the default
orientation of the split view is vertical in the description of the -isVertical
method. In the description of the -setIsVertical: method, it says that the
default orientation is horizontal. Clearly, both can't be right. The real default
orientation is actually horizontal, so the documentation for -isVertical is
incorrect. The documentation for the -setIsPaneSplitter: method is also in
error, claiming both settings are achieved by sending YES. To get a separator
without the bubbly Aqua look, a NO is what should actually be sent. These errors are
likely to be fixed eventually, of course.

There are no methods to move the dividers. Instead, the frames of the subviews should be
modified directly, and then the split view should be redisplayed. Care must be taken to be ensure
that the views are laid out properly and that enough room has been left for the divider(s). To make
this a little easier, the -dividerThickness method returns the size of the dividers. The -
isSubviewCollapsed: method returns YES if the divider is placed such that no part of a
subview is actually visible. In this case, the split view retains the subview, but doesn't display it
until the divider is moved to expose it.

NSSplitView Delegates

Split views support delegates and implement the standard delegate accessor methods -
setDelegate: and -delegate. There is a very rich collection of delegate methods
available, as well as a pair of notifications. Delegates are allowed to lay out all the subviews at
once when a split view is about to be rendered for the first time. They can also place maximum
and minimum size constraints on the subviews. Delegates can also say whether a subview can be
collapsed.

The NSSplitViewWillResizeSubviewsNotification notification is sent before

resizing a subview. After resizing subviews, the
NSSplitViewDidResizeSubviewsNotification notification is sent.

A full description of each delegate method is beyond the scope of this book. Refer to the
NSSplitView class documentation at /Developer/Documentation/Cocoa/
Reference/ApplicationKit/ObjC_classic/ Classes/NSSplitView.html for
full descriptions of each of the available methods.
Book: Cocoa® Programming
Section: Chapter 10. Views and Controls

Compound Controls

Compound controls use multiple cells to produce a more complex interface object. They
often contain glue code that makes the cells work together in a specific way. Most of these
controls still have their own specialized cell subclass. Much of the complexity of managing
multiple elements falls to the associated cell class instead of the control object.

Steppers look like a pair of very small buttons with up and down arrows on them. The most
complex and most flexible of the compound controls is the NSMatrix, a class for laying
out an arbitrary number of cells of arbitrary classes in a uniform way. Forms look like a
pair of text fields, one an uneditable label, and the other an editable text field. Forms are
usually used in matrices. Pop-up buttons are special buttons that can open a menu when
clicked. They can also be configured as pull-down menus.

Steppers

A stepper is a small control that draws an up and a down arrow. Clicking one of the arrows
will increment or decrement its value. Clicking and holding down an arrow will make some
steppers autorepeat. Steppers are normally used in conjunction with another control,
usually a text field. They send their actions whenever the user changes their value.

Steppers are implemented by the NSStepper control subclass and the NSStepperCell
cell subclass. An NSStepper instance can be found on the Cocoa-Other palette shown
earlier in this chapter in Figure 10.7. The stepper is under the vertical sliders.

Stepper Options in Interface Builder

Options for configuring a stepper can be found in Interface Builder's NSStepper

inspector. This inspector, shown in Figure 10.24, is displayed by using the Cmd-1 key
equivalent when an NSStepper or NSStepperCell is selected.

Figure 10.24. Interface Builder's NSStepper inspector.

The settings for steppers are straightforward. The value is the current value of the stepper.
Similar to sliders, a minimum and maximum value is provided. The increment amount
determines how much the stepper's value changes when an arrow is clicked. If the down
arrow is clicked, the increment value is used as a decrement value.

The Value Wraps check box determines if the stepper should start over from the beginning
of its range if the user attempts to increment or decrement beyond its minimum or
maximum values. If this check box is off, the stepper stops changing its value when it hits
the boundary of its range.

The Autorepeats check box turns autorepeat behavior on or off. If on, the stepper continues
to increment or decrement periodically while the mouse is held down on one of the arrows.
The stepper's action is resent for each autorepeat.

Similar to other controls, steppers support an integer tag that can be used to identify them
uniquely in program code.

Configuring a Stepper

Like every control, both NSStepper and NSStepperCell respond to the standard
accessor methods such as -intValue for their value. The standard -setTag: and -
tag also work as expected.
Both classes also respond to a series of new accessor methods. The minimum value's
accessors are -setMinValue: and -minValue. The maximum value's accessors are -
setMaxValue: and -maxValue. The accessors for the increment amount are -
setIncrement: and -increment. All six of these methods use double values.

The accessors for the boolean settings all take BOOL arguments. The -
setValueWraps: and -valueWraps methods control whether the value wraps
around. Autorepeat is manipulated and inspected with -setAutorepeat: and -
autorepeat, respectively.

NSMatrix Class

The NSMatrix class can take a collection of cells and lay them out uniformly in one or
two dimensions. It is commonly used with text fields and forms. When filled with button
cells, a matrix can make them work in concert to behave like radio buttons. (Only one
button can be on at a time, like the station selector buttons on an old-time car radio.)
Selection lists, such as those used to select multiple files, are also possible. Matrices can
contain cells of many different types, but place the restriction that all cells must be the
same size.

To create a matrix, simply Option-drag one of the resize handles of a standard control. This
works with any control that has an associated cell subclass. For example, color wells,
described in Chapter 17, don't have an associated cell class, so they can't be turned into
matrices. The Cocoa-Views palette, shown earlier in this chapter in Figures 10.3 and 10.9,
contains two preconfigured NSMatrix instances, one populated with basic NSFormCell
objects, and the other with NSButtonCell objects set up as radio buttons.

NSMatrix is a huge, complex class, so a full discussion of all its features is beyond the
scope of this book. Be sure to refer to the Cocoa documentation when attempting to do
complex manipulation of matrices. This discussion of NSMatrix leaves out several of the
more advanced methods that are available.

Event Handling with NSMatrix Objects

Because a matrix has many cells, it tends to respond differently to user events when
compared to a standard control. Matrices can handle drags between cells in special ways.
Matrices support standard target/action, and they extend it by adding the idea of a double-
click action.

When a user clicks inside a matrix, and then drags the mouse, the matrix has four ways to
interpret the action. A matrix's mode determines which interpretation is used. The four
matrix modes are described Table 10.3.
 Table 10.3. Matrix Modes

Mode Constant Description

Track NSTrackModeMatrix Acts as if the cells were working

individually. The cell where the mouse-
down event occurred tracks the mouse until
mouse-up.

Highlight NSHighlightModeMatrix Which cell tracks the mouse changes as the

mouse moves over other cells. No cells
remain selected after mouse-up.

Radio NSRadioModeMatrix Only one cell can ever be on at a time.

Selecting a cell deselects all others.

List NSListModeMatrix Drag to select multiple cells. Shift and other

selection modifiers work as expected. This
works like selecting multiple files in the
open and save panel's browsers.

Matrices extend target/action so that each cell can have its own target and action or a single
target and action can be used for the whole matrix. NSMatrix offers a default target and
action for any cells that don't have them set. It is important to be careful when making
connections in Interface Builder. When connecting from a matrix, be sure the connection is
coming from the right place, a single cell or the whole matrix. Any connections made for
individual cells will override the connections made for the whole matrix. When connecting
to a matrix, be careful to connect to the whole matrix or individual cells. It is easy to
accidentally connect to a cell when a connection to the whole matrix is desired.

The NSMatrix class also adds the idea of a double-click action. This is an action sent
when a double-click occurs inside the matrix. This is always sent to the matrix's target,
never the target of an individual cell. This action cannot be set in the Interface Builder
connection inspector. It can only be set programmatically, using the -
setDoubleAction: method. The double action is returned by the -doubleAction
method. The -sendDoubleAction method sends the action as if the user had double-
clicked. One important consideration when using double-click actions is that the single-
click action is always sent before the double-click action.

NOTE
 Sometimes developers want to have a double-click action for a standard
control. Controls don't support this, but turning a control into an NSMatrix
with a single cell produces a control that looks just like a single control, but
also implements a double-click action. This can save the trouble of
subclassing.

Matrix Options in Interface Builder

Options for configuring a matrix can be found in Interface Builder's NSMatrix inspector.
This inspector, shown in Figure 10.25, is displayed by using the Cmd-1 key equivalent
when an NSMatrix is selected.

Figure 10.25. Interface Builder's NSMatrix inspector.

The color well and switch control the background of a matrix. The background color only
applies to the area between cells (intercell spacing) and any cells that don't draw their
backgrounds.

The Mode radio buttons set the matrix's selection mode. Refer to Table 10.3 for a
description of the various modes. If the mode is set to Radio, the Allows empty selection
check box is available. Radio mode only allows one cell to be selected. The check box tells
the matrix whether one cell must be selected at all times.

When a matrix is created in Interface Builder, the first cell created is considered to be the
prototype cell. Newly created matrix cells are created as copies (clones) of the prototype.
This makes it easier to add new cells because they don't have to be reconfigured one at a
time. It is important to configure a control completely before Option-dragging its handles
to create a matrix. After the matrix is created, there is no way to edit the prototype.

NOTE

Older versions of Interface Builder, such as the version for NeXTSTEP, had a
button to copy a selected cell in the matrix so that it would be used as the
prototype cell. This functionality has sadly been lost, so now care must be
taken to remember to preconfigure a control to its final settings before turning
it into a matrix.

The Cells options refer to basic NSMatrix behaviors. Autosizing refers to how the matrix
handles being resized. If autosizing is off, the cells will not change their frames as the
matrix is resized. If autosizing is on, the cells will resize proportionally across the whole
matrix.

The Selection by rect switch enables the user to drag out a rectangle to select multiple cells.
This is especially useful for two-dimensional matrices in list mode. If this option is off, the
user must move the mouse over every single cell they want to select.

The Spacing control determines how much space is inserted between the cells of the
matrix. This can also be adjusted graphically by Cmd-dragging one of the resize handles.
The Row/Col fields set the number of cells in the matrix. This can also be adjusted by
Option-dragging a resize handle.

Methods for Configuring an NSMatrix

All the options available in Interface Builder can be adjusted programmatically through
accessor methods.

To manipulate the background color, use the -setBackgroundColor:, -

backgroundColor, -setDrawsBackground:, and -drawsBackground
methods. The matrix's mode is accessed with the -setMode: and -mode methods. The
four constants shown in Table 10.3 should be used to set the mode. If radio mode is
selected, the -setAllowsEmptySelection: and -allowsEmptySelection
accessors can be used.

Cell size is accessed for all cells with the -setCellSize: and -cellSize methods.
The intercell spacing is adjusted with -setIntercellSpacing: and -
intercellSpacing. The parameters and return values for these methods are NSSize
structures.

The prototype cell is set using the -setPrototype: and -prototype methods.
Individual cells can be looked up with the -cellWithTag: or -cellAtRow:
column: methods. To get all the cells in the matrix, use the -cells method. It returns
an NSArray. To add and remove cells, don't try to modify the immutable array. Instead,
use the methods described in the "Methods for Manipulating Cells" section later in this
chapter.

Autosize behavior is accessed by the -setAutosizesCells: and -

autosizesCells methods. Selection by rectangle is controlled by -
setSelectionByRect: and -isSelectionByRect.

Methods for Managing Cell Selection

To select a specific cell in the matrix, use either the -selectCellWithTag: or -

selectCell: method. It is also possible to select a cell based on location in the matrix
using the -selectCellAtRow:column: method. To select all cells, use the standard -
selectAll: action method (the same as used by text fields for selecting all their text).

Cells can be deselected with -deselectSelectedCell or -deselectAllCells.

Despite the name, the -deselectSelectedCell method will actually deselect all
selected cells if a multiple selection is active. The only real difference between these two
methods is that -deselectSelectedCell does not redisplay the matrix. Neither
method will deselect a cell if the matrix is in radio mode and disallows empty selections.

There are two ways to determine which cells are selected. If the mode is radio mode, where
only one cell can be selected at a time, it is safe to use the -selectedTag and -
selectedCell methods inherited from NSControl. If multiple selections are possible,
the -selectedCells method is best because it returns an array of all the selected cells.

Methods for Manipulating Cells

The -numberOfRows and -numberOfColumns methods return the current number of

rows and columns in a matrix. There are several methods that can be used to add or remove
columns or rows.

Add a column with -addColumn or -insertColumn:. The -addColumn method

adds the column at the right side of the matrix. The -insertColumn: method inserts a
new column before the specified column. A column can be removed with -
removeColumn:.

Add a row with -addRow or -insertRow:. The -addRow method adds the row at the
bottom of the matrix. A row can be removed with -removeRow:.

NOTE

Notice that the -insertColumn:, -removeColumn:, -insertRow:,

and -removeRow: method names are one of the very few inconsistencies in
the Cocoa framework. Based on how methods with a similar function are
named elsewhere in Cocoa, the methods really should have been given names
such as -insertColumnAtIndex:, and so on. Be careful to use the right
names when writing your code! There is no compiler error if the id type is
used instead of static typing with (NSMatrix *). Programs using the
wrong names will malfunction and report a runtime error.

Forms

Forms are controls that look like multiple text fields, each with a label. They provide a
convenient means of treating multiple data entry fields as a single unit.

Forms are implemented by the NSForm and NSFormCell classes. Unlike other controls,
the NSForm class does not have a one-to-one mapping of control to cell. NSForm is a
subclass of NSMatrix, so it can handle many NSFormCell instances at once.

Interface Builder has an NSForm on the Cocoa-Views palette, as shown earlier in Figure
10.9. After dragging a form to a window, it can be Option-dragged so that it has the needed
number of form cells. Although they descend from matrices, forms are constrained so that
they can have only one column.

Form Options in Interface Builder

Options for configuring a form can be found in Interface Builder's NSForm inspector. This
inspector, as shown in Figure 10.26, is displayed by using the Cmd-1 key equivalent when
an NSForm is selected.

Figure 10.26. Interface Builder's NSForm inspector.

The options for forms and form cells are a limited combination of the options for text fields
and matrices. The background color control works like the one for NSMatrix objects.
The alignment controls work as expected. Alignment can be set independently for the title,
or label, and the editable part of the form cell.

The various options in the Options box work like their counterparts in the text field and
matrix inspectors. The only switch that is a little different is the Scrollable switch. If it is
turned on, the editable part of the form behaves similar to a text field that has been set to
Scrollable. If it is turned off, however, the text will not wrap; it will simply be cut off.
Usually, the scrollable behavior is preferred.

NSForm Methods

The NSForm class augments the NSControl and NSMatrix classes with a few new
methods. Most manipulation of forms is done using methods from the superclasses. A few
exceptions, however, are worth considering.

The alignment and font for all the cells can be set for both the title and the editable text.
The methods to make these changes across the whole form are -
setTitleAlignment:, -setTextAlignment:, -setTitleFont:, and -
setTextFont:. The alignment methods take the same constants as text fields and other
controls. They are NSLeftTextAlignment, NSRightTextAlignment,
NSCenterTextAlignment, and NSNaturalTextAlignment. The
NSJustifiedTextAlignment constant is meaningless for forms. The font methods
work with NSFont instances.

The sizes and spacing of the cells in a form can be set using the -setEntryWidth: and
-setInterlineSpacing: methods. The -setEntryWidth: method affects the
entire width of all the cells. The -setInterlineSpacing: method is preferred over
the NSMatrix -setIntercellSpacing: method for setting the spacing between
cells.

Cells can be added with the -addEntry: and -insertEntry:atIndex: methods.

Both require that a title, in the form of an NSString, be provided. The -addEntry:
method adds the new cell at the bottom of the form. A cell can be removed with the -
removeEntryAtIndex: method.

To find a particular cell, the -cellAtIndex: and -indexOfCellWithTag:

methods are used. The selected cell's index is obtained with -indexOfSelectedItem.
A particular cell can be activated and have all its text selected at the same time by calling
the -selectTextAtIndex: method.

NSFormCell Methods

Working with an NSFormCell class is much like working with an NSTextField. The
main difference is the addition of the title (label). All the normal NSCell methods for
setting fonts, values, and so on, work on the editable portion of the field. To manipulate the
title, a new set of methods is provided.

Change the title with -setTitle: if an NSString is available. The -title method
returns the current title. The -setTitleFont:, -titleFont, -
setTitleAlignment:, and -titleAlignment methods can access the title's font
and alignment attributes. To work with the title and the attributes all at once, use an
NSAttributedString with -setAttributedTitle: and -attributedTitle.

The title's width can be accessed with the -setTitleWidth: and -titleWidth
methods. This width is what the cell uses to decide how to split itself between the title and
editable portion.

Pop-Up Buttons and Pull-Down Lists

Pop-up buttons are a special kind of button that, when clicked, open a menu of options.
There are two types of pop-up button in Cocoa. The first, a basic pop up, performs a
function much like a set of radio buttons. It offers a list of choices, only one of which can
be selected at a time. When the menu is not open, the button's title displays the title of the
selected menu item. Radio buttons are preferred for this function when they fit in the
interface. If space is cramped or there are more than ten options, a pop up is a good
alternative.

A pull-down menu is different. The title on the button never changes. Selecting an item in a
pull-down menu doesn't cause the item to be selected as it would in a pop up. Instead, it
simply triggers an action to be sent. Pull downs are good for implementing verbs in the
user interface. Opening a pull down offers users a series of actions that they can perform.

Pop-up buttons and pull-down lists are both implemented by the NSPopUpButton and
NSPopUpButtonCell classes. Changing configuration parameters alters the pop up or
pull down behavior of an instance.

Interface Builder offers an NSPopUpButton instance preconfigured as a basic pop up

button on the Cocoa-Other palette. Figure 10.7 shows this palette. (There are no instances
preconfigured as pull down menus.) The NSPopUpButton instance is found at the upper
center of the palette. The text Item1 appears on the button. The preconfigured pop up has
three items in it, named iItem1, Item2, and Item3. Double-clicking the button opens the
button's menu for editing. It can be edited like any other menu. Refer to Chapter 16,
"Menus," for information about manipulating menus.

Pop-Up Button Options in Interface Builder

Options for configuring a pop up button can be found in Interface Builder's

NSPopUpButton inspector. This inspector, shown in Figure 10.27, is displayed by using
the Cmd-1 key equivalent when an NSPopUpButton is selected. The individual items
inside the pop-up button's menu are NSMenu items. They are discussed in Chapter 16.

Figure 10.27. Interface Builder's NSPopUpButton inspector.

The Type control at the top of the inspector is used to change the pop-up button between
basic pop-up and pull-down behaviors. The PullDown Options area only applies if the
PullDown option has been chosen. The other options, Enabled, Small, and Tag all work the
same as they do for other controls.

The pull-down options primarily affect the visual aspects of the pull down. The title and
icon are shown on the pull down itself. The style and arrow direction determine rendering
details of the pull down. The available styles are Rounded, Square, and Shadowless Square.
The rounded type can only have a downward pointing arrow. The two square styles can
have their arrow point either right or down. When the menu appears onscreen it appears
below or to the right of the NSPopUpButton as indicated by the arrow. Figure 10.28
shows how the various different pop-up and pull-down list styles are rendered.

Figure 10.28. Different styles of NSPopUpButton.

NSPopUpButton Methods

The main behavior of a pop-up button is controlled with the -setPullsDown: and -
pullsDown accessors. Set it to YES for a pull down menu and NO for a pop up.

The various items inside the pop-up button are menu items, and part of a menu object. The
menu object is accessed with the -setMenu: and -menu methods. Chapter 16 explains
these objects and shows how to manipulate them from within program code. The
DynamicMenu example in Chapter 16 shows programmatic manipulation of the menu
inside of a pop-up button.

NOTE

The -setMenu: and -menu accessors exist for all control classes and
normally control contextual menus, as explained in Chapter 16. In the case of
pop-up buttons, no contextual menu is possible or available because the
control itself opens its own menu. Dynamically adding and removing items
from the pop up's menu would make a contextual menu pointless anyway
because the menu that pops up is effectively a contextual menu as it is.

Pop-up buttons also implement several convenience methods for manipulating the pop-up
menu. Refer to the class reference at /Developer/Documentation/Cocoa/
Reference/ApplicationKit/ObjC_classic/Classes/NSPopUpButton.
html for more information about these methods.

Three methods exist for dealing with a pop-up button's current selection. These methods
really only make sense when the button is in pop-up mode. The methods are -
selectItem:, -selectItemAtIndex:, and -selectItemWithTitle:. Which
method to use depends on whether it is more convenient to set a selection based on
NSMenuItem object, int index, or NSString title, respectively.

The current selection is determined by -selectedItem or -

titleOfSelectedItem. Surprisingly, there is no -indexOfSelectedItem
method. That's easy enough to fix with the following NSPopUpButton category, though:

@interface NSPopUpButton(MyIndexOfSelectedItemCategory)
- (int)indexOfSelectedItem;
@end
@implementation NSPopUpButton(MyIndexOfSelectedItemCategory)
- (int)indexOfSelectedItem
{
return [self indexOfItem:[self selectedItem]];
}
@end

NSPopUpButtonCell Methods

The NSPopUpButtonCell class is actually a subclass of the NSMenuItemCell class.

It is the object that actually owns the menu associated with a pop-up button, so most of the
NSPopUpButton methods work with this cell class as well.

There is one pair of accessors implemented by NSPopUpButtonCell that isn't available

elsewhere. To change the direction an arrow points on a square pull-down menu, use the -
setArrowPosition: and -arrowPosition methods. Use one of the
NSPopUpNoArrow, NSPopUpArrowAtCenter, or NSPopUpArrowAtBottom
constants. It isn't very clear how these constants correspond to the settings in Interface
Builder. The NSPopUpArrowAtCenter constant gives a right-pointing arrow, whereas
NSPopUpArrowAtBottom is a down pointing arrow. The NSPopUpNoArrow constant
is not an option in Interface Builder.
Book: Cocoa® Programming
Section: Chapter 10. Views and Controls

Summary

Cocoa offers a wide variety of user interface controls. All the standard controls that you
would expect to use, such as buttons, sliders, and text fields are present. Also, several view
classes can be used to help organize the controls in a window. Boxes, scrolling views, tab
views, and split views all add different ways to lay out a user interface.

As alluded to in the discussions of text fields in this chapter, handling text is a very
complex function. Cocoa offers a rich set of objects for manipulating text. The next chapter
discusses Cocoa's text-handling features in depth.

This chapter hasn't covered every view and control class Cocoa has to offer. Several more
controls are available that are very complex. Chapter 18, "Advanced Views and Controls"
discusses these additional NSView subclasses.
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 11. The Cocoa Text System

IN THIS CHAPTER

● Using the High-Level Text Classes

● The Text System Architecture
● Managing Fonts
● Text Input

Cocoa provides powerful text presentation and input capabilities that are not matched on
any other platform. The classes that are used to store and present text are complex and
include many hooks that provide flexibility and enable customization. This chapter begins
with several examples that show how to use the basic high-level features of the text system.
The examples demonstrate common tasks and use features that are sufficient for many
applications. This chapter then delves into the architecture of the text systems and
identifies the many classes that interact to implement high-level features and provide low-
level flexibility.

Cocoa's font support is an essential and powerful feature of the text system. This chapter
explains the classes used to represent and manage fonts. Interaction with the user and font
selection with Cocoa's built-in Font panel are explained. An overview of the sometimes
complex relationship between fonts and Unicode character sets is provided.

Finally, this chapter explains Cocoa's text-input system. Cocoa provides classes that assist
with user input validation. Hooks are provided to enable programmatic restriction of user
input. The interaction with the operating system and features to support bidirectional text
input and Eastern language input are explained. Apple's overview documentation for the
text system is available at http://developer.apple.com/techpubs/macosx/Cocoa/
TasksAndConcepts/ProgrammingTopics/TextArchitecture/index.html.
Book: Cocoa® Programming
Section: Chapter 11. The Cocoa Text System

Using the High-Level Text Classes

Cocoa's text system is extremely complex. The complexity is needed to support state-of-the-art features and a high
degree of customizability. However, it is possible to use the text system without exposing the underlying
complexity. High-level features common to most applications are easily accessed. The details and complexity are
only encountered when using advanced or specialized features.

The easiest way to include formatted text display and input in a Cocoa application is to drag a text object from the
Interface Builder Cocoa-Data palette. The NSTextView object on the Interface Builder palette is actually an
instance of the NSTextView class embedded as the document view of a scroll view. Scroll views, the
NSScrollView class, and document views are all explained in the "Scroll Views" section of Chapter 10, "Views
and Controls."

The combination of the NSTextView instance and the scroll view provide sophisticated text features including
display of arbitrary amounts of formatted text, rulers, undo and redo, multiple text justification options, multiple
text alignment options, kerning, ligatures, underlining, spell checking, embedded graphics, copy and paste, drag and
drop, and more. No programming is needed to use these features.

The Cocoa text classes are able to read, display, and write Rich Text Format (RTF) data. Apple provides an
additional format called RTFD that extends RTF to store text and embedded graphics in a directory with multiple
files instead of packing all the data in a single file. The text classes provide limited support for HyperText Markup
Language (HTML) formatted text display.

If a text object dragged from the Interface Builder palette is configured via Interface Builder's attributes inspector to
enable editing, users can edit the NSTextView directly. Even if the text object is not editable, it can be configured
to be selectable. If so, users can select the noneditable text for use with copy and paste, searching, or services.
Services are described in the "Services" section of Chapter 19, "Using Pasteboards." Text in Cocoa applications
should usually be selectable even if it is not editable. Even the text of labels in the user interface can benefit from
being selectable. If such text is selectable, users can select the words in the labels to search for them in online
documentation or use a Service to define words that might be unfamiliar.

NOTE

Services provide a mechanism for all Cocoa applications to benefit from features such as dictionary
lookup, email integration, automatic file format conversion, and text formatting. Each Cocoa
application is able to use Services provided by other Cocoa applications. Services are described in the
"Services" section of Chapter 19, "Using Pasteboards."

Setting the Text to Display

Text objects can be programmatically modified. One of the most common tasks is to programmatically set the text
to be displayed by an instance of NSTextView. The easiest way to do that is to use the -setString: method.
NSTextView is a subclass of NSText, which is in turn a subclass of NSView. The -setString: method is
implemented by NSText and is, therefore, available for use with instances of NSTextView. As its name implies,
the -setString: method accepts an NSString argument and replaces the entire content of the receiving text
view with the string. NSText's -string method is used to obtain the entire content of the text object.

NSString objects do not normally contain any formatting information. When text is set via -setText:, the new
text is displayed with the formatting that was previously applied to the first character of the text that was replaced.

To change the formatting of the text, use NSText's -setBackgroundColor:, -setFont:, -

setAlignment:, and -setTextColor: methods. Formatting attributes can be applied to all or part of the
text. NSText also provides -backgroundColor, -font, -alignment, and -textColor methods for
retrieving the attributes.

Many of NSText's methods such as -changeFont:, -alignCenter:, -alignLeft:, -alignRight:, -

superscript:, -subscript:, -unscript:, and -underline: apply formatting to the currently selected
range of text. The selected range of text can be set with the -setSelectedRange: method and obtained with
the -selectedRange method. Ranges are stored in NSRange structures. NSRange is explained in the
"NSRange" section of Chapter 7, "Foundation Framework Overview."

Appending, Inserting, and Replacing Text

There are several ways to append text to the existing content of a text object. The simplest, but least efficient, way
is to use code such as the following:

// Append "Text to append" to a text object called aTextView

[aTextView setString:[[aTextView string]
stringByAppendingString:@"Text to append"]];

NSText provides the -replaceCharactersInRange:withString:, -

replaceCharactersInRange:withRTF:, and -replaceCharactersInRange:withRTFD:
methods for replacing arbitrary ranges of text. The first argument to each of the methods is an NSRange structure.
The second argument to -replaceCharactersInRange:withString: is an NSString instance
containing the new text. The -replaceCharactersInRange:withRTF:, and -
replaceCharactersInRange:withRTFD: methods accept a second argument that is an NSData instance
containing RTF data or RTFD data, respectively.

To append text to an NSTextView instance, use code similar to the following:

// Append "Text to append" to a text object called aTextView

[aTextView replaceCharactersInRange:NSMakeRange(
[[aTextView string] length], 0) withString:@"Text to append"]];

This code replaces zero characters just past the end of the existing text with the specified string.

NOTE

To automatically scroll the newly appended text so that it is visible to the user, use NSText's -
scrollRangeToVisible: method and pass an NSRange containing the appended text as the
argument.

To insert text at a specific location, use code such as the following:

// Insert "Text to insert" at insertLocation in a text object called

aTextView
[aTextView replaceCharactersInRange:NSMakeRange(
insertLocation, 0) withString:@"Text to append"]];
Finally, to replace text, use one of the -replaceCharactersInRange: methods and specify a range with a
length greater than zero to replace.

Programmatically Ending Editing

When an editable Cocoa text object becomes the first responder, a standard insertion cursor is displayed, and the
user can begin entering text into the text object. When another object becomes the first responder, any current
editing in the text object that is no longer the first responder is ended. Editing needs to be ended to trigger delegate
messages that inform the application that editing is complete and application logic can be applied to the new input.
Controlling user input and delegate messages are explained in the "Using Delegate Methods" section of this chapter.

Many applications need to programmatically end editing to trigger the delegate messages and other logic. For
example, if a text object is inside a tab view and the user selects a different tab, the editing might not be ended until
the user selects another text object and makes it the first responder. However, after changing the visible tab, the user
can no longer see the text object that is being edited. Therefore, he might quit the application thinking that the edits
made have been accepted and saved by the application when in fact the application is unaware of the changes
because the editing was not ended.

The following code is recommended to programmatically end all editing within a window:

// gracefully end all editing in a window named aWindow

if([aWindow makeFirstResponder:aWindow])
{
// All editing is now ended and delegate messages sent etc.
}
else
{
// For some reason the text object being edited will not resign
// first responder status so force an end to editing anyway
[aWindow endEditingFor:nil];
}

This code gives the Cocoa frameworks maximum opportunity to end the editing gracefully. It works for ordinary
text views as well as the window's field editor. The field editor is a shared text object used to handle input in text
fields and other controls and is explained in "The Field Editor" section of Chapter 10.
Book: Cocoa® Programming
Section: Chapter 11. The Cocoa Text System

The Text System Architecture

Many classes are used to implement the complete text system. The classes are organized using the Model-View-
Controller (MVC) design introduced in the "Model-View-Controller" section of Chapter 6, "Cocoa Design Patterns."
The text to be displayed and the attributes that affect that display are stored in the model. The visual representation of
text and handing user input are the responsibility of the view layer. The logic that links the model and view is
implemented in the controller layer. Figure 11.1 shows the classes used by the text system, and their role in the
Model-View-Controller design:

Figure 11.1. Many classes interact to implement Cocoa's text system.

This Model-View-Controller design reduces dependencies between objects in different layers and makes it easier to
modify individual components without having to change the entire system. The MVC design also reduces the amount
of information needed to accomplish common tasks. It is possible to manipulate text in many ways using only the
NSTextView class.

The principal classes in the text system are NSTextStorage, NSLayoutManager, NSTextContainer,
NSTextView. Only NSTextContainer is intended to be subclassed. The behavior of the other classes should be
specialized by using delegates and notifications and only subclassed as a last resort. The advantages of using
delegates and notifications are explained in the "Delegates" section of Chapter 8, "The Application Kit Framework
Overview."

Most applications that customize the text system work with either the Model layer or the View layer. Complex text
can be created and processed entirely within the Model layer and displayed automatically by the View layer. In some
cases, changes to the way text is displayed or edited by users must be made by an application. Those changes take
place entirely in the View layer. There is seldom any need to interact directly with the Controller layer in Cocoa's text
system, and there are not many modifications that can be made to the Controller layer without disrupting the View
and Model layers.

Apple provides the following document to explain how to assemble the Model, View, and Controller parts of the text
system without using the preconfigured object in Interface Builder at http://developer.apple.com/techpubs/macosx/
Cocoa/TasksAndConcepts/ProgrammingTopics/TextArchitecture/Tasks/AssembleSysByHand.html.

The Model Layer: Text Storage and Attributed Strings

The Model layer of the text system can be used independently. For example, using only the Model layer, it is possible
to search for text, specify formatting, load and save text, and apply application logic to the text. The Model layer can
be used in nongraphical applications to perform text processing without the overhead of laying out and drawing text.

The primary class used to store text in the Model layer is NSTextStorage. NSTextStorage is a subclass of
NSMutableAttributedString, which is in turn a subclass of NSAttributedString. Attributed strings
store Unicode character strings as well as formatting commands that are applied to the strings when they are drawn.
Mutable attributed strings can be modified after they are created. The NSTextStorage class extends the
NSMutableAttributedString class to provide notifications when the attributes or strings are changed.

The NSAttributedString and NSMutableAttributedString classes are implemented in the Foundation

framework so that even nongraphical applications can work with them. Applications can define custom attributes as
needed. The Application Kit Framework extends the attributed string classes with categories to draw the strings and
provide a standard set of attribute definitions such as font face, point size, color, paragraph style, tab stops, and more.

NOTE

Font dimensions are measured in Postscript Points (pts.), which equal 1/72 of an inch. Points are the
standard unit of measurement in the printing industry. Points are also the standard unit of measurement
for all graphical operations in Quartz.

Table 11.1 lists the attributes that are defined by the Application Kit framework. Attribute values are normally stored
in NSDictionary instances using the attribute names as the keys for retrieving the values.

Table 11.1. Application Kit-Defined Text Attributes

Attribute Names Attribute Type Default Value

NSAttachmentAttributeName NSTextAttachment none

NSBackgroundColorAttributeName NSColor none

NSBaselineOffsetAttributeName NSNumber float 0.0

NSFontAttributeName NSFont Helvetica 12 pts.

NSForegroundColorAttributeName NSColor black

NSKernAttributeName NSNumber float 0.0

NSLigatureAttributeName NSNumber int 1

NSLinkAttributeName id none

NSParagraphStyleAttributeName NSParagraphStyle value returned by

NSParagraphStyle's
+defaultParagraphStyle method

NSSuperscriptAttributeName NSNumber int 0

NSUnderlineStyleAttributeName NSNumber int 0 (no underline)

Attachments such as images and files are stored in attributed strings by using a special character,
NSAttachmentCharacter, within the string to identify the location of the attachment. The attributes applied to
the NSAttachmentCharacter must include NSAttachmentAttributeName with an
NSTextAttachment instance as the value. The NSTextAttachment instance stores the data of the attachment
itself or information sufficient to load the data. The NSTextAttachment class is described at http://developer.
apple.com/techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSTextAttachment.html, and in
the documentation that comes with Apple's developer tools.

The NSParagraphStyleAttributeName attribute uses values that are NSParagraphStyle instances that
define how strings are aligned when displayed. NSParagraphStyle instances also define tab stops and word
wrapping. The NSParagraphStyle class is documented at http://developer.apple.com/techpubs/macosx/Cocoa/
Reference/ApplicationKit/ObjC_classic/Classes/NSParagraphStyle.html, and in the documentation that comes with
Apple's developer tools.

Initializing Attributed Strings

The Foundation framework implementation of NSAttributedString provides three methods to initialize

instances. The -initWithString: method accepts an NSString argument and returns an
NSAttributedString instance containing the string and default attributes. The -initWithString:
attributes: method accepts a string for the first argument and a dictionary containing attribute names and values
for the second argument. The returned NSAttributedString contains the string and attributes specified. Finally,
the -initWithAttributedString: returns an attributed string containing a string and attributes identical to
the ones specified in the NSAttributedString provided as an argument.

The Application Kit framework provides additional NSAttributedString methods to support initialization with
HTML, RTF, or RTFD format data, and data that is convertible to one of those formats using Services. The -
initWithHTML:documentAttributes:, - initWithRTF:documentAttributes:, -
initWithRTFD:documentAttributes:, and - initWithRTFDFileWrapper:
documentAttributes: methods each accept an NSData instance containing appropriately formatted data as
the first argument. The second argument is a pointer to a pointer to an NSDictionary instance. If the second
argument is not NULL, it is used to return by reference an NSDictionary instance containing the attributes defined
for the newly initialized attributed string. The dictionary returned must be retained if it is used outside the scope of
the call to one of the initializers. The complete set of attributes that can be stored in the dictionary returned by
reference in the documentAttributes: argument of one of these initializers is defined in Table 11.2.

Table 11.2. Keys and Values for documentAttributes: Arguments

Key Attribute Type Description

@"PaperSize" NSValue Contains an NSSize.

@"LeftMargin" NSNumber Contains a float value in pts.

@"RightMargin" NSNumber Contains a float value in pts.

@"BottomMargin" NSNumber Contains a float value in pts.

@"HyphenationFactor" NSNumber Contains a float value.

@"DocumentType" NSString Contains the value of one of the following constants:

NSPlainTextDocumentType,
NSRTFTextDocumentType,
NSRTFDTextDocumentType,
NSMacSimpleTextDocumentType,
NSHTMLTextDocumentType.

@"CharacterEncoding" NSNumber Contains an int specifying the NSStringEncoding used.

Present only in plain-text files.

@"ViewSize" to display in. NSValue Contains an NSSize representing the view size

@"ViewZoom" NSNumber Contains a float describing current zoom as a percentage.

@"ViewMode" NSNumber Contains an int. 1 indicates show page layout format

such as page boundaries and margins. 0
indicates not to show page layout.

@"CocoaRTFVersion" NSNumber Contains an int if created by Cocoa. Value of 100 indicates

Mac OS X, whereas lower values are earlier versions.
 @"Converted" NSNumber Contains an int. If the file was converted by a filter service, the
value will be 1 or greater. Absent or lower values indicate it was
not converted by a filter service.

An additional initializer, -initWithHTML:baseURL:documentAttributes:, is similar to -

initWithHTML:documentAttributes. It accepts an NSData instance containing the HTML data as the first
argument. The attributes dictionary is returned by reference in the last argument. The additional baseURL:
argument specifies a URL used to resolve relative URLs within the HTML data. The baseURL: argument must be
an instance of the NSURL class. The NSURL class is described in the "NSURL and NSURLHandle" section of
Chapter 23, "Networking."

NOTE

If the data passed to any of the Application Kit defined NSAttributedString initializers cannot be
interpreted, the initializers return nil.

Finally, the -initWithPath:documentAttributes: and -initWithURL:documentAttributes:

methods are used to initialize an attributed string with the contents of a file. These methods are not format specific. If
the file contains one of the supported types of data returned by NSAttributedString's
+textUnfilteredFileTypes class method, the contents are loaded directly. Otherwise, an attempt is made to
use Services to convert the data to a recognized format. The complete list of supported data types including the ones
that require Services is returned by the +textFileTypes method.

The -initWithPath:documentAttributes: method expects the first argument to be an NSString

containing a path. The first argument to -initWithURL:documentAttributes: must be a file location
specified by an NSURL instance. Both methods return the attributes dictionary for the loaded data by reference in the
second argument.

NOTE

The URL passed to -initWithURL:documentAttributes: must use the file:// URL

scheme. It is not possible to use the http:// scheme or other remote formats with this method. To
initialize an attributed string with remote data, use an NSURL instance to fetch the data from the remote
location via NSURL's -resourceDataUsingCache: method, and then use the data to initialize an
attributed string with -initWithHTML:baseURL:documentAttributes:.

NSAttributedString provides a convenience method to create an instance that contains an attributed string
representing an attachment. The +attributedStringWithAttachment: method returns an autoreleased
instance of NSAttributedString consisting of the NSAttachmentCharacter with attributes set to contain
the NSTextAttachment passed as the argument.

Using Attributed Strings

The length of an attributed string instance is returned as an integer by calling the method -length. An NSString
instance that contains the text portion of the NSAttributedString is returned by calling -string.

The -isEqualToAttributedString: method compares the receiver to the NSAttributedString passed

as the argument. To be considered equal, the string and the attributes of both attributed strings must correspond. This
method returns a Boolean value of YES if the strings are equal.

The -attributedSubstringFromRange: method returns an NSAttributedString instance that

contains the text and attachments within the range specified using an NSRange structure. If the NSRange argument
lies outside of the contents of the string-for example, beyond the end-this method raises an NSRangeException
exception.

The attributes that are attached to an attributed string are accessed by calling -attributesAtIndex:
effectiveRange:. This method expects an unsigned integer index for the first argument and returns an
NSDictionary containing all attributes that apply to the character at the specified index. The second argument is
an NSRange returned by reference that identifies the full range of characters to which the attributes in effect at the
index apply. If the effectiveRange: argument is NULL, the range is not returned. If the index is past the end of
the string, an NSRangeException is raised.

The -attribute:atIndex:effectiveRange: method is similar to -attributesAtIndex:

effectiveRange:, but it allows specification of a particular attribute. The attribute: argument is an
NSString instance containing an attribute name. If an attribute with the specified name is in effect at the specified
index, the value of the attribute is returned. If the effectiveRange: argument is not NULL, and the specified
attribute is in effect at the specified index, the range of characters to which the attribute applies is returned by
reference. If the specified attribute is not in effect at the specified index, and the effectiveRange: argument is
not NULL, the range that the attribute does not apply to is returned by reference.

The following example takes an NSAttributedString, finds any underlined text, and returns an NSString
containing a version of the string in HTML format with underline formatting preserved.

- (NSString *)convertUnderlineTextToHTML:(NSAttributedString *)
attributedString
// Returns a string containing HTML format text that preserves any underline
// formatting in attributedString but discards all other formatting
{
unsigned int length;
NSRange effectiveRange;
NSMutableString *resultString = [NSMutableString string];

length = [attributedString length];

effectiveRange = NSMakeRange(0, 0);

while (NSMaxRange(effectiveRange) < length)

{
id attrVal;
NSString *plainStr;

// get the effective range that has the same value for the underline
// attribute
attrVal = [attributedString attribute:NSUnderlineStyleAttributeName
atIndex:NSMaxRange(effectiveRange) effectiveRange:&effectiveRange];

if (nil != attrVal)
{
// this range is underlined so insert the HTML code for underline
[resultString appendString:@"<u>"];
}

// append the plain string to the result

plainStr = [[attributedString string] substringWithRange:effectiveRange];
 [resultString appendString:plainStr];

if (nil != attrVal)
{
// this range was underlined so insert the HTML code to end underline
[resultString appendString:@"</u>"];
}
}

return resultString;
}

Initially, the length of the attributed string is determined using the -length method, and the location of
effectiveRange is set to the start of the string. The while loop continues as long as effectiveRange is
within the attributed string.

The -attribute:atIndex:effectiveRange: method is called specifying the maximum position within

effectiveRange as the index argument. This causes the search to begin at index 0 the first time through the loop
and at the end of the previous search during each subsequent iteration. During each pass through the loop,
effectiveRange is updated to store the next contiguous range of characters with the same value for the
NSUnderlineStyleAttributeName. If the attributed string does have an
NSUnderlineStyleAttribute for the requested index, the value returned by -attribute:atIndex:
effectiveRange is nil, but effective range is still returned with the range of the string that does not have the
attribute.

A similar example using -attributesAtIndex:effectiveRange: can be constructed. Each contiguous

range of characters that have the same attributes is processed by the loop. The attributes can be analyzed inside the
loop to implement almost any format conversion.

Additional variants of the -attribute:atIndex:effectiveRange: method are available. Each provides a

slightly different way of searching for contiguous ranges of characters with similar formatting. Not all the methods
are described here, but enough information is provided to enable the straightforward usage of all the variations.

The -fontAttributesInRange: method returns attributes related to the appearance of an attributed string. The
returned NSDictionary contains any of the following attributes if they are in effect for the first character in the
specified range: NSBackgroundColorAttributeName, NSBaselineOffsetAttributeName,
NSFontAttributeName, NSForegroundColorAttributeName, NSKernAttributeName,
NSLigatureAttributeName, NSLinkAttributeName, NSSuperscriptAttributeName, and
NSUnderlineStyleAttributeName.

Similarly, the -rulerAttributesInRange: returns an NSDictionary containing the

NSParagraphStyleAttributeName for the first character in the specified range. Apple has indicated that in
the future there might be additional ruler-related attributes returned.

The method -containsAttachments returns a Boolean value of YES if the receiving attributed string instance
contains any attachments and NO otherwise.

Several methods are available to convert a requested range of an attributed string to RTF and RTFD formats. The
method -RTFFromRange:documentAttributes: returns an NSData instance with the appropriately
generated RTF for the NSRange passed as the first argument. The documentAttributes argument is optional.
If provided, it should be an NSDictionary with keys from Table 11.2, and their associated values. If the requested
range is outside of the receiving attributed string, an NSRangeException is raised. This method strips out any
attachments within the attributed string, but does not remove the NSAttachmentCharacter from the generated
RTF.
The method -RTFDFromRange:documentAttributes: is identical except that the returned NSData instance
contains a flattened RTFD representation of the attributed string, including any attachments.

-RTFDFileWrapperFromRange:documentAttributes: expects the same arguments, but returns the

RTFD contents as an NSFileWrapper instance, which represents the contents of an RTFD-bundled document.

Also included in the Application Kit extensions to NSAttributedString is support for finding linguistic
elements within an attributed string. The methods are -doubleClickAtIndex:, -lineBreakBeforeIndex:
withinRange:, -nextWordFromIndex:forward:. They are primarily used for determining ranges of text
affected by mouse clicks or user interaction with the keyboard.

The Application Kit framework adds NSAttributedString methods for drawing and calculating the graphical
size of the attributed strings when they are drawn. These methods are described in the "NSString Drawing Methods"
section of Chapter 14, "Custom Views and Graphics Part III."

Using Mutable Attributed Strings

The NSMutableAttributedString class extends the NSAttributedString class to enable modification

of the strings and attributes. As with the NSAttributedString class, the implementation of
NSMutableAttributedString is split across Cocoa's Foundation and the Application Kit frameworks.

There are methods to append, replace, and delete characters within the attributed string. -
appendAttributedString: appends the attributed string passed as the argument to the end of the receiver.
Similarly, an attributed string can be inserted at a specified location in an NSMutableString using the method -
insertAttributedString:atIndex:. If the index is not a valid position within the receiver, an
NSRangeException is raised.

The method -replaceCharactersInRange:withAttributedString: deletes the characters in the

specified NSRange and replaces them with the attributed string passed as the second argument. Similarly, -
replaceCharactersInRange:withString: replaces the characters within the specified NSRange with the
characters in the NSString that is passed as the second argument. If -replaceCharactersInRange:
withString: is used, the newly inserted characters have the attributes that were set for the location of the first
deleted character in the range. In both methods, if the NSRange is outside the bounds of the
NSMutableAttributedString, an NSRangeException is raised.

It is also possible to completely replace the contents of an NSMutableAttributedString using the method -
setAttributedString: passing an attributed string to use as the replaced contents.

The characters within a given range of an NSMutableAttributedString can be deleted by using the method -
deleteCharactersInRange:. If the NSRange passed as the argument is outside the bounds of the receiving
NSMutableAttributedString, an NSRangeException is raised.

Attributes can be modified for a range of text in an NSMutableAttributedString using the methods -
setAttributes:range:, -addAttribute:value:range:, -addAttributes:range:, and -
removeAttribute:range:. The method -setAttributes:range: replaces any attributes set on the
characters in the specified NSRange with those contained in the NSDictionary passed as the first argument. The
method -addAttributes:range: adds the attributes in the NSDictionary passed as the first argument to
the characters in the range. If an attribute already exists on the text, the value of that attribute is changed to the value
in the dictionary. A simpler method, -addAttribute:value:range:, does the same thing, but expects only a
single attribute identifier and value instead of an NSDictionary. Finally, attributes are removed from a range of
characters by the -removeAttribute:range: method. In all cases, if the range is outside of the receiving
string, an NSRangeException is raised.
NSMutableAttributedString's -mutableString method returns the receiver's string as an
NSMutableString instance.

The Application Kit adds methods to NSMutableAttributedString for dealing with font changes, attachment
handling, and fixing attributes that have changed because of editing. The method -applyFontTraits:range:
applies the font traits that are passed as a C bitwise mask in the first argument to the specified range. The mask
consists of one or more of the NSFontTraitMask values combined using the C logical OR operator.
NSFontTraitMask is described in the "Font Traits and Weights" section of this chapter.

A portion of a mutable attributed string can be given superscript or subscript traits by calling -
superscriptRange: or -subscriptRange:, respectively; passing the character range as an NSRange
argument. Any existing superscript or subscript traits can be removed from a range of characters by calling -
unscriptRange:.

The alignment of paragraphs within a range can be modified by calling -setAlignment:range:. The alignment
argument must have one of the following constant values: NSLeftTextAlignment,
NSRightTextAlignment, NSCenterTextAlignment, NSJustifiedTextAlignment, or
NSNaturalTextAlignment. NSNaturalTextAlignment uses the language-appropriate alignment for the
characters in the selected range. For example, Japanese or Arabic characters have different natural alignment than
common Western characters. Changes to the alignment only apply to paragraphs that begin within the specified range
of characters. If the range is outside of the receiving string, an NSRangeException is raised.

The method -readFromURL:options:documentAttributes: replaces the contents of the receiving

NSMutableAttributedString with the contents of the file at the NSURL passed as the first argument. The
second argument is an NSDictionary that specifies how the contents of the file are handled. For plain-text files,
the dictionary is consulted for the @"CharacterEncoding" key, which must have a corresponding NSNumber
value containing the NSStringEncoding constant that should be applied to the characters in the file.
NSStringEncoding is an enumerated type declared in NSString.h. NSStringEncoding values range from
1, which specifies NSASCIIStringEncoding, to 65536, which specifies
NSProprietaryStringEncoding. The available encoding constants are documented at http://developer.apple.
com/techpubs/macosx/Cocoa/Reference/Foundation/ObjC_classic/TypesAndConstants/FoundationTypesConstants.
html. The @"DefaultAttributes" key has an NSDictionary value that defines the attributes to be applied
to the characters loaded from the file. Table 11.1 lists the valid attribute keys and values. If the file being read from
the URL is an HTML file, a dictionary passed as the options: argument might contain the @"BaseURL" key,
which is consulted to resolve relative URLs within the file being read. The third argument to -readFromURL:
options:documentAttributes: is a pointer to a pointer to an NSDictionary. If the third argument is not
NULL, a dictionary that describes the document attributes of the file being read is returned by reference. Document
attribute keys and values are listed in Table 11.2. If the file identified by the URL is successfully read, -
readFromURL:options:documentAttributes: returns the Boolean value of YES. NO is returned
otherwise.

There are several methods to ensure that the attributes for a requested range are appropriate: -
fixAttributesInRange:, -fixAttachmentAttributeInRange:, -
fixFontAttributeInRange:, and -fixParagraphStyleAttributeInRange:. The -
fixAttachmentAttributeInRange: method removes any NSAttachmentAttributeName identifiers
that don't apply to NSAttachmentCharacter characters within the specified range of characters. The -
fixFontAttributeInRange: method ensures that the font settings on text within the range are correct. For
example, characters that lie within the Chinese Unicode character set but have a Western font attribute are corrected
to have an appropriate Chinese font attribute.

The method -fixParagraphStyleAttributeInRange: ensures that NSParagraphAttributes affect

only complete paragraphs. The method -fixAttributesInRange: invokes each of the other methods,
providing a single call to fix all the text within a range. Once again, ranges outside the bounds of the string cause an
NSRangeException to be raised.
The View and Controller classes in Cocoa's text system make changes to NSTextStorage instances automatically
as the result of user input. NSTextStorage is a subclass of NSMutableAttribtedString. A complex
system of notifications keeps the View and Control layers synchronized with changes in the text storage. When an
NSTextStorage instance is modified directly by program code, it's important to bracket the changes with calls to
NSMutableAttribtedString's -beginEditing and -endEditing methods. Doing so causes
NSTextStorage to coalesce notifications for changes that occur between -beginEditing and -endEditing
calls.

The classes in the View and Control layers of the text system need to perform time consuming layout and display
calculations each time they are notified of changes to the underlying NSTextStorage. The most efficient way to
modify an attributed string such as an NSTextStorage is to call -beginEditing, make as many changes as
needed, and then call -endEditing. The -beginEditing and -endEditing block prevents the other objects
in the text system from being notified until -endEditing is called.

The Control Layer: Text Layout and Containers

The visual representation of each character in an attributed string requires one or more glyphs. A glyph is a pictorial
representation of a character. Glyphs are managed by font and are described in more detail in the "Managing Fonts"
section of this chapter. The glyphs that are used to represent a character might depend on the context. Factors such as
the preceding and following glyphs, the position of a glyph on a line, and the orientation of a glyph all contribute to
the glyph that is ultimately displayed.

The NSLayoutManager class is responsible for selecting glyphs to represent the characters in attributed string
based on the attributes and context. The NSLayoutManager class must also position glyphs relative to each other
and the graphical area that contains the glyphs.

NSLayoutManager does not normally draw anything without the help of a view or accept user input. The View
layer handles those tasks in the text system. NSLayoutManager has its hands full mapping the attributed strings,
fonts, attachments, and paragraph styles in the Model layer to positioned glyphs ready for display in the View layer.
NSLayoutManager requires an incredibly complex implementation to support diverse languages, writing styles,
and fonts from around the world. It is one of the most complex and sophisticated classes in the Cocoa frameworks,
but it exposes very little of its complexity to Cocoa programmers.

NSLayoutManager uses instances of the NSTextContainer and NSTypesetter classes to assist it with its
task. The NSTextContainer class defines graphical areas within which the layout manager can place glyphs. By
default, text containers are rectangular, but NSTextContainer can be subclassed to simulate almost any shape.
Text containers can be used to force a layout manager to place glyphs around an irregular shape or leave gaps in the
glyph placement. NSLayoutManager uses private subclasses of NSTypesetter to control word wrapping,
hyphenation, line breaks, and even layout direction. Typesetters exist for right-to-left languages and vertical
languages. The NSSimpleHorizontalTypesetter class is used for most Western languages.

Diagrams of different ways layout managers and text containers can be configured are available at http://developer.
apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/ProgrammingTopics/TextArchitecture/index.html.

One NSTextStorage instance can be used with multiple NSLayoutManager instances. One
NSLayoutManager instance can have any number of ordered NSTextContainer instances. When the layout
manager has filled one container with glyphs, it moves on to the next container until it either runs out of glyphs to
place or runs out of containers. Each NSTextContainer instance is associated with at most one NSView
instance. NSLayoutManager can be used with NSTextContainer instances even if the containers are not
associated with views. In that configuration, the layout manager is used to calculate glyph placement and obtain
information such as the amount of space needed to display all the glyphs. The layout manager can even perform
precalculations and layout text in the background while other application threads continue to execute.
Apple provides the CircleView example in /Developer/Examples/AppKit/CircleView. The
CircleView example uses a custom NSView subclass and NSLayoutManager to position and draw glyphs
around the circumference of a circle. This example shows rudimentary use of NSLayoutManager in combination
with NSTextContainer and NSTextStorage.

Apple's TextEdit example (/Developer/Examples/AppKit/TextEdit) and the

TextSizingExample (/Developer/Examples/AppKit/TextSizingExample) both show complex
use of NSLayoutManager in combination with NSTextContainer to implement multiple column text, text
with margins, and text with complex sizing, wrapping and line break behaviors.

A new TextViewConfig example that is not distributed with Apple's Developer Tools prior to the release of Mac
OS X 10.1.5 is available at http://developer.apple.com/samplecode/Sample_Code/Cocoa/TextViewConfig.htm. This
example shows how to use multiple instances of NSLayoutManager with a single NSTextStorage instance
and multiple text containers.

The View Layer: NSTextView

The NSTextView class implements the View layer in Cocoa's text system. NSTextView handles display and
input of text at the user interface level. NSTextView is a subclass of NSText. NSText provides a general
interface to Cocoa's text system, but NSText is not normally used directly. Instead, NSTextView instances are
used. NSTextView provides the highest-level interface to the text system and includes features not available in
NSText.

Some simple uses of the NSTextView class have already been shown in the first sections of this chapter. The
simplest configuration for an NSTextView instance is the one provided by the text view on Interface Builder's
Cocoa-Data palette. That NSTextView is the document view of a scroll view and is preconfigured with one text
container as wide as the text view and very tall. Only one layout manager is used, and only one text storage is used.

The NSTextView methods for setting the text to be displayed and configuring text attributes such as color and
underline are all implemented to change the contents of the NSTextStorage instance associated with the view.
The NSTextContainer associated with the view is configured to resize horizontally when the view is resized
horizontally. The NSTextView instance is configured to automatically resize vertically to contain all the text in the
associated text container. If either the text storage or the text container change, the layout manager associated with
the NSTextView instance automatically lays out the text storage-attributed string within the text container to
account for the changes.

If the NSTextView changes size to accommodate a change in the size of the text container after text layout has
completed, the scroll view automatically adjusts the scrollbars to reflect the change.

NSTextView provides the -textStorage method that returns its associates NSTextStorage instance. The -
textContainer method returns the associated NSTextContainer instance. The -layoutManager method
returns the associated NSLayoutManager instance.

NSTextView provides a comprehensive set of methods for setting text attributes, controlling the display of text,
configuring text-input behavior, interacting with rulers, managing the user's current selection, undo, spell checking,
drag and drop, and even text-to-speech features. The NSTextView class is document at http://developer.apple.com/
techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSTextView.html and in the
documentation that comes with Apple's developer tools.

NSTextView is very seldom subclassed. Powerful techniques for controlling, validating, and formatting text input
by users without subclassing are described in the "Text Input" section of this chapter. NSTextView's methods are
largely self-explanatory after its interaction with NSLayoutManager, NSTextContainer, and
NSTextStorage has been described. The complete documentation for NSTextView is available at http://
developer.apple.com/techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSTextView.html
and comes with Apple's developer tools. The remainder of this section is dedicated to providing a couple of examples
that use NSTextView and the other text system classes.

Appending or Inserting an Image Attachment

One method for inserting or appending content to an NSTextView is by directly interacting with the
NSTextView's text storage. For example, a common task is to insert an image attachment into a text view. This can
be done at the NSTextStorage level using the following code:

NSTextAttachment *att;
NSString *path;
NSFileWrapper *wrapper;
NSAttributedString *attStr;

// determine the path to our image

path = [[NSBundle mainBundle] pathForResource:@"image" ofType:@"tiff"];

// construct an NSFileWrapper for the path

wrapper = [[[NSFileWrapper alloc] initWithPath:path] autorelease];

// construct an NSTextAttachment for the NSFileWrapper instance

att = [[[NSTextAttachment alloc] initWithFileWrapper:wrapper] autorelease];
attStr = [NSAttributedString attributedStringWithAttachment:att];

//Insertion Code Begins

[[theTextView textStorage] beginEditing];
[[theTextView textStorage] appendAttributedString:attStr];
[[theTextView textStorage] endEditing];
//Insertion Code Ends

The theTextView variable is a previously created NSTextView instance. The path to an image is used to
initialize a new NSFileWrapper instance. The NSFileWrapper instance is then used to create a new
NSTextAttachment. The NSAttributedString method, +attributedStringWithAttachment:,
creates an instance of an attributed string configured to hold the image attachment. NSFileWrapper is described
in Chapter 7's "NSFileWrapper" section. NSBundle is described in the "NSBundle" section of Chapter 7.

After the attributed string is constructed, theTextView's associated NSTextStorage is notified that editing is
going to begin by calling the -beginEditing method. The attributed string is appended directly to the text
storage, and the NSTextStorage is notified that editing is complete using -endEditing. The -
beginEditing and -endEditing methods cause NSTextStorage to coalesce change notifications for
changes that occur between -beginEditing and -endEditing. This is not very important in this example, but
if many changes are made at once, the -beginEditing and -endEditing block prevents the associated
NSLayoutManager from expensively recalculating the layout after each change. Instead, the layout can be
recalculated once including all the changes.

It is possible to insert the image at a specific location, using code such as the following:

//Insertion Code Begins

[[theTextView textStorage] beginEditing];
[[theTextView textStorage] replaceCharactersInRange:NSMakeRange(
insertionLocation,0) withAttributedString:attStr];
[[theTextView textStorage] endEditing];
//Insertion Code Ends
To replace text with an image or attachment, use one the -replaceCharactersInRange: method and specify
a range with a length greater than zero.

Inserting a Web Link

Inserting a Web link is similar to inserting an image. Begin by constructing an instance of NSDictionary that
contains an NSString instance (the link) as the value for the NSLinkAttribute identifier; then create a new
NSAttributedString with the text that should be displayed and the link requested.

The following NSAttributedString category provides an +attributedStringWithLink:

labelString: method that returns a properly formatted NSAttributedString for a link:

@implementation NSAttributedString (_MYLinkSupport)

+ (NSAttributedString *)attributedStringWithLink:(NSString *)link

labelString:(NSString *)text;
{
NSDictionary *attrsDict;
attrsDict = [NSDictionary dictionaryWithObject:link
forKey:NSLinkAttributeName];
return [[[NSAttributedString alloc] initWithString:text
attributes:attrsDict] autorelease];
}

@end

The +attributedStringWithLink:labelString: method is used to append a link to the text in an

NSTextView as follows:

NSAttributedString *linkStr;

linkStr = [NSAttributedString
attributedStringWithLink:@"http://www.cocoaprogramming.net"
labelString:@"Go to Cocoa Developer's Handbook site"];
[[textView textStorage] beginEditing];
[[textView textStorage] appendAttributedString:linkStr];
[[textView textStorage] endEditing];
Book: Cocoa® Programming
Section: Chapter 11. The Cocoa Text System

Managing Fonts

In the "The Control Layer: Text Layout and Containers" section of this chapter, it was
stated that glyphs are managed by font objects. Each font can be thought of as a collection
of glyphs. Each glyph depicts a character in a particular character set. Character sets are
described in the "NSCharacterSet" section of Chapter 7. Character sets describe groups of
Unicode characters. Because no font can contain glyphs for every possible Unicode
character, a complex relationship between character sets, Unicode characters, and fonts is
needed. The complexity is encapsulated within the NSLayoutManager class that is
responsible for laying out glyphs corresponding to the characters and attributes in
attributed strings.

Cocoa's text system can use Fonts specified in PostScript, Macintosh TrueType, Windows
TrueType, or OpenType formats. Fonts are automatically available for use if they are
located in the standard font locations (/Network/Fonts, /Local/Library/
Fonts, /Library/Fonts, ~/Library/Fonts, and /System/Library/
Fonts). The standard locations and the logic used to search for fonts and other resources
are described in the "Standard Locations" section of Chapter 22, "Integrating with the
Operating System."

Cocoa provides three principal classes for managing fonts: NSFont, NSFontPanel, and
NSFontManager. Fonts are grouped into font families. For example, Helvetica and
Times are two common font families. Each family consists of one or more individual fonts,
also called typefaces. Fonts exhibit one or more style traits. For example, bold and italic
are traits of a font. The terminology used to describe fonts is almost as old as the printing
press. A complete discussion of typography and fonts requires a book longer than this one.
By necessity, only an overview of Cocoa's font support and font usage is provided here.

When working with fonts, an individual typeface is often referenced by its fully specified
font name, which consists of the family name combined with the typeface's traits.
Helvetica-BoldOblique, LucidaGrande-Bold, and Futura-CondensedExtraBold are
examples of fully specified font names. Each typeface also has a weight, which refers to
how visually heavy the font appears. Examples of font weights include ultralight, light,
book, regular (also called plain or book), bold, extrabold, and black.

The Cocoa font managing classes use the Model-View-Controller architecture. The
NSFont class is the model. It encapsulates the glyphs and traits of a font. The standard
Font panel represented by an instance of the NSFontPanel class is the view component.
It provides a way for users to view and select fonts. The NSFontManager class is the
controller. It provides a list of available fonts, keeps track of which fonts are being used,
converts fonts between typefaces and traits, and controls communication between the Font
panel and an application.

The NSFont Class

Each NSFont instance represents a specific typeface and is created only once for each
application. Each NSFont instance is stored and reused. When an NSFont instance is
requested with a typeface that has been previously used, the existing instance is returned. If
the no appropriate NSFont instance has been created for the requested typeface, a new
instance is automatically created, stored for later reuse, and returned.

Getting an NSFont Instance

An instance of NSFont that corresponds to a specific font is returned by calling the

method +fontWithName:size: passing an NSString as the name argument and a
float as the size. The font name must be the fully specified font family name. The size is
measured in Postscript Points (pts.). Passing 0.0 as the size: parameter causes
+fontWithName:size: to return a font with a default size. The default size is
determined by the user's preference the defaults database that is described in the "Defaults
System" section of Chapter 7.

NOTE

Fonts created via +fontWithName:size: automatically flip themselves

when drawing in an NSView that has a flipped coordinate system. Flipped
views are described in the "Rectangle Tests" section of Chapter 12, "Custom
Views and Graphics Part I."

There are a number of convenience methods available to access standard fonts. Using the
standard fonts ensures a consistent appearance across applications. The
+systemFontOfSize: method provides the font that is used for standard interface
items such as buttons and menu items. Passing zero or a negative value as the size returns
the system font with the default size. The default size for the system font is returned by
+systemFontSize. The bold variation of this font is available using the method
+boldSystemFontSize:, again passing the size as a float. The
+smallSystemFontSize method returns the size to use when specifying a small
system font. The +labelFontOfSize: method returns an instance of NSFont
consistent with Apple's Aqua guidelines for labels in the user interface. The default size for
such fonts is returned by +labelFontSize.

The user font (also called the Application font) is returned by calling the method
+userFontOfSize:. This is the font used by default for text that the user is able to edit.
The user's default fixed pitch font is returned by the method
+userFixedPitchFontOfSize:. In both cases passing zero or a negative size results
in the return of a font with the default size. A fixed pitch font is one in which all the glyphs
require the same space when printed. Most fonts are proportionally spaced, meaning that
different glyphs require different amounts of space. The user font for an application can be
set by calling the method +setUserFont: passing an NSFont instance as the
argument. The fixed pitch user font is set by calling +setUserFixedPitchFont:.

Obtaining Font Information

NSFont provides a myriad of methods for getting detailed information about a font and
specific glyphs within a font. Only the most commonly used methods are described in this
section. The complete documentation for NSFont is available at http://developer.apple.
com/techpubs/macosx/Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSFont.
html, and in the documentation that comes with Apple's developer tools.

The fully specified name of a font is returned by NSFont's -fontName method. The
family name is returned by -familyName. The method -displayName returns the
name that should be used to identify the font in a user interface. The -displayName
method returns a name in the user's preferred language.

To determine if a font is a fixed pitch font, call the method -isFixedPitch. This
method returns a Boolean value of YES if the font has fixed pitch and NO if it is a
proportionally spaced font.

NSFont's -pointSize method returns a float that represents the size of the font in
Postscript Points. This is the overall height of the font from its lowest descender to its
highest ascender, and because of this, two fonts with the same point size might appear to be
radically different sizes. Figure 11.2 shows the critical dimensions of a font that are used to
layout glyphs and calculate the area needed to display glyphs. The method -ascender
returns the distance in Postscript Points from the baseline of the font to the highest
ascender. Likewise, -descender returns the distance of the lowest descender from the
font baseline.

Figure 11.2. Fonts are measured by their total point size as well as ascender,
descender, xHeight, and capHeight dimentions.

Calling -capHeight returns a float that is the height in Postscript Points of a capital
letter in the font. Individual letters might have ascenders that are larger or smaller than the
-capHeight value. The -xHeight method returns the height of a lowercase letter in
the font. NSFont approximates both the -capHeight and -xHeight values in some
cases because not all font formats provide the information.

The -defaultLineHeightForFont method returns a float that is the sum of the

ascender and descender of the font plus the default line gap (vertical distance between two
lines of text).

The method -maximumAdvancement returns an NSSize structure that represents the

maximum advancement of a glyph in the font. Depending on the type of font, the
advancement can be horizontal or vertical. The -boundingRectForFont method
returns an NSRect that is the union of the bounding rectangles for all the glyphs in the
font. The bounding rectangle is the minimum rectangle that completely encloses a glyph.
The union of those rectangles is the minimum rectangle that encloses all of the bounding
rectangles.

Using the Font Manager

The NSFontManager class is the hub of font used in Cocoa. It tracks the available fonts
and traits, displays the NSFontPanel, and notifies responders when a font is changed.
There is a single shared NSFontManager instance in each graphical Cocoa application.
The shared instance is retrieved with NSFontManager's +sharedFontManager class
method.

When a user changes font attributes with the Font panel, the shared NSFontManager
object records the requested attribute, changes, and then sends a -changeFont: message
up the responder chain. Objects in the responder chain implement -changeFont: to call
NSFontManager's -convertFont: method. The argument to -convertFont: is
an NSFont instance that will be converted to be consistent with the user's choices in the
Font panel. For example, if the user has changed only the point size selected in the Font
panel, the font passed to -convertFont: is modified to have the specified size without
affecting other attributes such as the font face or whether the font is italic.

The -convertFont: method can be called multiple times as the result of one -
changeFont: message. For example, if the current selection in a text editor includes text
with several different fonts, the -convertFont: method is called once for each font in
the selection. Because -convertFont: only modifies the attributes that were explicitly
set by the user, several convenient features are automatically provided to users. When the
selection includes multiple fonts, the user is able to change only the size of each font
without changing the font face. Similarly, the user is able to change all the selected text to
one font face without changing the different font sizes in the selection.

NSFontManager methods such as -addFontTrait: and -removeFontTrait:

simulate the corresponding changes made through the Font panel and cause
NSFontManager to send the -changeFont: message up the responder chain.

The weight of an NSFont instance is returned by calling the method -weightOfFont:

passing an NSFont instance as the argument. An NSFontTraitMask describing the
traits of a font is returned by calling the -traitsOfFont: passing an NSFont instance
as the argument. Font traits and weights are described in the next section.

Font Traits and Weights

Each typeface exhibits one or more style traits. A group of traits can be specified with an
NSFontTraitMask value. NSFontTraitMask values are used to create new
typefaces or modify existing typefaces. Table 11.3 lists common traits and their
restrictions. This is not a complete list of the possible traits for a font. Only the traits used
by NSFontManager to convert font into another are listed.

Table 11.3. Common Font Traits and Restrictions

Trait Restrictions

NSBoldFontMask Mutually exclusive with

NSUnboldFontMask

NSUnboldFontMask Mutually exclusive with

NSBoldFontMask

NSItalicFontMask Mutually exclusive with

NSUnitalicFontMask

NSUnitalicFontMask Mutually exclusive with

NSItalicFontMask

NSNonStandardCharacterSetFontMask None

NSNarrowFontMask None
NSCondensedFontMask Mutually exclusive with
NSExpandedFontMask

NSExpandedFontMask Mutually exclusive with

NSCondensedFontMask

NSSmallCapsFontMask None

NSPosterFontMask None

NSCompressedFontMask None

NSFixedPitchFontMask None

NSFont provides several methods for requesting a specific font using the fully specified
typeface name. NSFontManager provides alternative methods that use the family name,
the font traits, the font weight, and the size to specify a font. NSFontManager's -
fontWithFamily:traits:weight:size: accepts a family name passed as an
NSString for the first argument. The traits: argument is the value of an
NSFontTraitMask, or a C bitwise logical OR of multiple NSFontTraitMask values
from Table 11.3. The weight is an integer value between 0 and 15 that represents the visual
heaviness of a face. Table 11.4 lists the available integer weight values and the
corresponding typographic term for the weight. Finally, the size argument is passed as a
float value measured in Postscript Points.

Table 11.4. Font Weight Constants and Corresponding Typographic Terms

Weight Constant Standard Term

1 ultralight

2 thin
3 light, extralight

4 book

5 regular, plain, display, roman

6 medium

7 demi, demibold

8 semi, semibold

9 bold

10 extra, extrabold

11 heavy, heavyface

12 black, super

13 ultra, ultrablack, fat

14 extrablack, obese, nord

NOTE

If the NSBoldFontMask trait is included in the traits: argument to -

fontWithFamily:traits:weight:size:, the weight: argument
is ignored.

The weight of an NSFont instance is returned by calling the method -weightOfFont:

passing the NSFont instance as the argument. An NSFontTraitMask consisting of the
logical OR of all the traits of an NSFont is returned by calling -traitsOfFont:
passing the NSFont instance as the argument.

It is possible to determine if a font typeface has specific traits using the method -
fontNamed:hasTraits:. This method requires a fully specified font typeface name
such as an NSString for the first argument and a NSFontTraitMask value, or a
logical OR of multiple NSFontTraitMask values, as the second argument. It returns the
Boolean YES only if all the traits specified in the hasTraits: argument are true for the
named font.

Determining Available Fonts

An application can get an array of all available font typefaces by calling

NSFontManager's -availableFonts method. This method returns an NSArray
containing fully specified typeface names. Similarly, an application can get a subset of the
available fonts that correspond to a specific set of font traits by using the method -
availableFontNamesWithTraits: passing a logical OR of NSFontTraitMask
values as the argument. A value of 0 for the NSFontTraitMask returns fonts that are
neither bold nor italic faces. In both methods, fonts that are not normally displayed to the
user are prefaced with a . character.

A localized version of the family and face name is returned by the method -
localizedNameForFamily:face:. Passing nil as the face string returns a
localized version of the face name.

Converting Fonts

NSFontManager is able to provide NSFont instances by converting any of the family,

face, size, weight, or traits of an existing NSFont instance. The conversion methods
accept an NSFont instance argument used as the basis for changes.

The principal conversion method is -convertFont:. It returns an NSFont instance

derived from the font passed as an argument. Attributes specified by the user via the
standard Font panel or the standard Font menu are applied to the font being converted. For
example, if the Font panel currently has no selected font family, but the size is set to 72.0
pts., and -convertFont: is called passing an NSFont instance that represents
Helvetica-Bold 12.0 pts., the returned NSFont represents Helvetica-Bold 72.0 pts. If,
however, the font panel specifies the Times family with 48.0 pts., the returned NSFont
represents Times-Bold 48.0 pts. Only the font attributes explicitly specified by the user are
changed when converting a font.

The method -convertFont:toFace: returns an NSFont instance with the font face
name specified by a string passed as the second argument. All other attributes of the
returned font are identical to the attributes of the font passed as the first argument. The face
should be a fully specified family-face font name such as Helvetica-BoldOblique. If
NSFontManager is unable return the requested font, nil is returned.

The -convertFont:toFamily: method returns an NSFont belonging to the font

family passed as an NSString name. The returned font has the same size and traits as the
base font passed as the first argument. For example, if the passed NSFont instance
represents Helvetica-BoldOblique, and the requested family is Optima, this method returns
an NSFont representing Optima-BoldItatlic. If no face in the requested family has the
same attributes as the font argument, the NSFont argument is returned unmodified.

The method -convertFont:toHaveTrait: returns an NSFont instance based on

NSFont and the trait passed as the second argument. Only a single trait can be passed as
the toHaveTrait: argument. If NSFontManager is unable to make the conversion,
the NSFont passed as the first argument is returned unchanged. The -convertFont:
toNotHaveTrait: returns an NSFont instance based on the passed NSFont and
returns a variant that does not have the specified trait. Again, if the conversion does not
take place, the passed NSFont argument is returned unchanged.

The -convertFont:toSize: method returns an NSFont instance with the same

family, face, traits, and weight as the first argument and the float size in Postscript
Points specified by the second argument.

The final method in NSFontManager's conversion suite is -convertWeight:

ofFont:. The weight argument, a Boolean, specifies if the returned font should be
visually heavier (by passing a YES value) or lighter (by passing a NO value) than the
supplied NSFont instance. If there is no heavier or lighter face available, the NSFont
instance passed as the second argument is returned unmodified.

Current Font Selection

Applications notify the NSFontManager of changes in the current font using the method
-setSelectedFont:isMultiple:. Graphical applications should call this method
when the user's selection has changed and pass the font used by the current selection as the
first argument. Cocoa's NSText and NSTextView classes already do this. It is only
necessary to call -setSelectedFont:isMultiple: in applications that handle fonts
directly. If the selection uses only a single NSFont instance, the Boolean value NO is
passed as the isMultiple: argument. If there are multiple fonts used by the current
selection, the application should call -setSelectedFont:isMultiple: once for
each font used, passing the NSFont instances as the first argument. For the first font used,
call -setSelectedFont:isMultiple: with NO as the isMultiple: argument.
For each subsequent font, pass YES as the isMultiple: argument.

NSFontManager's -selectedFont method returns the last NSFont instance passed

to -setSelectedFont:isMultiple:. It is possible to determine if there are
multiple fonts selected by calling the method -isMultiple, which returns a Boolean
value.

NOTE

Using NSFontManager's -selectedFont method from within an

implementation of -changeFont: is not a reliable way to obtain the user's
font selection. Font attributes that the user has not explicitly set will have
indeterminate values. Instead use the NSFontManager's -
convertFont: method to convert an existing NSFont instance into one
that corresponds to the user's chosen font attributes.

Triggering -changeFont: Programmatically

NSFontManager sends the -changeFont: up the responder chain when the user
changes a selection in the Font panel or Font menu. The -changeFont: message is the
key to informing the rest of Cocoa's text system that a change has been made. Custom
objects that display editable text need to implement the -changeFont: method to call
NSFontManager's -convertFont: and convert fonts in the user's current selection. It
is possible to cause NSFontManager to send the -changeFont: message as the result
of programmatic changes as well.

NSFontManager's -addFontTrait: specifies a font trait that will be applied the next
time the NSFontManager receives a -convertFont: message. Calling -
addFontTrait: causes the NSFontManager to send a -changeFont: message.
The object that is passed as the argument to -addFontTrait: must respond to the -
tag message by returning NSFontTrait. The -removeFontTrait: operates in a
similar manner. It removes the trait returned by the -tag method of the argument and
sends the -changeFont: message.

The method -modifyFontViaPanel: causes the -changeFont: message to be sent

up the responder chain, and when the NSFontManager receives a subsequent -
convertFont: request, the NSFontManager uses the NSFontPanel's -
panelConvertFont method to return the new NSFont. The NSFontPanel class is
described in the "Using the Font Panel" section of this chapter.

Finally, the method -modifyFont: is used to control how fonts are converted by calls to
-convertFont:. The -modifyFont: method can be used to increase or decrease a
font's size or weight. It triggers a -changeFont: message. The object passed as the
argument to -modifyFont: must implement the -tag method to return one of the
constants in Table 11.5. The constant returned determines which method will be used to
convert fonts and consequently which attributes will change as the result of subsequent -
convertFont: calls.
 Table 11.5. Font Modification Actions and Corresponding Conversion Methods

Modification Action Conversion Method

NSNoFontChangeAction The font passed to -convertFont: is not

changed.

NSViaPanelFontAction The font passed to -convertFont: is changed by

NSFontPanel's -panelConvertFont method.

NSAddTraitFontAction The font passed to -convertFont: is changed by

the -convertFont:toHaveTrait: method.

NSRemoveTraitFontAction The font passed to -convertFont: is changed by

the -convertFont:toNotHaveTrait:
method.

NSSizeUpFontAction The font passed to -convertFont: is changed by

increasing its size using the -convertFont:
toSize: method.

NSSizeDownFontAction The font passed to -convertFont: is changed by

reducing its size using the -convertFont:
toSize: method.

NSHeavierFontAction The font passed to -convertFont: is changed by

increasing its weight using the -convertWeight:
ofFont: method.

NSLighterFontAction The font passed to -convertFont: is changed by

decreasing its weight using the -convertWeight:
ofFont: method.

NSFontManager normally sends the -changeFont: up the responder chain to

indicate that a change to a font is needed, but a different message can be specified via
NSFontManager's -setAction: method. Cocoa's text classes expect to receive -
changeFont: messages and will most likely malfunction if it is not sent, but it might
make sense to customize this behavior in some applications. The selector of the message
sent by NSFontManager is returned from the -action method.

Interacting with the User

As a Controller in the Model-View-Controller architecture, NSFontManager is

responsible for communications between the Model and the View layers. NSFont objects
compose the model. NSFontManager methods for interacting with the model have
already been described. NSFontManager doesn't provide any direct visual interaction
with the user, but it does provide access to the two most common View layer objects that
enable font manipulation: the Font panel and the Font menu. In addition,
NSFontManager is used to enable and disable the user's ability to change fonts via an
application's user interface.

A shared instance of the NSFontPanel class is from NSFontManager's -

fontPanel: method. The argument to -fontPanel: is a Boolean that indicates
whether the NSFontPanel instance should be created if it does not already exist. The
NSFontManager method -orderFrontFontPanel: makes the standard Cocoa
Font panel (creating it if necessary) the frontmost window.

The standard Font menu is returned from NSFontManager's -fontMenu: method as

an NSMenu instance. The argument to -fontMenu: is a Boolean value specifying
whether the menu should be created if it does not already exist. It is also possible to set the
current font menu for an application by calling NSFontManager's -setFontMenu:
passing the NSMenu instance to use as the Font menu as the argument.

The user interface objects that control interactive font changes can be disabled or enabled
using the -setEnabled: method and passing a Boolean as the argument. The current
status of the user interface is queried with -isEnabled, which returns a Boolean value.

Finally, the fonts that are shown to the user in the Font Panel are restricted by
implementing the -fontManager:willIncludeFont: method in the
NSFontManager's delegate. This method is called automatically if the delegate responds
to it. The first argument is the shared NSFontManager instance. The second argument is
the fully specified name of a font to be displayed in the Font panel. If -fontManager:
willIncludeFont: returns YES, the font is present in the Font panel. Otherwise, the
font is not shown and is not available for the user to select. The determination of the value
to return can be based on many different criteria. For example, an application might restrict
font selection to only fixed pitch fonts if a particular view that only displays fixed pitch
fonts is the first responder in the main or key windows.

Using the Font Panel and Font Menu

The NSFontPanel class encapsulates the standard Cocoa Font panel. The Font panel
provides a consistent and flexible user interface for selecting and modifying fonts. Figure
11.3 shows the standard Font panel and the standard Font menu.

Figure 11.3. The standard Font panel and Font menu are shown.

NSFontPanel is a subclass of the NSPanel class. NSPanel is briefly described in the

"NSWindow Overview" section of Chapter 8, "The Application Kit Framework
Overview," and more extensively in the "Working with Panels" section of Chapter 9,
"Applications, Windows, and Screens."

Each graphical Cocoa application has a single shared instance of the NSFontPanel class
that is created the first time it is needed. The shared instance is returned by calling
NSFontPanel's +sharedFontPanel method or by calling NSFontManager's -
fontPanel: method. It is made visible to the user by calling the -
makeKeyAndOrderFront: method inherited from the NSWindow class or by using
NSFontManager's -orderFrontFontPanel: method.

As with most standard Cocoa panels, it is possible to add an accessory view through the
use of -setAccessoryView: passing the NSView that should be added to the panel.
The -accessoryView method returns the current accessory view or nil if none has
been set. Accessory views are described in the "Document Actions and the Save Panel"
section of Chapter 9.

NSFontPanel's -worksWhenModal method ignores the -setWorksWhenModal:

flag and always returns YES, enabling users to change fonts even in modal panels. The -
worksWhenModal and -setWorksWhenModal: methods are explained in the "Using
Modal Windows" section of Chapter 9.

The NSFontPanel class uses the -panelConvertFont: method to change an

existing a font according to the Font Panel's current settings. The argument is the NSFont
instance to change. This works similarly to NSFontManager's -convertFont:
method, returning only the changes that are selected in the Font panel. If changes cannot be
made to the specified font, the original font instance is returned.

The method -reloadDefaultFontFamilies reloads the set of fonts displayed in the

Font panel. This in turn calls the NSFontManager's delegate's implementation of -
fontManager:willIncludeFont: for each font allowing the application to filter
the fonts shown to the user. The -reloadDefaultFontFamilies method can be
called to update the Font panel after the filter criteria for -fontManager:
willIncludeFont: has changed, or to detect new fonts added to the system while the
application has been running.

The standard Font menu is available on Interface Builder's Cocoa-Menus palette. Most of
the menu items in the Font menu send action messages up the responder chain. The menu
items are automatically enabled if an object in the responder chain responds to their actions
and disabled otherwise. The action messages are eventually received by a Cocoa text
object, such as an NSTextView instance or a custom object that responds to the action.

Three of the standard menu items in the Font menu are preconfigured to send messages
directly to the application's shared NSFontManager instance. The Font, Show Fonts
menu item sends the -orderFrontFontPanel: message to the font manager. The
Font, Bold and Font, Italic menu items send the -addFontTrait: message to the font
manager.
Book: Cocoa® Programming
Section: Chapter 11. The Cocoa Text System

Text Input

NSTextView uses helper objects called input managers to interpret user input and turn it into text or commands.
NSTextView passes raw character input to an input manager. The input manager determines what the raw input
means and sends messages to the NSTextView. If the input consists of characters to be inserted, the input
manager sends an -insertText: message with the text to insert. If the input consists of commands such as
cursor movement keys, the Enter key, or the Backspace key, the input manager sends a -
doCommandBySelector: message with an appropriate selector as the argument. The selector specifies the
action that the text view should take such as -moveDown:, -deleteBackward:, or -insertNewline:.
The set of actions that input managers can send is documented at http://developer.apple.com/techpubs/macosx/
Cocoa/Reference/ApplicationKit/ObjC_classic/Classes/NSResponder.html, and in the NSResponder
documentation that comes with Apple's developer tools.

NSTextView gives its delegate an opportunity to intercept actions sent with -doCommandBySelector:. The -
textView:doCommandBySelector: delegate method is described in the "NSTextView Delegate Methods
and Notifications" section of this chapter. If the delegate implements -textView:doCommandBySelector:,
and it returns YES, the text view does nothing further; otherwise, the text view performs the action specified by the
command.

Input managers are encapsulated by the NSInputManager class and communicate with NSTextView instances
via the NSTextInput protocol. Input managers are typically implemented as separate processes, and
communication between the input manager and applications is handled by NSInputManager instances. Input
managers are briefly described in the "Input Managers" section of Chapter 10, "Views and Controls." Apple
provides an NSInputManager example in /Developer/Examples/AppKit/HexInputServer.
Another example is available at http://developer.apple.com/samplecode/Sample_Code/Text/
Inline_Input_for_TextEdit.htm.

Input managers play a small but crucial role in the Cocoa text system. Input managers offer a great degree of
flexibility. For example, many Eastern languages require multiple keystrokes to compose a single Unicode
character. An input manager is able to accept as many keystrokes as necessary, and then call -insertText: only
once with the fully composed Unicode. Apple provides handwriting recognition capabilities that are implemented
as an input manager so that the characters, words, and commands that originate from a stylus and graphics tablet are
sent to an NSTextView. Similarly, speech input can be gathered from a microphone and injected into Cocoa's text
system. Because appropriate input managers exist, every Cocoa text object automatically works seamlessly with a
wide variety of input sources.

Using Delegate Methods

The NSText class sends notifications and communicates with its delegate when changes are made. The delegate is
given substantial control over text-editing behavior. As a subclass of NSText, NSTextView also uses the
delegate. In fact, NSTextView extends the set of messages sent to the delegate to include all NSText's delegate
messages as well as its own.

NOTE

Use the notifications sent by NSTextView objects or implement a delegate to customize text-
handing behavior. Many complex Cocoa classes including NSTextView are extremely difficult to
subclass effectively. Subclassing NSTextView should always be a last resort.
NSText Delegate Methods and Notifications

The delegate method -textShouldBeginEditing: is called when an action that will change the contents or
format of an NSText instance is about to take place. The argument to -textShouldBeginEditing: is the
text object that sent the message. If the delegate implements -textShouldBeginEditing: and returns the
Boolean value NO, the changes to the NSText object are not allowed. If -textShouldBeginEditing:
returns YES, the text system operates as usual.

When an NSText object is about to stop editing, for example, when another NSText object is about to become
active, the delegate's -textShouldEndEditing: method is called. The argument is the text object that sent the
message. The delegate implementation allows editing to end by returning the Boolean value YES. If NO is returned,
the text object that sent the message refuses to give up its First Responder status. Because the text object remains
the First Responder, no other text object can become active and begin editing. A text object must be the First
Responder to be edited. A text object can be forced to end editing even if -textShouldEndEditing: returns
NO by calling [aWindow endEditingFor:nil] where aWindow is the window that contains the text object.

There are three notifications that can be posted by an NSText object:

NSTextDidBeginEditingNotification, NSTextDidChangeNotification, and
NSTextDidEndEditingNotification. There are corresponding delegate methods for each of these
notifications. The delegate methods are called even if the delegate does not observe the notifications.

An NSTextDidBeginEditingNotification is sent when an action is about to change the contents or

format of an NSText object that was not already being edited. Use NSNotification's -object method to
access to the text object that sent the notification. The delegate method -textDidBeginEditing: is
automatically called when the NSTextDidBeginEditingNotification notification is sent. The argument
to -textDidBeginEditing: is the notification object.

An NSTextDidChangeNotification is sent when the contents or format of an NSText object have just
been changed. The NSNotification that is passed to any registered observers contains the affected NSText
object as its -object value. The delegate method -textDidChange: is automatically called with an
NSNotification argument when the notification is sent.

An NSTextDidEndEditingNotification is sent when a text object has ended editing. The

NSNotification's -object value is the text object that sent the notification. The delegate's -
textDidEndEditing: method is called with the notification as the argument. The NSNotification
instance sent for NSTextDidEndEditingNotification contains a dictionary with a single key,
NSTextMovement. Calling the notification's -userInfo method accesses the dictionary. The value for the
NSTextMovement key is one of the following constants that indicate why the editing ended:
NSReturnTextMovement, NSTabTextMovement, or NSBackTabTextMovement.

NSTextView Delegate Methods and Notifications

The NSTextView extends the delegate methods provided by NSText to handle fine-grained control of
attachments, links, selection changes, keyboard navigation, undo, and formatting.

The -textView:clickedOnCell:inRect:atIndex: delegate method is called after the user clicks an

attachment embedded in an NSTextView instance. The first argument is the NSTextView instance that sent the
message. The second argument is the cell that represents the attachment. The third argument is the rectangle that
encloses the attachment cell in the text view's coordinate system. The fourth argument is the position within the text
view's text storage of the NSAttachmentCharacter for the clicked attachment. The delegate can use this
method to select the attachment or send an action message.
 NOTE

The NSTextView object sent as the first argument to NSTextView's delegate messages is usually
the first text view in the ordered collection of text views used by an NSLayoutManager. A single
NSLayoutManager can layout text for multiple views. Because the change that caused a delegate
message to be sent might have occurred in one of the other text views managed by the layout manager,
there is no guarantee that the change happened in the text view passed as the first argument to the
delegate method.

The most reliable way to process text within an NSTextView delegate method is to use the sending
NSTextView's text storage directly, rather than using the NSTextView's methods.

The -textView:clickedOnLink:atIndex: delegate method is called after the user clicks a link embedded
in an NSTextView instance. The first argument is the NSTextView instance that sent the message. The second
argument is the link that was clicked. The third argument is the position within the text view's text storage of the
link. If the delegate does not respond to this message or returns NO, the text view's next responder is given an
opportunity to process the click. If the delegate handles the click, return YES from -textView:
clickedOnLink:atIndex:.

The -textView:doCommandBySelector: delegate message gives delegates an opportunity to intervene in

an NSTextView's command processing. The first argument is the text view that sent the message. The second
argument is a selector that identifies an action to perform. If the delegate does not respond to -textView:
doCommandBySelector: or returns NO, the text view processes the command by performing the action. If the
delegate does handle the command on behalf of the text view, -textView:doCommandBySelector: should
return YES informing the text view that no additional processing is required. Implement this delegate method to
influence selection changes, insertion cursor movement, text insertion, text deletion, and scrolling. Apple provides
an excellent example that uses this method at http://developer.apple.com/samplecode/Sample_Code/Cocoa/
TextViewDelegate.htm.

The -textView:doubleClickedOnCell:inRect:atIndex: method is called after the -textView:

clickedOnCell:inRect:atIndex: method if the user clicks a second time within the default double-click
threshold. The arguments to -textView:doubleClickedOnCell:inRect:atIndex: are the same as the
arguments to -textView:clickedOnCell:inRect:atIndex:. Implement this delegate method to
perform special processing when an attachment is double-clicked.

The -textView:draggedCell:inRect:event:atIndex: message is sent to the delegate when the user

attempts to drag an attachment within an NSTextView. The first argument is the NSTextView that sent the
message. The second argument is the cell that represents the attachment. The third argument is the rectangle that
encloses the attachment cell in the text view's coordinate system. The fourth argument is the NSEvent that started
the drag. The NSEvent class is described in the "Responders" section of Chapter 8. The fifth argument is the
position within the text view's text storage of the NSAttachmentCharacter for the dragged attachment. The
delegate can implement this method to initiate a dragging operation. Drag operations are explained in the "Drag and
Drop in Custom View and Window Objects" section of Chapter 19, "Using Pasteboards."

The -textView:shouldChangeTextInRange:replacementString: method is used to control

whether a particular range of characters can be modified. The first argument is the NSTextView that sent the
message. The second argument is an NSRange structure that identifies the range of characters to be replaced. The
third argument is a string containing the proposed replacement characters. The third argument is nil if only
attributes are being changed. If the delegate implements this method to return YES or the delegate does not
implement this method at all, the text view makes the change. If the delegate implements -textView:
shouldChangeTextInRange:replacementString: to return NO, the change is not made.
The -textView:willChangeSelectionFromCharacterRange:toCharacterRange: delegate
method is called before the selection is changed. The first argument is the NSTextView that sent the message. The
second argument is an NSRange structure identify the range of characters currently selected. The third argument is
the proposed range of characters that will be selected. Implement this method to return the range that should be
selected. The delegate can return the proposed range unmodified or substitute any other range as appropriate.

The -textView:writablePasteboardTypesForCell:atIndex: delegate method is used to return an

array of pasteboard types suitable for writing an attachment to the pasteboard. The first argument is the
NSTextView that sent the message. The second argument is the cell that represents the attachment. The third
argument is the position of the character that represents the attachment in the text view's text storage. Do not
implement this method if the delegate implements -textView:draggedCell:inRect:event:atIndex:.

The -textView:writeCell:atIndex:toPasteboard:type: delegate method is used to write an

attachment to a pasteboard. The first argument is the NSTextView that sent the message. The second argument is
the position of the character that represents the attachment in the text view's text storage. The third argument is the
pasteboard. The fourth argument is a pasteboard type. -textView:writeCell:atIndex:toPasteboard:
type: should return YES if the attachment is successfully written to the pasteboard and NO otherwise.

The -undoManagerForTextView: method enables the delegate to control which NSUndoManager instance
is used with a text view. The argument is the NSTextView that sent the message. Return an NSUndoManager
instance. NSUndoManager is described in the "Undo and Redo" section of Chapter 8.

NSTextView posts the following notifications in addition to the ones posted by the NSText class:
NSTextViewDidChangeSelectionNotification and
NSTextViewWillChangeNotifyingTextViewNotification.

The NSTextViewDidChangeSelectionNotification is posted whenever the selection changes in a text

view. This notification is posted once at the end of each selection operation. If the NSTextView's delegate
implements the -textViewDidChangeSelection: method, it is automatically called even if the delegate
does not observe the notification. The argument to -textViewDidChangeSelection: is the
NSNotification instance that was posted. Use NSNotification's -object method to obtain the
NSTextView that posted the notification. The notification's -userInfo dictionary contains a single key,
NSOldSelectedCharacterRange. The value of the key is an NSValue instance containing an NSRange
structure that identifies the previously selected range. The NSTextView that posted the notification can provide
the current selection range.

The NSTextViewWillChangeNotifyingTextViewNotification is posted whenever one

NSTextView is about to stop sending notifications and another is about to start. Observing this notification gives
objects a chance to reregister for notifications from a new NSTextView instance. Calling NSTextView's -
removeTextContainerAtIndex:, -textContainerChangedTextView:, and -
insertTextContainer:atIndex: methods results in this notification being posted. There's no delegate
method that is called automatically when this notification is posted.

The -object of the NSTextViewWillChangeNotifyingTextViewNotification is the old notifying

NSTextView or nil. The notification's -userInfo dictionary might contain zero, one, or two keys. The two
possible keys are NSOldNotifyingTextView and NSNewNotifyingTextView. The value for the
NSOldNotifyingTextView key is the old NSTextView, if it exists. The value for the
NSNewNotifyingTextView is the new NSTextView if it exists.

Using Formatters

Cocoa's text system is very powerful, but also very complex. Many classes cooperate to make a single instance of
NSTextView operate. Almost all text drawn by Cocoa applications is drawn by NSTextView instances, but it
does not make sense to have separate text views for every label, button, or text field that draws text. Instead, each
window has an instance of NSTextView that is shared by most of the other objects that need to draw text. The
shared NSTextView instance is called the window's field editor. The field editor is described in "The Field Editor"
section of Chapter 10.

The objects that use the field editor are usually subclasses of NSControl and NSCell. For example,
NSTextField is a subclass of NSControl, and NSTextField uses an instance of NSTextFieldCell in
its implementation. NSTextFieldCell is a subclass of NSActionCell, which is in turn a subclass of
NSCell.

Controls such as NSTextField, and the corresponding NSCell instance, not only draw text with the aid of the
field editor, they need to accept textual user input as well. Controls and cells optionally use NSFormatter
instances to assist with the display of textual information and to control or validate user input. NSFormatters are
described in the "Validation and Formatters" section of Chapter 10. The remainder of this section is used to explain
the interaction between NSFormatter subclasses and the field editor or another NSTextView.

Formatters convert objects such as NSCalendarDate or NSNumber into instances of NSString or

NSAttributedString, which are then displayed by the field editor. Formatters also accept characters input to
the field editor and convert the characters into other objects.

To convert objects into strings for display, NSFormatter subclasses must implement the -
stringForObjectValue: method. The optional -attributedStringForObjectValue: method can
also be implemented. Both methods accept an arbitrary object argument. They return an NSString and an
NSAttribtedString, respectively. If -attributedStringForObjectValue: is implemented by a
formatter, -stringForObjectValue: will never be called unless -
attributedStringForObjectValue: calls it. Controls and cells prefer attributed strings.

To convert strings into objects, NSFormatter subclasses must implement -getObjectValue:forString:

errorDescription:. The first argument is a pointer to a pointer to an object. This method returns an object by
reference in the first argument. The second argument is the string to convert. The third argument is a pointer to a
pointer to an NSString object. If an error is detected during conversion, a message describing the error can be
returned by reference in the third argument.

The following simple NSFormatter subclass formats 10-digit phone numbers with the standard USA notation.
For example, (800) 555-1234 is a correctly formatted phone number. The first three digits are an area code.
The next three digits are a prefix. The last four digits complete the phone number. Including the parentheses, a
space character, and the dash character between the prefix and the rest of the number, the formatted phone number
requires 14 characters.

Create a new Cocoa Application Project Builder project. A good name for the new project is
MYPhoneNumberFormatterExample. Add the following code for MYPhoneNumberFormatter.h and
MYPhoneNumberFormatter.m to the project.

File MYPhoneNumberFormatter.h:

/* MYPhoneNumberFormatter */

#import <Cocoa/Cocoa.h>

@interface MYPhoneNumberFormatter : NSFormatter

{
}
@end

File MYPhoneNumberFormatter.m:

#import "MYPhoneNumberFormatter.h"

@implementation MYPhoneNumberFormatter
/*" Instances of this class format 10 digit numbers using standard USA phone
number notation: (XXX) XXX-XXXX. "*/

/*" The number of characters needed to display a formatted 10 digit phone

number "*/
static const int MYNumberOfCharactersInFormattedPhoneNumber = 14;

- (NSString *)stringForObjectValue:(id)obj
/*" Returns a string by converting obj into a string formatted with
standard
USA phone number notation.
"*/
{
NSString *result = @"( ) - "; // default result if obj is
invalid

if([obj respondsToSelector:@selector(longLongValue)])
{
// obj is able to provide a ten digit number to format
long long phoneNumber = [obj longLongValue];
long long areaCode = (phoneNumber / 10000000); // first 3 digits
long long prefix = (phoneNumber / 10000) % 1000; // (digits 5-7)
long long fourDigitNumber = phoneNumber % 10000; // last 4 digits
result = [NSString stringWithFormat:@"(%03d) %03d-%04d", (int)areaCode,
(int)prefix, (int)fourDigitNumber];
}

return result;
}

- (BOOL)getObjectValue:(id *)obj forString:(NSString *)string

errorDescription:(NSString **)error
/*" Returns by reference in obj an NSNumber derived from string. The
NSNumber stores a ten digit number using the long long type. If
any errors are detected, this method returns NO and also returns
an error message by reference in error. If an error is detected,
the value returned by reference in obj is undefined. If no errors
are detected, this method returns YES. "*/
{
long long phoneNumber = 0; // the 10 digit phone number
long long areaCode = 0; // the 3 digit area code
long long prefix = 0; // the 3 digit prefix
long long fourDigitNumber = 0; // the 4 digit number
BOOL result = NO; // default result
 if(MYNumberOfCharactersInFormattedPhoneNumber == [string length])
{
// string has the proper length for a formatted phone number

// 01234567890123 character position in formatted phone number string

// (XXX) XXX-XXXX
areaCode = [[string substringWithRange:NSMakeRange(1, 3)] intValue];
prefix = [[string substringWithRange:NSMakeRange(6, 3)] intValue];
fourDigitNumber = [[string substringWithRange:NSMakeRange(10, 4)]
intValue];
}

// combine area code, prefix, and 4 digit number to create a 10 digit

number
phoneNumber = (areaCode * 10000000) + (prefix * 10000) + fourDigitNumber;
if(phoneNumber >= 1000000000)
{
// the 10 digit phone number must be greater than or equal to 1000000000
// because the first digit in the area code can not be 0
if(NULL != obj)
{
*obj = [NSNumber numberWithLongLong:phoneNumber]; // return NSNumber
}
result = YES;
}
else if(NULL != error)
{
// There were too few digits in the phone number
*error = @"Too few digits in phone number"; // return error by reference
}

return result;
}

@end

The code so far implements a minimal NSFormatter subclass. Both the -stringForObjectValue: and -
getObjectValue:forString:errorDescription: methods are implemented. Compile the project to
make sure there are no errors.

Double-click the MainMenu.nib file in the Resources folder of the new project. Interface Builder will start and
display the user interface for this example. Drag the MYPhoneNumberFormatter.h file into Interface Builder's
window titled MainMenu.nib. The MainMenu.nib window displays its Classes tab containing a class browser
that shows the MYPhoneNumberFormatter class selected. Ctrl-click the selected
MYPhoneNumberFormatter class in the class browser to display Interface Builder's contextual menu. Click
Instantiate MYPhoneNumberFormatter in the context menu. After an instance of
MYPhoneNumberFormatter is created in Interface Builder, the MainMenu.nib window switches to its
Instances tab, which now contains the new MYPhoneNumberFormatter instance.

Next, drag two editable NSTextField objects from Interface Builder's Cocoa-Views palette into the window
titled Window. The editable NSTextField object on the Cocoa-Views palette is shown in Figure 10.9 within the
"Text Fields" section of Chapter 10. Resize the text fields so that they are wide enough to display 10 digits plus the
formatting characters. Ctrl-drag a connection line from one of the text fields in the window titled Window to the
instance of MYPhoneNumberFormatter in the MainMenu.nib window. Interface Builder's Connections
inspector is automatically shown, if it is not already visible. In the Connections inspector, select the text field's
formatter outlet and click the Connect button.

Save the user interface using Interface Builder's File, Save menu item, and then quit Interface Builder.

Build and run the new application in Project Builder. When the user interface for the new application appears, both
text fields are shown. The text field that does not have a formatter accepts any characters typed into it, but only a
very precise set of characters are accepted by the text field that has the connection to the
MYPhoneNumberFormatter instance. The formatted text field does not allow editing to end until a number
with the correct formatting such as (555) 555-5555 is provided. The single-space character after the )
character is required and there cannot be any spaces or other characters after the last digit. Experiment by entering
different values into the two text fields to see the range of input allowed.

The new formatter is doing its job, but it does not provide a very nice experience for users. Currently, users must
enter the digits using the specific notation; no variations are tolerated. In addition, the formatter is sloppy. If any
three-digit number greater than 100 is typed into the area-code portion of the phone number, the rest of the input
can be random characters as long as the total length of the input is exactly 14 characters.

The next step is to improve the user experience by modifying the formatter. Quit the running example application
and return to Project Builder.

If a text field has a formatter, each time the text in the text field changes because of user input, the formatter's -
isPartialStringValid:newEditingString:errorDescription: method is called. The first
argument is a string containing the characters in the text field. The second argument is a pointer to a pointer to an
NSString instance. The second argument is used to return a replacement for the contents of the text field. The last
argument is a pointer to a pointer to a string used to return an error message by reference. If -
isPartialStringValid:newEditingString:errorDescription: returns NO, the contents of the
text field being formatted are replaced with the string return by reference in the second argument. If the method
returns YES, the text field's content is left alone and continues to show the string passed as the first argument just
the way the user entered it.

Add the following implementation of -isPartialStringValid:newEditingString:

errorDescription: to the implementation of MYPhoneNumberFormatter. Each time a character is
entered into the text field, the contents of the field are replaced with the new string returned by this method. The
basic algorithm is to find each decimal digit typed by the user and insert the characters into a string that already has
the correct formatting. Any characters typed by the user that are not decimal digits are ignored.

#define _MYNUM_VALID_DIGIT_POSITIONS (10)

/*" Array lists valid position for digits in a formatted phone number "*/
static int _MYValidPositionsInPhoneNumber[_MYNUM_VALID_DIGIT_POSITIONS] =
{ 1, 2, 3, 6, 7, 8, 10, 11, 12, 13 };

- (BOOL)isPartialStringValid:(NSString *)partial
newEditingString:(NSString **)newString
errorDescription:(NSString **)errorString
/*" This method is implemented to place digits within a formatted phone
number
string as the digits are typed. This method always returns NO and always
returns a formatted phone number string by reference in newString. This
method does no set the value of errorString.
"*/
{
BOOL result = NO;
int lengthOfPartial = [partial length];
 NSMutableString *formattedPartialString = [NSMutableString
stringWithString:@"( ) - "];
NSCharacterSet *digits = [NSCharacterSet decimalDigitCharacterSet];
int positionInPartial = 0;
int currentDigit = 0;

// while we have not run out of digits in partial string, place the digits
// in order in the valid positions within formattedPartialString
while(positionInPartial < lengthOfPartial &&
currentDigit < _MYNUM_VALID_DIGIT_POSITIONS)
{
NSRange remainingRangeInPartial = NSMakeRange(positionInPartial,
lengthOfPartial - positionInPartial);
NSRange rangeOfNextDigit = [partial rangeOfCharacterFromSet:digits
options:NSLiteralSearch range:remainingRangeInPartial];

if(rangeOfNextDigit.location != NSNotFound)
{
[formattedPartialString replaceCharactersInRange:
NSMakeRange(_MYValidPositionsInPhoneNumber[currentDigit], 1)
withString:[partial substringWithRange:rangeOfNextDigit]];
positionInPartial = rangeOfNextDigit.location + rangeOfNextDigit.
length;
currentDigit++;
}
else
{
// terminate the loop because there are no more digits
positionInPartial = lengthOfPartial;
}
}

*newString = formattedPartialString;

return result;
}

Build and run the example application. Experiment entering values into the formatted text field. One shortcoming of
this approach is that the text insertion cursor moves to the end of the text field after each character is entered. The
insertion cursor can be moved to any location in the field with the mouse or arrow keys, but it cannot be moved
more than one position with the Backspace or Delete keys. This is an unfortunate side effect of always returning a
full-length formatted string from -isPartialStringValid:newEditingString:
errorDescription:. A better behavior would be to have the formatter move the insertion cursor to the
position just after the last digit entered. Unfortunately, there is no reliable way to do that from within a formatter's -
isPartialStringValid:newEditingString:errorDescription: implementation.

The NSControl class has a delegate method that can be implemented to provide the desired text-insertion cursor
behavior. If the -control:didFailToValidatePartialString:errorDescription: method is
implemented by the control's delegate, the method is called whenever the formatter returns NO from -
isPartialStringValid:newEditingString:errorDescription:. Because
MYPhoneNumberFormatter always returns NO from -isPartialStringValid:newEditingString:
errorDescription:, the control's delegate can implement -control:
didFailToValidatePartialString:errorDescription: to position the insertion cursor just after the
last digit.
Code similar to the following implementation of -control:didFailToValidatePartialString:
errorDescription: can be implemented in a text field's delegate to set the insertion cursor's position.
NSControl's -controlTextDidChange: delegate method is another place where the insertion cursor can be
positioned.

- (void)control:(NSControl *)control
didFailToValidatePartialString:(NSString *)string
errorDescription:(NSString *)error
/*" Move the insertion cursor of the field editor used to edit control to the
location just past the last digit in string "*/
{
if(0 < [string length])
{
id fieldEditor = [[control window] fieldEditor:NO
forObject:control];
NSCharacterSet *digits = [NSCharacterSet decimalDigitCharacterSet];
NSRange rangeOfLastDigit = [string rangeOfCharacterFromSet:digits
options:NSLiteralSearch|NSBackwardsSearch];

if(NSNotFound != rangeOfLastDigit.location)
{
[fieldEditor setSelectedRange:NSMakeRange(
rangeOfLastDigit.location+1, 0)];
}
}
}

One last modification to the MYPhoneNumberFormatter class enables the display of attributes in the formatted
strings. Add the following method to the implementation of MYPhoneNumberFormatter in
MYPhoneNumberFormatter.h.

- (NSAttributedString *)attributedStringForObjectValue:(id)obj
withDefaultAttributes:(NSDictionary *)attrs
/*" Calls [self stringForObjectValue:obj] and returns an attributed string
containing a formatted string and color attributes. "*/
{
NSMutableAttributedString *result = [[[NSMutableAttributedString alloc]
initWithString:[self stringForObjectValue:obj] attributes:attrs]
autorelease];

if(MYNumberOfCharactersInFormattedPhoneNumber == [result length])

{
// The string to format has the correct length
// Add color attributes to the various components of the formatted phone
// number
NSColor *gray = [NSColor grayColor];
NSColor *black = [NSColor blackColor];

[result addAttribute:NSForegroundColorAttributeName value:gray range:

NSMakeRange(0, 1)];
[result addAttribute:NSForegroundColorAttributeName value:black range:
NSMakeRange(1, 3)];
[result addAttribute:NSForegroundColorAttributeName value:gray range:
NSMakeRange(4, 2)];
[result addAttribute:NSForegroundColorAttributeName value:black range:
 NSMakeRange(6, 3)];
[result addAttribute:NSForegroundColorAttributeName value:gray range:
NSMakeRange(9, 1)];
[result addAttribute:NSForegroundColorAttributeName value:black range:
NSMakeRange(10, 4)];
}

return result;
}

Build and run the example to see the effects of the new method. Controls such as NSTextField call the -
attributedStringForObjectValue: method in preference to -stringForObjectValue: if the
attributed string variant is available.

For more examples, an excellent tutorial that explains how to create NSFormatter subclasses is available at http://
www.stepwise.com/Articles/VermontRecipes/recipe05/recipe05.html.
Book: Cocoa® Programming
Section: Chapter 11. The Cocoa Text System

Summary

Few Cocoa applications need the full range of features and customization options that
Cocoa's text system provides. The objects on Interface Builder palettes are extremely
powerful, even in their default configuration; however, enough information was presented
in this chapter to enable very sophisticated use of Cocoa's text system. The MVC
architecture used to implement the text system makes it possible to customize parts of the
system without affecting other parts. The examples provided show the most common ways
the text classes are used, and the hooks needed to customize the text system.

The next chapter, "Custom Views and Graphics Part I," describes how to create custom
subclasses of NSView and implement custom drawing features. All Cocoa's visible user
interface objects are direct or indirect subclasses of NSView including the NSText and
NSTextView classes explained in this chapter. NSView provides the common features
needed to implement user interface elements as simple as NSBox or as complex as
NSTextView.
Book: Cocoa® Programming
Section: Part II: The Cocoa Frameworks

Chapter 12. Custom Views and Graphics Part I

IN THIS CHAPTER

● The Quartz Graphics Model

● Quartz Graphics Via the Application Kit
● Using the NSBezierPath Class
● Modifying Drawing

The Application Kit contains classes that provide the user interface elements common to
most applications. However, some applications require the use of custom interface
elements and graphics that none of the Application Kit classes provide. For example, the
Application Kit doesn't contain any classes for plotting graphs. Therefore, it is necessary to
subclass NSView, an Application Kit class, to create such graphics.

There are several ways to draw when implementing a subclass of NSView. The first and
most common way is to use Quartz 2D graphics. Another is to use Cocoa's support for
OpenGL 3D graphics. Finally, the Application Kit provides limited support for QuickDraw
graphics from prior Macintosh operating systems.

Quartz 2D graphics are accessed via Application Kit classes or Core Graphics functions. In
this chapter, only the Application Kit classes are discussed in depth. There are, however, a
few things that can be done in Core Graphics that can't be done with Cocoa's Application
Kit, such as capturing the screen and full-screen drawing. Using the Application Kit is as
efficient as using Core Graphics. There is little gained by using Core Graphics directly,
whereas much is lost when leaving behind the object-oriented features that Cocoa provides.
For example, the NSView class provides all the basic logic needed to manage the Quartz
drawing context so all the developer needs to add in a subclass is the minimal drawing
code.

OpenGL 3D graphics are accessed by subclassing the NSOpenGLView class.

NSOpenGLView provides OpenGL context management. This chapter only covers 2D
graphics. 3D graphics and OpenGL are described briefly in Chapter 21.
Book: Cocoa® Programming
Section: Chapter 12. Custom Views and Graphics Part I

The Quartz Graphics Model

To write effective code for 2D drawing in Cocoa, it is necessary to understand the graphics
model that underlies the Quartz 2D graphics layer in Mac OS X. It is beyond the scope of
this book to give every tiny detail of the graphics model, but this section provides, in the
most general terms, a bird's eye view of what is available and the capabilities of those
offerings. Most of the rest of this chapter and the two that follow flesh out the facilities
described in this section.

The Quartz graphics model is fundamentally based on Adobe's PDF standard, which in turn
takes most of its ideas from the PostScript graphics language. The graphics model is
complex, and this book can only touch on the most basic concepts. For more detailed
information, any good book on PostScript or PDF will prove invaluable.

Quartz graphics are designed to be both device and resolution independent. Quartz also
allows for basic color management. It maintains a current drawing state that consists of a
collection of parameters that affect future drawing. Similar to PostScript and PDF, Quartz
uses transformation matrices to alter the base coordinate system for effects such as
translation, rotation, scaling, and more. To actually draw something, a path or outline must
be defined, and then either stroked or filled. All these features and terms are defined in
more depth throughout this chapter.

Resolution Independence

To be resolution independent, the basic units of measurement used when specifying

coordinates are points, as understood by the printing industry. On a high-resolution device
a point still specifies the same distance as on a low-resolution device. As a result, the
graphics drawn will look the same size to the user when they move from one device to
another. The higher the resolution, the more pixels are painted when drawing a given
geometrical object.

The point unit is defined as 1/72 of an inch. Thus, on a 1440 dpi printer, one point would
be 20 dots long. A square one-point high and one-point wide covers an area of 400 dots
total. Apple assumes that all monitors have a resolution of 72 pixels per inch. In other
words, Apple assumes that one pixel on a monitor is one point in size (1/72 of an inch by
1/72 of an inch). Thus, when drawing to the screen, a point could actually be larger or
smaller than a true point that is supposed to be 1/72 inch. The result is that if you specify a
10x10-point square, a 10x10-pixel rectangle, painting 100 pixels total, will be drawn on the
screen. This one-to-one mapping is a direct result of Quartz's assumption that one screen
pixel equals one printer's point. It is dangerous to assume that this will always be the case,
however. Apple could, at some future date, choose to calibrate monitors' dpi ratings. This
might make sense to do as monitors increase in resolution.
Device Independence

To be device independent, it is important that when you specify a color it looks the same
on all devices. Quartz uses ColorSync to achieve this. You can bypass this and specify
device-dependent colors, but usually that is not a good idea. Any serious graphics should
use calibrated colors. Because Quartz itself uses ColorSync, you, as a developer, don't have
to do anything special to support it.

Transparency

One other aspect of color permeates Quartz: transparency. Usually the term alpha or alpha
channel is used to refer to transparency. Both bitmap images and the colors used to render
paths can have varying levels of transparency. Generally, alpha of zero means completely
transparent. Depending on context, alpha might be an integer in the range of 0-255 or,
more commonly, a floating-point value from 0.0-1.0. The highest number in the range (1.0
or 255) denotes fully opaque. In the present implementation of Quartz, transparency is
supported much better on the screen than it is on the printer or when printing to PDF. The
PDF standard, however, is evolving to support transparency better. According to Apple,
improved support for transparency when printing will eventually make its way into Quartz.

Paths

Paths support basic drawing. A path is an outline of a graphical shape. There are several
commands to add line segments, arcs, and more to a given path. While under construction,
a path is completely invisible. When the path is fully defined, the stroke or fill commands
can be used. Stroking a path paints the outline that the path defines. Filling the same path
creates a solid, filled shape instead.

The easiest way to think of a path being created is to envision an inkless pen tracing out the
path, following given commands. For lines and curves, the commands use the pen's current
position as an implied starting point. Note that the pen can be lifted by moving to a new
point instead of tracing out a line to the point. When the pen has traced out the path, a pen
with ink in it can actually follow the predefined path to put something visible onto the
page. Remember, if stroke or fill isn't used after defining a path, nothing will be shown on
your drawing canvas.

In Cocoa, there are a few convenience functions for laying out and drawing or filling
rectangular paths. There is also the NSBezierPath class that is used for most path
creation and manipulation.

Transforms

It is often convenient to define a basic path, and then repeat it multiple times, perhaps at
different locations, sizes, or rotations. This can be accomplished with the current
transformation matrix (CTM). A point can be thought of as a two dimensional vector,
allowing it to be multiplied by a matrix. In doing so, it undergoes a transformation into a
new vector. Depending on the contents of the matrix, the new vector could be at a different
location (such as translated or moved), a different size (scaled), or rotated. Some matrices
can cause shearing and other unusual effects as well.

With Quartz, you can specify an explicit matrix, or you can add a translation, rotation, or
scaling to the current matrix. For most developers, the latter is the easiest way to work with
the CTM. However, developers experienced with the CTM might choose to create and set
their own matrices explicitly.

One of the special properties of transformation matrices is that multiple matrices can be
multiplied together to create a new matrix that performs all the transformations that were
specified by the original matrices. For example, if there are three matrices with the first one
doing a translation, another one doing rotation, and the last one for scaling, by multiplying
the three together a single matrix can be created that performs all three operations. This
process of multiplying matrices together is known as concatenation.

Cocoa's NSAffineTransform class, described in Chapter 13, "Custom Views and

Graphics Part II," helps manage the CTM and provides a simple way to manipulate these
matrices. It can be given raw matrices or asked to concatenate scaling, rotation, or
translation elements to the matrix it represents.

Bitmapped Images

When drawing, sometimes it is necessary to draw bitmapped graphics, as opposed to paths.

Quartz offers several facilities for compositing bitmaps. Compositing combines an image
with the graphics that are already on the drawing canvas. There are 13 different
compositing operators available. In compositing terminology, the source is the image that
is being composited, and the destination is the area of the canvas being drawn.

The simplest compositing operation is clear, which zeroes out the drawing area. Another
simple operation, copy, copies the bitmap into the drawing area, completely replacing
whatever was underneath. One of the most common operations is source over, which
places the opaque parts of the source image on top of the destination, but enables the
destination to show through the transparent parts of the source image. Many other modes
are also available, and will be described more fully later.

The NSImage class described in Chapter 14, "Custom Views and Graphics Part III," can
be used for managing and compositing images. NSImage instances are usually composed
of one or more other objects called image representations. Various different NSImageRep
subclasses are used in conjunction with NSImage to support different image formats.
Graphics Contexts

Quartz uses a graphics context to control what is drawn. The graphics context stores
attributes such as the current line width, the current line end cap style, the current drawing
color, the current transformation matrix, and the current path. All graphics commands are
given to the context, and the context can modify them according to its settings.

There can also be multiple graphics contexts. Typically, each window has its own context.
It is possible for a view object within a window to have its own context. Some contexts
never draw to the screen. A context could be writing graphics commands to a file, a printer,
or even drawing into an offscreen image buffer. Usually, a developer doesn't need to worry
about what the current graphics context is doing. Cocoa's NSGraphicsContext class
described in Chapter 13, is used to query and modify contexts.

Text Rendering

The final big function performed by Quartz is to draw text. Quartz doesn't work entirely
alone because text is such a complex function. It uses Apple's ATSUI (an advanced text
rendering technology) to do most of the hard work. Working with text at this level is very
complex, so Cocoa offers a whole suite of classes for manipulating and displaying text. At
the lowest level there are NSString and NSAttributedString. The Application Kit
adds some categories to these objects for very simple text rendering. Drawing text with
strings is covered in Chapter 14. The NSText object and its associated helper objects
manage more complex rendering. This is complex enough that the text object is covered in
its own chapter. For more information, see Chapter 11, "Text Views."
Book: Cocoa® Programming
Section: Chapter 12. Custom Views and Graphics Part I

Quartz Graphics Via the Application Kit

The Application Kit provides several classes to assist in using Quartz to draw 2D graphics. It also
provides functions that can be used to do some basic, common drawing tasks, such as rapidly
drawing rectangles.

NOTE

Many Application Kit classes support Quartz drawing. For managing and drawing
bitmaps, there is NSImage and several NSImageRep subclasses. To draw lines,
rectangles, arcs, curves, polygons, and more, there is NSBezierPath. To adjust the
parameters of the current graphics context, use the NSGraphicsContext and
NSAffineTransform classes. To draw simple text, use the methods added to
NSString and NSAttributedString by the Application Kit in the
NSStringDrawing categories. If more complex or more efficient text drawing is
required, an NSText object should be used.

New Types and Functions

Before continuing, a few types and structures that the Foundation Kit defines for graphics must be
understood. There are several C functions and macros available for manipulating these types and
structures.

Points, Sizes, and Rectangles

The NSPoint type stores the x and y coordinates of two-dimensional points as floating-point
values. The NSPoint type is a C structure. Its x and y members can be accessed directly. For
example:

NSPoint myPoint;
NSPoint *pointPointer;
myPoint.x = 10.0;
myPoint.y = 25.0;
pointPointer = &myPoint;
pointPointer->x = 6.0;

A similar structure, NSSize, also has two floating-point members. NSSize stores the size of a
two dimensional area. Its two members are called height and width. One important thing to
remember about the NSSize type is that its members should never be negative. The compiler
won't automatically check this, so a developer must be careful with any code that manipulates
NSSize structures. Again, the members are accessed directly. For example:

NSPoint mySize;
NSPoint *sizePointer;
mySize.width = 50.0;
mySize.height = 70.5;
sizePointer = &mySize;
sizePointer->width = 100.0;

A third frequently used type is NSRect. Cocoa defines rectangles as having an origin and a size.
The origin member is an NSPoint structure and specifies the rectangle's lower-left corner. The
size member is an NSSize structure, giving the rectangle's width and height. An NSRect is
therefore a structure made up of two structures. The members are still accessed directly:

NSRect myRect;
NSRect *rectPointer;
myRect.origin.x = 10.0;
myRect.origin.y = 5.5;
myRect.size.width = 40.0;
myRect.size.height = 20.55;
rectPointer = &myRect;
rectPointer->origin.x = 21.43;

Each of these three types also has two companion types, one for a pointer to the structure, and the
other for a pointer to an array of structures. These types are NSPointPointer,
NSPointArray, NSSizePointer, NSSizeArray, NSRectPointer, and NSRectArray.
The following two variable declarations are equivalent:

NSRect *rectPointer;
NSRectPointer rectPointer;

And so on for the other five companion types.

There is one final type, NSRectEdge, which is often used to specify a particular edge of a
rectangle. NSRectEdge is an enumerated type and can have one of the following four values:
NSMinXEdge, NSMinYEdge, NSMaxXEdge, and NSMaxYEdge.

Point, Size and Rectangle Constants, Creation, and Accessors

To help manipulate the point, size, and rectangle structures, Cocoa defines some constants and
inline utility functions. Because these functions are inlined, don't be afraid to use them liberally.
They are well tested and will continue to work even if the Cocoa definitions of these structures
change in the future.

There is a constant zero version of each structure that has each member set to zero. They are named
NSZeroPoint, NSZeroSize, and NSZeroRect. These can be handy for clearing or resetting
the values of a point, size, or rectangle.

In many cases, a point, line, or rectangle structure needs to be provided to Cocoa and yet the
structure in question is not readily available. Perhaps the individual values are available as separate
variables, or need to be calculated. To make it easy to create a structure for Cocoa to use, a creation
function can be used that corresponds to the structure needed: NSMakePoint(), NSMakeSize
(), or NSMakeRect().

The two arguments to NSMakePoint() are the x and y values, in that order. NSMakeSize()
requires the two arguments width and height. To call NSMakeRect(), x, y, width, and height
must be specified. For example, this code creates an NSRect structure and passes it as an
argument to a hypothetical RectFunction() that accepts a single rectangle as its argument:

float x = 5.5;
float y = 10.0;
float w = x * 2.0;
RectFunction(NSMakeRect(x, y, w, y + 5.5));

Several other inline functions can be used to access special values or to obtain commonly
calculated values from NSRect structures. Table 12.1 describes these functions.

Table 12.1. Inline Rectangle Functions

Function Description

NSMinX(NSRect aRect) Returns the leftmost x coordinate in the rectangle (aRect.

origin.x)

NSMinY(NSRect aRect) Returns the lowest y coordinate in the rectangle (aRect.

origin.y)

NSMidX(NSRect aRect) Returns the center x coordinate in aRect

NSMidY(NSRect aRect) Returns the center y coordinate aRect

NSMaxX(NSRect aRect) Returns the right most x coordinate in the rectangle (aRect.
origin.x + aRect.size.width)
NSMaxY(NSRect aRect) Returns the largest y coordinate in the rectangle (aRect.
origin.y + aRect.size.height)

NSWidth(NSRect aRect) Returns the width of the rectangle (aRect.size.width)

NSHeight(NSRect aRect) Returns the height of the rectangle (aRect.size.height)

As an example, calculating the center point of a rectangle is accomplished like this:

NSPoint rectCenter = NSMakePoint(NSMidX(theRect), NSMidY

(theRect));

Rectangle Tests

Several other functions can also be used to test the values of these structures in various ways. For
example, NSEqualPoints(), NSEqualSizes(), and NSEqualRects() each take two
arguments and return a Boolean (BOOL type) YES or NO. The arguments should both be of the
same type, NSPoint, NSSize, or NSRect. Besides simply testing for equality, a single NSRect
can be tested to see if it covers any actual area with NSIsEmptyRect(). A rectangle with zero
width and/or zero height is considered to be empty.

There are also a few slightly more complex tests. To see if a point is inside a given rectangle, use
NSPointInRect(), providing an NSPoint and an NSRect as arguments. To see if a rectangle
is completely contained within another rectangle, use NSContainsRect() with two NSRect
arguments. This function returns true if the first rectangle completely encloses the second
rectangle. If the second rectangle is empty or touches an edge of the first rectangle, it returns NO.
To see if two rectangles share any area between them, use NSIntersectsRect(), again with
two NSRect arguments. If either rectangle is empty, this function returns NO. All these functions
assume that the coordinate system has not been scaled, rotated, or translated. In such cases, some of
the functions might not work exactly as expected.

A final test function, related to NSPointInRect(), is NSMouseInRect(). This function

requires three arguments: an NSPoint, an NSRect, and a BOOL. The first two arguments work
exactly like NSPointInRect(). The third argument, the BOOL, specifies whether or not the
coordinate system has been flipped so that the origin is at the upper left. Use NSMouseInRect()
to test the location of the cursor's hot spot.

NOTE

In a flipped coordinate system, the positive Y axis runs from top to bottom instead of
the normal Quartz orientation that places the origin at the lower left with increasing Y
values moving up the screen. Flipped coordinate systems are seen most commonly in
 text based views.

Rectangle Manipulation

There are six functions that produce new rectangles based on manipulation of existing rectangles in
various ways. The first is NSIntegralRect(), which returns a new rectangle that has had its
origin and size massaged so that each value is an integer. If the rectangle doesn't already have
integral bounds, it expands slightly. If it has a zero or negative size, NSZeroRect is returned.

The next function is NSUnionRect(). This function takes two NSRect arguments and returns a
new NSRect that completely encloses both of them. Note that if the two rectangles don't intersect,
this would return a rectangle that is much larger than either of the original two rectangles. If one of
the input rectangles has zero or negative values in their size member, the other rectangle is returned
verbatim. If both input rectangles have invalid sizes, then NSZeroRect is returned.

To find the rectangular area of overlap between two rectangles, use NSIntersectionRect(),
which takes two NSRect values. If the overlap is a point, a line, or there is no overlap at all,
NSZeroRect is returned. Otherwise, a rectangle defining the area of overlap is returned.

To take a rectangle and create a smaller rectangle centered inside the original rectangle, use
NSInsetRect(). This function takes the original rectangle and two floating-point values as
arguments. The first floating-point number is the amount to move the left and right edges of the
rectangle inward. The second number is the distance to move the top and bottom edges. Because
both pairs of edges move inward by the same amount, the new rectangle that is returned is centered
inside the original rectangle.

The NSOffsetRect() function moves a rectangle by a specified amount. For arguments, pass
the original rectangle, a floating-point X offset and a floating-point Y offset. The rectangle's origin
is moved by the specified amount and the size remains unchanged.

The final rectangle manipulation function is the most complex. NSDivideRect() is used to take
a rectangle and split it into two new rectangles. It works by taking a slice off of an edge of the
rectangle, leaving two new rectangles. The first is the slice itself, the second is what remains of the
original rectangle after slicing. (Note that the original NSRect is left unaffected.) The parameters
are input NSRect; a pointer to an NSRect where the slice is put; a pointer to the NSRect in
which the remainder rectangle is placed; a floating-point number to specify how much of a slice to
take; and an NSRectEdge to specify which side of the rectangle should be sliced.

For example, suppose we want to take a slice off the left edge of a rectangle that has a width of
10.0 points. The code would look like this:

NSRect startRect = NSMakeRect(8.0, 8.0, 200.0, 100.0);

NSRect slice, remainder;
NSDivideRect(startRect, &slice, &remainder, 10.0, NSMinXEdge);
After the previous code, startRect's values have not changed, but slice contains a rectangle
made up of the slice we took off the left edge. The remainder variable contains the original
rectangle minus the area sliced off.

Storing Points, Sizes, and Rectangles in the Defaults Database

It is useful to be able to store points, sizes, and rectangles in the user defaults (preferences)
database. However, there is no explicit property list type for these values. To make it easier to store
any of these values in the database, there are six functions that can convert a point, size, or
rectangle into an NSString or vice versa.

To convert an NSPoint, NSSize, or NSRect into a string, use NSStringFromPoint(),

NSStringFromSize(), or NSStringFromRect(), respectively. Each takes a single
argument of the expected type, and returns a pointer to an autoreleased NSString instance.

To go the other direction, use NSPointFromString(), NSSizeFromString(), or

NSRectFromString(). They each take a pointer to a single NSString instance and return an
NSPoint, NSSize, or NSRect, respectively.

In general, these functions are used together. The parsing functions are quite specific about how
they expect the input string to be laid out, and the string-creation routines are designed to produce
the exact output that the parsers want to see.

Subclassing NSView

To do any custom drawing in Cocoa, a subclass of NSView must be created. The easiest way to
learn how to do this is by working through an example. The simplest possible path that can be
drawn is a line segment so that is the example shown here.

The first step to drawing is to create a subclass of NSView and override the inherited -
drawRect: method. This method is called whenever the Application Kit determines that the view
needs to be redrawn. The developer should not call this method. Instead, to redraw the view, call
the -setNeedsDisplay: method. This method can be used to tell the Application Kit that the
view needs to be redisplayed. The Application Kit automatically takes care of redrawing the view
at an appropriate time as well as setting everything up so that the graphics drawn are output to the
correct place.

The most basic skeleton code possible for a view subclass that draws looks like this:

File MYLinesView.h:

#import <Cocoa/Cocoa.h>

@interface MYLinesView : NSView

{
}

- (void)drawRect:(NSRect)aRect;

@end

File MYLinesView.m :

#import "MYLinesView.h"

@implementation MYLinesView

- (void)drawRect:(NSRect)aRect
{
[[NSColor blackColor] set];
NSRectFill([self bounds]);
}

@end

Before going further, this example code should be integrated into a project to more easily work
with it. Create a new Cocoa application project called Lines in Project Builder, and add
MYLinesView.h and MYLInesView.m to the new project's Classes folder as shown in Figure
12.1.

Figure 12.1. A new Project Builder project called Lines contains the files MYLinesView.h
and MYLinesView.m in the Classes folder.
Next, open up MainMenu.nib in the new project's Resources folder. When Interface Builder has
launched, select the Classes tab in Interface Builder's MainMenu.nib window and have Interface
Builder read the MYLinesView.h file. Use Read Files from Interface Builder's Classes menu, or
just drag the MYLinesView.h file into the MainMenu.nib window. Now, drag a Custom
View object from Interface Builder's palette and drop it onto the window being edited. The Custom
View object looks like a gray rectangle with the words CustomView on it. It can be found at the
upper-left corner of the Cocoa-Containers palette. This is the palette that also contains the tab view
and box. Figure 12.2 shows a CustomView object being dragged from Interface Builder's palette.

Figure 12.2. A CustomView object is dragged from Interface Builder's palette to a window.
When you have dragged a CustomView object onto your window, select the custom view and open
the Show Info window (Cmd-1). With a custom view selected, the Show Info window contains a
list of all the NSView subclasses known to Interface Builder. Interface Builder has already read the
files defining MYLinesView, and the MYLinesView class appears at the top of the list as shown
in Figure 12.3.

Figure 12.3. Because Interface Builder has already read the files defining MYLinesView, the
MYLinesView class appears in the list.
Select MYLinesView so that the custom view knows what class it should be. Figure 12.4 shows
the custom view configured to be an instance of MYLinesView and filling the entire content area
of a window.

Figure 12.4. The custom view is configured to be an instance of MYLinesView and fills the
entire content area of a window.
Use the Size mode of Interface Builder's Show Info window to configure the MYLinesView
instance to fill all available space when resized. Figure 12.5 shows the MYLinesView instance
selected and the correctly configured resize springs in the Size mode of Interface Builder's Show
Info window.

Figure 12.5. The MYLinesView instance is selected and the resize springs in the Size mode of
Interface Builder's Show Info window are correctly configured.

Save the MainMenu.nib that you have edited in Interface Builder. At this point, the project can
be built and run. Select Build and Run in Project Builder's Build menu. After a brief delay while
the project is compiled, the new Lines application launches, and the window configured in
Interface Builder to contain an instance of MYLinesView is displayed onscreen, as shown in
Figure 12.6. The content of the window is black because the MYLinesView instance covers the
entire area, and MYLinesView has been implemented to fill its bounds with the color black. If the
window is resized, the MYLinesView instance grows and shrinks to fill all available space in the
window's content area.

Figure 12.6. The Lines application displays a window containing a MYLinesView instance
that draws a black-filled area.
The code that implements MYLinesView's -drawRect: method first sets the current color to
black, and then fills the view's bounds rectangle with the current color. See Chapter 17, "Color," for
more information about the NSColor class, and Chapter 8, "The Application Kit Framework
Overview," for the description of a view's bounds. The view's bounds are obtained by calling the -
bounds method inherited from the NSView class. The NSRectFill() function fills a rectangle
with the current color.

This example, simple as it is, provides the basic framework for subclassing a view to perform
custom drawing. It shows the bare minimum that must be done to draw custom graphics. The next
examples expand on this foundation. The next section will add the promised ability to draw line
segments.
Book: Cocoa® Programming
Section: Chapter 12. Custom Views and Graphics Part I

Using the NSBezierPath Class

To draw something more than just colored rectangles, a bitmapped image must be rendered, or a Quartz path must be defined and
subsequently stroked or filled. Because the sample application started in the previous section is supposed to draw random line
segments, the latter option makes the most sense. Cocoa uses the NSBezierPath class to define and manipulate Quartz paths.

There are two ways to create an NSBezierPath instance. If an object is just temporary, using the +bezierPath method returns
an autoreleased object with an empty path. Alternatively, for an object that will be kept around, use the standard Objective-C
+alloc/-init pair to create a brand new, empty object.

After a path object is created, a path must be constructed. This tells the object where drawing takes place, but doesn't actually do any
drawing. Next, the path is rendered. There are several options for how the path might be used in rendering. A single path object can
be rendered multiple times in different ways. The next two sections of this chapter cover defining, and then rendering paths.

To get a jump start before going into these operations in depth, the example program that draws random line segments will be
finished. When a developer has a feel for the basic work involved, the details of all the operations and options available can be
discussed.

The first step is to obtain a path. For that, simply use the +bezierPath class method. The next step is to define the path. Because
this path is a simple line segment, only two methods are needed. The starting point of the line is defined by using -moveToPoint:,
and the end point is defined by using -lineToPoint:. Imagine someone with a pencil in hand. We tell them to lift the pencil off
the paper and move to the start point, and then draw a line to the end point. However, there is still one step left, and that is to actually
render the path. Use the -stroke method to do that. Stroking a path treats it as an outline and paints all the pixels that lay on the
path as it is traced out, which is exactly what should be done to paint a series of line segments.

There is a little other code needed to set the drawing color to white, to create a loop to draw many line segments, and to randomly
choose the coordinates of the start and end points. This code and the path code is displayed in this code listing:

File MYLinesView.m :

#import "MYLinesView.h"

#define NUM_LINES 50

@implementation MYLinesView

- (void)drawRect:(NSRect)aRect
{
int i;
NSRect bds = [self bounds];
[[NSColor blackColor] set];
NSRectFill(bds);
[[NSColor whiteColor] set];
for (i=0; i<NUM_LINES; i++) {
NSPoint start = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSPoint end = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSBezierPath *line = [NSBezierPath bezierPath];
[line moveToPoint:start];
[line lineToPoint:end];
[line stroke];
}
}

@end

Try adding this code and running it. A window with a random collection of white line segments on a black background should be
seen. If the window is resized, triggering a redraw, new line segments are chosen and drawn. (Try it!) This example provides a
functional NSView subclass. The Paths example on www.cocoaprogramming.net contains the previous code as well as the code for
many of the examples found throughout this chapter. Build it, run it, and then select the Simple Lines algorithm from the control
panel, to see the code in action. It should look similar to Figure 12.7.

Figure 12.7. Select the Simple Lines algorithm from the control panel to see the described code in action.

The next section explores more of the details of constructing and rendering paths and NSBezierPath manipulation to gain
familiarity with path objects.

Constructing a Path

After a developer has a path object, a graphics path can be constructed by appending a series of operations. The path object starts out
empty, which means nothing would be drawn. Line, move, curve, and arc segments can be appended to the path to create an outline.
Every operation begins at the current point. To understand the significance of the current point, imagine a pencil on a paper. Where
the point rests at any given moment is the pencil. An operation, such as a line, only provides the destination of the pencil after the line
has been drawn. The destination point becomes the new current point. Therefore, the line operation means "draw a line from the
current point to this new point." Some operations require more than one point to be specified, but all implicity use the current point as
the starting point for that operations segment. Each of the basic available operations that might be appended to a path is described in
Table 12.2.

Table 12.2. Valid Path Operations

Operation Purpose

Move Moves the current point to a new location. ("Lift the pencil and move it to this new location.")

Line Adds a line from the current point to a new location.

Curve Adds a Bezier cubic spline from the current point to a new location. Two control points also need to be defined in
addition to the destination.

Arc Adds a circular arc and, if needed, a line segment.

Oval Adds a complete oval or circle. Developer provides the desired bounding rectangle.

Glyph Adds a glyph from a specified font at the current point.

Path Adds another path.

 Close Adds a line segment from the current point to the starting point.

Inside the actual path object itself, all the different operations are stored as simple move, line, curve, and close operations. All the
others can be built from these basic primitives.

Several of the operations in Table 12.2, namely move, line, and curve, also offer relative versions. The difference between absolute
and relative operations is in how the points provided to the operation should be interpreted. In the absolute version, the points give a
specific location on the drawing canvas. In the relative version, however, the points provided are interpreted to be relative to the
current point. So, if the current point is (15, 35) and a line is drawn to (50, 40), the new current point is the endpoint of the line at (50,
40). If instead, the relative version is used with the same two points, the endpoint would be at (65, 75) instead of (50, 40) because the
endpoint was specified relative to the starting point, which implies adding the new point's coordinates to those of the current point to
calculate the endpoint.

Each of the path construction functions has corresponding methods that can be used with an instance of NSBezierPath. The
following sections are a catalog of the methods and what they do.

Move to Point

There are two methods to change the current point to a new point.

- (void)moveToPoint:(NSPoint)point
- (void)relativeMoveToPoint:(NSPoint)point

Nothing is drawn between the original point and the new point. The result of this operation is analogous to lifting a pencil off the
paper and moving it to a new location. With the relative version of the method, the new point is specified as if the current point were
the origin. In mathematical terms, it is doing a vector addition instead of simply replacing the old value with the new. These methods
correspond to the PostScript commands moveto and rmoveto, respectively.

The previous Lines example shows one way this method can be used. In the example, the first endpoint of each line segment is
specified by moving to that point's location.

Line to Point

There are two methods to add a line segment to a path.

- (void)lineToPoint:(NSPoint)point
- (void)relativeLineToPoint:(NSPoint)point

The line segment starts at the current point and ends with the specified point. As with the move methods, the relative version specifies
the new point relative to the current point, whereas the plain version, -lineToPoint:, does not. The current point is changed to
the line segment's endpoint at the end of this operation. These methods correspond to the PostScript commands lineto and
rlineto.

The Lines example shows one way this method can be used. In the example, several line segments are drawn by first moving to the
start of the line segment with -moveToPoint:, and then using -lineToPoint: to specify the other end of the line segment.

Curve to Point

There are two methods for adding curved line segments to a path.

- (void)curveToPoint:(NSPoint)endPoint controlPoint1:(NSPoint)controlPoint1
controlPoint2:(NSPoint)controlPoint2
- (void)relativeCurveToPoint:(NSPoint)endPoint controlPoint1:(NSPoint)controlPoint1
controlPoint2:(NSPoint)controlPoint2

The curve starts at the current point and ends at the point specified by the endPoint parameter. The two controlPoint
parameters specify Bezier control points that define exactly how the line segment curves. In simple terms, the curve starts out tangent
to an invisible line from the start point to control point one and ends up tangent to an invisible line from control point two to the end
point. Figure 12.8 shows this relationship. The exact quadratic equations that are used to calculate the curve can be found in any
computer graphics text.

Figure 12.8. The curve starts out tangent to an invisible line from the start point to control point one and ends up tangent to
an invisible line from control point two to the end point.

As with the line methods, the current point is moved to endPoint when this method is finished. These methods correspond to the
PostScript commands curveto and rcurveto.

The Paths example contains code that draws random Bezier curves. Besides just drawing the curve itself, the code also draws a
rectangle over each point: start, end, and both control points. Additionally, gray dashed lines are drawn between the endpoints of the
curve and their associated control points. The output looks similar to the previous diagram. When running the example, choose the
Bezier curves option from the control panel. Click Redraw several times to see a variety of examples. As more examples are viewed,
the relationship between the points becomes much more clear. The code is as follows:

- (void)drawCurve
{
NSBezierPath *curve = [NSBezierPath bezierPath];
NSBezierPath *line1 = [NSBezierPath bezierPath];
NSBezierPath *line2 = [NSBezierPath bezierPath];
NSRect bds = [self bounds];
NSPoint start = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSPoint end = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSPoint control1 = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSPoint control2 = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
float dash[1] = { 5. 0 };
[[NSColor whiteColor] set];
NSRectFill(bds);
[[NSColor grayColor] set];
// draw lines between the endpoints and their associated control points
[line1 moveToPoint:start];
[line1 lineToPoint:control1];
[line1 setLineDash:dash count:1 phase: 0. 0];
[line1 setLineWidth:2. 0];
[line1 stroke];
[line2 moveToPoint:end];
[line2 lineToPoint:control2];
[line2 setLineDash:dash count:1 phase: 0. 0];
[line2 setLineWidth:2. 0];
[line2 stroke];
[[NSColor blackColor] set];
// draw the curve itself
[curve moveToPoint:start];
[curve curveToPoint:end controlPoint1:control1 controlPoint2:control2];
[curve setLineWidth:4. 0];
[curve stroke];
 // draw rectangles around each point
NSRectFill(NSMakeRect(start. x - 5. 0, start. y - 5. 0, 10. 0, 10. 0));
NSRectFill(NSMakeRect(end. x - 5. 0, end. y - 5. 0, 10. 0, 10. 0));
NSRectFill(NSMakeRect(control1. x - 5. 0, control1. y - 5. 0, 10. 0, 10. 0));
NSRectFill(NSMakeRect(control2. x - 5. 0, control2. y - 5. 0, 10. 0, 10. 0));
}

Close Path

There is a special operation for drawing a line segment from the current point to the starting point of the most recent path segment.
This is known as closing a path, so the method is named -closePath. It takes no arguments and returns nothing.

Every time a move operation is performed, a new path segment is started. Thus, the line segment that is added ends at the point
specified by the most recent move operation and changes the current point to the same point. This operation is nearly always used
when working with filled paths, but can also be used to complete the outline of a shape. The corresponding PostScript command is
closepath.

NOTE

There is an important difference between adding a line segment with one of the previous line methods and using -
closePath. For a continuous path, such as a circle, square, polygon, and so on, it is important to be sure that the start/
end point of the loop is considered to be a corner as opposed to two separate line endings. This is accomplished by using
-closePath. If -closePath is not used, an incorrect rendering of two line caps instead of a mitered corner will
occur.

As an example of the difference between a path that uses -closePath and one that does not, consider the following code from the
Paths example:

- (void)drawClosePathExample
{
NSRect bds = [self bounds];
NSBezierPath *leftTriangle = [NSBezierPath bezierPath];
NSBezierPath *rightTriangle = [NSBezierPath bezierPath];
double center = NSMidX(bds);
double top = NSMaxY(bds) - 20. 0;

[[NSColor whiteColor] set];

NSRectFill(bds);
[[NSColor blackColor] set];
// draw left triangle without a closepath
[leftTriangle moveToPoint:NSMakePoint(20. 0, 20. 0)];
[leftTriangle lineToPoint:NSMakePoint(center - 20. 0, 20. 0)];
[leftTriangle lineToPoint:NSMakePoint(center * 0. 5, top)];
[leftTriangle lineToPoint:NSMakePoint(20. 0, 20. 0)];
[leftTriangle setLineWidth:10. 0];
[leftTriangle setLineCapStyle:NSButtLineCapStyle];
[leftTriangle setLineJoinStyle:NSRoundLineJoinStyle];
[leftTriangle stroke];
// draw right triangle with a closepath
[rightTriangle moveToPoint:NSMakePoint(center + 20. 0, 20. 0)];
[rightTriangle lineToPoint:NSMakePoint(NSMaxX(bds) - 20. 0, 20. 0)];
[rightTriangle lineToPoint:NSMakePoint(center * 1. 5, top)];
[rightTriangle closePath];
[rightTriangle setLineWidth:10. 0];
[rightTriangle setLineCapStyle:NSButtLineCapStyle];
[rightTriangle setLineJoinStyle:NSRoundLineJoinStyle];
[rightTriangle stroke];
}

When the previous code is run, the output looks like Figure 12.9. Note that the lower-left corner of the left triangle has a notch in it.
Because the left triangle doesn't have a close path at the end, Quartz renders the end caps (square butts) instead of a line join (rounded
corners in this case). This shows why -closePath should normally be used to finish defining the path of a closed polygon.

Figure 12.9. The difference between line cap without -closePath and line join with -closePath is shown.

Remove All Points

Use the -removeAllPoints method to completely erase the path stored inside of an NSBezierPath object and start over. After
calling it, the path is empty. This method is handy when reusing an NSBezierPath to draw several different paths. It is similar, but
not exactly the same as, the PostScript command newpath.

The most common reason to use -removeAllPoints is to avoid instantiating multiple NSBezierPath objects. Instead, the
object can be reused by emptying out all the points, and then defining a new path. In the Paths example, the code for the -
drawClippedLines method uses this technique. Each line is drawn, one at a time, by the same NSBezierPath object. The
code for this method can be found in the rounded rectangle example at the end of the "Appending an Arc" section later in this chapter.

Appending a Rectangle

A convenience method is available to add a rectangular path to the current path.

- (void)appendBezierPathWithRect:(NSRect)rectangle

The effect of this method is the same as the following sequence of operations:

1. move to the origin of rectangle

2. line to the lower-right corner of rectangle

3. line to the upper-right corner of rectangle

4. line to the upper-left corner of rectangle

5. close path

Note that the rectangle is defined in a counterclockwise manner. If a clockwise rectangle is needed, the operations have to be
explicitly performed by the developer instead of using this method. To quickly create a new path object that contains a rectangle, use
the related class method +bezierPathWithRect: as a shortcut. It gives a new autoreleased path object that defines the rectangle
as described previously.

Appending a Series of Lines

Another convenience method adds a continuous series of line segments to a path.

- (void)appendBezierPathWithPoints:(NSPointArray)points count:(int)count

This method adds a line operation to the current path for each point in the points array. If the path started out empty, the very first
operation is a move instead of a line. If there is an array of points that define the corners of a polygon, this method can be used to add
the polygon to the current path. The one caveat is that this method doesn't issue a close operation, so don't forget to close the path if
necessary.
An example of drawing several lines with this method can be found in the Paths example. The Lines using points array option in the
control panel activates this code:

[View full width]

- (void)drawLinesWithArray
{ // Single stroke method with points array
int i;
NSBezierPath *lines = [NSBezierPath bezierPath];
NSRect bds = [self bounds];
// clear the view to solid black background
[[NSColor blackColor] set];
NSRectFill(bds);
// set up to draw with white
[[NSColor whiteColor] set];
// draw a bunch of random connected lines
[lines moveToPoint:NSMakePoint(random() % (int)bds. size. width, random() % (int)bds.
size. height)];
for (i=0; i<numberOfLines; i++) {
pointsArray[i] = NSMakePoint(random() % (int)bds. size. width, random() % (
int)bds. size. height);
}
[lines appendBezierPathWithPoints:pointsArray count:numberOfLines];
// render the lines all at once
[lines stroke];
}

When this code is run, multiple random line segments are drawn. The end point of one line segment is the starting point for the next,
so all the line segments are connected together. Figure 12.10 shows an example of the drawing produced by this code.

Figure 12.10. The end point of one line segment is the starting point for the next.

Appending an Oval

Curve to operations can be used to draw ovals and circles, given the right set of points. Rather than calculate all the points, it is easier
to use a convenience function instead.

- (void)appendBezierPathWithOvalInRect:(NSRect)rect

This method adds a move and several curve segments to the path. The added shape is inscribed in the rectangle specified with rect.
An oval is displayed for rectangular shapes and a circle is displayed if a square is specified. The circle or oval starts at the top center
of the specified rectangle and continues counterclockwise around its circumference, finishing where it started.

To quickly create a brand new path object that contains an oval or a circle, use the related class method
+bezierPathWithOvalInRect: as a shortcut. It returns a new autoreleased path object that defines an oval as described in the
previous paragraph.

As an example of this method in action, take a look at the code for the -drawDonuts method in the Paths example. The code can be
found in the "Strokes and Fills" section later in this chapter.
Appending an Arc

There are two convenience methods that add a circular arc to the path.

- (void)appendBezierPathWithArcWithCenter:(NSPoint)center radius:(float)radius
startAngle:(float)startAngle endAngle:(float)endAngle
clockwise:(BOOL)clockwise
- (void)appendBezierPathWithArcWithCenter:(NSPoint)center radius:(float)radius
startAngle:(float)startAngle endAngle:(float)endAngle

The only difference between the two is in the clockwise parameter. If using the method that leaves it out, a counterclockwise direction
for the arc is assumed. The arc itself is a portion of a circle with the specified radius and center point. The startAngle parameter
determines, along with the center and radius parameters, the starting point of the arc. The arc will continue around the circle in
the direction specified (clockwise or counterclockwise) until it reaches the point specified by the endAngle parameter. Both angles
should be provided in degrees and not radians. These methods add a move and one or more curve operations to the path, leaving the
current point at the end of the arc.

An example showing a few variations of this method call is found in the Paths example. The -drawArcs method, selected by
choosing Arcs in the control panel, is coded like this:

- (void)drawArcs
{
NSRect bds = [self bounds];
NSPoint center = NSMakePoint(NSMidX(bds), NSMidY(bds));
NSBezierPath *arc1 = [NSBezierPath bezierPath];
NSBezierPath *arc2 = [NSBezierPath bezierPath];
NSBezierPath *arc3 = [NSBezierPath bezierPath];
NSBezierPath *arc4 = [NSBezierPath bezierPath];
double radius = MIN(center. x, center. y) * 0. 5 - 10. 0;

[[NSColor whiteColor] set];

NSRectFill(bds);
[[NSColor blackColor] set];
// lower left
[arc1 appendBezierPathWithArcWithCenter:
NSMakePoint(center. x * 0. 5, center. y * 0. 5)
radius:radius startAngle:0. 0 endAngle:90. 0];
// upper left
[arc2 appendBezierPathWithArcWithCenter:
NSMakePoint(center. x * 0. 5, center. y * 1. 5)
radius:radius startAngle:0. 0 endAngle:90. 0 clockwise:NO];
// lower right
[arc3 appendBezierPathWithArcWithCenter:
NSMakePoint(center. x * 1. 5, center. y * 0. 5)
radius:radius startAngle:0. 0 endAngle:90. 0 clockwise:YES];
// upper right
[arc4 appendBezierPathWithArcWithCenter:
NSMakePoint(center. x * 1. 5, center. y * 1. 5)
radius:radius startAngle:0. 0 endAngle:90. 0 clockwise:YES];
[arc2 closePath];
[arc4 closePath];
[arc1 stroke];
[arc2 stroke];
[arc3 stroke];
[arc4 stroke];
}

When this code is run, Figure 12.11 shows the drawing that is produced.

Figure 12.11. When the code described in the text is run, this is the drawing that is produced.
Another convenience method is available for drawing an arc with an attached line segment.

- (void)appendBezierPathWithArcFromPoint:(NSPoint)point1
toPoint:(NSPoint)point2 radius:(float)radius

This method makes it easier to add rounded corners to a polygon. It adds a line segment and the arc of a circle to the path. Two
tangent lines bound the circle from which the arc is taken-one from the current point to point1 and the other from point1 to
point2. To uniquely specify the circle, it also uses the specified radius.

The line segment that is added to the path runs from the current point to where the tangent line from the current point to point1
intersects the circle. The arc goes from that point to the point where the tangent from point1 to point2 intersects the circle. The
current point is left at the arc's end point. Figure 12.11 should help visualize this; it sounds far more complex than it really is. The
black line in Figure 12.12 shows what is actually added to the path object.

Figure 12.12. The black line shows what is actually added to the path object.

Because this operation relies on the existence of a current point, this method can't be used on an empty path or an exception is raised.
A move operation must be used to set the current point first. This operation is similar to the PostScript arcto operator.

As an example of how you might use this method to build a polygon with rounded corners, draw a rectangle with rounded corners.
Start at the midpoint of the top edge of the rectangle and work around the rectangle in a clockwise direction. Here is some code you
can use for this example:

File RoundedRect. h :

#import <Cocoa/Cocoa. h>

@interface NSBezierPath(RoundedRect)

- (void)appendBezierPathWithRoundedRectangle:(NSRect)aRect
withRadius:(float)radius;

@end

File RoundedRect. m :

#import "RoundedRect. h"

@implementation NSBezierPath(RoundedRect)

- (void)appendBezierPathWithRoundedRectangle:(NSRect)aRect
withRadius:(float)radius
{
NSPoint topMid = NSMakePoint(NSMidX(aRect), NSMaxY(aRect));
NSPoint topLeft = NSMakePoint(NSMinX(aRect), NSMaxY(aRect));
NSPoint topRight = NSMakePoint(NSMaxX(aRect), NSMaxY(aRect));
NSPoint bottomRight = NSMakePoint(NSMaxX(aRect), NSMinY(aRect));
[self moveToPoint:topMid];
[self appendBezierPathWithArcFromPoint:topLeft toPoint:aRect.origin
radius:radius];
[self appendBezierPathWithArcFromPoint:aRect.origin toPoint:bottomRight
radius:radius];
[self appendBezierPathWithArcFromPoint:bottomRight toPoint:topRight
radius:radius];
[self appendBezierPathWithArcFromPoint:topRight toPoint:topLeft
radius:radius];
[self closePath];
}

@end

The previous method is defined as an Objective-C category of NSBezierPath. It could then be used like any other method of
NSBezierPath. Simply call it with an NSRect defining the bounds of the rectangle and a radius for the curvature of the corners
and it appends an appropriate rounded rectangle to the path. Note that if the rectangle's width or height is less than twice the radius,
visual artifacts in the path are present as the arcs begin to overlap. Don't forget to stroke or fill the path to actually have drawing done;
this sample code simply adds to the path definition.

To see this example code in action, look at the Paths example source code. The clipped lines option uses the rounded rectangle
category to draw the outline of a rectangle with rounded corners and define a clipping area. No drawing takes place outside of the
clipping area outlined by the rounded rectangle. The onscreen drawing is accomplished by calling this method from the NSView's
-drawRect: method:

- (void)drawClippedLines
{ // Draw lots of random line segments, clipped to a rounded rect
int i;
NSBezierPath *line = [NSBezierPath bezierPath];
NSBezierPath *rect = [NSBezierPath bezierPath];
NSRect bds = [self bounds];
// clear the view to solid black background
[[NSColor blackColor] set];
NSRectFill(bds);
// set up to draw with white
[[NSColor whiteColor] set];
// save the current clipping path
[[NSGraphicsContext currentContext] saveGraphicsState];
// set up a new clipping path - a rect with rounded corners
[rect appendBezierPathWithRoundedRectangle:NSInsetRect(bds, 20. 0, 20. 0)
withRadius:30. 0];
[rect addClip];
// draw a bunch of random lines inside the new clipped area
for (i=0; i<numberOfLines; i++) {
// get random start and end points
NSPoint start = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
NSPoint end = NSMakePoint(random() % (int)bds. size. width,
random() % (int)bds. size. height);
[line removeAllPoints];
// draw a line segment
[line moveToPoint:start];
[line lineToPoint:end];
[line stroke];
 }
// restore the original clipping path
[[NSGraphicsContext currentContext] restoreGraphicsState];
// now take the rect used as the path and draw it with a little
// bit wider line width so that we have a nice looking frame
[rect setLineWidth:2. 0];
[rect stroke];
}

When this code is run, output similar to Figure 12.13 is created.

Figure 12.13. The -drawClippedLines method produces output similar to this.

- (void)appendBezierPath:(NSBezierPath *)path;

This method can be used to append the path defined by one NSBezierPath object to another. This can be used to build up complex
paths by appending several path objects together.

The previous methods are the primary methods used to construct a path using the NSBezierPath class. There are also several other
NSBezierPath methods that enable you to take individual character glyphs from the font of your choice and add them to a path.
Because these methods are somewhat complex, a whole section of this chapter devoted to them. See "NSBezierPath and Glyphs" in
Chapter 14 to learn how to use these methods.

Rendering a Path

When a path has been defined, it is ready to be rendered. Rendering is very easy because there are only a few ways to actually render
the path: stroke, fill, or clip. Clip, the third operation, doesn't actually do drawing, but instead restricts further drawing.

Strokes and Fills

Stroking a path is similar to taking a paintbrush and using it to trace out the path that has been defined. In other words, this renders
the outline of the shape the path defines. The star and donut shapes in Figure 12.14 are examples of stroked paths. To stroke a path,
simply send it a -stroke message. No arguments are required.

Figure 12.14. The star and donut shapes are examples of stroked paths.

Filling is like using the path as a wall, while pouring paint into the area enclosed by the path. A filled path gives a solid shape instead
of an outline. To fill a path, send it a -fill message. There are no arguments.
There is a wrinkle with fills, however. Suppose there is a shape such as a five-pointed star, drawn with the outline at the left in Figure
12.14. Further suppose there are multiple paths defined in a shape that forms something of a donut shape, as in the shape to the right
of the star.

When the star is filled, should the pentagon in the center be filled or not? What about the center of the donut, should it be filled? The
answer depends on application. You would probably want to fill the whole star, but not the center of the donut. This is where the
winding rule comes in. The winding rule determines how these situations should be handled. These situations do happen more often
than you might think, especially when handling text.

Before issuing the fill command, a developer probably wants to specify a winding rule to get the fill behavior required. The
enumerated type NSWindingRule defines two constants to represent the available winding-rule algorithms. The first,
NSNonZeroWindingRule, is the default winding rule and represents the case where the center of the star and donut are filled in.
The second is NSEvenOddWindingRule. With the even/odd rule, the filled star or donut would have a nonfilled hole in the
middle. See Figure 12.15 for examples of each rule.

Figure 12.15. Using different winding rules produces the pictured fill behaviors.

The winding rule for a particular path can be changed by using the -setWindingRule: method. The single parameter should be
one of the constants (NSNonZeroWindingRule or NSEvenOddWindingRule). A developer can find out which rule is used by
an NSBezierPath instance by querying with the -windingRule method, which returns one of these two values. Additionally,
the default winding rule can be queried and changed by using the NSBezierPath class methods +defaultWindingRule and
+setDefaultWindingRule:.

To demonstrate how the different rules can be used, the Paths example contains the code needed to draw the stars and donuts shown
in Figures 12.14 and 12.15.

To define the various ovals the code to draw the donuts uses -appendBezierPathWithOvalInRect:. Each oval is defined
separately and the path object is emptied out after each donut is rendered. (The next chunk of example code, to draw the stars, does a
better job of reusing the path data.) This example shows the results of a stroke, a fill without specifying a particular winding rule (the
default winding rule) and each of the winding rules supported by Quartz (nonzero and even-odd). As in the rounded-rectangle
example shown previously, this method is called from the -drawRect: method of the NSView subclass when it is time to do the
drawing:

- (void)drawDonuts
{
// Draw four different ovals
// 2 non zero 3 even/odd
// 1 stroked 4 default winding
NSBezierPath *path = [NSBezierPath bezierPath];
NSRect bds = [self bounds];
// divide the view into four rectangles
NSRect r1 = NSMakeRect(bds. origin. x, bds. origin. y,
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r2 = NSMakeRect(bds. origin. x, NSMidY(bds),
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r3 = NSMakeRect(NSMidX(bds), NSMidY(bds),
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r4 = NSMakeRect(NSMidX(bds), bds. origin. y,
bds. size. width / 2. 0, bds. size. height / 2. 0);
// clear the view to solid white background
 [[NSColor whiteColor] set];
NSRectFill(bds);
// set up drawing parameters - draw black with linewidth of 2. 0
[[NSColor blackColor] set];
[path setLineWidth:2. 0];
// Draw lower left donut (stroked)
[path appendBezierPathWithOvalInRect:NSInsetRect(r1, 10. 0, 10. 0)];
[path appendBezierPathWithOvalInRect:NSInsetRect(r1, 25. 0, 25. 0)];
[path stroke];
// draw lower right donut (default wind)
[path removeAllPoints];
[path setWindingRule:[NSBezierPath defaultWindingRule]];
[path appendBezierPathWithOvalInRect:NSInsetRect(r4, 10. 0, 10. 0)];
[path appendBezierPathWithOvalInRect:NSInsetRect(r4, 25. 0, 25. 0)];
[path fill];
// draw upper right donut (even/odd)
[path removeAllPoints];
[path setWindingRule:NSEvenOddWindingRule];
[path appendBezierPathWithOvalInRect:NSInsetRect(r3, 10. 0, 10. 0)];
[path appendBezierPathWithOvalInRect:NSInsetRect(r3, 25. 0, 25. 0)];
[path fill];
// draw upper left donut (non-zero)
[path removeAllPoints];
[path setWindingRule:NSNonZeroWindingRule];
[path appendBezierPathWithOvalInRect:NSInsetRect(r2, 10. 0, 10. 0)];
[path appendBezierPathWithOvalInRect:NSInsetRect(r2, 25. 0, 25. 0)];
[path fill];
}

The donuts code produces the output shown in Figure 12.16 when the Paths application is run and Donuts is chosen on the control
panel.

Figure 12.16. The pictured output is produced by the Paths example when Donuts is chosen on the control panel.

A similar approach to the one used with the donuts is used to draw the stars. However, rather than defining a new path for each star, a
single NSBezierPath is defined and reused for each star. To accomplish this and cause each star to be drawn at a different
location, the path is translated using an NSAffineTransform object. (This object is discussed in Chapter 13.) The translation
operation causes the path to be drawn at a different location without affecting its size or shape. Except for this difference, the code is
much like the donut drawing code shown previously:

- (void)drawStars
{
// Draw four different stars
// 2 non zero 3 even/odd
// 1 stroked 4 default winding
NSGraphicsContext *currentContext = [NSGraphicsContext currentContext];
NSBezierPath *path = [NSBezierPath bezierPath];
NSAffineTransform *transform = nil;
NSRect bds = [self bounds];
 // divide the view into four rectangles
NSRect r1 = NSMakeRect(bds. origin. x, bds. origin. y,
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r2 = NSMakeRect(bds. origin. x, NSMidY(bds),
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r3 = NSMakeRect(NSMidX(bds), NSMidY(bds),
bds. size. width / 2. 0, bds. size. height / 2. 0);
NSRect r4 = NSMakeRect(NSMidX(bds), bds. origin. y,
bds. size. width / 2. 0, bds. size. height / 2. 0);

// clear the view to a white background

[[NSColor whiteColor] set];
NSRectFill(bds);

// set the drawing color to black and the line width to 2. 0

[[NSColor blackColor] set];
[path setLineWidth:2. 0];
// define the star's path
[path moveToPoint:NSMakePoint(NSMinX(r1) + 40. 0, NSMinY(r1) + 20. 0)];
[path lineToPoint:NSMakePoint(NSMidX(r1), NSMaxY(r1) - 20. 0)];
[path lineToPoint:NSMakePoint(NSMaxX(r1) - 40. 0, NSMinY(r1) + 20. 0)];
[path lineToPoint:NSMakePoint(NSMinX(r1) + 20. 0, NSMaxY(r1) - 50. 0)];
[path lineToPoint:NSMakePoint(NSMaxX(r1) - 20. 0, NSMaxY(r1) - 50. 0)];
[path closePath];

// stroke the star in r1.

[path stroke];

// do r4 - default winding rule

[path setWindingRule:[NSBezierPath defaultWindingRule]];
transform = [NSAffineTransform transform];
[transform translateXBy:r4. origin. x yBy:r4. origin. y];
[currentContext saveGraphicsState];
[transform concat];
[path fill];
[currentContext restoreGraphicsState];

// do r3 - even/odd winding rule

[path setWindingRule:NSEvenOddWindingRule];
transform = [NSAffineTransform transform];
[transform translateXBy:r3. origin. x yBy:r3. origin. y];
[currentContext saveGraphicsState];
[transform concat];
[path fill];
[currentContext restoreGraphicsState];

// do r2 - non-zero winding rule

[path setWindingRule:NSNonZeroWindingRule];
transform = [NSAffineTransform transform];
[transform translateXBy:r2. origin. x yBy:r2. origin. y];
[currentContext saveGraphicsState];
[transform concat];
[path fill];
[currentContext restoreGraphicsState];
}

The output of the stars code is shown in Figure 12.17.

Figure 12.17. The output of the stars code looks like this.
Winding Rules

If a developer isn't familiar with PostScript or 2D graphics algorithms, she might wonder where the winding rule names come from or
even why they are called winding rules. If you look at the paths used in the previous example (star and donut), you will note that the
paths are closed. It could be said that the path winds around the area that it encloses. A winding rule is so named because it uses
information about the path's winding to determine whether a pixel is in a fill area.

To simplify the result, move from outside of the figure toward its center and count how many winds have been passed through,
starting with zero outside of the path. In the nonzero winding rule, whenever this count is nonzero, it is inside the object, therefore the
fill paints the pixels. This is a very inclusive fill, and never has holes in it.

The complete rule for nonzero is slightly more complex than just counting path crossings. If the path section crossed is moving from
left to right, add one to the crossing count. Conversely, subtract one from the count if the path segment moves from right to left. With
the donut graphic, both ovals are drawn in the same direction. If the inner oval was drawn in the opposite direction from the outer
oval, both the nonzero and even-odd rules would