initWithDescription:length:Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| NXSelection |
| Inherits From: | Object | |
| Declared In: | appkit/NXSelection.h |
| Class Description |
| The NXSelection class defines an object that describes a selection within a document. An NXSelection is an immutable description; it may be held by the system or other documents, and it cannot change over time.
Because a selection description can't be changed once it has been exported, it's a good idea to construct general descriptions that can survive changes to a document and don't require specific selection information to be stored in the document. This 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't require that any information be stored in the image's 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 not ids), where an object identifier is unique through 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't require that any selection-specific information be stored in the document's file, with the benefit that links can be made to read-only documents. Maintaining a character-range selection in a text document is more problematic. A possible solution is to insert a selection-begin and selection-end marker that refer to 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't be purged from the document, because the document can't 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's desirable to describe selection in a manner that doesn't require that selection-state information be maintained in the document whenever possible. Three well-known selection descriptions can apply to any document: the empty selection, the entire document, and the abstract concept of the current selection. NXSelection objects for these selections are returned by the emptySelection, allSelection, and currentSelection class methods. Since an NXSelection 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 is prudent to preface the description with a token specifying the description's byte ordering. It may also be prudent to version-stamp selection descriptions, so that old selections can be accurately read by updated versions of an application. |
| Instance Variables |
| None declared in this class. |
| Method Types |
| Returning special Selections | + emptySelection |
| + allSelection + currentSelection |
| Initializing a Selection | initWithDescription:length: |
| initWithDescriptionNoCopy:length: initFromPasteboard: |
| Copying a Selection | copyFromZone: | |
| Describing a Selection | descriptionOfLength: | |
| Comparing Selections | isEqual: |
| isWellKnownSelection |
| Writing the Selection to the Pasteboard |
| writeToPasteboard: |
| Class Methods |
| allSelection |
| + allSelection |
| Returns the shared instance of the well-known selection representing an entire document. |
| currentSelection |
| + currentSelection |
| 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. |
| emptySelection |
| + emptySelection |
| Returns the shared instance of the well-known selection representing no data. |
| Instance Methods |
| copyFromZone: |
| copyFromZone:(NXZone *)zone |
| If the receiving NXSelection is a shared instance of a well-known selection, returns the NXSelection. Otherwise, returns a copy of the NXSelection allocated from zone. |
| descriptionOfLength: |
| (const void *)descriptionOfLength:(int *)count |
| Returns a pointer to the description of the selection and fills in the integer indicated by count with the length (in bytes) of the description. The description was set with one of the initWithDescription... methods when the selection was created. |
| initFromPasteboard: |
| initFromPasteboard:(Pasteboard *)pasteboard |
| Initializes a newly allocated NXSelection instance from data on the specified pasteboard. If the NXSelection can't be initialized for any reason (for example, if data of type NXSelectionPboardType isn't found on the pasteboard) the new instance is freed and nil is returned.
See also: |
| initWithDescription:length: |
| initWithDescription:(const void *)description length:(int)count |
| Initializes a newly allocated NXSelection instance using a copy of the data indicated by description, of length count, to describe the selection. If count is 1, description is assumed to be null-terminated data. description can be in any format and of any length, but should be architecture independent. It's a good idea to include version information in such a description. |
| initWithDescriptionNoCopy:length: |
| initWithDescriptionNoCopy:(const void *)description length:(int)count |
| Initializes a newly allocated NXSelection instance using the data indicated by description, of length count, to describe the selection. The description will not be copied nor modified by the NXSelection, and it ought to be persistent and unchanging. If count is 1, description is assumed to be null-terminated data. description can be in any format and of any length, but should be architecture independent. It's a good idea to include version information in such a description. |
| isEqual: |
| (BOOL)isEqual:otherSel |
| Compares the receiving NXSelection with another NXSelection, specified by otherSel. Returns YES if they describe the same selection, and NO otherwise. |
| isWellKnownSelection |
| (BOOL)isWellKnownSelection |
| Returns YES if the NXSelection is one of the well-known selection types, and NO otherwise. There are well-known selection types for an entire document, the current selection, and for an empty selection.
See also: + allSelection, + currentSelection, + emptySelection |
| writeToPasteboard: |
| writeToPasteboard:(Pasteboard *)pasteboard |
| Writes the NXSelection to the pasteboard pasteboard. A copy of the selection can then be retrieved by initializing a new NXSelection from the pasteboard using initFromPasteboard:. |