Phoenix: sizers_overview.rst expanded; added a bunch of "contributed" snippets on various classes/methods; many fixes on strange doxygen layouts and XML hierarchies; fixed many cross-references between classes/methods/functions in the etg files.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@73128 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/sphinx/_downloads/ArtProvider.GetBitmap.1.py

@@ -0,0 +1,43 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to retrieve default platform's 
+# bitmaps using wx.ArtProvider
+
+import wx
+
+class BitmapFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, -1, title='ArtProvider example')
+
+        panel = wx.Panel(self)
+
+        main_sizer = wx.BoxSizer(wx.VERTICAL)
+        bitmap_sizer = wx.BoxSizer(wx.HORIZONTAL)
+
+        bitmap_sizer.Add((0, 0), 1, wx.EXPAND)
+        
+        # Show a few bitmaps retrieved via wx.ArtProvider
+        for kind in [wx.ART_INFORMATION, wx.ART_WARNING, wx.ART_CDROM, wx.ART_CUT]:
+            bmp = wx.ArtProvider.GetBitmap(kind, wx.ART_OTHER, (32, 32))
+            static_bitmap = wx.StaticBitmap(panel, -1, bmp)
+            bitmap_sizer.Add(static_bitmap, 0, wx.ALL, 5)
+
+        # Layout everything in a nice sizer
+        bitmap_sizer.Add((0, 0), 1, wx.EXPAND)
+        main_sizer.Add((0, 0), 1, wx.EXPAND)
+        main_sizer.Add(bitmap_sizer, 0, wx.EXPAND)
+        main_sizer.Add((0, 0), 1, wx.EXPAND)
+
+        panel.SetSizer(main_sizer)
+        main_sizer.SetSizeHints(panel)
+        main_sizer.Layout()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = BitmapFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_downloads/CloseEvent.Veto.1.py

@@ -0,0 +1,34 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample makes the main frame "immortal", i.e., non-closable 
+# by the user. The main window can not be close by pressing Alt+F4
+# or by clicking on the "X" button in the titlebar
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind the "close window" event to the OnClose handler
+        self.Bind(wx.EVT_CLOSE, self.OnClose)
+
+        self.Show()
+        self.close_attempts = 0
+
+        
+    def OnClose(self, event):
+
+        # Veto the event the user can not close the main
+        # window in any way
+        self.close_attempts += 1
+        print('I am immortal %d'%self.close_attempts)
+        event.Veto()
+
+
+app = wx.App(False)
+frame = MainWindow(None, 'Immortal Frame')
+app.MainLoop()

docs/sphinx/_downloads/Colour.1.py

@@ -0,0 +1,32 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to assign different fonts to various
+# wx.StaticTexts
+
+import wx
+
+app = wx.App(0)
+frame = wx.Frame(None, -1, 'Colour settings')
+
+text_ctrl_1 = wx.TextCtrl(frame, -1, 'Some text')
+text_ctrl_1.SetBackgroundColour(wx.Colour(0, 0, 255))
+# OR
+text_ctrl_2 = wx.TextCtrl(frame, -1, 'Other text')
+text_ctrl_2.SetBackgroundColour('BLUE')
+# OR
+text_ctrl_3 = wx.TextCtrl(frame, -1, 'Another text')
+text_ctrl_3.SetBackgroundColour('#0000FF')
+
+# Size up everything in a nice vertical box sizer
+sizer = wx.BoxSizer(wx.VERTICAL)
+sizer.Add(text_ctrl_1, 0, wx.EXPAND|wx.ALL, 10)
+sizer.Add(text_ctrl_2, 0, wx.EXPAND|wx.LEFT|wx.RIGHT, 10)
+sizer.Add(text_ctrl_3, 0, wx.EXPAND|wx.ALL, 10)
+frame.SetSizer(sizer)
+sizer.SetSizeHints(frame)
+
+frame.Show()
+
+# Enter the application main loop
+app.MainLoop()

docs/sphinx/_downloads/EvtHandler.Bind.1.py

@@ -0,0 +1,36 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows a simple example of how to use the
+# "Bind" method to handle an event
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind the "close window" event to the OnClose handler
+        self.Bind(wx.EVT_CLOSE, self.OnClose)
+
+        self.Show()
+
+        
+    def OnClose(self, event):
+
+        # This displays a message box asking the user to confirm
+        # she wants to quit the application
+        dlg = wx.MessageDialog(self, 'Are you sure you want to quit?', 'Question',
+                               wx.YES_NO | wx.NO_DEFAULT | wx.ICON_QUESTION)
+
+        if dlg.ShowModal() == wx.ID_YES:
+            self.Destroy()
+        else:
+            event.Veto()
+
+
+app = wx.App(False)
+frame = MainWindow(None, 'Bind example')
+app.MainLoop()

docs/sphinx/_downloads/Font.1.py

@@ -0,0 +1,63 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to assign different fonts to various
+# wx.StaticTexts
+
+import wx
+
+class FontFrame(wx.Frame):
+
+   def __init__(self, parent):
+
+        wx.Frame.__init__(self, parent, title='Font sample')
+
+        panel = wx.Panel(self, -1)
+
+        text1 = '''Lasciatemi cantare
+con la chitarra in mano
+lasciatemi cantare
+sono un italiano'''
+
+        text2 = '''Buongiorno Italia gli spaghetti al dente
+e un partigiano come Presidente
+con l'autoradio sempre nella mano destra
+e un canarino sopra la finestra'''
+
+        text3 = '''Buongiorno Italia con i tuoi artisti
+con troppa America sui manifesti
+con le canzoni con amore con il cuore
+con piu' donne sempre meno suore'''
+
+        # Construct 2 font objects from the wx.Font constructor
+        font1 = wx.Font(10, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_ITALIC, wx.FONTWEIGHT_NORMAL)
+        font2 = wx.Font(10, wx.FONTFAMILY_MODERN, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD)
+
+        # A font can be retrieved from the OS default font
+        # and modified
+        font3 = wx.SystemSettings.GetFont(wx.SYS_DEFAULT_GUI_FONT)
+        font3.SetStyle(wx.FONTSTYLE_ITALIC)
+        font3.SetPointSize(12)
+
+        lyrics1 = wx.StaticText(panel, -1, text1, style=wx.ALIGN_CENTRE)
+        lyrics1.SetFont(font1)
+        lyrics2 = wx.TextCtrl(panel, -1, text2, style=wx.TE_CENTER|wx.TE_MULTILINE)
+        lyrics2.SetFont(font2)
+        lyrics3 = wx.StaticText(panel, -1, text3, style=wx.ALIGN_CENTRE)
+        lyrics3.SetFont(font3)
+
+        # Size up everything in a nice vertical box sizer
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(lyrics1, 0, wx.EXPAND|wx.ALL, 10)
+        sizer.Add(lyrics2, 0, wx.EXPAND|wx.LEFT|wx.RIGHT, 10)
+        sizer.Add(lyrics3, 0, wx.EXPAND|wx.ALL, 10)
+        panel.SetSizer(sizer)
+        sizer.SetSizeHints(panel)
+        self.Center()
+
+
+app = wx.App(0)
+frame = FontFrame(None)
+frame.Show()
+# Enter the application main loop
+app.MainLoop()

docs/sphinx/_downloads/Frame.SetStatusWidths.1.py

@@ -0,0 +1,35 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a wx.StatusBar with 2 fields, 
+# set the second field to have double width with respect to the 
+# first and and display the date of today in the second field.
+
+import wx
+import datetime
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        # Set it up so it has two fields
+        self.CreateStatusBar(2)
+
+        # Set the second field to be double in width wrt the first
+        self.SetStatusWidths([-1, -2])
+
+        # Get today date via datetime
+        today = datetime.datetime.today()
+        today = today.strftime('%d-%b-%Y')
+
+        # Set today date in the second field
+        self.SetStatusText(today, 1)
+
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'SetStatusWidths example')
+app.MainLoop()

docs/sphinx/_downloads/MenuBar.1.py

@@ -0,0 +1,40 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a simple wx.MenuBar
+# and a simple wx.StatusBar
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        self.CreateStatusBar()
+
+        # Setting up the menu
+        file_menu = wx.Menu()
+
+        # wx.ID_ABOUT and wx.ID_EXIT are standard IDs provided
+        # by wxWidgets.
+        file_menu.Append(wx.ID_ABOUT, '&About',
+                         'Information about this application')
+        file_menu.AppendSeparator()
+        file_menu.Append(wx.ID_EXIT, 'E&xit', 'Exit the application')
+
+        # Creating the menubar
+        menu_bar = wx.MenuBar()
+
+        # Adding the 'file_menu' to the menu bar
+        menu_bar.Append(file_menu, '&File')
+
+        # Adding the menu bar to the frame content
+        self.SetMenuBar(menu_bar)
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'MenuBar and StatusBar')
+app.MainLoop()

docs/sphinx/_downloads/MoveEvent.1.py

@@ -0,0 +1,36 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to listen to a move change event for a 
+# top-level window (wx.Frame, wx.Dialog). This is MSW-specific
+
+import wx
+
+class MovingFrame(wx.Frame):
+           
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+        
+        wx.StaticText(self, label='x:', pos=(10, 10))
+        wx.StaticText(self, label='y:', pos=(10, 30))
+        
+        self.st1 = wx.StaticText(self, label='', pos=(30, 10))
+        self.st2 = wx.StaticText(self, label='', pos=(30, 30))
+
+        self.Bind(wx.EVT_MOVE, self.OnMove)
+
+        self.Show()  
+        
+    def OnMove(self, event):
+        
+        # Capture the mouse position (in screen coordinates) and
+        # assign its x, y values to the statictexts
+        x, y = event.GetPosition()
+        self.st1.SetLabel('%d'%x)
+        self.st2.SetLabel('%d'%y)
+
+    
+app = wx.App(False)
+frame = MovingFrame(None, 'MoveEvent example')
+app.MainLoop()

docs/sphinx/_downloads/Notebook.1.py

