File: tutorial.html

package info (click to toggle)
wxglade 0.6.5-2
links: PTS
area: main
in suites: wheezy
size: 3,348 kB
sloc: python: 24,679; xml: 1,022; makefile: 135; sh: 4
file content (530 lines) | stat: -rw-r--r-- 25,209 bytes
parent folder | download | duplicates (5)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
         
  <meta http-equiv="CONTENT-TYPE"
 content="text/html; charset=iso-8859-1" />
  <title>wxGlade tutorial</title>
                     
  <style type="text/css">
body { font-family: Arial, Helvetica, sans-serif }
  </style>
</head>
<body bgcolor="#ffffff" style="padding: 10px">

<h1>wxGlade Tutorial</h1>
    
<!-- CONTENT_START -->
  
<p>The aim of this minimal tutorial is to give an overview of wxGlade and its
functionalities: despite its very short length, it is (hopefully) complete
enough to make you understand how the application works, through a step-by-step
description of the creation of a frame containing a notebook with some
controls, a menubar and a statusbar.<br/>
 </p>
    
<p>Before we start, let me apologize for my English: it's not my native
language (I'm Italian), so it is very far from perfection.<br/>
 </p>
    
<h3>1. Creation of the frame</h3>
    
<p>To create a new frame, click on the appropriate button of the "palette"
(<img src="img/frame_button.gif" align="middle" width="31" height="31"
border="0" alt="" />): a dialog asking for the name of the class of the new
window is displayed: choose the name you prefer, but remember that it must be a
valid name for a Python (or C++) class.<br/>
 </p>
    
<p>Now the frame is displayed, and the properties window changes to show the
attributes of the widget just created. The first thing we'll do is change the
title of the frame, which is by default equal to the object's name, and insert
"Frame with notebook": the change takes effect when the <tt>Title</tt> property
loses focus.<br/>
 </p>
    
<h3>2. Creation of the menubar</h3>
    
<p>Let's activate the <tt>Widget</tt> tab of the properties notebook of our
frame, and check the property <tt>Has MenuBar</tt> to create a menu bar for the
frame.</p>
    
<p>The properties window changes again, and now it shows the properties of the
menubar: let's click on the <tt>Edit menus</tt> button to add some menus with
the Menu Editor.<br/>
 </p>
    
<p>Click on the button <tt>Add</tt> to add a menu, and then edit the
<tt>Label</tt> field to change its value to "File".<br/> Let's then add some
menu items to our File menu: click on the <tt>Add</tt> button again, change
<tt>Label</tt> to "New", and finally click the <tt>&gt;</tt> button: after the
latter action we can see that the label of our item ("New") is indented
compared to the previous one ("File"): this says that "New" is an item of
"File".<br/> Repeat the previous operations "ad libitum" to add other menus and
items (and sub-menus), then click <tt>OK</tt>: the window gets closed, and our
menubar contains the menus we added.<br/>
 </p>
    
<h3>3. Creation of the statusbar</h3>
    
<p>Under the <tt>Has MenuBar</tt> property of our frame there's the <tt>Has
StatusBar</tt> one: check it to add the statusbar.<br/>
 </p>
    
<p>The <tt>Fields</tt> property of the object just added keeps the fields to
display on the statubar: double-click on a field to edit it; to add, remove,
insert other fields use the appropriate buttons.<br/> Edit the default field, an
set its value to "Created with wxGlade!", then add some other fields with the
<tt>Add</tt> button: the <tt>Size</tt> column shows the dimension of each
field: you can change them as you like, but remember that one of the fields
must have a size of &nbsp;-1 (which tells that it will fill the remaining
space).<br/> After performing these operations, click on the <tt>Apply</tt>
button to reflect the changes on the widget.<br/>
 </p>
    
<h3>4. Creation of the notebook</h3>
    
<p>Now it's time to add a notebook to our frame. You should have noticed that
the frame you've just added contain a BoxSizer (<img
src="img/box_sizer_button.gif" align="middle" width="31" height="31" border="0"
alt="" />). This is because with wxGlade every container widget must have a
Sizer before you can add sub-widgets to it, and since it is very common for
frames to have just one child window, wxGlade adds an 1-slot BoxSizer
automatically for you. This doesn't happen for other containers, for which
you'll have to set their sizer manually, as will be explained below, after the
addition of the notebook to the frame.<br/></p>

