Introduction

A lot of the current documentation for wxPython is actually the C++ based wxWidgets documentation, with Python-specific comments added where needed. This means that wxPython users have to be able to read C++ method and function definitions and translate them into their Python equivalents. For people with no C++ experience, this can be quite a daunting prospect. The aim of this guide is to help make that process easier.

How the Docs are Organised

Apart from the "wxPython Notes" and some articles under "Topic Overview" which you may find useful, the most important parts of the wxPython documentation, for the Python programmer, are:

This is the information which you'll need to refer to again and again as you're developing your wxPython apps. Unfortunately, though, these references are written for C++ programmers, so virtually all the method and function definitions are in C++ format, which makes it hard for a Python programmer to make sense of.

Translating from C++

Let's take a look at a typical entry in the Alphabetical class Reference. If you go to the entry for wxWindow, for example, you'll see that it is organised as follows:

This is followed by all the various "member function" (method) definitions.

Constructors and Destructors

Two special methods are defined for each class, and these always appear at the top of the list. Firstly, there is the "constructor" method, which corresponds to a class's __init__() method in Python -- this is the method which is called whenever a new object of that class is created. In C++, the constructor always has the same name as the class itself. Thus, for example, the constructor for the wxWindow class is called:

The destructor method, as you might guess, is called whenever an object of that class is no longer used and should be destroyed. Python has an equivalent method: __del__(), though unlike C++ this is rarely used so many Pythoneers may not be aware of it. In C++, the destructor is always given the name of the class, with a tilde ("~") character in front. Thus, the destructor for the wxWindow class is:

In general, wxPython programs never use or need to worry about the destructor methods, so you can safely ignore them.

Method Definitions

The method definitions are the most useful part of the wxWidgets documentation -- and unfortunately also the most difficult to understand if you aren't familiar with C++. Here, for example, is the constructor (_init_() method) for the wxWindow class:

This may look horrendous, but it's not too hard to interpret if you remember the following:

  1. Just like in Python, all the parameters are listed out from left to right with a comma separating each parameter. So, for example, to create a new wxWindow you might use a call like the following:

    • myWindow = wxWindow(parent, id, pos, size, style, name)

    When defining a method in Python, you simply list out the name of each parameter, and give each one a possible default value. Because C++ is a much more complex language, there's a lot more information supplied for each parameter -- but the basic principle of listing the parameters one after the other still applies. Of course, as well as having the parameters embedded in the method definition, the parameters are also listed out separately in the "Parameters" section. Often, if you can't be bothered reading through all the complex details, the list of parameters will probably tell you everything you need to know. They're certainly a good place to start!

  2. Because C++ is a "strongly typed" language, each parameter has a "type" associated with it. For example, in the wxWindow constructor, the "pos" parameter has a type of wxPoint (a wxPoint object). These type values can be a useful clue to figuring out type of information to pass to the method. In addition to the various types of objects defined by wxWidgets itself, here are some of the more common built-in C++ types you might encounter:

    • int

      An "integer" number.

      long

      A "long integer" number.

      float

      A floating-point number.

      bool

      A TRUE-or-FALSE value.

      wxString

      A wxWidgets-specific string (text) value.
  3. Just like in Python, many of the parameters are given a default value. You don't need to list out all the parameters with default values, and if you do you can use the keyword to identify which parameter you are entering. For example, you could create a new wxWindow object using the following:

    • myWindow = wxWindow(parent, id, style = wxSIMPLE_BORDER)

    Because default values are already supplied for the remaining parameters, you don't need to list them out unless you actually want to use them.
  4. There's a bunch of special characters and codes listed in the method definitions which aren't relevant to Python at all. These include:

    • A * after the parameter type.

    • The word const before a type.

    • An ampersand (&) after the type.

    The good news is that as a Python programmer you can simply ignore all this gobbledigook!

  5. Because many of the methods defined in wxWidgets return a value to the caller, C++ requires that you define the type of the method as well as the type of each parameter. Just like with parameters, the type of value returned by the method is listed just before the method name itself. For example, the wxWindows.getFont() method has the following definition:

    • wxFont& GetFont() const

    In this case, the GetFont() method is set up to return a wxFont object. As with the parameters, the return type listed for a method can be a useful clue as to what information the method will return. Just as with parameters, you'll encounter cryptic codes which are only relevant to C++. For example:

    • The word static before the method name.

    • The word const at the end of the method definition.

    • The word void before a method definition.

    • The word virtual before a method definition.

    The void code deserves a special mention: if a method is defined to return the special type void, it means that that method doesn't return a value at all. This is just like in Python; for example, the method: 

        def spam(self, x):
        return x * 21.7

    returns a value, while the method: 

        def eggs(self, x):
        self.variable = x

    does not. In C++, the spam() method would have a return type of float, while the eggs() method would have a return type of void since it doesn't return a value at all.

  6. Just like in Python, C++ objects "inherit" all of the methods defined by their parent class(es). So, for example, the wxFrame class is based on the wxWindow class, the wxEvtHandler class, and the wxObject class. This means that, even though the methods for wxWindow, wxEvtHandler, and wxObject aren't listed in the documentation for wxFrame, a wxFrame object can still call all these inherited methods. It's useful to keep this in mind, as you'll sometimes find that the method you want isn't defined in the class itself, but in one of the parent classes.

  7. There's one other complexity which you should be aware of: C++ has a feature called "method overloading". This allows the C++ programmer to define more than one version of the same method, where the different versions are distinguished by different sets of parameters. For example, the wxWindow.ConvertPixelsToDialog() method has two definitions:

    • wxPoint ConvertPixelsToDialog(const wxPoint& pt)

      wxSize ConvertPixelsToDialog(const wxSize& sz)

    Same method name, different parameters. Python doesn't need or use method overloading, so for wxPython you'll always find a note in the method definition giving the Python names for the different versions of the method. So, for example, the entry for the wxWindow.ConvertPixelsToDialog() method includes the following note:

    • wxPython note: In place of a single overloaded method name, wxPython implements the following methods:

      • ConvertDialogPointToPixels(point)

        Accepts and returns a wxPoint

        ConvertDialogSizeToPixels(size)

        Accepts and returns a wxSize

  8. Finally, whenever you're reading the method definitions, keep an eye out for those wxPython notes. The information in the wxPython notes always takes precedence over anything the main wxWidgets docs may say.

Summary

As long as you remember these guidelines, decyphering the C++ oriented wxWidgets documentation isn't actually all that hard. It just looks a lot more complicated than it really is, thanks to all the C++ specific complexity. It doesn't take long, though, before your brain starts to automatically filter out the C++ gobbledigook, and you'll be able to use the wxWidgets references almost as quickly as if it were written for Python rather than C++.

Happy Pythoning, and may all your GUIs be fast and friendly.

C++GuideForwxPythoneers (last edited 2010-07-29 16:04:18 by fl-67-235-186-192)

NOTE: To edit pages in this wiki you must be a member of the TrustedEditorsGroup.