431839ac8e
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@28633 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
800 lines
40 KiB
HTML
800 lines
40 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1" ?>
|
||
<!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" xml:lang="en" lang="en">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
||
<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
|
||
<title>wxPython 2.5 Migration Guide</title>
|
||
<link rel="stylesheet" href="default.css" type="text/css" />
|
||
</head>
|
||
<body>
|
||
<div class="document" id="wxpython-2-5-migration-guide">
|
||
<h1 class="title">wxPython 2.5 Migration Guide</h1>
|
||
<p>This document will help explain some of the major changes in wxPython
|
||
2.5 since the 2.4 series and let you know what you need to do to adapt
|
||
your programs to those changes. Be sure to also check in the <a class="reference" href="CHANGES.html">CHANGES</a>
|
||
file like usual to see info about the not so major changes and other
|
||
things that have been added to wxPython.</p>
|
||
<div class="section" id="wxname-change">
|
||
<h1><a name="wxname-change">wxName Change</a></h1>
|
||
<p>The <strong>wxWindows</strong> project and library is now known as
|
||
<strong>wxWidgets</strong>. Please see <a class="reference" href="http://www.wxwidgets.org/name.htm">here</a> for more details.</p>
|
||
<p>This won't really affect wxPython all that much, other than the fact
|
||
that the wxwindows.org domain name has changed to wxwidgets.org,
|
||
so mail list, CVS, and etc. addresses have also changed. We're going
|
||
to try and smooth the transition as much as possible, but I wanted you
|
||
all to be aware of this change if you run into any issues.</p>
|
||
</div>
|
||
<div class="section" id="module-initialization">
|
||
<h1><a name="module-initialization">Module Initialization</a></h1>
|
||
<p>The import-startup-bootstrap process employed by wxPython was changed
|
||
such that wxWidgets and the underlying gui toolkit are <strong>not</strong>
|
||
initialized until the wx.App object is created (but before wx.App.OnInit
|
||
is called.) This was required because of some changes that were made
|
||
to the C++ wxApp class.</p>
|
||
<p>There are both benefits and potential problems with this change. The
|
||
benefits are that you can import wxPython without requiring access to
|
||
a GUI (for checking version numbers, etc.) and that in a
|
||
multi-threaded environment the thread that creates the app object will
|
||
now be the GUI thread instead of the one that imports wxPython. Some
|
||
potential problems are that the C++ side of the "stock-objects"
|
||
(wx.BLUE_PEN, wx.TheColourDatabase, etc.) are not initialized until
|
||
the wx.App object is created, so you should not use them until after
|
||
you have created your wx.App object. If you do then an exception will
|
||
be raised telling you that the C++ object has not been initialized
|
||
yet.</p>
|
||
<p>Also, you will probably not be able to do any kind of GUI or bitmap
|
||
operation unless you first have created an app object, (even on
|
||
Windows where most anything was possible before.)</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> All the Window and GDI (pen, bitmap, etc.)
|
||
class constructors and also many toplevel functions and static methods
|
||
will now check that a wx.App object has already been created and will
|
||
raise a wx.PyNoAppError exception if not.</p>
|
||
</div>
|
||
<div class="section" id="swig-1-3">
|
||
<h1><a name="swig-1-3">SWIG 1.3</a></h1>
|
||
<p>wxPython is now using SWIG 1.3.x from CVS (with several of my own
|
||
customizations added that I hope to get folded back into the main SWIG
|
||
distribution.) This has some far reaching ramifications:</p>
|
||
<blockquote>
|
||
<p>All classes derive from object and so all are now "new-style
|
||
classes." This also allows you to use mixin classes that are
|
||
new-style and to use properties, staticmethod, etc.</p>
|
||
<p>Public data members of the C++ classes are wrapped as Python
|
||
properties using property() instead of using
|
||
__getattr__/__setattr__ hacks like before. Normally you shouldn't
|
||
notice any difference, but if you were previously doing something
|
||
with __getattr__/__setattr__ in derived classes then you may have
|
||
to adjust things.</p>
|
||
<p>Static C++ methods are wrapped using the staticmethod() feature of
|
||
Python and so are accessible as ClassName.MethodName as expected.
|
||
They are still also available as top level functions named like
|
||
ClassName_MethodName as before.</p>
|
||
<p>The relationship between the wxFoo and wxFooPtr classes have
|
||
changed for the better. Specifically, all instances that you see
|
||
will be wx.Foo even if they are created internally using wx.FooPtr,
|
||
because wx.FooPtr.__init__ will change the instance's __class__ as
|
||
part of the initialization. If you have any code that checks
|
||
class type using something like isinstance(obj, wx.FooPtr) you will
|
||
need to change it to isinstance(obj, wx.Foo).</p>
|
||
</blockquote>
|
||
</div>
|
||
<div class="section" id="binding-events">
|
||
<h1><a name="binding-events">Binding Events</a></h1>
|
||
<p>All of the EVT_* functions are now instances of the wx.PyEventBinder
|
||
class. They have a __call__ method so they can still be used as
|
||
functions like before, but making them instances adds some
|
||
flexibility that I expect to take advantave of in the future.</p>
|
||
<p>wx.EvtHandler (the base class for wx.Window) now has a Bind method that
|
||
makes binding events to windows a little easier. Here is its
|
||
definition and docstring:</p>
|
||
<pre class="literal-block">
|
||
def Bind(self, event, handler, source=None, id=wxID_ANY, id2=wxID_ANY):
|
||
"""
|
||
Bind an event to an event handler.
|
||
|
||
event One of the EVT_* objects that specifies the
|
||
type of event to bind.
|
||
|
||
handler A callable object to be invoked when the event
|
||
is delivered to self. Pass None to disconnect an
|
||
event handler.
|
||
|
||
source Sometimes the event originates from a different window
|
||
than self, but you still want to catch it in self. (For
|
||
example, a button event delivered to a frame.) By
|
||
passing the source of the event, the event handling
|
||
system is able to differentiate between the same event
|
||
type from different controls.
|
||
|
||
id,id2 Used for menu IDs or for event types that require a
|
||
range of IDs
|
||
|
||
"""
|
||
</pre>
|
||
<p>Some examples of its use:</p>
|
||
<pre class="literal-block">
|
||
self.Bind(wx.EVT_SIZE, self.OnSize)
|
||
self.Bind(wx.EVT_BUTTON, self.OnButtonClick, theButton)
|
||
self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT)
|
||
</pre>
|
||
<p>The wx.Menu methods that add items to a wx.Menu have been modified
|
||
such that they return a reference to the wx.MenuItem that was created.
|
||
Additionally menu items and toolbar items have been modified to
|
||
automatically generate a new ID if -1 is given, similar to using -1
|
||
with window classess. This means that you can create menu or toolbar
|
||
items and event bindings without having to predefine a unique menu ID,
|
||
although you still can use IDs just like before if you want. For
|
||
example, these are all equivallent other than their specific ID
|
||
values:</p>
|
||
<pre class="literal-block">
|
||
1.
|
||
item = menu.Append(-1, "E&xit", "Terminate the App")
|
||
self.Bind(wx.EVT_MENU, self.OnExit, item)
|
||
|
||
2.
|
||
item = menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App")
|
||
self.Bind(wx.EVT_MENU, self.OnExit, item)
|
||
|
||
3.
|
||
menu.Append(wx.ID_EXIT, "E&xit", "Terminate the App")
|
||
self.Bind(wx.EVT_MENU, self.OnExit, id=wx.ID_EXIT)
|
||
</pre>
|
||
<p>If you create your own custom event types and EVT_* functions, and you
|
||
want to be able to use them with the Bind method above then you should
|
||
change your EVT_* to be an instance of wx.PyEventBinder instead of a
|
||
function. For example, if you used to have something like this:</p>
|
||
<pre class="literal-block">
|
||
myCustomEventType = wxNewEventType()
|
||
def EVT_MY_CUSTOM_EVENT(win, id, func):
|
||
win.Connect(id, -1, myCustomEventType, func)
|
||
</pre>
|
||
<p>Change it like so:</p>
|
||
<pre class="literal-block">
|
||
myCustomEventType = wx.NewEventType()
|
||
EVT_MY_CUSTOM_EVENT = wx.PyEventBinder(myCustomEventType, 1)
|
||
</pre>
|
||
<p>The second parameter is an integer in [0, 1, 2] that specifies the
|
||
number of IDs that are needed to be passed to Connect.</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> There is also an Unbind method added to
|
||
wx.EvtHandler that can be used to disconenct event handlers. It looks
|
||
like this:</p>
|
||
<pre class="literal-block">
|
||
def Unbind(self, event, source=None, id=wx.ID_ANY, id2=wx.ID_ANY):
|
||
"""
|
||
Disconencts the event handler binding for event from self.
|
||
Returns True if successful.
|
||
"""
|
||
</pre>
|
||
</div>
|
||
<div class="section" id="the-wx-namespace">
|
||
<h1><a name="the-wx-namespace">The wx Namespace</a></h1>
|
||
<p>The second phase of the wx Namespace Transition has begun. That means
|
||
that the real names of the classes and other symbols do not have the
|
||
'wx' prefix and the modules are located in a Python package named
|
||
wx. There is still a Python package named wxPython with modules
|
||
that have the names with the wx prefix for backwards compatibility.
|
||
Instead of dynamically changing the names at module load time like in
|
||
2.4, the compatibility modules are generated at build time and contain
|
||
assignment statements like this:</p>
|
||
<pre class="literal-block">
|
||
wxWindow = wx._core.Window
|
||
</pre>
|
||
<p>Don't let the "_core" in the name bother you. That and some other
|
||
modules are implementation details, and everything that was in the
|
||
wxPython.wx module before will still be in the wx package namespace
|
||
after this change. So from your code you would use it as wx.Window or
|
||
wxWindow if you import from the wxPython.wx module.</p>
|
||
<p>A few notes about how all of this was accomplished might be
|
||
interesting... SWIG is now run twice for each module that it is
|
||
generating code for. The first time it outputs an XML representaion
|
||
of the parse tree, which can be up to 20MB and 300K lines in size!
|
||
That XML is then run through a little Python script that creates a
|
||
file full of SWIG %rename directives that take the wx off of the
|
||
names, and also generates the Python compatibility file described
|
||
above that puts the wx back on the names. SWIG is then run a second
|
||
time to generate the C++ code to implement the extension module, and
|
||
uses the %rename directives that were generated in the first step.</p>
|
||
<p>Not every name is handled correctly (but the bulk of them are) and so
|
||
some work has to be done by hand, especially for the reverse-renamers.
|
||
So expect a few flaws here and there until everything gets sorted out.</p>
|
||
<p>In summary, the wx package and names without the "wx" prefix are now
|
||
the official form of the wxPython classes. For example:</p>
|
||
<pre class="literal-block">
|
||
import wx
|
||
|
||
class MyFrame(wx.Frame):
|
||
def __init__(self, parent, title):
|
||
wx.Frame.__init__(self, parent, -1, title)
|
||
p = wx.Panel(self, -1)
|
||
b = wx.Button(p, -1, "Do It", (10,10))
|
||
self.Bind(wx.EVT_BUTTON, self.JustDoIt, b)
|
||
|
||
def JustDoIt(self, evt):
|
||
print "It's done!"
|
||
|
||
app = wx.PySimpleApp()
|
||
f = MyFrame(None, "What's up?")
|
||
f.Show()
|
||
app.MainLoop()
|
||
</pre>
|
||
<p>You shouldn't need to migrate all your modules over to use the new
|
||
package and names right away as there are modules in place that try to
|
||
provide as much backwards compatibility of the names as possible. If
|
||
you rewrote the above sample using "from wxPython.wx import * ", the
|
||
old wxNames, and the old style of event binding it will still work
|
||
just fine.</p>
|
||
</div>
|
||
<div class="section" id="new-wx-dc-methods">
|
||
<h1><a name="new-wx-dc-methods">New wx.DC Methods</a></h1>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> In wxPython 2.5.1.5 there was a new
|
||
implementation of the wx.DC Draw and other methods that broke
|
||
backwards compatibility in the name of consistency. That change has
|
||
been reverted and the wx.DC Draw methods with 2.4 compatible
|
||
signatures have been restored. In addition a new set of methods have
|
||
been added that take wx.Point and/or wx.Size parameters instead of
|
||
separate integer parameters. The Draw and etc. methods now available
|
||
in the wx.DC class are:</p>
|
||
<pre class="literal-block">
|
||
FloodFill(self, x, y, colour, style = wx.FLOOD_SURFACE)
|
||
FoodFillPoint(self, pt, colour, style = wx.FLOOD_SURFACE)
|
||
|
||
GetPixel(self, x,y)
|
||
GetPixelPoint(self, pt)
|
||
|
||
DrawLine(self, x1, y1, x2, y2)
|
||
DrawLinePoint(self, pt1, pt2)
|
||
|
||
CrossHair(self, x, y)
|
||
CrossHairPoint(self, pt)
|
||
|
||
DrawArc(self, x1, y1, x2, y2, xc, yc)
|
||
DrawArcPoint(self, pt1, pt2, centre)
|
||
|
||
DrawCheckMark(self, x, y, width, height)
|
||
DrawCheckMarkRect(self, rect)
|
||
|
||
DrawEllipticArc(self, x, y, w, h, sa, ea)
|
||
DrawEllipticArcPointSize(self, pt, sz, sa, ea)
|
||
|
||
DrawPoint(self, x, y)
|
||
DrawPointPoint(self, pt)
|
||
|
||
DrawRectangle(self, x, y, width, height)
|
||
DrawRectangleRect(self, rect)
|
||
DrawRectanglePointSize(self, pt, sz)
|
||
|
||
DrawRoundedRectangle(self, x, y, width, height, radius)
|
||
DrawRoundedRectangleRect(self, r, radius)
|
||
DrawRoundedRectanglePointSize(self, pt, sz, radius)
|
||
|
||
DrawCircle(self, x, y, radius)
|
||
DrawCirclePoint(self, pt, radius)
|
||
|
||
DrawEllipse(self, x, y, width, height)
|
||
DrawEllipseRect(self, rect)
|
||
DrawEllipsePointSize(self, pt, sz)
|
||
|
||
DrawIcon(self, icon, x, y)
|
||
DrawIconPoint(self, icon, pt)
|
||
|
||
DrawBitmap(self, bmp, x, y, useMask = False)
|
||
DrawBitmapPoint(self, bmp, pt, useMask = False)
|
||
|
||
DrawText(self, text, x, y)
|
||
DrawTextPoint(self, text, pt)
|
||
|
||
DrawRotatedText(self, text, x, y, angle)
|
||
DrawRotatedTextPoint(self, text, pt, angle)
|
||
|
||
bool Blit(self, xdest, ydest, width, height, sourceDC, xsrc, ysrc,
|
||
rop = wx.COPY, useMask = False, xsrcMask = -1, ysrcMask = -1)
|
||
BlitPointSize(self, destPt, sz, sourceDC, srcPt, rop = wx.COPY,
|
||
useMask = False, srcPtMask = wxDefaultPosition)
|
||
|
||
|
||
SetClippingRegion(self, x, y, width, height)
|
||
SetClippingRegionPointSize(self, pt, sz)
|
||
SetClippingRegionAsRegion(self, region)
|
||
SetClippingRect(self, rect)
|
||
</pre>
|
||
</div>
|
||
<div class="section" id="building-extending-and-embedding-wxpython">
|
||
<h1><a name="building-extending-and-embedding-wxpython">Building, Extending and Embedding wxPython</a></h1>
|
||
<p>wxPython's setup.py script now expects to use existing libraries for
|
||
the contribs (gizmos, stc, xrc, etc.) rather than building local
|
||
copies of them. If you build your own copies of wxPython please be
|
||
aware that you now need to also build the ogl, stc, xrc, and gizmos
|
||
libraries in addition to the main wx lib.</p>
|
||
<p>The wxPython.h and other header files are now in
|
||
.../wxPython/include/wx/wxPython instead of in wxPython/src. You
|
||
should include it via the "wx/wxPython/wxPython.h" path and add
|
||
.../wxPython/include to your list of include paths. On OSX and
|
||
unix-like systems the wxPython headers are installed to the same place
|
||
that the wxWidgets headers are installed, so if you are building
|
||
wxPython compatible extensions on those platforms then your include
|
||
path should already be set properly.</p>
|
||
<p>If you are also using SWIG for your extension then you'll need to
|
||
adapt how the wxPython .i files are imported into your .i files. See
|
||
the wxPython sources for examples. Your modules will need to at least
|
||
<tt class="literal"><span class="pre">%import</span> <span class="pre">core.i</span></tt>, and possibly others if you need the definition of
|
||
other classes. Since you will need them to build your modules using
|
||
SWIG, the main wxPython .i files are also installed with the wxPython
|
||
headers in an i_files sibdirectory. It should be enough to pass a
|
||
-I/pathname on the command line for SWIG to find the files.</p>
|
||
<p>The bulk of wxPython's setup.py has been moved to another module,
|
||
wx/build/config.py. This module will be installed as part of wxPython
|
||
so 3rd party modules that wish to use the same setup/configuration
|
||
code can do so simply by importing this module from their own setup.py
|
||
scripts using <tt class="literal"><span class="pre">import</span> <span class="pre">wx.build.config</span></tt>.</p>
|
||
<p>You no longer need to call wxClassInfo::CleanUpClasses() and
|
||
wxClassInfo::InitializeClasses() in your extensions or when embedding
|
||
wxPython.</p>
|
||
<p>The usage of wxPyBeginAllowThreads and wxPyEndAllowThreads has changed
|
||
slightly. wxPyBeginAllowThreads now returns a boolean value that must
|
||
be passed to the coresponding wxPyEndAllowThreads function call. This
|
||
is to help do the RightThing when calls to these two functions are
|
||
nested, or if calls to external code in other extension modules that
|
||
are wrapped in the standard Py_(BEGIN|END)_ALLOW_THERADS may result in
|
||
wx event handlers being called (such as during the call to
|
||
os.startfile.)</p>
|
||
</div>
|
||
<div class="section" id="two-or-three-phase-create">
|
||
<h1><a name="two-or-three-phase-create">Two (or Three!) Phase Create</a></h1>
|
||
<p>If you use the Precreate/Create method of instantiating a window, (for
|
||
example, to set an extended style flag, or for XRC handlers) then
|
||
there is now a new method named PostCreate to help with transplanting
|
||
the brain of the prewindow instance into the derived window instance.
|
||
For example:</p>
|
||
<pre class="literal-block">
|
||
class MyDialog(wx.Dialog):
|
||
def __init__(self, parent, ID, title, pos, size, style):
|
||
pre = wx.PreDialog()
|
||
pre.SetExtraStyle(wx.DIALOG_EX_CONTEXTHELP)
|
||
pre.Create(parent, ID, title, pos, size, style)
|
||
self.PostCreate(pre)
|
||
</pre>
|
||
</div>
|
||
<div class="section" id="sizers">
|
||
<h1><a name="sizers">Sizers</a></h1>
|
||
<p>The hack allowing the old "option" keyword parameter has been removed.
|
||
If you use keyword args with w.xSizer Add, Insert, or Prepend methods
|
||
then you will need to use the <tt class="literal"><span class="pre">proportion</span></tt> name instead of
|
||
<tt class="literal"><span class="pre">option</span></tt>. (The <tt class="literal"><span class="pre">proportion</span></tt> keyword was also allowed in 2.4.2.4.)</p>
|
||
<p>When adding a spacer to a sizer you now need to use a wx.Size or a
|
||
2-integer sequence instead of separate width and height parameters.
|
||
This was optionally allowed in 2.4, but now it is required. This
|
||
allows for more consistency in how you add the various types of items
|
||
to a sizer. The first parameter defines the item (instead of the
|
||
possibily first two, depending on if you are doing a spacer or not,)
|
||
and that item can either be a window, a sizer or a spacer (which can
|
||
be a sequence or a wx.Size.) Removing the option for separate width
|
||
and height parameters greatly simplified the wrapper code.</p>
|
||
<p>The wx.GridBagSizer class (very similar to the RowColSizer in the
|
||
library) has been added to C++ and wrapped for wxPython. It can also
|
||
be used from XRC.</p>
|
||
<p>You should not use AddWindow, AddSizer, AddSpacer (and similar for
|
||
Insert, Prepend, and etc.) methods any longer. Just use Add and the
|
||
wrappers will figure out what to do. <strong>[Changed in 2.5.2.x]</strong>
|
||
AddWindow, AddSize, AddSpacer and etc. will now issue a
|
||
DeprecationWarning.</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> The Sizers have had some fundamental internal
|
||
changes in the 2.5.2.x release intended to make them do more of the
|
||
"Right Thing" but also be as backwards compatible as possible.
|
||
First a bit about how things used to work:</p>
|
||
<blockquote>
|
||
<ul class="simple">
|
||
<li>The size that a window had when Add()ed to the sizer was assumed
|
||
to be its minimal size, and that size would always be used by
|
||
default when calculating layout size and positions, and the
|
||
sizer itself would keep track of that minimal size.</li>
|
||
<li>If the window item was added with the <tt class="literal"><span class="pre">wx.ADJUST_MINSIZE</span></tt>
|
||
flag then when layout was calculated the item's <tt class="literal"><span class="pre">GetBestSize</span></tt>
|
||
would be used to reset the minimal size that the sizer used.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>The main thrust of the new Sizer changes was to make behaviour like
|
||
<tt class="literal"><span class="pre">wx.ADJUST_MINSIZE</span></tt> be the default, and also to push the tracking of
|
||
the minimal size to the window itself (since it knows its own needs)
|
||
instead of having the sizer take care of it. Consequently these
|
||
changes were made:</p>
|
||
<blockquote>
|
||
<ul class="simple">
|
||
<li>The <tt class="literal"><span class="pre">wx.FIXED_MINSIZE</span></tt> flag was added to allow for the old
|
||
behaviour. When this flag is used the size a window has when
|
||
added to the sizer will be treated as its minimal size and it
|
||
will not be readjusted on each layout.</li>
|
||
<li>The min size stored in <tt class="literal"><span class="pre">wx.Window</span></tt> and settable with
|
||
<tt class="literal"><span class="pre">SetSizeHints</span></tt> or <tt class="literal"><span class="pre">SetMinSize</span></tt> will by default be used by
|
||
the sizer (if it was set) as the minimal size of the sizer item.
|
||
If the min size was not set (or was only partially set) then the
|
||
window's best size is fetched and it is used instead of (or
|
||
blended with) the min size. <tt class="literal"><span class="pre">wx.Window.GetBestFittingSize</span></tt>
|
||
was added to facilitate getting the size to be used by the
|
||
sizers.</li>
|
||
<li>The best size of a window is cached so it doesn't need to
|
||
recaculated on every layout. <tt class="literal"><span class="pre">wx.Window.InvalidateBestSize</span></tt>
|
||
was added and should be called (usually just internally in
|
||
control methods) whenever something is done that would make the
|
||
best size change.</li>
|
||
<li>All wxControls were changed to set the minsize to what is passed
|
||
to the constructor or Create method, and also to set the real
|
||
size of the control to the blending of the min size and best
|
||
size. <tt class="literal"><span class="pre">wx.Window.SetBestFittingSize</span></tt> was added to help with
|
||
this, although most controls don't need to call it directly
|
||
because it is called indirectly via the <tt class="literal"><span class="pre">SetInitialSize</span></tt>
|
||
called in the base classes.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>At this time, the only situation known not to work the same as before
|
||
is the following:</p>
|
||
<pre class="literal-block">
|
||
win = SomeWidget(parent)
|
||
win.SetSize(SomeNonDefaultSize)
|
||
sizer.Add(win)
|
||
</pre>
|
||
<p>In this case the old code would have used the new size as the minimum,
|
||
but now the sizer will use the default size as the minimum rather than
|
||
the size set later. It is an easy fix though, just move the
|
||
specification of the size to the constructor (assuming that SomeWidget
|
||
will set its minsize there like the rest of the controls do) or call
|
||
<tt class="literal"><span class="pre">SetMinSize</span></tt> instead of <tt class="literal"><span class="pre">SetSize</span></tt>.</p>
|
||
<p>In order to fit well with this new scheme of things, all wxControls or
|
||
custom controls should do the following things. (Depending on how
|
||
they are used you may also want to do the same thing for non-control
|
||
custom windows.)</p>
|
||
<blockquote>
|
||
<ul>
|
||
<li><p class="first">Either override or inherit a meaningful <tt class="literal"><span class="pre">DoGetBestSize</span></tt> method
|
||
that calculates whatever size is "best" for the control. Once
|
||
that size is calculated then there should normally be a call to
|
||
<tt class="literal"><span class="pre">CacheBestSize</span></tt> to save it for later use, unless for some
|
||
reason you want the best size to be recalculated on every
|
||
layout.</p>
|
||
<p>Note: In order to successfully override <tt class="literal"><span class="pre">DoGetBestSize</span></tt> in
|
||
Python the class needs to be derived from <tt class="literal"><span class="pre">wx.PyWindow</span></tt>,
|
||
<tt class="literal"><span class="pre">wx.PyControl</span></tt>, or etc. If your class instead derives from
|
||
one of the standard wx classes then just be sure that the min
|
||
size gets explicitly set to what would have been the best size
|
||
and things should work properly in almost all situations.</p>
|
||
</li>
|
||
<li><p class="first">Any method that changes the attributes of the control such that
|
||
the best size will change should call <tt class="literal"><span class="pre">InvalidateBestSize</span></tt> so
|
||
it will be recalculated the next time it is needed.</p>
|
||
</li>
|
||
<li><p class="first">The control's constructor and/or Create method should ensure
|
||
that the minsize is set to the size passed in, and that the
|
||
control is sized to a blending of the min size and best size.
|
||
This can be done by calling <tt class="literal"><span class="pre">SetBestFittingSize</span></tt>.</p>
|
||
</li>
|
||
</ul>
|
||
</blockquote>
|
||
</div>
|
||
<div class="section" id="platforminfo">
|
||
<h1><a name="platforminfo">PlatformInfo</a></h1>
|
||
<p>Added wx.PlatformInfo which is a tuple containing strings that
|
||
describe the platform and build options of wxPython. This lets you
|
||
know more about the build than just the __WXPORT__ value that
|
||
wx.Platform contains, such as if it is a GTK2 build. For example,
|
||
instead of:</p>
|
||
<pre class="literal-block">
|
||
if wx.Platform == "__WXGTK__":
|
||
...
|
||
</pre>
|
||
<p>you should do this:</p>
|
||
<pre class="literal-block">
|
||
if "__WXGTK__" in wx.PlatformInfo:
|
||
...
|
||
</pre>
|
||
<p>and you can specifically check for a wxGTK2 build by looking for
|
||
"gtk2" in wx.PlatformInfo. Unicode builds are also detectable this
|
||
way. If there are any other platform/toolkit/build flags that make
|
||
sense to add to this tuple please let me know.</p>
|
||
<p>BTW, wx.Platform will probably be deprecated in the future.</p>
|
||
</div>
|
||
<div class="section" id="activex">
|
||
<h1><a name="activex">ActiveX</a></h1>
|
||
<p>Lindsay Mathieson's newest <a class="reference" href="http://members.optusnet.com.au/~blackpaw1/wxactivex.html">wxActiveX</a> class has been wrapped into a new
|
||
extension module called wx.activex. It is very generic and dynamic
|
||
and should allow hosting of arbitray ActiveX controls within your
|
||
wxPython apps. So far I've tested it with IE, PDF, and Flash
|
||
controls, (and there are new samples in the demo and also library
|
||
modules supporting these.)</p>
|
||
<p>The new wx.activex module contains a bunch of code, but the most
|
||
important things to look at are ActiveXWindow and ActiveXEvent.
|
||
ActiveXWindow derives from wxWindow and the constructor accepts a
|
||
CLSID for the ActiveX Control that should be created. (There is also
|
||
a CLSID class that can convert from a progID or a CLSID String.) The
|
||
ActiveXWindow class simply adds methods that allow you to query some
|
||
of the TypeInfo exposed by the ActiveX object, and also to get/set
|
||
properties or call methods by name. The Python implementation
|
||
automatically handles converting parameters and return values to/from
|
||
the types expected by the ActiveX code as specified by the TypeInfo,
|
||
(just bool, integers, floating point, strings and None/Empty so far,
|
||
but more can be handled later.)</p>
|
||
<p>That's pretty much all there is to the class, as I mentioned before it
|
||
is very generic and dynamic. Very little is hard-coded and everything
|
||
that is done with the actual ActiveX control is done at runtime and
|
||
referenced by property or method name. Since Python is such a dynamic
|
||
language this is a very good match. I thought for a while about doing
|
||
some Python black-magic and making the specific methods/properties of
|
||
the actual ActiveX control "appear" at runtime, but then decided that
|
||
it would be better and more understandable to do it via subclassing.
|
||
So there is a utility class in wx.activex that given an existing
|
||
ActiveXWindow instance can generate a .py module containing a derived
|
||
class with real methods and properties that do the Right Thing to
|
||
reflect those calls to the real ActiveX control. There is also a
|
||
script/tool module named genaxmodule that given a CLSID or progID and
|
||
a class name, will generate the module for you. There are a few
|
||
examples of the output of this tool in the wx.lib package, see
|
||
iewin.py, pdfwin.py and flashwin.py.</p>
|
||
<p>Currently the genaxmodule tool will tweak some of the names it
|
||
generates, but this can be controled if you would like to do it
|
||
differently by deriving your own class from GernerateAXModule,
|
||
overriding some methods and then using this class from a tool like
|
||
genaxmodule. [TODO: make specifying a new class on genaxmodule's
|
||
command-line possible.] The current default behavior is that any
|
||
event names that start with "On" will have the "On" dropped, property
|
||
names are converted to all lower case, and if any name is a Python
|
||
keyword it will have an underscore appended to it. GernerateAXModule
|
||
does it's best when generating the code in the new module, but it can
|
||
only be as good as the TypeInfo data available from the ActiveX
|
||
control so sometimes some tweaking will be needed. For example, the
|
||
IE web browser control defines the Flags parameter of the Navigate2
|
||
method as required, but MSDN says it is optional.</p>
|
||
<p>It is intended that this new wx.activex module will replace both the
|
||
older version of Lindsay's code available in iewin.IEHtmlWindow, and
|
||
also the wx.lib.activexwraper module. Probably the biggest
|
||
differences you'll ecounter in migrating activexwrapper-based code
|
||
(besides events working better without causing deadlocks) is that
|
||
events are no longer caught by overriding methods in your derived
|
||
class. Instead ActiveXWindow uses the wx event system and you bind
|
||
handlers for the ActiveX events exactly the same way you do for any wx
|
||
event. There is just one extra step needed and that is creating an
|
||
event ID from the ActiveX event name, and if you use the genaxmodule
|
||
tool then this extra step will be handled for you there. For example,
|
||
for the StatusTextChange event in the IE web browser control, this
|
||
code is generated for you:</p>
|
||
<pre class="literal-block">
|
||
wxEVT_StatusTextChange = wx.activex.RegisterActiveXEvent('StatusTextChange')
|
||
EVT_StatusTextChange = wx.PyEventBinder(wxEVT_StatusTextChange, 1)
|
||
</pre>
|
||
<p>and you would use it in your code like this:</p>
|
||
<pre class="literal-block">
|
||
self.Bind(iewin.EVT_StatusTextChange, self.UpdateStatusText, self.ie)
|
||
</pre>
|
||
<p>When the event happens and your event handler function is called the
|
||
event properties from the ActiveX control (if any) are converted to
|
||
attributes of the event object passed to the handler. (Can you say
|
||
'event' any more times in a single sentence? ;-) ) For example the
|
||
StatusTextChange event will also send the text that should be put into
|
||
the status line as an event parameter named "Text" and you can access
|
||
it your handlers as an attribute of the event object like this:</p>
|
||
<pre class="literal-block">
|
||
def UpdateStatusText(self, evt):
|
||
self.SetStatusText(evt.Text)
|
||
</pre>
|
||
<p>Usually these event object attributes should be considered read-only,
|
||
but some will be defined by the TypeInfo as output parameters. In
|
||
those cases if you modify the event object's attribute then that value
|
||
will be returned to the ActiveX control. For example, to prevent a
|
||
new window from being opened by the IE web browser control you can do
|
||
this in the handler for the iewin.EVT_NewWindow2 event:</p>
|
||
<pre class="literal-block">
|
||
def OnNewWindow2(self, evt):
|
||
evt.Cancel = True
|
||
</pre>
|
||
<p>So how do you know what methods, events and properties that an ActiveX
|
||
control supports? There is a funciton in wx.activex named GetAXInfo
|
||
that returns a printable summary of the TypeInfo from the ActiveX
|
||
instance passed in. You can use this as an example of how to browse
|
||
the TypeInfo provided, and there is also a copy of this function's
|
||
output appended as a comment to the modules produced by the
|
||
genaxmodule tool. Beyond that you'll need to consult the docs
|
||
provided by the makers of the ActiveX control that you are using.</p>
|
||
</div>
|
||
<div class="section" id="png-images">
|
||
<h1><a name="png-images">PNG Images</a></h1>
|
||
<p>Prior to 2.5 the PNG image handler would convert all alpha channel
|
||
information to a mask when the image was loaded. Pixels that were
|
||
more than halfway transparent would be made fully transparent by the
|
||
mask and the rest would be made fully opaque.</p>
|
||
<p>In 2.5 the image handler has been updated to preserve the alpha
|
||
channel and will now only create a mask when all the pixels in the
|
||
image are either fully transparent or fully opaque. In addition, the
|
||
wx.DC.DrawBitmap and wx.DC.Blit methods are able to correctly blend
|
||
the pixels in the image with partially transparent alpha values.
|
||
(Currently only on MSW and Mac, if anybody knows how to do it for GTK
|
||
then please submit a patch!)</p>
|
||
<p>If you are using a PNG with an alpha channel but you need to have a
|
||
wx.Mask like you automatically got in 2.4 then you can do one of the
|
||
following:</p>
|
||
<blockquote>
|
||
<ul class="simple">
|
||
<li>Edit the image and make all the partially transparent pixels be
|
||
fully transparent.</li>
|
||
<li>Use a different image type.</li>
|
||
<li>Set a mask based on colour after you load the image.</li>
|
||
</ul>
|
||
</blockquote>
|
||
</div>
|
||
<div class="section" id="ogl-is-dead-long-live-ogl">
|
||
<h1><a name="ogl-is-dead-long-live-ogl">OGL is dead! LONG LIVE OGL!</a></h1>
|
||
<p><strong>[Changed in 2.5.2.x]</strong></p>
|
||
<p>The wx.ogl module has been deprecated in favor of the new Python port
|
||
of the OGL library located at wx.lib.ogl contributed by Pierre Hj<48>lm.
|
||
This will hopefully greatly extend the life of OGL within wxPython by
|
||
making it more easily maintainable and less prone to getting rusty as
|
||
there seems to be less and less interest in maintaining the C++
|
||
version.</p>
|
||
<p>There are only a few known compatibility issues at this time. First
|
||
is the location of OGL. The deprecated version is located in the
|
||
wx.ogl module, and the new version is in the wx.lib.ogl package. So
|
||
this just means that to start using the new version you need to adjust
|
||
your imports. So if your code currently has something like this:</p>
|
||
<pre class="literal-block">
|
||
import wx
|
||
import wx.ogl as ogl
|
||
</pre>
|
||
<p>Then just change it to this:</p>
|
||
<pre class="literal-block">
|
||
import wx
|
||
import wx.lib.ogl as ogl
|
||
</pre>
|
||
<p>The other compatibility issue deals with removing a wart in the
|
||
original API that was necessary in order to allow overloaded methods
|
||
in derived classes to call the same method in the base class when
|
||
using the old SWIG. Instead dedaling with the wart you can now just
|
||
call the base class method like you woudl for any other Python class.
|
||
For example, if you had to do something like this previously:</p>
|
||
<pre class="literal-block">
|
||
class MyDividedShape(ogl.DividedShape):
|
||
...
|
||
def OnSizingEndDragLeft(self, pt, x, y, keys, attch):
|
||
self.base_OnSizingEndDragLeft(pt, x, y, keys, attch)
|
||
...
|
||
</pre>
|
||
<p>You will need to change it to be like this:</p>
|
||
<pre class="literal-block">
|
||
class MyDividedShape(ogl.DividedShape):
|
||
...
|
||
def OnSizingEndDragLeft(self, pt, x, y, keys, attch):
|
||
ogl.DividedShape.OnSizingEndDragLeft(self, pt, x, y, keys, attch)
|
||
...
|
||
</pre>
|
||
</div>
|
||
<div class="section" id="obsolete-modules">
|
||
<h1><a name="obsolete-modules">Obsolete Modules</a></h1>
|
||
<p>Instead of over a dozen separate extension modules linked together
|
||
into a single extension module, the "core" module is now just a few
|
||
extensions that are linked independently, and then merged together
|
||
later into the main namespace via Python code.</p>
|
||
<p>Because of the above and also because of the way the new SWIG works,
|
||
the "internal" module names have changed, but you shouldn't have been
|
||
using them anyway so it shouldn't bother you. ;-) In case you were
|
||
erroneously using them in 2.4, here are the internal extension modules
|
||
no longer exist:</p>
|
||
<blockquote>
|
||
<ul class="simple">
|
||
<li>clip_dnd</li>
|
||
<li>cmndlgs</li>
|
||
<li>controls</li>
|
||
<li>controls2</li>
|
||
<li>events</li>
|
||
<li>filesys</li>
|
||
<li>fonts</li>
|
||
<li>frames</li>
|
||
<li>gdi</li>
|
||
<li>image</li>
|
||
<li>mdi</li>
|
||
<li>misc</li>
|
||
<li>misc2</li>
|
||
<li>printfw</li>
|
||
<li>sizers</li>
|
||
<li>stattool</li>
|
||
<li>streams</li>
|
||
<li>utils</li>
|
||
<li>windows</li>
|
||
<li>windows2</li>
|
||
<li>windows3</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>They have been replaced by the following, but please remember that
|
||
these are just "implementation details" and you should really be using
|
||
the objects in these modules only via the wx or wxPython.wx packages:</p>
|
||
<blockquote>
|
||
<ul class="simple">
|
||
<li>_core</li>
|
||
<li>_gdi</li>
|
||
<li>_windows</li>
|
||
<li>_controls</li>
|
||
<li>_misc</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>The help module no longer exists and the classes therein are now part
|
||
of the core module imported with wxPython.wx or the wx package.</p>
|
||
</div>
|
||
<div class="section" id="other-stuff">
|
||
<h1><a name="other-stuff">Other Stuff</a></h1>
|
||
<p>wxPyDefaultPosition and wxPyDefaultSize are gone. Use the
|
||
wxDefaultPosition and wxDefaultSize objects instead.</p>
|
||
<p>Similarly, the wxSystemSettings backwards compatibiility aliases for
|
||
GetSystemColour, GetSystemFont and GetSystemMetric have also gone into
|
||
the bit-bucket. Use GetColour, GetFont and GetMetric instead.</p>
|
||
<p>Use the Python True/False constants instead of the true, TRUE, false,
|
||
FALSE that used to be provided with wxPython.</p>
|
||
<p>Use None instead of the ancient and should have been removed a long
|
||
time ago wx.NULL alias.</p>
|
||
<p>wx.TreeCtrl.GetFirstChild no longer needs to be passed the cookie
|
||
variable as the 2nd parameter. It still returns it though, for use
|
||
with GetNextChild.</p>
|
||
<p>The wx.NO_FULL_REPAINT_ON_RESIZE style is now the default style for
|
||
all windows. The name still exists for compatibility, but it is set
|
||
to zero. If you want to disable the setting (so it matches the old
|
||
default) then you need to use the new wx.FULL_REPAINT_ON_RESIZE style
|
||
flag otherwise only the freshly exposed areas of the window will be
|
||
refreshed.</p>
|
||
<p>wxPyTypeCast has been removed. Since we've had the OOR (Original
|
||
Object Return) for a couple years now there should be no need to use
|
||
wxPyTypeCast at all.</p>
|
||
<p>If you use the old wxPython package and wxPython.wx namespace then
|
||
there are compatibility aliases for much of the above items.</p>
|
||
<p>The wxWave class has been renamed to wxSound, and now has a slightly
|
||
different API.</p>
|
||
<p>wx.TaskbarIcon works on wxGTK-based platforms (for some window
|
||
managers,) however you have to manage it a little bit more than you
|
||
did before. Basically, the app will treat it like a top-level frame
|
||
in that if the wx.TaskBarIcon still exists when all the frames are
|
||
closed then the app will still not exit. You need to ensure that the
|
||
wx.TaskBarIcon is destroyed when your last Frame is closed. For
|
||
wxPython apps it is usually enough if your main frame object holds the
|
||
only reference to the wx.TaskBarIcon, then when the frame is closed
|
||
Python reference counting takes care of the rest.</p>
|
||
<p>Before Python 2.3 it was possible to pass a floating point object as a
|
||
parameter to a function that expected an integer, and the
|
||
PyArg_ParseTuple family of functions would automatically convert to
|
||
integer by truncating the fractional portion of the number. With
|
||
Python 2.3 that behavior was deprecated and a deprecation warning is
|
||
raised when you pass a floating point value, (for example, calling
|
||
wx.DC.DrawLine with floats for the position and size,) and lots of
|
||
developers using wxPython had to scramble to change their code to call
|
||
int() before calling wxPython methods. Recent changes in SWIG have
|
||
moved the conversion out of PyArg_ParseTuple to custom code that SWIG
|
||
generates. Since the default conversion fragment was a little too
|
||
strict and didn't generate a very meaningful exception when it failed,
|
||
I decided to use a custom fragment instead, and it turned out that
|
||
it's very easy to allow floats to be converted again just like they
|
||
used to be. So, in a nutshell, any numeric type that can be
|
||
converted to an integer is now legal to be passed to SWIG wrapped
|
||
functions in wxPython for parameters that are expecting an integer.
|
||
If the object is not already an integer then it will be asked to
|
||
convert itself to one. A similar conversion fragment is in place for
|
||
parameters that expect floating point values.</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> The MaskedEditCtrl modules have been moved
|
||
to their own sub-package, wx.lib.masked. See the docstrings and demo
|
||
for changes in capabilities, usage, etc.</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> wx.MaskColour constructor has been deprecated
|
||
and will raise a DeprecationWarning if used. The main wx.Mask
|
||
constructor has been modified to be compatible with wx.MaskColour so
|
||
you should use it instead.</p>
|
||
<p><strong>[Changed in 2.5.2.x]</strong> In wx.TextCtrls that have the
|
||
wx.TE_PROCESS_TAB style the TAB key will be treated like an ordinary
|
||
character and will not cause any tab traversal navigation at all. If
|
||
you use this style but would still like to have the normal tab
|
||
traversal take place then you should send your own
|
||
wx.NavigationKeyEvent from the wx.EVT_KEY_DOWN handler. There is a
|
||
new Navigate method in the wx.Window class to help send the event and
|
||
it is used something like this:</p>
|
||
<pre class="literal-block">
|
||
flags = wx.NavigationKeyEvent.IsForward
|
||
if event.ShiftDown():
|
||
flags = wx.NavigationKeyEvent.IsBackward
|
||
if event.ControlDown():
|
||
flags |= wx.NavigationKeyEvent.WinChange
|
||
self.Navigate(flags)
|
||
</pre>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|