<p>Let's add such notebook, then: to do so, click on the Notebook button (<img
 src="img/notebook_button.gif" align="middle" border="0" width="30" height="30"
 alt="" />) on the palette: now when you move the mouse inside the sizer's area
 (<img src="img/sizer_slot.gif" align="middle" border="0" width="30"
 height="30" alt="" />), the pointer changes its shape and becomes a cross:
 this tells us that we can drop the notebook on the sizer's only slot.<br/> A
 left-click starts the operation, and a dialog asking for the placement of the
 notebook's tabs appears: choose what you like best.</p>


<p>Now let's select the <tt>Common</tt> tab of the properties of the object
just added: we can see that the <tt>Class</tt> property's value is
<tt>wxNotebook</tt>, i.e.  the name of the class our object is an instance
of. If we change such value, we can make our notebook an instance of a custom
class derived from wxNotebook: this has no effect during the creation of the
app, but it changes the generated code, so that a definition for our custom
class will be written. Let's change then the value of <tt>Class</tt> to
<tt>MyNotebook</tt>, to make wxGlade generate the code for the custom
class.</p>

<p><b>NOTE:</b> The above is true only for "container" widgets, i.e. those that
can have children. For controls, instead, the meaning is slightly different;
let me illustrate it with an example.<br/>

<blockquote>Suppose you have a button inside a panel, its <tt>Class</tt> is
<tt>wxButton</tt>. If you change such value to <tt>MyCustomButton</tt>, wxGlade
assumes that you have a subclass of <tt>wxButton</tt> called
<tt>MyCustomButton</tt> defined somewhere, and that such class has a costructor
compatible with that of the "regular" <tt>wxButton</tt>, and so when it
generates the code for the object, it writes:
<pre>button_1 = MyCustomButton(parent, id, "Label")</pre> instead of
<pre>button_1 = wxButton(parent, id, "Label")</pre> </blockquote>

<p><b>NOTE 2:</b> For XRC output, if the value of <tt>Class</tt> is different
from the default one, the object will have a <tt>subclass</tt> attribute. For
the example above, the code generated would be: </p>
<blockquote> 
&lt;object class="wxButton" name="button_1" subclass="MyCustomButton"/&gt; 
</blockquote>
<p>This means that you should be a little careful with XRC output, in that you
have to remember to reset the <tt>Class</tt> value to the default one when
adding a "top-level" widget (frame, dialog,...), because by default wxGlade
assumes they are custom classes.
</p>
    
<h3>5. Adding and removing notebook pages</h3>
    
<p>This operation is almost identical to the handling of statusbar fields: the
<tt>Tabs</tt> property of our notebook controls the number of pages (tabs) and
their labels (don't forget to "Apply" the changes!).<br/>
 </p>
    
<h3>6. Addition of some controls</h3>
    
<p>We have now reached the last part of this short tutorial: the addition
of some controls to the first page of our notebook. In particular, we'll add
a text area and two buttons: these operations will allow us to show the layout
options of the objects inside sizers, and the cut &amp;
paste support of wxGlade. <br/>
 </p>
    
<p>As said before, the first thing to do in order to add widgets to a container
is to set its sizer.  Let's start with the addition of a sizer to the first
page of the notebook, which is where we are going to put our controls, then: to
do so, click on the BoxSizer button (<img src="img/box_sizer_button.gif"
align="middle" width="31" height="31" border="0" alt="" />) on the palette, and
then move the mouse inside the page. Again, the pointer is now a cross, and so
we can drop the sizer on our page: if everything is OK, you should see a dialog
asking for some features of the sizer to add. We have to change the default
values, since we want a 2-slots vertical box, so set to Vertical the
orientation and to 2 the number of slots. None of the two actions is mandatory,
since both the orientation (or better, the type) of the sizer and the number of
slots can be changed in any moment: the former by changing the value of the
<tt>Class</tt> property, the latter from the popup menu you can activate with a
right-click on the "handle" button of the sizer or on the corresponding node of
the tree of widgets. (As a side note, this same procedure can be used to show
the menu of almost every object handled by wxGlade).<br/></p>

<p><font size="4"><b>6.1 Text area</b></font></p>
    
<p>Let's click on the TextCtrl button (<img src="img/text_ctrl_button.gif"
 align="middle" width="30" height="30" alt="" />) and insert the text area in
 the first slot of our sizer. </p>
    
