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) -> table 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 () 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.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) -> table
Parse a HTML-color. This function can parse colors like #rrggbb and #rrggbbaa and also red. Max 4 chars per channel.

Parameters:

  • col The color to parse

Returns:

    table 4 values representing color in RGBA format (each of them in [0, 1] range) or nil if input is incorrect.

Usage:

    -- This will return 0, 1, 0, 1
 gears.color.parse_color("#00ff00ff")
gears.color.create_solid_pattern (col) -> ()
Create a solid pattern

Parameters:

  • 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:

  • 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 = { <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:

  • 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 = { <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:

  • 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:

  • col The string describing the pattern.

Returns:

    a cairo pattern object

See also:

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

See also:

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:

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:

  • image Image or path to it.
  • new_color New color.

Returns:

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

Parameters:

  • 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:

  • solid
  • png
  • linear
  • radial

Fields

gears.color.color.transparent N/A
No color
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50