Creating a wizard

A wizard is a series of simple dialogs chained together to force the user to step through them one by one. Typically, they are used to guide a user through installation or a complex setup procedure by breaking down the information into small pieces. Figure 9.11 displays a sample wizard, displaying Back and Next buttons.

In wxPython, a wizard is a series of pages controlled by an instance of the class wx.wizard.Wizard. The wizard instance manages the events that take the user through the pages. The pages themselves are instances of either the class wx.wizard.Wizard-PageSimple or wx.wizard.WizardPage. In both cases, they are merely wx.Panel instances with the additional logic needed to manage the page chain. The difference between the two instances is manifested only when the user presses the Next button. An instance of wx.wizard.WizardPage allows you to determine dynamically which page to navigate to at runtime, whereas an instance of wx.wizard.WizardPageSimple requires that the order be preset before the wizard is displayed. Listing 9.11 displays the code for a simple wizard.

Figure 9.11 sample

A simple wizard

Figure 9.11 sample

A simple wizard

Listing 9.11 Creating a simple static wizard import wx import wx.wizard class TitledPage(wx.wizard.WizardPageSimple):

wx.wizard.WizardPageSimple.__init__(self, parent) self.sizer = wx.BoxSizer(wx.VERTICAL) self.SetSizer(self.sizer)

titleText = wx.StaticText(self, -1, title) titleText.SetFont(

wx.Font(18, wx.SWISS, wx.NORMAL, wx.BOLD)) self.sizer.Add(titleText, 0, wx.ALIGN_CENTRE | wx.ALL, 5) self.sizer.Add(wx.StaticLine(self, -1), 0, wx.EXPAND | wx.ALL, 5)

Creating sample pages

Simple Wizard")

Creating wizard pages if _name_ == "_main_":

