---

NSColorList Class Reference

Overview

An NSColorList object is an ordered list of NSColor objects, identified by keys. Instances of NSColorList, or more simply color lists, are used to manage named lists of NSColor instances. The NSColorPanel 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.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

Tasks

Initializing an NSColorList Object

• – initWithName:
• – initWithName:fromFile:

Getting Color Lists

• + availableColorLists
• + colorListNamed:

Getting Color List Properties

• – name
• – isEditable

Managing Colors By Key

• – allKeys
• – colorWithKey:
• – insertColor:key:atIndex:
• – removeColorWithKey:
• – setColor:forKey:

Writing and Removing Color-List Files

• – removeFile
• – writeToFile:

Class Methods

availableColorLists

Returns an array of all color lists found in the standard color list directories.

+ (NSArray *)availableColorLists

Return Value

An array of NSColorList objects representing all of the color lists found in the standard color list directories, including color catalogs (lists of colors identified only by name). Color lists created at runtime aren’t included in this list unless they’re saved into one of the standard color list directories.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + colorListNamed:

Declared In

NSColorList.h

colorListNamed:

Searches the array that’s returned by availableColorLists and returns the color list with the given name.

+ (NSColorList *)colorListNamed:(NSString *)name

Parameters

name

The name of the color list to retrieve. This name must not include the “.clr” suffix.

Return Value

The color list with the specified name or nil if no such color list exists.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – name

Declared In

NSColorList.h

Instance Methods

allKeys

Returns an array of the keys by which the NSColor objects are stored in the receiver.

- (NSArray *)allKeys

Return Value

An array of NSString objects containing all the keys by which the NSColor objects are stored in the receiver.

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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

colorWithKey:

Returns the NSColor object associated with the given key.

- (NSColor *)colorWithKey:(NSString *)key

Parameters

key

The key for which to retrieve the color.

Return Value

The color associated with the given key or nil if there is none.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

initWithName:

Initializes and returns the receiver, registering it under the given name if it isn’t in use already.

- (id)initWithName:(NSString *)name

Parameters

name

The name under which to register the color list. Specify @”” if you don’t want a name.

Return Value

The initialized color list.

Discussion

This method invokes initWithName:fromFile: with a fromFile: argument of nil, indicating that the color list doesn’t need to be initialized from a file. Note that this method does not add the color list to availableColorLists until the color list is saved into the user’s path with writeToFile: with a value of nil.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

initWithName:fromFile:

Initializes and returns the receiver, registering it under the given name if it isn’t in use already.

- (id)initWithName:(NSString *)name fromFile:(NSString *)path

Parameters

name

The name of the file for the color list (minus the “.clr” extension). Specify @”” if you don’t want a name.

path

The full path to the file for the color list. A nil path indicates the color list should be initialized with no colors.

Discussion

Note that this method does not add the color list to availableColorLists until the color list is saved into the user’s path with writeToFile: with a value of nil.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

insertColor:key:atIndex:

Inserts the specified color at the specified location in the receiver.

- (void)insertColor:(NSColor *)color key:(NSString *)key atIndex:(NSUInteger)location

Parameters

color

The color to add to the color list.

key

The key with which to associate the color.

location

The location in the color list at which to place the specified color. Locations are numbered starting with 0.

Discussion

If the list already contains a color with the same key at a different location, it’s removed from the old location. This method posts NSColorListDidChangeNotification to the default notification center. It raises NSColorListNotEditableException if the color list isn’t editable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – colorWithKey:
• – removeColorWithKey:
• – setColor:forKey:

Declared In

NSColorList.h

isEditable

Returns a Boolean value indicating whether the receiver can be modified.

- (BOOL)isEditable

Return Value

YES if the color list can be modified; otherwise NO. This result depends on the source of the list: If it came from a write-protected file, this method returns NO.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

name

Returns the name of the receiver.

- (NSString *)name

Return Value

The name of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

removeColorWithKey:

Removes the color associated with the specified key from the receiver.

- (void)removeColorWithKey:(NSString *)key

Parameters

key

The key for which to remove the color.

Discussion

This method does nothing if the receiver doesn’t contain the key. This method posts NSColorListDidChangeNotification to the default notification center. It raises NSColorListNotEditableException if the receiver is not editable.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertColor:key:atIndex:
• – setColor:forKey:

Declared In

NSColorList.h

removeFile

Removes the file from which the list was created, if the file is in a standard search path and owned by the user.

- (void)removeFile

Discussion

The receiver is removed from the list of available color lists returned by availableColorLists. If there are no outstanding references to the color list, this method might deallocate the object as well.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

setColor:forKey:

Associates the specified NSColor object with the specified key.

- (void)setColor:(NSColor *)color forKey:(NSString *)key

Parameters

color

The color to associate with the given key.

key

The key.

Discussion

If the list already contains key, this method sets the corresponding color to color; otherwise, it inserts color at the end of the list by invoking insertColor:key:atIndex:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – colorWithKey:
• – insertColor:key:atIndex:
• – removeColorWithKey:

Declared In

NSColorList.h

writeToFile:

Saves the receiver to a file at the specified path.

- (BOOL)writeToFile:(NSString *)path

Parameters

path

The path at which to save the color list. If path is a directory, the receiver is saved in a file named listname.clr in that directory (where listname is the name with which the receiver was initialized).

If path includes a filename, this method saves the file under that name. If path is nil, the file is saved as listname.clr in the user’s private colorlists directory.

Return Value

YES upon success and NO if the method fails to write the file.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeFile

Declared In

NSColorList.h

Notifications

NSColorListDidChangeNotification

Posted whenever a color list changes. The notification object is the NSColorList object that changed. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSColorList.h

---