PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSColorList


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


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, 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 a String. These keys are used to identify the colors in the list and are used to display the color to the user in the color panel. In addition, colors can be inserted at specified positions in the list.

The color list has a name, specified when you create the object using one of the NSColorList constructors.

Instances of NSColorList are created for all user-created color lists (those in the color panel) and various color catalogs available on the system.

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.

The standard search path for color lists is:

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

NSColorList posts a ColorListDidChangeNotification when a color list is changed.




Method Types


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


Constructors



NSColorList

public NSColorlist()

Description forthcoming.

public NSColorList(String name)

Creates a color list, registering it under name if name isn't in use already. This constructor invokes the constructor with two arguments, using null as the additional argument, indicating that the color list doesn't need to be initialized from a file.

public NSColorList( String name, String path)

Initializes and returns the receiver, registering it under name if 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). A null path indicates the color list should be initialized with no colors.


Static Methods



availableColorLists

public static 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.

See Also: colorListNamed



colorListNamed

public static NSColorList colorListNamed(String name)

Searches the array that's returned by availableColorLists and returns the NSColorList named name, or null if no such color list exists. name must not include the ".clr" suffix.

See Also: name




Instance Methods



allKeys

public NSArray allKeys()

Returns an array of String 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.

colorWithKey

public NSColor colorWithKey(String key)

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

insertColorForKeyAtIndex

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

Inserts color at the specified location in the color list (numbered starting with 0). 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 ColorListChangedNotification to the default notification center. It throws ColorListNotEditableException if the color list isn't editable.

See Also: colorWithKey, removeColorWithKey, setColorForKey



isEditable

public boolean isEditable()

Returns true 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 false.

name

public String name()

Returns the name of the NSColorList.

removeColorWithKey

public void removeColorWithKey(String 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 ColorListDidChangeNotification to the default notification center. It throws ColorListNotEditableException if the color list is not editable.

See Also: insertColorForKeyAtIndex, setColorForKey



removeFile

public void removeFile()

Removes the file from which the list was created, if the file is in a standard search path and owned by the user. The receiver is removed from the list of available color lists returned by availableColorLists.

setColorForKey

public void setColorForKey( NSColor color, String key)

Associates the specified NSColor with key. 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

public boolean writeToFile(String path)

If path is a directory, saves the NSColorList in a file named listname.clr in that directory (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 null, this method saves the file as listname.clr in the users' 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. This notification contains a notification object but no userInfo dictionary. The notification object is the NSColorList object that changed.



Table of Contents