Difference between revisions of "Wizard Scripting Commands"

From Code::Blocks
(delete 'UNDER CONSTRUCTION')
 
(34 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
[[Category:Code::Blocks Documentation]]
 
 
[[Category:Scripting Code::Blocks]]
 
[[Category:Scripting Code::Blocks]]
 
In this page, all the wizards-related script commands are listed and explained.
 
In this page, all the wizards-related script commands are listed and explained.
Line 5: Line 4:
 
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.
 
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.
  
 +
= Global variables and basic primitive functions =
 +
 +
 +
The first thing to know is that each wizard script contains
 +
 +
== Global variables ==
 +
:example
 +
 +
<code>ObjectName <- _T("name")</code>
 +
<code>ObjectIndex <- 0</code>
 +
 +
 +
== Basic primitive functions ==
 +
 +
*'''Common and mandatory for all types of project :'''
 +
 +
which contains different entry pages, see [[Wizard Scripting Commands#Adding wizard pages|Adding wizard pages ]]
 +
 +
<code>void BeginWizard ()</code>
 +
 +
 +
* '''For a project :'''
 +
 +
**to get the template files in a project
 +
 +
<code>wxString GetFilesDir ()</code>
 +
 +
**to get generated files in a project
 +
 +
<code>wxString GetGeneratedFile(index)</code>'''
 +
 +
**to create project
 +
<code>bool SetupProject (project)</code>
 +
 +
 +
*'''For a single target (within a project)'''
 +
 +
<code>bool SetupTarget (target, IsDebug)</code>
 +
 +
 +
*'''For file creation'''
 +
 +
<code>wxString CreateFiles ()</code>
 +
 +
 +
*'''For an item to be defined by the user'''
 +
 +
<code>bool SetupCustom ()</code>
 +
 +
 +
:These functions will be performed by the manager wizard.
  
 
= Adding wizard pages =
 
= Adding wizard pages =
Line 15: Line 65:
  
  
−
== AddIntroPage(intro_msg) ==
+
{{Function_Description_2args|1=
 +
== AddInfoPage(pageId,intro_msg) ==
 +
 
 +
Add an informational page. It contains an informational text. It also contains a checkbox labelled "Skip".
  
−
Add the "Intro" page. This is usually the first page to be displayed by the wizard and it only contains a static text explaining in a few words what this wizard will do.
+
Usually used for the first page to be displayed by the wizard and it explains in a few words what this wizard will do.
  
  
 
[[Image:Intro_panel.png]]
 
[[Image:Intro_panel.png]]
 +
|3=pageId
 +
|4=wxString
 +
|5=The page's ID.
 +
|6=info_msg
 +
|7=wxString
 +
|8=The info text
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_1args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!Parameter || Type || Description
 
−
|-
 
−
|intro_msg || wxString || The intro text
 
−
|}
 
−
 
 
−
 
 
 
== AddFilePathPage(showHeaderGuard) ==
 
== AddFilePathPage(showHeaderGuard) ==
  
Line 39: Line 92:
  
 
[[Image:File_path_panel.png]]
 
[[Image:File_path_panel.png]]
 +
|3=showHeaderGuard
 +
|4=bool
 +
|5=If true, a ''header guard'' text box will be visible
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_1args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!Parameter || Type || Description
 
−
|-
 
−
|showHeaderGuard || bool || If true, a ''header guard'' text box will be visible
 
−
|}
 
−
 
 
−
 
 
 
== AddProjectPathPage() ==
 
== AddProjectPathPage() ==
  
Line 57: Line 107:
  
 
[[Image:Project_path_panel.png]]
 
[[Image:Project_path_panel.png]]
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_4args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!Parameter || Type || Description
 
−
|-
 
−
| - || - || -
 
−
|}
 
−
 
 
−
 
 
 
== AddCompilerPage(compilerID, validCompilerIDs, allowCompilerChange, allowConfigChange) ==
 
== AddCompilerPage(compilerID, validCompilerIDs, allowCompilerChange, allowConfigChange) ==
  
Line 77: Line 121:
  
 
[[Image:Compiler_panel.png]]
 
[[Image:Compiler_panel.png]]
 +
| 3=compilerID | 4=wxString | 5=The preselected compiler ID for the list. If this string is empty, the globally default compiler will be selected.
 +
| 6=validCompilerIDs | 7=wxString | 8=A semicolon separated list of valid compiler IDs to include in the list. If you want all available compilers to be listed, use <code>_T("*")</code>. If you want only GCC-based or MSVC-based compilers to appear in the list, use <code>_T("gcc*;msv*")</code>.
 +
| 9=allowCompilerChange | 10=bool | 11=If true, the user will be able to change the compiler selection. If false, the selection will be read-only.
 +
| 12=allowConfigChange | 13=bool | 14=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.
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_6args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!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 <code>_T("*")</code>. If you want only GCC-based or MSVC-based compilers to appear in the list, use <code>_T("gcc*;msv*")</code>.
 
−
|-
 
−
| 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) ==
 
== AddBuildTargetPage(targetName, isDebug, showCompiler, compilerID, validCompilerIDs, allowCompilerChange) ==
  
Line 103: Line 139:
  
 
[[Image:Build_target_panel.png]]
 
[[Image:Build_target_panel.png]]
 +
| 3=targetName | 4=wxString | 5=The new target's name.
 +
| 6=isDebug | 7=bool | 8=If true, the "Enable debugging symbols" check box will be checked.
 +
| 9=showCompiler | 10=bool | 11=If true, the compiler selection list will be visible.
 +
| 12=compilerID | 13=wxString | 14=The preselected compiler ID for the list. If this string is empty, the globally default compiler will be selected.
 +
| 15=validCompilerIDs | 16=wxString | 17=A semicolon separated list of valid compiler IDs to include in the list. If you want all available compilers to be listed, use <code>_T("*")</code>. If you want only GCC-based or MSVC-based compilers to appear in the list, use <code>_T("gcc*;msv*")</code>.
 +
| 18=allowCompilerChange | 19=bool | 20=If true, the user will be able to change the compiler selection. If false, the selection will be read-only.
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_4args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!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 <code>_T("*")</code>. If you want only GCC-based or MSVC-based compilers to appear in the list, use <code>_T("gcc*;msv*")</code>.
 
−
|-
 
−
| 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) ==
 
== AddGenericSingleChoiceListPage(pageId, descr, choices, defChoice) ==
 
Adds a page that contains a script-defined list and the user can select one single value from it.
 
Adds a page that contains a script-defined list and the user can select one single value from it.
Line 128: Line 154:
  
 
[[Image:Generic_single_choice_list.png]]
 
[[Image:Generic_single_choice_list.png]]
 +
| 3=pageId | 4=wxString | 5=The page's ID.
 +
| 6=descr | 7=wxString | 8=The description displayed at the top of the page.
 +
| 9=choices | 10=wxString | 11=Semicolon separated list of the available selections.
 +
| 12=defChoice | 13=int | 14=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.
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_4args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!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) ==
 
== AddGenericSelectPathPage(pageId, descr, label, defValue) ==
 
Adds a page that allows the user to select a folder from the filesystem.
 
Adds a page that allows the user to select a folder from the filesystem.
Line 149: Line 167:
  
 
[[Image:Generic_select_path.png]]
 
[[Image:Generic_select_path.png]]
 +
| 3=pageId | 4=wxString | 5=The page's ID.
 +
| 6=descr | 7=wxString | 8=The description displayed at the top of the page.
 +
| 9=label | 10=wxString | 11=The label above the text box (e.g. "Location of Foo:").
 +
| 12=defValue | 13=wxString | 14=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.
 +
}}
  
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
{{Function_Description_1args|1=
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!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) ==
 
== AddPage(pageId) ==
  
 
Adds a custom page from XRC resource.
 
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.
+
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.
−
 
+
|3=pageId
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
+
|4=wxString
−
|- style="background: #ececec; border: 0px solid gray"
+
|5=The page's ID. This must match the wxPanel's name in the XRC resource.
−
!Parameter || Type || Description
+
}}
−
|-
 
−
| pageId || wxString || The page's ID. This must match the wxPanel's name in the XRC resource.
 
−
|}
 
−
 
 
  
  
Line 190: Line 196:
 
== Text controls (wxTextCtrl) ==
 
== Text controls (wxTextCtrl) ==
  
 +
{{Function_Description_2args|1=
 
=== SetTextControlValue(control_name, value) ===
 
=== SetTextControlValue(control_name, value) ===
 
Sets the value of the text control identified by <code>control_name</code>.
 
Sets the value of the text control identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
|6=value
 +
|7=wxString
 +
|8=The new value
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetTextControlValue(control_name) ===
 +
Gets the value of the text control identified by <code>control_name</code>.
 +
|2=The control's current value (wxString).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
== Checkbox controls (wxCheckBox) ==
 +
 +
{{Function_Description_2args|1=
 +
=== CheckCheckbox(control_name, value) ===
 +
Checks or unchecks the checkbox identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
|6=value
 +
|7=bool
 +
|8=Check if true, uncheck if false
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== IsCheckboxChecked(control_name) ===
 +
Gets the check-state of the checkbox identified by <code>control_name</code>.
 +
|2=The control's current check-state (bool).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
 +
== Combobox controls (wxComboBox) ==
 +
 +
{{Function_Description_2args|1=
 +
=== SetComboboxSelection(control_name, value) ===
 +
Sets the selected item in the combobox identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
|6=value
 +
|7=int
 +
|8=The item's index. Use -1 for no selection
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetComboboxSelection(control_name) ===
 +
Gets the selected item in the combobox identified by <code>control_name</code>.
 +
|2=The control's currently selected index (int).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetComboboxStringSelection(control_name) ===
 +
Gets the selected item's string in the combobox identified by <code>control_name</code>.
 +
|2=The control's currently selected item's string (wxString).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetCompilerFromCombobox(control_name) ===
 +
Assuming you have used FillComboboxWithCompilers() (below) to fill the combobox, this returns the selected compiler's ID.
 +
|2=The control's currently selected item's string (wxString).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== FillComboboxWithCompilers(control_name) ===
 +
Fills the combobox with a list of compilers.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
== Radiobox controls (wxRadioBox) ==
 +
 +
{{Function_Description_2args|1=
 +
=== SetRadioboxSelection(control_name, value) ===
 +
Sets the selected item in the radiobox identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
|6=value
 +
|7=int
 +
|8=The item's index. Use -1 for no selection
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetRadioboxSelection(control_name) ===
 +
Gets the selected item in the radiobox identified by <code>control_name</code>.
 +
|2=The control's currently selected index (int).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 +
 +
== Listbox controls (wxListBox) ==
  
 +
{{Function_Description_2args|1=
 +
=== SetListboxSelection(control_name, value) ===
 +
Sets the selected item in the listbox identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
|6=value
 +
|7=int
 +
|8=The item's index. Use -1 for no selection
 +
}}
  
−
{| border="1" cellpadding="3" cellspacing="0" style="border: 1px solid gray; border-collapse: collapse;"
 
−
|- style="background: #ececec; border: 0px solid gray"
 
−
!Parameter || Type || Description
 
−
|-
 
−
| control_name || wxString || The control's name
 
−
|-
 
−
| value || wxString || The new value
 
−
|}
 
  
 +
{{Function_Description_1args|1=
 +
=== GetListboxSelection(control_name) ===
 +
Gets the selected item in the listbox identified by <code>control_name</code>.
 +
|2=The control's currently selected index (int).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
  
  
 
{{Function_Description_1args|1=
 
{{Function_Description_1args|1=
−
=== GetTextControlValue(control_name) ===
+
=== GetListboxSelections(control_name) ===
−
Gets the value of the text control identified by <code>control_name</code>.
+
Gets the selected items in the listbox identified by <code>control_name</code> to a wxString. The selections are separated ';' and returned as a single string. Use <code>GetArrayFromString()</code> functions to separate them. Please note that the ListBox should be created with <code>wxLB_MULTIPLE</code> or <code>wxLB_EXTENDED</code> window style.
−
|2=The control's current value (wxString).
+
|2=The control's selections (wxString).
 +
|3=control_name
 +
|4=wxString
 +
|5=The control's name
 +
}}
 +
 
 +
 
 +
{{Function_Description_1args|1=
 +
=== GetListboxStringSelections(control_name) ===
 +
Gets the ''content strings'' of the selected items in the listbox identified by <code>control_name</code> to a wxString. The selections are separated ';' and returned as a single string. Use <code>GetArrayFromString()</code> functions to separate them. Please note that the ListBox should be created with <code>wxLB_MULTIPLE</code> or <code>wxLB_EXTENDED</code> window style.
 +
|2=The control's selections (wxString).
 
|3=control_name  
 
|3=control_name  
 
|4=wxString  
 
|4=wxString  
Line 214: Line 363:
 
}}
 
}}
  
 +
 +
== All controls (common functions) ==
 +
 +
{{Function_Description_2args|1=
 +
=== EnableWindow(control_name, value) ===
 +
Enables/disables the window (control) identified by <code>control_name</code>.
 +
|3=control_name
 +
|4=wxString
 +
|5=The window's (control) name
 +
|6=value
 +
|7=bool
 +
|8=Enable if true, disable if false
 +
}}
 +
 +
 +
 +
= Common operations  =
 +
 +
== Get various common info ==
 +
In this section here are the commands associated with the Wizard.
 +
 +
{{Function_Description_0args|1=
 +
=== GetWizardType() ===
 +
|2=return wizard type (enum TemplateOutputType)
 +
}}
 +
 +
See [[Scripting_commands#Constants|Constants : enum TemplateOutputType]]
 +
 +
{{Function_Description_1args|1=
 +
=== FindTemplateFile(filename) ===
 +
|2=returns the full path name of the template file (wxString)
 +
|3=filename
 +
|4=const wxString&
 +
|5=the file name
 +
}}
 +
 +
== Project path page ==
 +
 +
{{Function_Description_0args|1=
 +
=== GetProjectPath() ===
 +
|2=project path (wxString)
 +
}}
 +
 +
{{Function_Description_0args|1=
 +
=== GetProjectName() ===
 +
|2=project name (wxString)
 +
}}
 +
 +
{{Function_Description_0args|1=
 +
=== GetProjectFullFilename() ===
 +
|2=project full filename (wxString)
 +
}}
 +
 +
{{Function_Description_0args|1=
 +
=== GetProjectTitle() ===
 +
|2=project title (wxString)
 +
}}
 +
 +
== Compiler page ==
 +
 +
{{Function_Description_0args|1=
 +
=== GetCompilerID() ===
 +
|2=compiler identification (wxString)
 +
}}
 +
 +
See [[Project_file#Compiler|Compiler : Internal name]]
 +
 +
=== Debug target ===
 +
{{Function_Description_0args|1=
 +
==== GetWantDebug() ====
 +
|2= (bool)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetDebugName() ====
 +
|2= target name (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetDebugOutputDir() ====
 +
|2= output directory (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetDebugObjetOutputDir() ====
 +
|2= object output directory (wxString)
 +
}}
 +
 +
=== Release target ===
 +
{{Function_Description_0args|1=
 +
==== GetWantRelease() ====
 +
|2= (bool)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetReleaseName() ====
 +
|2= release name (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetReleaseOutputDir() ====
 +
|2= output directory (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
==== GetReleaseObjetOutputDir() ====
 +
|2= object output directory (wxString)
 +
}}
 +
 +
== Build target page ==
 +
{{Function_Description_0args|1=
 +
=== GetTargetCompilerID() ===
 +
|2=compiler identification (wxString)
 +
}}
 +
 +
See [[Project_file#Compiler|Compiler : Internal name]]
 +
 +
{{Function_Description_0args|1=
 +
=== GetTargetEnableDebug () ===
 +
|2= (bool)
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetTargetName() ===
 +
|2= target name (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetTargetOutputDir() ===
 +
|2= output directory (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetTargetObjetOutputDir() ===
 +
|2= object output directory (wxString)
 +
}}
 +
 +
== File path page ==
 +
{{Function_Description_0args|1=
 +
=== GetFilename() ===
 +
|2=file name (wxString)
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetFileHeaderGuard() ===
 +
|2=(bool)
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetFileAddToProject() ===
 +
|2= (bool)
 +
 +
See also [[Wizard Scripting Commands#AddFileToTargets(the_wiz, the_file)|AddFileToTargets()]]
 +
 +
}}
 +
{{Function_Description_0args|1=
 +
=== GetFileTargetIndex() ===
 +
|2= (int)
 +
}}
 +
{{Function_Description_1args|1=
 +
=== SetFilePathSelectionFilter(const filter)===
 +
|2= (void)
 +
|3= filter
 +
|4= const wxString&
 +
}}
 +
 +
Example : Wizard.SetFilePathSelectionFilter(_T("C++ files (*.cpp;*.cxx;*.cc)|*.cpp;*.cxx;*.cc"));
 +
 +
= Functions of the script 'common_functions.script' =
 +
 +
This script contains functions more complex but easier to implement
 +
 +
location developing :
 +
src\plugins\scriptedwizard\resources\common_functions.script
 +
 +
location in use :
 +
share\CodeBlocks\templates\wizard\common_functions.script
 +
 +
{{Function_Description_2args|1=
 +
=== WarningsOn(base, compilerID) ===
 +
Valid compiler warnings according to the <code>compilerID</code>.
 +
|3=base
 +
|4=wxString
 +
|5=project, target, custom
 +
|6=compilerID
 +
|7=wxString
 +
|8=see [[Project_file#Compiler|Compiler : Internal name]]
 +
}}
 +
Example in a project :
 +
WarningsOn(project, Wizard.GetCompilerID())
 +
 +
{{Function_Description_2args|1=
 +
=== DebugSymbolsOn(base, compilerID) ===
 +
Valid compiler debug according to the <code>compilerID</code>.
 +
|3=base
 +
|4=wxString
 +
|5=project, target, custom
 +
|6=compilerID
 +
|7=wxString
 +
|8=see [[Project_file#Compiler|Compiler : Internal name]]
 +
}}
 +
Example in a project :
 +
DebugSymbolsOn(project, Wizard.GetCompilerID())
 +
 +
{{Function_Description_2args|1=
 +
=== OptimizationsOn(base, compilerID) ===
 +
Valid compiler optimization according to the <code>compilerID</code>.
 +
|3=base
 +
|4=wxString
 +
|5=project, target, custom
 +
|6=compilerID
 +
|7=wxString
 +
|8=see [[Project_file#Compiler|Compiler : Internal name]]
 +
}}
 +
Example in a project :
 +
OptimizationsOn(project, Wizard.GetCompilerID())
 +
 +
{{Function_Description_2args|1=
 +
=== CppExceptionsOn(base, compilerID) ===
 +
Valid compiler C++ Exceptions according to the <code>compilerID</code>.
 +
|3=base
 +
|4=wxString
 +
|5=project, target, custom
 +
|6=compilerID
 +
|7=wxString
 +
|8=see [[Project_file#Compiler|Compiler : Internal name]]
 +
}}
 +
Example in a project :
 +
CppExceptionsOn(project, Wizard.GetCompilerID())
 +
 +
 +
{{Function_Description_1args|1=
 +
=== VerifyDirectory(dir_or_macro) ===
 +
Verify a (provided) directory exists - otherwise throw an error.
 +
|2=return the true directory having replaced all possible macros else _T("") (wxString)
 +
|3=dir_or_macro
 +
|4=wxString
 +
|5=the directory or macros
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== VerifyMacro(macro) ===
 +
Try to make it a real path and verify it's existense
 +
|2=return the true directory having replaced macros else _T("")  (wxString)
 +
|3=macro
 +
|4=wxString
 +
|5=the macro
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== GetCompilerIncludeDir(selection, defaultSelection, defaultIncludeMacro) ===
 +
Get compiler include directory (taking GV's into account)
 +
|2=the include directory (which maybe translated from a macro) else _T("") (wxString)
 +
|3=selection
 +
|4=wxString
 +
|5=the original directory selection the user has made
 +
|6=defaultSelection
 +
|7=wxString
 +
|8=the default directory proposed by the wizard (using a macro)
 +
|9=defaultIncludeMacro
 +
|10=wxString
 +
|11=the default include directory proposed by the wizard (using a macro)
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== GetCompilerIncludeMacro(selection, defaultSelection, defaultIncludeMacro) ===
 +
Get compiler include macro (if possible and a GV has been provided)
 +
|2=the include macro (if possible), empty if not able to use a macro (wxString)
 +
|3=selection
 +
|4=wxString
 +
|5=the original directory selection the user has made
 +
|6=defaultSelection
 +
|7=wxString
 +
|8=the default directory proposed by the wizard (using a macro)
 +
|9=defaultIncludeMacro
 +
|10=wxString
 +
|11=the default include directory proposed by the wizard (using a macro)
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== GetCompilerLibDir(selection, defaultSelection, defaultLibMacro) ===
 +
Get compiler library directory (taking GV's into account)
 +
|2=the include directory (which maybe translated from a macro) else _T("") (wxString)
 +
|3=selection
 +
|4=wxString
 +
|5= the original directory selection the user has made
 +
|6=defaultSelection
 +
|7=wxString
 +
|8=the default directory proposed by the wizard (using a macro)
 +
|9=defaultIncludeMacro
 +
|10=wxString
 +
|11=the default library directory proposed by the wizard (using a macro)
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== GetCompilerLibMacro(selection, defaultSelection, defaultLibMacro) ===
 +
Get compiler library macro (if possible and a GV has been provided)
 +
|2=the library macro (if possible), empty if not able to use a macro (wxString)
 +
|3=selection
 +
|4=wxString
 +
|5= the original directory selection the user has made
 +
|6=defaultSelection
 +
|7=wxString
 +
|8=the default directory proposed by the wizard (using a macro)
 +
|9=defaultIncludeMacro
 +
|10=wxString
 +
|11=the default library directory proposed by the wizard (using a macro)
 +
}}
 +
 +
 +
{{Function_Description_1args|1=
 +
=== GetFixedProjectName(ProjectName) ===
 +
Converting project's name to be valid c++ identifier
 +
(needed for class names) and valid c++ file name
 +
(i.e. can not contain unicode and forbidden chars)
 +
|2=return correct name else _T("") (wxString)
 +
|3=ProjectName
 +
|4=wxString
 +
|5=project name
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== VerifyFile(dir, file, type) ===
 +
Verify the existence of a file of specific type
 +
|2=true, if the file exists, false otherwise (bool)
 +
|3=dir
 +
|4=wxString
 +
|5=the directory the file is expected in
 +
|6=file
 +
|7=wxString
 +
|8=name of the file to look for
 +
|9=type
 +
|10=wxString
 +
|11=descriptive name of the file to show in the error message
 +
}}
 +
 +
 +
{{Function_Description_3args|1=
 +
=== VerifyLibFile(dir, file, type) ===
 +
Verify the existence of a file of library type (add prefix lib, postfix .a and .lib)
 +
|2= true, if the library exists, false otherwise (bool)
 +
|3=dir
 +
|4=wxString
 +
|5=the directory the library is expected in
 +
|6=file
 +
|7=wxString
 +
|8=name of the library to look for (usually for e.g. "libGL.a" providing "GL" is enough.
 +
|9=type
 +
|10=wxString
 +
|11=descriptive name of the library to show in the error message
 +
}}
 +
 +
 +
{{Function_Description_2args|1=
 +
=== AddFileToTargets(the_wiz, the_file) ===
 +
Add a file to a selection of target(s).Thus the wizard must have had a FilePathPanel for the selection of these.
 +
|3=the_wiz
 +
|4=wxString
 +
|5=a reference to the wizard (to access the targets indexes)
 +
|6=the_file
 +
|7=wxString
 +
|8=name of the file (including fuill path) that shall be added
 +
}}
 +
 +
See also [[Wizard Scripting Commands#GetFileAddToProject()|GetFileAddToProject()]]
  
 
(to be continued)
 
(to be continued)

Latest revision as of 13:53, 8 July 2017

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.

Global variables and basic primitive functions

The first thing to know is that each wizard script contains

Global variables

example
ObjectName <- _T("name") 
ObjectIndex <- 0


Basic primitive functions

  • Common and mandatory for all types of project :

which contains different entry pages, see Adding wizard pages 

void BeginWizard ()


  • For a project :
    • to get the template files in a project
wxString GetFilesDir ()
    • to get generated files in a project
wxString GetGeneratedFile(index)
    • to create project
bool SetupProject (project)


  • For a single target (within a project)
bool SetupTarget (target, IsDebug)


  • For file creation
wxString CreateFiles ()


  • For an item to be defined by the user
bool SetupCustom ()


These functions will be performed by the manager wizard.

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.


Intro panel.png

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.


File path panel.png

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.


Project path panel.png

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.


Compiler panel.png

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.


Build target panel.png

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.


Generic single choice list.png

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.


Generic select path.png

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


GetListboxSelections(control_name)

Gets the selected items in the listbox identified by control_name to a wxString. The selections are separated ';' and returned as a single string. Use GetArrayFromString() functions to separate them. Please note that the ListBox should be created with wxLB_MULTIPLE or wxLB_EXTENDED window style.

Returns: The control's selections (wxString).


Parameter Type Description
control_name wxString The control's name


GetListboxStringSelections(control_name)

Gets the content strings of the selected items in the listbox identified by control_name to a wxString. The selections are separated ';' and returned as a single string. Use GetArrayFromString() functions to separate them. Please note that the ListBox should be created with wxLB_MULTIPLE or wxLB_EXTENDED window style.

Returns: The control's selections (wxString).


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


Common operations

Get various common info

In this section here are the commands associated with the Wizard.

GetWizardType()

Returns: return wizard type (enum TemplateOutputType)

See Constants : enum TemplateOutputType

FindTemplateFile(filename)

Returns: returns the full path name of the template file (wxString)


Parameter Type Description
filename const wxString& the file name

Project path page

GetProjectPath()

Returns: project path (wxString)

GetProjectName()

Returns: project name (wxString)

GetProjectFullFilename()

Returns: project full filename (wxString)

GetProjectTitle()

Returns: project title (wxString)

Compiler page

GetCompilerID()

Returns: compiler identification (wxString)

See Compiler : Internal name

Debug target

GetWantDebug()

Returns: (bool)

GetDebugName()

Returns: target name (wxString)

GetDebugOutputDir()

Returns: output directory (wxString)

GetDebugObjetOutputDir()

Returns: object output directory (wxString)

Release target

GetWantRelease()

Returns: (bool)

GetReleaseName()

Returns: release name (wxString)

GetReleaseOutputDir()

Returns: output directory (wxString)

GetReleaseObjetOutputDir()

Returns: object output directory (wxString)

Build target page

GetTargetCompilerID()

Returns: compiler identification (wxString)

See Compiler : Internal name

GetTargetEnableDebug ()

Returns: (bool)

GetTargetName()

Returns: target name (wxString)

GetTargetOutputDir()

Returns: output directory (wxString)

GetTargetObjetOutputDir()

Returns: object output directory (wxString)

File path page

GetFilename()

Returns: file name (wxString)

GetFileHeaderGuard()

Returns: (bool)

GetFileAddToProject()

Returns: (bool)

See also AddFileToTargets()

GetFileTargetIndex()

Returns: (int)

SetFilePathSelectionFilter(const filter)

Returns: (void)


Parameter Type Description
filter const wxString& -

Example : Wizard.SetFilePathSelectionFilter(_T("C++ files (*.cpp;*.cxx;*.cc)|*.cpp;*.cxx;*.cc"));

Functions of the script 'common_functions.script'

This script contains functions more complex but easier to implement

location developing : 

src\plugins\scriptedwizard\resources\common_functions.script

location in use : 

share\CodeBlocks\templates\wizard\common_functions.script

WarningsOn(base, compilerID)

Valid compiler warnings according to the compilerID.

Returns: Nothing.


Parameter Type Description
base wxString project, target, custom
compilerID wxString see Compiler : Internal name

Example in a project : 

WarningsOn(project, Wizard.GetCompilerID())

DebugSymbolsOn(base, compilerID)

Valid compiler debug according to the compilerID.

Returns: Nothing.


Parameter Type Description
base wxString project, target, custom
compilerID wxString see Compiler : Internal name

Example in a project : 

DebugSymbolsOn(project, Wizard.GetCompilerID())

OptimizationsOn(base, compilerID)

Valid compiler optimization according to the compilerID.

Returns: Nothing.


Parameter Type Description
base wxString project, target, custom
compilerID wxString see Compiler : Internal name

Example in a project : 

OptimizationsOn(project, Wizard.GetCompilerID())

CppExceptionsOn(base, compilerID)

Valid compiler C++ Exceptions according to the compilerID.

Returns: Nothing.


Parameter Type Description
base wxString project, target, custom
compilerID wxString see Compiler : Internal name

Example in a project : 

CppExceptionsOn(project, Wizard.GetCompilerID())


VerifyDirectory(dir_or_macro)

Verify a (provided) directory exists - otherwise throw an error.

Returns: return the true directory having replaced all possible macros else _T("") (wxString)


Parameter Type Description
dir_or_macro wxString the directory or macros


VerifyMacro(macro)

Try to make it a real path and verify it's existense

Returns: return the true directory having replaced macros else _T("") (wxString)


Parameter Type Description
macro wxString the macro


GetCompilerIncludeDir(selection, defaultSelection, defaultIncludeMacro)

Get compiler include directory (taking GV's into account)

Returns: the include directory (which maybe translated from a macro) else _T("") (wxString)


Parameter Type Description
selection wxString the original directory selection the user has made
defaultSelection wxString the default directory proposed by the wizard (using a macro)
defaultIncludeMacro wxString the default include directory proposed by the wizard (using a macro)


GetCompilerIncludeMacro(selection, defaultSelection, defaultIncludeMacro)

Get compiler include macro (if possible and a GV has been provided)

Returns: the include macro (if possible), empty if not able to use a macro (wxString)


Parameter Type Description
selection wxString the original directory selection the user has made
defaultSelection wxString the default directory proposed by the wizard (using a macro)
defaultIncludeMacro wxString the default include directory proposed by the wizard (using a macro)


GetCompilerLibDir(selection, defaultSelection, defaultLibMacro)

Get compiler library directory (taking GV's into account)

Returns: the include directory (which maybe translated from a macro) else _T("") (wxString)


Parameter Type Description
selection wxString the original directory selection the user has made
defaultSelection wxString the default directory proposed by the wizard (using a macro)
defaultIncludeMacro wxString the default library directory proposed by the wizard (using a macro)


GetCompilerLibMacro(selection, defaultSelection, defaultLibMacro)

Get compiler library macro (if possible and a GV has been provided)

Returns: the library macro (if possible), empty if not able to use a macro (wxString)


Parameter Type Description
selection wxString the original directory selection the user has made
defaultSelection wxString the default directory proposed by the wizard (using a macro)
defaultIncludeMacro wxString the default library directory proposed by the wizard (using a macro)


GetFixedProjectName(ProjectName)

Converting project's name to be valid c++ identifier (needed for class names) and valid c++ file name (i.e. can not contain unicode and forbidden chars)

Returns: return correct name else _T("") (wxString)


Parameter Type Description
ProjectName wxString project name


VerifyFile(dir, file, type)

Verify the existence of a file of specific type

Returns: true, if the file exists, false otherwise (bool)


Parameter Type Description
dir wxString the directory the file is expected in
file wxString name of the file to look for
type wxString descriptive name of the file to show in the error message


VerifyLibFile(dir, file, type)

Verify the existence of a file of library type (add prefix lib, postfix .a and .lib)

Returns: true, if the library exists, false otherwise (bool)


Parameter Type Description
dir wxString the directory the library is expected in
file wxString name of the library to look for (usually for e.g. "libGL.a" providing "GL" is enough.
type wxString descriptive name of the library to show in the error message


AddFileToTargets(the_wiz, the_file)

Add a file to a selection of target(s).Thus the wizard must have had a FilePathPanel for the selection of these.

Returns: Nothing.


Parameter Type Description
the_wiz wxString a reference to the wizard (to access the targets indexes)
the_file wxString name of the file (including fuill path) that shall be added

See also GetFileAddToProject()

(to be continued)


Mandrav 11:28, 9 July 2006 (EDT)

Retrieved from "https://wiki.codeblocks.org/index.php?title=Wizard_Scripting_Commands&oldid=9288"