Code::Blocks - User contributions [en]

Creating a simple "Hello World" plugin

2006-11-28T09:02:56Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we denoted the project title as '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you will see the next plugin property dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

(New)
The time is right and we should compile the project. The next step is to install the plugin. Go to the '''Plugins->Manage plugins''' option. Hit the '''Install new''' button. The manager ask you where the plugin lies. Go to that folder and select the *.cbplugin file. Code::Blocks imports your plugin automatically. If this procedure was successful you can see your plugin in the ''Installed plugins'' list. To execute your plugin go to the '''Plugins''' menu and choose your plugin. That's all.

(Old)
This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

A short overview about Code::Blocks architecture

2006-11-24T15:54:49Z

Pegasus: /* Introduction */

[[Category:Developer Documentation]]
The following are guidelines about the architecture of Code::Blocks. Anyone writing code or a patch for Code::Blocks, should read this to understand how Code::Blocks works.

== Introduction ==

C::B keeps projects '''''cbProject''''' in a workspace '''''cbWorkspace'''''. This workspace can have more than one project. This is managed by the '''''ProjectManager'''''. Here a short overview:

[[Image:Codeblocks.jpg]]

The words with cursiv font are classes in C::B. The '''''cbProject''''' itself manages different targets '''''ProjectBuildTargets''''' and different files '''''ProjectFiles'''''.

== Messages ==

C::B has a message window where you can see all kind of messages. This messages are managed by '''''MessageManager'''''.

[[Image:messages.jpg]]

If you want to put some messages on this windows you should use that manager.

== Access to the managers ==

All managers in C::B can accessed by the '''''Manager''''' class. For example if you want to access to the ProjectManager you should use the Manager::Get() method:

''ProjectManager* prjmgr = Manager::Get()->GetProjectManager();''

File:Messages.jpg

2006-11-24T15:46:28Z

Pegasus:

A short overview about Code::Blocks architecture

2006-11-24T15:37:11Z

Pegasus: /* Introduction */

A short overview about Code::Blocks architecture

2006-11-24T15:30:19Z

Pegasus: /* Introduction */

File:Codeblocks.jpg

2006-11-24T15:23:06Z

Pegasus:

A short overview about Code::Blocks architecture

2006-11-24T15:20:56Z

Pegasus:

Developer documentation

2006-11-24T15:14:27Z

Pegasus:

[[Category:Code::Blocks Documentation]]
[[Category:Developer Documentation]]
Articles for Code::Blocks developers.

* '''[http://launchpad.net/products/codeblocks/ Translation]'''
:Code::Blocks uses Launchpad to coordinate translation efforts.

* '''[[Coding style]]'''
:The source code formatting style used in the Code::Blocks' source.

* '''[[Creating a custom lexer for Code::Blocks editor]]'''
:How to add support for new syntax lighting schemes.

* '''[[Creating a patch to submit to BerliOS (Patch Tracker)]]'''
:Creating a diff file and then submitting it to the patch tracker.

* '''[[Unicode Standards]]'''
:Information about unicode standards and how unicode is handled in Code::Blocks' source code.

* '''[[Various development tips]]'''
:List of various development tips for Code::Blocks.

