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
}