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.
See also:
- create_pattern_uncached
- create_solid_pattern
- create_png_pattern
- create_linear_pattern
- create_radial_pattern
Info:
- Copyright: 2010 Uli Schlachter
- Author: Uli Schlachter
Functions
| returns... (col) | |
| parse_color (col) | Parse a HTML-color. |
| create_solid_pattern (col) | Create a solid pattern |
| create_png_pattern (file) | Create an image pattern from a png file |
| create_linear_pattern (arg) | Create a linear pattern object. |
| create_radial_pattern (arg) | Create a radial pattern object. |
| create_pattern_uncached (col) | Create a pattern from a given string. |
| create_pattern (col) | Create a pattern from a given string, same as gears.color. |
| create_opaque_pattern (col) | Check if a pattern is opaque. |
| recolor_image (image, new_color) | Fill non-transparent area of an image with a given color. |
| ensure_pango_color (check_color, fallback) | Get a valid color for Pango markup |
Tables
| types | Mapping of all supported color types. |
Fields
| transparent | No color |
Functions
Methods- returns... (col)
-
- col string The string describing the pattern.
Returns:
-
a cairo pattern object
- parse_color (col)
-
Parse a HTML-color.
This function can parse colors like
#rrggbband#rrggbbaaand alsored. Max 4 chars per channel.- 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")
- create_solid_pattern (col)
-
Create a solid pattern
- col The color for the pattern
Returns:
-
A cairo pattern object
- create_png_pattern (file)
-
Create an image pattern from a png file
- file The filename of the file
Returns:
-
a cairo pattern object
- 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,y0andx1,y1are the start and stop point of the pattern. For the explanation of<stops>, see color.create_pattern.Returns:
-
a cairo pattern object
- 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,y0andx1,y1are the start and stop point of the pattern.r0andr1are the radii of the start / stop circle. For the explanation of<stops>, see color.create_pattern.Returns:
-
a cairo pattern object
- 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.
- col The string describing the pattern.
Returns:
-
a cairo pattern object
See also:
- create_pattern (col)
-
Create a pattern from a given string, same as gears.color.
- col
See also:
- 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.
- col An argument that create_pattern accepts.
Returns:
-
The pattern if it is surely opaque, else nil
- recolor_image (image, new_color)
-
Fill non-transparent area of an image with a given color.
- image Image or path to it.
- new_color New color.
Returns:
-
Recolored image.
- ensure_pango_color (check_color, fallback)
-
Get a valid color for Pango markup
- 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
- types
-
Mapping of all supported color types. New entries can be added.
Fields:
- solid
- png
- linear
- radial