OpenStep Programming Reference - Oracle Cloud2550 Garcia Avenue Mountain View, CA 94043 U.S.A. OpenStep Programming Reference Part No 802-2112-10 Revision A, September 1996 A Sun Microsystems,

2550 Garcia AvenueMountain View, CA 94043U.S.A.

OpenStep Programming Reference

Part No 802-2112-10Revision A, September 1996

A Sun Microsystems, Inc. Business

PleaseRecycle

1996 Sun Microsystems, Inc.

2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A. All rights reserved.

Portions Copyright 1995 NeXT Computer, Inc. All rights reserved.

This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, anddecompilation. No part of this product or document may be reproduced in any form by any means without prior writtenauthorization of Sun and its licensors, if any.

Portions of this product may be derived from the UNIX® system, licensed from UNIX System Laboratories, Inc., a wholly ownedsubsidiary of Novell, Inc., and from the Berkeley 4.3 BSD system, licensed from the University of California. Third-party fontsoftware, including font technology in this product, is protected by copyright and licensed from Sun's suppliers. This productincorporates technology licensed from Object Design, Inc.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set forth insubparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227-19.

The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.

TRADEMARKS

Sun, Sun Microsystems, the Sun logo, SunSoft, the SunSoft logo, Solaris, SunOS, and OpenWindows are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the UnitedStates and other countries, exclusively licensed through X/Open Company, Ltd. OPEN LOOK is a registered trademark ofNovell, Inc. PostScript and Display PostScript are trademarks of Adobe Systems, Inc. Object Design is a trademark and the ObjectDesign logo is a registered trademark of Object Design, Inc. OpenStep, NeXT, the NeXT logo, NEXTSTEP, the NEXTSTEP logo,Application Kit, Foundation Kit, Project Builder, and Workspace Manager are trademarks of NeXT Computer, Inc. Unicode is atrademark of Unicode, Inc. VT100 is a trademark of Digital Equipment Corporation. All other product names mentioned hereinare the trademarks of their respective owners.

All SPARC trademarks are trademarks or registered trademarks of SPARC International, Inc. in the United States and othercountries. SPARCcenter, SPARCcluster, SPARCCompiler, SPARCdesign, SPARC811, SPARCengine, SPARCprinter,SPARCserver, SPARCstation, SPARCstorage, SPARCworks, microSPARC-11, and UltraSPARC are licensed exclusively to SunMicrosystems, Inc. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK® and SunTM Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees.Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical userinterfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, whichlicense also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written licenseagreements.

X Window System is a product of X Consortium, Inc.

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR APARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES AREPERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEWEDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES INTHE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

iii

Contents

Part 1 —Application Kit

1. Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Encapsulating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

General Drawing and Event Handling . . . . . . . . . . . . . . . . . . . . 1-1

Menus and Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Grouping and Scrolling Views . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Controlling an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Text and Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Graphics and Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Printing and Faxing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Accessing the File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Sharing Data with Other Applications . . . . . . . . . . . . . . . . . . . . 1-4

Spell-Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Application Kit Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

NSActionCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

iv OpenStep Programming Reference—September 1996

NSApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13

NSBitmapImageRep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38

NSBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-49

NSBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-55

NSBrowserCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-79

NSBundle Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-83

NSButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-85

NSButtonCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-96

NSCachedImageRep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-107

NSCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-109

NSClipView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-138

NSCoder Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-144

NSColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-144

NSColorList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-160

NSColorPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-164

NSColorPicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-172

NSColorWell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-175

NSControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-178

NSCStringText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-197

NSCursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-231

NSCustomImageRep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-239

NSDataLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-241

NSDataLinkManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-245

NSDataLinkPanel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-247

Contents v

NSEPSImageRep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-251

NSEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-253

NSFont. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-263

NSFontManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-273

NSFontPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-286

NSForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-289

NSFormCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-294

NSHelpPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-298

NSImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-304

NSImageRep. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-328

NSMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-338

NSMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-366

NSMenuCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-373

NSOpenPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-375

NSPageLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-378

NSPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-384

NSPasteboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-387

NSPopUpButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-399

NSPrinter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-407

NSPrintInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-420

NSPrintOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-430

NSResponder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-438

NSSavePanel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-445

NSScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-452

vi OpenStep Programming Reference—September 1996

NSScroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-455

NSScrollView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-462

NSSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-472

NSSlider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-475

NSSliderCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-480

NSSpellChecker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-487

NSSpellServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-495

NSSplitView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-501

NSTableColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-504

NSTableHeaderCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-510

NSTableHeaderView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-510

NSTableView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-512

NSText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-535

NSTextField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-559

NSTextFieldCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-566

NSView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-568

NSWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-605

NSWorkspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-649

2. Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

NSChangeSpelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

NSColorPickingCustom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

NSColorPickingDefault. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

NSDraggingDestination (Informal Protocol) . . . . . . . . . . . . . . . 666

NSDraggingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

Contents vii

NSDraggingSource (Informal Protocol) . . . . . . . . . . . . . . . . . . . 674

NSIgnoreMisspelledWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

NSMenuActionResponder (Informal Protocol) . . . . . . . . . . . . . 677

NSMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679

NSNibAwaking (Informal Protocol) . . . . . . . . . . . . . . . . . . . . . . 681

NSServicesRequests (Informal Protocol). . . . . . . . . . . . . . . . . . . 683

NSTableDataSource (Informal Protocol) . . . . . . . . . . . . . . . . . . . 684

3. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Rectangle Drawing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Color Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Array Allocation Functions for Use by the NSText Class . . . . . 3-8

Imaging Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

Attention Panel Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Services Menu Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12

X-Windows Convenience Functions . . . . . . . . . . . . . . . . . . . . . . 3-14

Other Application Kit Functions . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

4. Types and Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Cells and Button Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Data Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

viii OpenStep Programming Reference—September 1996

Drag Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16

Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

Page Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Pasteboards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

Save Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23

Scrollers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23

Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25

Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38

Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39

Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40

Part 2 —Foundation Kit

5. Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

NSArchiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

NSArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

NSAssertionHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18

NSAutoreleasePool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

NSBundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25

Contents ix

NSCalendarDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33

NSCharacterSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-42

NSCoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47

NSConditionLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-57

NSConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-60

NSCountedSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-67

NSData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-70

NSDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-77

NSDateFormatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-85

NSDeserializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-88

NSDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-90

NSDistantObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-98

NSEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-100

NSException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-102

NSFormatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-109

NSInvocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-114

NSLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-118

NSMethodSignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-119

NSMutableArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-122

NSMutableCharacterSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-129

NSMutableData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-131

NSMutableDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-137

NSMutableSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-140

NSMutableString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-143

x OpenStep Programming Reference—September 1996

NSNotification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-146

NSNotificationCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-149

NSNotificationQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-153

NSNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-158

NSObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-168

NSPosixFileDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-188

NSProcessInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-195

NSProxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-198

NSRecursiveLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-200

NSRunLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-202

NSScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-205

NSSerializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-210

NSSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-212

NSString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-218

NSThread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-242

NSTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-245

NSTimeZone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-249

NSTimeZoneDetail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-254

NSUnarchiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-256

NSUserDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-260

NSValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-270

6. Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

NSCoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

NSCopying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Contents xi

NSLocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

NSMutableCopying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

NSObjCTypeSerializationCallBack . . . . . . . . . . . . . . . . . . . . . . . 282

NSObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

7. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Memory Allocation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Object Allocation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

Error-Handling Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Geometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11

Range Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18

Hash Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19

Map Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23

Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-27


Bundle Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Hash Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

Map Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Notification Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

Run Loop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

Searching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11

Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

xii OpenStep Programming Reference—September 1996

User Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13

Part 3 —Display PostScript

9. Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

NSDPSContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

10. Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

NSDPSContextNotification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

11. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Compositing Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Graphics State Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5

12. Client Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

PostScript Execution Context Functions . . . . . . . . . . . . . . . . . . . 12-1

Communication with the Display PostScript Server . . . . . . . . . 12-2

13. Single-Operator Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

“PS” Prefix Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2

“DPS” Prefix Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2


Defined Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Symbolic Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Part 4 —Sound Kit

15. Sound Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Sound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Contents xiii

SoundMeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

SoundView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Index Index-1

xiv OpenStep Programming Reference—September 1996

xv

Introduction

This book describes the Application Programming Interface (API) for theOpenStep™ development environment. OpenStep is an operating systemindependent, object-oriented application layer, based on NeXT’s advancedobject technology. See the “Further Reading” section at the end of thisintroduction for a description of the other books in the OpenStepdocumentation set.

The OpenStep software is divided into the following kits:

• The Application Kit contains the software for writing applications that usewindows, draw on the screen, and respond to user actions on the keyboardand mouse.

• The Foundation Kit provides the fundamental building blocks thatapplications use to manage data and resources. It defines facilities forhandling multibyte character sets, object persistency and distribution, andprovides an interface to common operating system facilities.

• Display Postscript Kit provides OpenStep with its device-independentimaging model.

• The Sound Kit provides software for capturing, manipulating, reading, andwriting sounds.

Each kit is a combination of Objective C classes and protocols, along with Cfunctions, types, and constants. Please note that many of the types used formethod argument and return values in this book are defined in the Objective Clanguage. These include:

xvi OpenStep Programming Reference—September 1996

• BOOL• Class• id• IMP• nil• Protocol• SEL

In addition, the type codes used to encode method argument and return typesfor archiving and other purposes are also defined in the Objective C language.

Book OrganizationThis book contains sections for each kit. Each section contains chaptersdescribing the kit’s classes, protocols, functions, and types and constants. Thefollowing outline shows the book organization:

• Application Kit• Classes• Protocols• Functions• Types and Constants

• Foundation Kit• Classes• Protocols• Functions• Types and Constants

• Display PostScript System• Classes• Protocols• Display PostScript Operators• Client Library Functions• Single-Operator Functions• Types and Constants

• Sound Kit• Classes• Types and Constants

Introduction xvii

Chapter OrganizationThe following sections desribe each chapters organization, and brieflydiscusses:

• Inheritance Hierarchies• Delegates• Formal and Informal Protocols

Classes

Each class chapter contains a kit’s class descriptions listed alphabetically. Eachclass description starts with a table listing the class’s inheritance hierarchy,protocol conformance, and header file containing the class interface. Forexample:

The first line in this example specifies a class’s inheritance hierarchy, in thiscase NSActionCell ’s inheritance hierarchy. It specifies that NSActionCellinherits from NSCell , and that NSCell inherits from NSObject . NSCell iscalled NSActionCell ’s superclass. NSObject is the root class of almost allOpenStep inheritance hierarchies.

The second line in the previous example specifies the formal protocols that theclass conforms to. These include both protocols the class adopts and those itinherits from other adopting classes. If inherited, the name of the adoptingclass in given in parentheses.

The third line in the previous example specifies the header file that declares theclass interface.

Inherits From: NSCell : NSObject

Conforms To: NSCoding, NSCopying (NSCell),NSObject (NSObject)

Declared In: AppKit/NSActionCell.h

xviii OpenStep Programming Reference—September 1996

After a general description of the class, the class’s methods are listed infunctional groups. For example, here is NSScroller’s list:

This list is followed by class methods in alphabetical order, then instancemethods in alphabetical order. Each method’s prototype is given, followed by abrief description.

Some classes have separate sections with titles such as “Methods Implementedby the Superview”, “Methods Implemented by ”, “Methods Implemented bythe Owner.” These are informal protocols. They document methods that can ormust be implemented to receive messages on behalf of instances of the class.

Methods Implemented by the Delegate

If the class describes a delegate, the delegate methods are listed last. These arenot methods defined in the class; they are methods that you can define torespond to messages sent from instances of the class. If you define a delegatemethod, the delegate will receive automatic messages to perform that delegatemethod at the appropriate time. For example, if you define awindowDidBecomeKey: method for an NSWindow object’s delegate, thedelegate will receive windowDidBecomeKey: messages whenever the

Activity Class Method

Laying out the NSScroller + scrollerWidth– arrowsPosition– checkSpaceForParts– rectForPart:– setArrowsPosition:– usableParts

Setting the NSScroller’s values – knobProportion– setFloatValue:knobProportion:

Displaying – drawArrow:highlight:– drawKnob– drawParts– highlight:

Handling events – hitPart– testPart:– trackKnob:– trackScrollButtons:

Introduction xix

NSWindow object becomes the key window. Messages are sent to an object’sdelegate only if you define a method that can respond to the message withinthe delegate.

In essence, this section documents an informal protocol. But because thesemethods are so closely tied to the behavior of a particular class, they’redocumented with the class rather than in the Protocols chapters.

Protocols

The protocol chapters describe OpenStep’s formal and informal protocols.Formal protocols are declared using the @protocol compiler directive. Theycan be formally adopted and implemented by a class and tested by sending anobject a conformsToProtocol: message.

Some formal protocols are adopted and implemented by OpenStep classes.However, many formal protocols are declared by a kit, but not implemented byit. These formal protocols list methods that you can implement to respond tokit-generated messages.

A few formal protocols are implemented by a kit, but not by a class that’s partof the OpenStep API. Rather, the protocol is implemented by an anonymousobject that the kit supplies. The protocol lets you know what messages you cansend to the object.

Like formal protocols, informal protocols declare a list of methods that othersare invited to implement. If an informal protocol is closely associated with oneparticular class, for example, the list of methods implemented by the delegate,it’s documented in the class description.

Note – Informal protocols associated with more than one class, or notassociated with any particular class, are documented in the Protocols chapters.

Protocol information is organized into many of the same sections as describedpreviously for a class specification. But protocols are not classes and thereforediffer somewhat in the kind of information provided.

xx OpenStep Programming Reference—September 1996

Each formal protocol description starts with a table listing the classes thatadopt the protocol, and the header file containing the protocol description. Forexample:

Many protocols declare methods that applications must implement and so arenot adopted by any OpenStep classes. Some protocols are implemented byanonymous objects (instances of an unknown class); the protocol is the onlyinformation available about what messages the object can respond to. Protocolsthat have an implementation available through an anonymous object generallydon’t have to be reimplemented by other classes.

An informal protocol cannot be formally adopted by a class and it cannotformally incorporate another protocol. So its description begins withinformation about the category where it’s declared:

Informal protocols are typically declared as categories of the NSObject class.This gives them the widest possible scope. If the protocol includes enoughmethods to warrant it, they’re divided by type and presented just as themethods of a class are.

Functions

Within the function chapters related functions are grouped together under aheading that describes that groups similarities. Here is a partial list of theseheadings from the Application Kit:

• Rectangle Drawing Functions• Color Functions• Text Functions• Array Allocation Functions• Imaging Functions

Each function, its arguments, and its return value are briefly described in anaccompanying comment.

Adopted By: NSText

Declared In: AppKit/NSSpellProtocol.h

Category Of: NSObject

Declared In: AppKit/NSDragging.h

Introduction xxi

Types and Constants

Within these chapters related defined types, enumeration constants, symbolicconstants, structures, and global variables are grouped together under aheading that describes where the type or constant is used. Here is a partial listof these headings from the Application Kit:

• Application• Box• Buttons• Cells and Button Cells• Color

A short description accompanies each group.

Further ReadingIn addition to this document, the OpenStep documentation set consists of:

• QuickStart to Using the OpenStep Desktop—for beginning end-users. Aminimal set of instructions to get you started running OpenStep.

• Using the OpenStep Desktop—the complete end-user guide.• User Interface Guidelines—for application developers; identifies the objects

supplied in the Application Kit, describes their appearances and behaviors,and the kinds of application-specific behaviors that developers mustimplement. Includes detailed discussions of the mouse and keyboardoperations performed by users to operate the interface. Provides detailedguidelines for such things as choosing keyboard shortcut characters. Alsodescribes the behaviors that should be implemented for custom objects.

• OpenStep Development Tools—describes the essential tools for developing anOpenStep application: the Project Builder, Interface Builder, Header Viewer,Icon Builder, Edit applications, and the distributed Debugger. The manualalso included chapters on the Objective C language and the NSObject class.

xxii OpenStep Programming Reference—September 1996

Part 1 — Application Kit

1-1

Classes 1

The Application Kit classes are the core of OpenStep. They describe OpenStep’sappearance and behavior. The following sections give an overview of theApplication Kit classes.

Encapsulating an ApplicationThe central class of the Application Kit is NSApplication . Every applicationthat uses the Application Kit is a single NSApplication object, known to yourprogram as NSApp. Your NSApplication object

• Keeps track of the application’s windows and menus• Controls the main event loop• Opens Interface Builder files (with support from the NSAwakening

protocol)

• Maintains information about printing, languages, screens, color support,and so on

General Drawing and Event HandlingThe NSWindow and NSView classes are the centerpieces of drawing. Morespecifically, NSWindow objects represent rectangular areas on the screen in whichthe user works. To the extent that everything the user does is directed to anNSWindow, an application’s set of NSWindows is the application. NSViews areareas within NSWindows that perform your application’s drawing.

1-2 OpenStep Programming Reference—September 1996

1

NSPanel is a subclass of NSWindow that you use to display transient, global, orpressing information. For example, you would use a Panel, rather than aninstance of NSWindow, to display error messages, or to query the user for aresponse to remarkable or unusual circumstances.

The NSResponder class defines the responder chain, an ordered list of objects thatrespond to user events. When the user clicks the mouse or presses a key, anevent is generated and passed up the responder chain in search of an object thatcan respond to it.

Menus and CursorsThe NSMenu, NSMenuCell , and NSCursor classes define the look and behaviorof the menus and cursors that your application displays to the user.

Grouping and Scrolling ViewsThe NSBox, NSSplitView , and NSScrollView classes provide graphicwidgets to some other NSView or collection of NSViews. An NSBox groups somenumber of other NSViews, and lets you draw a border around the entire group.NSSplitView lets you stack NSViews vertically, apportioning to each NSViewsome amount of a common territory; a sliding control bar lets the userredistribute the territory among NSViews. NSScrollView , and its helperNSClipView , provide a scrolling mechanism as well as the graphic objects thatlet the user initiate and control a scroll.

Controlling an ApplicationThe NSControl and NSCell classes, and their subclasses, define an easilyrecognized set of buttons, sliders, and browsers that the user can manipulategraphically to control some aspect of your application. Just what a particularcontrol affects is up to you: When a control is “touched,” it sends a specificmessage to a specific object. This is the targeted/action paradigm; for eachNSControl , you define both the target (an object) and the action (the messagethat’s sent to that object).

An NSCell completes the implementation of an NSControl . In general, foreach NSControl there is a corresponding NSCell ; thus a button comprises aNSButton and an NSButtonCell , a slider is an NSSlider and anNSSliderCell , and so on.

Text and Fonts 1-3

1

Text and FontsMost applications display text in some form. The NSCStringText andNSTextField classes make this presentation as straightforward and simple aspossible. The size of the NSCStringText class is daunting at first, but forsimple text presentation only a handful of methods are actually needed (or youcan use the streamlined NSTextField class). More complicated text-basedapplications, such as word processors, can take advantage of theNSCStringText class’ more sophisticated features, such as rulers and breaktables.

The NSFont and NSFontManager classes encapsulate and manage differentfont families, sizes, and variations. The NSFont class defines a single object foreach distinct font. For efficiency, these objects, which can be large, are shared byall the objects in your application. The NSFontPanel class defines the font-specification panel that’s presented to the user.

Graphics and ColorThe NSImage, NSImageRep, and the other image representation classesencapsulate graphic data, allowing you to easily and efficiently access imagesstored in files on the disk. The presentation of an image is greatly influenced bythe hardware that it’s displayed on. For example, a particular image may lookgood on a color monitor, but may be too “rich” for monochrome. Through theimage classes, you can group representations of the same image, where eachrepresentation fits a specific type of display device—the decision of whichrepresentation to use can be left to the NSImage class itself.

Colors are represented by the NSColor class. Applications incorporate andsupport colors by using the NSColorPanel , NSColorList , NSColorPicker ,and NSColorWell classes. These classes let the user to select and apply colors.The NSColorPicking protocol lets you extend the standard color panel.

The four standard color formats—RGB, CMYK, HSB, and grayscale—arerecognized by the color classes. You can also tell the classes to recognize customrepresentations.


1

Printing and FaxingThe NSPrinter , NSPageLayout , and NSPrintInfo classes work together toprovide the means for printing and faxing the information that your applicationdisplays in its NSWindows and NSViews. For more control, the NSWindow andNSView classes define methods that can fine-tune the printing and faxingmechanism.

Accessing the File SystemThe Application Kit does not provide a class that defines objects to correspond tofiles on the disk. However, the NSOpenPanel and NSSavePanel provide aconvenient and familiar user interface to the file system.

Sharing Data with Other ApplicationsThe NSPasteboard class defines a repository for data that’s copied from yourapplication, making this data available to any application that cares to use it.This is the familiar cut-copy-paste mechanism. The NSServicesRequestprotocol uses the NSPasteboard to communicate data that’s passed betweenapplications by a registered service.

An intimate link between applications can be created through the NSDataLink ,NSDataLinkManager , NSDataLinkPanel , and NSSelection classes.Through these classes, multiple applications can share the same data. A changeto the data in one application is seen immediately in all others that display thatdata.

