Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXColorList

	Inherits From:	Object
	Declared In:	appkit/NXColorList.h

Class Description

Instances of NXColorList are used to manage named lists of NXColors.  Colors are added to, looked up in, and removed from an NXColorList by name.  NXColorPanel's list-mode color picker uses instances of NXColorList for the standard PANTONE®Colors, the NeXT colors, and any lists created by the user.  An application can use NXColorList to manage document-specific color lists, which may be added to an application's NXColorPanel using its attachColorList: method. An NXColorList manages colors in one of two ways.  When managing a list such as the PANTONE Colors, an NXColorList issues colors with persistent names.  When managing other color lists, such as the NeXT color list or a list created by the user, an NXColorList issues colors without names. NXColors generated with persistent names reference both the color name and color list name.  This reference remains even if the color is copied to another list and the user then renames the color in the NXColorPanel.  Lists that generate colors with persistent names are considered immutable--attempts to change them at runtime will raise exceptions as described in the list editing methods.  The PANTONE Color list is currently the only example of a list that issues colors with persistent names. The Application Kit function NXSetColor() assures that colors with persistent names are printed correctly regardless of the list from which they are selected.  Say, for example, the user has created a new color list in the color panel, copied a PANTONE Color into that list, given that color a new name, then used the color from the new list in a document.  When that document is printed, the NXSetColor() function recognizes the color's persistent name and references the PANTONE Color list to find the correct color value for the device. An NXColorList saves and retrieves its colors from files with the extension ".clr".  The standard search path for the files for color lists include ~/Library/Colors, ~/.Next/Colors (for historical reasons), /LocalLibrary/Colors, and /NextLibrary/Colors. NXColorList reads color list files in several different--and undocumented--formats; NXColorList saves color lists using typed streams API. The files for color lists such as the PANTONE Colors provided with NEXTSTEP are stored in file-wrappers.  This allows for localized and device-dependent versions of such lists.  Color lists created by the user from the NXColorPanel are saved as files in the directory ~/Library/Colors.  Color lists created for a document by an application may be saved in the document's file package. See also:  attachColorList:, detachColorList: (NXColorPanel)

Instance Variables

None declared in this class.

Method Types

Initializing and freeing

init

initWithName: initWithName:fromFile: freeAndRemoveFile free

	Getting all color lists	+ availableColorLists
	Color list names	+ findColorListNamed:

name

Managing colors by name

setColorNamed:color:

colorNamed: nameOfColorAt: localizedNameForColorNamed: removeColorNamed:

	Generates persistent names	generatesNamedColors
	Editing	isEditable
	Number of colors	colorCount
	Saving to a file	saveTo:
	Archiving	read:

write:

Class Methods

availableColorLists

+ (List

*)availableColorLists

Returns a List object of all NXColorLists found in the standard color list directories. This list belongs to the NXColorList class and should not be cached by the caller. Color lists created at run time are not included in this list unless they were saved into one of the standard color list directories. This method is primarily for use by NXColorPanel. The standard search path for color lists is discussed in the class description.

findColorListNamed:

+ findColorListNamed:(const char *)name

Returns the list with the name name; if the list doesn't exist, returns nil.  name mustn't include the ".clr" suffix.  Color lists are searched for in the color list search path and among the named, registered lists.  The search path for color lists is discussed in the class description. See also:  initWithName:

Instance Methods

colorCount

(unsigned)colorCount

Returns the number of colors in the NXColorList.

colorNamed:

(NXColor)colorNamed:(const char *)colorName

Returns the NXColor associated with colorName.  Raises the exception NX_colorUnknown if colorName isn't in the NXColorList. See also:  removeColorNamed:, setColorNamed:color:

free

free

Frees the NXColorList and its storage.

freeAndRemoveFile

freeAndRemoveFile

Frees the NXColorList.  If the list belongs to the user, this method also deletes the file from which the list was created.

generatesNamedColors

(BOOL)generatesNamedColors

Determines if the list generates colors with persistent names when its colorNamed: method is invoked. Colors with persistent names maintain references to their source list and color name, even if the user copies the color to another list and changes the name in the NXColorPanel.  If an NXColorList generates colors with persistent names, this behavior can't be changed at runtime. See also:  colorNamed:, removeColorNamed:, setColorNamed:color:

init

init

Creates an unnamed NXColorList. See also:  initWithName:, initWithName:fromFile:

initWithName:

initWithName:(const char *)name

Creates and returns a new NXColorList. Also registers it under the specified name if the name isn't in use already. See also:  initWithName:fromFile:, saveTo:

initWithName:fromFile:

initWithName:(const char *)name fromFile:(const char *)path

Creates and returns a new NXColorList.  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). This method also registers the NXColorList under name if that name isn't already in use. This method is the designated initializer for NXColorList. See also:  initWithName:, saveTo:

isEditable

(BOOL)isEditable

Returns YES if the list doesn't generate colors with persistent names and if the user has both read and write access to the file from which the NXColorList was initiated; returns NO otherwise. See also:  generatesNamedColors, initWithName:fromFile:

localizedNameForColorNamed:

(const char *)localizedNameForColorNamed:(const char *)colorName

Returns a name in the user's language of choice for the color associated with colorName.  The directory for a color list (such as PANTONE colors) should contain a ".lproj" directory for each supported language.  This method searches in the directory of the user's chosen language for a ".strings" file containing translated color names. This method raises an exception if colorName isn't in the list. If the color has no translation for the user's chosen language, then colorName is returned.

name

(const char *)name

Returns the name of the NXColorList. See also:  initWithName:, initWithName:fromFile:

nameOfColorAt:

(const char *)nameOfColorAt:(unsigned)count

Returns the name associated with the NXColor at count in the NXColorList.

read:

read:(NXTypedStream *)stream

Reads the NXColorList from the specified stream. Returns self.

removeColorNamed:

(void)removeColorNamed:(const char *)colorName

Removes the specified color.  This method raises the exception NX_colorNotEditable if the NXColorList generates named colors; it raises the exception NX_colorUnknown if colorName isn't in the NXColorList. See also:  generatesNamedColors, isEditable

saveTo:

saveTo:(const char *)path

If path is a directory, saves the NXColorList in a file named listname.clr (where listname is the name with which the NXColorList was initialized). If path includes a file name, this method saves the file under that name. If path isn't specified, then this method saves the file as ~/Library/Colors in a file named listname.clr. See also:  initWithName:, initWithName:fromFile:

setColorNamed:color:

(void)setColorNamed:(const char *)colorName color:(NXColor)color

Adds the NXColor color to the list and associates it with the name colorName.  If colorName is already in the list, this method sets its NXColor to color.   This method raises the exception NX_colorNotEditable if the NXColorList generates named colors; it raises the exception NX_colorUnknown if colorName isn't in the NXColorList.

write:

write:(NXTypedStream *)stream

Writes the NXColorList to the specified stream.  Returns self.

Methods Implemented by the Delegate

colorListDidChange:colorName:

colorListDidChange:list colorName:(const char *)colorName

Indicates that a color in the NXColorList was changed. This method is invoked when the list is first created or when the setColorNamed:color: or removeColorNamed: method is invoked. See also:  initWithName:fromFile:, removeColorNamed:, setColorNamed:color: