Widget Layouts

Complex widget layouts can be interesting and really add to the power and flexibility of Awesome. This functionality is implemented through layout widgets, which are mainly designed to contain and modify the positioning of one or more other widgets. These other widgets can be those generated by awesome itself, awful, or external libraries like Vicious. These instructions use code after these commits: fbba41d,601dc23, and ceaeaed.

Basic Usage
To use a layout widget, you must call its constructor, add one or more widgets to it, and set any special properties that you want to modify. Generally, the top most layout widget will be placed in a wibox to be displayed.

To create a layout widget, call its constructor. local mymargin = wibox.layout.margin

Then add a widget. mylauncher = awful.widget.launcher({ image = beautiful.awesome_icon,                                    menu = mymainmenu }) mymargin:set_widget(mylauncher)

As you can see, the  function adds the widget to this layout. This is typical for layouts that only accept a single widget. For layouts that accept an arbitrary number of widgets, the  function is used, and for widgets that accept a finite number of widgets, the   function is used, where item generally describes where the widget will go.

Finally, set any properties you wish to change. mymargin:set_margins(1)

The order of these functions is not critical: as long as the layout widget is created before any of its functions are used, the results will be the same.

Available Layout Types
All layout widgets and their callable functions are described fully in the Awesome Lua API documentation in the wibox.layout.* sections.

Align
Used to place widgets in on the Left, Right, Top, Bottom or Middle of a given space.

Direction
The align layout should not be called directly, but should be called using either of the directional functions: myalign = wibox.layout.align.horizontal or myalign = wibox.layout.align.vertical

Horizontal will layout widgets in a Left, Middle, Right format: myalign:set_left(widget_left) myalign:set_middle(widget_middle) myalign:set_right(widget_right) while vertical will place them Top, Middle, Bottom: myalign:set_top(widget_top) myalign:set_middle(widget_middle) myalign:set_bottom(widget_bottom) Note that not all of these widgets have to be assigned, the align layout deals smartly with placing widgets if any are missing.

Expand Mode
By default, the middle widget will expand or contract (even to the point of disappearing) to take up any room left by the outside widgets. This isn't always the desired case. The  function is used to change this behavior.

Inside
Use  to cause the middle widget to expand to fill the space left over by the outside widgets. Note that if there is no space left over, the middle widget will not be shown. In this mode the top or left widget gets first priority on the available space, then the right or bottom widget, and finally the middle widget. This is the default behavior.

Outside
Use  to center the middle widget in the available space and cause the outside widgets (left, right, top or bottom) to expand to fill any space left over on the applicable side of the widget. In this mode the middle widget gets first priority on space, and the other two widgets expand into whatever is left over on their side. Widgets should be written to handle not being given as much space as they ask for, so this shouldn't break them. If the middle widget takes up all the available space, the outside widgets won't be shown.

None
Using  will leave any left over space empty. The middle widget will be centered, and is given first priority on available space. The other two widgets may use whatever is left over on their side, but will not expand to fill that space. If the middle widget takes up all the available space, the outside widgets won't be shown.

Constraint
This widget will limit the size of its daughter widget. Set the daughter widget with. Set the constraint height and/or width with  and   respectively, where integer   is the size in pixels. If you use  instead of an integer it will remove the constraint in that direction. Using  will set the strategy to "max" and clear both constraint directions.

Constraint Strategies
The constraint strategy defines how to apply the constraint. Note that these describe the constraint not the widget it is constraining.If you want to apply a different strategy to each direction, carefully use nested constraint widgets.

Exact
This will force the height and/or width to match the constraint exactly. myconstraint:set_strategy("exact")

Min
This will force the height and/or width to be larger than the constraint values. myconstraint:set_strategy("min")

Max
This will force the height and/or width to be smaller than the constraint values. myconstraint:set_strategy("max")

Margin
This adds padding all the way around the widget it contains. Use  to set the sub widget. If n is an integer,  will set a margin of n pixels all the way around the widget and ,  ,  , and   will set a margin of n pixels on just the specified side.

Best Practices
Widget layouts can grow quite complex very quickly, as you add more things to display and arrange things in interesting ways. The default layout includes 6 widgets to begin with and after adding more it can easily become difficult to figure out where you are in your layout. To help with this, organizing your widgets consistently in your code and adding plenty of comments can help immensely. Here are some suggestions:
 * Use comments to denote exactly what a widget is for and where it goes.
 * Name layout widgets based on their parent and location.
 * Use indentation to denote what level you are working at.
 * Build the layout like it is HTML:
 * Declare your outer most layout.
 * Set its options.
 * Declare a subwidget.
 * Set its options.
 * Declare and add any additional sub widgets.
 * Add widget to outer layout.
 * Add outer layout to wibox.
 * For complex layouts, draw a mock-up of what you want it to look like before you start.
 * Read the documentation on available layouts before you start so you understand what is possible.

Labeling
To label a widget that shows data, such as a progress bar, you can use an align widget with two sub widgets: the data widget and a textbox widget. internal_battery = awful.widget.align.vertical

internal_battery_pb = awful.widget.progressbar internal_battery_pb:set_vertical(true) internal_battery_pb:set_width(8) internal_battery_pb:set_height(20) internal_battery_pb:set_background_color(beautiful.bg_normal) internal_battery_pb:set_border_color(beautiful.fg_normal) internal_battery_pb:set_color({ type = "linear", from = { 0, 0 }, to = { 0, 20 },                                       stops = { { 0,   beautiful.fg_focus},                                        { 0.2, beautiful.fg_focus},                                        { 1,   beautiful.bg_focus}                                    } }) vicious.register(internal_battery_pb, vicious.widgets.bat, "$2", 20, "CMB1") internal_battery:set_middle(internal_battery_pb)

internal_battery_label = wibox.widget.textbox internal_battery_label:set_text("I") internal_battery_label:set_align("center") internal_battery:set_bottom(internal_battery_label) Note that the progress bar widget is set as the middle widget. By default the middle widget expands to take as much space, and because there is no top widget, it will use any space that the label does not. If you want the label on the top, you would just use  instead of.