# Module: `gears.shape`

Module dedicated to gather common shape painters.

It adds the concept of "shape" to Awesome. A shape can be applied to a background, a margin, a mask or a drawable shape bounding.

The functions exposed by this module always take a cairo context as first parameter followed by a width and height. Individual functions may take additional parameters for their specific implementions.

The functions provided by this module only create a path in the content. to actually draw the content, use `cr:fill()`, `cr:mask()`, `cr:clip()` or `cr:stroke()`

In many case, it is necessary to apply the shape using a transformation such as a rotation. The preferred way to do this is to wrap the function in another function calling `cr:rotate()` (or any other transformation matrix).

To specialize a shape where the API doesn't allows extra arguments to be passed, it is possible to wrap the shape function like:

local new_shape = function(cr, width, height) gears.shape.rounded_rect(cr, width, height, 2) end

Many elements can be shaped. This include:

* clients (see gears.surface.apply_shape_bounding) * wiboxes (see wibox.shape) * All widgets (see wibox.container.background) * The progressbar (see wibox.widget.progressbar.bar_shape) * The graph (see wibox.widget.graph.step_shape) * The checkboxes (see wibox.widget.checkbox.check_shape) * Images (see wibox.widget.imagebox.clip_shape) * The taglist tags (see awful.widget.taglist) * The tasklist clients (see awful.widget.tasklist) * The tooltips (see awful.tooltip)

### Info:

- Copyright: 2011-2016 Emmanuel Lepage Vallee
- Originally authored by: Emmanuel Lepage Vallee
  (Full contributors list available on our github project)

## Static module functions

gears.shape.partial_squircle (cr, width, height, tl, tr, br, bl, rate, delta) | Add a squircle shape with only some of the corner are "circled" to the current path. |
gears.shape.squircle (cr, width, height, rate, delta) | Add a squircle shape to the current path. |
gears.shape.star (cr, width, height, n) | Add a star shape to the current path. |
gears.shape.rounded_rect (cr, width, height, radius) | Add a rounded rectangle to the current path. |
gears.shape.rounded_bar (cr, width, height) | Add a rectangle delimited by 2 180 degree arcs to the path. |
gears.shape.partially_rounded_rect (cr, width, height, tl, tr, br, bl, rad) | A rounded rect with only some of the corners rounded. |
gears.shape.infobubble (cr, width, height, corner_radius, arrow_size, arrow_position) | A rounded rectangle with a triangle at the top. |
gears.shape.rectangular_tag (cr, width, height, arrow_length) | A rectangle terminated by an arrow. |
gears.shape.arrow (cr, width, height, head_width, shaft_width, shaft_length) | A simple arrow shape. |
gears.shape.hexagon (cr, width, height) | A squeezed hexagon filling the rectangle. |
gears.shape.powerline (cr, width, height, arrow_depth) | Double arrow popularized by the vim-powerline module. |
gears.shape.isosceles_triangle (cr, width, height) | An isosceles triangle. |
gears.shape.cross (cr, width, height, thickness) | A cross (**+**) symbol. |
gears.shape.octogon (cr, width, height, corner_radius) | A similar shape to the rounded_rect, but with sharp corners. |
gears.shape.circle (cr, width, height, radius) | A circle shape. |
gears.shape.rectangle (cr, width, height) | A simple rectangle. |
gears.shape.parallelogram (cr, width, height, base_width) | A diagonal parallelogram with the bottom left corner at x=0 and top right at x=width. |
gears.shape.losange (cr, width, height) | A losange. |
gears.shape.pie (cr, width, height, start_angle, end_angle, radius) | A pie. |
gears.shape.arc (cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) | A rounded arc. |
gears.shape.solid_rectangle_shadow (cr, width, height, x_offset, y_offset) | Overlap 2 rectangles to emulate a shadow effect. |
gears.shape.radial_progress (cr, w, h, percent, hide_left) | A partial rounded bar. |
gears.shape.transform (shape) -> () | Adjust the shape using a transformation object |

## Static module functions

