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

Usage:

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

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

awesome

Contents

Theme related libraries

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Libraries

Sample files

Classes

Documentation

Module: gears.shape

Info:

Static module functions

Static module functions

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Returns:

See also:

Usage:

Module: `gears.shape`