Wizard Page Events - Revision history

Mandrav: Documentation of OnClick()

2007-12-10T09:10:28Z

Documentation of OnClick()

← 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)

Artojon: removed extra category

2006-11-11T17:41:52Z

removed extra category

← 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.

Mandrav: Categorized document

2006-07-10T10:19:33Z

Categorized document

← 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.

Mandrav: Added note in GetNextPage()

2006-07-10T10:17:13Z

Added note in GetNextPage()

← Older revision		Revision as of 10:17, 10 July 2006
Line 189:		Line 189:
	!Return type \|\| Value		!Return type \|\| Value
	\|-		\|-
	\|wxString \|\| The ~~previous~~ page's ID		\|wxString \|\| The next page's ID
	\|}		\|}

Line 199:		Line 199:
	\| - \|\| - \|\| -		\| - \|\| - \|\| -
	\|}		\|}


			''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 [[Wizard Page Events#OnGetPrevPage()\|OnGetPrevPage]].		See the sample in [[Wizard Page Events#OnGetPrevPage()\|OnGetPrevPage]].



			[[User:Mandrav\|Mandrav]] 06:17, 10 July 2006 (EDT)

Mandrav: Added OnGetPrevPage() and OnGetNextPage() events

2006-07-10T10:13:55Z

Added OnGetPrevPage() and OnGetNextPage() events

← 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]].

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

2006-07-10T09:55:40Z

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

← 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
			}

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...