Wizard Page Events

A script can handle various wizard events while the wizard is running. This page explains these events (and their uses) in detail.

Page IDs

Every wizard page (pre-defined or custom) has a unique page ID. This ID is a wxString that identifies the page in scripts.

These are the valid pre-defined page IDs:

Page	ID
Intro	"IntroPage"
File selection	"FilePathPage"
Project settings	"ProjectPathPage"
Compiler	"CompilerPage"
Build target	"BuildTargetPage"
Generic path
Generic single choice list

You 'll notice that the two last pre-defined pages don't have an ID. This is because you can have more than one of them inside the same wizard and so the IDs wouldn't be unique anymore.

For these two pages, the ID is the first argument passed to their creation calls. See AddGenericSelectPathPage and AddGenericSingleChoiceListPage syntax.

You can give these two pages any ID you want but make sure it's unique. Besides the obvious reasons why it should be unique, the page ID is also used by various wizard pages to store per-page user selections inside the Code::Blocks configuration. So a duplicate ID will save under the same configuration key...

Events

Now that we 've seen what page IDs are, we can talk about wizard script events.

To make a script handle a wizard event, you must create a script function with a special name to handle this event. All event functions must follow the same naming conventions:

• First is the event name
• An underscore follows
• And finally the page ID

Look in the events documentation below. Each event contains sample code.

OnEnter(forward)

Fired just before a page is displayed by the wizard. The script can initialize the page contents in this event.

Return type	Value
void	-

Parameter	Type	Description
forward	bool	If true, the page entered after the user clicked "Next". If false, the user had clicked "Back".

Sample:

function OnEnter_CompilerPage(forward)
{
    // we only care to initialize if going forward
    if (forward)
    {
        // do something?
    }
}

OnLeave(forward)

Fired just before a page is changed to another. This is a very useful event because the script can assign the page contents to variables.

Inside this event, the script has the ability to abort the page change. So, for example, the script can check the values the user entered and abort the page from changing if it detects incorrect values.

Return type	Value
bool	If this function returns true, the page is allowed to change. If it returns false, the change is aborted (the wizard stays in the same page).

Parameter	Type	Description
forward	bool	If true, the page entered after the user clicked "Next". If false, the user had clicked "Back".

Sample:

function OnLeave_MyXRCPanel(forward)
{
    // we only care to check validity if going forward
    if (forward)
    {
        local userName = Wizard.GetTextControlValue("txtUserName");
        if (userName.IsEmpty())
        {
            ShowWarning(_T("You must enter a username!"));
            return false; // abort the page change
        }
    }
    return true; // all is well
}

OnGetPrevPage()

In various times through the wizard's lifetime, it fires this event so that the wizard knows which page is "chained" before the current page.

Using this event, a script can dynamically alter the pages order (possibly based on user selections).

Return type	Value
wxString	The previous page's ID

Parameter	Type	Description
-	-	-

NOTE: if the script returns an empty (or non-existent) page ID, the wizard assumes this is the first page (i.e. no previous page).

Sample:

// assume we have the following pages in the wizard:
// Intro
// Project settings
// Single choice list (1)
// Select path for libfoo (2)
// Compiler selection (3)
//
// and we want to skip the libfoo path selection (2) based on user
// selection in the single choice list (1)
//
// for this to work, we need to create two event functions:
// OnGetNextPage for the choice list (1) and
// OnGetPrevPage for the compiler selection (3) and
// so that we can "jump over" the libfoo path selection page (2)

// we need a global var to keep the user's selection
ChoiceSelection <- 0;

function OnGetNextPage_MyChoiceList()
{
    ChoiceSelection = Wizard.GetListboxSelection(_T("lstSelection"));
    if (ChoiceSelection == 2)
    {
        // based on user's selection, we must skip the libfoo path selection page
        return _T("CompilerPage"));
    }
    // normally, libfoo path selection follows
    return _T("LibFooPath");
}

function OnGetPrevPage_CompilerPage()
{
    if (ChoiceSelection == 2)
    {
        // based on user's selection, we must skip the libfoo path selection page
        return _T("MyChoiceList"));
    }
    // normally, libfoo path selection is before this page
    return _T("LibFooPath");
}

OnGetNextPage()

In various times through the wizard's lifetime, it fires this event so that the wizard knows which page is "chained" after the current page.

Using this event, a script can dynamically alter the pages order (possibly based on user selections).

Return type	Value
wxString	The next page's ID

Parameter	Type	Description
-	-	-

NOTE: if the script returns an empty (or non-existent) page ID, the wizard assumes this is the last page (i.e. no next page).

See the sample in OnGetPrevPage.

Mandrav 06:17, 10 July 2006 (EDT)