Minimal Example

Malcolm Nealon

Introduction

The purpose of this tutorial is to teach the reader how to use the wxWidgets related Form Designer written by Guru Karithresan. Wx-DevCpp is therefore an adaptation of DevCpp which is available from http://www.bloodshed.net/devcpp

We are going to be creating the wxWidgets Minimal sample which looks something like this:

However in order to ensure that we cover as much as possible in such a basic tutorial, We are going to add a toolbar, as well one of the standard common dialogs, just to illustrate how it is done.

Installing wx-DevCpp

Wx-DevCpp is available from http://wxdsgn.sourceforge.net/. On the web page which appears is a link for the download. At the time of writing the available version is Full wx-devcpp beta 6.4 distribution - (Form designer, mingw 3.3.1 and wxWidgets 2.53)

Download the installer package, find the downloaded file and double click on it to start the installer. Follow the instructions on screen, allow wx-DevCpp to create the code completion cache and you should be ready.

Once the installer is complete, the program is ready to use.

Checking the Installation

As a precaution against an incorrect installation I generate a new project to create a basic wxWidgets Frame. This is simple to do. First we create a new project.

We need to select a wxWidgets based project.

So we will simply choose the wxWidgets Frame project.

and find/create somewhere to save the project. Once the Project is open we need to simply press F9 and the program should compile and run without error producing:

We can in fact use this project as the starting point for our own project, and as such we need to change a couple of properties of the frame. I am attempting to clone the minimal sample (initially) so the first thing we want to do is change the size of the form. Firstly we need to expand the project tree by clicking on the cross,

producing

and following this we select the newProgramFrame.wxform file. The IDE changes to reflect the selection.

We can now see the form designer that Guru has implemented. On the left we can see the properties editor, in the centre the form we are designing, and on the right we see a list of wxWidgets that are supported by wx-DevCpp. The drop down list in the upper right offers selections which limit the visible controls.

You can see on the properties editor the current Height and Width of the form. Simply click once on the property you wish to change and enter a new value to replace the highlighted value. Easy Peasy. You should see the prototype form change to reflect your new values.

Next we need to add two controls. firstly the status bar and secondly the menu. To make this a little simpler, we drop the drop down list down, and select the option "Controls", we then select the option and then left mouse click on the Form Prototype. The result is seen on the form prototype.

Editing the StatusBar

We now come to one of the less than savoury aspects of wx-DevCpp. Several of the control creation dialogs still need a little work, and one of those is the StatusBar Field Editor dialog. To access the StatusBar Field Editor dialog we click on the Fileds property on the properties bar: Clicking on the ellipsis button causes the StatusBar Field Editor dialog to appear.

This works as follows. On an empty statusbar, first enter the desired text in the Caption text box, alter the size of the field,

then press the Add button.

Notice that the status bar in the dialog reflects the statusbar for the Form. To Add another field, simply repeat. Pressing Add when the contents of the Field Properties text boxes are unchanged results in an "empty" field.

We can now see that our original text is too large for the field. We need to alter the field. However, wx-DevCpp at the moment doesn't allow re-editing of the status bar fields. In order to correct the error, we have to repeat the previous steps, but increasing the Width value.

Follow this with an empty field again.

Then select the Initial field in the Fields list, and click on Delete, repeat for the first empty field name.

Once the statusbar is to your liking, pressing OK saves the statusbar.

Note that currently there is no re-editing possible to the contents of the StatusBar fields. You can however delete fields, So with a little work and repetition you can still create statusbars to your liking. Just to make sure we can press F9 again and see our Frame with a status bar.

Adding a Menu to your Form

To add a mernu to a form simply change the Control dropdown list to menu:

Click ONCE on MenuBar component then once on the form. You will see an icon representing the menu appear on the form at the mouse position. Currently wx-DevCpp does not support a WYSIWYG menu system.

In the properties editor, click on the Menu Items option, then on the ellipsis button which appears.

We are then presented with the Menu Item Editor dialog.

The Menu we will create is very simple, two upper level values and two lower level values. Initially we click on Add Item. We can see that wx-DevCpp has added a few items for us, however we will edit them to reflect the minimal sample. Change the Caption to &File, the & preprocesses the accelerator key, such that Alt+F key combination activates the File menu option etc.. Now click in the ID Name text field.

We can see that wx-DevCpp has generated an ID name and Value for us. We can accept these or use our own. For ease I will accept the values from wx-DevCpp. We have to Apply every change in the Menu Item Editor dialog, so do that now. We can continue adding the top level of our menu, by repeating our previous steps for the &Help menu option.

Select our &File menu item and then click the Creat Submenu button. We can see that wx-DevCpp has created a submenu beneath the File menu option.

We change the Caption to reflect our minimal example, which also shows the use of a key combination to acheive the same result. We can simply choode Alt+X and the program should exit.

