cwc

• Index

Contents

• Static module functions
• Deprecated functions

Libraries

• cuteful.client
• cuteful.enum
• cuteful.tag
• gears.matcher
• gears.surface

Core components

• cwc
• cwc.client
• cwc.container
• cwc.kbd
• cwc.plugin
• cwc.pointer
• cwc.screen

Plugins

• cwc.cwcle

Utility libraries

• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.object
• gears.protected_call
• gears.sort
• gears.string
• gears.table

Theme related libraries

• gears.color

Classes

• gears.cache
• gears.matrix

Documentation

• Getting Started
• Custom Layout
• C Plugin

Module: gears.surface

Utilities to integrate and manipulate Cairo drawing surfaces.

Static module functions

Deprecated functions

Static module functions

🔗 gears.surface.load_uncached_silently (surface, default) -> ()

Try to convert the argument into an lgi cairo surface. This is usually needed for loading images by file name.

Parameters:

Name		Type(s)	Description
surface			The surface to load or nil
default			The default value to return on error; when nil, then a surface in an error state is returned.

Returns:

1. The loaded surface, or the replacement default
2. An error message, or nil on success.

🔗 gears.surface.load_silently (surface, default) -> ()

Try to convert the argument into an lgi cairo surface. This is usually needed for loading images by file name and uses a cache. In contrast to load(), errors are returned to the caller.

Parameters:

Name		Type(s)	Description
surface			The surface to load or nil
default			The default value to return on error; when nil, then a surface in an error state is returned.

Returns:

1. The loaded surface, or the replacement default, or nil if called with nil.
2. An error message, or nil on success.

🔗 gears.surface.load_uncached (surface) -> ()

Try to convert the argument into an lgi cairo surface. This is usually needed for loading images by file name. Errors are handled via gears.debug.print_error.

Parameters:

Name		Type(s)	Description
surface			The surface to load or nil

Returns:

The loaded surface, or nil

🔗 gears.surface (surface) -> ()

Try to convert the argument into an lgi cairo surface. This is usually needed for loading images by file name. Errors are handled via gears.debug.print_error.

Parameters:

Name		Type(s)	Description
surface			The surface to load or nil

Returns:

The loaded surface, or nil.

🔗 gears.surface.get_size (surf) -> ()

Get the size of a cairo surface

Parameters:

Name		Type(s)	Description
surf			The surface you are interested in

Returns:

The surface's width and height.

🔗 gears.surface.duplicate_surface (s) -> ()

Create a copy of a cairo surface. The surfaces returned by surface.load are cached and must not be modified to avoid unintended side-effects. This function allows to create a copy of a cairo surface. This copy can then be freely modified. The surface returned will be as compatible as possible to the input surface. For example, it will likely be of the same surface type as the input. The details are explained in the create_similar function on a cairo surface.

Parameters:

Name		Type(s)	Description
s			Source surface.

Returns:

The surface's duplicate.

🔗 gears.surface.load_from_shape (width, height, shape, shape_color, bg_color) -> cairo.surface

Create a surface from a gears.shape Any additional parameters will be passed to the shape function

Parameters:

Name		Type(s)	Description	Default value
width		number	The surface width	Not applicable
height		number	The surface height	Not applicable
shape			A gears.shape compatible function	Not applicable
shape_color	Optional		The shape color or pattern	"#000000"
bg_color	Optional		The surface background color	"#00000000"

Returns:

cairo.surface the new surface

🔗 gears.surface.apply_shape_bounding (draw, shape, ...)

Apply a shape to a client or a wibox.

If the wibox or client size change, this function need to be called again.

Parameters:

Name		Type(s)	Description
draw		client or wibox	A wibox or a client.
shape		gears.shape or function	The shape.
...	Optional		Any additional parameters will be passed to the shape function.

🔗 gears.surface.crop_surface {[args]} -> ()

Crop a surface on its edges.

Parameters:

Note: This static module functions uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be crop_surface{}. This is a Lua shortcut syntax equivalent to crop_surface({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.

Name		Type(s)	Description	Default value
args	Optional	table		nil
left	Optional	integer	Left cutoff, cannot be negative	0
right	Optional	integer	Right cutoff, cannot be negative	0
top	Optional	integer	Top cutoff, cannot be negative	0
bottom	Optional	integer	Bottom cutoff, cannot be negative	0
ratio	Optional	number or nil	Ratio to crop the image to. If edge cutoffs and ratio are given, the edge cutoffs are computed first. Using ratio will crop the center out of an image, similar to what "zoomed-fill" does in wallpaper setter programs. Cannot be negative	nil
surface	Optional	surface	The surface to crop	nil

Returns:

The cropped surface

Deprecated functions

🔗 gears.surface.widget_to_svg (widget, path, width, height)

Create an SVG file with this widget content. This is dynamic, so the SVG will be updated along with the widget content. because of this, the painting may happen hover multiple event loop cycles.

Parameters:

Name		Type(s)	Description
widget		widget	A widget
path		string	The output file path
width		number	The surface width
height		number	The surface height

Returns:

1. The cairo surface
2. The hierarchy.

See also:

🔗 gears.surface.widget_to_surface (widget, width, height, format)

Create a cairo surface with this widget content. This is dynamic, so the SVG will be updated along with the widget content. because of this, the painting may happen hover multiple event loop cycles.

Parameters:

Name		Type(s)	Description	Default value
widget		widget	A widget	Not applicable
width		number	The surface width	Not applicable
height		number	The surface height	Not applicable
format	Optional		The surface format	cairo.Format.ARGB32

Returns:

1. The cairo surface
2. The hierarchy.

See also: