Module: awful.tree

Structure to manipulate clients and wiboxes stacking order and geometry.

This module allows to group clients alongside wiboxes. It is a building block of the layout system. Generally, it isn’t required to directly use this module to acheive anything. It is used under the hood for storing layout geometry when a tag is not selected and to manage the z-index and layers such as client.ontop.

The awful.tree object is just a sub-class of awful.tree.node. The only difference is that awful.tree has more signals than the awful.tree.nodes.

Multiple signals are forwarded from the clients, wiboxes and tags to make it easier to create stateful layouts. Note that none of them are necessary to use this module.

Here is a concrete example of the awful.tree which backs the layering subsystem:

Lifecycle notes

  • When a client is killed, "request::cleanup" is sent to all tree (root node). If the node isn’t unlinked after the signal, it will be automatically removed.
  • The wibox are held using weak references. They can be garbage collected even if present in a tree. When this happen, "request::cleanup" is sent, but it doesn’t have the wibox since it has already been deleted. The nodes will be removed from the tree automatically.
  • When a tree is garbage collected, so are all nodes.
  • client:swap() does not affect trees. The user must connect those signals and handle them if needed.
  • Instances exposes by the screen, tags or the root object are read only. To modify them you must implement a layout object or arrange function.

Info:

  • Originally authored by: Emmanuel Lepage-Vallee <elv1313@gmail.com>
    (Full contributors list available on our github project)

Constructors

awful.tree {[args]} Create a new tree.
awful.tree.list {[args]} Create a new list.

Static module functions

awful.tree.iterate_next (node, inclusive) -> function Iterate from self to the furtest leaf of the tree.
awful.tree.iterate_previous (node, inclusive) -> function Iterate from self to the root of the tree.
awful.tree.iterate_next_sibling (node, inclusive) -> function Iterate from self to the last sibling (node with same parent).
awful.tree.iterate_previous_sibling (node, inclusive) -> function Iterate from self to the first sibling (node with same parent).
awful.tree.iterate_children (node) -> function Recursively iterate from self last child node.
awful.tree.iterate_parent (node, inclusive) -> function Iterate the parent nodes until the root node.

Object properties

geometry table The total geometry for this node and all children.
effective_geometry table The geometry with gaps and size hints applied. Read only
gaps integer or table or nil Padding (usually called “useless gaps”) to put around a client or wibox.
root awful.tree.node Get the node which has no further parent. Read only
client client or nil Return the client object, if any.
clients table Return a table with all clients held by this node and any children.
wibox wibox or nil Return the wibox object, if any. Read only
wiboxes table Return a table with all wiboxes held by this node and any children. Read only
parent awful.tree.node or awful.tree or nil The parent node. Read only
previous_sibling awful.tree.node or nil The previous node which has the same parent. Read only
next_sibling awful.tree.node or nil The next node which has the same parent. Read only
previous awful.tree.node or nil The previous node as if the tree was a flat list. Read only
next awful.tree.node or nil The next node as if the tree was a flat list. Read only
first_child awful.tree.node or nil The first direct child. Read only
last_child awful.tree.node or nil The last direct child. Read only
type string What is the node content. Read only
honor_size_hints table or boolean When applying the geometry, honor the client size hints.
protected boolean When true, :cleanup() won’t remove the node and :detach() will fail.
read_only boolean When true, none of the awful.tree mutator methods will work. Read only
valid boolean Is false when the node has been deleted. Read only
label string or nil A name for this node.
placement nil or placement An awful.placement function to use when the client has size hints.

Object methods

:swap (other) -> boolean Swap 2 nodes.
:join () -> boolean Merge all children nodes and remove self.
:push (other) -> boolean Make the node passed as argument the first child node of self.
:append (other) -> boolean Make the node passed as argument the last child node of self.
:detach () -> boolean Remove a node from the tree.
:fork () -> awful.tree Copy an entire (sub-)tree into a new awful.tree instance.
:cleanup () -> nil or awful.tree Remove all unprotected nodes from the tree.
:move_before (other) -> boolean Insert self before other.
:move_after (other) -> boolean Move self after other.
:wrap {[args]} -> awful.tree.node Wrap self with a new node.
:create_after {[args]} -> awful.tree.node Create a new node and place it after self.
:create_before {[args]} -> awful.tree.node Create a new node and place it before self.
:push_new {[args]} -> awful.tree.node Push a new node at the beginning of the branch.
:append_new {[args]} -> awful.tree.node Append a new node at the leaf end of this branch.
:find_client_node (client) -> nil or awful.tree.node Locate the node which contain a client.
:find_wibox_node (wibox) -> nil or awful.tree.node Locate the node which contain a wibox.

