Permalink
Browse files

Add a graphical depiction of the object graph to the docs.

Also, stop calling the graph a hierarchy or a tree. We'll now consistently
refer to it as an "object graph".
  • Loading branch information...
1 parent 6a20326 commit 2d68649fe763c1192bbed684ee6f55b3f5bf9883 @cortesi cortesi committed Nov 15, 2008
Showing with 70 additions and 46 deletions.
  1. +1 −1 doc-src/index.py
  2. +25 −42 doc-src/objects.html
  3. BIN doc-src/objgraph.png
  4. +3 −3 doc-src/qsh.html
  5. +7 −0 resources/README
  6. +34 −0 resources/objgraph.dot
View
@@ -35,7 +35,7 @@ def py(self, path, **kwargs):
pages = [
Page("index.html", "Introduction"),
- Page("objects.html", "Object Hierarchy"),
+ Page("objects.html", "Object Graph"),
Directory("objects"),
Page("configuration.html", "Configuration"),
Directory("configuration"),
View
@@ -1,6 +1,6 @@
-Qtile's public API consists of a hierarchy of nodes, each with a set of
-associated commands. The same API serves a number of different purposes:
+Qtile's public API consists of a graph of nodes, each with a set of associated
+commands. The same API serves a number of different purposes:
- Commands can be bound to keys in the Qtile configuration file.
- Commands can be called manually through __qsh__, the Qtile shell.
@@ -10,43 +10,26 @@
can be accessed from its built-in help command, and are not documented here.
-Object Hierarchy
-================
+Object Graph
+============
- Qtile's object hierarchy consists of seven node types: __layout__,
- __window__, __group__, __bar__, __widget__, __screen__, and a special root
- node that lies at the top of the tree. Each node has a set of associated
- commands, a set of children, and a set of keys. This is what the hierarchy
- looks like at a high level:
+ Qtile's object graph consists of seven node types: __layout__, __window__,
+ __group__, __bar__, __widget__, __screen__, and a special __root__ node.
+ Individual nodes are addressed by a path specification that starts at the
+ root node, and follows the edges of the graph. Each node has a set of
+ associated commands, a set of children, and a set of keys. This is what
+ the graph looks like:
-<pre>
-root
- bar
- screen
- group
- layout
- screen
- window
- layout
- group
- screen
- window
- screen
- bar
- layout
- window
- widget
- bar
- group
- screen
- window
- group
- screen
- layout
-</pre>
+<center>
+<img src="objgraph.png">
+</center>
+
+ Each arrow can be read as "holds a reference to". So, we would say that a
+ __widget__ object _holds a reference to_ objects of type __bar__,
+ __screen__ and __group__, exposed as attributes with the same names.
Lets start with a simple example. The following script runs the __status__
- command on the root node of the command tree (which, in this case, is the
+ command on the root node of the command graph (which, in this case, is the
Client object):
<!--(block | pySyntax)-->
@@ -55,16 +38,16 @@
print c.status()
<!--(end)-->
- Children are exposed as attributes on each node, so we can access the
- "info" command on the group child node like so:
+ From the graph, we can see that the root node holds a reference to
+ __group__ nodes. We can access the "info" command on the current group like
+ so:
<!--(block | pySyntax)-->
c.group.info()
<!--(end)-->
- In the example above, __c.group__ specifies the _current_ group. To access
- a specific group, regardless of whether or not it is current, we use the
- Python containment syntax:
+ To access a specific group, regardless of whether or not it is current, we
+ use the Python containment syntax:
<!--(block | pySyntax)-->
c.group["b"].info()
@@ -74,7 +57,7 @@
accessed by simply leaving the key specifier out. The key specifier is
mandatory for __widget__ and __bar__ nodes.
- We can now drill down deeper in the hierarchy. To access the screen
+ We can now drill down deeper in the graph. To access the screen
currently displaying group "b", we can do this:
<!--(block | pySyntax)-->
@@ -89,7 +72,7 @@
libqtile.command.CommandError: No object screen in path 'group['b'].screen'
</pre>
- The hierarchy is not a tree, since it can contain cycles. This path
+ The graph is not a tree, since it can contain cycles. This path
(redundantly) specifies the group belonging to the screen that belongs to
group "b":
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
@@ -7,10 +7,10 @@
file. See the GNU Readline documentation for more information.
-Navigating the Object Hierarchy
-===============================
+Navigating the Object Graph
+===========================
-The shell presents a filesystem-like interface to the object hierarchy - the
+The shell presents a filesystem-like interface to the object graph - the
builtin "cd" and "ls" commmands act like their familiar shell counterparts:
<pre>
View
@@ -0,0 +1,7 @@
+
+
+objgraph.dot
+
+ The Qtile object graph, in graphviz dot format. Render like so:
+
+ circo -Tpng objgraph.dot > objgraph.png
View
@@ -0,0 +1,34 @@
+
+digraph G {
+ root = "root";
+ splines = true;
+
+ root -> bar;
+ root -> group;
+ root -> layout;
+ root -> screen;
+ root -> widget;
+ root -> window;
+
+ bar -> screen;
+
+ group -> layout;
+ group -> screen;
+ group -> window;
+
+ layout -> group;
+ layout -> screen;
+ layout -> window;
+
+ screen -> bar;
+ screen -> layout;
+ screen -> window;
+
+ widget -> bar;
+ widget -> group;
+ widget -> screen;
+
+ window -> group;
+ window -> screen;
+ window -> layout;
+}

0 comments on commit 2d68649

Please sign in to comment.