This is NSSelection.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSSelection
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding, NSCopying
fi0 NSObject (NSObject)
fs20
fs28 s7 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSSelection.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 The NSSelection class defines an object that describes a selection within a document. An NSSelection, or simply, selection, is an immutable description; it may be held by the system or other documents, and it cannot change over time. Selections are typically used by NSDataLink objects to represent the source and destination of a link.
fs16
fs28 Because a selection description can'27t be changed once it'27s been exported, it'27s a good idea to construct general descriptions that can survive changes to a document and don'27t require selection-specific information to be stored in the document. This description may be simple or complex, depending upon the application. For example, a painting application might describe a selection in an image as a simple rectangle. This description doesn'27t require that any information be stored in the image'27s file, and the description can be expected to remain valid through the life of the image. An object-based drawing application might describe a selection as a list of object identifiers (though i noti0 b idb0 s), where an object identifier is unique throughout the life of the document. Based on this list, a selection could be meaningfully reconstructed, even if new objects are added to the document or selected objects are deleted. Such a scheme doesn'27t require that any selection-specific information be stored in the document'27s file, with the benefit that links can be made to read-only documents.
fs16
fs28 Maintaining a character-range selection in a text document is more problematic. A possible solution is to insert selection-begin and selection-end markers that define a specific selection into the text stream. A selection description would then refer to a specific selection marker. This solution requires that selection state information be stored and maintained within the document. Furthermore, this information generally shouldn'27t be purged from the document, because the document can'27t know how many references to the selection exist. (References to the selection could be stored with documents on removable media, like floppy disks.) This selection-state information should be maintained as long as it refers to any meaningful data. For this reason, it'27s desirable to describe selection in a manner that doesn'27t require that selection-state information be maintained in the document whenever possible.
fs16
fs28 Three well-known selection descriptions can apply to any document: the empty selection, the entire document, and the abstract concept of the current selection. NSSelection objects for these selections are returned by the b emptySelectionb0 ,b allSelectionb0 , and b currentSelectionb0 class methods.
fs16
fs28 Since an NSSelection may be used in a document that is read by machines with different architectures, care should be taken to write machine-independent descriptions. For example, using a binary structure as a selection description will fail on a machine where an identically defined structure has a different size or is kept in memory with different byte ordering. Exporting (and then parsing) ASCII descriptions is often a good solution. If binary descriptions must be used, it'27s prudent to preface the description with a token specifying the description'27s byte ordering.
fs16
fs28 It may also be prudent to version-stamp selection descriptions, so that old selections can be accurately read by updated versions of an application.
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Returning Special Selection Shared Instances
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSSelection *)b allSelectionb0 tab Returns the shared instance of the well-known selection representing the entire document.
fi-6552 fs16
fs28 fi-6552 + (NSSelection *)b currentSelectionb0 tab Returns the shared instance of the well-known selection representing the abstract concept of the current selection. The current selection never describes a specific selection; it describes a selection that may change frequently.
fi-6552 fs16
fs28 fi-6552 + (NSSelection *)b emptySelectionb0 tab Returns the shared instance of the well-known selection representing no data.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Creating and Initializing a Selection
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSSelection *)b selectionWithDescriptionData:b0 (NSData *)i datai0 tab
s9 li7030 fi-6553 fi-5796 tab Creates and returns an NSSelection object that records i datai0 as the description of the selection.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithDescriptionData:b0 (NSData *)i newDatai0 tab Initializes a newly allocated NSSelection object that records i datai0 as the description of the selection. Returns the initialized object.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithPasteboard:b0 (NSPasteboard *)i pasteboardi0 tab
s9 li7030 fi-6553 fi-5796 tab Initializes a newly allocated NSSelection object that takes its description of the selection from i pasteboardi0 . Returns the initialized object.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Describing a Selection
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSData *)b descriptionDatab0 tab Returns the data that describes the selection as set by b selectionWithDescriptionData:b0 or b initWithDescriptionData:b0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isWellKnownSelectionb0 tab Returns YES if the receiver is one of the well-known selection types (those representing the entire document, current selection, or empty selection) and NO otherwise.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Writing a Selection to the Pasteboard
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b writeToPasteboard:b0 (NSPasteboard *)i pasteboardi0 tab
s9 li7030 fi-6553 fi-5796 tab Writes the selection data to the pasteboard i pasteboardi0 . A copy of the selection can then be retrieved by initializing a new NSSelection from the pasteboard using b initWithPasteboard:b0 .
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.