ProColor Public API
Many of ProColor's methods and members are for internal use only. However, these members
and methods are all public:
- new ProColor(options)
Creates, displays, and returns a new ProColor object with the given options.
- procolor.color
The current color as selected by the user. This will always be a string in canonical hex RGB
form, '#RRGGBB".
- procolor.div
The dynamically-created containing element of the color-picker and all of its child controls.
This element is publicly-visible, but its child elements should be considered implementation
details, and they can and will likely change in future versions of ProColor.
- procolor.options.imgPath
This variable is used to control the image path used by the automatic-attachment routine,
which creates ProColor objects attached to <input> controls whose classes
contain 'procolor'. The default image path is 'img/procolor_win_'. You
must set this value in your page's <head> if you are going to set it at all.
- procolor.options.showInField
This variable controls how the automatically-attached ProColor objects will have their
showInField option set. You
must set this value in your page's <head> if you are going to set it at all.
- procolor.positionPopup()
If this is a popup and the associated input element is moved on the page, you should call this
method to reposition the popup above or below the moved input element.
- procolor.close()
Closes and destroys a color-picker. The ProColor object will still exist after calling this
function, but none of its elements will exist anymore. Note that the procolor.color
member will still be valid after this is called.
- procolor.update(mode, color, sources)
Programmatically change the selected color. mode must be either "rgb" or
"hsb", and the color must be an object of one of the following two forms,
depending on the mode:
{ r:red, g:green, b:blue }
{ hue:hue, sat:saturation, brt:brightness
The RGB values range from 0 to 255, inclusive, and the HSB values range from 0 to 359 (hue)
and 0 to 100 (saturation & brightness). Fractional values are allowed, and values
outside allowed ranges will be clipped.
The sources is an array of strings describing parts of the color-picker that
should not be updated. If update() is called externally (i.e., by you),
this array should always be empty (i.e., it should always be []).
This method updates the visual appearance of the color-picker, and also updates the
input field (if appropriate) and updates procolor.color.
- procolor.formatOutput(color, format)
Given a color in a recognizable format (like "#RRGGBB"), convert that color to the
given output format. This uses the same formatting logic as the outputFormat
option above.
- procolor.decodeHexColor(color)
Given a color in a recognizable format (like "#RRGGBB"), convert that to a clean RGB object,
same as would be passed to procolor.update(). This tries several different ways
to decode the color. If it is unable to decode the color, it returns false instead
of an RGB object.
- procolor.trueBrightness(rgb)
Given an RGB object describing a color, this returns the brightness of that object, on the
range of [0,1]. This is weighted according to human color perception, with weights of
0.3, 0.59, and 0.11, for red, green, and blue respectively.
- procolor.computeTextColor(rgb)
Given an RGB object describing a background color, this will return a new RGB object
describing a similarly-hued color that can be used for displaying legible text against
that background.
- procolor.RGBtoHSB(rgb)
Given an RGB color object, this returns an equivalent HSB color object,
always with valid (but possibly with fractional) integer values.
- procolor.HSBtoRGB(rgb)
Given an HSB color object, this returns an equivalent RGB color object,
always with valid (but possibly with fractional) integer values.
- procolor.acceptAndClose()
Simulate the user pressing Enter or double-clicking on the color-picker; this calls
options.onAcceptClick, and then procolor.Close() (but only if this
is in 'popup' mode.
- procolor.cancelAndClose()
Simulate the user pressing Esc or clicking outside the color-picker; this calls
options.onCancelClick, and then procolor.Close() (but only if this
is in 'popup' mode.
MouseCapture Public API
ProColor uses a small library named "MouseCapture" for performing mouse tracking, and you can
use it in your own programs. Its usage is very simple; create a MouseCapture object, call
mousecapture.begin(), and then within your callback, call mousecapture.end() when the mouse
button is released. Its API is documented below:
- new MouseCapture()
Creates and returns a new MouseCapture object with the given options. A MouseCapture
object can be used to capture mouse input from a mouse-button-press until its release.
- mousecapture.setCursor(cursor)
In the current mouse capture, change the mouse cursor to the given type. This takes a
standard CSS cursor type, such as 'default' or 'pointer' or 'crosshair'.
- mousecapture.begin(callback)
Begin the mouse capture. This will capture all mouse and keyboard input events and send
them to the given callback function. The callback will be called as callback(event, eventType).
- mousecapture.end()
This ends a mouse capture and allows events to propagate normally.