Signals

client::replaced Emitted when one of the children node sets the client property.
reorderred Emitted when the node order changed.
request::cleanup_node Emitted when a node has been removed from the tree.
request::cleanup Emitted when a node has been removed from the tree.
client::added Emitted on the awful.tree root node when a client is added.
wibox::added Emitted on the awful.tree root node when a wibox is added.
request::client_swap Forwarded from the client request::swap.
request::raise_node Forwarded from the client or wibox request::raise.
request::lower_node Forwarded from the client or wibox request::lower.
request::resize_node Forwarded from the client request::resize.
request::honor_size_hints Forwarded from the client property::size_hints_honor.
request::add_client Sent when a client is added to one of the tags.
request::remove_client Sent when the client is no longer tagged in any of the tags.
request::hide Hide object when none of the tags are the primary selection.
request::show Show objects when one of the tag is the primary selection.


Constructors

🔗 awful.tree {[args]}
Create a new tree.

Parameters:

Name Type(s) Description Default value
args Optional table {}

Returns:

    awful.tree The new tree.
🔗 awful.tree.list {[args]}
Create a new list.

A list is a specialized tree where it isn’t possible to insert sub-trees. This is indented to be used alongside :mirror_to() to “flatten” trees into tables.

Parameters:

Name Type(s) Description Default value
args Optional table {}

Returns:

    awful.tree The new list.

Static module functions

🔗 awful.tree.iterate_next (node, inclusive) -> function

Iterate from self to the furtest leaf of the tree.

for node in awful.tree.iterate_next(tree, true) do
    -- Do something.
end

for node in awful.tree.iterate_next(tree, false) do
    -- Do something.
end

for node in awful.tree.iterate_next(branch2, true) do
    -- Do something.
end

for node in awful.tree.iterate_next(branch2, false) do
    -- Do something.
end

Parameters:

Name Type(s) Description Default value
node awful.tree or awful.tree.node The initial node (or tree). Not applicable
inclusive Optional boolean Also include node in th iterator. false

Returns:

    function An iterator.

See also:

awful.tree.iterate_previous Iterate from self to the root of the tree. static module functions
awful.tree.iterate_next_sibling Iterate from self to the last sibling (node with same parent). static module functions
next
🔗 awful.tree.iterate_previous (node, inclusive) -> function

Iterate from self to the root of the tree.

for node in awful.tree.iterate_previous(tree.last_child, true) do
    -- Do something.
end

for node in awful.tree.iterate_previous(tree.last_child, false) do
    -- Do something.
end

for node in awful.tree.iterate_previous(branch2, true) do
    -- Do something.
end

for node in awful.tree.iterate_previous(branch2, false) do
    -- Do something.
end

Parameters:

Name Type(s) Description Default value
node awful.tree or awful.tree.node The initial node (or tree). Not applicable
inclusive Optional boolean Also include node in th iterator. false

Returns:

    function An iterator.

See also:

awful.tree.iterate_next Iterate from self to the furtest leaf of the tree. static module functions
awful.tree.iterate_previous_sibling Iterate from self to the first sibling (node with same parent). static module functions
previous
🔗 awful.tree.iterate_next_sibling (node, inclusive) -> function

Iterate from self to the last sibling (node with same parent).

for node in awful.tree.iterate_next_sibling(tree.first_child, true) do
    -- Do something.
end

for node in awful.tree.iterate_next_sibling(tree.first_child, false) do
    -- Do something.
end

for node in awful.tree.iterate_next_sibling(branch1.first_child, true) do
    -- Do something.
end

for node in awful.tree.iterate_next_sibling(branch1.first_child, false) do
    -- Do something.
end

Parameters:

Name Type(s) Description Default value
node awful.tree or awful.tree.node The initial node (or tree). Not applicable
inclusive Optional boolean Also include node in th iterator. false

Returns:

    function An iterator.

See also:

awful.tree.iterate_previous_sibling Iterate from self to the first sibling (node with same parent). static module functions
awful.tree.iterate_next Iterate from self to the furtest leaf of the tree. static module functions
next_sibling
🔗 awful.tree.iterate_previous_sibling (node, inclusive) -> function

Iterate from self to the first sibling (node with same parent).

for node in awful.tree.iterate_previous_sibling(tree.last_child, true) do
    -- Do something.
end

for node in awful.tree.iterate_previous_sibling(tree.last_child, false) do
    -- Do something.
end

