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