🔗 gears.shape.partial_squircle (cr, width, height, tl, tr, br, bl, rate, delta)
  Add a squircle shape with only some of the corner are "circled" to the current path. The squircle is not exactly as the definition. It will expand to the shape's width and height, kinda like an ellipse

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height
  tl |  | boolean | If the top left corner is rounded
  tr |  | boolean | If the top right corner is rounded
  br |  | boolean | If the bottom right corner is rounded
  bl |  | boolean | If the bottom left corner is rounded
  rate |  | number | The "squareness" of the squircle, should be greater than 1
  delta |  | number | The "smoothness" of the shape, delta must be greate than 0.01 and will be reset to 0.01 if not

  ### Usage:

      shape.partial_squircle(cr, 70, 70, false, true)
      shape.partial_squircle(cr, 70, 70, true, false, true)
      shape.partial_squircle(cr, 70, 70, true, false, true, true)

🔗 gears.shape.squircle (cr, width, height, rate, delta)
  Add a squircle shape to the current path. This will behave the same as partial_squircle

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height
  rate |  | number | The "squareness" of the squircle, should be greater than 1
  delta |  | number | The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not

  ### Usage:

      shape.squircle(cr, 70, 70, 2)
      shape.squircle(cr, 70, 70, 8)
      shape.squircle(cr, 70, 70, 1.5)

🔗 gears.shape.star (cr, width, height, n)
  Add a star shape to the current path. The star size will be the minimum of the given width and weight

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The width constraint
  height |  | number | The height constraint
  n |  | number | Number of grams (default n = 5 -> pentagram)

  ### Usage:

      shape.star(cr, 70, 70, 4)
      shape.star(cr, 70, 70, 9)
      shape.transform(shape.star) : translate(70/2, 70/2)
      : rotate(math.pi) : scale(0.5, 0.75)
      : translate(-70/2, -70/2) (cr, 70, 70)

🔗 gears.shape.rounded_rect (cr, width, height, radius)
  Add a rounded rectangle to the current path. Note: If the radius is bigger than either half side, it will be reduced.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo content
  width |  | number | The rectangle width
  height |  | number | The rectangle height
  radius |  | number | The corner radius

  ### Usage:

      shape.rounded_rect(cr, 70, 70, 10)
      shape.rounded_rect(cr,20,70, 5)
      shape.transform(shape.rounded_rect) : translate(0,25) (cr,70,20, 5)

🔗 gears.shape.rounded_bar (cr, width, height)
  Add a rectangle delimited by 2 180 degree arcs to the path.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo content
  width |  |  | The rectangle width
  height |  |  | The rectangle height.

  ### Usage:

      shape.rounded_bar(cr, 70, 70)
      shape.rounded_bar(cr, 20, 70)
      shape.rounded_bar(cr, 70, 20)

🔗 gears.shape.partially_rounded_rect (cr, width, height, tl, tr, br, bl, rad)
  A rounded rect with only some of the corners rounded.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height
  tl |  | boolean | If the top left corner is rounded
  tr |  | boolean | If the top right corner is rounded
  br |  | boolean | If the bottom right corner is rounded
  bl |  | boolean | If the bottom left corner is rounded
  rad |  | number | The corner radius

  ### Usage:

      shape.partially_rounded_rect(cr, 70, 70)
      shape.partially_rounded_rect(cr, 70, 70, true)
      shape.partially_rounded_rect(cr, 70, 70, true, true, false, true, 30)

🔗 gears.shape.infobubble (cr, width, height, corner_radius, arrow_size, arrow_position)
  A rounded rectangle with a triangle at the top.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  corner_radius | Optional | number | The corner radius | `5`
  arrow_size | Optional | number | The width and height of the arrow | `10`
  arrow_position | Optional | number | The position of the arrow | `width/2 - arrow_size/2`

  ### Usage:

      shape.infobubble(cr, 70, 70)
      shape.transform(shape.infobubble) : translate(0, 20)
      : rotate_at(35,35,math.pi) (cr,70,20,10, 5, 35 - 5)
      shape.transform(shape.infobubble)
      : rotate_at(35,35,3*math.pi/2) (cr,70,70, nil, nil, 40)