Spell-CheckingThe NSSpellServer class lets you define a spell-checking facility and provideit as a service to other applications. To connect your application to a spellingchecker, you use the NSSpellChecker class. TheNSIgnoreMisspelledWords , and NSChangeSpelling protocols support thespell-checking mechanism.

Application Kit Class Hierarchy 1-5

1

Application Kit Class HierarchyThe Application Kit contains over 60 classes which inherit directly or indirectlyfrom NSObject , the root class defined in the Foundation Kit. The followingdiagram shows the Application Kit’s class inheritance relationships.


1

Figure 1-1 Application Kit Classes

NSObject

NSCell

NSColor

NSColorList

NSColorPicker

NSCursor

NSDataLink

NSDataLinkManager

NSEvent

NSFont

NSFontManager

NSImageRep

NSImage

NSPasteboard

NSPrintInfo

NSPrintOperation

NSPrinter

NSResponder

NSScreen

NSSelection

NSSpellChecker

NSSpellServer

NSWorkspace

NSActionCell

NSBrowserCell

NSBitmapImageRep

NSCachedImageRep

NSCustomImageRep

NSEPSImageRep

NSApplication

NSView

NSWindow

NSButtonCell

NSFormCell

NSSliderCell

NSTextFieldCell

NSBox

NSClipView

NSControl

NSScrollView

NSSplitView

NSText

NSPanel

NSMenuCell

NSBrowser

NSButton

NSColorWell

NSMatrix

NSSlider

NSScroller

NSTextField

NSCStringText

NSColorPanel

NSDataLinkPanel

NSFontPanel

NSHelpPanel

NSMenu

NSPageLayout

NSSavePanel

NSPopUpButton

NSForm

NSOpenPanel

NSActionCell 1-7

1

NSActionCell

Class Description

An NSActionCell defines an active area inside a control (an instance ofNSControl or one of its subclasses). As an NSControl ’s active area, anNSActionCell does three things: it usually performs display of text or an icon(the subclass NSSliderCell is an exception); it provides the NSControl witha target and an action; and it handles mouse (cursor) tracking by properlyhighlighting its area and sending action messages to its target based on cursormovement. The only way to specify the NSControl for a particularNSActionCell is to send the NSActionCell a drawWithFrame:inView:message, passing the NSControl as the argument for the inView: keyword ofthe method.

NSActionCell implements the target object and action method as defined byits superclass, NSCell . As a user manipulates an NSControl ,NSActionCell ’s trackMouse:inRect:ofView:untilMouseUp: method(inherited from NSCell ) updates its appearance and sends the action messageto the target object with the NSControl object as the only argument.

Usually, the responsibility for an NSControl ’s appearance and behavior iscompletely given over to a corresponding NSActionCell . (NSMatrix , and itssubclass NSForm, are NSControl s that don’t follow this rule.)

A single NSControl may have more than one NSActionCell . To helpidentify it in this case, every NSActionCell has an integer tag. Note, however,that no checking is done by the NSActionCell object itself to ensure that thetag is unique. See the NSMatrix class for an example of a subclass ofNSControl that contains multiple NSActionCell s.

Many of the methods that define the contents and look of an NSActionCell ,such as setFont: and setBordered: , are reimplementations of methodsinherited from NSCell . They are subclassed to ensure that the NSActionCellis redisplayed if it’s currently in an NSControl .

Inherits From: NSCell : NSObject

Conforms To: NSCoding, NSCopying (NSCell),NSObject (NSObject)

Declared In: AppKit/NSActionCell.h


1

Method Types

Instance Methods

action

– (SEL)action

Returns the action cell’s action method. Keep in mind that the argument of anaction method sent by an action cell is its associated NSControl (the objectreturned by controlView ). See also setAction: , target , controlView .

controlView

– (NSView *)controlView

Returns the view (normally an NSControl ) in which the action cell was lastdrawn. In general, your code should use the object returned by this methodonly to redisplay indirectly the action cell. For example, the subclasses ofNSActionCell defined by the Application Kit invoke this method in order to


Configuring an NSActionCell – setAlignment:– setBezeled:– setBordered:– setEnabled:– setFloatingPointFormat:left:right:– setFont:– setImage:

Manipulating NSActionCellValues – doubleValue– floatValue– intValue– setStringValue:– stringValue

Displaying – drawWithFrame:inView:– controlView

Target and action – action– setAction:– setTarget:– target

Assigning a tag – setTag:– tag

NSActionCell 1-9

1

send the NSControl a message such as updateCellInside: . TheNSControl in which an action cell is drawn is set automatically by thedrawWithFrame:inView: method. You can’t explicitly set the NSControl .See also drawWithFrame:inView: .

doubleValue

– (double)doubleValue

Returns the action cell’s contents as a double-precision floating point number.If the action cell is being edited when this message is received, editing isvalidated first. See also setDoubleValue: (NSCell ), floatValue ,intValue , stringValue , validateEditing (NSControl ).

drawWithFrame:inView:

– (void)drawWithFrame:(NSRect)cellFrameinView:(NSView *)controlView

Draws the action cell in the rectangle cellFrame of controlView (whichshould normally be an NSControl ). This sets the action cell’s control tocontrolView and performs the drawing if and only if controlView is anNSControl object (an instance of NSControl or a subclass thereof). Focusmust be locked on the NSControl before invoking this method. TheNSControl automatically performs this locking. See alsodrawWithFrame:inView: (NSCell ).

floatValue

– (float)floatValue

Returns the action cell’s contents as a single-precision floating point number. Ifthe action cell is being edited when this message is received, editing isvalidated first. See also setFloatValue: (NSCell ), doubleValue ,intValue , stringValue , validateEditing (NSControl ).

intValue

– (int)intValue


1

Returns the action cell’s contents as an integer. If the action cell is being editedwhen this message is received, editing is validated first. See alsosetIntValue: (NSCell ), doubleValue , floatValue , stringValue ,validateEditing (NSControl ).

setAction:

– (void)setAction:(SEL)aSelector

Sets the action cell’s action method to aSelector . The argument of an actionmethod sent by an action cell is its associated NSControl (the object returnedby controlView ). See also action , setTarget: , controlView ,sendAction:to: (NSControl ).

setAlignment:

– (void)setAlignment:(NSTextAlignment)mode

If the action cell is a text cell (type NSTextCellType ), this method sets its textalignment mode to mode, which should be one of the following enumerationconstants:

• NSLeftTextAlignment• NSRightTextAlignment• NSCenterTextAlignment• NSJustifiedTextAlignment• NSNaturalTextAlignment

If it’s currently in an NSControl view, the action cell is redisplayed or markedas needing redisplay. See also alignment (NSCell ).

setBezeled:

– (void)setBezeled:(BOOL)flag

Adds or removes the action cell’s bezel, according to the value of flag .Adding a bezel removes the action cell’s border, if any. If it’s currently in anNSControl view, the action cell is redisplayed or marked as needing redisplay.See also isBezeled (NSCell ), setBordered: .

NSActionCell 1-11

1

setBordered:

– (void)setBordered:(BOOL)flag

