# Module: `wibox.hierarchy`

Management of widget hierarchies.

Each widget hierarchy object has a widget for which it saves e.g. size and transformation in its parent. Also, each widget has a number of children.

### Info:

- Copyright: 2015 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Constructors

wibox.hierarchy.new (context, widget, width, height, redraw_callback, layout_callback, callback_arg) | Create a new widget hierarchy that has no parent. |

## Static module functions

wibox.hierarchy.count_widget (widget) | Add a widget to the list of widgets for which hierarchies should count their occurrences. |

## Object methods

:wibox.hierarchy.update (context, widget, width, height, region) -> () | Update a widget hierarchy with some new state. |
:wibox.hierarchy.get_widget () -> wibox.widget | Get the widget that this hierarchy manages. |
:wibox.hierarchy.get_matrix_to_parent () -> () | Get a matrix that transforms to the parent's coordinate space from this hierarchy's coordinate system. |
:wibox.hierarchy.get_matrix_to_device () -> () | Get a matrix that transforms to the base of this hierarchy's coordinate system (aka the coordinate system of the device that this hierarchy is applied upon) from this hierarchy's coordinate system. |
:wibox.hierarchy.get_matrix_from_parent () -> () | Get a matrix that transforms from the parent's coordinate space into this hierarchy's coordinate system. |
:wibox.hierarchy.get_matrix_from_device () -> () | Get a matrix that transforms from the base of this hierarchy's coordinate system (aka the coordinate system of the device that this hierarchy is applied upon) into this hierarchy's coordinate system. |
:wibox.hierarchy.get_draw_extents () -> () | Get the extents that this hierarchy possibly draws to (in the current coordinate space). |
:wibox.hierarchy.get_size () -> () | Get the size that this hierarchy logically covers (in the current coordinate space). |
:wibox.hierarchy.get_children () -> () | Get a list of all children. |
:wibox.hierarchy.get_count (widget) -> () | Count how often this widget is visible inside this hierarchy. |
:wibox.hierarchy.draw (context, cr) | Draw a hierarchy to some cairo context. |

## Constructors

🔗 wibox.hierarchy.new (context, widget, width, height, redraw_callback, layout_callback, callback_arg)
  Create a new widget hierarchy that has no parent.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  context |  |  | The context in which we are laid out.
  widget |  |  | The widget that is at the base of the hierarchy.
  width |  |  | The available width for this hierarchy.
  height |  |  | The available height for this hierarchy.
  redraw_callback |  |  | Callback that is called with the corresponding widget hierarchy on widget::redraw_needed on some widget.
  layout_callback |  |  | Callback that is called with the corresponding widget hierarchy on widget::layout_changed on some widget.
  callback_arg |  |  | A second argument that is given to the above callbacks.

  ### Returns:

  A new widget hierarchy

## Static module functions

🔗 wibox.hierarchy.count_widget (widget)
  Add a widget to the list of widgets for which hierarchies should count their occurrences. Note that for correct operations, the widget must not yet be visible in any hierarchy.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  widget |  |  | The widget that should be counted.

## Object methods

🔗 :wibox.hierarchy.update (context, widget, width, height, region) -> ()
  Update a widget hierarchy with some new state.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  context |  |  | The context in which we are laid out.
  widget |  |  | The widget that is at the base of the hierarchy.
  width |  |  | The available width for this hierarchy.
  height |  |  | The available height for this hierarchy.
  region | Optional |  | A region to use for accumulating changed parts

  ### Returns:

  A cairo region describing the changed parts (either the `region` argument or a new, internally created region).
🔗 :wibox.hierarchy.get_widget () -> wibox.widget
  Get the widget that this hierarchy manages.

  ### Returns:

  wibox.widget The widget held by this node.
🔗 :wibox.hierarchy.get_matrix_to_parent () -> ()
  Get a matrix that transforms to the parent's coordinate space from this hierarchy's coordinate system.

  ### Returns:

  A matrix describing the transformation.
🔗 :wibox.hierarchy.get_matrix_to_device () -> ()
  Get a matrix that transforms to the base of this hierarchy's coordinate system (aka the coordinate system of the device that this hierarchy is applied upon) from this hierarchy's coordinate system.

  ### Returns:

  A matrix describing the transformation.
🔗 :wibox.hierarchy.get_matrix_from_parent () -> ()
  Get a matrix that transforms from the parent's coordinate space into this hierarchy's coordinate system.

  ### Returns:

  A matrix describing the transformation.
🔗 :wibox.hierarchy.get_matrix_from_device () -> ()
  Get a matrix that transforms from the base of this hierarchy's coordinate system (aka the coordinate system of the device that this hierarchy is applied upon) into this hierarchy's coordinate system.

  ### Returns:

  A matrix describing the transformation.
🔗 :wibox.hierarchy.get_draw_extents () -> ()
  Get the extents that this hierarchy possibly draws to (in the current coordinate space). This includes the size of this element plus the size of all children (after applying the corresponding transformation).

  ### Returns:

  x, y, width, height
🔗 :wibox.hierarchy.get_size () -> ()
  Get the size that this hierarchy logically covers (in the current coordinate space).

  ### Returns:

  width, height
🔗 :wibox.hierarchy.get_children () -> ()
  Get a list of all children.

  ### Returns:

  List of all children hierarchies.
🔗 :wibox.hierarchy.get_count (widget) -> ()
  Count how often this widget is visible inside this hierarchy. This function only works with widgets registered via count_widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  widget |  |  | The widget that should be counted

  ### Returns:

  The number of times that this widget is contained in this hierarchy.
🔗 :wibox.hierarchy.draw (context, cr)
  Draw a hierarchy to some cairo context. This function draws the widgets in this widget hierarchy to the given cairo context. The context's clip is used to skip parts that aren't visible.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  context |  |  | The context in which widgets are drawn.
  cr |  |  | The cairo context that is used for drawing.

generated by LDoc 1.5.0