doc: fix format for wibox.widget.base.make_widget
Closes https://github.com/awesomeWM/awesome/pull/548.
This commit is contained in:
parent
c4d21d5f12
commit
2bca03cb87
|
@ -236,11 +236,12 @@ widget. The arguments to this function is the available space and it should
|
||||||
return its desired size. Note that this function only provides a hint which is
|
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
|
not necessarily followed. The widget must also be able to draw itself at
|
||||||
different sizes than the one requested.
|
different sizes than the one requested.
|
||||||
<pre><code>function widget:fit(context, width, height)
|
|
||||||
|
function widget:fit(context, width, height)
|
||||||
-- Find the maximum square available
|
-- Find the maximum square available
|
||||||
local m = math.min(width, height)
|
local m = math.min(width, height)
|
||||||
return m, m
|
return m, m
|
||||||
end</code></pre>
|
end
|
||||||
|
|
||||||
The next callback is :draw. As the name suggests, this function is called to
|
The next callback is :draw. As the name suggests, this function is called to
|
||||||
draw the widget. The arguments to this widget are the context that the widget is
|
draw the widget. The arguments to this widget are the context that the widget is
|
||||||
|
@ -250,24 +251,24 @@ 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
|
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
|
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
|
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
|
by the layout that placed this widget. You should not call `cr:reset_clip()`, as
|
||||||
<code>cr:reset_clip()</code>, as redraws will not be handled correctly in this
|
redraws will not be handled correctly in this case.
|
||||||
case.
|
|
||||||
<pre><code>function widget:draw(wibox, cr, width, height)
|
function widget:draw(wibox, cr, width, height)
|
||||||
cr:move_to(0, 0)
|
cr:move_to(0, 0)
|
||||||
cr:line_to(width, height)
|
cr:line_to(width, height)
|
||||||
cr:move_to(0, height)
|
cr:move_to(0, height)
|
||||||
cr:line_to(width, 0)
|
cr:line_to(width, 0)
|
||||||
cr:stroke()
|
cr:stroke()
|
||||||
end</code></pre>
|
end
|
||||||
|
|
||||||
There are two signals configured for a widget. When the result that :fit would
|
There are two signals configured for a widget. When the result that :fit would
|
||||||
return changes, the <code>widget::layout_changed</code> signal has to be
|
return changes, the `widget::layout_changed` signal has to be emitted. If this
|
||||||
emitted. If this actually causes layout changes, the affected areas will be
|
actually causes layout changes, the affected areas will be redrawn. The other
|
||||||
redrawn. The other signal is <code>widget::redraw_needed</code>. This signal
|
signal is `widget::redraw_needed`. This signal signals that :draw has to be
|
||||||
signals that :draw has to be called to redraw the widget, but it is safe to
|
called to redraw the widget, but it is safe to assume that :fit does still
|
||||||
assume that :fit does still return the same values as before. If in doubt, you
|
return the same values as before. If in doubt, you can emit both signals to be
|
||||||
can emit both signals to be safe.
|
safe.
|
||||||
|
|
||||||
If your widget only needs to draw something to the screen, the above is all that
|
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
|
is needed. The following callbacks can be used when implementing layouts which
|
||||||
|
@ -278,24 +279,26 @@ 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
|
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
|
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,
|
its own extents. If the result of this callback changes,
|
||||||
<code>widget::layout_changed</code> has to be emitted. You can use @{fit_widget}
|
`widget::layout_changed` has to be emitted. You can use @{fit_widget} to call
|
||||||
to call the `:fit` callback of other widgets. Never call `:fit` directly! For
|
the `:fit` callback of other widgets. Never call `:fit` directly! For example,
|
||||||
example, if you want to place another widget <code>child</code> inside of your
|
if you want to place another widget `child` inside of your widget, you can do it
|
||||||
widget, you can do it like this:
|
like this:
|
||||||
<pre><code>-- For readability
|
|
||||||
local base = wibox.widget.base
|
-- For readability
|
||||||
function widget:layout(width, height)
|
local base = wibox.widget.base
|
||||||
|
function widget:layout(width, height)
|
||||||
local result = {}
|
local result = {}
|
||||||
table.insert(result, base.place_widget_at(child, width/2, 0, width/2, height)
|
table.insert(result, base.place_widget_at(child, width/2, 0, width/2, height)
|
||||||
return result
|
return result
|
||||||
end</code></pre>
|
end
|
||||||
|
|
||||||
Finally, if you want to influence how children are drawn, there are four
|
Finally, if you want to influence how children are drawn, there are four
|
||||||
callbacks available that all get similar arguments:
|
callbacks available that all get similar arguments:
|
||||||
<pre><code>function widget:before_draw_children(context, cr, width, height)
|
|
||||||
function widget:after_draw_children(context, cr, width, height)
|
function widget:before_draw_children(context, cr, width, height)
|
||||||
function widget:before_draw_child(context, index, child, cr, width, height)
|
function widget:after_draw_children(context, cr, width, height)
|
||||||
function widget:after_draw_child(context, index, child, cr, width, height)</code></pre>
|
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
|
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
|
note that a larger clip will be active during these callbacks that also contains
|
||||||
|
@ -303,27 +306,30 @@ 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
|
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
|
different area. As an example, these functions can be used to draw children
|
||||||
translucently:
|
translucently:
|
||||||
<pre><code>function widget:before_draw_children(wibox, cr, width, height)
|
|
||||||
|
function widget:before_draw_children(wibox, cr, width, height)
|
||||||
cr:push_group()
|
cr:push_group()
|
||||||
end
|
end
|
||||||
function widget:after_draw_children(wibox, cr, width, height)
|
function widget:after_draw_children(wibox, cr, width, height)
|
||||||
cr:pop_group_to_source()
|
cr:pop_group_to_source()
|
||||||
cr:paint_with_alpha(0.5)
|
cr:paint_with_alpha(0.5)
|
||||||
end</code></pre>
|
end
|
||||||
|
|
||||||
In pseudo-code, the call sequence for the drawing callbacks during a redraw
|
In pseudo-code, the call sequence for the drawing callbacks during a redraw
|
||||||
looks like this:
|
looks like this:
|
||||||
<pre><code>widget:draw(wibox, cr, width, height)
|
|
||||||
widget:before_draw_children(wibox, cr, width, height)
|
widget:draw(wibox, cr, width, height)
|
||||||
for child do
|
widget:before_draw_children(wibox, cr, width, height)
|
||||||
|
for child do
|
||||||
widget:before_draw_child(wibox, cr, child_index, child, width, height)
|
widget:before_draw_child(wibox, cr, child_index, child, width, height)
|
||||||
cr:save()
|
cr:save()
|
||||||
-- Draw child and all of its children recursively, taking into account the
|
-- Draw child and all of its children recursively, taking into account the
|
||||||
-- position and size given to base.place_widget_at() in :layout().
|
-- position and size given to base.place_widget_at() in :layout().
|
||||||
cr:restore()
|
cr:restore()
|
||||||
widget:after_draw_child(wibox, cr, child_index, child, width, height)
|
widget:after_draw_child(wibox, cr, child_index, child, width, height)
|
||||||
end
|
end
|
||||||
widget:after_draw_children(wibox, cr, width, height)</code></pre>
|
widget:after_draw_children(wibox, cr, width, height)
|
||||||
|
|
||||||
@param proxy If this is set, the returned widget will be a proxy for this
|
@param proxy If this is set, the returned widget will be a proxy for this
|
||||||
widget. It will be equivalent to this widget. This means it
|
widget. It will be equivalent to this widget. This means it
|
||||||
looks the same on the screen.
|
looks the same on the screen.
|
||||||
|
|
Loading…
Reference in New Issue