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
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
ory_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)