Adds or removes the action cell’s border, according to the value of flag . Theborder is black and has a width of 1.0. Adding a border removes the actioncell’s bezel, if any. If it’s currently in an NSControl view, the action cell isredisplayed or marked as needing redisplay. See also isBordered (NSCell ),setBezeled: .

setEnabled:

– (void)setEnabled:(BOOL)flag

Enables or disables the action cell’s ability to receive mouse and keyboardevents, according to the value of flag . If it’s currently in an NSControl view,the action cell is redisplayed or marked as needing redisplay. See alsoisEnabled (NSCell ).

setFloatingPointFormat:left:right:

– (void)setFloatingPointFormat:(BOOL)autoRangeleft:(unsigned int)leftDigits right:(unsigned int)rightDigits

Sets the action cell’s floating point format as described in the NSCell classspecification for the setFloatingPointFormat:left:right: method. Ifit’s currently in an NSControl view, the action cell is redisplayed or marked asneeding redisplay. See also setFloatingPointFormat:left:right:(NSCell ).

setFont:

– (void)setFont:(NSFont *)fontObject

Sets the action cell’s font to fontObject . If the action cell is a text cell (typeNSTextCellType ), this method sets its font to fontObject . In addition, if it’scurrently in an NSControl view, the action cell is redisplayed or marked asneeding redisplay. See also font (NSCell ).

setImage:

– (void)setImage:(NSImage *)image


1

Sets the action cell’s icon to image and sets its NSCell type toNSImageCellType . If it’s currently in an NSControl view, the action cell isredisplayed or marked as needing redisplay. See also setImage: (NSCell ).

setStringValue:

– (void)setStringValue:(NSString *)aString

Sets the action cell’s contents to a copy of aString . If it’s currently in anNSControl view, the action cell is redisplayed or marked as needing redisplay.See also setStringValue: (NSCell ), stringValue , doubleValue ,floatValue , intValue .

setTag:

– (void)setTag:(int)anInt

Sets the action cell’s tag to anInt . The tag can be used to identify the actioncell in an NSControl that contains multiple NSCell s (an NSMatrix , forexample). See also tag , setTag: (NSControl ).

setTarget:

– (void)setTarget:(id)anObject

Sets the action cell’s target object to anObject . This is the object that is sentthe action cell’s action method. See also target , setAction: .

stringValue

– (NSString *)stringValue

Returns the action cell’s contents as an NSString object. If the action cell isbeing edited when this message is received, editing is validated first. See alsosetStringValue: , stringValue (NSCell ), validateEditing(NSControl ), doubleValue , floatValue , intValue .

tag

– (int)tag

NSApplication 1-13

1

Returns the action cell’s tag. The tag can be used to identify the action cell inan NSControl that contains multiple NSCell s (an NSMatrix , for example).See also setTag: , tag (NSControl ).

target

– (id)target

Returns the action cell’s target object (the object that receives the action cell’saction method). See also setTarget: , action .

NSApplication

Class Description

The NSApplication class provides the central framework for yourapplication’s execution. Every application must have exactly one instance ofNSApplication (or of a custom subclass of NSApplication ). Yourprogram’s main() function should create this instance by calling thesharedApplication class method. (Alternatively, you could use alloc andinit , making sure they’re called only once.) After creating theNSApplication , the main() function should load your application’s mainnib file, and then start the event loop by sending the NSApplication a runmessage. Here’s an example of a typical OpenStep main() function in itsentirety:

void main(int argc, char *argv[]) {NSApplication *app = [NSApplication sharedApplication];[NSBundle loadNibNamed:@"myMain" owner:app];[app run];

}

Inherits From: NSResponder : NSObject

Conforms To: NSCoding (NSResponder),NSObject (NSObject)

Declared In: AppKit/NSApplication.hAppKit/NSColorPanel.hAppKit/NSDataLinkPanel.hAppKit/NSHelpPanel.hAppKit/NSPageLayout.h


1

Creating the NSApplication object connects the program to the windowsystem and the Display PostScript server, and initializes its PostScriptenvironment. The NSApplication object maintains a list of all the NSWindowsthat the application uses, so it can retrieve any of the application’s NSViews.

The NSApplication object’s main task is to receive events from the windowsystem and distribute them to the proper NSResponder s. TheNSApplication translates an event into an NSEvent object, then forwards theNSEvent to the affected NSWindow object. A key-down event that occurs whilethe Command key is pressed results in a performKeyEquivalent: message,and every NSWindow has an opportunity to respond to it. Other keyboard andmouse events are sent to the NSWindow associated with the event; theNSWindow then distributes these NSEvent s to the objects in its view hierarchy.

In general, it’s neater and cleaner to separate the code that embodies yourprogram’s functionality into a number of custom objects. Usually those customobjects are subclasses of NSObject . Methods defined in your custom objectscan be invoked from a small dispatcher object without being closely tied to theNSApplication object. It’s rarely necessary to create a custom subclass ofNSApplication . You will need to do so only if you need to provide your ownspecial response to messages that are routinely sent to the NSApplicationobject. To use a custom subclass of NSApplication , simply substitute it forNSApplication in the main() function above.

When you create an instance of NSApplication (or of a custom subclass ofNSApplication ), it gets stored as the global variable NSApp. Although thisglobal variable isn’t used in the example main() function above, you mightfind it convenient to refer to NSApp within the source code for yourapplication’s custom objects. Note that you can also retrieve theNSApplication object by invoking sharedApplication .

The NSApplication class sets up autorelease pools during initialization andduring the event loop—that is, within its init (or sharedApplication ) andrun methods. Similarly, the methods that the Application Kit adds toNSBundle employ autorelease pools during the loading of nib files. Theautorelease pools aren’t accessible outside the scope of the respectiveNSApplication and NSBundle methods. This isn’t usually a problem,because a typical OpenStep application instantiates its objects by loading nibfiles (and by having the objects from the nib file create other objects duringinitialization and during the event loop). However, if you do need to useOpenStep classes within the main() function itself (other than to invoke themethods just mentioned), you should instantiate an autorelease pool before

NSApplication 1-15

1

using the classes, and then release the pool once you’re done. For moreinformation, see the description of the NSAutoreleasePool class in theFoundation Kit section of this book.

The Delegate and Observers

The NSApplication object can be assigned a delegate that responds on behalfof the NSApplication to certain messages addressed to the NSApplicationobject. Some of these messages, such asapplication:openFile:withType: , ask the delegate to open a file.Another message, applicationShouldTerminate: , lets the delegatedetermine whether the application should be allowed to quit.

An NSApplication can also have observers. Observers receive notifications ofchanges in the NSApplication , but they don’t have the unique responsibilitythat a delegate has. Any instance of a class that implements an observermethod can register to receive the corresponding notification. For example, if aclass implements applicationDidFinishLaunching: and registers toreceive the corresponding notification, instances of this class are given anopportunity to react after the NSApplication has been initialized. Theobserver methods are listed later in this class specification. For informationabout how to register to receive notifications, see the class specification for theFoundation Kit’s NSNotificationCenter class.

There can be only one delegate, but there can be many observers. The delegateitself can be an observer—in fact, in many applications the delegate might bethe only observer. Most observers need to explicitly register with anNSNotificationCenter before they can receive a particular notificationmessage, but the delegate only needs to implement the method. By simplyimplementing an observer method, the NSApplication ’s delegate isautomatically registered to receive the corresponding notification.


