Added note about GUI architecture to doc/hacking.txt + doc/img/gui_flow/.

doc/img/gui_flow/
|-- gui_flow.xml              XML definition of the information-flow graph.
|-- graph.xsl                 XSLT translating gui_flow.xml -> gui_flow.svg
`-- math.sqrt.template.xsl    Template for calculating sqrt(x) in XSLT.

Periodically I get the hare-brained idea that I want to do something
with XSLT.  I'm not sure what I was thinking ;).  It's done now though,
and it seems a shame to waste it.

diff --git a/doc/hacking.txt b/doc/hacking.txt
index 70f2f8b62137ea8b97d35507ff7641768d1e3544..c0e954da0f404781d264c4971865f0488a3f0992 100644 (file)
--- a/doc/hacking.txt
+++ b/doc/hacking.txt
@@ -147,3 +147,19 @@ There are also a number of features who's standard library support
 changes with different versions of Python.  :mod:`~hooke.compat`
 provides a uniform interface to those tools so that Hooke will work
 with several Python versions.
+
+GUI
+---
+
+:mod:`hooke.ui.gui` contains enough code that you might want a word
+about its organization before diving into the code.  Information flows
+like this:
+
+.. image:: img/gui_flow/gui_flow.svg
+  
+With the following naming scheme in HookeFrame:
+
+  ===================  ==================
+  callbacks            ``_on_*``
+  response processors  ``_postprocess_*``
+  ===================  ==================

diff --git a/doc/img/gui_flow/graph.xsl b/doc/img/gui_flow/graph.xsl
new file mode 100644 (file)
index 0000000..4d7d2fc
--- /dev/null
+++ b/doc/img/gui_flow/graph.xsl
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:svg="http://www.w3.org/2000/svg"
+               xmlns:xlink="http://www.w3.org/1999/xlink"
+                xmlns:math="http://exslt.org/math"
+               xmlns:ex="http://www.example.com/graph"
+                version="1.0">
+  <xsl:import href="math.sqrt.template.xsl"/>
+  <xsl:output indent="yes"/>
+
+  <xsl:template match="ex:graph">
+    <xsl:variable name="view-box" select="./ex:config/@viewBox"/>
+    <svg:svg version="1.0" viewBox="{$view-box}">
+      <svg:defs>
+       <xsl:variable name="arc-color" select="./ex:config/@arc-color"/>
+       <svg:marker id="arrowhead" viewBox="0 0 20 20" refX="20" refY="10" 
+                   markerUnits="strokeWidth" markerWidth="8" markerHeight="6"
+                   orient="auto" style="{$arc-color}">
+         <svg:path d="M 0 0 L 20 10 L 0 20 z"/>
+       </svg:marker>
+      </svg:defs>
+      <!-- making sure the arcs are drawn first -->
+      <xsl:apply-templates select="ex:arc"/>
+      <xsl:apply-templates select="ex:node"/>
+    </svg:svg>
+  </xsl:template>
+
+  <xsl:template match="ex:arc">
+    <xsl:variable name="text-color" select="../ex:config/@text-color"/>
+    <xsl:variable name="arc-color" select="../ex:config/@arc-color"/>
+    <xsl:variable name="node-radius" select="../ex:config/@node-radius"/>
+    <xsl:variable name="arc-offset" select="../ex:config/@arc-offset"/>
+    <svg:g style="{$arc-color}">
+      <xsl:variable name="from"><xsl:value-of select="@from"/></xsl:variable>
+      <xsl:variable name="to"><xsl:value-of select="@to"/></xsl:variable>
+      <xsl:variable name="x1" select="../ex:node[@name=$from]/@cx"/>
+      <xsl:variable name="y1" select="../ex:node[@name=$from]/@cy"/>
+      <xsl:variable name="x2" select="../ex:node[@name=$to]/@cx"/>
+      <xsl:variable name="y2" select="../ex:node[@name=$to]/@cy"/>
+      <!-- calculate endpoints shortened by $node-radius + $arc-offset -->
+      <xsl:variable name="Dx" select="$x2 - $x1"/>
+      <xsl:variable name="Dy" select="$y2 - $y1"/>
+      <xsl:variable name="Dsquare" select="($Dx*$Dx + $Dy*$Dy)"/>
+      <xsl:variable name="D"><xsl:call-template name="sqrt">
+         <xsl:with-param name="number" select="$Dsquare"/>
+      </xsl:call-template></xsl:variable>
+      <xsl:variable name="a-off" select="$node-radius + $arc-offset"/> 
+      <xsl:variable name="dx" select="$a-off * $Dx div $D"/>
+      <xsl:variable name="dy" select="$a-off * $Dy div $D"/>
+      <xsl:variable name="X1" select="$x1 + $dx"/>
+      <xsl:variable name="Y1" select="$y1 + $dy"/>
+      <xsl:variable name="X2" select="$x2 - $dx"/>
+      <xsl:variable name="Y2" select="$y2 - $dy"/>
+      <svg:path style="marker-end:url(#arrowhead);stroke-width:1;"
+               d="M{$X1} {$Y1} L{$X2} {$Y2}"/>
+      <svg:defs>
+       <svg:path id="textPath-{@label}" d="M{$X1} {$Y1} L{$X2} {$Y2}"/>
+      </svg:defs>
+      <svg:text text-anchor="middle" style="{$text-color}">
+       <svg:textPath xlink:href="#textPath-{@label}" startOffset="50%">
+         <svg:tspan dy="-0.4em">  <!-- raise text slightly off the line -->
+           <xsl:value-of select="@label"/>
+         </svg:tspan>
+       </svg:textPath>
+      </svg:text>
+    </svg:g>
+  </xsl:template>
+
+  <xsl:template match="ex:node">
+    <xsl:variable name="text-color" select="../ex:config/@text-color"/>
+    <xsl:variable name="node-color" select="../ex:config/@node-color"/>
+    <xsl:variable name="node-radius" select="../ex:config/@node-radius"/>
+    <svg:g style="{$node-color}">
+      <svg:circle cx="{@cx}" cy="{@cy}" r="{$node-radius}"/>
+      <svg:text text-anchor="middle" x="{@cx}" y="{@cy}"
+               style="dominant-baseline:central;{$text-color}">
+       <xsl:value-of select="@label"/>
+      </svg:text>
+    </svg:g>
+  </xsl:template>
+</xsl:stylesheet>

diff --git a/doc/img/gui_flow/gui_flow.xml b/doc/img/gui_flow/gui_flow.xml
new file mode 100644 (file)
index 0000000..2ab957c
--- /dev/null
+++ b/doc/img/gui_flow/gui_flow.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<?xml-stylesheet href="graph.xsl" type="text/xsl" alternate="no"?>
+<ex:graph xmlns:ex="http://www.example.com/graph">
+  <ex:config text-color="stroke:none;fill:rgb(44,44,44);"
+            node-color="stroke:rgb(44,44,44);fill:white;"
+            arc-color="stroke:rgb(44,44,44);fill:rgb(44,44,44);"
+            node-radius="35" arc-offset="5"
+            viewBox="0 0 586 86"/>
+  <ex:node name="panels" cx="43" cy="43" label="Panels"/>
+  <ex:node name="frame" cx="293" cy="43" label="Frame"/>
+  <ex:node name="engine" cx="543" cy="43" label="Engine"/>
+  <ex:arc from="panels" to="frame" label="callbacks" rotate="90"/>
+  <ex:arc from="frame" to="panels" label="panel methods"/>
+  <ex:arc from="frame" to="engine" label="execute_command()"/>
+  <ex:arc from="engine" to="frame" label="response processors"/>
+</ex:graph>

diff --git a/doc/img/gui_flow/math.sqrt.template.xsl b/doc/img/gui_flow/math.sqrt.template.xsl
new file mode 100644 (file)
index 0000000..00196eb
--- /dev/null
+++ b/doc/img/gui_flow/math.sqrt.template.xsl
@@ -0,0 +1,37 @@
+<?xml version="1.0"?>\r
+<!-- http://www.exslt.org/math/functions/sqrt/math.sqrt.template.xsl -->\r
+<xsl:stylesheet version="1.0"\r
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"\r
+                xmlns:math="http://exslt.org/math"\r
+                extension-element-prefixes="math">\r
+\r
+<xsl:template name="sqrt">\r
+  <!-- The number you want to find the square root of -->\r
+  <xsl:param name="number" select="0" />  \r
+  <!-- The current 'try'.  This is used internally. -->\r
+  <xsl:param name="try" select="1" />\r
+  <!-- The current iteration, checked against maxiter to limit loop count -->  \r
+  <xsl:param name="iter" select="1" />\r
+  <!-- Set this up to ensure against infinite loops -->\r
+  <xsl:param name="maxiter" select="10" />\r
+\r
+  <!-- This template was written by Nate Austin using Sir Isaac Newton's\r
+       method of finding roots -->\r
+\r
+  <xsl:choose>\r
+    <xsl:when test="$try * $try = $number or $iter > $maxiter">\r
+      <xsl:value-of select="$try"/>\r
+    </xsl:when>\r
+    <xsl:otherwise>\r
+      <xsl:call-template name="sqrt">\r
+        <xsl:with-param name="number" select="$number"/>\r
+        <xsl:with-param name="try" \r
+                        select="$try - (($try * $try - $number) div (2 * $try))"/>\r
+        <xsl:with-param name="iter" select="$iter + 1"/>\r
+        <xsl:with-param name="maxiter" select="$maxiter"/>\r
+      </xsl:call-template>\r
+    </xsl:otherwise>\r
+  </xsl:choose>\r
+</xsl:template>\r
+\r
+</xsl:stylesheet>\r