-
Notifications
You must be signed in to change notification settings - Fork 149
/
doc.html
200 lines (194 loc) · 8.78 KB
/
doc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
<!DOCTYPE html>
<html>
<head>
<title>Flexi ColorPicker Documentation</title>
<style type="text/css">
#page {
width: 880px;
margin: 0 auto;
background-color: #EAEAEA;
padding: 30px;
}
h1 {
font-family: Arial, Helvetica, sans-serif;
color: #565857;
}
h2 {
font-family: Arial, Helvetica, sans-serif;
color: #CF5B40;
}
h3 {
text-decoration: underline;
}
em {
font-weight: bold;
}
</style>
</head>
<body>
<div id="page">
<h1>Flexi ColorPicker Documentation</h1>
<p>
Welcome to Flexi ColorPicker Documentation. This document describes
the usage and API of the color picker. The library was built
with simplicity in mind so there should not be anything what
can surprise you.
</p>
<h2>Usage</h2>
<p>The color picker is built on top of HSV color model.
The only two parts of the picker is therefore
the slider, which allows you to select "hue" and
the picker for selecting "saturation" and "value".
Both the slider and the picker have to be specified
as HTML elements. The main advantage is that their
dimensions can be set in CSS.
The color picker is not dependent on any external library
or CSS stylesheet. You get all the functionality by
including only one tiny JavaScript file (see example below).
<p>
<p>
Once you have your markup ready and CSS width and
height set for both the slider and picker, the
only thing you have to do is to instantiate
the "ColorPicker" object. You can do that
by calling the <em>ColorPicker()</em> function
passing the slider, the picker element and
callback as arguments. The callback is called
whenever the color changes and it is passed
color in hexadecimal, hsv and rgb formats.
Hexadecimal format is the string used most commonly
in CSS. Hsv and Rgb are objects with these properties:
hsv: { h: /* hue [0,359] (angle) */, s: /* saturation [0,1] */, v: /* value [0,1] */ }
rgb: { r: /* red [0,255] */, g: /* green [0,255] */, b: /* blue [0,255] */ }
</pre>
</p>
<h2>Basic example</h2>
<pre>
<html>
<head>
<script type="text/javascript"
src="colorpicker.js"></script>
<style type="text/css">
#picker { width: 200px; height: 200px }
#slide { width: 30px; height: 200px }
</style>
</head>
<body>
<div id="picker"></div>
<div id="slide"></div>
<script type="text/javascript">
ColorPicker(
document.getElementById('slide'),
document.getElementById('picker'),
function(hex, hsv, rgb) {
console.log(hsv.h, hsv.s, hsv.v);
console.log(rbg.r, rgb.g, rgb.b);
document.body.style.backgroundColor = hex;
});
</script>
</body>
</html>
</pre>
<p>Note that you can set arbitrary dimensions,
position, border and other CSS properties
to the slider and picker element as you would
do with any other HTML element on the page.</p>
<h2>Advanced usage</h2>
<h3>Indicators</h3>
<p>
Flexi color picker allows you to set indicators - elements indicating the currently
selected color. Following the Flexi color picker philosophy, there is no built-in images
for the indicators. Instead, user has freedom to use any element he wants. It could
be an <em>img</em> tag, <em>div</em> tag or any other object which can then
be styled in CSS the usual way.</p>
<p>
The user is expected to create a wrapper around the picker and picker indicator and another wrapper for the slide and slide indicator.
The wrapper has to be a positioned element (in CSS: position relative/absolute/fixed).
The <em>ColorPicker</em> passes coordinates of the indicators as arguments into
the <em>callback</em>. The user can therefore set the left/top coordinate
of an indicator inside the callback (assuming the indicator is absolutely positioned).
</p>
<p>
As the common usage is to center the indicator around the indicator
position, the ColorPicker provides a helper function to do that to save the user from typing.
See below an example and implementation of the helper for the curious ones.
</p>
<pre>
<style type="text/css">
#picker-wrapper {
width: 200px;
height: 200px;
position: relative;
}
#slide-wrapper {
width: 30px;
height: 200px;
position: relative;
}
#picker-indicator {
width: 3px;
height: 3px;
position: absolute;
border: 1px solid white;
}
#slide-indicator {
width: 100%;
height: 10px;
position: absolute;
border: 1px solid black;
}
</style>
<div id="picker-wrapper">
<div id="picker"></div>
<div id="picker-indicator"></div>
</div>
<div id="slide-wrapper">
<div id="slide"></div>
<div id="slide-indicator"></div>
</div>
<script type="text/javascript">
ColorPicker(document.getElementById('slide'), document.getElementById('picker'),
function(hex, hsv, rgb, mousePicker, mouseSlide) {
ColorPicker.positionIndicators(
document.getElementById('slide-indicator'),
document.getElementById('picker-indicator'),
mouseSlide, mousePicker
);
document.body.style.backgroundColor = hex;
});
</script>
</pre>
<h4>Implementation of the <em>ColorPicker.positionIndicators</em></h4>
<p>Note that it is not necessary to use the helper to position the indicators.
As you can see below the implementation is straigtforward.
<pre>
ColorPicker.positionIndicators = function(slideIndicator, pickerIndicator, slideIndicatorPosition, pickerIndicatorPosition) {
if (slideIndicatorPosition) {
pickerIndicator.style.left = ''; // reset the left coordinate
pickerIndicator.style.top = '0px';
pickerIndicator.style.right = '0px';
slideIndicator.style.top = (slideIndicatorPosition.y - slideIndicator.offsetHeight/2) + 'px';
}
if (pickerIndicatorPosition) {
pickerIndicator.style.top = (pickerIndicatorPosition.y - pickerIndicator.offsetHeight/2) + 'px';
pickerIndicator.style.left = (pickerIndicatorPosition.x - pickerIndicator.offsetWidth/2) + 'px';
}
};
</pre>
<h3>Setting a color</h3>
<p>
The color of the color picker can also be set in the program instead
of by the user mouse clicks. The usage is straightforward. The <em>ColorPicker</em>
instance provides three methods: <em>setHsv(hsvObject)</em>, <em>setRgb(rgbObject)</em>
and <em>setHex(hexString)</em>. See example below as it describes it better.
</p>
<pre>
var c = ColorPicker( ... );
c.setHsv({ h: 310, s: .3, v: .7 }); // hue is an angle <0..359>
c.setRgb({ r: 230, g: 150, b: 30 }); // integer range <0..255>
c.setRgb({ r: .7, g: .2, b: .5 }); // float range <0..1>
c.setHex('#223344'); // usual HTML hex color string
</pre>
</div>
</body>
</html>