Wizard scripts

From Code::Blocks

When you click "File->New", you 're presented with wizards to create various new things. These are:

  • New project
  • New build target inside the active project
  • New file(s)
  • New anything (custom)
  • User template


"New..." dialog


All the above functionality (except user templates) is provided by wizard scripts. In this section, I 'm gonna try to explain everything about wizard scripts.


Before starting out creating your own wizard scripts or editing existing ones, these are "must read":


Where are they located?

Wizard scripts are located under the Code::Blocks' data folder. The base wizards folder is [Code::Blocks install dir]/share/codeblocks/templates/wizards.

Scripts are arranged in subfolders (one for each wizard) inside the above folder. To make this clear, the structure of this folder is displayed below with the "console" wizard expanded to see all its files:

Base folder
  console
    c
      main.c
    cpp
      main.cpp
    logo.png
    wizard.png
    wizard.script
    wizard.xrc
  fltk
  ...
  ...
  empty
  ...
  ...
  common_functions.script
  config.script

What files do I need to create a valid wizard?

There are three files that are absolutely needed for your wizard to be registered correctly:

  • logo.png - The wizard's icon. This will be displayed in the "New..." dialog.
  • wizard.png - The wizard's bitmap. This bitmap is displayed on the left side in the wizard dialog.
  • wizard.script - The wizard's script. You didn't think you could have a scripted wizard without a script, did you? ;)
  • wizard.xrc - The wizard's custom pages. This file is optional but if you are using custom pages then all the panels as XRC resources must be placed in wizard.xrc.

How do I edit an existing wizard?

That's easy: edit its script :). This can be done easily from within Code::Blocks. Just right-click on the wizard's icon in the "New..." dialog. The same context menu contains an option to edit the global configuration script (config.script).


Wizard scripts context menu


Note that no restart is needed if you edit a script. Just save it and launch the wizard again :).

Code::Blocks needs to be restarted only when editing the global configuration script. An informational message is displayed in this case so you don't wonder why your changes are not taking any effect ;).


How do I create a new wizard?

First thing you should do is read about Wizard Scripting Commands and use it as a reference on what commands are accepted and what their syntax is.


How do I register my new wizard?

Wizard scripts are registered with Code::Blocks by adding a registration line in the global wizards configuration script (config.script).

Let's look at the registration of an existing wizard:

// config.script
function RegisterWizards()
{

    RegisterWizard(wizProject,     _T("empty"),        _T("Empty project"),         _T("Console"));

    // more wizards following
    ...
    ...
}

The arguments to the RegisterWizard() function are as follows:

  1. The type of output for this wizard. Can be one of the following, self-explaining types:
    • wizProject
    • wizTarget
    • wizFiles
    • wizCustom
  2. The subfolder where this wizard's files are located
  3. The wizard's title, as will appear in the "New..." dialog
  4. The wizard's category. Free-form text. If your wizard fits one of the existing categories, please use it.

After you add the new wizard in config.script, you must restart Code::Blocks to re-initialize all the registered wizards.


Mandrav 07:51, 9 July 2006 (EDT)