for node in awful.tree.iterate_previous_sibling(branch1.last_child, true) do
    -- Do something.
end

for node in awful.tree.iterate_previous_sibling(branch1.last_child, false) do
    -- Do something.
end

Parameters:

Name Type(s) Description Default value
node awful.tree or awful.tree.node The initial node (or tree). Not applicable
inclusive Optional boolean Also include node in th iterator. false

Returns:

    function An iterator.

See also:

awful.tree.iterate_next_sibling Iterate from self to the last sibling (node with same parent). static module functions
awful.tree.iterate_next Iterate from self to the furtest leaf of the tree. static module functions
previous_sibling
🔗 awful.tree.iterate_children (node) -> function

Recursively iterate from self last child node.

for node in awful.tree.iterate_children(tree) do
    -- Do something.
end

for node in awful.tree.iterate_children(branch1) do
    -- Do something.
end

Parameters:

Name Type(s) Description
node awful.tree or awful.tree.node The initial node (or tree).

Returns:

    function An iterator.

See also:

iterate_parent Iterate the parent nodes until the root node. static module functions
🔗 awful.tree.iterate_parent (node, inclusive) -> function

Iterate the parent nodes until the root node.

for node in awful.tree.iterate_parent(client4_node, true) do
    -- Do something.
end

for node in awful.tree.iterate_parent(client4_node, false) do
    -- Do something.
end

Parameters:

Name Type(s) Description Default value
node awful.tree or awful.tree.node The initial node (or tree). Not applicable
inclusive Optional boolean Also include node in th iterator. false

Returns:

    function An iterator.

See also:

iterate_children Recursively iterate from self last child node. static module functions

Object properties

🔗 geometry table · 1 signal
The total geometry for this node and all children.

Note that this property is read only for tree node and writable for client and wibox nodes.

Note that doing my_node.geometry.x = 1337 is not supported. The geometry can only be set as a full table. However, the table does not need to contain all aspects, so my_node.geometry = { x = 1337} will work.

Constraints:

Table keys:
x (integer) : The horizontal position.
y (integer) : The vertical position.
width (integer) : The width.
height (integer) : The height.
Unit : pixel
Valid values : The geometry.

See also:

client.geometry Return or set client geometry. (client) object methods
wibox.geometry Get or set wibox geometry. (wibox) object methods
gaps
effective_geometry

Click to display more

Emit signals:

  • property::geometry When the geometry value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value geometry The new value affected to the property.
    • old_value geometry The property’s old value.
🔗 effective_geometry table · read only
The geometry with gaps and size hints applied.

This should be equal or smaller than geometry unless the minimum width and height are honored and larger than geometry. When the effective_geometry is smaller than the geometry and a placement function is set, it will be used to place the client within the parent area. That placement function is not allowed to change the width and height.

Constraints:

Table keys:
x (integer) : The horizontal position.
y (integer) : The vertical position.
width (integer) : The width.
height (integer) : The height.
Unit : pixel
Valid values : The geometry.

See also:

client.geometry Return or set client geometry. (client) object methods
wibox.geometry Get or set wibox geometry. (wibox) object methods
gaps
honor_size_hints Forwarded from the client property::size_hints_honor. signals
geometry
🔗 gaps integer or table or nil · 1 signal
Padding (usually called “useless gaps”) to put around a client or wibox.

Note that doing my_node.gaps.left = 1337 is not supported. The gaps can only be set as a full table or a number.However, the table does not need to contain all sides, so my_node.gaps = { left = 1337} will work.

Constraints:

Default value : 0
Type description:
integer : The same value for each side.
table: : A different value for each side.
left (integer) : The gap on the left of a client or wibox.
right (integer) : The gap on the right of a client or wibox.
top (integer) : The gap on the top of a client or wibox.
bottom (integer) : The gap on the bottom of a client or wibox.
nil : When called on a branch or awful.tree root node.
Unit : pixel
Minimum value : 0
Maximum value : 65535

See also:

geometry

Click to display more

Emit signals:

  • property::gaps When the gaps value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value gaps The new value affected to the property.
    • old_value gaps The property’s old value.
🔗 root awful.tree.node · read only
Get the node which has no further parent.

Note that this can return itself when it is the root.

Constraints:

Default value : It can be self when the type is "root“. Otherwise it will the recursive parent.
🔗 client client or nil · 1 signal · 1 signal
Return the client object, if any.

This only works on client nodes.

Constraints:

Default value : nil
Type description:
nil : When the node type isn’t "client".
client : When the node type is "client".

See also:

request::client_swap Forwarded from the client request::swap. signals
type
clients

Click to display more

Emit signals:

Emit signals:

  • property::client When the client value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value client The new value affected to the property.
    • old_value client The property’s old value.
🔗 clients table · 2 signals
Return a table with all clients held by this node and any children.

For the "client" node type, this returns a table with the .client. For the "branch" node type, this return all client found by :iterate_children

When setting this property, if the a client isn’t already present in the (sub-) tree, "request::add_client" will be emitted. If no node containing the client is added once the request is completed, :append_new { client = c } will be used as a fallback. It will also emit "request::remove_client" if necessary and use :detach() as a fallback.

Constraints:

Default value : {}
Table content : The collection of all children clients, unordered.

See also:

client A process window managed by AwesomeWM. module

Click to display more

Emit signals:
🔗 wibox wibox or nil · read only
Return the wibox object, if any.

This only works on wibox nodes.

Constraints:

Default value : nil
Type description:
nil : When the node type isn’t "wibox".
wibox : When the node type is "wibox".

See also:

type
client A process window managed by AwesomeWM. module
wiboxes
🔗 wiboxes table · read only
Return a table with all wiboxes held by this node and any children.

Constraints:

Default value : {}
Table content : The collection of all children wiboxes.

See also:

wibox Box where widget can be displayed. module
🔗 parent awful.tree.node or awful.tree or nil · read only
The parent node.

Constraints:

Default value : nil
Type description:
nil : When there is no parent.
awful.tree.node : When there is a parent.
awful.tree : When the parent is the root object.

See also:

first_child
last_child
🔗 previous_sibling awful.tree.node or nil · read only
The previous node which has the same parent.

Constraints:

Default value : nil
Type description:
nil : When there is no previous sibling.
awful.tree.node : When there is a previous sibling.

See also:

next_sibling
previous
parent
🔗 next_sibling awful.tree.node or nil · read only
The next node which has the same parent.

Constraints:

Default value : nil
Type description:
nil : When there is no next sibling.
awful.tree.node : When there is a next sibling.

See also:

previous_sibling
next
parent
🔗 previous awful.tree.node or nil · read only
The previous node as if the tree was a flat list.

Constraints:

Default value : nil
Type description:
nil : When there is no previous node.
awful.tree.node : When there is a previous node.

See also:

next
previous_sibling
parent
🔗 next awful.tree.node or nil · read only
The next node as if the tree was a flat list.

Constraints:

Default value : nil
Type description:
nil : When there is no next node.
awful.tree.node : When there is a next node.

See also:

previous
next_sibling
parent
🔗 first_child awful.tree.node or nil · read only
The first direct child.

Constraints:

Default value : nil
Type description:
nil : When there is no children.
awful.tree.node : When there is a child.

See also:

last_child
parent
🔗 last_child awful.tree.node or nil · read only
The last direct child.

Constraints:

Default value : nil
Type description:
nil : When there is no children.
awful.tree.node : When there is a child.

See also:

first_child
parent
🔗 type string · read only
What is the node content.

An awful.tree.node can contain a client, wibox or other nodes. Those are mutually exclusive and cannot be changed after the node has been created. The closest way to change the type is to use :wrap() and :join().

Constraints:

Default value : This depends of which method created the node.
Valid values:
"branch" : A node which can (optionally) contain other nodes.
"awful.tree" : A "branch" node without a parent.
"client" : A node which contain a client.
"wibox" : A node which contain a wibox.

See also:

wrap Wrap self with a new node. object methods
join Merge all children nodes and remove self. object methods
🔗 honor_size_hints table or boolean · 1 signal
When applying the geometry, honor the client size hints.

This is for client nodes only.

See the ICCCM documentation.

Constraints:

Default value : true
Type description:
boolean : Set all hints to true or false.
table: : Set each hints individually.
maximum_width (boolean) : The maximum width the client claims to support.
maximum_height (boolean) : The maximum height the client claims to support.
minimum_width (boolean) : The minimum width the client claims to support.
minimum_height (boolean) : The minimum height the client claims to support.
base_width (boolean) : The “default” width.
base_height (boolean) : The “default” height.
minimum_aspect_ratio (boolean) : The relation between the horizontal and vertical size.
maximum_aspect_ratio (boolean) : The relation between the horizontal and vertical size.
resize_width_increment (boolean) : The minimum num of pixels by which the width can be increased or decreased.
resize_height_increment (boolean) : The minimum num of pixels by which the height can be increased or decreased.

See also:

client.size_hints A table with size hints of the client. (client) object properties
client.size_hints_honor Honor size hints, e.g. (client) object properties
geometry

Click to display more

Emit signals:

  • property::honor_size_hints When the honor_size_hints value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value honor_size_hints The new value affected to the property.
🔗 protected boolean · 1 signal
When true, :cleanup() won’t remove the node and :detach() will fail.

This property is recursive. If any of the children nodes are protected, this will return true.

Constraints:

Default value : false
Valid values : true or false.

See also:

cleanup Emitted when a node has been removed from the tree. signals

Click to display more

Emit signals:

  • property::protected When the protected value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value protected The new value affected to the property.
    • old_value protected The property’s old value.
🔗 read_only boolean · read only
When true, none of the awful.tree mutator methods will work.

This property is recursive. If any of the parent nodes are read only, then this is also read only. This property cannot be set. All user created trees are read-write and most internal ones are read-only.

Constraints:

Default value : false
Valid values : true or false.
🔗 valid boolean · read only
Is false when the node has been deleted.

Deleted nodes cannot be re-used, they should not be kept in tables or it will leak memory.

Constraints:

Default value : true
Valid values : true or false.
🔗 label string or nil · 1 signal
A name for this node.

Constraints:

Default value : nil

Click to display more

Emit signals:

  • property::label When the label value changes.
    • self awful.tree The object which changed (useful when connecting many object to the same callback).
    • new_value label The new value affected to the property.
    • old_value label The property’s old value.
🔗 placement nil or placement
An awful.placement function to use when the client has size hints.

The function must place the client within a larger geometry. It is not allowed to set the width or height. The function called with the pretend argument set to true and the bounding_rect set to the value of geometry. The first object argument contains a geometry table representing the size with the gaps added.

Constraints:

Default value : awful.placement.top_left
Type description:
function: : A custom callback to generate and set the geometry.
Function prototype:
Parameters:
obj (object) : Any object with a geometry property or method.
args (table) : The placement arguments. See awful.placement for a complete list.
Return (table) : A table with an x, y, width and height keys.
placement : Any of the awful.placement function or constructs.

See also:

awful.placement Algorithms used to place various drawables. module
awful.placement.top_left Align a client to the top left of the parent area. (awful.placement) static module functions
honor_size_hints Forwarded from the client property::size_hints_honor. signals
gaps

Object methods

🔗 :swap (other) -> boolean

Swap 2 nodes.

 -- Get some of the nodes into variables.
 local client1 = tree.first_child
 local branch  = tree.first_child.next_sibling
 local client5 = tree.last_child

 -- Swap 'client1' and 'client5'.
 client1:swap(client5)

 -- Swap 'client1' and 'branch'.
 client1:swap(branch)

Parameters:

Name Type(s) Description
other awful.tree.node The other node.

Returns:

    boolean true if it was swapped and false if the tree is read only or other == self.
🔗 :join () -> boolean

Merge all children nodes and remove self.

Note: This is not recursive.

 -- Destroy the branch and merge all children into the tree.
 local branch  = tree.first_child.next_sibling
 branch:join()

Returns:

    boolean true if it was joined or false if the tree is read only or self is protected.

See also:

detach Remove a node from the tree. object methods
🔗 :push (other) -> boolean

Make the node passed as argument the first child node of self.

 -- Get some of the nodes into variables.
 local client1 = tree.first_child
 local branch  = tree.first_child.next_sibling
 local client5 = tree.last_child

 -- Move 'client5' to become 'tree.first_child'.
 tree:push(client5)

 -- Move 'client1' to become 'branch.first_child'.
 branch:push(client1)

Parameters:

Name Type(s) Description
other awful.tree.node The node which will become the new first_child of self.

Returns:

    boolean If the node was inserted. It will be false when the awful.tree is read only or other isn’t a valid awful.tree.node.

See also:

append Make the node passed as argument the last child node of self. object methods
move_after Move self after other. object methods
move_before Insert self before other. object methods
first_child
🔗 :append (other) -> boolean

Make the node passed as argument the last child node of self.

 -- Get some of the nodes into variables.
 local client1 = tree.first_child
 local branch  = tree.first_child.next_sibling
 local client5 = tree.last_child

 -- Move 'client1' to become 'tree.last_child'.
 tree:append(client1)

 -- Move 'client5' to become 'branch.last_child'.
 branch:append(client5)

Parameters:

Name Type(s) Description
other awful.tree.node The node which will become the new last_child of self.

Returns:

    boolean If the node was inserted. It will be false when the awful.tree is read only or other isn’t a valid awful.tree.node.

See also:

push Make the node passed as argument the first child node of self. object methods
move_after Move self after other. object methods
move_before Insert self before other. object methods
last_child
🔗 :detach () -> boolean · 2 signals

Remove a node from the tree.

Once detached, it can no longer be used again. This will also invalidate all children.

If the node or any of its children are protected or if the tree is read only, this method wont do anything and will return false.

 -- Remove client4.
 tree.last_child.previous:detach()

 -- Remove 'branch'.
 tree.last_child.previous_sibling:detach()

Returns:

    boolean If the node was detached. It will be false when the node is protected or the awful.tree is read only.

See also:

join Merge all children nodes and remove self. object methods

Click to display more

Emit signals:
🔗 :fork () -> awful.tree
Copy an entire (sub-)tree into a new awful.tree instance.

It only copy the official awful.tree properties, it does not copy the custom properties.

Returns:

    awful.tree The copy of self as a new awful.tree.
🔗 :cleanup () -> nil or awful.tree
Remove all unprotected nodes from the tree.

Returns:

    nil or awful.tree The removed nodes, if any.

See also:

protected
🔗 :move_before (other) -> boolean

Insert self before other.

This method takes an existing node, remove it from its current position and insert it before self. The other node must be part of the same tree.

 -- Get some of the nodes into variables.
 local client1 = tree.first_child
 local branch  = tree.first_child.next_sibling
 local client5 = tree.last_child

 -- Move 'client5' to become 'tree.first_child'.
 client5:move_before(client1)

 -- Move 'branch' before 'client1'.
 branch:move_before(client1)

Parameters:

Name Type(s) Description
other awful.tree.node The node which will be inserted.

Returns:

    boolean If the node was inserted. It will be false when the awful.tree is read only.

See also:

move_after Move self after other. object methods
push Make the node passed as argument the first child node of self. object methods
append Make the node passed as argument the last child node of self. object methods
🔗 :move_after (other) -> boolean

Move self after other.

This method takes an existing node, remove it from its current position and insert it after self. The other node must be part of the same tree.

 -- Get some of the nodes into variables.
 local client1 = tree.first_child
 local branch  = tree.first_child.next_sibling
 local client5 = tree.last_child

 -- Move 'client5' after 'client1' and before 'branch.
 client5:move_after(client1)

 -- Move 'client1' after 'branch'.
 client1:move_after(branch)

Parameters:

Name Type(s) Description
other awful.tree.node The node which will be inserted.

Returns:

    boolean If the node was inserted. It will be false when the awful.tree is read only or other isn’t a valid awful.tree.node.

See also:

move_before Insert self before other. object methods
push Make the node passed as argument the first child node of self. object methods
append Make the node passed as argument the last child node of self. object methods
🔗 :wrap {[args]} -> awful.tree.node

Wrap self with a new node.

-- Create a tree.
local tree = awful.tree {}

-- Add a bunch of clients.
for _, c in ipairs(client.get()) do
    tree:append_new {
        client = c,
    }
end

-- Wrap client2.
local second_node = tree.first_child.next_sibling
local new_branch  = second_node:wrap { label = "new_branch" }

-- Move client4 to the new branch.
local client4_node = tree.last_child.previous_sibling
new_branch:push(client4_node)

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be :wrap{}. This is a Lua shortcut syntax equivalent to :wrap({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table nil
label Optional string A name for the new wrapper node. nil
protected Optional boolean If the new node is protected during :cleanup(). false

Returns:

    awful.tree.node The new wrapper node.
🔗 :create_after {[args]} -> awful.tree.node

Create a new node and place it after self.

The node type depends on the arguments. If neither a client or a wibox is specified, the new node will contain a branch.

-- Create a tree.
local tree = awful.tree {}

-- Create a branch.
local branch1 = tree:push_new {
    label = "branch1",
}

-- Create another branch before "branch1".
branch1:create_after {
    label = "branch2",
}

-- Add a client to "branch1".
branch1:create_after {
    client           = client.get()[1],
    honor_size_hints = false,
    geometry         = {
        x       = 100,
        y       = 100,
        width   = 100,
        height  = 100,
    },
}

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be :create_after{}. This is a Lua shortcut syntax equivalent to :create_after({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table {}
client Optional client or nil A client object. nil
wibox Optional wibox or nil A wibox object. nil
protected Optional boolean If the new node is protected during :cleanup(). false
honor_size_hints Optional boolean Honor the client size hints when applying the client geometry. true
geometry Optional table or nil The geometry. nil

Returns:

    awful.tree.node The new node.

See also:

create_before Create a new node and place it before self. object methods
push_new Push a new node at the beginning of the branch. object methods
append_new Append a new node at the leaf end of this branch. object methods
🔗 :create_before {[args]} -> awful.tree.node

Create a new node and place it before self.

The node type depends on the arguments. If neither a client or a wibox is specified, the new node will contain a branch.

-- Create a tree.
local tree = awful.tree {}

-- Create a branch.
local branch1 = tree:push_new {
    label = "branch1",
}

-- Create another branch before "branch1".
branch1:create_before {
    label = "branch2",
}

-- Add a client to "branch1".
branch1:create_before {
    client           = client.get()[1],
    honor_size_hints = false,
    geometry         = {
        x       = 100,
        y       = 100,
        width   = 100,
        height  = 100,
    },
}

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be :create_before{}. This is a Lua shortcut syntax equivalent to :create_before({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table {}
client Optional client or nil A client object. nil
wibox Optional wibox or nil A wibox object. nil
protected Optional boolean If the new node is protected during :cleanup(). false
honor_size_hints Optional boolean Honor the client size hints when applying the client geometry. true
geometry Optional table or nil The geometry. nil

Returns:

    awful.tree.node The new node.

See also:

create_after Create a new node and place it after self. object methods
push_new Push a new node at the beginning of the branch. object methods
append_new Append a new node at the leaf end of this branch. object methods
🔗 :push_new {[args]} -> awful.tree.node

Push a new node at the beginning of the branch.

The new node will become self.first_child.

The node type depends on the arguments. If neither a client or a wibox is specified, the new node will contain a branch.

-- Create a tree.
local tree = awful.tree {}

-- Create a branch.
local branch1 = tree:push_new {
    label = "branch1",
}

-- Create another branch before "branch1".
tree:push_new {
    label = "branch2",
}

-- Add a client to "branch1".
branch1:push_new {
    client           = client.get()[1],
    honor_size_hints = false,
    geometry         = {
        x       = 100,
        y       = 100,
        width   = 100,
        height  = 100,
    },
}

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be :push_new{}. This is a Lua shortcut syntax equivalent to :push_new({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table {}
client Optional client or nil A client object. nil
wibox Optional wibox or nil A wibox object. nil
protected Optional boolean If the new node is protected during :cleanup(). false
honor_size_hints Optional boolean Honor the client size hints when applying the client geometry. true
geometry Optional table or nil The geometry. nil

Returns:

    awful.tree.node The new node.

See also:

create_after Create a new node and place it after self. object methods
create_before Create a new node and place it before self. object methods
append_new Append a new node at the leaf end of this branch. object methods
first_child
🔗 :append_new {[args]} -> awful.tree.node

Append a new node at the leaf end of this branch.

The new node will become self.last_child.

The node type depends on the arguments. If neither a client or a wibox is specified, the new node will contain a branch.

-- Create a tree.
local tree = awful.tree {}

-- Create a branch.
local branch1 = tree:append_new {
    label = "branch1",
}

-- Create another branch after "branch1".
tree:append_new {
    label = "branch2",
}

-- Add a client to "branch1".
branch1:append_new {
    client           = client.get()[1],
    honor_size_hints = false,
    geometry         = {
        x       = 100,
        y       = 100,
        width   = 100,
        height  = 100,
    },
}

Parameters:

Note: This object methods uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be :append_new{}. This is a Lua shortcut syntax equivalent to :append_new({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table {}
client Optional client or nil A client object. nil
wibox Optional wibox or nil A wibox object. nil
protected Optional boolean If the new node is protected during :cleanup(). false
honor_size_hints Optional boolean Honor the client size hints when applying the client geometry. true
geometry Optional table or nil The geometry. nil

Returns:

    awful.tree.node The new node.

See also:

create_after Create a new node and place it after self. object methods
create_before Create a new node and place it before self. object methods
push_new Push a new node at the beginning of the branch. object methods
last_child
🔗 :find_client_node (client) -> nil or awful.tree.node

Locate the node which contain a client.

-- Remove 'client1'.
tree:find_client_node(client.get()[1]):detach()

-- Remove 'client5'.
branch:find_client_node(client.get()[5]):detach()

Parameters:

Name Type(s) Description
client client A client.

Returns:

    nil or awful.tree.node The node which contain the client or nil.

See also:

find_wibox_node Locate the node which contain a wibox. object methods
client A process window managed by AwesomeWM. module
🔗 :find_wibox_node (wibox) -> nil or awful.tree.node

Locate the node which contain a wibox.

local wibox1, wibox2 = wibox {}, wibox {}

-- Remove 'wibox1'.
tree:find_wibox_node(wibox1):detach()

-- Remove 'wibox2'.
branch:find_wibox_node(wibox2):detach()

Parameters:

Name Type(s) Description
wibox wibox A wibox.

Returns:

    nil or awful.tree.node The node which contain the wibox or nil.

See also:

find_client_node Locate the node which contain a client. object methods
wibox Box where widget can be displayed. module

Signals

🔗 client::replaced
Emitted when one of the children node sets the client property.

This signal is only present in the awful.tree root object, not individual nodes.

Arguments:

Name Type(s) Description
self awful.tree The tree object.
node awful.tree.node The client node which had its client replaced.
previous_client client The client object it previously held.

See also:

client A process window managed by AwesomeWM. module
🔗 reorderred
Emitted when the node order changed.

It can be due to additions, deletions or order changes.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
source string Which method or event caused the change.
branch awful.tree or awful.tree.node The branch node closest to the change.
🔗 request::cleanup_node
Emitted when a node has been removed from the tree.

Arguments:

Name Type(s) Description
self awful.tree The node about to be removed.
context string Why the node is being removed.
hints table Any other information.
node awful.tree.node The node to cleanup.

See also:

request::cleanup Emitted when a node has been removed from the tree. signals
🔗 request::cleanup
Emitted when a node has been removed from the tree.

This signal is sent on individual nodes. Use request::cleanup_node if you need to receive all removed nodes on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The node about to be removed.
context string Why the node is being removed.
hints table Any other information.
node awful.tree.node The node to cleanup.

See also:

request::cleanup_node Emitted when a node has been removed from the tree. signals
🔗 client::added
Emitted on the awful.tree root node when a client is added.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree root node.
client client The client.

See also:

wibox::added Emitted on the awful.tree root node when a wibox is added. signals
client::replaced Emitted when one of the children node sets the client property. signals
🔗 wibox::added
Emitted on the awful.tree root node when a wibox is added.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree root node.
wibox wibox The wibox.

See also:

client::added Emitted on the awful.tree root node when a client is added. signals
🔗 request::client_swap
Forwarded from the client request::swap.

Usually, the handler should do one of two things. If :find_client_node() returns something for the swapped client, then the nodes should be swapped. If there isn’t, it is safe to call .client = other on the node.

This signal is only present on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the client swapped.
hints table Other data.
client client The client to replace.
node awful.tree.node The node on which to replace the client.

See also:

client A process window managed by AwesomeWM. module
🔗 request::raise_node
Forwarded from the client or wibox request::raise.

This signal is only present on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the object in need of being raised.
hints table Other data.
node awful.tree.node The node on which to replace the client.

See also:

client A process window managed by AwesomeWM. module
🔗 request::lower_node
Forwarded from the client or wibox request::lower.

This signal is only present on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the object in need of being lowered.
hints table Other data.
node awful.tree.node The node on which to replace the client.

See also:

client A process window managed by AwesomeWM. module
🔗 request::resize_node
Forwarded from the client request::resize.

This signal is only present on the awful.tree root object.

See also:

client A process window managed by AwesomeWM. module
🔗 request::honor_size_hints
Forwarded from the client property::size_hints_honor.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the size hints chaning.
hints table Other data.
node awful.tree.node The node on which to replace the client.
🔗 request::add_client
Sent when a client is added to one of the tags.

This signal is only present on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the client added.
hints table Other data.
client client The client.

See also:

client A process window managed by AwesomeWM. module
🔗 request::remove_client
Sent when the client is no longer tagged in any of the tags.

This signal is only present on the awful.tree root object.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the client removed.
hints table Other data.
client client The client.

See also:

client A process window managed by AwesomeWM. module
🔗 request::hide
Hide object when none of the tags are the primary selection.

If there are, for example, wiboxes to hide, do it here.

A tag “primary seletion” means when it is selected and its layout is used. When multiple tags are selected, it usually means the one with the lowest index.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the tree being hidden.
hints table Other data (currently empty).
🔗 request::show
Show objects when one of the tag is the primary selection.

Note that it isn’t required to implement this signal. Making the wibox visible and other tasks like it can be done when arrange is called on the layout.

A tag “primary seletion” means when it is selected and its layout is used. When multiple tags are selected, it usually means the one with the lowest index.

Arguments:

Name Type(s) Description
self awful.tree The awful.tree object.
context string Why is the tree being hidden.
hints table Other data (currently empty).
generated by LDoc 1.4.6