From 197b9476cd884b5f462ff406d177c84eac9bea31 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@drexel.edu>
Date: Sun, 1 Aug 2010 16:32:57 -0400
Subject: [PATCH] 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.
---
 doc/hacking.txt                         | 16 +++++
 doc/img/gui_flow/graph.xsl              | 81 +++++++++++++++++++++++++
 doc/img/gui_flow/gui_flow.xml           | 16 +++++
 doc/img/gui_flow/math.sqrt.template.xsl | 37 +++++++++++
 4 files changed, 150 insertions(+)
 create mode 100644 doc/img/gui_flow/graph.xsl
 create mode 100644 doc/img/gui_flow/gui_flow.xml
 create mode 100644 doc/img/gui_flow/math.sqrt.template.xsl

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