app = wx.PySimpleApp() wizard = wx.wizard.Wizard(None, -1, page1 = TitledPage(wizard, "Page 1") page2 = TitledPage(wizard, "Page 2") page3 = TitledPage(wizard, "Page 3") page4 = TitledPage(wizard, "Page 4") page1.sizer.Add(wx.StaticText(page1, -1,

"Testing the wizard")) page4.sizer.Add(wx.StaticText(page4, -1,

"This is the last page.")) wx.wizard.WizardPageSimple_Chain(page1, page2) wx.wizard.WizardPageSimple_Chain(page2, page3) wx.wizard.WizardPageSimple_Chain(page3, page4) wizard.FitToPage(page1) <1_~L

d Sizing the wizard if wizard.RunWizard(page1):

Creatingwizard instance

Creating page chain print "Success"

Running the wizard

O For the purpose of populating a wizard, we create a simple little page that contains a static text title. Typically, you'd have some form elements here, and probably some data for the user to enter. © The function wx.wizard.WizardPageSimple_Chain() is a convenience method that mutually calls SetNext() and SetPrev() of the two pages passed as arguments. d Calling FitToSize() sizes the wizard based on the page passed as an argument, and also all the pages reachable from that page in the chain. Call this method only after the page chain has been created. Q The argument to this method is the page to start the wizard on. The wizard knows to close when it reaches a page that has no Next page. The RunWizard() method returns True if the user goes through the whole wizard and exits by pressing the Finish button.

Creating the wx.wizard.Wizard instance is the first part of using a wizard. The constructor looks similar to the following:

wx.wizard.Wizard(parent, id=-1, title=wx.EmptyString, bitmap=wx.NullBitmap, pos=wx.DefaultPosition)

In this example, the parent, id, title, and pos are as in wx.Panel. If set, the bitmap argument displays on each page. There is one style flag, wx.wizard.WIZARD_EX_ helpbutton, that causes a Help button to display. This is an extended flag, and must be set using the two-step creation process outlined in chapter 8.

Typically, you'll manage the size of the window by calling FitToSize() as displayed in line d of listing 9.11, however, you can also set a minimal size by calling SetPageSize() with a tuple or wx.Size instance. The GetPageSize() method returns the current size. In both cases, the size is only used for the part of the dialog reserved for individual pages, while the dialog as a whole will be somewhat larger.

You can manage the pages from within this class. The method GetCurrent-Page() returns the page currently being displayed, and if the wizard is not currently being displayed, the method returns None. You can determine if the current page has a next or previous page by calling HasNextPage() or HasPrevPage() . Running the wizard is managed with the RunWizard() method, as described in line © of listing 9.11.

Wizards fire command events that you can capture for more specialized processing, as displayed in table 9.5. In all these cases, the event object itself is of the class wx.wizard.WizardEvent, which exposes two methods. GetPage() returns the wx.WizardPage instance which was active when the event was generated, rather than the instance that may be displayed as a result of the event. The method Get-Direction() returns True if the event is a page change going forward, and False if it is a page change going backward.

Table 9.5 Events of wx.wizard.WizardDialog

Event

Description

EVT_WIZARD_CANCEL

Fired when the the user presses the Cancel button. This event may be vetoed using Veto(), in which case the dialog will not be dismissed.

EVT_WIZARD_FINISHED

Fired when the user presses the Finished button.

EVT_WIZARD_HELP

Fired when the user presses the Help button.

EVT_WIZARD_PAGE_CHANGED

Fired after the page has already been changed, to allow for postprocessing.

EVT_WIZARD_PAGE_CHANGING

Fired when the user has requested a page change, but it has not yet occurred. This event may be vetoed (if, for example, there is a required field that needs to be filled).

The wx.wizard.WizardPageSimple class is treated as though it were a panel. The constructor for the class allows you to set the Previous and Next pages, as in the following:

wx.wizard.WizardPageSimple(parent=None, prev=None, next=None)

If you don't want to set them in the constructor, you can use the SetPrev() and SetNext() methods. And if that's too much trouble, you can use wx.wizard.

The wx.wizard.WizardPageSimple class is treated as though it were a panel. The constructor for the class allows you to set the Previous and Next pages, as in the following:

wx.wizard.WizardPageSimple(parent=None, prev=None, next=None)

If you don't want to set them in the constructor, you can use the SetPrev() and SetNext() methods. And if that's too much trouble, you can use wx.wizard.

WizardPageSimple_Chain(), which sets up the chaining relationship between two pages.

The complex version of wizard pages, wx.wizard.WizardPage, differs slightly. Rather than setting the Previous and Next explicitly, it defines handler methods that allow you to use more elaborate logic to define where to go next. The constructor is as follows:

wx.WizardPage(parent, bitmap=wx.NullBitmap, resource=None)

If set, the bitmap argument overrides the bitmap set in the parent wizard. The resource argument loads the page from a wxPython resource. To handle the page logic, override GetPrev() and GetNext() to return whatever you want the wizard to do next. A typical usage may be to dynamically determine the Next page based on user response to the current page.

9.4 Showing startup tips

Many applications use startup tips as a way of introducing users to program features they otherwise may not see. There is a very simple mechanism in wxPython for showing startup tips. Figure 9.12 displays a sample tip window.

Listing 9.12 displays the code.

Listing 9.12 Displaying a startup tip in five lines or less import wx if __name__ == "__main__": app = wx.PySimpleApp() provider = wx.CreateFileTipProvider("tips.txt", 0) wx.ShowTip(None, provider, True)

There are two convenience functions that govern the startup tips. The first creates a wx.TipProvider, as in the following:

wx.CreateFileTipProvider(filename, currentTip)

The filename attribute is the name of a file with the string tips. The currentTip is the index of the tip within the file to start with, and the first tip in the file is index 0. The application is responsible for storing that information between runs.

You can dD startup tips very easily.

Figure 9.12 A sample tip window with a helpful message.

The tip file is a simple text file where each line is a new tip. Blank lines in the file are skipped, and lines beginning with # are considered comments, and are also skipped. Here is the tip file for this example.

You can do startup tips very easily. Feel the force, Luke.

The tip provider is an instance of the class wx.PyTipProvider. If you need more elaborate functionality, you can create your own subclass of wx.TipProvider and override the function GetTip().

The function that displays the tip is wx.ShowTip().

wx.ShowTip(parent, tipProvider, showAtStartup)

The parent is the parent window, if any, and the tipProvider is usually created from wx.CreateFileTipProvider. The showAtStartup argument controls whether the Show Tips At Startup checkbox is selected. It does not control whether the tips are actually displayed at startup, that's up to you. The return value of this function is the Boolean state of the Show Tips At Startup checkbox so that you can use that value the next time your application starts.

Was this article helpful?

+2 -2

Post a comment