Next we add the text "Quit this program" in the Hint text box. This text will be shown in the statusbar when we select this menu option. We also want to produce a function prototype into which we can enter our own code for this menu option. We want to close the program whenever this menu option is activated, this is an OnMenu event, so we press the Create button next to the OnMenu drop down box.

We receive a warning that we need to save our files before we can create the function, so go ahead and save them.

And just for fun, accept the new function name.

Finish this submenu by Applying the changes. Now select the &Help menu option in the left hand pane, press Create Submenu, and repeat the process for our About submenu option.

Apply the changes and OK. We're out of here. Once back in the IDE press F9 again, and see the results.

Close the program (by the X box, our program still needs a little work) and return to the IDE.

Now look at the created source code from wx-DevCpp. We can see the new functions created by wx-DevCpp which we need to edit. Simply change the created code:

/*

* Mnuexitaltx1005Click

*/

void newProgramFrame::Mnuexitaltx1005Click(wxCommandEvent& event)

{

    // insert your code here

    event.Skip();

}

to

void newProgramFrame::Mnuexitaltx1005Click(wxCommandEvent& event)

{

    // true is to force the frame to close

    Close(true);

}

and

/*

* Mnuaboutf11006Click

*/


void newProgramFrame::Mnuaboutf11006Click(wxCommandEvent& event)

{

    // insert your code here

    event.Skip();

}

to

/*

* Mnuaboutf11006Click

*/


void newProgramFrame::Mnuaboutf11006Click(wxCommandEvent& event)

{

    wxString msg;

    msg.Printf(

        _T("This is the About dialog of the minimal sample.\n")

        _T("Welcome to %s"), wxVERSION_STRING

    );

   

    wxMessageBox(msg, _T("About Minimal"),wxOK | wxICON_INFORMATION, this);

}

Press F9 again and try the menu out, don't forget the shortcuts (Alt+X, F1), and check the results.

Close the program and return to the IDE.

Adding A Toolbar

Select the Form designer tab, and in the Control drop down box, select Toolbar, the possible widgets are displayed.

Click on the ToolBar control followed by clicking on the form prototype. You should see a ToolBar prototype appear at the top of the form prototype.

Adding controls to the Toolbar is now merely clicking once on the control and then once on the ToolBar prototype. We will need some bitmaps for the ToolBar buttons, so copy the bitmaps folder from the wxWidgets Toolbar Sample folder to your project folder.

Now, we can add a couple of buttons. Click once on the ToolButton control followed by a single mouse click on the ToolBar prototype.

In the Properties editor, select Active Bitmap and then click on the ellipsis button which appears.

we are then presented with thePicture Editor dialog.

Click on Load, and in the File Open dialog which follows, select the Open.bmp file. This bitmap appears in the Picture Editor Dialog.

And click on OK. The bitmap appears in the ToolBar button Prototype.

Repeat the process of adding a Toolbar Button, and this time in the File Open dialog select the Help.bmp file. This bitmap appears in the Picture Editor Dialog.

And click on OK. The bitmap appears in the ToolBar button Prototype.

We need some sort of event responce to the toolbar buttons, so we will add couple of common dialogs.

Adding Common Dialogs

In the Control drop down box, select Toolbar, the possible widgets are displayed. We are still in Toolbar mode at this point, so click on the Form prototype to select it.

Click once on the OpenFileDialog control, and once on the Form prototype. An icon representing the OpenFileDialog appears on the form prototype.

Repeat the process for a MessageDialog.

With the Message Dialog still selected, we can use the property editor to provide a title and a message, Change the Title to "Mal's Tutorial", and the message to something like "wx-DevCpp kicks some ass".

ToolBar Button Events

For this part of the tutorial, we are going to react to ToolBar Button presses.

In the Form prototype, click once on the first button (the one with the Open.bmp attached), then in the property editor, select the Events tab.

From here we can select the type of event we wish to respond to.

We wish to react to a button click, so (no rocket science here) select the OnClick option and in the drop down box

we select <Add New Function> and are immediately greeted with:

so we accept this and are placed in the source code at the standard code for this button click which looks like this:

void newProgramFrame::WxToolButton1Click(wxCommandEvent& event)

{

    // insert your code here

    event.Skip();

}

If we look at the code generated in the newProgramFrame::CreateGUIControls function, we can see that the code created for the OpenFile Dialog is:

WxOpenFileDialog1 = new wxFileDialog(this, "Choose a file", "", "", "*.*", wxOPEN);

We change newProgramFrame::WxToolButton1Click to:

/*

* WxToolButton1Click

*/


void newProgramFrame::WxToolButton1Click(wxCommandEvent& event)

{

    WxOpenFileDialog1->ShowModal();

}

We repeat the process for the second toolbar button, but this time we reference the MessageDialog we created previously. I leave this as an exercise for the reader.

The Final Result

Compile the final program, and check that everything works as expected. Pressing the toolbar buttons should result in dialogs opening, producing something like:

Hopefully this tutorial has provided a brief glimpse into the possibilities offered by wx-DevCpp to wxWidgets programmers.