# Module: `gears.surface`

Utilities to integrate and manipulate Cairo drawing surfaces.

### Info:

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

## Static module functions

gears.surface.load_uncached_silently (surface, default) -> () | Try to convert the argument into an lgi cairo surface. |
gears.surface.load_silently (surface, default) -> () | Try to convert the argument into an lgi cairo surface. |
gears.surface.load_uncached (surface) -> () | Try to convert the argument into an lgi cairo surface. |
gears.surface (surface) -> () | Try to convert the argument into an lgi cairo surface. |
gears.surface.get_size (surf) -> () | Get the size of a cairo surface |
gears.surface.duplicate_surface (s) -> () | Create a copy of a cairo surface. |
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 |
gears.surface.apply_shape_bounding (draw, shape, ...) | Apply a shape to a client or a wibox. |
gears.surface.crop_surface {[args]} -> () | Crop a surface on its edges. |

## Deprecated functions

gears.surface.widget_to_svg (widget, path, width, height) | Create an SVG file with this widget content. | Deprecated
gears.surface.widget_to_surface (widget, width, height, format) | Create a cairo surface with this widget content. | Deprecated

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

  wibox.widget.draw_to_svg_file | Create an SVG file showing this widget. (wibox.widget) | static module functions
  wibox.widget.draw_to_image_surface | Create a cairo image surface showing this widget. (wibox.widget) | static module functions

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

  wibox.widget.draw_to_svg_file | Create an SVG file showing this widget. (wibox.widget) | static module functions
  wibox.widget.draw_to_image_surface | Create a cairo image surface showing this widget. (wibox.widget) | static module functions

generated by LDoc 1.5.0