Extended wxDev-C++ Tutorial

Dan Koga

Introduction

This tutorial shows you how to build an application using wx-Devcpp and wxWidgets. wx-Devcpp is an extension to Dev-C++, an open-source IDE for C/C++. wx-Devcpp adds a visual form designer that lets you easily create dialogs and frames and layout controls within the dialogs and frames. wxWidgets is an open-source C++ cross-platform GUI framework.

We will build a program, Tidy Text, that removes all ">" characters (or others you specify) from text on the clipboard. For example, the text from an email that has been forwarded several times. Tidy Text does the following:

-Copies text from the clipboard.

-Removes all occurrences of a specified set of characters from the text.

-Displays the cleaned text in an edit window.

-Copies the cleaned text to the clipboard.

Tidy Text will contain typical elements of a GUI application -- sizable application (frame) window, menu bar, tool bar, edit window and status bar. We will also create a dialog box to enter program options.

If you have not installed wx-DevCpp you can download it from their home page. The installation is straightforward.

Installation Notes

-I recommend installing to the default directory (C:\Dev-Cpp) as I have read reports of people encountering problems if they install to a directory path containing spaces.

-The beta 6.8 version has a minor bug -- if you change the User's Default Directory (Tools | Environment Options | Files & Directories tab) you will have to edit the project resource directories (Project | Project Options | Directories tab | Resource Directories). A nonexistent directory is listed so the resource compiler can not find some files and the build will fail with Error 255 or Error 1. Change the directory to C:\Dev-Cpp\include (if you used the default install directory). The developers are aware of the problem and it should be fixed in the next release.

New Project

To create a new project:

1. Select File | New | Project. The New Project dialog is displayed.



2. Make sure the Basic tab is selected then select wxWidgets Frame. In the Name box enter TidyText (no space). Select Ok.

3. wx-Devcpp displays a Create New Project file selection dialog box. Navigate to the directory where you want wx-Devcpp to save the project files or create a new directory and select the new directory. Select Save.

4. wx-Devcpp displays the Create New Project - wxWidgets Frame dialog.



5. In the Title box enter Tidy Text (note the space). This is the name displayed in the application's title bar.

6. Optionally, enter a name in the Author box. The name will be inserted in source code files.

7. In the Default Styles section, in addition to the initial selections, select Resize Border and Max Button. These are the styles that will be applied to the application frame window. Select Create.

8. Select Project | Project Options. Make sure the General tab is selected.



9. In the Icon section click the Library button.

10. In the Icon Library window double-click the Editor icon. This is the icon associated with the program. Select OK in the Project Options dialog. wx-Devcpp copies the icon file to the project directory.

11. In the Properties tab click the Icon property then click the Ellipsis button.



12. In the Picture Editor dialog click the Load button.

13. In the Open dialog select the TidyText.ico file then select the Open button.

14. Select the OK button in the Picture Editor dialog.

This is the icon displayed in the application title bar. The icon will be resized to fit the title bar.

Note: The resized icon may appear rather dark. If you want a lighter title bar icon you can use this . Just right-click and save it.

wx-Devcpp creates all the files needed for a bare-bones application that you can compile and run. Try it out by pressing F9 (Execute | Compile & Run).

Note: If you get the following error:

C:\Dev-Cpp\Projects\TidyText\Makefile.win

[Build Error]  [TidyText_private.res] Error 255


check the project resource directories entry (Project | Project Options | Directories tab | Resource Directories tab). Make sure the directory is C:\Dev-Cpp\include. If not, select the directory, use the edit box to change it, then select Replace.

Status Bar

We now have a working skeleton application. The first item we will add is something simple, a status bar. This will show you the basics of using the wx-Devcpp form designer.

To add a status bar:

1. In the Control Filter drop-down list, located on the right side of the workspace above the list of all controls, select Controls.



Note: The list of controls is visible only when a frame or dialog is being edited.

2. Click on StatusBar.



3. Then click on the Tidy Text form window.



wx-Devcpp adds a status bar to the bottom of the application window.

Note the [*] characters preceding the name of some file names in the tabs. This indicates the file has been modified. wx-Devcpp added a member variable (WxStatusBar1) to the TidyTextFrm class and code to create the status bar.

4. Make sure the status bar is selected (click it to select it or use the drop-down list above the Properties/Events tabs). You can tell which control is selected by the eight square sizing boxes around the control.

5. Click the Name property in the Property tab window. Change the Name to m_pStatusBar.



The Name property is the member variable name wx-Devcpp created. I prefer to prefix member variables with "m_" and "p" if the variable contains a pointer, which it does in this case.

6. Click the IDName property and change it to ID_STATUSBAR.

wx-Devcpp assigns a numeric value (IDValue) to IDName and uses that value to identify each control in a window. The name and value are defined in the frame class definition.

wx-Devcpp makes adding and editing controls a simple task. In addition, it takes care of adding and updating the necessary code for the controls.

Menu Bar

In this lesson we will add a Menu Bar, a menu and a menu item.

To add a menu bar:

1. In the Control Filter drop-down list select Menu.

2. Click the MenuBar item.



3. Click in the Tidy Text frame window.



Tip: You can adjust the initial display size of the frame window by dragging an edge or corner, just like a normal frame window. The Height and Width properties change as you drag. I made the frame window smaller to save space on this page.

wx-Devcpp displays a MenuBar icon in the frame window. Currently, there is no visual drag-drop editing feature for menu bar items. Editing is performed using a dialog box.

4. Click the Name property and enter m_pMenuBar

To edit the menu bar:

1. In the Properties pane click the Menu Items property then click the ellipsis button.



2. wx-Devcpp displays the Menu Item Editor dialog box.



3. Click the Add Item button.

4. In the Caption box enter &File.

The & preceding the "F" defines an accelerator key that wx-Devcpp maps to the menu item. When the the user presses Alt+F the File menu is displayed.

5. In the ID Name box enter ID_MENU_FILE.

wx-Devcpp uses the ID Name and ID Value to identify menu items.

6. Click the Apply button.

7. Click the Create Submenu button.

8. In the Caption box enter E&xit\tCtrl+Q

9. The "\tCtrl+Q" defines a shortcut key combination and is displayed, right-justified, in the menu item.

10. In the ID Name box enter ID_FILE_EXIT

11. In the Hint box enter Quit this program

12. The Hint text is displayed in the status bar when the menu item is highlighted.

13. In the Events section, click the Create button next to the OnMenu drop-down list box.

14. A Confirm dialog box is displayed telling you files need to be saved first. Click Yes to save the files.

15. A New Function dialog box is displayed. In the Create New Function? box enter OnFileExit. Click Ok.

16. In the Menu Item Editor dialog click Apply.

17. Click Ok.

18. Click the Classes tab in the Project Manager pane.



The Classes tab displays the Class Browser. The Class Browser shows classes and their member functions and variables. Clicking on a member function will take you to the function implementation. If the class members are not displayed click on the "+".

Click the OnFileExit member function of TidyTextFrm.

Add this line to the function body:

Close();

In later lessons we will add additional menus using the same procedure as above. Press F9 and verify the menu works as described.

Behind the scenes, wx-Devcpp took care of several tasks for you.

-Added code to create the menu bar and items.

-Added the event handler function.

-Created an entry in TidyTextFrm's Event Table to connect the menu selection event to the event handler function.

Event Tables map events such as mouse input, menu selection and system events to a class member function. For example, when the user selects the File | Exit menu item, the Event Table maps that event to the OnFileExit member function so that function is called.

Edit Control

We will use a multi-line edit control in the frame window. The edit control provides basic text editing capabilities - cut, copy, paste and limited undo.

To add an edit control:

1. Make sure the frame window is displayed. In the Control Filter select Controls.

2. Click the Edit control then click in the frame window.



3. In the Properties pane, click the "+" next to the Edit Style property to display available styles.

4. Select the wxTE_MULTILINE style and change the value to True.

5. Select the Font property. Click the Ellipsis button. In the Font dialog select Arial 10 point.

6. Select the IDName property and enter ID_EDIT_CONTROL.

7. Select the Name property and enter m_pEditControl.

8. Select the Text property and delete the text.

This is the text initially displayed in the control and we do not want anything displayed.