<p>The default dimension isn't right, as we want to display a long and
multiline text: to edit the layout, let's select the <tt>Layout</tt> tab of the
TextCtrl's properties, and set to 1 the value of <tt>Option</tt> and to
<tt>wxEXPAND</tt> that of <tt>Alignment</tt>.  To make the text area multiline,
let's check the
<tt>wxTE_MULTILINE</tt> checkbox of the <tt>Style</tt> property (in the
<tt>Widget</tt> tab): as with almost every <tt>Style</tt> property in wxGlade,
such change has no visible effect, but it changes the generated code.</p>
    
<p><b><font size="+1">6.2 Buttons</font></b><br/></p>
   
<p>Now replace the second slot with a horizontal Sizer which will contain our
two buttons: set the number of slots to 3, to leave room for a spacer to insert
between the two buttons (so as they won't appear too close to each other).<br/>
 </p>
 
<p>Replace then the first slot with a new button, as usually with the
approprate button (<img src="img/button_button.gif" align="middle" width="30"
height="30" alt="" />).<br/> To add the second button, instead, we will use the
clipboard: let's click on the <tt>Copy</tt> item of the popup menu of the first
button (or select it and press <tt>Ctrl+C</tt>), then move the mouse inside the
third slot, and finally click on the <tt>Paste</tt> item of the popup menu of
the slot to paste the copied widget (again, you can alternatively left-click on
the empty slot and then press <tt>Ctrl+V</tt>, or if you have a 3-buttons mouse
just click on the empty slot with the middle button).<br/>
 </p>

<p> Now add a spacer (<img src="img/spacer_button.gif" align="middle"
 width="30" height="30" alt="" />) of the appropriate dimension between the
 buttons, to keep them at a reasonable distance.<br/></p>
     
<p>Finally, the last operation we have to do is to edit the layout of the
horizontal Sizer that contains the buttons: set to 0 the value of "Option",
uncheck <tt>wxEXPAND</tt> from <tt>Aligment</tt> and check
<tt>wxALIGN_CENTER_HORIZONTAL</tt>, and set a border (<tt>4</tt>) on the top
(<tt>wxTOP</tt>) and bottom (<tt>wxBOTTOM</tt>), to keep the buttons separate
from the text area and the notebook lower border. <br/>
 </p>
 
<p><b>NOTE on widgets' ids: </b>You certainly know that every wxWindows widget
has an id, used among other things for event handling, so in wxGlade each
widget has an <tt>Id</tt> property. This may have the following values:<br/>
 </p>
 
<ul>
   
   <li><u>a number</u>: this will be the integer which will be passed to the
   constructor of the widget</li>

   <li><u>a name</u>: in this case wxGlade assumes it is the name of an id
   declared somewhere in the program, and uses it. For example, you can set the
   value of <tt>Id</tt> to <tt>wxID_OK</tt> for the default OK button of a
   dialog</li>
   
   <li><u>a pair name=value</u>: in this case before the constructor of the
   widget the declaration of the variable is generated. For example you could
   write <tt>TEST_BUTTON=wxNewId()</tt> to generate the id of a button called
   "Test" (note for C++ code generation: since ids are stored in an anonymous
   enum, only constant initializers are allowed, so the assigment above is not
   legal - but you can use, for instance, <tt>TEST_BUTTON=100</tt>) </li>

   <li><u>a pair name=?</u>: this special form means that the code will contain
   the definition of a varable "name" with an auto-assigned unique id. For
   python output, this is the same as "name=wxNewId()", while for C++ output,
   it's the equivalent of "name=1000" (of course, 1000 is just an example
   here). In this latter case, wxGlade will start generating ids exacly from
   1000, so you can safely use ids below that for your own purposes.</li>
 
</ul>
 
<p> </p>
    
<h3>7. Last changes</h3>

 Finally, suppose you are not happy with the current layout, and you decide
it's better to put the buttons above the text area and not below as they are:
so what can we do? Simple: let's change the value of the <tt>Pos</tt> property
of the sizer which contains the buttons, and set its value to <tt>0</tt>, to
move the sizer before the text area: easy, isn't it?  <br/> <br/> Now our
window is complete: all we have to do is set a reasonable initial size for
it. To do this, resize the frame until you find a good size, and then activate
the <tt>Size</tt> property.<br/>
    
<h3>8. Code generation</h3>

 Before we proceed with the code generation, let's save our work, selecting the
  <tt>Save As...</tt> item of the <tt>File</tt> menu of the main wxGlade
  window: this operation is not strictly necessary, but it's a good practice to
  not risk to loose the work, in particular until wxGlade will reach a certain
  maturity :-)<br/>
   
<p>Now we can go on with the code generation: select the <tt>Application</tt>
item on the tree of widgets (it is the root) to make the <tt>Application</tt>
tab appear on the properties window. This panel contains the options for the
code generation:<br/>
 </p>
    
<ul>
  <li><u>Name</u>: name to give to the wxApp object which represents the application:
if this property and the next one (Class) are not active, there will be no
code for the application startup, but only that of the various  widgets<br/>
 </li>
   <li><u>Class</u>: name of the class derived from wxApp which represents
the application: if this property is not active but the previous one (Name)
is, the application object will be an instance of wxPySimpleApp (this applies
to Python output only - for C++ output this property must be active if you
want the startup code to be generated)</li>
<li><u>Encoding</u>: encoding used to store the saved .wxg file (also for XRC);</li>
  <li><u>Enable gettext support</u>: if checked, all the strings in the generated sources will be wrapped by a "_()", ready for gettext;</li>
   <li><u>Top window</u>: main window of the application to generate<br/>
 </li>
   <li><u>Code generation</u>: this controls the kind of output, and lets
you choose between a single source file containing all the widgets, or a separate
file for each custom class defined (for C++ output, the single-file mode
actually generates two files, a ".h" and a ".cpp")<br/>
  </li>
 <li><u>Language</u>: this lets you choose the language of the generated code:
at the moment, Python, C++ and XRC, i.e. wxWindows resources xml format. Note
that in this last case some of the properties of the application are ignored
(Name, Class, Top window), and some are disallowed (you cannot set Code generation
to multi-files)<br/>
  </li>
  <li><u>Overwrite existing sources</u>: if checked, the code will be completely re-generated instead of updated (see the first note below for details);</li>
    <li><u>Output path</u>: in single-file mode, name of the output file;
in   multi-file mode, path to the output directory: in this last case, every
custom class will be placed in a file with the name of such class, except for
the (eventual) wxApp class, which is placed in a file whose name is given by
the Name property described above. For example, for our notebook, we'll have 
<tt>MyFrame.py</tt>, <tt>MyNotebook.py</tt> and <tt>app.py</tt> (assuming
you're generating Python code, of course).<br/>
  </li>
   <li><u>Generate code</u>: button which starts the code generation</li>
 
</ul>
    
<p>After the selection of the various options as described above, click on the
<tt>Generate code</tt> button: if everything is OK, after a while a message box
appears: this says that the operation is over... like this short tutorial
;-)<br/>
 </p>
  
<h3>9. Notes</h3>

<p>This section contains a list of things that you should know about wxGlade
(known bugs and/or limitations, "hidden" features, tips and tricks, ...) which
I wasn't able to fit in the tutorial <!-- (I am definitely a bad writer :) -->. The list
is loosely sorted by importance.
</p>

