Wizard Scripting Commands

In this page, all the wizards-related script commands are listed and explained.

Before we start, remember that in every wizard script there is a global variable defined named Wizard. This is the object that all the following commands are known under.

Adding wizard pages

The script writer creates a wizard by adding various pre-defined and/or custom pages to the wizard object. The order the pages are added define the order in which they will appear (almost).

The script has the chance to interfere with the wizards operation any time the user presses "Next" or "Back" on the wizard dialog. For more on this, please read Wizard Page Events.

NOTE: The following commands only make sense inside the BeginWizard() script function.

AddInfoPage(pageId,intro_msg)

Add an informational page. It contains an informational text. It also contains a checkbox labelled "Skip".

Usually used for the first page to be displayed by the wizard and it explains in a few words what this wizard will do.

Returns: Nothing.

Parameter	Type	Description
pageId	wxString	The page's ID.
info_msg	wxString	The info text

AddFilePathPage(showHeaderGuard)

Add a page that allows for the selection of a file. This file might not exist. Usually used by wizards of type wizFiles for the selection of the output files.

It also contains a header guard text box which can be visible or not. Usually used when the file in question is a C/C++ header, in which case you might want to allow the user to customize the header guard word. Note that if this is visible it is also auto-updated to match the selected filename. The auto-update takes the filename part (no path), capitalizes it and replaces any non-character or non-digit to an underscore.

Returns: Nothing.

Parameter	Type	Description
showHeaderGuard	bool	If true, a header guard text box will be visible

AddProjectPathPage()

Add a page that allows the user to customize the new project. Usually used by wizards of type wizProject.

This page contains text boxes to set the project title, filename and base directory.

Returns: Nothing.

Parameter	Type	Description
-	-	-

AddCompilerPage(compilerID, validCompilerIDs, allowCompilerChange, allowConfigChange)

Perhaps the most used pre-defined wizard page. It contains a compiler selection list and a couple of well-known pre-defined build targets: Debug and Release.

The compilers' list can contain all supported compilers or a script-defined list. It can also be selected whether compiler selection will be enabled or not.

Finally, the build targets related settings can be either visible or not. If they 're visible, they allow the user to customize per-target the target's name, working directory and objects output (intermediate) directory.

Returns: Nothing.

Parameter	Type	Description
compilerID	wxString	The preselected compiler ID for the list. If this string is empty, the globally default compiler will be selected.
validCompilerIDs	wxString	A semicolon separated list of valid compiler IDs to include in the list. If you want all available compilers to be listed, use _T("*"). If you want only GCC-based or MSVC-based compilers to appear in the list, use _T("gcc*;msv*").
allowCompilerChange	bool	If true, the user will be able to change the compiler selection. If false, the selection will be read-only.
allowConfigChange	bool	If true, the settings for the two pre-defined build targets (Debug/Release) will be shown and available for the user to customize. If false, they will not be visible.

AddBuildTargetPage(targetName, isDebug, showCompiler, compilerID, validCompilerIDs, allowCompilerChange)

Adds a page for creating a new build target. This page allows the user to enter a name for the new build target, set its working directory, set its objects output (intermediate) directory and, optionally, a compiler selection list.

It also contains a checkbox to denote whether this target should have debugging symbols enabled or not.

The compilers' list can contain all supported compilers or a script-defined list. It can also be selected whether compiler selection will be enabled or not.

Returns: Nothing.

Parameter	Type	Description
targetName	wxString	The new target's name.
isDebug	bool	If true, the "Enable debugging symbols" check box will be checked.
showCompiler	bool	If true, the compiler selection list will be visible.
compilerID	wxString	The preselected compiler ID for the list. If this string is empty, the globally default compiler will be selected.
validCompilerIDs	wxString	A semicolon separated list of valid compiler IDs to include in the list. If you want all available compilers to be listed, use _T("*"). If you want only GCC-based or MSVC-based compilers to appear in the list, use _T("gcc*;msv*").
allowCompilerChange	bool	If true, the user will be able to change the compiler selection. If false, the selection will be read-only.

AddGenericSingleChoiceListPage(pageId, descr, choices, defChoice)

Adds a page that contains a script-defined list and the user can select one single value from it.

Returns: Nothing.

Parameter	Type	Description
pageId	wxString	The page's ID.
descr	wxString	The description displayed at the top of the page.
choices	wxString	Semicolon separated list of the available selections.
defChoice	int	The pre-selected choice. This is used only the first time this page is displayed. The user's selection is stored in the Code::Blocks configuration file and remembered for subsequent uses of this page.

AddGenericSelectPathPage(pageId, descr, label, defValue)

Adds a page that allows the user to select a folder from the filesystem.

Returns: Nothing.

Parameter	Type	Description
pageId	wxString	The page's ID.
descr	wxString	The description displayed at the top of the page.
label	wxString	The label above the text box (e.g. "Location of Foo:").
defValue	wxString	The pre-selected path. This is used only the first time this page is displayed. The user's selection is stored in the Code::Blocks configuration file and remembered for subsequent uses of this page.

AddPage(pageId)

Adds a custom page from XRC resource.

The wizard allows the script to add custom pages from XRC. Each such page must actually be a wxPanel inside the XRC. This wxPanel's name is then used as the pageID parameter. Note that all custom page panels are placed in wizard.xrc.

Returns: Nothing.

Parameter	Type	Description
pageId	wxString	The page's ID. This must match the wxPanel's name in the XRC resource.

Operating on GUI controls

The wizard allows scripts to operate on the controls currently visible (i.e. on the current page the user is viewing). By "operate on" I mean get and set their values. This is especially useful for custom XRC pages (else what would they be good for?) and a couple of the pre-defined pages.

In this section, the script commands that allows the script to operate on page controls are explained by control type.

Text controls (wxTextCtrl)

SetTextControlValue(control_name, value)

Sets the value of the text control identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name
value	wxString	The new value

GetTextControlValue(control_name)

Gets the value of the text control identified by control_name.

Returns: The control's current value (wxString).

Parameter	Type	Description
control_name	wxString	The control's name

Checkbox controls (wxCheckBox)

CheckCheckbox(control_name, value)

Checks or unchecks the checkbox identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name
value	bool	Check if true, uncheck if false

IsCheckboxChecked(control_name)

Gets the check-state of the checkbox identified by control_name.

Returns: The control's current check-state (bool).

Parameter	Type	Description
control_name	wxString	The control's name

Combobox controls (wxComboBox)

SetComboboxSelection(control_name, value)

Sets the selected item in the combobox identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name
value	int	The item's index. Use -1 for no selection

GetComboboxSelection(control_name)

Gets the selected item in the combobox identified by control_name.

Returns: The control's currently selected index (int).

Parameter	Type	Description
control_name	wxString	The control's name

GetComboboxStringSelection(control_name)

Gets the selected item's string in the combobox identified by control_name.

Returns: The control's currently selected item's string (wxString).

Parameter	Type	Description
control_name	wxString	The control's name

GetCompilerFromCombobox(control_name)

Assuming you have used FillComboboxWithCompilers() (below) to fill the combobox, this returns the selected compiler's ID.

Returns: The control's currently selected item's string (wxString).

Parameter	Type	Description
control_name	wxString	The control's name

FillComboboxWithCompilers(control_name)

Fills the combobox with a list of compilers.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name

Radiobox controls (wxRadioBox)

SetRadioboxSelection(control_name, value)

Sets the selected item in the radiobox identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name
value	int	The item's index. Use -1 for no selection

GetRadioboxSelection(control_name)

Gets the selected item in the radiobox identified by control_name.

Returns: The control's currently selected index (int).

Parameter	Type	Description
control_name	wxString	The control's name

Listbox controls (wxListBox)

SetListboxSelection(control_name, value)

Sets the selected item in the listbox identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The control's name
value	int	The item's index. Use -1 for no selection

GetListboxSelection(control_name)

Gets the selected item in the listbox identified by control_name.

Returns: The control's currently selected index (int).

Parameter	Type	Description
control_name	wxString	The control's name

All controls (common functions)

EnableWindow(control_name, value)

Enables/disables the window (control) identified by control_name.

Returns: Nothing.

Parameter	Type	Description
control_name	wxString	The window's (control) name
value	bool	Enable if true, disable if false

(to be continued)

Mandrav 11:28, 9 July 2006 (EDT)