# Module: `gears.color`

This module simplifies the creation of cairo pattern objects.

In most places in awesome where a color is needed, the provided argument is passed to gears.color, which actually calls create_pattern and creates a pattern from a given string or table.

This function can create solid, linear, radial and png patterns.

A simple example for a solid pattern is a hexadecimal color specification. For example `#ff8000` creates a solid pattern with 100% red, 50% green and 0% blue. Limited support for named colors (`red`) is also provided.

In general, patterns are specified as strings formatted as `"type:arguments"`. `"arguments"` is specific to the pattern being used. For example, one can use: "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff" The above will call create_radial_pattern with the provided string, after stripping the `radial:` prefix.

Alternatively, patterns can be specified via tables. In this case, the table's 'type' member specifies the type. For example: { type = "radial", from = { 50, 50, 10 }, to = { 55, 55, 30 }, stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } } } Any argument that cannot be understood is passed to create_solid_pattern.

Please note that you MUST NOT modify the returned pattern, for example by calling :set_matrix() on it, because this function uses a cache and your changes could thus have unintended side effects. Use create_pattern_uncached if you need to modify the returned pattern.

### Info:

- Copyright: 2010 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Static module functions

gears.color.parse_color (col) -> (number, number, number, number, nil) | Parse a HTML-color. |
gears.color.create_solid_pattern (col) -> () | Create a solid pattern |
gears.color.create_png_pattern (file) -> () | Create an image pattern from a png file |
gears.color.create_linear_pattern (arg) -> () | Create a linear pattern object. |
gears.color.create_radial_pattern (arg) -> () | Create a radial pattern object. |
gears.color.create_pattern_uncached (col) -> () | Create a pattern from a given string. |
gears.color.create_pattern () -> gears.color | Create a pattern from a given string, same as gears.color. |
gears.color.create_opaque_pattern (col) -> () | Check if a pattern is opaque. |
gears.color.recolor_image (image, new_color) -> () | Fill non-transparent area of an image with a given color. |
gears.color.change_opacity (input, opacity) -> color | Take an input color and set a different opacity. |
gears.color.to_rgba_string (color, fallback) -> string | Convert a color back to an hexadecimal color code. |
gears.color.ensure_pango_color (check_color, fallback) -> string | Get a valid color for Pango markup |

## Tables

color.types | Mapping of all supported color types. |

## Fields

gears.color.color.transparent | N/A | No color |

## Static module functions

🔗 gears.color.parse_color (col) -> (number, number, number, number, nil)
  Parse a HTML-color. This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`. Max 4 chars per channel.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  col |  |  | The color to parse

  ### Returns:

  1. number between 0 and 1 for the 'red' value (1st channel)
  2. number between 0 and 1 for the 'green' value (2nd channel)
  3. number between 0 and 1 for the 'blue' value (3rd channel)
  4. number between 0 and 1 for the 'opacity' value (4th channel) if the incoming color code only has 3 values (only rgb, not opacity) the 4th return value is 1.
  5. nil if input is incorrect

  ### Usage:

      -- Both of the following will return 0, 0.4, 0.8, 1
      gears.color.parse_color("#0066ccff")
      gears.color.parse_color("#0066cc")

🔗 gears.color.create_solid_pattern (col) -> ()
  Create a solid pattern

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  col |  |  | The color for the pattern

  ### Returns:

  A cairo pattern object
🔗 gears.color.create_png_pattern (file) -> ()
  Create an image pattern from a png file

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  file |  |  | The filename of the file

  ### Returns:

  a cairo pattern object
🔗 gears.color.create_linear_pattern (arg) -> ()
  Create a linear pattern object. The pattern is created from a string. This string should have the following form: `"x0, y0:x1, y1:<stops>"` Alternatively, the pattern can be specified as a table: { type = "linear", from = { x0, y0 }, to = { x1, y1 }, stops = { } } `x0,y0` and `x1,y1` are the start and stop point of the pattern. For the explanation of `<stops>`, see `color.create_pattern`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  | string or table | The argument describing the pattern.

  ### Returns:

  a cairo pattern object
🔗 gears.color.create_radial_pattern (arg) -> ()
  Create a radial pattern object. The pattern is created from a string. This string should have the following form: `"x0, y0, r0:x1, y1, r1:<stops>"` Alternatively, the pattern can be specified as a table: { type = "radial", from = { x0, y0, r0 }, to = { x1, y1, r1 }, stops = { } } `x0,y0` and `x1,y1` are the start and stop point of the pattern. `r0` and `r1` are the radii of the start / stop circle. For the explanation of `<stops>`, see `color.create_pattern`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  arg |  | string or table | The argument describing the pattern

  ### Returns:

  a cairo pattern object
🔗 gears.color.create_pattern_uncached (col) -> ()
  Create a pattern from a given string. For full documentation of this function, please refer to `color.create_pattern`. The difference between `color.create_pattern` and this function is that this function does not insert the generated objects into the pattern cache. Thus, you are allowed to modify the returned object.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  col |  |  | The string describing the pattern.

  ### Returns:

  a cairo pattern object

  ### See also:

  create_pattern | Create a pattern from a given string, same as gears.color. | static module functions

🔗 gears.color.create_pattern () -> gears.color
  Create a pattern from a given string, same as gears.color.

  ### Returns:

  gears.color A cairo pattern object.

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

🔗 gears.color.create_opaque_pattern (col) -> ()
  Check if a pattern is opaque. A pattern is transparent if the background on which it gets drawn (with operator OVER) doesn't influence the visual result.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  col |  |  | An argument that create_pattern accepts.

  ### Returns:

  The pattern if it is surely opaque, else nil
🔗 gears.color.recolor_image (image, new_color) -> ()
  Fill non-transparent area of an image with a given color.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  image |  |  | Image or path to it.
  new_color |  |  | New color.

  ### Returns:

  Recolored image.
🔗 gears.color.change_opacity (input, opacity) -> color
  Take an input color and set a different opacity.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  input |  | string or pattern | The input color.
  opacity |  | number | A floating point number between 0 and 1.

  ### Returns:

  color The new color if successful or `input` if invalid.
🔗 gears.color.to_rgba_string (color, fallback) -> string
  Convert a color back to an hexadecimal color code.

  This takes an input color, pattern or gradient and attempt to convert it to a color. If this fails, `fallback` is returned. This is useful when a color needs to be concatenated into a Pango markup string.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  color |  | pattern, string or gradient | Note that only solid colors can be convedted to the `RGBA` format. | Not applicable
  fallback | Optional | pattern, string or gradient | The color to return if `color` cannot be converted to a string. | `nil`

  ### Returns:

  string The color in `#rrggbbaa` format.

  ### See also:

  gears.color.ensure_pango_color | Get a valid color for Pango markup | static module functions

🔗 gears.color.ensure_pango_color (check_color, fallback) -> string
  Get a valid color for Pango markup

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  check_color |  |  | The color to check.
  fallback |  | string | The color to return if the first is invalid. (default: black)

  ### Returns:

  string color if it is valid, else fallback.

## Tables

🔗 color.types
  Mapping of all supported color types. New entries can be added.

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  solid |  |  |
  png |  |  |
  linear |  |  |
  radial |  |  |

## Fields

🔗 gears.color.color.transparent N/A
  No color

generated by LDoc 1.5.0