<ul>
  <li>When you generate Python or C++ code, if the output file already exists,
  wxGlade by default doesn't overwrite all its contents, but only the lines
  inside a 
  <pre>
  # begin wxGlade: ...
  # end wxGlade
  </pre>
  block. This is a desirable feature in most occasions,
  since it lets you add your code to the file without worrying of losing it
  when re-generating the GUI code, but there are situations in which a little
  attention is required. In particular, you should be aware of the following:
  <ul>
    <li>If the output file contains a class whose name is the same as that of
    one of your custom classes, but its body has no wxGlade block, the code for
    that class is not generated (a warning appears on the shell);</li>
    <li>If you rename one of your custom classes, you should rename also its
    code in the output file (and also all the occurrences of such name in the
    wxGlade tags), because wxGlade has no way of determining the previous name
    of such class, and will treat it like a brand new one (this means that it
    will generate a new class declaration instead of updating the old one). Let
    me explain this with an example:<br/>
    Suppose you have a class called <tt>MyFrame</tt>, and the corresponding
    generated file <tt>frame.py</tt>:<br/><pre>
#!/usr/bin/env python
# generated by wxGlade 0.2 on Sat Dec 14 15:15:06 2002

from wxPython.wx import *

class MyFrame(wxFrame):
    def __init__(self, *args, **kwds):
        # begin wxGlade: MyFrame.__init__
        kwds["style"] = wxDEFAULT_FRAME_STYLE
        wxFrame.__init__(self, *args, **kwds)

        self.__set_properties()
        self.__do_layout()
        # end wxGlade

    def __set_properties(self):
        # begin wxGlade: MyFrame.__set_properties
        self.SetTitle("frame_1")
        # end wxGlade

    def __do_layout(self):
        # begin wxGlade: MyFrame.__do_layout
        pass
        # end wxGlade

# end of class MyFrame
</pre>
   Now suppose you rename <tt>MyFrame</tt> to <tt>RenamedFrame</tt>. If you
   don't care to fix <tt>frame.py</tt> accordingly, if you re-generate it you
   will get something like:<br/><pre>
#!/usr/bin/env python
# generated by wxGlade 0.2 on Sat Dec 14 15:15:06 2002

from wxPython.wx import *

class RenamedFrame(wxFrame):
    def __init__(self, *args, **kwds):
        # begin wxGlade: RenamedFrame.__init__
        kwds["style"] = wxDEFAULT_FRAME_STYLE
        wxFrame.__init__(self, *args, **kwds)

        self.__set_properties()
        self.__do_layout()
        # end wxGlade

    def __set_properties(self):
        # begin wxGlade: RenamedFrame.__set_properties
        self.SetTitle("frame_1")
        # end wxGlade

    def __do_layout(self):
        # begin wxGlade: RenamedFrame.__do_layout
        pass
        # end wxGlade

# end of class RenamedFrame


class MyFrame(wxFrame):
    def __init__(self, *args, **kwds):
        # content of this block not found: did you rename this class?
        pass

    def __set_properties(self):
        # content of this block not found: did you rename this class?
        pass

    def __do_layout(self):
        # content of this block not found: did you rename this class?
        pass

# end of class MyFrame
</pre>
which is clearly not what you intended.<br/>&nbsp;</li>
    
<li>If you remove a custom class from the wxg file, wxGlade won't automatically
remove it from the source when it is re-generated (this does not apply if there
is no old version of such source), but it will try to update the parts inside
wxGlade blocks nonetheless: this means that:
<ul>
  <li>If you want to remove the class, you have to do it manually,</li>
  <li>If you want to keep the class as is, you have to remove the wxGlade tags.</li>