Note: wx-Devcpp uses the term Edit control and I have done the same, however, if you look at the source code there is no EditControl class. The wxWidget class is actually wxTextCtrl.

Press F9 to compile and run the program. You can enter text and edit using Ctrl+X (Cut), Ctrl+C (Copy) and Ctrl+V (Paste), even though there are no menu commands yet. We will add them next.

Add menu items:

1. Open the Menu Item Editor and select Add Item.

Note: There is a bug in the Menu Item Editor. If the new item is shown as a child of the File menu ignore it. The new item is actually created at the same level as the File menu.

2. Enter the following then click Apply.

-Caption: &Edit

-ID Name: ID_MENU_EDIT

3. Click Create Submenu.

4. Enter the following.

-Caption: Cu&t\tCtrl+X

-ID Name: ID_EDIT_CUT

-Hint: Cut selection to clipboard

5. Click the Create button for the OnMenu Event.

6. Create a function named OnEditCut.

7. Click the Create button for the OnUpdateUI Event.

8. Create a function named OnUpdateUIEditCut.

The framework calls the OnUpdateUI event handler function to give your program an opportunity to enable/disable, check/uncheck, etc. an item.

9. Click Apply.

Use steps 3 - 9 as a guide to create submenu items for Copy and Paste.

We need to add code to each event handler.

-To OnEditCut add m_pEditControl->Cut();

-To OnEditCopy add m_pEditControl->Copy();

-To OnEditPaste add m_pEditControl->Paste();

-To OnUpdateUIEditCut add event.Enable(m_pEditControl->CanCut());

-To OnUpdateUIEditCopy add event.Enable(m_pEditControl->CanCopy());

-To OnUpdateUIEditPaste add event.Enable(m_pEditControl->CanPaste());

Compile and run the program. Test out the editing features.

Tool Bar

In this lesson we will add a tool bar with buttons for the Cut, Copy and Paste operations.

To add a tool bar:

1. Make sure the frame window is selected. Select Toolbar in the Control Filter.

2. Click ToolBar in the control list then click inside the frame window.



3. Change the IDName property to ID_TOOLBAR.

4. Change the Name property to m_pToolbar.

Copy the following files from C:\Dev-Cpp\wx\samples\toolbar\bitmaps to your TidyText project directory.

-cut.bmp

-copy.bmp

-paste.bmp

We will use these images for the buttons.

To add a tool bar button:

1. Click ToolButton in the control list then click inside the tool bar.

2. Select the Active Bitmap property then click the Ellipsis button.

2. Use the Picture Editor to load the cut.bmp image.

2. Change the following properties:

-IDName to ID_TB_CUT.

-IDValue to the same value assigned to ID_EDIT_CUT.

If we use the same value for the tool bar button as the corresponding menu item the framework will use the menu item event handlers. No need to add separate event table entries for the command or update.

-Label to Cut.

-ToolTip to Cut Ctrl+X

Tip: To display the Label text below the button change the wxTB_TEXT Toolbar Style to True.

Using the previous steps as a guide, add Copy and Paste buttons.



Do not worry about the buttons appearing "chopped off", when you compile and run the program they will display properly.

Compile and run the program to test the edit buttons. Also, browse through the source code files to see what code wx-Devcpp added to support the tool bar and buttons.

Clipboard

We will use two wxWidgets classes to access the clipboard, wxClipboard and wxTextDataObject. The framework provides a global instance, wxTheClipboard, of the clipboard class. We pass wxTheClipboard a wxTextDataObject object that receives the text on the clipboard or that contains text to place on the clipboard.

First, we need a submenu item and tool bar button so the user can select the command to clean the text on the clipboard. We will add the submenu item to the Edit menu. You can select your own bitmap image for the tool bar button or use this .

Modify Edit menu:

1. Open the Menu Item Editor and select the Edit menu.

2. Select Create Submenu.

3. Select Seperator in the Type drop-down list.



4. Select Apply.

5. Select Create Submenu.

6. Complete the fields as follows.

-Caption: C&lean Clipboard\tCtrl+T.

-ID Name: ID_EDIT_CLEAN_CLIPBOARD.