1

Method Types


Creating and initializing theNSApplication

+ sharedApplication– finishLaunching

Changing the active application – activateIgnoringOtherApps:– deactivate– isActive

Running the event loop – abortModal– beginModalSessionForWindow:– endModalSession:– isRunning– run– runModalForWindow:– runModalSession:– sendEvent:– stop:– stopModal– stopModalWithCode:

Getting, removing, and postingevents

– currentEvent– postEvent:atStart:– discardEventsMatchingMask:beforeEvent:– nextEventMatchingMask:untilDate:inMode:dequeue:

Sending action messages – sendAction:to:from:– targetForAction:– tryToPerform:with:

Setting the application’s icon – setApplicationIconImage:– applicationIconImage

Hiding all windows – hide:– isHidden– unhide:– unhideWithoutActivation

Managing windows – keyWindow– mainWindow– makeWindowsPerform:inOrder:– miniaturizeAll:– preventWindowOrdering– setWindowsNeedUpdate:– updateWindows– windows– windowWithWindowNumber:

NSApplication 1-17

1

Showing standard panels – orderFrontColorPanel:– orderFrontDataLinkPanel:– orderFrontHelpPanel:– runPageLayout:

Getting the main menu – mainMenu– setMainMenu:

Managing the Windows menu – addWindowsItem:title:filename:– arrangeInFront:– changeWindowsItem:title:filename:– removeWindowsItem:– setWindowsMenu:– updateWindowsItem:– windowsMenu

Managing the Services menu – registerServicesMenuSendTypes:returnTypes:– servicesMenu– setServicesMenu:– servicesProvider– setServicesProvider:– validRequestorForSendType:returnType:

Getting the Display PostScriptcontext

– context

Reporting an exception – reportException:

Terminating the application – terminate:

Assigning a delegate – delegate– setDelegate:

Methods Implemented by theDelegate

– applicationDidBecomeActive:– applicationDidFinishLaunching:– applicationDidHide:– applicationDidResignActive:– applicationDidUnhide:– applicationDidUpdate:– application:openFile:– application:openFileWithoutUI:– application:openTempFile:– applicationOpenUntitledFile:– applicationShouldTerminate:– applicationWillBecomeActive:– applicationWillFinishLaunching:– applicationWillHide:– applicationWillResignActive:– applicationWillTerminate:– applicationWillUnhide:– applicationWillUpdate:



1

Class Methods

sharedApplication

+ (NSApplication *)sharedApplication

Returns the NSApplication instance, creating it if it doesn’t yet exist.

Instance Methods

abortModal

– (void)abortModal

Aborts the modal event loop by raising the exceptionNSAbortModalException , which is caught by runModalForWindow: , themethod that started the modal loop. Since this method raises an exception, itnever returns; runModalForWindow: , when stopped with this method,returns the enumeration constant NSRunAbortedResponse . Note that youcan’t use this method to abort modal sessions where you control the modalloop and periodically invoke runModalSession: . See alsorunModalSession: , endModalSession: , stopModal ,stopModalWithCode: .

activateIgnoringOtherApps:

– (void)activateIgnoringOtherApps:(BOOL)flag

Makes the receiving application the active application. If flag is NO, theapplication is activated only if no other application is currently active.Normally, this method is invoked with flag set to NO. When the WorkspaceManager launches an application, it deactivates itself, soactivateIgnoringOtherApps:NO allows the application to become active ifthe user waits for it to launch, but the application remains unobtrusive if theuser activates another application. If flag is YES, the application will alwaysactivate. Regardless of the setting of flag , there may be a time lag before theapplication activates; you should not assume that the application will be activeimmediately after sending this message.

NSApplication 1-19

1

Note – You can make one of your NSWindows the key window withoutchanging the active application; when you send a makeKeyWindow message toan NSWindow object, you simply ensure that the NSWindow object will be thekey window when the application is active.

You should rarely need to invoke this method. Under most circumstances theApplication Kit takes care of proper activation. However, you might find thismethod useful if you implement your own methods for interapplicationcommunication. See also deactivate .

addWindowsItem:title:filename:

– (void)addWindowsItem:(NSWindow *)aWindowtitle:(NSString *)aStringfilename:(BOOL)isFilename

Adds an item to the Windows menu corresponding to the window objectaWindow. If isFilename is NO, aString appears literally in the menu. IfisFilename is YES, aString is assumed to be a converted name with thename of the file preceding the path (the way NSWindow’ssetTitleWithRepresentedFilename: method shows a title). If an item foraWindow already exists in the Windows menu, this method has no effect. Yourarely invoke this method because an item is placed in the Windows menu foryou whenever a window object’s title is set. See alsochangeWindowsItem:title:filename: ,setTitleWithRepresentedFilename: (NSWindow).

applicationIconImage

– (NSImage *)applicationIconImage

Returns the NSImage used for the application’s icon. See alsosetApplicationIconImage: .

arrangeInFront:

– (void)arrangeInFront:(id)sender


1

Arranges all of the windows listed in the Windows menu in front of all otherwindows. Windows associated with the application but not listed in theWindows menu are not ordered to the front. See also removeWindowsItem: ,orderFront: (NSWindow).

beginModalSessionForWindow:

– (NSModalSession)beginModalSessionForWindow:(NSWindow *)theWindow

Prepares the application for a modal session with theWindow . In other words,this method prepares the application so that mouse events get to it only if theyoccur in theWindow . theWindow is made the key window and ordered to thefront. The return value is a structure that stores information used by the systemduring a modal session. This structure is allocated by the method and is meantto be used to refer to the session. The application should not access any of thefields of this structure.

The method beginModalSessionForWindow: should be balanced byendModalSession: . If an exception is raised,beginModalSessionForWindow: arranges for proper cleanup. Do not useNS_DURING constructs to send an endModalSession: message in the event ofan exception. See also runModalSession: , endModalSession: .

changeWindowsItem:title:filename:

– (void)changeWindowsItem:(NSWindow *)aWindowtitle:(NSString *)aStringfilename:(BOOL)isFilename

Changes the item for aWindow in the Windows menu to aString . If aWindowdoesn’t have an item in the Windows menu, this method adds the item. IfisFilename is NO, aString appears literally in the menu. If isFilename isYES, aString is assumed to be a converted name with the file’s namepreceding the path (the way NSWindow’ssetTitleWithRepresentedFilename: places a title). See alsoaddWindowsItem:title:filename: ,setTitleWithRepresentedFilename: (NSWindow).

context

– (NSDPSContext *)context

NSApplication 1-21

1

Returns the NSApplication ’s Display PostScript context. See alsoNSDPSContext .

currentEvent

– (NSEvent *)currentEvent

Returns a pointer to the last event the NSApplication object retrieved fromthe event queue. A pointer to the current event is also passed with every eventmessage.

deactivate

– (void)deactivate

Deactivates the application if it’s active. Normally, you shouldn’t invoke thismethod; the Application Kit is responsible for proper deactivation. See alsoactivateIgnoringOtherApps: .

delegate

– (id)delegate