@@ -0,0 +1,75 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample creates a "File->Open" menu, and lets the user select
+# a Python file. Upon selection, the file is read in memory and a new
+# wx.TextCtrl showing the file content is added as a page of a wx.Notebook
+
+import wx
+import os
+
+class NotebookFrame(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Create the notebook 
+        self.notebook = wx.Notebook(self, style=wx.NB_BOTTOM)
+
+        # Setting up the menu
+        file_menu = wx.Menu()
+
+        # wx.ID_OPEN
+        menu_item = file_menu.Append(wx.ID_OPEN, '&Open...', 'Open and read a new Python file')
+        # Bind the "select menu item" event to the OnOpen event handler
+        self.Bind(wx.EVT_MENU, self.OnOpen, menu_item)
+
+        # Creating the menubar
+        menu_bar = wx.MenuBar()
+
+        # Adding the 'file_menu' to the menu bar
+        menu_bar.Append(file_menu, '&File')
+        
+        # Adding the menu bar to the frame content
+        self.SetMenuBar(menu_bar)
+
+        self.Show()
+
+
+    def OnOpen(self, event):
+
+        # This is how you pre-establish a file filter so that the dialog
+        # only shows the extension(s) you want it to.
+        wildcard = 'Python source (*.py)|*.py'
+        
+        dlg = wx.FileDialog(None, message="Choose a Python file", defaultDir=os.getcwd(), 
+                            defaultFile="", wildcard=wildcard, style=wx.FD_OPEN)
+
+        # Show the dialog and retrieve the user response. If it is the OK response, 
+        # process the data.
+        if dlg.ShowModal() == wx.ID_OK:
+            # This returns the file that was selected
+            path = dlg.GetPath()
+
+            # Open the file as read-only and slurp its content
+            fid = open(path, 'rt')
+            text = fid.read()
+            fid.close()
+
+            # Create the notebook page as a wx.TextCtrl and
+            # add it as a page of the wx.Notebook
+            text_ctrl = wx.TextCtrl(self.notebook, style=wx.TE_MULTILINE)
+            text_ctrl.SetValue(text)
+
+            filename = os.path.split(os.path.splitext(path)[0])[1]
+            self.notebook.AddPage(text_ctrl, filename, select=True)
+
+        # Destroy the dialog. Don't do this until you are done with it!
+        # BAD things can happen otherwise!
+        dlg.Destroy()
+
+
+app = wx.App(False)
+frame = NotebookFrame(None, 'Notebook example')
+app.MainLoop()

docs/sphinx/_downloads/PaintDC.1.py

@@ -0,0 +1,44 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample uses the random module to draw 100 random lines iinside
+# a wx.Frame client area, as a demonstration of how to handle a wx.PaintDC
+
+import wx
+import random
+
+class PaintFrame(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind a "paint" event for the frame to the
+        # "OnPaint" method
+        self.Bind(wx.EVT_PAINT, self.OnPaint)
+        self.Show()
+
+
+    def OnPaint(self, event):
+
+        dc = wx.PaintDC(self)        
+        w, h = self.GetClientSize()
+
+        # Use a blue pen, for example...
+
+        dc.SetPen(wx.Pen('BLUE'))
+        
+        # Remember the signature of wx.DC.DrawLine:
+        # DrawLine(x1, y1, x2, y2)
+        
+        for i in range(100):
+            x1 = random.randint(1, w-1)
+            y1 = random.randint(1, h-1)
+            x2 = random.randint(1, w-1)
+            y2 = random.randint(1, h-1)
+            dc.DrawLine(x1, y1, x2, y2)
+
+            
+app = wx.App(False)
+frame = PaintFrame(None, 'PaintDC example')
+app.MainLoop()

docs/sphinx/_downloads/Process.1.py

@@ -0,0 +1,73 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample demonstrates a simple use of wx.Process/wx.Execute to
+# monitor an external program stdout
+
+import wx
+
+class ProcessFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='Process/Execute example')
+
+        panel = wx.Panel(self)
+        self.label = wx.TextCtrl(panel, style=wx.TE_MULTILINE)
+        self.btn = wx.Button(panel, label="Start")
+
+        self.process = None
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+        self.Bind(wx.EVT_IDLE, self.OnIdle)
+        self.Bind(wx.EVT_END_PROCESS, self.OnProcessEnded)
+        
+    def OnButton(self, event):
+        self.btn.Enable(False)
+        self.label.SetValue('')
+        self.LongRunning()
+
+    def LongRunning(self):
+        """
+        This runs in the GUI thread but uses wx.Process and
+        wx.Execute to start and monitor a separate process.
+        """
+
+        cmd = 'python -u external_program.py'
+
+        self.process = wx.Process(self)
+        self.process.Redirect()
+
+        wx.Execute(cmd, wx.EXEC_ASYNC, self.process)
+
+    def OnIdle(self, event):
+        """ This event handler catches the process stdout. """
+
+        if self.process is not None:
+            stream = self.process.GetInputStream()
+            if stream.CanRead():
+                text = stream.read()
+                self.label.AppendText(text)
+
+    def OnProcessEnded(self, event):
+
+        stream = self.process.GetInputStream()
+
+        if stream.CanRead():
+            text = stream.read()
+            self.label.AppendText(text)
+
+        self.btn.Enable(True)
+        self.label.AppendText('Finished')
+
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = ProcessFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_downloads/SplitterWindow.1.py

@@ -0,0 +1,43 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a "spli-split" window, i.e. a
+# window split verticall which contains two windows split horizontally
+
+import wx
+
+class SplitterFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, title='SplitterWindow example')
+
+        # Create the main splitter window (to be split vertically)
+        splitter = wx.SplitterWindow(self, -1, style=wx.SP_LIVE_UPDATE)
+        splitter.SetMinimumPaneSize(100)
+        
+        panel1 = wx.Panel(splitter, -1)
+
+        static = wx.StaticText(panel1, -1, 'Hello World', pos=(10, 100))
+        panel1.SetBackgroundColour(wx.WHITE)
+
+        # Create the second splitter window (to be split horizontally)
+        splitter2 = wx.SplitterWindow(splitter, -1, style=wx.SP_LIVE_UPDATE)
+        splitter2.SetMinimumPaneSize(100)
+        
+        panel2 = wx.Panel(splitter2, -1)
+        panel2.SetBackgroundColour(wx.BLUE)
+
+        panel3 = wx.Panel(splitter2, -1)
+        panel3.SetBackgroundColour(wx.RED)
+
+        splitter2.SplitHorizontally(panel2, panel3)
+        splitter.SplitVertically(panel1, splitter2)
+        self.Centre()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = SplitterFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_downloads/StatusBar.SetStatusWidths.1.py

@@ -0,0 +1,35 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a wx.StatusBar with 2 fields, 
+# set the second field to have double width with respect to the 
+# first and and display the date of today in the second field.
+
+import wx
+import datetime
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        # Set it up so it has two fields
+        self.CreateStatusBar(2)
+
+        # Set the second field to be double in width wrt the first
+        self.SetStatusWidths([-1, -2])
+
+        # Get today date via datetime
+        today = datetime.datetime.today()
+        today = today.strftime('%d-%b-%Y')
+
+        # Set today date in the second field
+        self.SetStatusText(today, 1)
+
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'SetStatusWidths example')
+app.MainLoop()

docs/sphinx/_downloads/TreeCtrl.1.py

@@ -0,0 +1,51 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample classifies the Python keywords alphabetically, using the 
+# first letter of the keyword (i.e., ``and`` goes into ``a``, ``for`` 
+# goes into ``f`` and so on):
+#      
+#      * For each letter, adds a child to the treectrl root
+#      * In each child of the root item, adds its corresponding keyword(s)
+#
+
+import wx
+import keyword
+import string
+
+class TreeFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, title='TreeCtrl example')
+
+        tree_ctrl = wx.TreeCtrl(self, -1, style=wx.TR_DEFAULT_STYLE | \
+                                                wx.TR_FULL_ROW_HIGHLIGHT | \
+                                                wx.TR_EDIT_LABELS)
+
+        # Add the tree root
+        root = tree_ctrl.AddRoot('Python keywords')
+
+        letters = []
+        
+        for kwd in keyword.kwlist:
+            first = kwd[0]
+            if first not in letters:
+                letters.append(first)
+
+        for letter in letters:
+            item = tree_ctrl.AppendItem(root, letter)
+            for kwd in keyword.kwlist:
+                first = kwd[0]
+                if first == letter:
+                    sub_item = tree_ctrl.AppendItem(item, kwd)
+                    
+        tree_ctrl.ExpandAll()
+        self.Centre()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = TreeFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_downloads/functions.CallAfter.1.py

@@ -0,0 +1,57 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows hot to take advantage of wx.CallAfter when running a
+# separate thread and updating the GUI in the main thread
+
+import wx
+import threading
+import time
+
+class MainFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='CallAfter example')
+
+        panel = wx.Panel(self)
+        self.label = wx.StaticText(panel, label="Ready")
+        self.btn = wx.Button(panel, label="Start")
+        self.gauge = wx.Gauge(panel)
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+        sizer.Add(self.gauge, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+    def OnButton(self, event):
+        """ This event handler starts the separate thread. """
+        self.btn.Enable(False)
+        self.gauge.SetValue(0)
+        self.label.SetLabel("Running")
+
+        thread = threading.Thread(target=self.LongRunning)
+        thread.start()
+
+    def OnLongRunDone(self):
+        self.gauge.SetValue(100)
+        self.label.SetLabel("Done")
+        self.btn.Enable(True)
+
+    def LongRunning(self):
+        """This runs in a different thread.  Sleep is used to
+         simulate a long running task."""
+        time.sleep(3)
+        wx.CallAfter(self.gauge.SetValue, 20)
+        time.sleep(5)
+        wx.CallAfter(self.gauge.SetValue, 70)
+        time.sleep(4)
+        wx.CallAfter(self.OnLongRunDone)
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = MainFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_downloads/functions.Execute.1.py

@@ -0,0 +1,73 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample demonstrates a simple use of wx.Process/wx.Execute to
+# monitor an external program stdout
+
+import wx
+
+class ProcessFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='Process/Execute example')
+
+        panel = wx.Panel(self)
+        self.label = wx.TextCtrl(panel, style=wx.TE_MULTILINE)
+        self.btn = wx.Button(panel, label="Start")
+
+        self.process = None
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+        self.Bind(wx.EVT_IDLE, self.OnIdle)
+        self.Bind(wx.EVT_END_PROCESS, self.OnProcessEnded)
+        
+    def OnButton(self, event):
+        self.btn.Enable(False)
+        self.label.SetValue('')
+        self.LongRunning()
+
+    def LongRunning(self):
+        """
+        This runs in the GUI thread but uses wx.Process and
+        wx.Execute to start and monitor a separate process.
+        """
+
+        cmd = 'python -u external_program.py'
+
+        self.process = wx.Process(self)
+        self.process.Redirect()
+
+        wx.Execute(cmd, wx.EXEC_ASYNC, self.process)
+
+    def OnIdle(self, event):
+        """ This event handler catches the process stdout. """
+
+        if self.process is not None:
+            stream = self.process.GetInputStream()
+            if stream.CanRead():
+                text = stream.read()
+                self.label.AppendText(text)
+
+    def OnProcessEnded(self, event):
+
+        stream = self.process.GetInputStream()
+
+        if stream.CanRead():
+            text = stream.read()
+            self.label.AppendText(text)
+
+        self.btn.Enable(True)
+        self.label.AppendText('Finished')
+
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = ProcessFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/_static/css/tables.css

