|
| 1 | +# Colors |
| 2 | + |
| 3 | +The Colors plugin is intended primarily for storing colors so that you can easily access them anywhere in your project, without the need to remember the actual color code or ARGB code. The plugin calculates the desired color and returns it in ARGB format. |
| 4 | + |
| 5 | +The plugin comes with 8 standard colors: white, black, red, green, blue, yellow, cyan and magenta. |
| 6 | + |
| 7 | +## Usage |
| 8 | + |
| 9 | +If you want to use the Colors plugin, import it from the Lightning SDK: |
| 10 | + |
| 11 | +```js |
| 12 | +import { Colors } from '@lightningjs/sdk' |
| 13 | +``` |
| 14 | + |
| 15 | +### Loading on Boot |
| 16 | + |
| 17 | +You can automatically load and initialize the Colors plugin when your App boots, by specifying the `static` method `colors()` on the App class in the file **src/App.js**. |
| 18 | + |
| 19 | +With the `colors` method, you can return a boolean *true*, an object or a string: |
| 20 | + |
| 21 | +```js |
| 22 | +export default class App extends Lightning.Component { |
| 23 | + static colors() { |
| 24 | + //default |
| 25 | + return true |
| 26 | + //object |
| 27 | + return { |
| 28 | + background: '#c9deff', |
| 29 | + focus: '#276ee5' |
| 30 | + } |
| 31 | + //string |
| 32 | + return 'my/custom/colors-file.json' |
| 33 | + } |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +### Defining the Colors File |
| 38 | + |
| 39 | +With the default and *string* option during boot, the Colors plugin expects a JSON file, named **colors.json**. (Or another JSON file at a custom location defined with the string option.) This JSON file should look like the following: |
| 40 | + |
| 41 | +```json |
| 42 | +{ |
| 43 | + "background": "#c9deff", |
| 44 | + "focus": "#276EE5" |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +### Retrieving Colors |
| 49 | + |
| 50 | +To retrieve a color from the Colors plugin, you simply have to import `Colors` into your source file and use the following function to get the color. For example: |
| 51 | + |
| 52 | +```js |
| 53 | +Colors('white').get() |
| 54 | +``` |
| 55 | + |
| 56 | +### Adjusting Color Values |
| 57 | + |
| 58 | +The Colors plugin also enables you to adjust the values of a specific color before retrieving it. |
| 59 | + |
| 60 | +#### Alpha |
| 61 | +If you want your color to have some opacity / alpha, you can use the following code: |
| 62 | + |
| 63 | +```js |
| 64 | +Colors('red').alpha(0.4).get() |
| 65 | +``` |
| 66 | + |
| 67 | +The parameter of the `alpha` function expects a value with between 0 and 1. |
| 68 | + |
| 69 | +#### Hue Value |
| 70 | +You can adjust the Hue value of your color using the following code: |
| 71 | + |
| 72 | +```js |
| 73 | +Colors('red').hue(120).get() |
| 74 | +``` |
| 75 | + |
| 76 | +The parameter of the `hue` function expects a value between 0 and 360. |
| 77 | + |
| 78 | +#### Lightness |
| 79 | +You can adjust the lightness of your color using the following code: |
| 80 | + |
| 81 | +```js |
| 82 | +Colors('green').lightness(0.3).get() |
| 83 | +``` |
| 84 | + |
| 85 | +The parameter of the `lightness` function expects a value between 0 and 1. |
| 86 | + |
| 87 | +#### Saturation |
| 88 | +You can adjust the saturation of your color using the following code: |
| 89 | + |
| 90 | +```js |
| 91 | +Colors('blue').saturation(0.3).get() |
| 92 | +``` |
| 93 | + |
| 94 | +The parameter of the `saturation` function expects a value between 0 and 1. |
| 95 | + |
| 96 | +#### Lighter |
| 97 | +You can also make your color lighter using the following code: |
| 98 | + |
| 99 | +```js |
| 100 | +Colors('red').lighter(0.3).get() |
| 101 | +``` |
| 102 | + |
| 103 | +The `lighter` function takes the current `Lightness` value and changes this value based on the parameter used. |
| 104 | + |
| 105 | +The parameter of the `lighter` function expects a value between 0 and 1. |
| 106 | + |
| 107 | +#### Darker |
| 108 | +Similarly, you can make your color darker using the following code: |
| 109 | + |
| 110 | +```js |
| 111 | +Colors('red').darker(0.3).get() |
| 112 | +``` |
| 113 | + |
| 114 | +The `darker` function takes the current `Brightness` value and changes this value based on the parameter. |
| 115 | + |
| 116 | +The parameter of the `lighter` function expects a value between 0 and 1. |
| 117 | + |
| 118 | +#### Mixing |
| 119 | +If you want to mix two different colors, you can use the `mix` function. |
| 120 | + |
| 121 | +```js |
| 122 | +Colors('cyan').mix(Colors('magenta').get(), 0.5).get() |
| 123 | +``` |
| 124 | + |
| 125 | +The first parameter of this function can be a stored color or an ARGB color. |
| 126 | + |
| 127 | +The second parameter is the mixing percentage. We normalized this percentage to a value from 0 to 1. |
| 128 | + |
| 129 | +### Chaining |
| 130 | + |
| 131 | +The Colors plugin also enables you to chain functions. For example, making a specific color darker and give it a certain opacity: |
| 132 | + |
| 133 | +```js |
| 134 | +Colors('red').darker(0.2).alpha(0.8).get() |
| 135 | +``` |
0 commit comments