🔗 gears.shape.rectangular_tag (cr, width, height, arrow_length)
  A rectangle terminated by an arrow.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  arrow_length | Optional | number | The length of the arrow part | `height/2`

  ### Usage:

      shape.rectangular_tag(cr, 70, 70)
      shape.transform(shape.rectangular_tag) : translate(0, 30) (cr, 70, 10,  10)
      shape.transform(shape.rectangular_tag) : translate(0, 30) (cr, 70, 10, -10)

🔗 gears.shape.arrow (cr, width, height, head_width, shaft_width, shaft_length)
  A simple arrow shape.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  head_width | Optional | number | The width of the head (/\) of the arrow | `head_width`
  shaft_width | Optional | number | The width of the shaft of the arrow | `width /2`
  shaft_length | Optional | number | The head_length of the shaft (the rest is the head) | `height/2`

  ### Usage:

      shape.arrow(cr, 70, 70)
      shape.arrow(cr,70,70, 30, 10, 60)
      shape.transform(shape.arrow) : rotate_at(35,35,math.pi/2)(cr,70,70)

🔗 gears.shape.hexagon (cr, width, height)
  A squeezed hexagon filling the rectangle.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height

  ### Usage:

      shape.hexagon(cr, 70, 70)
      shape.transform(shape.hexagon) : translate(0,15)(cr,70,20)
      shape.transform(shape.hexagon) : rotate_at(35,35,math.pi/2)(cr,70,40)

🔗 gears.shape.powerline (cr, width, height, arrow_depth)
  Double arrow popularized by the vim-powerline module.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  arrow_depth | Optional | number | The width of the arrow part of the shape | `height/2`

  ### Usage:

      shape.powerline(cr, 70, 70)
      shape.transform(shape.powerline) : translate(0, 25) (cr,70,20)
      shape.transform(shape.powerline) : translate(0, 25) (cr,70,20, -20)

🔗 gears.shape.isosceles_triangle (cr, width, height)
  An isosceles triangle.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height

  ### Usage:

      shape.isosceles_triangle(cr, 70, 70)
      shape.isosceles_triangle(cr,20,70)
      shape.transform(shape.isosceles_triangle) : rotate_at(35, 35, math.pi/2)(cr,70,70)

🔗 gears.shape.cross (cr, width, height, thickness)
  A cross (**+**) symbol.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  thickness | Optional | number | The cross section thickness | `width/3`

  ### Usage:

      shape.cross(cr, 70, 70)
      shape.cross(cr,20,70)
      shape.transform(shape.cross) : scale(0.5, 1)(cr,70,70)

🔗 gears.shape.octogon (cr, width, height, corner_radius)
  A similar shape to the rounded_rect, but with sharp corners.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height
  corner_radius |  | number |

  ### Usage:

      shape.octogon(cr, 70, 70)
      shape.octogon(cr,70,70,70/2.5)
      shape.transform(shape.octogon) : translate(0, 25) (cr,70,20)

🔗 gears.shape.circle (cr, width, height, radius)
  A circle shape.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  radius | Optional | number | The radius | `math.min(width height) / 2)`

  ### Usage:

      shape.circle(cr, 70, 70)
      shape.circle(cr,20,70)
      shape.transform(shape.circle) : scale(0.5, 1)(cr,70,70)

🔗 gears.shape.rectangle (cr, width, height)
  A simple rectangle.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height

  ### Usage:

      shape.rectangle(cr, 70, 70)
      shape.rectangle(cr,20,70)
      shape.transform(shape.rectangle) : scale(0.5, 1)(cr,70,70)

🔗 gears.shape.parallelogram (cr, width, height, base_width)
  A diagonal parallelogram with the bottom left corner at x=0 and top right at x=width.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  base_width | Optional | number | The parallelogram base width | `width/3`

  ### Usage:

      shape.parallelogram(cr, 70, 70)
      shape.parallelogram(cr,70,20)
      shape.transform(shape.parallelogram) : scale(0.5, 1)(cr,70,70)

🔗 gears.shape.losange (cr, width, height)
  A losange.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  width |  | number | The shape width
  height |  | number | The shape height

  ### Usage:

      shape.losange(cr, 70, 70)
      shape.losange(cr,20,70)
      shape.transform(shape.losange) : scale(0.5, 1)(cr,70,70)

🔗 gears.shape.pie (cr, width, height, start_angle, end_angle, radius)
  A pie.

  The pie center is the center of the area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  start_angle | Optional | number | The start angle (in radian) | `0`
  end_angle | Optional | number | The end angle (in radian) | `math.pi/2`
  radius | Optional | number | The shape height | `math.min(width height)/2`

  ### Usage:

      shape.pie(cr, 70, 70)
      shape.pie(cr,70,70, 1.0471975511966,   4.1887902047864)
      shape.pie(cr,70,70, 0, 2*math.pi, 10)

🔗 gears.shape.arc (cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded)
  A rounded arc.

  The pie center is the center of the area.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  thickness | Optional | number | The arc thickness | `math.min(width height)/2`
  start_angle | Optional | number | The start angle (in radian) | `0`
  end_angle | Optional | number | The end angle (in radian) | `math.pi/2`
  start_rounded | Optional | boolean | If the arc start rounded | `false`
  end_rounded | Optional | boolean | If the arc end rounded | `false`

  ### Usage:

      shape.arc(cr,70,70, 10)
      shape.arc(cr,70,70, 10, nil, nil, true, true)
      shape.arc(cr,70,70, nil, 0, 2*math.pi)

🔗 gears.shape.solid_rectangle_shadow (cr, width, height, x_offset, y_offset)
  Overlap 2 rectangles to emulate a shadow effect.

  This is intended to be used with either the wibox.container.margin or the client.shape to implement MS-DOS and TWM MenuShadowColor "classic" shadows.

  Warning: If `x_offset` or `y_offset` are greater than the width or height respectively, strange thing will happen.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  cr |  |  | A cairo context | Not applicable
  width |  | number | The shape width | Not applicable
  height |  | number | The shape height | Not applicable
  x_offset | Optional | number | The shadow area horizontal offset. | `5`
  y_offset | Optional | number | The shadow area vertical offset. | `5`

  ### Usage:

      shape.solid_rectangle_shadow(cr, 70, 70, 10, 5)
      shape.solid_rectangle_shadow(cr, 70, 70, 5, -10)
      shape.solid_rectangle_shadow(cr, 70, 70, 30, -30)

🔗 gears.shape.radial_progress (cr, w, h, percent, hide_left)
  A partial rounded bar. How much of the rounded bar is visible depends on the given percentage value.

  Note that this shape is not closed and thus filling it doesn't make much sense.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  cr |  |  | A cairo context
  w |  | number | The shape width
  h |  | number | The shape height
  percent |  | number | The progressbar percent
  hide_left |  | boolean | Do not draw the left side of the shape

  ### Usage:

      shape.radial_progress(cr, 70, 20, .3)
      shape.radial_progress(cr, 70, 20, .6)
      shape.radial_progress(cr, 70, 20, .9)

🔗 gears.shape.transform (shape) -> ()
  Adjust the shape using a transformation object Apply various transformations to the shape

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  shape |  |  | A shape function

  ### Returns:

  A transformation handle, also act as a shape function

  ### See also:

  gears.matrix.translate | Translate this matrix (gears.matrix) | methods
  gears.matrix.scale | Scale this matrix (gears.matrix) | methods
  gears.matrix.rotate | Rotate this matrix (gears.matrix) | methods
  gears.matrix.rotate_at | Rotate a shape from a custom point (gears.matrix) | methods
  gears.matrix.multiply | Multiply this matrix with another matrix. (gears.matrix) | methods
  gears.matrix.invert | Invert this matrix (gears.matrix) | methods

  ### Usage:

      gears.shape.transform(gears.shape.rounded_bar)
         : rotate(math.pi/2)
            : translate(10, 10)

generated by LDoc 1.5.0