@@ -55,3 +55,31 @@
 {
   background: #E0E0E0 url('../images/sphinxdocs/cell-grey.jpg');
 }
+
+.centertable
+{
+    margin-bottom: 2em;
+}
+
+.centertable th.head
+{
+    font-weight: bold;
+    text-align: left;
+    border-bottom: 1px solid black;
+    padding-right: .5em;
+}
+
+.centertable th.field-name
+{
+    font-weight: bold;
+    text-align: left;
+    padding-right: 1em;
+}
+
+.centertable th {
+    background-color: #ede;
+}
+
+.centertable td {
+    vertical-align: middle;
+}

docs/sphinx/rest_substitutions/overviews/sizers_overview.rst

@@ -106,6 +106,418 @@ two buttons have a stretch factor of zero and keep their initial width:
 Within wxDesigner, this stretch factor gets set from the `Option` menu.
 
 
+`wx.Sizers` - the visual approach
+---------------------------------
+
+
+----------------------------
+Basic way of adding a window
+----------------------------
+
+Let's take a look at :class:`BoxSizer`.
+This is the most simple type of box sizer, and the way we add widgets to it is explained by looking
+at the :meth:`BoxSizer.Add` signature:
+
+.. raw:: html
+
+   <hr color="#A9A9A9">
+
+.. method:: Add(window, proportion=0, flag=0, border=0, userData=None)
+
+   Appends a child to the sizer.
+
+   :param `window`: a window, a spacer or another sizer to be added to the sizer. Its initial size 
+    (either set explicitly by the user or calculated internally) is interpreted as the minimal and 
+    in many cases also the initial size.
+   :param int proportion: this parameter is used in :class:`BoxSizer` to indicate if a child of a sizer 
+    can change its size in the main orientation of the :class:`BoxSizer` - where 0 stands for not changeable 
+    and a value of more than zero is interpreted relative to the value of other children of the same 
+    :class:`BoxSizer`. For example, you might have a horizontal :class:`BoxSizer` with three children, two 
+    of which are supposed to change their size with the sizer. Then the two stretchable windows would 
+    get a value of 1 each to make them grow and shrink equally with the sizer's horizontal dimension.
+   :param int flag: OR-combination of flags affecting sizer's behaviour.
+   :param int border: determines the border width, if the flag parameter is set to include any border flag.
+   :param object userData: allows an extra object to be attached to the sizer item, for use in derived 
+    classes when sizing information is more complex than the proportion and flag will allow for.
+    
+   :rtype: :class:`SizerItem`
+
+.. raw:: html
+
+   <hr color="#A9A9A9">
+
+
+Let's create a vertical sizer (children will be placed on top of each other) and place two buttons in it.
+All the "extra" parameters are set to 0; we'll worry about them later.
+
+.. figure:: _static/images/overviews/boxsizer1.png
+   :class: floatright
+
+::
+
+    sizer = wx.BoxSizer(wx.VERTICAL)
+    sizer.Add(wx.Button(self, -1, 'An extremely long button text'), 0, 0, 0)
+    sizer.Add(wx.Button(self, -1, 'Small button'), 0, 0, 0)
+    self.SetSizer(sizer)
+    
+
+You'll notice a couple of things about this:
+
+* The buttons are just big enough to accommodate the text in them. In fact, any control placed
+  into a sizer this way will appear at its minimum size unless we change the parameters.
+* The window size is not changed to fit the sizer. This results in a lot of ugly empty space.
+
+
+Let's worry about the second issue first. To make the window size more appropriate, we can set 
+the size hints to tell the enclosing window to adjust to the size of the sizer:
+
+.. figure:: _static/images/overviews/boxsizer2.png
+   :class: floatright
+
+.. code-block:: python
+   :emphasize-lines: 4
+
+    sizer = wx.BoxSizer(wx.VERTICAL)
+    sizer.Add(wx.Button(self, -1, 'An extremely long button text'), 0, 0, 0)
+    sizer.Add(wx.Button(self, -1, 'Small button'), 0, 0, 0)
+    sizer.SetSizeHints(self)
+    self.SetSizer(sizer)
+
+This is particularly useful in circumstances like this one, in which the :class:`Frame`'s default size 
+would otherwise be much too big or small to show most layouts in an aesthetically pleasing manner.
+
+--------------------------
+The `proportion` parameter
+--------------------------
+
+The first parameter to :meth:`BoxSizer.Add`
+is obviously the :class:`Window` or :class:`Sizer` that you are adding. The second one (the `proportion`)
+defines how large the sizer's children are in relation to each other. In a vertical sizer, this changes
+the height; in a horizontal sizer, this changes the width. Here are some examples:
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 40 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 3,4
+
+		  sizer = wx.BoxSizer(wx.VERTICAL)
+		  # Second button is three times as tall as first button
+		  sizer.Add(wx.Button(self, -1, 'An extremely long button text'), 1, 0, 0)
+		  sizer.Add(wx.Button(self, -1, 'Small button'), 3, 0, 0)
+		  sizer.SetSizeHints(self)
+		  self.SetSizer(sizer)
+
+     - .. figure:: _static/images/overviews/boxsizer3.png
+          :align: left
+
+   * - Same code as above, with window resized. Notice that the bottom button is still three times as tall as the top button.
+
+     - .. figure:: _static/images/overviews/boxsizer31.png
+          :align: left
+
+   * - .. code-block:: python
+          :emphasize-lines: 3,4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # First button is 3/2 the height of the second button
+          sizer.Add(wx.Button(self, -1, 'An extremely long button text'), 3, 0, 0)
+          sizer.Add(wx.Button(self, -1, 'Small button'), 2, 0, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+     - .. figure:: _static/images/overviews/boxsizer32.png
+          :align: left
+		  
+
+|
+
+If one of the `proportion` parameters is 0, that :class:`Window` will be the minimum size, and the others 
+will resize proportionally:
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 40 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 4,5
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Third button is twice the size of the second button
+          sizer.Add(wx.Button(self, -1, 'An extremely long button text'), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, 'Small button'), 1, 0, 0)
+          sizer.Add(wx.Button(self, -1, 'Another button'), 2, 0, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+     - .. figure:: _static/images/overviews/boxsizer33.png
+          :align: left
+
+   * - Same code as above, with window resized. The top button (proportion 0) is still the minimum height, 
+       and the third button is still twice the height of the second.
+
+     - .. figure:: _static/images/overviews/boxsizer34.png
+          :align: left
+
+
+This is especially useful when you want, for example, a button at the bottom which is only
+as big as necessary, and some other control that occupies the rest of the frame. To do so, 
+give the button proportion 0 and the other control a number greater than 0. Mac users in 
+particular will appreciate you for not creating huge aqua-styled buttons.
+
+
+-----------------------------------
+The `flags` and `border` parameters
+-----------------------------------
+
+The `flag` argument accepted by :meth:`Sizer.Add`
+is a ``OR``-combination of the following flags. Two main behaviours are defined using these flags. One is 
+the border around a window: the `border` parameter determines the border width whereas the flags given here 
+determine which side(s) of the item that the border will be added. The other flags determine how the sizer 
+item behaves when the space allotted to the sizer changes, and is somewhat dependent on the specific kind 
+of sizer used.
+
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| Sizer Flag                                                          | Description                                                                 |
++=====================================================================+=============================================================================+
+| ``TOP``                                                             | These flags are used to specify which side(s) of the sizer                  |
++---------------------------------------------------------------------+ item the border width will apply to.                                        | 
+| ``BOTTOM``                                                          |                                                                             |
++---------------------------------------------------------------------+                                                                             |
+| ``LEFT``                                                            |                                                                             |
++---------------------------------------------------------------------+                                                                             |
+| ``RIGHT``                                                           |                                                                             |
++---------------------------------------------------------------------+                                                                             |
+| ``ALL``                                                             |                                                                             |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| ``EXPAND``                                                          | The item will be expanded to fill the space assigned to                     |
+|                                                                     | the item.                                                                   |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| ``SHAPED``                                                          | The item will be expanded as much as possible while also                    |
+|                                                                     | maintaining its aspect ratio                                                |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| ``FIXED_MINSIZE``                                                   | If you would rather have a window item stay the size it started with then   |
+|                                                                     | use ``FIXED_MINSIZE``                                                       |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| ``RESERVE_SPACE_EVEN_IF_HIDDEN``                                    | Normally `Sizers` don't allocate space for hidden windows or other items.   | 
+|                                                                     | This flag overrides this behavior so that sufficient space is allocated for |
+|                                                                     | the window even if it isn't visible. This makes it possible to dynamically  |
+|                                                                     | show and hide controls without resizing parent dialog, for example.         |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+| ``ALIGN_CENTER`` **or** ``ALIGN_CENTRE``                            | The ``ALIGN*`` flags allow you to specify the alignment of the item         |
++---------------------------------------------------------------------+ within the space allotted to it by the sizer, adjusted for the border if    |
+| ``ALIGN_LEFT``                                                      | any.                                                                        |
++---------------------------------------------------------------------+                                                                             | 
+| ``ALIGN_RIGHT``                                                     |                                                                             |
++---------------------------------------------------------------------+                                                                             | 
+| ``ALIGN_TOP``                                                       |                                                                             |
++---------------------------------------------------------------------+                                                                             | 
+| ``ALIGN_BOTTOM``                                                    |                                                                             |
++---------------------------------------------------------------------+                                                                             | 
+| ``ALIGN_CENTER_VERTICAL`` **or** ``ALIGN_CENTRE_VERTICAL``          |                                                                             |
++---------------------------------------------------------------------+                                                                             | 
+| ``ALIGN_CENTER_HORIZONTAL`` **or** ``ALIGN_CENTRE_HORIZONTAL``      |                                                                             |
++---------------------------------------------------------------------+-----------------------------------------------------------------------------+
+
+|
+
+
+Let's start with the simplest case: the alignment flags. These are pretty self-explanatory.
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 40 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Second button is right aligned
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.ALIGN_RIGHT, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+
+     - .. figure:: _static/images/overviews/boxsizer4.png
+          :align: left
+
+
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Second button is center-aligned
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.ALIGN_CENTER, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+
+     - .. figure:: _static/images/overviews/boxsizer41.png
+          :align: left
+
+
+
+Next is the ``EXPAND`` flag. This is synonymous with ``GROW``.
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 40 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Second button expands to the whole parent's width
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.EXPAND, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+
+     - .. figure:: _static/images/overviews/boxsizer5.png
+          :align: left
+
+
+
+You can see that the first button takes its minimum size, and the second one grows to match it. This affects 
+controls in the opposite manner of the second parameter; ``EXPAND`` in a vertical sizer causes horizontal 
+expansion, and in a horizontal sizer it causes vertical expansion.
+
+Next is ``SHAPED``. This flag ensures that the width and height of the object stay proportional to each other. 
+It doesn't make much sense for buttons, but can be excellent for bitmaps, which would be contorted or clipped 
+if not scaled proportionally.
+
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 30 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Second button will scale proportionally
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 1, wx.SHAPED, 0)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+
+
+     - .. figure:: _static/images/overviews/boxsizer51.png
+          :align: left
+
+   * - Same code as above, with window resized. The width grew dramatically with the height. In fact, it didn't 
+       quite grow vertically the whole way because it couldn't maintain the correct ratio while doing so.
+
+     - .. figure:: _static/images/overviews/boxsizer52.png
+          :align: left
+
+
+Finally, we have the border flags. These only make sense when the `border` parameter is greater than 0, and describe 
+the sides of the control on which the border should appear. In order to demonstrate this most clearly, we'll keep 
+the ``EXPAND`` flag.
+
+
+.. list-table:: 
+   :header-rows: 1
+   :widths: 40 10
+   :class: centertable
+
+   * - Code
+   
+     - Resulting Image
+   
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Border size effects
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.EXPAND | wx.LEFT, 20)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+          
+          
+     - .. figure:: _static/images/overviews/boxsizer53.png
+          :align: left
+          
+
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Border size effects
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.EXPAND | wx.LEFT | wx.RIGHT, 20)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+          
+          
+     - .. figure:: _static/images/overviews/boxsizer54.png
+          :align: left
+          
+
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Border size effects
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.EXPAND | wx.LEFT | wx.RIGHT | wx.TOP, 20)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+          
+          
+     - .. figure:: _static/images/overviews/boxsizer55.png
+          :align: left
+
+   * - .. code-block:: python
+          :emphasize-lines: 4
+
+          sizer = wx.BoxSizer(wx.VERTICAL)
+          # Border size effects
+          sizer.Add(wx.Button(self, -1, "An extremely long button text"), 0, 0, 0)
+          sizer.Add(wx.Button(self, -1, "Small Button"), 0, wx.EXPAND | wx.ALL, 20)
+          sizer.SetSizeHints(self)
+          self.SetSizer(sizer)
+          
+          
+     - .. figure:: _static/images/overviews/boxsizer56.png
+          :align: left
+
+
+You can see that the button is offset from the specified edges of the sizer by the number of pixels that we
+specified in the `border` parameter.
+
+
 Hiding Controls Using Sizers
 ----------------------------
 
@@ -118,9 +530,9 @@ This is useful when hiding parts of the interface, since you can avoid removing
 .. note:: This is supported only by :ref:`BoxSizer` and :ref:`FlexGridSizer`.
 
 
-
+--------
 BoxSizer
-^^^^^^^^
+--------
 
 :ref:`BoxSizer` can lay out its children either vertically or horizontally, depending on what flag is being used in its constructor. 
 When using a vertical sizer, each child can be centered, aligned to the right or aligned to the left. Correspondingly, when using a 
@@ -132,9 +544,9 @@ be stretched horizontally. The following sample shows the same dialog as in the
    :align: center
 
 
-
+--------------
 StaticBoxSizer
-^^^^^^^^^^^^^^
+--------------
 
 :class:`StaticBoxSixer` is the same as a :class:`BoxSizer`, but surrounded by a static box. Here is a sample:
 
@@ -143,9 +555,9 @@ StaticBoxSizer
    :align: center
 
 
-
+---------
 GridSizer
-^^^^^^^^^
+---------
 
 :ref:`GridSizer` is a two-dimensional sizer. All children are given the same size, which is the minimal size required by the biggest
 child, in this case the text control in the left bottom border. Either the number of columns or the number or rows is fixed and the grid
@@ -158,9 +570,9 @@ sizer will grow in the respectively other orientation if new children are added:
 
 For programming information, see :ref:`GridSizer`.
 
-
+-------------
 FlexGridSizer
-^^^^^^^^^^^^^
+-------------
 
 Another two-dimensional sizer derived from :ref:`GridSizer`. The width of each column and the height of each row are calculated individually
 according to the minimal requirements from the respectively biggest child. Additionally, columns and rows can be declared to be stretchable 

docs/sphinx/rest_substitutions/snippets/python/contrib/ArtProvider.GetBitmap.1.py

@@ -0,0 +1,43 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to retrieve default platform's 
+# bitmaps using wx.ArtProvider
+
+import wx
+
+class BitmapFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, -1, title='ArtProvider example')
+
+        panel = wx.Panel(self)
+
+        main_sizer = wx.BoxSizer(wx.VERTICAL)
+        bitmap_sizer = wx.BoxSizer(wx.HORIZONTAL)
+
+        bitmap_sizer.Add((0, 0), 1, wx.EXPAND)
+        
+        # Show a few bitmaps retrieved via wx.ArtProvider
+        for kind in [wx.ART_INFORMATION, wx.ART_WARNING, wx.ART_CDROM, wx.ART_CUT]:
+            bmp = wx.ArtProvider.GetBitmap(kind, wx.ART_OTHER, (32, 32))
+            static_bitmap = wx.StaticBitmap(panel, -1, bmp)
+            bitmap_sizer.Add(static_bitmap, 0, wx.ALL, 5)
+
+        # Layout everything in a nice sizer
+        bitmap_sizer.Add((0, 0), 1, wx.EXPAND)
+        main_sizer.Add((0, 0), 1, wx.EXPAND)
+        main_sizer.Add(bitmap_sizer, 0, wx.EXPAND)
+        main_sizer.Add((0, 0), 1, wx.EXPAND)
+
+        panel.SetSizer(main_sizer)
+        main_sizer.SetSizeHints(panel)
+        main_sizer.Layout()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = BitmapFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/CloseEvent.Veto.1.py

@@ -0,0 +1,34 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample makes the main frame "immortal", i.e., non-closable 
+# by the user. The main window can not be close by pressing Alt+F4
+# or by clicking on the "X" button in the titlebar
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind the "close window" event to the OnClose handler
+        self.Bind(wx.EVT_CLOSE, self.OnClose)
+
+        self.Show()
+        self.close_attempts = 0
+
+        
+    def OnClose(self, event):
+
+        # Veto the event the user can not close the main
+        # window in any way
+        self.close_attempts += 1
+        print('I am immortal %d'%self.close_attempts)
+        event.Veto()
+
+
+app = wx.App(False)
+frame = MainWindow(None, 'Immortal Frame')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/Colour.1.py

@@ -0,0 +1,32 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to assign different fonts to various
+# wx.StaticTexts
+
+import wx
+
+app = wx.App(0)
+frame = wx.Frame(None, -1, 'Colour settings')
+
+text_ctrl_1 = wx.TextCtrl(frame, -1, 'Some text')
+text_ctrl_1.SetBackgroundColour(wx.Colour(0, 0, 255))
+# OR
+text_ctrl_2 = wx.TextCtrl(frame, -1, 'Other text')
+text_ctrl_2.SetBackgroundColour('BLUE')
+# OR
+text_ctrl_3 = wx.TextCtrl(frame, -1, 'Another text')
+text_ctrl_3.SetBackgroundColour('#0000FF')
+
+# Size up everything in a nice vertical box sizer
+sizer = wx.BoxSizer(wx.VERTICAL)
+sizer.Add(text_ctrl_1, 0, wx.EXPAND|wx.ALL, 10)
+sizer.Add(text_ctrl_2, 0, wx.EXPAND|wx.LEFT|wx.RIGHT, 10)
+sizer.Add(text_ctrl_3, 0, wx.EXPAND|wx.ALL, 10)
+frame.SetSizer(sizer)
+sizer.SetSizeHints(frame)
+
+frame.Show()
+
+# Enter the application main loop
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/EvtHandler.Bind.1.py

@@ -0,0 +1,36 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows a simple example of how to use the
+# "Bind" method to handle an event
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind the "close window" event to the OnClose handler
+        self.Bind(wx.EVT_CLOSE, self.OnClose)
+
+        self.Show()
+
+        
+    def OnClose(self, event):
+
+        # This displays a message box asking the user to confirm
+        # she wants to quit the application
+        dlg = wx.MessageDialog(self, 'Are you sure you want to quit?', 'Question',
+                               wx.YES_NO | wx.NO_DEFAULT | wx.ICON_QUESTION)
+
+        if dlg.ShowModal() == wx.ID_YES:
+            self.Destroy()
+        else:
+            event.Veto()
+
+
+app = wx.App(False)
+frame = MainWindow(None, 'Bind example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/Font.1.py

@@ -0,0 +1,63 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to assign different fonts to various
+# wx.StaticTexts
+
+import wx
+
+class FontFrame(wx.Frame):
+
+   def __init__(self, parent):
+
+        wx.Frame.__init__(self, parent, title='Font sample')
+
+        panel = wx.Panel(self, -1)
+
+        text1 = '''Lasciatemi cantare
+con la chitarra in mano
+lasciatemi cantare
+sono un italiano'''
+
+        text2 = '''Buongiorno Italia gli spaghetti al dente
+e un partigiano come Presidente
+con l'autoradio sempre nella mano destra
+e un canarino sopra la finestra'''
+
+        text3 = '''Buongiorno Italia con i tuoi artisti
+con troppa America sui manifesti
+con le canzoni con amore con il cuore
+con piu' donne sempre meno suore'''
+
+        # Construct 2 font objects from the wx.Font constructor
+        font1 = wx.Font(10, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_ITALIC, wx.FONTWEIGHT_NORMAL)
+        font2 = wx.Font(10, wx.FONTFAMILY_MODERN, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD)
+
+        # A font can be retrieved from the OS default font
+        # and modified
+        font3 = wx.SystemSettings.GetFont(wx.SYS_DEFAULT_GUI_FONT)
+        font3.SetStyle(wx.FONTSTYLE_ITALIC)
+        font3.SetPointSize(12)
+
+        lyrics1 = wx.StaticText(panel, -1, text1, style=wx.ALIGN_CENTRE)
+        lyrics1.SetFont(font1)
+        lyrics2 = wx.TextCtrl(panel, -1, text2, style=wx.TE_CENTER|wx.TE_MULTILINE)
+        lyrics2.SetFont(font2)
+        lyrics3 = wx.StaticText(panel, -1, text3, style=wx.ALIGN_CENTRE)
+        lyrics3.SetFont(font3)
+
+        # Size up everything in a nice vertical box sizer
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(lyrics1, 0, wx.EXPAND|wx.ALL, 10)
+        sizer.Add(lyrics2, 0, wx.EXPAND|wx.LEFT|wx.RIGHT, 10)
+        sizer.Add(lyrics3, 0, wx.EXPAND|wx.ALL, 10)
+        panel.SetSizer(sizer)
+        sizer.SetSizeHints(panel)
+        self.Center()
+
+
+app = wx.App(0)
+frame = FontFrame(None)
+frame.Show()
+# Enter the application main loop
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/Frame.SetStatusWidths.1.py

@@ -0,0 +1,35 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a wx.StatusBar with 2 fields, 
+# set the second field to have double width with respect to the 
+# first and and display the date of today in the second field.
+
+import wx
+import datetime
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        # Set it up so it has two fields
+        self.CreateStatusBar(2)
+
+        # Set the second field to be double in width wrt the first
+        self.SetStatusWidths([-1, -2])
+
+        # Get today date via datetime
+        today = datetime.datetime.today()
+        today = today.strftime('%d-%b-%Y')
+
+        # Set today date in the second field
+        self.SetStatusText(today, 1)
+
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'SetStatusWidths example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/MenuBar.1.py

@@ -0,0 +1,40 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a simple wx.MenuBar
+# and a simple wx.StatusBar
+
+import wx
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        self.CreateStatusBar()
+
+        # Setting up the menu
+        file_menu = wx.Menu()
+
+        # wx.ID_ABOUT and wx.ID_EXIT are standard IDs provided
+        # by wxWidgets.
+        file_menu.Append(wx.ID_ABOUT, '&About',
+                         'Information about this application')
+        file_menu.AppendSeparator()
+        file_menu.Append(wx.ID_EXIT, 'E&xit', 'Exit the application')
+
+        # Creating the menubar
+        menu_bar = wx.MenuBar()
+
+        # Adding the 'file_menu' to the menu bar
+        menu_bar.Append(file_menu, '&File')
+
+        # Adding the menu bar to the frame content
+        self.SetMenuBar(menu_bar)
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'MenuBar and StatusBar')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/MoveEvent.1.py

