Chapter 7. wxGlade technical notes

This is an informal overview of wxGlade internals, made through a sample session of use. Each action of the hypothetical user will be described from the point of view of the application, to (hopefully) understand what's happening behind the scenes.

These notes are absolutely incomplete and in some cases they might be outdated or not completely correct: the best reference is always the source code.

Installing and Designing own Widget Plugins

wxGlade supports a simple plugin system for widgets to load all widgets at the application startup dynamically. The plugin system loads all built-in widgets like Static Text widget or the Gauge widget. It also loads widgets installed by users.

Widgets Packages

The wxGlade plugin system supports two different types of widget packages:

  1. directory package - a single directory with all necessary files inside

  2. ZIP package - a zipped version of a "directory" package

Example 7.1. Directory package

static_text          <- Directory named after the widget name
|-- __init__.py      <- Mostly an empty file or a file with just a comment
|-- codegen.py       <- Python and C++ code generators
|-- wconfig.py       <- Widget configuration
|-- lisp_codegen.py  <- Lisp code generator
|-- perl_codegen.py  <- Perl code generator
`-- static_text.py   <- wxGlade GUI code

Example 7.2. ZIP package

# unzip -l static_text.zip 
Archive:  static_text.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  2013-12-09 10:02   static_text/
      329  2013-12-09 10:02   static_text/__init__.py
     3352  2013-12-09 10:02   static_text/codegen.py
      320  2013-12-09 10:02   static_text/wconfig.py
     1640  2013-12-09 10:02   static_text/lisp_codegen.py
     1841  2013-12-09 10:02   static_text/perl_codegen.py
     5917  2013-12-09 10:02   static_text/static_text.py
---------                     -------
    13079                     6 files

Create a ZIP Package

Creating a ZIP package is quite simple. Just create a ZIP package from widgets directory with all Python and additional files. Don't include Python bytecode files because they are not platform independent.

# tree static_text/
static_text/
|-- __init__.py
|-- codegen.py
|-- wconfig.py
|-- lisp_codegen.py
|-- perl_codegen.py
`-- static_text.py

# zip -r static_text.zip static_text 
  adding: static_text/ (stored 0%)
  adding: static_text/__init__.py (deflated 36%)
  adding: static_text/codegen.py (deflated 67%)
  adding: static_text/wconfig.py (deflated 64%)
  adding: static_text/lisp_codegen.py (deflated 54%)
  adding: static_text/perl_codegen.py (deflated 56%)
  adding: static_text/static_text.py (deflated 69%)

Check the integrity of the created ZIP archive:

# zip -T static_text.zip 
test of static_text.zip OK

Installing Widget Plugins Locally

The installation of local plugins is a two-step process:

  1. Place the widget package in the Local widget path (see the section called “Preferences Dialog”). Create this directory if it doesn't exist.

  2. Add widget name to the text file named widgets.txt. This file is also located in the directory specified in Local widget path. Just create a simple text file, if the file doesn't exists.

The new widget will be available after wxGlade has been restarted.

Designing own Widget Plugins

Note

This section is under construction! Please use this information carefully.

  1. Create a new directory named like the widget and change in this directory

  2. Place an empty file __init__.py in that directory

  3. Create a file wconfig.py in the widget directory and describe the styles used by this widget

    """\
    wxStaticLine widget configuration
    
    @copyright: <Add year and your name>
    @license: <Choice a license>
    """
    
    config = {
        'wxklass': 'myCtrl',
        'style_defs': {
            'wxMCFance': {
                'desc': _('Use the new and fancy design.'),
            },
            'wxMCOldFashion': {
                'desc': _('Use the old fashion design.'),
            },
        },
        'box_label': _('Style'),
        'default_style': 'wxMCFance',
        'style_list': ['wxMCFance', 'wxMCOldFashion']
    }
  4. Create a Python file codegen.py with initial content like

    """
    Code generator functions for myCtrl objects
    
    @copyright: <Add year and your name>
    @license: <Choice a license>
    """
    
    import common
    
    
    class PythonMyCtrlGenerator(wcodegen.PythonWidgetCodeWriter):
    
        tmpl = '%(name)s = %(klass)s(%(parent)s, %(id)s, %(label)s%(style)s)\n'
    
    # end of class PythonMyCtrlGenerator
    
    
    def initialize():
        common.class_names['EditmyCtrl'] = 'myCtrl'
    
        pygen = common.code_writers.get("python")
        if pygen:
            pygen.add_widget_handler('myCtrl', PythonMyCtrlGenerator())
  5. Create a Python file named like the widget directory e.g. myctrl.py

  6. Create remaining code generators

  7. Example of the created structure

    myctrl
    |-- __init__.py
    |-- codegen.py
    |-- myctrl.py
    `-- wconfig.py

Widget Initialisation

Note

This section is incomplete.

  1. Load generic and language independent widget configuration from wconfig.py (common.load_config())

  2. Load and initialise language code writers (common.load_code_writers())

  3. Load and initialise widgets (common.load_widgets())

  4. Load and initialise sizers (common.load_sizers() )