You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

235 lines
9.8 KiB

7 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
  1. # tinyColorPicker and colors
  2. Looking for mobile first, tiny foot print, fast, scaleable, flexible, pluggable and a rich color model...<br>
  3. This small (4.9KB gZip, 10.8KB minified, no HTML, images or css needed) HSB colorpicker is based on a subset of [colors.js](https://github.com/PitPik/colorPicker/blob/master/colors.js) from it's big brother [colorPicker](https://github.com/PitPik/colorPicker/) for a precise and rich color model, supports all modern features like touch and MS pointer, GPU accelerated rendering, battery friendly requestAnimationFrame and provides a lot of hooks for developers to write plugins.
  4. tinyColorPicker now supports AMD / CommonJS and bower.
  5. ##Demo
  6. See **demo** at [dematte.at/tinyColorPicker](http://dematte.at/tinyColorPicker)
  7. <img src="development/screen-shot-all.jpg" />
  8. All the WCAG 2.0 calculations for readability are also based on opacity levels of all layers.<br>
  9. Supported color spaces are: rgb, hsv(b), hsl, HEX
  10. ## Usage
  11. ```javascript
  12. <script type="text/javascript" src="jqColorPicker.min.js"></script>
  13. <script type="text/javascript">
  14. $('.color').colorPicker(); // that's it
  15. // $().colorPicker.destroy(); // for singlePageApps
  16. </script>
  17. ```
  18. ## AMD / CommonJS wrapper
  19. tinyColorPicker now supports AMD and CommonJS import (thanks to [Munawwar](https://github.com/Munawwar)).
  20. ## bower support
  21. tinyColorPicker can be received by bower:
  22. ```javascript
  23. bower install tinyColorPicker
  24. ```
  25. ##jqColorPicker.js
  26. colorPicker uses an instance of Colors and passes the options to it, so some values are the same...
  27. ```javascript
  28. $('.color').colorPicker({
  29. color: ..., // see Colors...
  30. customBG: '#FFF' // see Colors...
  31. animationSpeed: 150, // toggle animation speed
  32. GPU: true, // use transform: translate3d
  33. doRender: true | 'selector', // manipulate color and bgColor of input field (on certain elements if selector)
  34. opacity: true, // enable / disable alpha slider
  35. renderCallback: function($elm, toggled) {}, // this === instance; $elm: the input field;toggle === true -> just appeared; false -> opposite; else -> is rendering on pointer move
  36. // toggled true/false can for example be used to check if the $elm has a certain className and then hide alpha,...
  37. buildCallback: function($elm) {}, // this === instance; $elm: the UI
  38. css: '', // replaces existing css
  39. cssAddon: '', // adds css to existing
  40. margin: '', // positioning margin (can also be set in cssAddon)
  41. scrollResize: true // toggle for reposition colorPicker on window.resize/scroll
  42. gap: 4 // gap to right and bottom edge of view port if repositioned to fit
  43. preventFocus: false // prevents default on focus of input fields (e.g. no keyboard on mobile)
  44. body: document.body // the element where the events are attached to (touchstart, mousedown, pointerdown, focus, click, change)
  45. });
  46. ```
  47. ####Some tips
  48. The renderCallback can be used as openCallback and closeCallback:
  49. ```javascript
  50. renderCallback: function($elm, toggled) {
  51. if (toggled === true) { // simple, lightweight check
  52. // ... like an open callback
  53. } else if (toggled === false) {
  54. // ... like a close callback
  55. }
  56. }
  57. ```
  58. Here you can fire events if necessary or check for a className or data attribute on $elm to see if there is a hint for hiding the opacity slider:
  59. ```javascript
  60. this.$UI.find('.cp-alpha').toggle(!$elm.hasClass('no-alpha'));
  61. ```
  62. ##colors.js
  63. This section only shows the options for color.js. They are picked up automatically if set in $('.color').colorPicker
  64. ```javascript
  65. Colors({ // all options have a default value...
  66. color: 'rgba(204, 82, 37, 0.8)', // initial color (#RGB, RGB, #RRGGBB, RRGGBB, rgb(r, g, b), ...)
  67. grey: {r: 0.298954, g: 0.586434, b: 0.114612}, // CIE-XYZ 1931
  68. luminance: {r: 0.2126, g: 0.7152, b: 0.0722}, // W3C 2.0
  69. valueRanges: {rgb: {r: [0, 255], g: [0, 255], b: [0, 255]}, hsv:...}, // skip ranges if no conversion required
  70. customBG: '#808080' // the solid bgColor behind the chosen bgColor (saved color)
  71. convertCallback: function(colors, type){}, // callback function after color convertion for further calculations...
  72. });
  73. ```
  74. ##The color model, the methods and more
  75. After initializing Color or ColorPicker you'll get a clean but rhich model of the instance:
  76. ```javascript
  77. myColors: {
  78. colors: { all kinds of color values... see later},
  79. options: { all the options you set or that are set as default... },
  80. __proto__: { // all methods Color uses (See https://github.com/PitPik/colorPicker for details)
  81. setColor: function(newCol, type, alpha) {},
  82. setCustomBackground: function(col) {},
  83. saveAsBackground: function() {},
  84. // new method: converts current color to HTML-String like: rgba(123, 234, 0, 0.89)
  85. // forceAlpha === true / false -> alway / never print alpha, === undefined -> auto
  86. toString: function('rgb' || 'hsl' || 'hex' || '' -> 'rgb', forceAlpha) {},
  87. }
  88. }
  89. ```
  90. colors.js is a quite handy tool for color calculations/conversion (gray value, contrast and luminance, etc...). It can also calculate layer mixes between background and foreground colors and therefore make calculations about readability (WCAG 2.0 standard).
  91. If you need more complex calculations or more color spaces, use the version from https://github.com/PitPik/colorPicker. It supports also cmy, cmyk, XYZ and Lab.
  92. ```javascript
  93. myColorPicker: {
  94. $trigger: ... // jQuery object of active trigger or null if none active
  95. $UI: ... // jQuery object of the colorPicker HTML element
  96. color: { // instance of Color inside colorPicker
  97. colors: { all kinds of color values... see later},
  98. options: { all the options you set or that are set as default... },
  99. __proto__: { all methods Color uses ... see above}
  100. },
  101. __proto__: { // all methods ColorPicker uses
  102. render: function() {},
  103. toggle: function(openClose) {} // openClose: true = open; false = close
  104. }
  105. }
  106. ```
  107. The color model
  108. ```javascript
  109. HEX: // current color as HEX (upper case, 6 digits)
  110. rgb: // current RGB color as normalized values (0 - 1)
  111. r: // red
  112. g: // green
  113. b: // blue
  114. hsv: // current color values in normalized HSV (HSB) model
  115. h: // hue
  116. s: // saturation
  117. v: // value (brightness)
  118. hsl: // current color values in normalized HSL model
  119. h: // hue
  120. s: // saturation
  121. l: // lightness
  122. RND: // all above colors in their defined ranges
  123. rgb: // current RGB color, rounded between 0 and 255
  124. r: // red (0 - 255)
  125. g: // green (0 - 255)
  126. b: // blue (0 - 255)
  127. hsv: // see above
  128. h: // hue (0 - 360 degrees)
  129. s: // saturation (0 - 100 %)
  130. v: // value (brightness) (0 - 100 %)
  131. hsl: // see above
  132. h: // hue (0 - 360 degrees)
  133. s: // saturation (0 - 100 %)
  134. l: // lightness (0 - 100 %)
  135. background: // saved (background) color (saveAsBackground(){})
  136. rgb: // color in RGB model
  137. r: // red
  138. g: // green
  139. b: // blue
  140. RGB: // RGB color, rounded between 0 and 255
  141. r: // red (0 - 255)
  142. g: // green (0 - 255)
  143. b: // blue (0 - 255)
  144. alpha: // alpha or opacity value (0 - 1)
  145. equivalentGrey: // r = g = b = (0 - 255)
  146. rgbaMixBlack: // saved (background) color mixed with solid black color
  147. r: // red
  148. g: // green
  149. b: // blue
  150. a: // resulting alpha or opacity value (0 - 1)
  151. luminance: // luminance of resulting mix (0 - 1)
  152. rgbaMixCustom: // saved (background) color mixed with custom (solid) color
  153. r: // red
  154. g: // green
  155. b: // blue
  156. a: // resulting alpha or opacity value (0 - 1)
  157. luminance: // luminance of resulting mix (0 - 1)
  158. rgbaMixWhite: // saved (background) color mixed with solid white color
  159. r: // red
  160. g: // green
  161. b: // blue
  162. a: // resulting alpha or opacity value (0 - 1)
  163. luminance: // luminance of resulting mix (0 - 1)
  164. alpha: // alpha or opacity value (0 - 1) of current color
  165. equivalentGrey: // r = g = b = (0 - 1)
  166. HUELuminance: // luminance of hue (in full brightnes and saturation) (0 - 1)
  167. RGBLuminance: // luminance of the current color
  168. hueRGB: // rounded integer value of current color in rgb model with full saturation and brightness
  169. r: // red (0 - 255)
  170. g: // green (0 - 255)
  171. b: // blue (0 - 255)
  172. saveColor: // '' or 'web smart' or 'web save', if so.
  173. webSave: // closest web-save color
  174. r: // red (0 - 255)
  175. g: // green (0 - 255)
  176. b: // blue (0 - 255)
  177. webSmart: // closest web-smart color
  178. r: // red (0 - 255)
  179. g: // green (0 - 255)
  180. b: // blue (0 - 255)
  181. rgbaMixBG: // color mix result: current color above saved (background) color
  182. r: // red (0 - 1)
  183. g: // green (0 - 1)
  184. b: // blue (0 - 1)
  185. a: // resulting alpha or opacity value (0 - 1)
  186. luminance: // luminance of resulting mix (0 - 1)
  187. rgbaMixBGMixCustom: // color mix result: current color above saved (background) color above solid custom color
  188. r: // red (0 - 1)
  189. g: // green (0 - 1)
  190. b: // blue (0 - 1)
  191. a: // resulting alpha or opacity value (0 - 1)
  192. luminance: // luminance of resulting mix (0 - 1)
  193. luminanceDelta: // luminance difference between current color and resulting saved-custom mix (0 - 1)
  194. hueDelta: // hue difference between current color and resulting saved-custom mix (0 - 1)
  195. WCAG2Ratio: // readability vale (1 - 21, 1:1 to 21:1)
  196. rgbaMixBlack: // color mix result: current color above solid black
  197. r: // red (0 - 1)
  198. g: // green (0 - 1)
  199. b: // blue (0 - 1)
  200. a: // resulting alpha or opacity value (0 - 1)
  201. luminance: // luminance of resulting mix (0 - 1)
  202. WCAG2Ratio: // readability vale (1 - 21, 1:1 to 21:1)
  203. rgbaMixWhite: // color mix result: current color above solid white
  204. r: // red (0 - 1)
  205. g: // green (0 - 1)
  206. b: // blue (0 - 1)
  207. a: // resulting alpha or opacity value (0 - 1)
  208. luminance: // luminance of resulting mix (0 - 1)
  209. WCAG2Ratio: // readability vale (1 - 21, 1:1 to 21:1)
  210. ```