---

NSColorList

Overview

An NSColorList is an ordered list of NSColors, identified by keys. Instances of NSColorList, or more simply color lists, 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.

Tasks

Constructors

• NSColorList

Getting All Color Lists

• availableColorLists

Getting a Color List by Name

• colorListNamed
• name

Managing Colors by Key

• allKeys
• colorWithKey
• insertColorForKeyAtIndex
• removeColorWithKey
• setColorForKey

Editing

• isEditable

Writing and Removing Files

• removeFile
• writeToFile

Static Methods

availableColorLists

Returns an array of all NSColorLists found in the standard color list directories, including color catalogs (lists of colors identified only by name).

public static NSArray availableColorLists()

Discussion

Color lists created at runtime aren’t included in this list unless they’re saved into one of the standard color list directories.

See Also

• colorListNamed

colorListNamed

Searches the array that’s returned by availableColorLists and returns the NSColorList named name, or null if no such color list exists.

public static NSColorList colorListNamed(String name)

Discussion

name must not include the “.clr” suffix.

See Also

• name

Instance Methods

allKeys

Returns an array of String objects that contains all the keys by which the NSColors are stored in the receiver.

public NSArray allKeys()

Discussion

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.

colorWithKey

Returns the NSColor associated with key, or null if there is none.

public NSColor colorWithKey(String key)

insertColorForKeyAtIndex

Inserts color at the specified location in the receiver (numbered starting with 0).

public void insertColorForKeyAtIndex(NSColor color, String key, int location)

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 ColorListDidChangeNotification to the default notification center. It throws ColorListNotEditableException if the color list isn’t editable.

See Also

• colorWithKey
• removeColorWithKey
• setColorForKey

isEditable

Returns true if the receiver can be modified.

public boolean isEditable()

Discussion

This result depends on the source of the list: If it came from a write-protected file, this method returns false.

name

Returns the name of the receiver.

public String name()

removeColorWithKey

Removes the color associated with key from the receiver.

public void removeColorWithKey(String key)

Discussion

This method does nothing if the receiver doesn’t contain the key. This method posts ColorListDidChangeNotification to the default notification center. It throws ColorListNotEditableException if the receiver is not editable.

See Also

• insertColorForKeyAtIndex
• setColorForKey

removeFile

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

public void removeFile()

Discussion

The receiver is removed from the list of available color lists returned by availableColorLists.

setColorForKey

Associates the specified NSColor with key.

public void setColorForKey(NSColor color, String 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 insertColorForKeyAtIndex.

See Also

• colorWithKey
• insertColorForKeyAtIndex
• removeColorWithKey

writeToFile

If path is a directory, saves the receiver in a file named listname.clr in that directory (where listname is the name with which the receiver was initialized).

public boolean writeToFile(String path)

Discussion

If path includes a filename, this method saves the file under that name. If path is null, this method saves the file as listname.clr in the user’s private colorlists directory. Returns true upon success and false if it fails to write the file.

See Also

• removeFile

Notifications

ColorListDidChangeNotification

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

---