Mac Developer Library

Developer

AppKit Framework Reference NSColorList Class Reference

Options
Deployment Target:

On This Page
Language:

NSColorList

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.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Initializes and returns the receiver, registering it under the given name if it isn’t in use already.

    Declaration

    Swift

    init(name name: String)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init?(name name: String, fromFile path: String?)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func availableColorLists() -> [AnyObject]

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init?(named name: String) -> NSColorList

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – name

  • Returns the name of the receiver.

    Declaration

    Swift

    var name: String? { get }

    Objective-C

    @property(readonly, copy) NSString *name

    Return Value

    The name of the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isEditable - isEditable Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isEditable

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

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

    Declaration

    Swift

    var allKeys: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the NSColor object associated with the given key.

    Declaration

    Swift

    func colorWithKey(_ key: String) -> NSColor?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func insertColor(_ color: NSColor, key key: String, atIndex location: Int)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeColorWithKey(_ key: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Associates the specified NSColor object with the specified key.

    Declaration

    Swift

    func setColor(_ color: NSColor, forKey key: String)

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeFile()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Saves the receiver to a file at the specified path.

    Declaration

    Swift

    func writeToFile(_ path: String?) -> Bool

    Objective-C

    - (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

    YEStrue upon success and NOfalse if the method fails to write the file.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – removeFile

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.