* '''[[Scripting Code::Blocks]]'''
:Information about scripting Code::Blocks with [http://www.squirrel-lang.org/ Squirrel].

* '''[[A short overview about Code::Blocks architecture]]'''
:Information about the architecture of Code::Blocks.

== Plugin development ==

* [[Creating a simple "Hello World" plugin]]
* [[Creating a Plug-in which modifies CB's Menus]]
* [[Creating a plugin that actually does something]]

* [[Research on doing a Plug-in for embedded help in CB]]

== Scripting ==

Using scripting to extend Code::Blocks' functionality

* [[Wizard scripts|Creating a new project wizard]]

Creating a simple "Hello World" plugin

2006-11-23T15:05:08Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin property dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

(New)
The time is right and we should compile the project. The next step is to install the plugin. Go to the '''Plugins->Manage plugins''' option. Hit the '''Install new''' button. The manager ask you where the plugin lies. Go to that folder and select the *.cbplugin file. Code::Blocks imports your plugin automatically. If this procedure was successful you can see your plugin in the ''Installed plugins'' list. To execute your plugin go to the '''Plugins''' menu and choose your plugin. That's all.

(Old)
This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T14:59:04Z

Pegasus: /* Compile! (And test) */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

(New)
The time is right and we should compile the project. The next step is to install the plugin. Go to the '''Plugins->Manage plugins''' option. Hit the '''Install new''' button. The manager ask you where the plugin lies. Go to that folder and select the *.cbplugin file. Code::Blocks imports your plugin automatically. If this procedure was successful you can see your plugin in the ''Installed plugins'' list. To execute your plugin go to the '''Plugins''' menu and choose your plugin. That's all.

(Old)
This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T14:29:59Z

Pegasus: /* Compile! (And test) */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

(New)
After compiling the project you get different files. A *.dll file, and a *.zip file. You can test your plugin now with the '''Plugins->Manage plugins''' option. Hit now the Install new button go to the folder where your project lies and select the *.cbplugin file. Code::Blocks imports your plugin automatically. If this procedure was successful you can see your plugin in the ''Installed plugins'' list. To execute your plugin go to the '''Plugins''' menu and choose your plugin. That's all.

(Old)
This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T14:29:09Z

Pegasus: /* Compile! (And test) */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

(New)
After compiling the project you get different files. A *.dll file, and a *.zip file. You can test your plugin now with the '''Plugins->Manage pluins''' option. Hit now the Install new button go to the folder where your project lies and select the *.cbplugin file. Code::Blocks imports your plugin automatically. If this procedure was successful you can see your plugin in the ''Installed plugins'' list. To execute your plugin go to the '''Plugins''' menu and choose your plugin. That's all.

(Old)
This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T14:10:53Z

Pegasus: /* Adding Functionality */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Manage plugins''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T13:52:34Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading it. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Plugin Manager''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T12:32:17Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the title of your project. You can see that we called that '''HelloWordPlugin'''. The other field are self-explanatory. If you click the Next button you came to the next plugin propertiy dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Plugin Manager''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

Creating a simple "Hello World" plugin

2006-11-23T12:25:41Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the name of your project. You can see that we called that '''MyNewPlugin'''. The other field are self-explanatory. If you click the Next button you came to the Plugin project dialog:

[[Image:Plugindevelop_3.jpg]]

Let's denote the plugin name with '''HelloWorld'''. After clicking the next button a new dialog apears and you can edit a bunch of information about your plugin. In the next step you can choose which compiler you want to use for your plugin project.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Plugin Manager''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

File:Plugindevelop 4.jpg

2006-11-23T12:16:56Z

Pegasus:

Creating a simple "Hello World" plugin

2006-11-23T12:13:06Z

Pegasus: /* Creating the Plugin Project */

[[Category:Plugin development]]
[[Category:Outdated]]
{{outdated}}
'''NOTE''': This tutorial was written using the Code::Blocks final beta under windows.

==Prerequisites==

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. In order to use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see
[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)|Compiling wxWidgets 2.6.2 to develop Code::Blocks]]

To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks [https://www.codeblocks.org/downloads.shtml download page]. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under ''Codeblocks\sdk\include'', so ''cbPlugin.h'' is ''Codeblocks\sdk\include\cbPlugin.h'' for example.

==Overview==

This tutorial will guide you through the creation of a simple "Hello World" plugin, which when activated displays "Hello World!" in the Code::Blocks log tab below the editor. This could be done completely by hand, but Code::Blocks contains a very useful plugin project generator (which, incidentally, is a plugin itself), so we'll use that.

==Creating the Plugin Project==

Select the '''File->New->Project''' option from the main menu bar and choose the Code::Blocks Plugin Wizard. You will see a dialog box with some information but you can skip that after reading. Now you will see the following dialog box:

[[Image:Plugindevelop_2.jpg]]

In the first edit field write the name of your project. You can see that we called that '''MyNewPlugin'''. The other field are self-explanatory. If you click the Next button you came to the Plugin project dialog:

[[Image:Plugindevelop_3.jpg]]

Now you can type the name of the plugin itself that is used in the plugin manager. We denoted it with '''HelloWorld'''.

===Plugin Type===

The Code::Blocks SDK contains interfaces for various different types of plugins in the ''cbPlugin.h'' file. The drop down ''Plugin type'' list in the wizard allows you to select which type of plugin you wish to build - essentially which class the main plugin interface class will inherit from. We want to build a Tool plugin, so select that from the list. Tool type plugins are added to the Plugins main menu submenu automatically, and their ''Execute'' method is called when they are selected by the user. We will use this later in order to display our message.

===Plugin Info===

The ''Plugin name'' field is the name of the plugin interface class which the wizard will create. Enter "HelloWorldPlugin" here. More information can be provided by clicking on the ''Enter Plugin Info'' button. The fields here are fairly self explanitory, but one which you should pay particular attention to is the ''Title'' field, since this is what Code::Blocks will use to refer to the plugin in the menus. In the generated code, the plugin info is kept in the plugin class' ''m_PluginInfo'' member, which is of the type ''PluginInfo'' and is set in the plugin interface class' constructor. ''PluginInfo'' is detailed in ''cbPlugin.h'', if you want to go take a look.

===Provides Configuration Dialog===

This indicates whether or not the plugin is to provide a configuration dialog which can be accessed through the '''Settings->Configure Plugins''' submenu. We don't need one, so leave this box unchecked.

===Filenames===

The filenames should have been filled in automatically by the dialog when you entered the Plugin name, if you used the name "HelloWorldPlugin", for example, these should be helloworldplugin.h and helloworldplugin.cpp respectively. If you want to change the names of the files generated, this is where to do it (this tutorial will assume you have left them as the default values).

The guard-block box is simply if you wish to place inclusion guards in the header file, and if you do what symbol to use. If you don't know what these are then just leave it as it is.

Click '''Create''' and take note of the next dialog box's message about the SDK include and library directories, that's what we'll be dealing with next.

==Letting the project know where to find the SDK==

Code::Blocks should have created a new project called "Custom Plugin". Before we can compile anything we need to make sure that the compiler knows where the sdk files are in order to include headers and link the libraries. If your compiler has not been setup to know where wxWidgets is yet then this must also be done (see the links in Prerequisites for more details).

Right click on the project and select '''Build Options''' then the '''Directories''' tab. Here, make sure the '''Compiler''' tab is selected then click on the '''Add''' button. Browse to where you unzipped the SDK and select the ''include'' directory (for example ''C:\CodeBlocks\sdk\include'' if you installed the SDK there), then click okay and select whether or not the path should remain relative. Go to the "Linker" tab and add the "lib" directory under where the SDK was installed in similar fashion (following my install, this would be in ''C:\CodeBlocks\sdk\lib'').

===Linker Options===

If you click on the '''Linker Options''' tab at the top level in the Build Options dialog, you will see that the plugin is being linked to the Code::Blocks core library (codeblocks) and the wxWidgets library (wxmsw242 under windows ''NOTE: The plugin generator uses 2.4.2, if you're using a different version of wxWidgets then change this'').

===Compiler Options===

The '''Compiler Options''' tab shows that several symbols have been defined when the plugin is compiled: ''__GNUWIN32__'', ''WXUSINGDLL'' and ''BUILDING_PLUGIN'' in this case (using windows). The first two are indicators to wxWidgets of the compiler and DLL options to use, and the last is an indicator to the Code::Blocks SDK headers that they are being used to build a plugin (which affects whether or not symbols are exported or imported for the DLL - see ''cbPlugin.h'' for example).

==Adding Functionality==

The plugin wizard should have generated us helloworldplugin.h and helloworldplugin.cpp. The header file contains the class definition and a C function declaration which is used to load the plugin when asked by the main Code::Blocks program (''GetPlugin''). What we're interested in, however, is the definition of the class methods in helloworldplugin.cpp. The plugin wizard has generated us a constructor in which the ''m_PluginInfo'' information is set, and three methods. ''OnAttatch'' and ''OnRelease'' are methods called to inform the plugin when it is attached (the user has selected it and Code::Blocks has loaded it) or released (Code::Blocks no longer has a use for it or is shutting down). Since our plugin does not need to perform any actions on loading or shutting down, we can leave these as they are.

The ''Execute'' method, as mentioned earlier, is what we are really interested in. We are going to use the MessageManager class to add a log message in the window beneath the editor. To do this we will need access to both the Manager class and the MessageManager class. Manager is and internal Code::Blocks class which is used to keep track of internal information and the various task specific managers (like the MessageManager and EditorManager - which is used to keep track of all the open files and their editors). MessageManager is responsible for both normal output and debugging output (see ''messagemanager.h'' for more details). Replace the generated Execute method with this new one:

int HelloWorldPlugin::Execute()
{
if( !IsAttached() )
return -1;
Manager::Get()->GetMessageManager()->Log( _("Hello World!") );
return 0;
}

This new method uses the Manager's static Get method to return the singleton Manager object, then uses that to access the MessageManager through the GetMessageManager method. MessageManager has a method called ''Log'' which appends a string to the bottom of the output log, so we use this to add the "Hello World!" message. The _() construct is part of wxWidgets' internationalisation utilities, and more information on it can be found in the wxWidgets [http://wiki.wxwidgets.org/wiki.pl?WxWidgets_Source_Oddities documentation].

The first two lines check to see if the plugin has been attatched (in other words selected by the user in the '''Plugins->Plugin Manager''' menu), and thus whether it should perform any action at all. As far as I can tell, the return value of Execute is not used anywhere, but all the default plugins use -1 for failure and 0 for success (much like the main function in a C program) so that is what is used here.

Add headfiles to helloworldplugin.cpp

#include <manager.h>
#include <messagemanager.h>

Now we have our code in place we are ready to...

==Compile! (And test)==

This should produce a file called HelloWorldPlugin.dll, which can be tested by copying to the ''CodeBlocks\share\CodeBlocks\plugins\'' directory and restarting Code::Blocks. There should now be an option in the '''Plugins''' menu for "Hello World" (or whatever the title field was set to when the plugin was generated - or in ''m_PluginInfo''). Click on this and "Hello World!" should appear in the Code::Blocks logging window. Congratulations, you've just created your first plugin!

==Further Information==

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets [http://www.wxwidgets.org/docs.htm documentation]. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the [https://www.codeblocks.org/downloads.shtml download page].

Hopefully this tutorial has helped you work through a few fundamentals in terms of creating plugins, happy coding!

File:Plugindevelop 3.jpg

2006-11-23T12:01:24Z

Pegasus:

File:Plugindevelop 2.jpg

2006-11-23T12:01:08Z

Pegasus:

File:Plugindevelop 1.jpg

2006-11-23T11:46:08Z

Pegasus: