Wizard Page Events - Revision history

Mandrav: Documentation of OnClick()

2007-12-10T09:10:28Z

Documentation of OnClick()

Artojon: removed extra category

2006-11-11T17:41:52Z

removed extra category

Mandrav: Categorized document

2006-07-10T10:19:33Z

Categorized document

Mandrav: Added note in GetNextPage()

2006-07-10T10:17:13Z

Added note in GetNextPage()

Mandrav: Added OnGetPrevPage() and OnGetNextPage() events

2006-07-10T10:13:55Z

Added OnGetPrevPage() and OnGetNextPage() events

Mandrav: Started events documentation. Added OnEnter() and OnLeave().

2006-07-10T09:55:40Z

Started events documentation. Added OnEnter() and OnLeave().

Mandrav: Initial text and Page IDs

2006-07-10T09:33:58Z

Initial text and Page IDs

New page

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:

{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
|- style="background: #ececec; border: 0px solid gray"
!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 [[Wizard Scripting Commands#AddGenericSelectPathPage(pageId, descr, label, defValue)|AddGenericSelectPathPage]] and [[Wizard Scripting Commands#AddGenericSingleChoiceListPage(pageId, descr, choices, defChoice)|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...

← Older revision		Revision as of 09:10, 10 December 2007
Line 208:		Line 208:


		+	=== OnClick() ===
		+	Most basic control types call OnClick when they are clicked.

−	[[User:Mandrav\|Mandrav]] 06:17, 10 ~~July 2006~~ (~~EDT~~)	+	Using this event, a script can respond to user choices at the time they take place. For example, one could enable/disable some controls based on a checkbox's state, right when the user clicks the said checkbox.
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Return type \|\| Value
		+	\|-
		+	\| - \|\| -
		+	\|}
		+
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Parameter \|\| Type \|\| Description
		+	\|-
		+	\| - \|\| - \|\| -
		+	\|}
		+
		+
		+	'''Sample:'''
		+	// assume we have the following controls on the page:
		+	// chkOption (checkbox)
		+	// txtText (text)
		+
		+	function OnClick_chkOption()
		+	{
		+	// enable/disable the text box based on the checkbox's state
		+	Wizard.EnableWindow(_T("txtText"), Wizard.IsCheckboxChecked(_T("chkOption"));
		+	}
		+
		+
		+
		+
		+
		+	[[User:Mandrav\|Mandrav]] 09:10, 10 December 2007 (UTC)

← Older revision		Revision as of 17:41, 11 November 2006
Line 1:		Line 1:
−	~~[[Category:Code::Blocks Documentation]]~~
	[[Category:Scripting Code::Blocks]]		[[Category:Scripting Code::Blocks]]
	A script can handle various wizard events while the wizard is running. This page explains these events (and their uses) in detail.		A script can handle various wizard events while the wizard is running. This page explains these events (and their uses) in detail.

← Older revision		Revision as of 10:19, 10 July 2006
Line 1:		Line 1:
		+	[[Category:Code::Blocks Documentation]]
		+	[[Category:Scripting Code::Blocks]]
	A script can handle various wizard events while the wizard is running. This page explains these events (and their uses) in detail.		A script can handle various wizard events while the wizard is running. This page explains these events (and their uses) in detail.

@@ Line 189: / Line 189: @@
 !Return type || Value
 |-
-|wxString || The previous page's ID
+|wxString || The next page's ID
 |}
@@ Line 199: / Line 199: @@
 | - || - || -
 |}
 See the sample in [[Wizard Page Events#OnGetPrevPage()|OnGetPrevPage]].

← Older revision		Revision as of 10:13, 10 July 2006
Line 111:		Line 111:
	return true; // all is well		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).
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Return type \|\| Value
		+	\|-
		+	\|wxString \|\| The previous page's ID
		+	\|}
		+
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!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).
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Return type \|\| Value
		+	\|-
		+	\|wxString \|\| The previous page's ID
		+	\|}
		+
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Parameter \|\| Type \|\| Description
		+	\|-
		+	\| - \|\| - \|\| -
		+	\|}
		+
		+	See the sample in [[Wizard Page Events#OnGetPrevPage()\|OnGetPrevPage]].

← Older revision		Revision as of 09:55, 10 July 2006
Line 31:		Line 31:

	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...		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.
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!Return type \|\| Value
		+	\|-
		+	\|void \|\| -
		+	\|}
		+
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!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.
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!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).
		+	\|}
		+
		+
		+	{\| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
		+	\|- style="background: #ececec; border: 0px solid gray"
		+	!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
		+	}