awesome/docs/04-new-widgets.md

# Creating new widget

All widgets have to be generated by the `wibox.widget.base.make_widget` function
so that the needed signals are added and mouse input handling is set up.

The returned widget will have a `:buttons` member function that can be used to
register a set of mouse button events with the widget.

To implement your own widget, you can implement some member functions on a
freshly-created widget. Note that all of these functions should be deterministic
in the sense that they will show the same behavior if they are repeatedly called
with the same arguments (same width and height). If your widget is updated and
needs to change, suitable signals have to be emitted. This will be explained
later.

The first callback is `:fit`. This function is called to select the size of your
widget. The arguments to this function are the available space and it should
return its desired size. Note that this function only provides a hint which is
not necessarily followed. The widget must also be able to draw itself at
different sizes than the one requested.

    function widget:fit(context, width, height)
        -- Find the maximum square available
        local m = math.min(width, height)
        return m, m
    end

The next callback is `:draw`. As the name suggests, this function is called to
draw the widget. The arguments to this function are the context that the widget is
drawn in, the Cairo context on which it should be drawn and the widget's size.
The Cairo context is set up in such a way that the widget has its top-left corner
at (0, 0) and its bottom-right corner at (width, height). In other words, no
special transformation needs to be done. Note that during this callback a
suitable clip will already be applied to the Cairo context so that this callback
will not be able to draw outside of the area that was registered for the widget
by the layout that placed this widget. You should not call `cr:reset_clip()`, as
redraws will not be handled correctly in this case.

    function widget:draw(context, cr, width, height)
        cr:move_to(0, 0)
        cr:line_to(width, height)
        cr:move_to(0, height)
        cr:line_to(width, 0)
        cr:stroke()
    end

There are two signals configured for a widget. When the result that `:fit` would
return changes, the `widget::layout_changed` signal has to be emitted. If this
actually causes layout changes, the affected areas will be redrawn. The other
signal is `widget::redraw_needed`. This signal signals that `:draw` has to be
called to redraw the widget, but it is safe to assume that `:fit` does still
return the same values as before. If in doubt, you can emit both signals to be
safe.

If your widget only needs to draw something to the screen, the above is all that
is needed. The following callbacks can be used when implementing layouts which
place other widgets on the screen.

The `:layout` callback is used to figure out which other widgets should be drawn
relative to this widget. Note that it is allowed to place widgets outside of the
extents of your own widget, for example at a negative position or at twice the
size of this widget. Use this mechanism if your widget needs to draw outside of
its own extents. If the result of this callback changes,
`widget::layout_changed` has to be emitted. You can use `:fit_widget` to call
the `:fit` callback of other widgets. Never call `:fit` directly!  For example,
if you want to place another widget `child` inside of your widget, you can do it
like this:

    -- For readability
    local base = wibox.widget.base
    function widget:layout(width, height)
        local result = {}
        table.insert(result, base.place_widget_at(child, width/2, 0, width/2, height)
        return result
    end

Finally, if you want to influence how children are drawn, there are four
callbacks available that all get similar arguments:

    function widget:before_draw_children(context, cr, width, height)
    function widget:after_draw_children(context, cr, width, height)
    function widget:before_draw_child(context, index, child, cr, width, height)
    function widget:after_draw_child(context, index, child, cr, width, height)

All of these are called with the same arguments as the `:draw()` method. Please
note that a larger clip will be active during these callbacks that also contains
the area of all children. These callbacks can be used to influence the way in
which children are drawn, but they should not cause the drawing to cover a
different area. As an example, these functions can be used to draw children
translucently:

    function widget:before_draw_children(context, cr, width, height)
        cr:push_group()
    end
    function widget:after_draw_children(context, cr, width, height)
        cr:pop_group_to_source()
        cr:paint_with_alpha(0.5)
    end

In pseudo-code, the call sequence for the drawing callbacks during a redraw
looks like this:

    widget:draw(context, cr, width, height)
    widget:before_draw_children(context, cr, width, height)
    for child do
        widget:before_draw_child(context, cr, child_index, child, width, height)
        cr:save()
        -- Draw child and all of its children recursively, taking into account the
        -- position and size given to base.place_widget_at() in :layout().
        cr:restore()
        widget:after_draw_child(context, cr, child_index, child, width, height)
    end
    widget:after_draw_children(context, cr, width, height)

The `:set_children()` method gets called recursively when setting a widget with
the declarative layout system, therefore the method should be well-defined.
It should probably hook into the `:add` or `:add_widget` methods or be
overridden to do nothing.