</ul>
  </ul>

  <p>As of version 0.3, it is possible to turn off this "update contents"
  feature, by checking the "Overwrite existing sources" property of the
  Application: if the property value is <tt>True</tt>, wxGlade will always
  re-generate the code from scratch (performing the appropriate backups,
  according to the preferences you can set from
  <tt>View->Preferences->Other</tt>).</p></li>

  <li>When you add new custom classes to an app, if there is a previous version
  of the generated code, the definitions of the new classes will be inserted
  *before* the old ones: this usually is not a problem, but for C++ output
  there could be occasions in which the generated code won't compile "out of
  the box", but you'll have to perform some manual adjustments (e.g. add some
  forward declarations before the new classes).
  <br/>&nbsp;</li>

  <li>When you add slots to sizers, it may be possible that you don't see
  such new slots: this happens because the size of the window that contains the
  sizer is too small, and so new slots are hidden. The solution is to resize
  the window, so that its layout is recalculated and the new slots are shown.
  <br/>&nbsp;</li>

  <li>XRC code generation has some differences wrt Python or C++; apart from
    those already mentioned in section 8, the most important ones are:
  <ul>
<!--
    <li>At the moment there is no support for custom classes, which means that
    the Class property of widgets is ignored. There's a chance that future
    versions of wxGlade will support it, though, since XRC itself has something
    similar (but it seems that at the moment it can be used only by C++
    progs).</li>
-->
    <li>Some widgets are not supported at all (e.g. status
    bar and grid): for them no code will be generated, but instead the XRC output
    file will contain a comment like this:
    <pre>&lt;!-- code generator for wxStatusBar objects not available --&gt;
    </pre></li>
    <li>Output files are always overwritten, so if you manually edit the XRC
    file, all the changes you made will be lost when you re-generate it.</li>
  </ul><br/>&nbsp;

  <li>Starting from version 0.2, there's a special component called
  <tt>CustomWidget</tt> (<img src="img/custom_widget.gif" align="middle"
  border="0" alt="" />). This is different from the others because it can be
  used to include in a wxg file any widget, even if it is not directly
  supported by wxGlade. The key feature for this is the Arguments property,
  which has two different meanings: for Python or C++ output, it lets you
  define the constructor parameters for the object. In this case it has two
  special parameters, <tt>$parent</tt> and <tt>$id</tt>, which as you can guess
  by their names are placeholders for the actual parent and id of the
  object. For XRC output, instead, it lets you specify additional properties of
  the object. In this case each entry should be in the form
  <blockquote><tt>name: value</tt></blockquote> (invalid entries will be
  silently ignored): for each of these lines, the output will contain a
  <blockquote><tt>&lt;name&gt;value&lt;/name&gt;</tt></blockquote> property of
  the XRC object.<br/>&nbsp;</li>

  <li>Starting from version 0.2, there's a script called <tt>xrc2wxg.py</tt>
  shipped with wxGlade. You can use this script to convert an XRC file to
  a wxGlade resource, so that you can edit it with wxGlade itself. Its usage is
  straightforward: 
  <pre>python xrc2wxg.py xrc_file.xrc wxg_file.wxg</pre>
  (if <tt>wxg_file.wxg</tt> is omitted, it defaults to <tt>xrc_file.wxg</tt>),
  but there are some limitations you should be aware of:
  <ul>
    <li>First of all, it can handle correctly only "wxGlade-friendly" XRC
    files. This basically means that all windows but the toplevel ones must be
    inside a sizer (but there are other cases).</li>
    <li>All the widgets unknown to wxGlade will be replaced by the special
    <tt>CustomWidget</tt> component.</li>
    <li>Finally, <tt>xrc2wxg</tt> is very experimental, and so it probably
    contains many bugs. If you find one of them, please report it (this is
    valid for wxGlade in general, BTW).<br/>&nbsp;</li>
  </ul></li>

  <li>You can invoke code generation also from the command line, without
  starting the GUI. For the details, type
  <pre>python wxglade.py -h</pre> at your shell's prompt.</li>
</ul>    
  
<p>I hope the contents are clear (and my English not too ridicule ;-), anyway
  for questions, comments, critics you can reach me by e-mail at <tt>
    &lt;agriggio at users dot sourceforge dot net&gt;</tt>.<br/></p>
     
<p>Alberto Griggio<br/></p>

<!-- CONTENT_END -->

  <br/>
   <br/>
<br/>
</body>
</html>