@@ -0,0 +1,36 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to listen to a move change event for a 
+# top-level window (wx.Frame, wx.Dialog). This is MSW-specific
+
+import wx
+
+class MovingFrame(wx.Frame):
+           
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+        
+        wx.StaticText(self, label='x:', pos=(10, 10))
+        wx.StaticText(self, label='y:', pos=(10, 30))
+        
+        self.st1 = wx.StaticText(self, label='', pos=(30, 10))
+        self.st2 = wx.StaticText(self, label='', pos=(30, 30))
+
+        self.Bind(wx.EVT_MOVE, self.OnMove)
+
+        self.Show()  
+        
+    def OnMove(self, event):
+        
+        # Capture the mouse position (in screen coordinates) and
+        # assign its x, y values to the statictexts
+        x, y = event.GetPosition()
+        self.st1.SetLabel('%d'%x)
+        self.st2.SetLabel('%d'%y)
+
+    
+app = wx.App(False)
+frame = MovingFrame(None, 'MoveEvent example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/Notebook.1.py

@@ -0,0 +1,75 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample creates a "File->Open" menu, and lets the user select
+# a Python file. Upon selection, the file is read in memory and a new
+# wx.TextCtrl showing the file content is added as a page of a wx.Notebook
+
+import wx
+import os
+
+class NotebookFrame(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Create the notebook 
+        self.notebook = wx.Notebook(self, style=wx.NB_BOTTOM)
+
+        # Setting up the menu
+        file_menu = wx.Menu()
+
+        # wx.ID_OPEN
+        menu_item = file_menu.Append(wx.ID_OPEN, '&Open...', 'Open and read a new Python file')
+        # Bind the "select menu item" event to the OnOpen event handler
+        self.Bind(wx.EVT_MENU, self.OnOpen, menu_item)
+
+        # Creating the menubar
+        menu_bar = wx.MenuBar()
+
+        # Adding the 'file_menu' to the menu bar
+        menu_bar.Append(file_menu, '&File')
+        
+        # Adding the menu bar to the frame content
+        self.SetMenuBar(menu_bar)
+
+        self.Show()
+
+
+    def OnOpen(self, event):
+
+        # This is how you pre-establish a file filter so that the dialog
+        # only shows the extension(s) you want it to.
+        wildcard = 'Python source (*.py)|*.py'
+        
+        dlg = wx.FileDialog(None, message="Choose a Python file", defaultDir=os.getcwd(), 
+                            defaultFile="", wildcard=wildcard, style=wx.FD_OPEN)
+
+        # Show the dialog and retrieve the user response. If it is the OK response, 
+        # process the data.
+        if dlg.ShowModal() == wx.ID_OK:
+            # This returns the file that was selected
+            path = dlg.GetPath()
+
+            # Open the file as read-only and slurp its content
+            fid = open(path, 'rt')
+            text = fid.read()
+            fid.close()
+
+            # Create the notebook page as a wx.TextCtrl and
+            # add it as a page of the wx.Notebook
+            text_ctrl = wx.TextCtrl(self.notebook, style=wx.TE_MULTILINE)
+            text_ctrl.SetValue(text)
+
+            filename = os.path.split(os.path.splitext(path)[0])[1]
+            self.notebook.AddPage(text_ctrl, filename, select=True)
+
+        # Destroy the dialog. Don't do this until you are done with it!
+        # BAD things can happen otherwise!
+        dlg.Destroy()
+
+
+app = wx.App(False)
+frame = NotebookFrame(None, 'Notebook example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/PaintDC.1.py

@@ -0,0 +1,44 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample uses the random module to draw 100 random lines iinside
+# a wx.Frame client area, as a demonstration of how to handle a wx.PaintDC
+
+import wx
+import random
+
+class PaintFrame(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # Bind a "paint" event for the frame to the
+        # "OnPaint" method
+        self.Bind(wx.EVT_PAINT, self.OnPaint)
+        self.Show()
+
+
+    def OnPaint(self, event):
+
+        dc = wx.PaintDC(self)        
+        w, h = self.GetClientSize()
+
+        # Use a blue pen, for example...
+
+        dc.SetPen(wx.Pen('BLUE'))
+        
+        # Remember the signature of wx.DC.DrawLine:
+        # DrawLine(x1, y1, x2, y2)
+        
+        for i in range(100):
+            x1 = random.randint(1, w-1)
+            y1 = random.randint(1, h-1)
+            x2 = random.randint(1, w-1)
+            y2 = random.randint(1, h-1)
+            dc.DrawLine(x1, y1, x2, y2)
+
+            
+app = wx.App(False)
+frame = PaintFrame(None, 'PaintDC example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/Process.1.py

@@ -0,0 +1,73 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample demonstrates a simple use of wx.Process/wx.Execute to
+# monitor an external program stdout
+
+import wx
+
+class ProcessFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='Process/Execute example')
+
+        panel = wx.Panel(self)
+        self.label = wx.TextCtrl(panel, style=wx.TE_MULTILINE)
+        self.btn = wx.Button(panel, label="Start")
+
+        self.process = None
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+        self.Bind(wx.EVT_IDLE, self.OnIdle)
+        self.Bind(wx.EVT_END_PROCESS, self.OnProcessEnded)
+        
+    def OnButton(self, event):
+        self.btn.Enable(False)
+        self.label.SetValue('')
+        self.LongRunning()
+
+    def LongRunning(self):
+        """
+        This runs in the GUI thread but uses wx.Process and
+        wx.Execute to start and monitor a separate process.
+        """
+
+        cmd = 'python -u external_program.py'
+
+        self.process = wx.Process(self)
+        self.process.Redirect()
+
+        wx.Execute(cmd, wx.EXEC_ASYNC, self.process)
+
+    def OnIdle(self, event):
+        """ This event handler catches the process stdout. """
+
+        if self.process is not None:
+            stream = self.process.GetInputStream()
+            if stream.CanRead():
+                text = stream.read()
+                self.label.AppendText(text)
+
+    def OnProcessEnded(self, event):
+
+        stream = self.process.GetInputStream()
+
+        if stream.CanRead():
+            text = stream.read()
+            self.label.AppendText(text)
+
+        self.btn.Enable(True)
+        self.label.AppendText('Finished')
+
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = ProcessFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/SplitterWindow.1.py

@@ -0,0 +1,43 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a "spli-split" window, i.e. a
+# window split verticall which contains two windows split horizontally
+
+import wx
+
+class SplitterFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, title='SplitterWindow example')
+
+        # Create the main splitter window (to be split vertically)
+        splitter = wx.SplitterWindow(self, -1, style=wx.SP_LIVE_UPDATE)
+        splitter.SetMinimumPaneSize(100)
+        
+        panel1 = wx.Panel(splitter, -1)
+
+        static = wx.StaticText(panel1, -1, 'Hello World', pos=(10, 100))
+        panel1.SetBackgroundColour(wx.WHITE)
+
+        # Create the second splitter window (to be split horizontally)
+        splitter2 = wx.SplitterWindow(splitter, -1, style=wx.SP_LIVE_UPDATE)
+        splitter2.SetMinimumPaneSize(100)
+        
+        panel2 = wx.Panel(splitter2, -1)
+        panel2.SetBackgroundColour(wx.BLUE)
+
+        panel3 = wx.Panel(splitter2, -1)
+        panel3.SetBackgroundColour(wx.RED)
+
+        splitter2.SplitHorizontally(panel2, panel3)
+        splitter.SplitVertically(panel1, splitter2)
+        self.Centre()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = SplitterFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/StatusBar.SetStatusWidths.1.py

@@ -0,0 +1,35 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to create a wx.StatusBar with 2 fields, 
+# set the second field to have double width with respect to the 
+# first and and display the date of today in the second field.
+
+import wx
+import datetime
+
+class MainWindow(wx.Frame):
+
+    def __init__(self, parent, title):
+
+        wx.Frame.__init__(self, parent, title=title)
+
+        # A Statusbar in the bottom of the window
+        # Set it up so it has two fields
+        self.CreateStatusBar(2)
+
+        # Set the second field to be double in width wrt the first
+        self.SetStatusWidths([-1, -2])
+
+        # Get today date via datetime
+        today = datetime.datetime.today()
+        today = today.strftime('%d-%b-%Y')
+
+        # Set today date in the second field
+        self.SetStatusText(today, 1)
+
+        self.Show()
+
+app = wx.App(False)
+frame = MainWindow(None, 'SetStatusWidths example')
+app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/TreeCtrl.1.py

@@ -0,0 +1,51 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample classifies the Python keywords alphabetically, using the 
+# first letter of the keyword (i.e., ``and`` goes into ``a``, ``for`` 
+# goes into ``f`` and so on):
+#      
+#      * For each letter, adds a child to the treectrl root
+#      * In each child of the root item, adds its corresponding keyword(s)
+#
+
+import wx
+import keyword
+import string
+
+class TreeFrame(wx.Frame):
+
+    def __init__(self):
+
+        wx.Frame.__init__(self, None, title='TreeCtrl example')
+
+        tree_ctrl = wx.TreeCtrl(self, -1, style=wx.TR_DEFAULT_STYLE | \
+                                                wx.TR_FULL_ROW_HIGHLIGHT | \
+                                                wx.TR_EDIT_LABELS)
+
+        # Add the tree root
+        root = tree_ctrl.AddRoot('Python keywords')
+
+        letters = []
+        
+        for kwd in keyword.kwlist:
+            first = kwd[0]
+            if first not in letters:
+                letters.append(first)
+
+        for letter in letters:
+            item = tree_ctrl.AppendItem(root, letter)
+            for kwd in keyword.kwlist:
+                first = kwd[0]
+                if first == letter:
+                    sub_item = tree_ctrl.AppendItem(item, kwd)
+                    
+        tree_ctrl.ExpandAll()
+        self.Centre()
+
+
+if __name__ == '__main__':
+    app = wx.App(0)
+    frame = TreeFrame()
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/functions.CallAfter.1.py

@@ -0,0 +1,57 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows hot to take advantage of wx.CallAfter when running a
+# separate thread and updating the GUI in the main thread
+
+import wx
+import threading
+import time
+
+class MainFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='CallAfter example')
+
+        panel = wx.Panel(self)
+        self.label = wx.StaticText(panel, label="Ready")
+        self.btn = wx.Button(panel, label="Start")
+        self.gauge = wx.Gauge(panel)
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+        sizer.Add(self.gauge, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+    def OnButton(self, event):
+        """ This event handler starts the separate thread. """
+        self.btn.Enable(False)
+        self.gauge.SetValue(0)
+        self.label.SetLabel("Running")
+
+        thread = threading.Thread(target=self.LongRunning)
+        thread.start()
+
+    def OnLongRunDone(self):
+        self.gauge.SetValue(100)
+        self.label.SetLabel("Done")
+        self.btn.Enable(True)
+
+    def LongRunning(self):
+        """This runs in a different thread.  Sleep is used to
+         simulate a long running task."""
+        time.sleep(3)
+        wx.CallAfter(self.gauge.SetValue, 20)
+        time.sleep(5)
+        wx.CallAfter(self.gauge.SetValue, 70)
+        time.sleep(4)
+        wx.CallAfter(self.OnLongRunDone)
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = MainFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/contrib/functions.Execute.1.py

@@ -0,0 +1,73 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample demonstrates a simple use of wx.Process/wx.Execute to
+# monitor an external program stdout
+
+import wx
+
+class ProcessFrame(wx.Frame):
+
+    def __init__(self, parent):
+        wx.Frame.__init__(self, parent, title='Process/Execute example')
+
+        panel = wx.Panel(self)
+        self.label = wx.TextCtrl(panel, style=wx.TE_MULTILINE)
+        self.btn = wx.Button(panel, label="Start")
+
+        self.process = None
+
+        sizer = wx.BoxSizer(wx.VERTICAL)
+        sizer.Add(self.label, proportion=1, flag=wx.EXPAND)
+        sizer.Add(self.btn, proportion=0, flag=wx.EXPAND)
+
+        panel.SetSizerAndFit(sizer)
+        self.Bind(wx.EVT_BUTTON, self.OnButton)
+
+        self.Bind(wx.EVT_IDLE, self.OnIdle)
+        self.Bind(wx.EVT_END_PROCESS, self.OnProcessEnded)
+        
+    def OnButton(self, event):
+        self.btn.Enable(False)
+        self.label.SetValue('')
+        self.LongRunning()
+
+    def LongRunning(self):
+        """
+        This runs in the GUI thread but uses wx.Process and
+        wx.Execute to start and monitor a separate process.
+        """
+
+        cmd = 'python -u external_program.py'
+
+        self.process = wx.Process(self)
+        self.process.Redirect()
+
+        wx.Execute(cmd, wx.EXEC_ASYNC, self.process)
+
+    def OnIdle(self, event):
+        """ This event handler catches the process stdout. """
+
+        if self.process is not None:
+            stream = self.process.GetInputStream()
+            if stream.CanRead():
+                text = stream.read()
+                self.label.AppendText(text)
+
+    def OnProcessEnded(self, event):
+
+        stream = self.process.GetInputStream()
+
+        if stream.CanRead():
+            text = stream.read()
+            self.label.AppendText(text)
+
+        self.btn.Enable(True)
+        self.label.AppendText('Finished')
+
+
+if __name__ == "__main__":
+    app = wx.App(0)
+    frame = ProcessFrame(None)
+    frame.Show()
+    app.MainLoop()

docs/sphinx/rest_substitutions/snippets/python/converted/ArtProvider.1.py

@@ -7,7 +7,7 @@
                    pass
                  
     
-                   # optionally override this one as well
+               # optionally override this one as well
                def CreateIconBundle(self, id, client):
 
                    # Your implementation of CreateIconBundle here

docs/sphinx/rest_substitutions/snippets/python/converted/ArtProvider.2.py

@@ -2,3 +2,5 @@
         if wx.Platform == '__WXGTK__':
             bmp = wx.ArtProvider.GetBitmap("gtk-cdrom", wx.ART_MENU)
 
+
+

docs/sphinx/rest_substitutions/snippets/python/converted/LogNull.2.py

@@ -4,4 +4,5 @@
           if os.path.exists('bogus.png'):
               bmp = wx.Bitmap('bogus.png')
           else:
-              ...
+              pass
+            # ... do something else here...

etg/_xrc.py

@@ -122,7 +122,7 @@ def run():
     
     
     module.addPyFunction('EmptyXmlResource', '(flags=XRC_USE_LOCALE, domain="")',
-        deprecated="Use XmlResource instead",
+        deprecated="Use :class:`xrc.XmlResource` instead",
         doc='A compatibility wrapper for the XmlResource(flags, domain) constructor',
         body='return XmlResource(flags, domain)')
     

etg/app.py

@@ -508,8 +508,8 @@ def run():
 
 
 
-    module.addPyClass('PySimpleApp', ['App'], deprecated="Use wx.App instead.",
+    module.addPyClass('PySimpleApp', ['App'], deprecated="Use :class:`App` instead.",
-        doc="""This class is deprecated.  Please use wx.App instead.""",
+        doc="""This class is deprecated.  Please use :class:`App` instead.""",
         items=[
             PyFunctionDef('__init__', '(self, *args, **kw)',
                 body="App.__init__(self, *args, **kw)")

etg/bitmap.py

@@ -264,8 +264,8 @@ def run():
             """)
 
     module.addPyFunction('BitmapFromBuffer', '(width, height, dataBuffer, alphaBuffer=None)',
-        deprecated="Use Bitmap.FromBuffer or Bitmap.FromBufferAndAlpha instead.",
+        deprecated="Use :meth:`Bitmap.FromBuffer` or :meth:`Bitmap.FromBufferAndAlpha` instead.",
-        doc='A compatibility wrapper for Bitmap.FromBuffer and Bitmap.FromBufferAndAlpha',
+        doc='A compatibility wrapper for :meth:`Bitmap.FromBuffer` and :meth:`Bitmap.FromBufferAndAlpha`',
         body="""\
             if alphaBuffer is not None:
                 return Bitmap.FromBufferAndAlpha(width, height, dataBuffer, alphaBuffer)
@@ -306,8 +306,8 @@ def run():
             """)
 
     module.addPyFunction('BitmapFromBufferRGBA', '(width, height, dataBuffer)',
-        deprecated="Use Bitmap.FromBufferRGBA instead.",
+        deprecated="Use :meth:`Bitmap.FromBufferRGBA` instead.",
-        doc='A compatibility wrapper for Bitmap.FromBufferRGBA',
+        doc='A compatibility wrapper for :meth:`Bitmap.FromBufferRGBA`',
         body='return Bitmap.FromBufferRGBA(width, height, dataBuffer)')
 
 
@@ -351,20 +351,20 @@ def run():
             """)
 
     module.addPyFunction('EmptyBitmapRGBA', '(width, height, red=0, green=0, blue=0, alpha=0)',
-        deprecated="Use Bitmap.FromRGBA instead.",
+        deprecated="Use :meth:`Bitmap.FromRGBA` instead.",
-        doc='A compatibility wrapper for Bitmap.FromRGBA',
+        doc='A compatibility wrapper for :meth:`Bitmap.FromRGBA`',
         body='return Bitmap.FromRGBA(width, height, red, green, blue, alpha)')
 
     #-----------------------------------------------------------------------
 
     # For compatibility:
     module.addPyFunction('EmptyBitmap', '(width, height, depth=BITMAP_SCREEN_DEPTH)',
-                         deprecated="Use wx.Bitmap instead",
+                         deprecated="Use :class:`Bitmap` instead",
                          doc='A compatibility wrapper for the wx.Bitmap(width, height, depth) constructor',
                          body='return Bitmap(width, height, depth)')
 
     module.addPyFunction('BitmapFromImage', '(image)',
-                         deprecated="Use wx.Bitmap instead",
+                         deprecated="Use :class:`Bitmap` instead",
                          doc='A compatibility wrapper for the wx.Bitmap(wx.Image) constructor',
                          body='return Bitmap(image)')
 

etg/event.py

@@ -142,7 +142,7 @@ def run():
             PyPropertyDef('typeId', '_getEvtType'),
             
             PyFunctionDef('__call__', '(self, *args)',
-                deprecated="Use wx.EvtHandler.Bind() instead.",
+                deprecated="Use :meth:`EvtHandler.Bind` instead.",
                 doc="""\
                     For backwards compatibility with the old EVT_* functions.
                     Should be called with either (window, func), (window, ID,
@@ -330,7 +330,7 @@ def run():
             return event.Unbind(self, id, id2, handler)              
             """)
 
-    module.addPyCode('PyEvtHandler = wx.deprecated(EvtHandler, "Use EvtHandler instead.")')
+    module.addPyCode('PyEvtHandler = wx.deprecated(EvtHandler, "Use :class:`EvtHandler` instead.")')
 
 
     #---------------------------------------

etg/icon.py

@@ -61,8 +61,8 @@ def run():
     
     # For compatibility:
     module.addPyFunction('EmptyIcon', '()',
-                         deprecated="Use wx.Icon instead",
+                         deprecated="Use :class:`Icon` instead",
-                         doc='A compatibility wrapper for the wx.Icon() constructor',
+                         doc='A compatibility wrapper for the :class:`Icon` constructor',
                          body='return Icon()')
     
     #-----------------------------------------------------------------

etg/image.py

@@ -222,7 +222,7 @@ def run():
     c.addCppMethod('PyObject*', 'GetDataBuffer', '()',
         doc="""\
         Returns a writable Python buffer object that is pointing at the RGB
-        image data buffer inside the wx.Image. You need to ensure that you do
+        image data buffer inside the :class:`Image`. You need to ensure that you do
         not use this buffer object after the image has been destroyed.""",
         body="""\
             byte* data = self->GetData();
@@ -236,7 +236,7 @@ def run():
     c.addCppMethod('PyObject*', 'GetAlphaBuffer', '()',
         doc="""\
         Returns a writable Python buffer object that is pointing at the Alpha
-        data buffer inside the wx.Image. You need to ensure that you do
+        data buffer inside the :class:`Image`. You need to ensure that you do
         not use this buffer object after the image has been destroyed.""",
         body="""\
             byte* data = self->GetAlpha();
@@ -254,7 +254,7 @@ def run():
         Sets the internal image data pointer to point at a Python buffer
         object.  This can save making an extra copy of the data but you must
         ensure that the buffer object lives lives at least as long as the 
-        wx.Image does.""",
+        :class:`Image` does.""",
         body="""\
             if (!data->checkSize(self->GetWidth() * self->GetHeight() * 3))
                 return;
@@ -266,7 +266,7 @@ def run():
         Sets the internal image data pointer to point at a Python buffer
         object.  This can save making an extra copy of the data but you must
         ensure that the buffer object lives lives at least as long as the 
-        wx.Image does.""",
+        :class:`Image` does.""",
         body="""\
             if (!data->checkSize(new_width * new_height * 3))
                 return;
@@ -280,7 +280,7 @@ def run():
         Sets the internal image alpha pointer to point at a Python buffer
         object.  This can save making an extra copy of the data but you must
         ensure that the buffer object lives lives at least as long as the 
-        wx.Image does.""",
+        :class:`Image` does.""",
         body="""\
             if (!alpha->checkSize(self->GetWidth() * self->GetHeight()))
                 return;
@@ -349,7 +349,7 @@ def run():
     c.addPyMethod('ConvertToBitmap', '(self, depth=-1)', 
         doc="""\
         ConvertToBitmap(depth=-1) -> Bitmap\n
-        Convert the image to a wx.Bitmap.""",
+        Convert the image to a :class:`Bitmap`.""",
         body="""\
         bmp = wx.Bitmap(self, depth)
         return bmp
@@ -358,7 +358,7 @@ def run():
     c.addPyMethod('ConvertToMonoBitmap', '(self, red, green, blue)', 
         doc="""\
         ConvertToMonoBitmap(red, green, blue) -> Bitmap\n
-        Creates a monochrome version of the image and returns it as a wx.Bitmap.""",
+        Creates a monochrome version of the image and returns it as a :class:`Bitmap`.""",
         body="""\
         mono = self.ConvertToMono( red, green, blue )
         bmp = wx.Bitmap( mono, 1 )
@@ -483,27 +483,27 @@ def run():
 
     # For compatibility:
     module.addPyFunction('EmptyImage', '(width=0, height=0, clear=True)',
-                         deprecated="Use wx.Image instead.",
+                         deprecated="Use :class:`Image` instead.",
                          doc='A compatibility wrapper for the wx.Image(width, height) constructor',
                          body='return Image(width, height, clear)')
     
     module.addPyFunction('ImageFromBitmap', '(bitmap)',
-                         deprecated="Use wx.Image instead.",
+                         deprecated="Use :class:`Image` instead.",
-                         doc='Create a wx.Image from a wx.Bitmap',
+                         doc='Create a :class:`Image` from a :class:`Bitmap`',
                          body='return bitmap.ConvertToImage()')
 
     module.addPyFunction('ImageFromStream', '(stream, type=BITMAP_TYPE_ANY, index=-1)',
-                         deprecated="Use wx.Image instead.",
+                         deprecated="Use :class:`Image` instead.",
                          doc='Load an image from a stream (file-like object)',
                          body='return wx.Image(stream, type, index)')
 
     module.addPyFunction('ImageFromData', '(width, height, data)',
-                         deprecated="Use wx.Image instead.",
+                         deprecated="Use :class:`Image` instead.",
                          doc='Compatibility wrapper for creating an image from RGB data',
                          body='return Image(width, height, data)')
 
     module.addPyFunction('ImageFromDataWithAlpha', '(width, height, data, alpha)',
-                         deprecated="Use wx.Image instead.",
+                         deprecated="Use :class:`Image` instead.",
                          doc='Compatibility wrapper for creating an image from RGB and Alpha data',
                          body='return Image(width, height, data, alpha)')
 
@@ -511,24 +511,24 @@ def run():
     
     module.addPyFunction('ImageFromBuffer', '(width, height, dataBuffer, alphaBuffer=None)',
         doc="""\
-            Creates a `wx.Image` from the data in dataBuffer.  The dataBuffer
+            Creates a :class:`Image` from the data in `dataBuffer`.  The `dataBuffer`
             parameter must be a Python object that implements the buffer interface,
-            such as a string, array, etc.  The dataBuffer object is expected to
+            such as a string, array, etc.  The `dataBuffer` object is expected to
             contain a series of RGB bytes and be width*height*3 bytes long.  A buffer
             object can optionally be supplied for the image's alpha channel data, and
             it is expected to be width*height bytes long.
         
-            The wx.Image will be created with its data and alpha pointers initialized
+            The :class:`Image` will be created with its data and alpha pointers initialized
             to the memory address pointed to by the buffer objects, thus saving the
-            time needed to copy the image data from the buffer object to the wx.Image.
+            time needed to copy the image data from the buffer object to the :class:`Image`.
             While this has advantages, it also has the shoot-yourself-in-the-foot
             risks associated with sharing a C pointer between two objects.
         
             To help alleviate the risk a reference to the data and alpha buffer
-            objects are kept with the wx.Image, so that they won't get deleted until
+            objects are kept with the :class:`Image`, so that they won't get deleted until
             after the wx.Image is deleted.  However please be aware that it is not
             guaranteed that an object won't move its memory buffer to a new location
-            when it needs to resize its contents.  If that happens then the wx.Image
+            when it needs to resize its contents.  If that happens then the :class:`Image`
             will end up referring to an invalid memory location and could cause the
             application to crash.  Therefore care should be taken to not manipulate
             the objects used for the data and alpha buffers in a way that would cause

etg/pyevent.py

@@ -33,16 +33,16 @@ def run():
     
     cls = ClassDef(name='wxPyEvent', bases=['wxEvent'], 
         briefDoc="""\
-            wx.PyEvent can be used as a base class for implementing custom
+            :class:`PyEvent` can be used as a base class for implementing custom
             event types in Python. You should derive from this class instead
-            of `wx.Event` because this class is Python-aware and is able to
+            of :class:`Event` because this class is Python-aware and is able to
             transport its Python bits safely through the wxWidgets event
             system and have them still be there when the event handler is
-            invoked. Note that since wx.PyEvent is taking care of preserving
+            invoked. Note that since :class:`PyEvent` is taking care of preserving
             the extra attributes that have been set then you do not need to
             override the Clone method in your derived classes.
             
-            :see: `wx.PyCommandEvent`""",
+            :see: :class:`PyCommandEvent`""",
         items=[
             MethodDef(name='wxPyEvent', isCtor=True, items=[
                 ParamDef(type='int', name='id', default='0'),
@@ -74,17 +74,17 @@ def run():
     
     cls = ClassDef(name='wxPyCommandEvent', bases=['wxCommandEvent'], 
         briefDoc="""\
-            wx.PyCommandEvent can be used as a base class for implementing
+            :class:`PyCommandEvent` can be used as a base class for implementing
             custom event types in Python. You should derive from this class
-            instead of `wx.CommandEvent` because this class is Python-aware
+            instead of :class:`CommandEvent` because this class is Python-aware
             and is able to transport its Python bits safely through the
             wxWidgets event system and have them still be there when the
-            event handler is invoked. Note that since wx.PyCommandEvent is
+            event handler is invoked. Note that since :class:`PyCommandEvent` is
             taking care of preserving the extra attributes that have been set
             then you do not need to override the Clone method in your
             derived classes.
             
-            :see: `wx.PyEvent`""",
+            :see: :class:`PyEvent`""",
         items=[
             MethodDef(name='wxPyCommandEvent', isCtor=True, items=[
                 ParamDef(type='wxEventType', name='evenType', default='wxEVT_NULL'),

etg/rawbmp.py

@@ -44,12 +44,12 @@ def run():
     
     addPixelDataClass(module, 'wxNativePixelData', 'wxBitmap', bpp=24,
         doc="""\
-        NativePixelData: A class providing direct access to a wx.Bitmap's
+        A class providing direct access to a :class:`Bitmap`'s
         internal data without alpha channel (RGB). 
         """)
     addPixelDataClass(module, 'wxAlphaPixelData', 'wxBitmap', bpp=32,
         doc="""\
-        AlphaPixelData: A class providing direct access to a wx.Bitmap's
+        A class providing direct access to a :class:`wx.Bitmap`'s
         internal data including the alpha channel (RGBA). 
         """)
     #addPixelDataClass(module, 'wxImagePixelData', 'wxImage', bpp=32,

etg/toolbar.py

@@ -81,7 +81,7 @@ def run():
     # TODO: Which others are commonly enough used that they should be here too?
     c.addPyMethod('AddSimpleTool', '(self, toolId, bitmap, shortHelpString="", longHelpString="", isToggle=0)',
         doc='Old style method to add a tool to the toolbar.',
-        deprecated='Use AddTool instead.',
+        deprecated='Use :meth:`AddTool` instead.',
         body="""\
             kind = wx.ITEM_NORMAL
             if isToggle: kind = wx.ITEM_CHECK
@@ -92,7 +92,7 @@ def run():
                   '(self, id, label, bitmap, bmpDisabled=wx.NullBitmap, kind=wx.ITEM_NORMAL,'
                   ' shortHelp="", longHelp="", clientData=None)',
         doc='Old style method to add a tool in the toolbar.',
-        deprecated='Use AddTool instead.',
+        deprecated='Use :meth:`AddTool` instead.',
         body="""\
             return self.AddTool(id, label, bitmap, bmpDisabled, kind,
                                 shortHelp, longHelp, clientData)
@@ -100,7 +100,7 @@ def run():
 
     c.addPyMethod('InsertSimpleTool', '(self, pos, toolId, bitmap, shortHelpString="", longHelpString="", isToggle=0)',
         doc='Old style method to insert a tool in the toolbar.',
-        deprecated='Use InsertTool instead.',
+        deprecated='Use :meth:`InsertTool` instead.',
         body="""\
             kind = wx.ITEM_NORMAL
             if isToggle: kind = wx.ITEM_CHECK
@@ -111,7 +111,7 @@ def run():
                   '(self, pos, id, label, bitmap, bmpDisabled=wx.NullBitmap, kind=wx.ITEM_NORMAL,'
                   ' shortHelp="", longHelp="", clientData=None)',
         doc='Old style method to insert a tool in the toolbar.',
-        deprecated='Use InsertTool instead.',
+        deprecated='Use :meth:`InsertTool` instead.',
         body="""\
             return self.InsertTool(pos, id, label, bitmap, bmpDisabled, kind,
                                    shortHelp, longHelp, clientData)

etg/wxdatetime.py

@@ -113,21 +113,21 @@ def run():
     
     # and give them some simple wrappers for Classic compatibility
     module.addPyFunction('DateTimeFromTimeT', '(timet)',
-        doc="Compatibility wrapper for DateTime.FromTimeT",
+        doc="Compatibility wrapper for :meth:`DateTime.FromTimeT`",
         body="return DateTime.FromTimeT(timet)",
-        deprecated='Use DateTime.FromTimeT instead.')
+        deprecated='Use :meth:`DateTime.FromTimeT` instead.')
     module.addPyFunction('DateTimeFromJDN', '(jdn)',
-        doc="Compatibility wrapper for DateTime.FromJDN",
+        doc="Compatibility wrapper for :meth:`DateTime.FromJDN`",
         body="return DateTime.FromJDN(jdn)",
-        deprecated='Use DateTime.FromJDN instead.')
+        deprecated='Use :meth:`DateTime.FromJDN` instead.')
     module.addPyFunction('DateTimeFromHMS', '(hour, minute=0, second=0, millisecond=0)',
-        doc="Compatibility wrapper for DateTime.FromHMS",
+        doc="Compatibility wrapper for :meth:`DateTime.FromHMS`",
         body="return DateTime.FromHMS(hour, minute, second, millisecond)",
-        deprecated='DateTime.FromHMS instead.')
+        deprecated='Use :meth:`DateTime.FromHMS` instead.')
     module.addPyFunction('DateTimeFromDMY', '(day, month, year=DateTime.Inv_Year, hour=0, minute=0, second=0, millisecond=0)',
-        doc="Compatibility wrapper for DateTime.FromDMY",
+        doc="Compatibility wrapper for :meth:`DateTime.FromDMY`",
         body="return DateTime.FromDMY(day, month, year, hour, minute, second, millisecond)",
-        deprecated='Use DateTime.FromDMY instead.')
+        deprecated='Use :meth:`DateTime.FromDMY` instead.')
     
     
     # Fixup similar conflicts in the Set method overloads

etgtools/sphinx_generator.py

@@ -1460,7 +1460,7 @@ class Snippet(Node):
             hierarchy = self.GetHierarchy()
             spacer = ''
             if 'Section' in hierarchy:
-                spacer = ' '*4
+                spacer = ' '*3
             elif 'Parameter' in hierarchy:
                 spacer = ' '
                 
@@ -1942,7 +1942,7 @@ class XMLDocString(object):
         else:
             raise Exception('Unhandled docstring kind for %s'%xml_item.__class__.__name__)
 
-        if hasattr(xml_item, 'deprecated') and xml_item.deprecated:
+        if hasattr(xml_item, 'deprecated') and xml_item.deprecated and isinstance(xml_item.deprecated, basestring):
             element = et.Element('deprecated', kind='deprecated')
             element.text = VERSION
             
@@ -2267,7 +2267,16 @@ class XMLDocString(object):
         fullname = self.GetFullName()
         contrib_folder = os.path.join(SNIPPETROOT, 'python', 'contrib')
 
-        possible_py = glob.glob(os.path.normpath(contrib_folder + '/' + fullname + '*.py'))
+        possible_py = []
+
+        for suffix in range(1, 101):
+
+            sample = os.path.join(contrib_folder, '%s.%d.py'%(fullname, suffix))
+
+            if not os.path.isfile(sample):
+                break
+
+            possible_py.append(sample)
 
         return possible_py
                 
@@ -2579,6 +2588,12 @@ class XMLDocString(object):
 
         self.Reformat(stream)
 
+        if hasattr(method, 'deprecated') and method.deprecated:
+            text = method.deprecated
+            if isinstance(text, basestring):
+                text = '%s %s\n%s%s\n\n'%('      .. deprecated::', VERSION, ' '*9, text.replace('\n', ' '))
+                stream.write(text)
+
         possible_py = self.HuntContributedSnippets()
         
         if possible_py:
@@ -2623,6 +2638,10 @@ class XMLDocString(object):
 
         self.Reformat(stream)
 
+        if hasattr(function, 'deprecated') and function.deprecated:
+            text = '%s %s\n%s%s\n\n'%('   .. deprecated::', VERSION, ' '*6, function.deprecated.replace('\n', ' '))
+            stream.write(text)
+
         possible_py = self.HuntContributedSnippets()
         
         if possible_py:

sphinxtools/postprocess.py

@@ -165,8 +165,10 @@ def BuildEnumsAndMethods(sphinxDir):
 
         # Avoid Sphinx warnings on wx.TreeCtrl
         text = text.replace('**( `', '** ( `')
+        
         # Replace EmptyString stuff
-        text = text.replace('EmptyString', "''")
+        for item in ['wx.EmptyString', 'EmptyString']:
+            text = text.replace(item, '""')
         
         # Replace ArrayXXX stuff...
         for cpp in ['ArrayString()', 'ArrayInt()', 'ArrayDouble()', 'ArrayString']:

sphinxtools/utilities.py

@@ -560,6 +560,7 @@ def WriteSphinxOutput(stream, filename, append=False):
     fid = codecs.open(text_file, mode, encoding='utf-8')        
     if mode == 'w':
         fid.write('.. include:: headings.inc\n\n')
+
     fid.write(text)
     fid.close()
 
@@ -761,7 +762,7 @@ def FormatContributedSnippets(kind, contrib_snippets):
     if kind == 'class':
         text = TEMPLATE_CONTRIB
     else:
-        text = spacer + '\n**Contributed Examples:**\n\n'
+        text = '\n' + spacer + '**Contributed Examples:**\n\n'
     
     for indx, snippet in enumerate(contrib_snippets):
         fid = open(snippet, 'rt')
@@ -771,14 +772,19 @@ def FormatContributedSnippets(kind, contrib_snippets):
         onlyfile = os.path.split(snippet)[1]
 
         text += RAW_1%(spacer, spacer)
-        text += '\n' + spacer + 'Example %d - %s (:download:`download <_downloads/%s>`)::\n\n'%(indx+1, user, onlyfile)
+        text += '\n' + spacer + 'Example %d - %s (:download:`download <_downloads/%s>`):\n\n'%(indx+1, user, onlyfile)
 
-        for line in lines[1:]:
+        text += spacer + '.. literalinclude:: %s\n'%snippet
-            text += 4*' '+ spacer + line
+        text += spacer + '   :lines: 2-\n\n'
 
-        text += '\n'
         text += RAW_2%(spacer, spacer)
 
+        text += '\n\n%s|\n\n'%spacer
+        
+        download = os.path.join(SPHINXROOT, '_downloads', onlyfile)
+        if not os.path.isfile(download):
+            shutil.copyfile(snippet, download)
+
     return text