Returns the NSApplication ’s delegate. See also setDelegate: .

discardEventsMatchingMask:beforeEvent:

– (void)discardEventsMatchingMask:(unsigned int)maskbeforeEvent:(NSEvent *)lastEvent

Removes from the event queue all events matching mask that were generatedbefore lastEvent . If lastEvent is nil , all events matching mask areremoved from the queue.

endModalSession:

– (void)endModalSession:(NSModalSession)session

Finishes and cleans up after a modal session. The argument session shouldbe taken from a previous invocation of beginModalSession:for: . See alsorunModalSession: , beginModalSessionForWindow: .


1

finishLaunching

– (void)finishLaunching

Activates the application, opens any files specified by the “NSOpen” userdefault, and unhighlights the application’s icon in the Workspace Manager.This method is invoked by run before it starts the event loop. When thismethod begins, it posts the notificationNSApplicationWillFinishLaunchingNotification with the receivingobject to the default notification center. When it successfully completes, it poststhe notification NSApplicationDidFinishLaunchingNotification . Ifyou override finishLaunching , the subclass method should invoke thesuperclass method.

hide:

– (void)hide:(id)sender

Collapses the application’s graphics—including all its windows, menus, andpanels—into a single small window. The hide: message is usually sent usingthe Hide command in the application’s main Menu. When this method begins,it posts the notification NSApplicationWillHideNotification with thereceiving object to the default notification center. When it completessuccessfully, it posts the notification NSApplicationDidHideNotification .See also unhide: .

isActive

– (BOOL)isActive

Returns YES if the application is currently active, and NO if it isn’t. See alsoactivateIgnoringOtherApps: .

isHidden

– (BOOL)isHidden

Returns YES if the application is currently hidden, and NO if it isn’t.

isRunning

– (BOOL)isRunning

NSApplication 1-23

1

Returns YES if the application is running, and NO if the stop: method hasended the main event loop. See also run , stop: , terminate: .

keyWindow

– (NSWindow *)keyWindow

Returns the key NSWindow, that is, the NSWindow that receives keyboardevents. If there is no key NSWindow, or if the key NSWindow belongs to anotherapplication, this method returns nil . See also mainWindow , isKeyWindow(NSWindow).

mainMenu

– (NSMenu *)mainMenu

Returns the id of the application’s main menu. See also NSMenu.

mainWindow

– (NSWindow *)mainWindow

Returns the application’s main window. See also NSWindow.

makeWindowsPerform:inOrder:

– (NSWindow *)makeWindowsPerform:(SEL)aSelector inOrder:(BOOL)flag

Sends the application object’s NSWindows a message to perform theaSelector method. The message is sent to each NSWindow in turn until oneof them returns YES; the method then returns a pointer to that window. If noNSWindow returns YES, the method returns nil . If flag is YES, the applicationobject’s NSWindows receive the aSelector messages in the front-to-back orderin which they appear in the Window Server’s window list. If flag is NO, theNSWindows receive the messages in the order they appear in the applicationobject’s window list. This order generally reflects the order in which theNSWindows were created. The method designated by aSelector can’t takeany arguments.

miniaturizeAll:

– (void)miniaturizeAll:(id)sender


1

Miniaturizes all the receiver’s application windows.

nextEventMatchingMask:untilDate:inMode:dequeue:

– (NSEvent *)nextEventMatchingMask:(unsigned int)maskuntilDate:(NSDate *)expiration inMode:(NSString *)modedequeue:(BOOL)flag

Returns the next event matching mask, or nil if no such event is found beforethe expiration date. If flag is YES, the event is removed from the queue.The mode argument names an NSRunLoop mode that determines what otherports are listened to and what timers may fire while the application is waitingfor the event.

orderFrontColorPanel:

– (void)orderFrontColorPanel:(id)sender

Brings up the color panel.

orderFrontDataLinkPanel:

– (void)orderFrontDataLinkPanel:(id)sender

Shows the shared instance of the data link panel, creating it first if necessary.Note that this method is not part of the OpenStep specification.

orderFrontHelpPanel:

– (void)orderFrontHelpPanel:(id)sender

Shows the application’s help panel or the default help panel. Note that thismethod is not part of the OpenStep specification.

postEvent:atStart:

– (void)postEvent:(NSEvent *)event atStart:(BOOL)flag

Adds event to the front of the application’s event queue if flag is YES, or tothe back of the queue otherwise.

NSApplication 1-25

1

preventWindowOrdering

– (void)preventWindowOrdering

Suppresses the usual window ordering in handling the most recentmouse-down event. Most applications will not need to use this method sincethe Application Kit support for dragging will call this method when draggingis initiated.

registerServicesMenuSendTypes:returnTypes:

– (void)registerServicesMenuSendTypes:(NSArray *)sendTypesreturnTypes:(NSArray *)returnTypes

Registers pasteboard types that the application can send and receive inresponse to service requests. If the application has a Services menu, a menuitem is added for each service provider that can accept one of the specifiedsend types or return one of the specified return types. This method shouldtypically be invoked at application startup time or when an object that can useservices is created. It can be invoked more than once; its purpose is to ensurethat there is a menu item for every service that the application may use. Theindividual items will be dynamically enabled and disabled by the eventhandling mechanism to indicate which services are currently appropriate. Anapplication (or object instance that can cut or paste) should register everypossible type that it can send and receive. See alsovalidRequestorForSendType:returnType: (NSResponder ),readSelectionFromPasteboard: (NSCStringText ),writeSelectionToPasteboard:types: (NSCStringText ),NSPasteboard .

removeWindowsItem:

–(void)removeWindowsItem:(NSWindow *)aWindow

Removes the item for aWindow in the Windows menu. Note that this methoddoesn’t prevent the item from being automatically added again, so you mustuse NSWindow’s setExcludedFromWindowsMenu: method if you want theitem to remain excluded from the Windows menu. See alsochangeWindowsItem:title:filename: ,setExcludedFromWindowsMenu: (NSWindow).


1

reportException:

– (void)reportException:(NSException *)anException

Logs the given exception by calling NSLog() (Foundation Kit Functions).

run

– (void)run

Initiates the application object’s main event loop. The loop continues until astop: or terminate: message is received. Each iteration through the loop,the next available event from the Window Server is stored, and is thendispatched by sending the event to the application object using sendEvent: .A run message should be sent as the last statement from main() , after theapplication’s objects have been initialized. This method returns if it isterminated by stop: , but never returns if it is terminated by terminate: . Seealso runModalForWindow: , sendEvent: , stop: , terminate: .

runModalForWindow:

– (int)runModalForWindow:(NSWindow *)theWindow

Establishes a modal event loop for theWindow . Until the loop is broken by astopModal , stopModalWithCode: , or abortModal message, the applicationwon’t respond to any mouse, keyboard, or window-close events unless they’reassociated with theWindow . If stopModalWithCode: is used to stop themodal event loop, this method returns the argument passed tostopModalWithCode: . If stopModal is used, it returns the constantNSRunStoppedResponse . If abortModal is used, it returns the constantNSRunAbortedResponse . This method is functionally similar to the followingcode:

NSWindow *theWindow;NSModalSession session;

