NSColorList Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Color Programming Topics
Declared in
NSColorList.h
Related sample code

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

NSCoding

Tasks

Initializing an NSColorList Object

Getting Color Lists

Getting Color List Properties

Managing Colors By Key

Writing and Removing Color-List Files

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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Related Sample Code
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 OS X v10.0 and later.
Related Sample Code
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 OS X v10.0 and later.
Related Sample Code
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 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 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 OS X v10.0 and later.
See Also
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 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 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 OS X v10.0 and later.
See Also
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 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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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
Declared In
NSColorList.h


© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-28)

Did this document help you? Yes It's good, but... Not helpful...