-Hint: Clean clipboard contents.

-Bitmaps: Click Browse and load the star bitmap.

-OnMenu handler: OnCleanClipboard.

-OnUpdateUI handler: OnUpdateUICleanClipboard

7. Click Apply then OK.

Notice we added a bitmap to the submenu item.

Add tool bar button:

1. Select Toolbar in the Control Filter.

2. Select Separator in the control list then click on the tool bar.



3. Select ToolButton in the control list then click the tool bar.

4. Load the star bitmap for the button.

5. Change the following properties:

-IDName: ID_TB_CLEAN_CLIPBOARD

-IDValue: same value as the Clean Clipboard submenu item.

-Label: Clean

-ToolTip: Clean clipboard

We need to add some source code in TidTextFrm.cpp.

#include <wx/clipbrd.h>

#include <wx/dataobj.h>

#include <wx/string.h>

Make sure you add the includes outside the block of includes generated by wx-Devcpp.

Add this line to OnUpdateUICleanClipboard:

event.Enable(wxTheClipboard->IsSupported(wxDF_TEXT));

Add these lines to OnCleanClipboard:

if (wxTheClipboard->Open())

{

    // Retrieve text from the clipboard

    wxTextDataObject textData;

    wxTheClipboard->GetData(textData);

    wxTheClipboard->Close();

   

    // Clean the text

    wxString text(textData.GetText());

    text.Replace(">", "");

   

    // Display clean text in the edit control and place it on

    // the clipboard.

    m_pEditControl->SetValue(text);

    m_pEditControl->Copy();

}

Compile and run the program. Place some text on the clipboard and clean it.

Dialog Box

In this final lesson we will build a simple dialog box that lets the user enter the characters to remove from clipboard text.

To create a new dialog box:

1. Select File | New | New wxDialog.

2. In the New wxWidgets Form dialog box select Yes to add it to the project.

3. In the Create New wxWidgets Dialog dialog box:

-Class Name: OptionsDlg

-File name: OptionsDlg

-Title: Options Dialog

-Default Style: Uncheck Min Button

4.Select Create. Note: The dialog form in the wx-Devcpp edit window shows a system menu, minimize, maximize and close button regardless of styles actually selected.

-Change the IDName property to ID_OPTIONS_DLG

Add controls to the Options Dialog box:

1. Select Controls in the Control Filter.

2. Add a StaticText control in the upper left corner.

3. Change the Label property to Remove characters:.

4. Add a Edit control below the StaticText control.

5. Change the Font property to Arial 10 point.

6. Delete the Text property value.

7. Add a Button control below the Edit control.

8. Change the &Default property to True, the IDName property to wxID_OK, the IDValue property to 5100 the Label property to OK

Note: wxID_OK is a standard identifier supplied by wxWidgets. Its value is define as 5100.

9. Add a Button control next to the OK button.

10. Change the IDName property to wxID_CANCEL, the IDValue property to 5101 and the Label property to Cancel.

When finished, the Options Dialog layout should look something like this:

We need to add a submenu item and code to display the dialog.

Add dialog support:

1. Add an Options submenu to the Edit menu and create a OnEditOptions menu event handler.

2. Enter the following code in the handler function.

OptionsDlg optionsdlg(this);

optionsdlg.WxEdit1->SetValue(m_RemoveChars);

if (optionsdlg.ShowModal() == wxID_OK)

    m_RemoveChars = optionsdlg.WxEdit1->GetValue();


3. Add a member variable, m_RemoveChars of type wxString, to the TidyTextFrm class.

4. Initialize the variable to ">".

Lastly, we need to modify the OnCleanClipboard event handler so that each character in m_RemoveChars is removed, not the string as a whole. In OnCleanClipboard, replace the line

text.Replace(">", "");

with

if (!m_RemoveChars.IsEmpty())

{

    wxString str;

    for (size_t index = 0; index < m_RemoveChars.Len(); index++)

    {

        str = m_RemoveChars[index];

        text.Replace(str.c_str(), "");

    }

}

Compile and run the program.

I hope this tutorial has been helpful in providing an introduction to wx-Devcpp and the wxWidgets framework.