session = [NSApp beginModalSessionForWindow:theWindow];for (;;) { if ([NSApp runModalSession:session] != NSRunContinuesResponse) break;}[NSApp endModalSession:session];

NSApplication 1-27

1

See also stopModal , stopModalWithCode: , abortModal ,runModalSession: .

runModalSession:

– (int)runModalSession:(NSModalSession)session

Runs a modal session represented by session , as defined in a previousinvocation of beginModalSessionForWindow: . A loop using this method issimilar to a modal event loop run with runModalForWindow: except that theapplication can continue processing between method invocations. When youinvoke this method, events for the NSWindow of this session are dispatched asnormal. This method returns when there are no more events. You must invokethis method frequently enough that the window remains responsive to events.

If the modal session was not stopped, this method returnsNSRunContinuesResponse . If stopModal was invoked as the result of eventprocessing, NSRunStoppedResponse is returned. If stopModalWithCode:was invoked, this method returns the value passed to stopModalWithCode: .The NSAbortModalException exception raised by abortModal isn’t caught.See also beginModalSessionForWindow:, endModalSession: , stopModal ,stopModalWithCode: .

runPageLayout:

– (void)runPageLayout:(id)sender

Brings up the application object’s Page Layout panel, which allows the user toselect the page size and orientation.

sendAction:to:from:

– (BOOL)sendAction:(SEL)aSelector to:(id)aTarget from:(id)sender

Sends an action message to the object aTarget . If aTarget is nil , theapplication object looks for an object that can respond to the message—that is,for an object that implements a method matching aSelector . It begins withthe first responder of the key window. If the first responder can’t respond, ittries the first responder’s next responder, and continues following nextresponder links up the NSResponder chain. If none of the objects in the keywindow’s responder chain can handle the message, the application objectattempts to send the message to the key NSWindow’s delegate.


1

If the delegate doesn’t respond and the main window is different from the keywindow, NSApp begins again with the first responder in the main window. Ifobjects in the main window can’t respond, the NSApplication objectattempts to send the message to the main window’s delegate. If still no objecthas responded, NSApp tries to handle the message itself. If NSApp can’trespond, it attempts to send the message to its own delegate. This methodreturns YES if the action is applied; otherwise it returns NO.

sendEvent:

– (void)sendEvent:(NSEvent *)theEvent

Sends an event to the application object. You rarely send sendEvent:messages directly although you might want to override this method to performsome action on every event. The sendEvent: messages are sent from the mainevent loop (the run method). This method dispatches events to theappropriate responders: the application object handles application events; theNSWindow indicated in the event record handles window related events; andmouse and key events are forwarded to the appropriate NSWindow for furtherdispatching.

When sending the activate application event, this method posts thenotifications NSApplicationWillBecomeActive andNSApplicationDidBecomeActive with the receiving object to the defaultnotification center. When sending the deactivate application event, it posts theNSApplicationWillResignActiveNotification andNSApplicationDidResignActiveNotification notifications with thereceiving object to the default notification center.

servicesMenu

– (NSMenu *)servicesMenu

Returns the application object’s Services menu. Returns nil if no Servicesmenu has been created. See also setServicesMenu: .

servicesProvider

- (id)servicesProvider

NSApplication 1-29

1

Returns the application’s services provider application. The services providerapplication responds to remote messages sent from the Services menus of otherapplications. The services provider application should contain methods that aservice-providing application uses to give services to other applications. See alsosetServicesProvider: , NSRegisterServicesProvider() .

setApplicationIconImage:

– (void)setApplicationIconImage:(NSImage *)anImage

Sets the application’s icon to anImage . See also applicationIconImage .

setDelegate:

– (void)setDelegate:(id)anObject

Makes anObject the application’s delegate. The notification messages that adelegate can expect to receive are listed under “Methods Implemented by theDelegate” on page -34. The delegate doesn’t need to implement all themethods. See also delegate .

setMainMenu:

– (void)setMainMenu:(NSMenu *)aMenu

Makes aMenu the application’s main menu. See also mainMenu .

setServicesMenu:

– (void)setServicesMenu:(NSMenu *)aMenu

Makes aMenu the application object’s Services menu. See also servicesMenu .

setServicesProvider:

- (id)setServicesProvider:(id)provider

Registers the service provider application that will respond to remote messages.Applications registered with this method should create an NSApplicationobject. See also servicesProvider , NSRegisterServicesProvider() .


1

setWindowsMenu:

– (void)setWindowsMenu:(id)aMenu

Makes aMenu the application object’s Windows menu. See also windowsMenu .

setWindowsNeedUpdate:

– (void)setWindowsNeedUpdate:(BOOL)flag

Sets whether the application’s windows need updating when the applicationhas finished processing the current event. This method is especially useful formaking sure menus are updated to reflect changes not initiated by user actions.

stop:

– (void)stop:(id)sender

Stops the main event loop. This method will break the flow of control out ofthe run method, thereby returning to the main() function. A subsequent runmessage will restart the loop. If this method is applied during a modal eventloop, it will break that loop but not the main event loop. See also terminate: ,run , runModalSession: .

stopModal

– (void)stopModal

Stops a modal event loop. This method should always be paired with aprevious runModalForWindow: or beginModalSessionForWindow:message. When runModalForWindow: is stopped with this method, it returnsNSRunStoppedResponse . This method will stop the loop only if it’s executedby code responding to an event. See also stopModalWithCode: ,runModalSession: , abortModal .

stopModalWithCode:

– (void)stopModalWithCode:(int)returnCode

This method is similar to stopModal except that the argument returnCodeallows you to specify the value that runModalForWindow: will return. Seealso stopModal , abortModal .

NSApplication 1-31

1

targetForAction:

– (id)targetForAction:(SEL)aSelector

Returns the object that receives the action message aSelector .

terminate:

– (void)terminate:(id)sender

Frees the application object and exits the application. This is the default actionmethod for the application’s Quit menu item. Each use of terminate:invokes applicationShouldTerminate: to notify the delegate that theapplication is about to terminate. If applicationShouldTerminate: returnsNO, control is returned to the main event loop, and the application isn’tterminated. Otherwise, this method frees the application object and terminatesthe application.

Note – You should not put final cleanup code in your application’s main()function; it will never be executed.

See also stop: , applicationShouldTerminate: (delegate method).

tryToPerform:with:

– (BOOL)tryToPerform:(SEL)aSelector with:(id)anObject

Aids in dispatching action messages. The application object tries to performthe method aSelector using its inherited NSResponder methodtryToPerform:with: . If the application object doesn’t perform aSelector ,the object’s delegate is given the opportunity to perform it using its inheritedNSObject method performSelector:object:afterDelay: . If either theapplication object or the application object’s delegate accept aSelector , thismethod returns YES; otherwise it returns NO. See also tryToPerform:with:(NSResponder ), instancesRespondToSelector: (NSObject ),performSelector:object:afterDelay: (NSObject ).

unhide:

– (void)unhide:(id)sender


1

Restores a hidden application to its former state

OpenStep Programming Reference - Oracle Cloud2550 Garcia Avenue Mountain View, CA 94043 U.S.A. OpenStep Programming Reference Part No 802-2112-10 Revision A, September 1996 A Sun Microsystems,

Documents