Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSColorList 

Inherits From:	NSObject

Conforms To:	NSCoding
NSObject (NSObject)

Declared In:	AppKit/NSColorList.h 

Class Description

Instances of NSColorList are used to manage named lists of NSColors. NSColorPanel's list-mode color picker uses instances of NSColorList to represent any lists of colors that come with the system, as well as any lists created by the user. An application can use NSColorList to manage document-specific color lists, which may be added to an application's NSColorPanel using its attachColorList: method.

An NSColorList is similar to a dictionary object: An NSColor is added to, looked up in, and removed from the list by specifying its key, which is an NSString. In addition, colors can be inserted at specified positions in the list. The list itself has a name, specified when you create the object (using either initWithName: or initWithName:fromFile:).

An NSColorList saves and retrieves its colors from files with the extension ª.clrº in directories defined by a standard search path. To access all the color lists in the standard search path, use the availableColorLists method; this returns an array of NSColorLists, from which you can retrieve the individual color lists by name.

NSColorList reads color list files in several different formats; it saves color lists using the archiver API.

Initializing an NSColorList

- (id)initWithName:(NSString *)name	Initializes and returns the receiver, registering it under the specified name if the name isn't in use already. 

- (id)initWithName:(NSString *)name	Initializes and returns the receiver, registering it under the
fromFile:(NSString *)path		specified name if the name isn't in use already. path should be the full path to the file for the color list; name should be the name of the file for the color list (minus the ª.clrº extension). 

Getting All Color Lists

+ (NSArray *)availableColorLists	Returns an array of all NSColorLists found in the standard color list directories. Color lists created at run time aren't included in this list unless they're saved into one of the standard color list directories.

Getting a Color List by Name

+ (NSColorList *)colorListNamed:(NSString *)name
	Searches the array that's returned by availableColorLists and returns the NSColorList named name, or nil if no such color list exists. name mustn't include the ª.clrº suffix.

- (NSString *)name	Returns the name of the NSColorList. 

Managing Colors by Key

- (NSArray *)allKeys	Returns an array of NSString objects that contains all the keys by which the NSColors are stored in the NSColorList. The length of this array equals the number of colors, and its contents are arranged according to the ordering specified when the colors were inserted.

- (NSColor *)colorWithKey:(NSString *)key	Returns the NSColor associated with key, or nil if there is none.

- (void)insertColor:(NSColor *)color	Inserts color at the specified location in the list (which is
key:(NSString *)key		numbered starting with 0). If the list already contains a
atIndex:(unsigned)location		color with the same key at a different location, it's removed from the old location. This method posts the NSColorListChangedNotification notification to the default notification center. Raises NSColorListNotEditableException if the color list is not editable. This method posts the NSColorListChangedNotification notification to the default notification center.

- (void)removeColorWithKey:(NSString *)key	Removes the color associated with key from the list. This method does nothing if the list doesn't contain the key. This method posts the NSColorListChangedNotification notification to the default notification center. Raises NSColorListNotEditableException if the color list is not editable.

- (void)setColor:(NSColor *)aColor	Associates the specified NSColor with the key key. If the
forKey:(NSString *)key		list already contains key, this method sets the corresponding color to aColor; otherwise, it inserts aColor at the end of the list.

Editing

- (BOOL)isEditable	Returns YES if the color list can be modified. This depends on the source of the list: If it came from a write-protected file, this method returns NO.

Writing and Removing Files

- (BOOL)writeToFile:(NSString *)path	If path is a directory, saves the NSColorList in a file named listname.clr (where listname is the name with which the NSColorList was initialized). If path includes a file name, this method saves the file under that name. If path is nil, this method saves the file as listname.clr in the standard location. Returns YES upon success.

- (void)removeFile	Deletes the file from which the list was created, unless the user doesn't own the color list. The receiver is removed from the list of available colors, but isn't released.