Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSColorPanel
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
NSColorPanel provides a standard user interface for selecting color in an application. It provides a number of standard color selection modes and, with the NSColorPickingDefault and NSColorPickingCustom interfaces, allows an application to add its own color selection modes. It allows the user to save swatches containing frequently used colors.
Tasks
Constructors
Creating the NSColorPanel
Setting Color Picker Modes
Setting the NSColorPanel
-
accessoryView
-
isContinuous
-
mode
-
setAccessoryView
-
setAction
-
setContinuous
-
setMode
-
setShowsAlpha
-
setTarget
-
showsAlpha
Attaching a Color List
Setting Color
Getting Color Information
Responding to a color change
-
changeColordelegate method
Constructors
NSColorPanel
Creates an empty NSColorPanel.
public NSColorPanel()
Creates a new NSColorPanel.
public NSColorPanel(NSRect contentRect, int styleMask, int backingType, boolean defer)
Discussion
The contentRect argument specifies the location and size of the panel’s content area in screen coordinates. Note that the Window Server limits window position coordinates to ±16,000 and sizes to 10,000.
The styleMask argument specifies the panel’s style. Either it can be NSWindow.BorderlessWindowMask, or it can contain any of the options described in NSWindow’s “Constants,” combined using the C bitwise OR operator.
Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should normally not need to create them. Also, note that an NSWindow’s style mask should include NSWindow.TitledWindowMask if it includes any of the others.
The backingType argument specifies how the drawing done in the panel is buffered by the object’s window device, and possible values are described in NSWindow’s “Constants.”
The defer argument determines whether the window server creates a window device for the new panel immediately. If defer is true, it defers creating the window until the panel is moved onscreen. All display messages sent are postponed until the panel is created, just before it’s moved onscreen. Deferring the creation of the window improves launch time and minimizes the virtual memory load on the window server.
The new panel creates an instance of NSView to be its default content view. You can replace it with your own object by using the setContentView method.
Creates a new NSColorPanel.
public NSColorPanel(NSRect contentRect, int styleMask, int backingType, boolean defer, NSScreen aScreen)
Discussion
This constructor is equivalent to the one above, except contentRect is specified relative to the lower-left corner of aScreen.
If aScreen is null, contentRect is interpreted relative to the lower-left corner of the main screen. The main screen is the one that contains the current key window or, if there is no key window, the one that contains the main menu. If there’s neither a key window nor a main menu (if there’s no active application), the main screen is the one where the origin of the screen coordinate system is located.
Static Methods
dragColor
Drags color into a destination view from sourceView
public static boolean dragColor(NSColor color, NSEvent anEvent, NSView sourceView)
Discussion
in response to anEvent. This method is usually invoked by the mouseDown method of sourceView. The dragging mechanism handles all subsequent events.
Because it is a static method, dragColor can be invoked whether or not the instance of NSColorPanel exists. Returns true.
setPickerMask
Accepts as the mask parameter one or more logically ORed color mode masks described in “Constants.”
public static void setPickerMask(int mask)
Discussion
This method determines which color selection modes will be available in an application’s NSColorPanel. This method has an effect only before NSColorPanel is instantiated.
If you create a class that implements the color-picking interfaces (NSColorPickingDefault and NSColorPickingCustom), you may want to give it a unique mask—one different from those defined for the standard color pickers. To display your color picker, your application will need to logically OR that unique mask with the standard color mask constants when invoking this method.
See Also
setPickerMode
public static void setPickerMode(int mode)
Discussion
Sets the color panel’s initial picker to mode, which may be one of the symbolic constants described in “Constants.” The mode determines which picker will initially be visible. This method may be called at any time, whether or not an application’s NSColorPanel has been instantiated.
See Also
sharedColorPanel
Returns the shared NSColorPanel, creating it if necessary.
public static NSColorPanel sharedColorPanel()
sharedColorPanelExists
Returns true if the NSColorPanel has been created already.
public static boolean sharedColorPanelExists()
See Also
Instance Methods
accessoryView
Returns the accessory view, or null if there is none.
public NSView accessoryView()
See Also
attachColorList
Adds the list of NSColors specified in colorList to all the color pickers in the receiver that display color lists by invoking attachColorList on all color pickers in the application.
public void attachColorList(NSColorList colorList)
Discussion
An application should use this method to add an NSColorList saved with a document in its file package or in a directory other than NSColorList’s standard search directories.
See Also
color
Returns the currently selected color in the receiver.
public NSColor color()
See Also
detachColorList
Removes the list of NSColors specified in colorList from all the color pickers in the receiver that display color lists by invoking detachColorList on all color pickers in the application.
public void detachColorList(NSColorList colorList)
Discussion
Your application should use this method to remove an NSColorList saved with a document in its file package or in a directory other than NSColorList’s standard search directories.
See Also
isContinuous
Returns whether the receiver continuously sends the action message to the target as the user manipulates the color picker.
public boolean isContinuous()
See Also
mode
Returns the color picker mode of the receiver.
public int mode()
Discussion
The mode constants for the standard color pickers are listed in “Choosing the Color Pickers in a Color Panel”.
See Also
setAccessoryView
Sets the accessory view displayed in the receiver to aView.
public void setAccessoryView(NSView aView)
Discussion
The accessory view can be any custom view you want to display with NSColorPanel, such as a view offering color blends in a drawing program. The accessory view is displayed below the color picker and above the color swatches in the NSColorPanel. The NSColorPanel automatically resizes to accommodate the accessory view.
See Also
setAction
Sets the action message to action.
public void setAction(NSSelector action)
Discussion
When you select a color in the color panel NSColorPanel sends its action to its target, provided that neither the action nor the target is null. The action is NULL by default.
See Action Messages for additional information on action messages.
See Also
setColor
Sets the color of the receiver to color.
public void setColor(NSColor color)
Discussion
This method posts a ColorPanelColorDidChangeNotification with the receiver to the default notification center.
See Also
setContinuous
Sets the receiver to send the action message to its target continuously as the color of the NSColorPanel is set by the user.
public void setContinuous(boolean flag)
Discussion
Send this message with flag set to true if, for example, you want to continuously update the color of the target.
See Also
setMode
Sets the mode of the receiver if mode is one of the modes allowed by the color mask.
public void setMode(int mode)
Discussion
The color mask is set when you first create the shared instance of NSColorPanel for an application. mode may be one of the symbolic constants described in “Constants.”
See Also
setShowsAlpha
Tells the receiver whether or not to show alpha values and an opacity slider, depending on the Boolean value flag.
public void setShowsAlpha(boolean flag)
Discussion
Note that calling the NSColor method setIgnoresAlpha with a value of true overrides any value set with this method.
See Also
setTarget
Sets the target of the receiver to target.
public void setTarget(Object target)
Discussion
When you select a color in the color panel NSColorPanel sends its action to its target, provided that neither the action nor the target is null. The target is null by default.
See Also
showsAlpha
Returns whether or not the receiver shows alpha values and an opacity slider.
public boolean showsAlpha()
Discussion
Note that calling the NSColor method setIgnoresAlpha with a value of true overrides any value set with setShowsAlpha.
See Also
Constants
These constants specify which of the color modes the NSColorPanel can use. For more information, see “Choosing the Color Pickers in a Color Panel”.
These constants specify the active color mode used when an application’s instance of NSColorPanel is masked for more than one color mode. For more information, see “Choosing the Color Pickers in a Color Panel”.
Delegate Methods
changeColor
public void changeColor(Object sender)
Discussion
When the user selects a color in an NSColorPanel, the NSColorPanel sends a changeColor action message to the first responder. You can override this method in any responder that needs to respond to a color change. sender is the color panel.
Notifications
ColorPanelColorDidChangeNotification
Posted when the NSColorPanel’s color is set, as when setColor is invoked. The notification object is the notifying NSColorPanel. This notification does not contain a userInfo dictionary.
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)