<!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>Window Layout — Envisage Documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '4.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/et.ico"/>
<link rel="top" title="Envisage Documentation" href="../index.html" />
<link rel="up" title="Tasks User Manual" href="index.html" />
<link rel="next" title="Menus and Tool Bars" href="menus.html" />
<link rel="prev" title="Introduction" href="intro.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="menus.html" title="Menus and Tool Bars"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Envisage Documentation</a> »</li>
<li><a href="index.html" accesskey="U">Tasks User Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="window-layout">
<span id="layout"></span><h1>Window Layout<a class="headerlink" href="#window-layout" title="Permalink to this headline">¶</a></h1>
<p>First and foremost, the Tasks plugin is designed to facilitate the layout of
modern, customizable user interfaces. Accordingly, we shall begin by learning
how to use Tasks to perform basic window layout.</p>
<div class="section" id="lifecycle-of-a-task">
<span id="index-0"></span><h2>Lifecycle of a Task<a class="headerlink" href="#lifecycle-of-a-task" title="Permalink to this headline">¶</a></h2>
<p id="index-1">The Tasks plugin adheres to the model-view-controller (MVC) design pattern <a class="footnote-reference" href="#id4" id="id1">[1]</a>,
for which the <tt class="docutils literal"><span class="pre">Task</span></tt> class functions as the controller and the <tt class="docutils literal"><span class="pre">TaskWindow</span></tt>
class as the view, with the model being application-specific <a class="footnote-reference" href="#id5" id="id2">[2]</a>. Insofar as a
<tt class="docutils literal"><span class="pre">Task</span></tt> is a controller, it does not itself instantiate or contain any GUI
controls, although it does provide factories and a default layout for the
controls that it manages. Controls are instantiated when a <tt class="docutils literal"><span class="pre">Task</span></tt> is assigned
to a <tt class="docutils literal"><span class="pre">TaskWindow</span></tt>. Specifically, the following actions are taken at this time:</p>
<ol class="arabic simple">
<li>The task’s central pane is constructed and attached to the window</li>
<li>All of the task’s dock panes are constructed, even if they are not by default
visible</li>
<li>The visible dock panes are laid out around the central pane according to the
task’s default layout or persisted UI state information</li>
</ol>
<p>While the <tt class="docutils literal"><span class="pre">Task</span></tt> remains connected to the <tt class="docutils literal"><span class="pre">TaskWindow</span></tt>, neither its central
pane nor its dock panes will be destroyed. If the user “closes” a dock pane, the
pane will be merely hidden, and can be re-activated via the application’s View
menu. Only when the <tt class="docutils literal"><span class="pre">Task</span></tt> itself is closed—that is, when it is removed from
the <tt class="docutils literal"><span class="pre">TaskWindow</span></tt>—will its panes be destroyed. This marks the end of the
<tt class="docutils literal"><span class="pre">Task</span></tt>‘s lifecycle. If the task is to be re-used, a new instance should be
constructed.</p>
</div>
<div class="section" id="defining-a-task">
<span id="index-2"></span><h2>Defining a Task<a class="headerlink" href="#defining-a-task" title="Permalink to this headline">¶</a></h2>
<p>Minimally, a task is defined by subclassing <tt class="docutils literal"><span class="pre">Task</span></tt> and providing a central
pane. For example, we define a task for editing Python scripts <a class="footnote-reference" href="#id6" id="id3">[3]</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pyface.tasks.api</span> <span class="kn">import</span> <span class="n">Task</span>
<span class="k">class</span> <span class="nc">ExampleTask</span><span class="p">(</span><span class="n">Task</span><span class="p">):</span>
<span class="nb">id</span> <span class="o">=</span> <span class="s">'example.example_task'</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">'Python Script Editor'</span>
<span class="k">def</span> <span class="nf">create_central_pane</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="n">PythonEditorPane</span><span class="p">()</span>
</pre></div>
</div>
<p id="index-3">The <tt class="docutils literal"><span class="pre">id</span></tt> attribute is a unique internal identifier for the task, whereas
<tt class="docutils literal"><span class="pre">name</span></tt> is a user-visible descriptor for the task. We shall see that this is a
common pattern in the Tasks framework.</p>
<p id="index-4">All tasks must implement <tt class="docutils literal"><span class="pre">create_central_pane()</span></tt> and return a TaskPane
instance. We might define the <tt class="docutils literal"><span class="pre">PythonEditorPane</span></tt> pane above as follows, making
use of the <tt class="docutils literal"><span class="pre">PythonEditor</span></tt> available in PyFace:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pyface.api</span> <span class="kn">import</span> <span class="n">PythonEditor</span>
<span class="kn">from</span> <span class="nn">pyface.tasks.api</span> <span class="kn">import</span> <span class="n">TaskPane</span>
<span class="kn">from</span> <span class="nn">traits.api</span> <span class="kn">import</span> <span class="n">Instance</span>
<span class="k">class</span> <span class="nc">PythonEditorPane</span><span class="p">(</span><span class="n">TaskPane</span><span class="p">):</span>
<span class="nb">id</span> <span class="o">=</span> <span class="s">'example.python_editor_pane'</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">'Python Editor'</span>
<span class="n">editor</span> <span class="o">=</span> <span class="n">Instance</span><span class="p">(</span><span class="n">PythonEditor</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">create</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">editor</span> <span class="o">=</span> <span class="n">PythonEditor</span><span class="p">(</span><span class="n">parent</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">control</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">editor</span><span class="o">.</span><span class="n">control</span>
<span class="k">def</span> <span class="nf">destroy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">editor</span><span class="o">.</span><span class="n">destroy</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">control</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">editor</span> <span class="o">=</span> <span class="bp">None</span>
</pre></div>
</div>
<p>Besides providing an ID and a name for the pane, we implement the two basic
methods of <tt class="docutils literal"><span class="pre">TaskPane</span></tt>, namely <tt class="docutils literal"><span class="pre">create(parent)</span></tt> and <tt class="docutils literal"><span class="pre">destroy()</span></tt>. The former
constructs a toolkit-specific control for the pane and assigns its to the pane’s
<tt class="docutils literal"><span class="pre">control</span></tt> attribute. The latter performs the inverse operation, destroying the
control and clearing <tt class="docutils literal"><span class="pre">control</span></tt> attribute. These methods give one full control
over how a pane is constructed, but as we shall see below there are other, more
convenient methods for defining a pane.</p>
</div>
<div class="section" id="defining-a-dock-pane">
<span id="index-5"></span><h2>Defining a Dock Pane<a class="headerlink" href="#defining-a-dock-pane" title="Permalink to this headline">¶</a></h2>
<p>Now we imagine that we are building a very primitive Python IDE and that we
would like to add a dock pane for browsing the local filesystem. We could create
a <tt class="docutils literal"><span class="pre">DockPane</span></tt> subclass similarly to the <tt class="docutils literal"><span class="pre">TaskPane</span></tt> above, implementing the
<tt class="docutils literal"><span class="pre">create_contents(parent)</span></tt> method of <tt class="docutils literal"><span class="pre">DockPane</span></tt> to provide the
toolkit-specific control for the file browser. But if we are familiar with
Traits UI we see that it would be more convenient to use the Traits UI
<tt class="docutils literal"><span class="pre">FileEditor</span></tt> for this purpose. The Tasks framework provides the
<tt class="docutils literal"><span class="pre">TraitsDockPane</span></tt> class to facilitate this. We define the pane as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pyface.tasks.api</span> <span class="kn">import</span> <span class="n">TraitsDockPane</span>
<span class="kn">from</span> <span class="nn">traits.api</span> <span class="kn">import</span> <span class="n">Event</span><span class="p">,</span> <span class="n">File</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Str</span>
<span class="kn">from</span> <span class="nn">traitsui.api</span> <span class="kn">import</span> <span class="n">View</span><span class="p">,</span> <span class="n">Item</span><span class="p">,</span> <span class="n">FileEditor</span>
<span class="k">class</span> <span class="nc">FileBrowserPane</span><span class="p">(</span><span class="n">TraitsDockPane</span><span class="p">):</span>
<span class="c">#### TaskPane interface ###############################################</span>
<span class="nb">id</span> <span class="o">=</span> <span class="s">'example.file_browser_pane'</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">'File Browser'</span>
<span class="c">#### FileBrowserPane interface ########################################</span>
<span class="c"># Fired when a file is double-clicked.</span>
<span class="n">activated</span> <span class="o">=</span> <span class="n">Event</span>
<span class="c"># The list of wildcard filters for filenames.</span>
<span class="n">filters</span> <span class="o">=</span> <span class="n">List</span><span class="p">(</span><span class="n">Str</span><span class="p">)</span>
<span class="c"># The currently selected file.</span>
<span class="n">selected_file</span> <span class="o">=</span> <span class="n">File</span>
<span class="c"># The view used to construct the dock pane's widget.</span>
<span class="n">view</span> <span class="o">=</span> <span class="n">View</span><span class="p">(</span><span class="n">Item</span><span class="p">(</span><span class="s">'selected_file'</span><span class="p">,</span>
<span class="n">editor</span><span class="o">=</span><span class="n">FileEditor</span><span class="p">(</span><span class="n">dclick_name</span><span class="o">=</span><span class="s">'activated'</span><span class="p">,</span>
<span class="n">filter_name</span><span class="o">=</span><span class="s">'filters'</span><span class="p">),</span>
<span class="n">style</span><span class="o">=</span><span class="s">'custom'</span><span class="p">,</span>
<span class="n">show_label</span><span class="o">=</span><span class="bp">False</span><span class="p">),</span>
<span class="n">resizable</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<p>When a control is needed for the pane, it will be constructed using the standard
Traits UI mechanisms. There exist additional options, not described here, for
specifying a model object, which is often important when building a complex
application. There is also a <tt class="docutils literal"><span class="pre">TraitsTaskPane</span></tt> class that provides similar
functionality for defining Traits-based central panes. As always, the reader is
referred to the Tasks API documentation for more information.</p>
<p>Now let us amend the example task defined above with a <tt class="docutils literal"><span class="pre">create_dock_panes()</span></tt>
method. This method returns the list of dock pane instances associated with the
task. We also define a method on our task for opening a file in the editor,
which we connect to the dock pane’s <tt class="docutils literal"><span class="pre">activated</span></tt> event:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ExampleTask</span><span class="p">(</span><span class="n">Task</span><span class="p">):</span>
<span class="p">[</span> <span class="o">...</span> <span class="p">]</span>
<span class="k">def</span> <span class="nf">create_dock_panes</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">""" Create the file browser and connect to its double click event.</span>
<span class="sd"> """</span>
<span class="n">browser</span> <span class="o">=</span> <span class="n">PythonScriptBrowserPane</span><span class="p">()</span>
<span class="n">handler</span> <span class="o">=</span> <span class="k">lambda</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="n">browser</span><span class="o">.</span><span class="n">selected_file</span><span class="p">)</span>
<span class="n">browser</span><span class="o">.</span><span class="n">on_trait_change</span><span class="p">(</span><span class="n">handler</span><span class="p">,</span> <span class="s">'activated'</span><span class="p">)</span>
<span class="k">return</span> <span class="p">[</span> <span class="n">browser</span> <span class="p">]</span>
<span class="k">def</span> <span class="nf">open_file</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
<span class="sd">""" Open the file with the specified path in the central pane.</span>
<span class="sd"> """</span>
<span class="bp">self</span><span class="o">.</span><span class="n">window</span><span class="o">.</span><span class="n">central_pane</span><span class="o">.</span><span class="n">editor</span><span class="o">.</span><span class="n">path</span> <span class="o">=</span> <span class="n">filename</span>
</pre></div>
</div>
</div>
<div class="section" id="providing-a-default-layout">
<span id="index-6"></span><h2>Providing a Default Layout<a class="headerlink" href="#providing-a-default-layout" title="Permalink to this headline">¶</a></h2>
<p>Although dock panes are designed to be moved around and otherwise manipulated by
the user, we often have a particular default layout in mind when designing an
application. The Tasks framework provides the <tt class="docutils literal"><span class="pre">TaskLayout</span></tt> class to make the
specification of this layout possible. Usually, we are only concerned with four
attributes of this class, namely <tt class="docutils literal"><span class="pre">left</span></tt>, <tt class="docutils literal"><span class="pre">right</span></tt>, <tt class="docutils literal"><span class="pre">bottom</span></tt>, and
<tt class="docutils literal"><span class="pre">top</span></tt>. Each of these attributes may be assigned a layout item, which is
either a <tt class="docutils literal"><span class="pre">PaneItem</span></tt>, for specifying a particular dock pane; a <tt class="docutils literal"><span class="pre">Tabbed</span></tt> item,
containing other <tt class="docutils literal"><span class="pre">PaneItem</span></tt> instances; or a <tt class="docutils literal"><span class="pre">Splitter</span></tt>, containing arbitrary
subitems.</p>
<p>A few examples should suffice to make this clear. To stack the dock pane with ID
‘dock_pane_1’ on top of that with ID ‘dock_pane_2’, with both to the left of the
central pane, one specifies:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">left</span> <span class="o">=</span> <span class="n">Splitter</span><span class="p">(</span><span class="n">PaneItem</span><span class="p">(</span><span class="s">'dock_pane_1'</span><span class="p">),</span>
<span class="n">PaneItem</span><span class="p">(</span><span class="s">'dock_pane_2'</span><span class="p">),</span>
<span class="n">orientation</span><span class="o">=</span><span class="s">'vertical'</span><span class="p">)</span>
</pre></div>
</div>
<p id="index-7">We could also have used <tt class="docutils literal"><span class="pre">VSplitter</span></tt>, which is a convenient abbreviation for a
splitter with vertical orientation. Similarly, <tt class="docutils literal"><span class="pre">HSplitter</span></tt> is an abbrevation
for a splitter with horizontal orientation.</p>
<p>To put these dock panes in tab group below the central pane, we might write:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">bottom_panes</span> <span class="o">=</span> <span class="n">Tabbed</span><span class="p">(</span><span class="n">PaneItem</span><span class="p">(</span><span class="s">'dock_pane_1'</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">400</span><span class="p">),</span>
<span class="n">PaneItem</span><span class="p">(</span><span class="s">'dock_pane_2'</span><span class="p">))</span>
</pre></div>
</div>
<p>Observe that we have explicitly provided a height for the first dock
pane. Provided that the dock pane’s underlying control does not have a
conflicting minimum or maximum size constraint, Tasks guarantees that it will
honor this height exactly. Of course, if <tt class="docutils literal"><span class="pre">width</span></tt> or <tt class="docutils literal"><span class="pre">height</span></tt> are not
provided, Tasks will use the dock pane’s toolkit-specific size hint to
determine its size.</p>
<p>Now we will provide our example task with a simple layout using the
<tt class="docutils literal"><span class="pre">default_layout</span></tt> attribute of <tt class="docutils literal"><span class="pre">Task</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ExampleTask</span><span class="p">(</span><span class="n">Task</span><span class="p">):</span>
<span class="p">[</span> <span class="o">...</span> <span class="p">]</span>
<span class="n">default_layout</span> <span class="o">=</span> <span class="n">TaskLayout</span><span class="p">(</span>
<span class="n">left</span><span class="o">=</span><span class="n">PaneItem</span><span class="p">(</span><span class="s">'example.python_script_browser_pane'</span><span class="p">))</span>
</pre></div>
</div>
<p>Note that dock panes that do not appear in the layout will not be visible by
default. A task without a default layout is equivalent to a task with an empty
layout; in both cases, only the central pane will be visible by
default. Finally, note that the layout behavior is undefined if a dock pane
appears multiple times in a layout.</p>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>For more information about the MVC pattern as used in ETS, the reader is
referred to the <a class="reference external" href="http://enthought.github.com/traits/TUIUG/intro.html">Introduction</a> of the Traits UI
User Guide.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Throughout this document, “<tt class="docutils literal"><span class="pre">Task</span></tt>” will refer to the class of that name
in the Tasks API, while “task” will be reserved for the general UI
concept, and similarly for other terms.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>In this and the subsequent section, we will be referencing (often in
abbreviated form) the Tasks example code in the TraitsGUI package,
available <a class="reference external" href="https://github.com/enthought/traitsgui/tree/master/examples/tasks">online</a> and
in the ETS distribution.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/e-logo-rev.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Window Layout</a><ul>
<li><a class="reference internal" href="#lifecycle-of-a-task">Lifecycle of a Task</a></li>
<li><a class="reference internal" href="#defining-a-task">Defining a Task</a></li>
<li><a class="reference internal" href="#defining-a-dock-pane">Defining a Dock Pane</a></li>
<li><a class="reference internal" href="#providing-a-default-layout">Providing a Default Layout</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="intro.html"
title="previous chapter">Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="menus.html"
title="next chapter">Menus and Tool Bars</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/tasks_user_manual/layout.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<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>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="menus.html" title="Menus and Tool Bars"
>next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
>previous</a> |</li>
<li><a href="../index.html">Envisage Documentation</a> »</li>
<li><a href="index.html" >Tasks User Manual</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008-2011, Enthought.
Last updated on May 14, 2013.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
c66175b08690d24bca431460aac64d89
>
files
>
275
