CHColorMapControl
- Inherits
from:
- NSControl
:
NSView :
NSResponder : NSObject
- Conforms to:
- NSCoding (NSResponder)
- NSObject (NSObject)
Declared in: - CHAppKit/CHColorMapControl.h
Class Description
A CHColorMapControl allows display and editing of an NSColorList that is ordered
based on floating point key values. NSColorLists are part of Apple's AppKit
framework and hold sets of NSColors in a dictionary using key/value pairs. A
CHColorMapControl uses NSColorLists with keys between "0.0" and "1.0"
and converts these keys into floating point numbers to order them. Once ordered,
an NSColorList can then be used as a colormap or color-ramp in your application.
Programming Topics
Using
Color
NSColorList
Commonly Used Methods
| - colorList |
Returns the NSColorList that the control is representing. |
| - setColorList: |
Sets the control's underlying data to that of NSColorList. The NSColorList
keys should be compatible with the way that CHColorMapControl handles them.
I.e, the keys should be float values between 0.0 and 1.0 representing that
color's position in the colormap. |
Constants
These constants specify the orientation of the control. They're used by initWithFrame:orientation:
and orientation.
| Constant |
Description |
| CHVerticalOrientation |
The control is oriented vertically, with position values of 0.0 at the
bottom and 1.0 at the top |
| CHHorizontalOrientation |
The control is oriented horizontally, with position values of 0.0 at the
left and 1.0 at the right. |
Adopted Protocols
NSCoding
-
- -
encodeWithCoder:
-
initWithCoder:
Method Types
Initializing a CHColorMapControl
-
- - initWithFrame:orientation:
Accessing the control's appearance
- - isSmooth
- setIsSmooth:
- isContinuous
- setContinuous:
- drawTickMarks
- setDrawTickMarks:
- numberOfTicks
- setNumberOfTicks:
- drawMarkers
- setDrawMarkers:
- editable
- setEditable:
- controlSize
- setControlSize:
- drawCrossBars
- setDrawCrossBars:
- orientation
Asking about the selected cell's information
- - selectedCellIndex
- selectedCellPosition
- selectedCellColor
Changing the control's state
- - setSelectedCellIndex:
- setSelectedCellPosition:
- setColor:
Utility methods
- - indexOfCellAtLocation:
- indexOfCellAtPosition:
- colorAtPosition:
- reverseColorList:
Adding and Deleting colors
- - addMarkerAtPosition:
- - addMarkerAtPosition:withColor:
- deleteColorFromListAtIndex:
Selection
- - deselectAllCells
- selectAllCells
Accessing the control's underlying NSColorList data
- - colorList
- colorListAsArray
- colorListAsDictionary
- setColorList:
- setColorListFromDictionary
Instance Methods
- (void)addMarkerAtPosition:(float)position
Adds a new entry to the colormap at the specified position. The value for
position should be between 0.0 and 1.0. The color of the entry is determined
by averaging and weighting the colors on either side of the given position.
See Also: - addMarkerAtPosition:withColor:,
-deleteColorFromListAtIndex:
- (BOOL)addMarkerAtPosition:(float)position withColor:(NSColor
*)theColor
Adds a new entry to the colormap at the specified position using the color
specified by theColor. The value for position should be between
0.0 and 1.0.
See Also: - addMarkerAtPosition:,
-deleteColorFromListAtIndex:
- (NSColor *)colorAtPosition:(float)position
Returns the NSColor for a given position in the colormap. position can
be any number between 0.0 and 1.0.
See Also: -selectedCellColor
- (NSColorList *)colorList
Returns the associated colormap as an NSColorList object.
See Also: - setColorList:
- (NSArray *)colorListAsArray
Returns an array of CHColorMapCell objects. Each object in the array corresponds
to a single color entity in the color list.
See Also: - colorList, -
colorListAsDictionary, (CHColorMapCell)
- (NSDictionary *)colorListAsDictionary
Returns the the associated colormap data as a dictionary. Each element of the
dictionary represents a single element of the colormap with the key being the
position of the element within the colormap. The data object for each key is
represented as an NSArray with four NSNumbers - one each for RGBA.
Here is an XML sample of the data layout that is returned:
<dict>
<key>0.000000</key>
<array>
<real>4.333334e-01</real>
<real>0.000000e+00</real>
<real>1.000000e+00</real>
<real>1.000000e+00</real>
</array>
<key>1.000000</key>
<array>
<real>1.000000e+00</real>
<real>9.770401e-01</real>
<real>8.088235e-01</real>
<real>1.000000e+00</real>
</array>
</dict>
See Also: - colorList:, -
colorListAsArray
- (NSControlSize)controlSize
Returns the size of the receiver. Valid return values as described in "Constants"(NSCell)
are NSRegularControlSize
and NSSmallControlSize.
See Also: - setControlSize:
- (void)deleteColorFromListAtIndex:(int)index
Deletes a color from the receiver at the specified index.
See Also: - addMarkerAtPosition:,
-addMarkerAtPosition:withColor:
- (void)deselectAllCells
If there are any cells selected, this method deselects them.
See Also: - selectAllCells,
-selectedCellIndex
- (BOOL)drawCrossBars
Returns whether or not the receiver will draw the crossbars that go across the
colormap display at each color position.
See Also: - setDrawCrossBars:
- (BOOL)drawMarkers
Returns whether or not the receiver will draw the thumb controls that display
the color and allow sliding of each color entry in the control.
See Also: - setDrawMarkers:
- (BOOL)drawTickMarks
Returns whether or not the receiver will draw the tick marks along the outer edge
of the control's colormap display. This return value is meaningless if numberOfTicks
is set to 0.
See Also: - setDrawTickMarks:, -numberOfTicks,
-setNumberOfTicks:
- (BOOL)editable
Returns a boolean describing whether or not the receiver is considered "editable"
or not. If a control is not editable it will not respond to user interaction in
any way. Although it still appear enabled, there will also be a small "lock"
icon that is displayed to show that the control is not editable. This state is
used mainly when an NSColorList that is not-editable is associated with the receiver.
The state may be overriden by the setEditable: method.
See Also: - setEditable:
- (int)indexOfCellAtLocation:(NSPoint)location
Returns the index of the color cell at a given mouse location within the receiver.
The mouse location should be in the receiver's window coordinates.
See Also: - indexOfCellAtPosition:
indexOfCellAtPosition:
- (int)indexOfCellAtPosition:(float)position
Returns the index of the color cell at a given position of the colormap. Valid
values for position can be any number between 0.0 and 1.0.
See Also: - indexOfCellAtLocation:,
- colorAtPosition:
initWithFrame:orientation:
- (id)initWithFrame:(NSRect)frameRect orientation:(CHControlOrientation)orientation
Initializes a newly allocated CHColorMapControl with frameRect as its
frame rectangle. The new object must be inserted into the view hierarchy of
an NSWindow before it can be used effectively. This method is the designated
initializer for the CHColorMapControl class. Returns self. The value
supplied in the orientation argument will determine the direction of
the control. See "Constants".
- (BOOL)isContinuous
Returns a boolean representing whether or not the receiver sends continuous notifications
for colormap sliders. If this value is YES
then a CHCMSelectedCellDidChangePositionNotification
is sent continually during a sliding operation of a colormap entry. If the value
is NO then a notification is sent
only on a mouseUp of that slider.
See Also: - setContinuous:
- (BOOL)isSmooth
Returns a boolean representing whether or not the receiver should draw its colormap
as a smooth gradiant or as finite color blocks.
See Also: - setIsSmooth:
- (int)numberOfTicks
Returns the number of tick marks associated with the receiver. The tick marks
assigned to the minimum and maximum values are included.
See Also: - setNumberOfTickMarks:
- (CHControlOrientation)orientation
Returns the orientation of the control as a CHControlOrientation,
see "Constants."
- (IBAction)reverseColorList:(id)sender
AThis method does exactly as it says. It reverses the order in which the colors
are stored in the color list. If you call this method from code then you are responsible
for making sure setNeedsDisplay:YES is called
when you are finished.
See Also: - numberOfTicks
- (void)setNumberOfTicks:(int)numberOfTicks
Sets the number of tick marks displayed by the receiver (which include those assigned
to the minimum and maximum values). By default, this value is 0, and no tick marks
appear. The number of tick marks assigned to a slider, along with the slider's
minimum and maximum values, determine the values associated with the tick marks.
See Also: - numberOfTicks
- (NSColor *)selectedCellColor
Returns the color of the currently selected cell, or nil
if there is no selected cell.
See Also: - setColor:
- (int)selectedCellIndex
Returns the index of the currently selected cell. If there is no currently selected
cell, this method returns -1.
See Also: - setSelectedCellIndex:
- (float)selectedCellPosition
Returns a float value of the position of the currently selected cell. The value
will be between 0.0 and 1.0.
See Also: - setSelectedCellPosition:
- (void)setColor:(id)sender
Sets the color of the currently selected cell using the color: method of
sender. You do not usually call this method directly. It is most commonly
used by a shared NSColorPanel to change the receiver's color.
See Also: - selectedCellColor , -
setSelectedCellColor:
- (void)setColorList:(NSColorList *)colorList
Sets the colorlist that is used for data storage of the color map data. After
creating a CHColorMapControl you should use this method to reference a specific
NSColorList so that the control has data. You may use this method to change the
colorlist that is displayed by the control. The NSColorList should be formatted
in a special way. Specifically, the keys for the dictionary in the colorlist should
be strings that correspond to float values between 0.0 and 1.0. The keys do not
need to be in order before assigning them to the colormap control using this method.
This method will sort the keys before displaying them in the control. The control
uses a seperate copy of the data, so the original data is not being changed in
any way and you may release the original data after sending it to this method.
You may get reference to the new data by using the colorList
method of CHColorMapControl.
See Also: - colorList
- (void)setControlSize:(NSDictionary *)aDictionary
Sets the colorlist that is used for data storage of the color map data. The dictionary
keys should be float values between 0.0 and 1.0 representing the position of the
color value on the colormap scale. Each object in the dictionary should be an
array of four NSNumbers (floats between 0.0 and 1.0) representing the RGBA values
of the color, respectively. In the future, there will be a seperate method that
allows you store NSColors directly in the dictionary instead of this slightly
cumbersome method of RGBA quads.
See Also: - setColorList, -
colorListAsDictionary
- (void)setControlSize:(NSControlSize)size
Sets the size for the controls of the receiver. By default, the controls are NSRegularControlSize.
See Also: - controlSize
- (void)setDrawCrossBars:(BOOL)yesNo
Sets whether or not the receiver will display crossbars across the display area
for each color cell.
See Also: - drawCrossBars
- (void)setDrawMarkers:(BOOL)yesNo
Sets whether or not the receiver will display the control sliders at each color
cell position. Without markers, there will be no way for a user to interact with
the control, other than by adding colors via a right-click in the display area.
If you would like to disable user control, a better way is to use the setEditable:
method. One use for this method is to remove any decoration (by using this method
in conjunction with setDrawCrossBars: and setDrawTickMarks:)
from the control so as to use it in a type of "preview" mode for a colorlist.
See Also: - drawMarkers
- (void)setDrawTickMarks:(BOOL)yesNo
Sets whether or not the receiver will display the tick marks to the outside of
the preview area. You may change the number of ticks by using setNumberOfTicks:.
You may also remove all tick marks by setting the number of ticks to 0. It is
your choice as to which you would like to use, although this method allows you
to turn them off and on without having to keep up with the set number yourself.
See Also: - drawTickMarks:
- (void)setEditable:(BOOL)yesNo
Sets whether or not the control is editable by the user. This state may be set
automatically if an NSColorList which is not editable is set to the control. By
using this method, you may override that condition after the colorlist is assigned
to the control.
See Also: - editable
- (void)setIsSmooth:(BOOL)yesNo
Sets whether or not the receiver should draw its colormap as a smooth gradiant
or as finite color blocks.
See Also: - isSmooth
- (void)setNumberOfTicks:(int)numberOfTicks
Sets the number of tick marks displayed in the receiver (which include those assigned
to the minimum and maximum values). By default, this value is zero, and no tick
marks appear.
See Also: - numberOfTicks
- (void)setSelectedCellColor:(NSColor *)theColor
Sets the color of currently selected cell for the receiver. The receiver will
automatically be redrawn as needed.
See Also: - selectedCellIndex
- (void)setSelectedCellIndex:(int)index
Sets the currently selected cell for the receiver. The value for index should
be the index of the cell within an array of colormap entries. For example, if
there are three colors in the colormap and you want to select the middle one,
you will use 1 as the index value. If you had wanted to select the first
(bottom or left, depending on orientation of the control) then you would use an
index of 0. You will need to call setNeedsDisplay:YES for the receiver
for the change to be seen.
See Also: - selectedCellIndex
- (void)setSelectedCellPosition:(float)position
Sets the position of the currently selected cell. The value for position
should be a number between 0.0 and 1.0. This method, in effect, moves the currently
selected marker to position. The receiver will automatically redraw if
necessary.
See Also: - selectedCellPosition
|