File: layout.html

package info (click to toggle)
sqlkit 0.9.5-1
links: PTS, VCS
area: main
in suites: wheezy
size: 8,184 kB
sloc: python: 17,477; sql: 166; makefile: 95; xml: 23; sh: 11
file content (897 lines) | stat: -rw-r--r-- 39,571 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      
      <title>
    A GUI description language - purpose
 &mdash; sqlkit v0.9.5 documentation</title>
      
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/sqlkit.css" type="text/css" />
    <link rel="stylesheet" href="../_static/print.css" type="text/css" media="print" />

    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="sqlkit v0.9.5 documentation" href="../index.html" />
        <link rel="up" title="Layout GUI built on the fly  - A GUI description language" href="contents.html" />
        <link rel="next" title="Debug helpers" href="../debug/contents.html" />
        <link rel="prev" title="Layout GUI built on the fly  - A GUI description language" href="contents.html" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.9.5',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>


<!-- <link rel="stylesheet" href="http://www.myjqueryplugins.com/plugins/jmenu/demo/jquery/jMenu.jquery.css" type="text/css" /> -->
      <link rel="stylesheet" href="../_static/jMenu.jquery.css" type="text/css" />
      <script type="text/javascript" src="http://www.myjqueryplugins.com/plugins/jmenu/demo/jquery/jquery.js"></script>
      <script type="text/javascript" src="http://www.myjqueryplugins.com/plugins/jmenu/demo/jquery/jquery-ui.js"></script>

      <!-- <script type="text/javascript" src="http://www.myjqueryplugins.com/plugins/jmenu/demo/jquery/jMenu.jquery.js"></script> -->

      <script type="text/javascript">

	var _gaq = _gaq || [];
	_gaq.push(['_setAccount', 'UA-18221996-2']);
	_gaq.push(['_trackPageview']);

	(function() {
	  var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();

      </script>
      <script type="text/javascript" src="../_static/jMenu.jquery.js"></script>
      <script type="text/javascript">
	      $(document).ready(function(){
		      $("#jMenu").jMenu({
			      ulWidth : '150',
			      effects : {
				      effectSpeedOpen : 300,
				      effectSpeedClose : 300,
				      effectTypeOpen : 'slide',
				      effectTypeClose : 'slide',
				      effectOpen : 'linear',
				      effectClose : 'linear'
			      },
			      TimeBeforeOpening : 100,
			      TimeBeforeClosing : 400,
			      animatedText : false,
			      paddingLeft: 1		});
	      })
      </script>
<!-- Preview -->
     <script type="text/javascript" src="../_static/imgpreview.js"></script>
     <script type="text/javascript">
       $(document).ready(function(){
           $('.preview').imgPreview();
       });
     </script>
     
     <!--[if !IE 7]>
	     <style type="text/css">
		     #wrap {display:table;height:100%}
	     </style>
     <![endif]-->
    </head>
    <body>
        




<div id="wrap">
    
<div id="header">

	<div class="logo"><a href="../misc/tour.html">
       <img src="../_static/sqlkit.png" align="left"  alt="Logo" border="0"/></a>
        </div>
	<div id="description">Acces to db made easy</div>
</div>


   <div style="clear:left;"></div>


<div >
	<ul id="jMenu">
            <li><a class="fNiv" href="../index.html" title="Home" 
                  >Home</a></li>

            <li><a li class="fNiv" href="../sqlkit/contents.html"
                  title="Sqlkit - the python package" 
                  >Sqlkit</a>

	       <ul>
		 <li ><a href="../sqlkit/contents.html"
		       title="Sqlkit - the python package" 
		       >Sqlkit</a></li>

		 <li ><a href="../sqlkit/sqlwidget.html" title="Widgets" 
		       >Widgets</a>
		       <ul> 
			 <li ><a href="../sqlkit/mask.html" title="Mask" 
			       >Mask view</a></li>
			 <li ><a href="../sqlkit/table.html" title="Table" 
			       >Table view</a></li>
		       </ul>
                 </li>
		 <li ><a href="../sqlkit/browsing.html" title="Browsing Data" 
		       >Browsing data</a>
		    <ul> 
		      <li ><a href="../sqlkit/constraints.html" title="Constraints" 
			    >Constraints</a></li>
		      <li ><a href="../sqlkit/filters.html" title="Filters" 
			    >Filters</a></li>
		      <li ><a href="../sqlkit/totals.html" title="Totals" 
			    >Totals</a></li>
		    </ul>
                 </li>
		 <li ><a href="../sqlkit/editing.html" title="Editing Data" 
		       >Editing data</a>
			 <ul> 
			   <li ><a href="../sqlkit/completion.html" title="Completion" 
				 >Completion</a></li>
			   <li ><a href="../sqlkit/validation.html" title="Validation" 
				 >Validation</a></li>
			   <li ><a href="../sqlkit/relationship.html" title="Relationships" 
				 >Relationships</a></li>
			 </ul>
		       </li>
		 <li ><a href="../sqlkit/printing.html" title="Printing" 
		       ><span>Printing</span></a></li>
		 <li ><a href="../sqlkit/advanced/contents.html" title="Advanced configuration" 
		       >Advanced configuration</a>
			 <ul> 
			   <li ><a href="../sqlkit/advanced/fields.html" title="Fields" 
				 >Fields</a></li>
			   <li ><a href="../sqlkit/advanced/views.html" title="Views" 
				 >Views</a></li>
			 </ul>
		       </li>

	       </ul>
            </li>

            <li><a class="fNiv" href="../misc/sqledit.html"
                  title="Sqledit GUI" 
                  >Sqledit GUI</a></li>

            <li><a class="fNiv" href="../misc/tutorials.html"
                  title="Support & tutorials" 
                  >Support & Tutorials</a>
	       <ul>
		 <li ><a href="../misc/sqledit.html"
		       title="Sqledit - the application" 
		       >Sqledit - the application</a></li>
		 <li ><a href="../misc/tour.html"
		       title="Sqlkit - the features'tour"
		       >Sqlkit - features' tour</a></li>
		 <li ><a href="../misc/sqledit.html"
		       title="Sqledit - the application" 
		       >Installing instructions</a></li>
		</ul> 
            </li>

            <li><a class="fNiv" href="contents.html" title="Layout"
                  >Layout</a></li>

            <li><a  class="fNiv"href="../misc/contents.html" title="Download" 
                  >Download</a>

	       <ul>
		 <li ><a href="../misc/contents.html"
		       title="Download"
		       >Download</a></li>
		 <li ><a href="http://sqlkit.argolinux.org/download/Changelog"  title="Changelog"
		       title="Changelog"
		       >Changelog</a></li>
		 <li ><a href="../misc/backward_incompatibilities.html"
		       title="Backward incompatibilities"
		       >Backward incompatibilities</a></li>
	       </ul>
            </li>



        </ul>
</div>
   <div style="clear:left;"></div>

    
    <div class="related">
      <ul>
	
<!-- <div class="prevnext"> -->
<!--    <li class="right"  style="margin-right: 10px">Indice -->
<!--      <a href="../genindex.html" title="Indice generale" -->
<!--                accesskey="I">indice</a></li> -->

        <li class="right">Prev:
        <a href="contents.html" title="previous chapter">Layout GUI built on the fly  - A GUI description language</a></li>
        <li class="right">Next:
        <a href="../debug/contents.html" title="next chapter">Debug helpers</a></li>
<!-- </div> -->


      </ul>

    </div>

    
  <div class="sphinxsidebar">
     <div class="sphinxsidebarwrapper">


	    <div class="topnav">
    <h3>Table of contents</h3>
		    <ul>
<li><a class="reference external" href="#">A GUI description language - purpose</a></li>
<li><a class="reference external" href="#description-of-the-language">Description of the language</a><ul>
<li><a class="reference external" href="#a-longer-example">a longer example</a></li>
<li><a class="reference external" href="#comment">Comment</a></li>
<li><a class="reference external" href="#el-element">el element</a><ul>
<li><a class="reference external" href="#list-of-elements">list of elements</a></li>
</ul>
</li>
<li><a class="reference external" href="#custom-widgets">custom  widgets</a><ul>
<li><a class="reference external" href="#calling-layout">Calling Layout</a></li>
</ul>
</li>
<li><a class="reference external" href="#methods">methods</a><ul>
<li><a class="reference external" href="#element-names">element names</a></li>
</ul>
</li>
<li><a class="reference external" href="#stock-names">stock names</a></li>
<li><a class="reference external" href="#notebook">Notebook</a></li>
<li><a class="reference external" href="#automatic-name-mechanism">Automatic name mechanism</a></li>
<li><a class="reference external" href="#container-naming">container naming</a><ul>
<li><a class="reference external" href="#functions">Functions</a></li>
<li><a class="reference external" href="#layout-class-implementation">Layout class implementation</a></li>
</ul>
</li>
<li><a class="reference external" href="#lwidgets-and-lcontainer">LWidgets and LContainer</a></li>
<li><a class="reference external" href="#window-creation">Window creation</a></li>
<li><a class="reference external" href="#producing-xml">Producing xml</a></li>
</ul>
</li>
</ul>

		<div class="clearboth"></div>
	    </div>



    <h3>Questions?</h3>

    <p>Subscribe to out mailing list <a href="http://groups.google.com/group/sqlkit">
       Google group</a>:</p>

    <form action="http://groups.google.com/group/sqlkit/boxsubscribe" style="padding-left: 1em">
      <input type="text" name="email" value="your@email"/>
      <input type="submit" name="sub" value="Subscribe" />
    </form>
    <div id="searchbox" style="display: none">

    <h3>Quick search</h3>
	<form class="search" action="../search.html" method="get">
	  <input type="text" name="q" size="18" />
	  <input type="submit" value="Search" />
	  <input type="hidden" name="check_keywords" value="yes" />

	  <input type="hidden" name="area" value="default" />
	</form>
	<p class="searchtip" style="font-size: 90%">
        Enter search terms or a module, class or function name.
	</p>
    <h3>License</h3>
	<img src="../_static/gplv3.png" alt="logo GPLv3">

    </div>
    <script type="text/javascript">$('#searchbox').show(0);</script>

     </div>
  </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">

            <div class="body">
                
<div class="section" id="a-gui-description-language-purpose">
<span id="layout"></span><h1>A GUI description language - purpose<a class="headerlink" href="#a-gui-description-language-purpose" title="Permalink to this headline">¶</a></h1>
<div class="sidebar">
<p class="first sidebar-title">Note</p>
<p>this page needs to be reviewed. While it should be mostly correct
when ported to rest format has not been reviewed.</p>
<p class="last">A complete tour of what can be done is available in the demo</p>
</div>
<p>The class Layout is a class that understands a GUI description
language to create GUI on the fly, with minimal effort by the programmers,
that doesn&#8217;t need to know a lot of Gtk details.</p>
<p>You cannot do <em>any</em> possible thing you would do with gtk, but methods are
provided to refine the layout and it isn&#8217;t difficult to add GtkObjects or
features.</p>
<p>The purpose is to easy things with simple setup, not to cover any possible
graphical layout. The main purpose is to be used in designing layout of
record editor (<a class="reference external" href="../misc/tour.html#sqlkit"><em>Features</em></a>) for db, but it can be used with any other
program as well.</p>
<p>Layout is not an interactive tool: it uses gtk.Builder xml to create the GUI, ie:
it produces xml for gtk.Builder.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>gtk.Builder</p>
<p class="last">up to 0.9.2 sqlkit used glade. This dependancy has been dropped in favor
of gtk.Builder that is directly available in standard GTK installation.</p>
</div>
<p>Care must be used to create names for the elements that are unique in
the single layout, so as to be able to reach any single object, not only to
refine configuration but also to interact with the GtkObj in the
program. This reflects in the fact that the name is unique.</p>
<p>A normal GUI is plenty of labels and tooltip.
At the moment of this writing no localization is provided but gettext
support is in program.</p>
</div>
<div class="section" id="description-of-the-language">
<h1>Description of the language<a class="headerlink" href="#description-of-the-language" title="Permalink to this headline">¶</a></h1>
<p>a starting example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">layout</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s">   el=first_name  el=last_name</span>
<span class="s">   el=address     -</span>
<span class="s">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>A layout is a sequence of tokens and display modifiers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">token:</th><td class="field-body"><p class="first">describes a GtkObject (Button, Entry...), may also be a compound. An
example: el=first_name. They will normally start with a description key,
followed by a &#8216;=&#8217; and then followed by a string possibly separated by a
&#8216;/&#8217; and.or a:</p>
<div class="highlight-python"><pre>key=string/variable:wid1.wid2</pre>
</div>
<p>or in regexp notation and more precise:</p>
<div class="highlight-python"><pre>(key=)string(.[0-9a-z])?(/variable)((:width.)(width)([-&lt;&gt;]))?
 key   txt    id          var        width1   width2  align</pre>
</div>
<p>no element is needed apart the &#8216;string&#8217;, the key defaults to &#8216;el&#8217; (Entry +
Label), the variable defaults to the string, wid1 and wid2 (described
below) use GtkWidget defaults.</p>
<p>The string part may end with .[a-z0-9] just to be able to refer in a
unique way to single elements that are apparently equal (see <a class="reference internal" href="#names"><em>element names</em></a>)</p>
<p>an indication of the desidered alignment may be given using one of (&#8216;-&#8216;,
&#8216;&lt;&#8217;, &#8216;&gt;&#8217;). this take effect oly if the element is position in a
gtk.Alignment (eg. &#8216;ae&#8217; element ie: entry with width). in that case:</p>
<blockquote class="last">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">&gt;:</th><td class="field-body">right alignment   (xalign = 1)</td>
</tr>
<tr class="field"><th class="field-name">&lt;:</th><td class="field-body">left alignment    (xalign = 0)</td>
</tr>
<tr class="field"><th class="field-name">-:</th><td class="field-body">xscale of the alignment is set to 1 i.e. the child of the
alignment (the entry in the example will grow when more space
is given to the widget)</td>
</tr>
</tbody>
</table>
</blockquote>
</td>
</tr>
</tbody>
</table>
<div class="sidebar">
<p class="first sidebar-title">Automatisms with sqlkit</p>
<p class="last">Note that when used from within sqlkit layout definition any text
field is rendered with entry within an alignment (<tt class="docutils literal"><span class="pre">ae</span></tt> element) and an
alignment of &#8216;-&#8216; is added to any text field longer than 20 chars.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">spare token:</th><td class="field-body"><p class="first">A token may further be:</p>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">&#64;:</th><td class="field-body">it is equivalent to a newline (in fact I figure it like spinning ;-)</td>
</tr>
<tr class="field"><th class="field-name">-:</th><td class="field-body">forces the previous element to span one more column to the left</td>
</tr>
<tr class="field"><th class="field-name">^:</th><td class="field-body">forces the element above it to span one more row down</td>
</tr>
<tr class="field"><th class="field-name">%.*:</th><td class="field-body">the element is a label for a notebook (see &#8216;notebook&#8217; method)</td>
</tr>
</tbody>
</table>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">display modifiers:</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">A modifier is an element that modifies the way elements are arranged,
mainly it modifies the packing info or the container, but can also modify
the display eg: label and entry on the same line or one above the other.
A modifier is:</p>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">{}:</th><td class="field-body"><p class="first">a pair of curly braces</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">[XTHVbNPSvhpOBmMFA](.id):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">(possibly) followed (w/out spaces) by some opts as in
{V r=man/sex r=woman}, this will create a nester layout with 2
radiobutton packed into a GtkVBox. For an explanation of the (.id)
part see below (container naming)</p>
<p>Possible opts are XTHVbNPSvhpOBmMFA:</p>
<blockquote class="last">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">T:</th><td class="field-body">gtkTable</td>
</tr>
<tr class="field"><th class="field-name">H:</th><td class="field-body">gtkHBox</td>
</tr>
<tr class="field"><th class="field-name">V:</th><td class="field-body">gtkVBox</td>
</tr>
<tr class="field"><th class="field-name">N:</th><td class="field-body">gtkNotebook</td>
</tr>
<tr class="field"><th class="field-name">F:</th><td class="field-body">gtkFrame</td>
</tr>
<tr class="field"><th class="field-name">M:</th><td class="field-body">gtkMenubar</td>
</tr>
<tr class="field"><th class="field-name">t:</th><td class="field-body">gtkToolBar</td>
</tr>
<tr class="field"><th class="field-name">h:</th><td class="field-body">gtkHPaned</td>
</tr>
<tr class="field"><th class="field-name">v:</th><td class="field-body">gtkVPaned</td>
</tr>
<tr class="field"><th class="field-name">S:</th><td class="field-body">gtkScrolledWindow</td>
</tr>
<tr class="field"><th class="field-name">B:</th><td class="field-body">gtkMenuBar</td>
</tr>
<tr class="field"><th class="field-name">M:</th><td class="field-body">gtkMenu</td>
</tr>
<tr class="field"><th class="field-name">m:</th><td class="field-body">gtkMenuItem</td>
</tr>
<tr class="field"><th class="field-name">O:</th><td class="field-body">gtkToolbar</td>
</tr>
<tr class="field"><th class="field-name">W:</th><td class="field-body">Window</td>
</tr>
<tr class="field"><th class="field-name">E:</th><td class="field-body">EventBox</td>
</tr>
<tr class="field"><th class="field-name">X:</th><td class="field-body">Expander</td>
</tr>
<tr class="field"><th class="field-name">p:</th><td class="field-body">ViewPort</td>
</tr>
<tr class="field"><th class="field-name">A:</th><td class="field-body">Alignment</td>
</tr>
</tbody>
</table>
</blockquote>
</td>
</tr>
</tbody>
</table>
</blockquote>
<p>Elements will be packed in a table widget unless changed by a option
when instantiating the class as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lay</span> <span class="o">=</span> <span class="n">Layout</span><span class="p">(</span><span class="n">lay</span><span class="p">,</span> <span class="n">opts</span><span class="o">=</span><span class="s">&quot;V=&quot;</span><span class="p">)</span>
</pre></div>
</div>
<dl class="last docutils">
<dt>Other values for opts are <tt class="docutils literal"><span class="pre">[&gt;=-|]</span></tt> - to be confirmed</dt>
<dd><table class="first last docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">=:</th><td class="field-body">implies that label and entry will be displayed one over the other (this
is the default)</td>
</tr>
<tr class="field"><th class="field-name">-:</th><td class="field-body">implies that label and entry will be displayed on the same line.</td>
</tr>
<tr class="field"><th class="field-name">|:</th><td class="field-body">will draw a line around the widgets, using a frame. That means a GtkFrame
and a GtkAlignment are silently created. You can set
properties of the silently created expander using key F.id</td>
</tr>
<tr class="field"><th class="field-name">&gt;:</th><td class="field-body">will encapsulate the result into an Expander that allows to
collapse all its content via a click on a little arrow. You can set
properties of the silently created expander using key X.id. A double
&#8216;&gt;&gt;&#8217; results in an expanded expander. The id is used as label for the
expander. so that &#8216;&gt;&gt;.clients&#8217;, will be expanded in an oped expander
with a label &#8220;clients&#8221;</td>
</tr>
</tbody>
</table>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<div class="section" id="a-longer-example">
<h2>a longer example<a class="headerlink" href="#a-longer-example" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><pre>el=first_name                  el=last_name
el=address                     -
{V r=man/sex      r=woman/sex}  b=register</pre>
</div>
</div>
<div class="section" id="comment">
<h2>Comment<a class="headerlink" href="#comment" title="Permalink to this headline">¶</a></h2>
<p>A &#8216;#&#8217; sign starts a comment. Anything till the end of the line will be
discarded, as usual...</p>
</div>
<div class="section" id="el-element">
<h2>el element<a class="headerlink" href="#el-element" title="Permalink to this headline">¶</a></h2>
<p>the most used element will probably turn out to be a Label + Entry widget
that can be constructed as in el=first name. It will really be understood
as:</p>
<div class="highlight-python"><pre>{ l=first_name el=first_name }</pre>
</div>
<p>or:</p>
<div class="highlight-python"><pre>{ l=first_name
  el=first_name }</pre>
</div>
<p>According to the opt modifier = or -</p>
<div class="section" id="list-of-elements">
<h3>list of elements<a class="headerlink" href="#list-of-elements" title="Permalink to this headline">¶</a></h3>
<p>A partial list of elements:</p>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">l:</th><td class="field-body">Label,</td>
</tr>
<tr class="field"><th class="field-name">L:</th><td class="field-body">EventLabel, a label in a GtkEventBox</td>
</tr>
<tr class="field"><th class="field-name">e:</th><td class="field-body">Entry,</td>
</tr>
<tr class="field"><th class="field-name">E:</th><td class="field-body">Event,</td>
</tr>
<tr class="field"><th class="field-name">b:</th><td class="field-body">Button,</td>
</tr>
<tr class="field"><th class="field-name">r:</th><td class="field-body">RadioButton,</td>
</tr>
<tr class="field"><th class="field-name">c:</th><td class="field-body">CheckButton,</td>
</tr>
<tr class="field"><th class="field-name">TV:</th><td class="field-body">TreeView,</td>
</tr>
<tr class="field"><th class="field-name">TX:</th><td class="field-body">TextView,</td>
</tr>
<tr class="field"><th class="field-name">TVS:</th><td class="field-body">ScrolledTreeView,</td>
</tr>
<tr class="field"><th class="field-name">TXS:</th><td class="field-body">ScrolledTextView,</td>
</tr>
<tr class="field"><th class="field-name">cal:</th><td class="field-body">Calendar,</td>
</tr>
<tr class="field"><th class="field-name">sb:</th><td class="field-body">Statusbar,</td>
</tr>
<tr class="field"><th class="field-name">le:</th><td class="field-body">ComboLE,</td>
</tr>
</tbody>
</table>
<p>more symbols are in the source...</p>
</blockquote>
</div>
</div>
<div class="section" id="custom-widgets">
<h2>custom  widgets<a class="headerlink" href="#custom-widgets" title="Permalink to this headline">¶</a></h2>
<p>Occasionally you will find yourself in nee for a custom identifier. You can
create one and register it. Have a look at the code in layoutgenerator
module.</p>
<div class="section" id="calling-layout">
<h3>Calling Layout<a class="headerlink" href="#calling-layout" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>def __init__(self, lay, level=0, parent_container="W", opts="T",
             elements={}, container_id='',title="Window",dbg=0):</pre>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">lay:</th><td class="field-body"><p class="first">the string describing the desired layout</p>
</td>
</tr>
<tr class="field"><th class="field-name">level:</th><td class="field-body"><p class="first">nested level (used only by layout itself)</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">parent_container:</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">a flag among the container flags that says which is the container: determines
the packing info for the result. Default is W (Window) as a toplevel
window. In this case info for a toplevel window is built.</p>
</td>
</tr>
<tr class="field"><th class="field-name">opts:</th><td class="field-body"><p class="first">This string has the same meaning of the modifier string of a container that
can be put directly after the &#8216;{&#8216; char.</p>
<p>Mainly this is a way to force the use of a container for the outer call of
layout. Default is to put all widgets in a GtkTable but any container can be
chosen from the container flags.</p>
<p>A special component of &#8216;opts&#8217;, is &#8216;s&#8217; that asks to add a StatusBar. The
method &#8216;sb&#8217; is provided to talk with that Statusbar whose key name is sb=StBar.</p>
</td>
</tr>
<tr class="field"><th class="field-name">addto:</th><td class="field-body"><p class="first last">follows the name of a container that will receive the resulting
layout. Must be a container that accept &#8216;add&#8217; method.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="methods">
<h2>methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h2>
<p>NOTE: some methods can only be called after &#8216;show&#8217; has being called. These
methods use gtk directly, not glade.</p>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">xml(file=None):</th><td class="field-body"><p class="first">will produce the xml needed for glade, may be write to file</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">show(action=function_name):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">will directly call glade to display the
GUI, returns a dict of Gtk objects whose keys are the element
<em>keys</em>. After this method there is no point in changing
elements[] properties. The action can be gtk.main.</p>
</td>
</tr>
<tr class="field"><th class="field-name">elements:</th><td class="field-body"><p class="first">a dict of all lwidgets. The keys are the element
definitions. Any element can be configure up to the moment show is called.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">conf(el,property):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">will set a property for an element of the layout  equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">elements</span><span class="p">[</span><span class="s">&#39;el_key&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="s">&#39;name&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
</pre></div>
</div>
</td>
</tr>
<tr class="field"><th class="field-name">sig(list):</th><td class="field-body"><p class="first">will set handlers for the signal for each widget. The list
is a list of tuples of 3 elements:</p>
<blockquote>
<ul class="simple">
<li>el_key</li>
<li>handler</li>
<li>signal. If the last is missing, clicked is used</li>
</ul>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">tip (el, text):</th><td class="field-body"><p class="first">a tooltip for the element &#8216;el&#8217;. It tip is called before
&#8216;show&#8217;, it will end up in xml+glade, otherwise it will call
gtkTooltip directly</p>
</td>
</tr>
<tr class="field"><th class="field-name">sb(text):</th><td class="field-body"><p class="first">will push text on the StatusBar</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">menu(&#8216;el_key&#8217;, (entry-name, handler, signal=activated), &#8216;i&#8217;), (), ():</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">Will add MenuItems (Stock ImageMenuItems if 4^ element is &#8216;i&#8217;)</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">notebook(&#8216;el_key&#8217;, [&#8216;label 1&#8217;, &#8216;label2&#8217;,...],position):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">Adds the label to tabs and allow to set the position (top,left,
right, bottom) for a GtkNotebook. There is another way to obtain
this effect. You can add %label as first entry in the block that
will be enclosed in the notebook. See below: notebook</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">frame(&#8216;el_key&#8217;, &#8216;label&#8217;):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">Adds a label to a frame, and writes it w/ bold face</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">prop(el_key,property_name, value):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first">Sets a property  for element el_key</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">pack(el_key,property_name, value):</th></tr>
<tr><td>&nbsp;</td><td class="field-body"><p class="first last">Sets a pack property for element el_key</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
<div class="section" id="element-names">
<span id="names"></span><h3>element names<a class="headerlink" href="#element-names" title="Permalink to this headline">¶</a></h3>
<p>For each element of the layout we need to build a key for xml, so that we
know how to refer to the gtk object in the program. Layout will build the
name starting from what was written in the element description, if that
results in being already used it builds a unique name adding a number, but that
may result in difficulty to interact with it from inside the program.</p>
<p>If that&#8217;s an issue try being clear when creating the layout. Use ids, the
string separated by a &#8216;.&#8217; that you can add to element names and to container
flags:</p>
<blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">container:</th><td class="field-body"><div class="first highlight-python"><pre>{H.Z   {B.id0</pre>
</div>
</td>
</tr>
<tr class="field"><th class="field-name">element names:</th><td class="field-body"><div class="first last highlight-python"><div class="highlight"><pre><span class="n">e</span><span class="o">=</span><span class="n">name</span><span class="o">.</span><span class="n">id1</span><span class="o">/</span><span class="n">string</span>
</pre></div>
</div>
</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>
<div class="section" id="stock-names">
<h2>stock names<a class="headerlink" href="#stock-names" title="Permalink to this headline">¶</a></h2>
<p>if the name of an element starts with &#8216;gtk-&#8216;, use-stock = True is set for
that element.</p>
</div>
<div class="section" id="notebook">
<h2>Notebook<a class="headerlink" href="#notebook" title="Permalink to this headline">¶</a></h2>
<p>A notebook need some labels to identify the tabs. These are other child of
the GtkNotebook container interspersed with the content of the
container. You can set them with the notebook method, or you can use a
symbol in the describing string using % trailer:</p>
<div class="highlight-python"><pre>{N.0  { %first_tab_RIGHT
      TXS=one }
    { %second_tab
      TXS=due
    }
}</pre>
</div>
<p>will be equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">l</span><span class="o">.</span><span class="n">notepad</span><span class="p">(</span><span class="s">&#39;N.0&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s">&#39;first tab&#39;</span><span class="p">,</span><span class="s">&#39;second tab&#39;</span><span class="p">],</span> <span class="s">&#39;right&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Please, note that you can enforce a position with a trailing _(LEFT|TOP|...)
to the first label. Note also that any underscore will be substituted w/ a
space.</p>
</div>
<div class="section" id="automatic-name-mechanism">
<h2>Automatic name mechanism<a class="headerlink" href="#automatic-name-mechanism" title="Permalink to this headline">¶</a></h2>
<p>A normal element definition is of the form:</p>
<div class="highlight-python"><pre>  key=string/variable:width.height


* the :width.width part is discarded
* the rest is used as key, *but*
* if no 'key=' part was explicitly used as in 'first_name' two will be
  created: e=string, l=string</pre>
</div>
</div>
<div class="section" id="container-naming">
<h2>container naming<a class="headerlink" href="#container-naming" title="Permalink to this headline">¶</a></h2>
<p>Containers need a name too. You are supposed to know which one is used: it
will be GtkTable unless you asked for a different one. You need it in case
you want to modify its properties.</p>
<p>Their name will be the container flag [THVbNPSvhpOBmMFA] possibly followed
by a dot . and an identifier. The identifier will be a progressive counter,
starting from 0 but may be imposed appending .id to the flags of the
container, as in:</p>
<div class="highlight-python"><pre>{V.my_id first_name last_name }</pre>
</div>
<div class="section" id="functions">
<h3>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">map_layouts(filename=None,</span> <span class="pre">buf=None)</span></tt></p>
<p>This functions fills in a dictionary widgets.info whose structure is:</p>
<blockquote>
name : (label, tip)</blockquote>
<p>when a widget is created w/ name &#8216;name&#8217; the label will be set to &#8216;label&#8217; and
a tooltip will be set to &#8216;tip&#8217;. This can help a lot in many situations. Db
field name will be mapped to user friendly labels, translation will be as
easy as pointing to a different file.</p>
<p>The function can point to a filename or can read a string. You can write
directly the info dictionary if you prefer...</p>
</div>
<div class="section" id="layout-class-implementation">
<h3>Layout class implementation<a class="headerlink" href="#layout-class-implementation" title="Permalink to this headline">¶</a></h3>
<p>Each layout live in a container (may be a toplevel Window) and creates a
container to house its children. This can cause a little bit of
confusion so I call parent_container the container in which a widget live and
container the Gtk container (Table, HBox, VBox...) where I house layout children.</p>
<p>You can think at your layout as divided in blocks, each one named &#8216;cell&#8217; in
the code. A cell is or the definition of a gtkObj or a nested layout.
You can see this list for debugging purposes with method _dbg_parse_layout.</p>
<p>You can think at these cells as displayed in a grid, each one defined by a
row and a column. The constructor of Layout uses a dict named &#8216;cells&#8217; with
indices (row,col) to store the name of the corresponding LWidget or
LContainer.</p>
<p>When the object is instantiated, Layout</p>
<blockquote>
<ol class="arabic simple">
<li>creates a container (LContainer object)</li>
<li>splits the layout description into tokens that are or
-a element descriptions
- nested layouts (starts w/ &#8216;{&#8216;)
...</li>
</ol>
</blockquote>
<p>For each token that describes a single element, creates the corresponding
lwidget object, for each nested layout creates another instance of Layout.</p>
</div>
</div>
<div class="section" id="lwidgets-and-lcontainer">
<h2>LWidgets and LContainer<a class="headerlink" href="#lwidgets-and-lcontainer" title="Permalink to this headline">¶</a></h2>
<p>the difference between an LWidget and an LContainer is that an LContainer has
children and must pack info for all the children when producing xml (apart
from producing the xml for itself)</p>
</div>
<div class="section" id="window-creation">
<h2>Window creation<a class="headerlink" href="#window-creation" title="Permalink to this headline">¶</a></h2>
<p>Each call to Layout must create a container to house all its children, but
the first (or outer) one needs normally to create also the TopLevel Window,
that to us is nothing than another LContainer whose (only) child is just
another container (the outer one for Layout).</p>
</div>
<div class="section" id="producing-xml">
<h2>Producing xml<a class="headerlink" href="#producing-xml" title="Permalink to this headline">¶</a></h2>
<p>Layout produces xml just asking to the toplevel (an LContainer object) to
produce xml.  LContainer xml, produces xml for itself and for its children,
if some of them is a container the process iterates.</p>
</div>
</div>


            </div>
        </div>
     </div>
   </div>

        
</div> <!-- wrap -->

            <div class="bottomnav footer">
                <div class="doc_copyright">
                Alessandro Dentella -- Copyright 2006-2007-2008-2009-2010
		  Sqlkit release 0.9.5
<!--                 % if hasdoc('copyright'): -->
<!--                     &copy; <a href="../copyright.html">Copyright</a> 2008, Sandro Dentella. -->
<!--                 % else: -->
<!--                     &copy; Copyright 2008, Sandro Dentella. -->
<!--                 % endif -->
                    creato usando  <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
                </div>
            </div>
        












<br style="clear: left" />

    </body>
</html>