Code::Blocks - User contributions [en]

WxSmith tutorial: Hello world

2015-05-20T20:43:19Z

WardXmodem: Talk of close() is obsolete; left in but separated; new method (automatic) shown

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

In wxWidgets 3.0.2 the screen looks like this. [[User:WardXmodem|WardXmodem]] 21:38, 20 May 2015 (CEST)

[[Image:1g_3.0.2.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel
with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons ([[Image:build-etc-icons.png]]) to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

==== ''The following discussion on having to add close() is no longer true, at least at Code::Blocks 13.12, wxWidgets 3.0.2. '' ====

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

==== ''End of old "have to add close()" section. With newer releases the following is done for you: ====

<pre>
void PlainFrame::OnQuit(wxCommandEvent& event)
{
Close();
}
</pre>

[[User:WardXmodem|WardXmodem]] 22:43, 20 May 2015 (CEST)
==== End of updated close() information. ====

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to [https://bugs.launchpad.net/ubuntu/+source/wxwidgets2.8/+bug/662077 Ubuntu bug 662077]. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

File:Build-etc-icons.png

2015-05-20T20:04:00Z

WardXmodem: The location of things on the screen changes from release to release, and with screen size, etc; so as a convenience to the reader I snipped the little icon block being referenced and pasted it into the text.

The location of things on the screen changes from release to release, and with screen size, etc; so as a convenience to the reader I snipped the little icon block being referenced and pasted it into the text.

WxSmith tutorial: Hello world

2015-05-20T20:02:54Z

WardXmodem: /* Overview of the Interactive Development Environment (IDE) */

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

In wxWidgets 3.0.2 the screen looks like this. [[User:WardXmodem|WardXmodem]] 21:38, 20 May 2015 (CEST)

[[Image:1g_3.0.2.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel
with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons ([[Image:build-etc-icons.png]]) to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to [https://bugs.launchpad.net/ubuntu/+source/wxwidgets2.8/+bug/662077 Ubuntu bug 662077]. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

WxSmith tutorial: Hello world

2015-05-20T20:00:46Z

WardXmodem: Correct location of icon image

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

In wxWidgets 3.0.2 the screen looks like this. [[User:WardXmodem|WardXmodem]] 21:38, 20 May 2015 (CEST)

[[Image:1g_3.0.2.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel
with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons ( [Image:build-etc-icons.png]] )to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to [https://bugs.launchpad.net/ubuntu/+source/wxwidgets2.8/+bug/662077 Ubuntu bug 662077]. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

WxSmith tutorial: Hello world

2015-05-20T19:58:47Z

WardXmodem: Add tiny icon image as the location doesn't agree with the text

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

In wxWidgets 3.0.2 the screen looks like this. [[User:WardXmodem|WardXmodem]] 21:38, 20 May 2015 (CEST)

[[Image:1g_3.0.2.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel
([Image:build-etc-icons.png]]) with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to [https://bugs.launchpad.net/ubuntu/+source/wxwidgets2.8/+bug/662077 Ubuntu bug 662077]. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

WxSmith tutorial: Hello world

2015-05-20T19:38:15Z

WardXmodem: Add image of updated 3.0.2 view corresponding to image 1g

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

In wxWidgets 3.0.2 the screen looks like this. [[User:WardXmodem|WardXmodem]] 21:38, 20 May 2015 (CEST)

[[Image:1g_3.0.2.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to [https://bugs.launchpad.net/ubuntu/+source/wxwidgets2.8/+bug/662077 Ubuntu bug 662077]. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

File:1g 3.0.2.png

2015-05-20T19:36:16Z

WardXmodem: Updated image 1g for WxWidgets 3.0.2

Updated image 1g for WxWidgets 3.0.2

WxSmith tutorial: Hello world

2013-12-14T01:32:03Z

WardXmodem: Following tutorial and correcting; e.g. you must {added DOUBLE-}click wxwidgets project

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and double-click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to Ubuntu bug 662077. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

WxSmith tutorials

2013-12-14T01:22:17Z

WardXmodem:

[[Category:wxSmith Documentation]]

Welcome to the wxSmith tutorials page! wxSmith combines with Code::Blocks, wxWidgets and a C++ compiler to give you a WYSIWYG way to create applications with a graphical user interface (GUI). The combination forms a tool for Rapid Application Development (RAD) that works on Linux, Mac OS X and Windows. As you work, you see on the screen the forms you are designing; and they look to you just like they will look to the user of your program.

The tutorials assume no prior knowledge of Code::Blocks or wxWidgets and are, in fact, good tutorials for learning them also. They do assume a basic acquaintance with C++ to recognize what you are looking at in code snippets that form part of the tutorials.

Moreover, wxSmith knows a lot about all the major wxWidgets components – buttons, check boxes, radio buttons, drop-down lists and so on. When you have selected and “dropped” one onto your form, the wxSmith property browser shows you all the component's properties and lets you modify them. It can also show all the events a component can produce and, on a quick mouse click, will set up the framework for you to code your program's response to the event.

Although wxSmith is strictly speaking a plugin to Code::Blocks, that fact is a technicality important only to writers of the program. The user, however, downloads, installs, and uses one program. As a user, it will look to you like wxSmith is just a part of Code:Blocks.

Our tutorials will start from the very basics and work up to some fairly tricky but very useful techniques.

Before you can use wxSmith, however, you need to install several libraries. If you are using Ubuntu Linux or one of its derivatives, you can install them from the Ubuntu Software Center. The libraries you need are:

libwxgtk2.8.dev (for compiling)

libwxgtk2.8.0 (the runtime library)

libwxgtk2.8.dbg (for debugging).

[If you know how to get this material from other sources, please edit this to share that knowledge.]

''OK, Installing Ubuntu Dec 2013, I found the USC used a dash before final dotted: ...2.8-dev, ...2.8-0''
[[User:WardXmodem|WardXmodem]] 02:20, 14 December 2013 (CET)

Here is a list of the tutorials. You may click on one to jump to it, but they are definitely cumulative, and you should work through them in order.

* Tutorial 1: [[wxSmith tutorial: Hello world|Hello world]]
* Tutorial 2: [[wxsmith tutorial: Working with items|Working with Menus and Components]]
* Tutorial 3: [[wxSmith tutorial: Building more complex window|Building a More Complex Window]]
* Tutorial 4: [[wxSmith tutorial: Working with multiple resources|Working with Multiple Forms]]
* Tutorial 5: [[wxSmith tutorial: Using wxPanel resources|Using wxPanel resources]]
* Tutorial 6: [[wxSmith tutorial: Accessing items in resource|Accessing Components in a Form]]
* Tutorial 7: [[wxSmith tutorial: Creating items with custom paint and mouse handling|Creating items with custom paint and mouse handling]]
* Tutorial 8: [[wxSmith tutorial: Drawing on the Screen and Saving Drawings|Drawing on the Screen and Saving Drawings]]
* Tutorial 9: [[wxSmith tutorial: Keyboard Input and Displaying Results|Keyboard Input and Displaying Results]]
* See also: [[wxSmith extensions]]

WxSmith tutorials

2013-12-14T01:20:08Z

WardXmodem: Ref to Ubuntu SW Center required slightly different syntax of the libraries (-dev etc, not .dev)

[[Category:wxSmith Documentation]]

Welcome to the wxSmith tutorials page! wxSmith combines with Code::Blocks, wxWidgets and a C++ compiler to give you a WYSIWYG way to create applications with a graphical user interface (GUI). The combination forms a tool for Rapid Application Development (RAD) that works on Linux, Mac OS X and Windows. As you work, you see on the screen the forms you are designing; and they look to you just like they will look to the user of your program.

The tutorials assume no prior knowledge of Code::Blocks or wxWidgets and are, in fact, good tutorials for learning them also. They do assume a basic acquaintance with C++ to recognize what you are looking at in code snippets that form part of the tutorials.

Moreover, wxSmith knows a lot about all the major wxWidgets components – buttons, check boxes, radio buttons, drop-down lists and so on. When you have selected and “dropped” one onto your form, the wxSmith property browser shows you all the component's properties and lets you modify them. It can also show all the events a component can produce and, on a quick mouse click, will set up the framework for you to code your program's response to the event.

Although wxSmith is strictly speaking a plugin to Code::Blocks, that fact is a technicality important only to writers of the program. The user, however, downloads, installs, and uses one program. As a user, it will look to you like wxSmith is just a part of Code:Blocks.

Our tutorials will start from the very basics and work up to some fairly tricky but very useful techniques.

Before you can use wxSmith, however, you need to install several libraries. If you are using Ubuntu Linux or one of its derivatives, you can install them from the Ubuntu Software Center. The libraries you need are:

libwxgtk2.8.dev (for compiling)

libwxgtk2.8.0 (the runtime library)

libwxgtk2.8.dbg (for debugging).

[If you know how to get this material from other sources, please edit this to share that knowledge.]
''OK, Installing Ubuntu Dec 2013, I found the USC used a dash before final dotted: ...2.8-dev, ...2.8-0'' [[User:WardXmodem|WardXmodem]] 02:20, 14 December 2013 (CET)

Here is a list of the tutorials. You may click on one to jump to it, but they are definitely cumulative, and you should work through them in order.

* Tutorial 1: [[wxSmith tutorial: Hello world|Hello world]]
* Tutorial 2: [[wxsmith tutorial: Working with items|Working with Menus and Components]]
* Tutorial 3: [[wxSmith tutorial: Building more complex window|Building a More Complex Window]]
* Tutorial 4: [[wxSmith tutorial: Working with multiple resources|Working with Multiple Forms]]
* Tutorial 5: [[wxSmith tutorial: Using wxPanel resources|Using wxPanel resources]]
* Tutorial 6: [[wxSmith tutorial: Accessing items in resource|Accessing Components in a Form]]
* Tutorial 7: [[wxSmith tutorial: Creating items with custom paint and mouse handling|Creating items with custom paint and mouse handling]]
* Tutorial 8: [[wxSmith tutorial: Drawing on the Screen and Saving Drawings|Drawing on the Screen and Saving Drawings]]
* Tutorial 9: [[wxSmith tutorial: Keyboard Input and Displaying Results|Keyboard Input and Displaying Results]]
* See also: [[wxSmith extensions]]

WxSmith tutorial: Hello world

2013-09-24T02:43:40Z

WardXmodem: Corrected use of Close() to (at least it works for me) Destory()

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>
(''I found it had to be Destroy() not Close() [[User:WardXmodem|WardXmodem]] 04:43, 24 September 2013 (CEST)'')

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to Ubuntu bug 662077. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>

Talk:WxSmith tutorial: Hello world

2013-09-24T02:13:07Z

WardXmodem: /* FIXING Close() per above */

This is a wonderful tutorial which bring me to the world of wxWidget step by step, Thanks! As a beginner myself, I really learned a lot from this page.
I think I can create some video tutorials ( use Wink or other screen cast tools) to support these topics.

== Using Close() in an OnClose() handler ==

Doing this makes the program crash when closing via close symbol.
http://forums.wxwidgets.org/viewtopic.php?t=34967&p=143167
Somebody forgot to change the tutorial or is this intentional?
----
== FIXING Close() per above ==

in the section
void plainFrame::OnClose(wxCloseEvent& event)
instead of inserting Close(); I inserted:
Destroy();
and that seemed to do it.

'''Question:''' The tutorial doesn't show the same screens or options, should I take notes on what I'm finding "now" and make appropriate corrections? They could always be backed out.

I'm hoping as I go on with the tutorial, it will explain '''why so much of the code is commented out'''
//(*.....
//*)
and '''why such things as the event table are empty''' (I assumed I had to add
EVT_CLOSE ( plainFrame::OnClose)
but in fact after the simple frame would run and close properly, I changed this to:
// EVT_CLOSE ( plainFrame::OnClose)
and it still closes properly (I did a rebuild to make sure). I'm assuming F9 DOES what it says, i.e. compiles to incorporate my changes)

--[[User:WardXmodem|WardXmodem]] 04:05, 24 September 2013 (CEST)

Talk:WxSmith tutorial: Hello world

2013-09-24T02:05:33Z

WardXmodem: /* Using Close() in an OnClose() handler */

A short overview about Code::Blocks architecture

2013-05-14T01:21:12Z

WardXmodem: Correction to 'cursiv (sic) font' => italic font. Cursive means like handwriting (connected letters)

[[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 ''italic'' 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();''

== See also ==

* [[Source hierarchy|Explanation of source hierarchy]]

FAQ-Compiling (errors)

2013-05-12T18:53:32Z

WardXmodem: Corr Typo "is will work" => it will work

[[Category:Code::Blocks Documentation]]
__TOC__
Return to '''[[FAQ]]'''.

----

==== Q: How do I troubleshoot a compiler problem? ====

'''A:''' I would start by turning on full Compiler logging.

This is done by selecting the "Full command line" option Under menu "Settings" -> "Compiler" -> Global compiler settings -> [the compiler you use] -> "Other Setting" tab, "Compiler logging". In 12.11 and newer this is enabled by default.

This option will make Code::Blocks output the exact commands it uses to compile your code.

Things to remember:

* You should review all the commands and their options;
* If you have compiled your app before, do a ''re-''build (or ''clean'' before build) to see all compiling / linking steps;
* If you don't know what an option or a command does please read the documentation for the compiler/linker you're using;
* Look for missing commands;
* For every source file (<tt>.cpp</tt>; <tt>.c</tt>; <tt>.d</tt>; etc) in your project, you must have at least one command in the log. This command must produce an object file (file extension <tt>.o</tt> if using gcc/g++ and <tt>.obj</tt> if using Visual Studio);
* Every object file should be linked in the final executable, if not there are undefined symbols errors;
* Remember the file extension matters: <tt>*.c</tt> is compiled as C file, <tt>*.cpp</tt> is compiled as C++ file. [http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html Read more]

==== Q: What do I need to know when using 3rd party libs? ====
Here are some basics about typical mistakes done when working with third party libs, including wxWidgets. The following is valid for ''every'' third party SDK / toolbox / component you want to use and describes what steps your have to do:

* Download the sources of the component OR a ready-to-use development version. The difference: While the first requires you to compile the component yourself it will definitely work with your compiler. The latter must be compiled in a compatible way: So a compatible compiler, compatible OS, compatible settings. Inspect the components docs about how to get what you want.
* Place the component sources and compiled parts anywhere you want It is not required to copy such parts to any other folder you might think - in fact, this may even be dangerous in case you overwrite existing files.
* Create a project where you want to use your component.
* In the ''compiler'' settings, point to the folder, where the include files of your component are. For WX this is special, as usually you include like #include <wx/foo.h>. So do ''not'' point to [Component_Folder]\include\wx, but to [Component_Folder]\include instead.
* Note that the compiler only needs to know the interfaces / classes / structures / methods, it will not throw an error about undefined references or alike. The compiler will only complain in case it cannot find references in terms of include files. If thats the case, adjust your project's compiler settings. Keep in mind that you do need to fulfil the requirements of your component itself, too. Thus, wxChart for example will need for wxWidgets, too. So - you may need to do the same process for wxWidgets, too before you can use wxChart - unless you have done that already.
* In the ''linker'' settings, point to the folder where you have your compiled library. A library usually ends with *.a or *.lib. Note that there are generally two types of libs: Static libs (after linking you are done) and Dynamic libs (where you link against an import lib but require another dynamic lib at runtime).
* In the linker settings add the library/libraries you need to link against in the ''right order'' to the list of libs to link against. ''Order matters'' - again, dependencies must be taken into account. Inspect the developers guide of the component to know the dependencies. On Windows, this may include the MSDN, too which tells you what libraries you need to link against for certain symbols you or the library may make use of.
* The linker will never complain about includes it cannot find. Because the linker just links object files or library files together. But the linker may complain about unresolved symbols which you need to provide. So if that happens, either your setup is missing a lib, or the order is wrong.

Again, this is valid for all third party stuff you want to use. Its heavily ''platform'' and ''compiler'' dependent. The IDE should be less of concern for you. Every IDE can be setup in a way it will compile and link your stuff unless you provide everything needed as explained above.

If you don't understand parts written here it is ''strongly'' recommended you start with a book about general programming in C/C++ that covers library handling in more detail.

For the example wxChart in the end is not easy for starters. Usually you need to compile wxWidgets before, then wxChart and usually not all dependencies are explained in the docs and it behaves differently on different OS'es / compilers. Also, wcChart can be compiled in many flavours - so you need to make sure the flavour matches a) your needs and b) the way you compiled wxWidgets.

==== Q: My simple C++ program throws up lots of errors - what is going on? ====

If you have a C++ program like this:

#include <iostream>
int main() {
std::cout << "hello world\n";
}

and when you compile it you get errors like this:

fatal error: iostream: No such file or directory

then you have probably given your source file a .c extension. If you do that, the GCC compiler (and others) will probably attempt to compile the file as a C program, not as C++. You should always give your C++ source files the extension .cpp to make sure the compiler handles them correctly.

==== Q: I imported a MSVCToolkit project/workspace, but Code::Blocks insists on trying to use GCC. What's wrong? ====

'''A:''' A little documentation problem ^^;. The "default compiler" is usually GCC, so when you imported it with "the default compiler", you told it to use GCC. To fix this situation, go to "Project", "Build Options" and select VC++ Toolkit as your compiler.

Another possibility is to put the Microsoft compiler as the default one. To do this, choose '''''Settings - Compiler''''', choose the Microsoft compiler in the '''''Selected Compiler''''' section (top of dialog box) and press the '''''Set as default''''' button.

From now onwards, for all new projects the Microsoft compiler will be taken by default.

==== Q: When compiling a wxWidgets project, I get several "variable 'vtable for xxxx' can't be auto-imported". What's wrong? ====

'''A:''' You need to add WXUSINGDLL in "Project->Build options->Compiler #defines" and rebuild your project (or create a new project and use the "Using wxWidgets DLL" project option which adds "-DWXUSINGDLL" to Project->Build options->Other options).
Other errors with the same resolution are:
'unresolved external symbol "char const * const wxEmptyString" (?wxEmptyString@@3PBDB)' or similar.
If you were using 1.0-finalbeta and were trying to build a statically linked wxWidgets project, the cause of the problem was some faulty templates. But that's fixed now.

==== Q: I can't compile a multithreaded app with VC Toolkit! Where are the libraries? ====

'''A:''' Sorry, no fix for your problem...

Your problem doesn't come from CodeBlocks. It exists, because the free VC toolkit (VCTK) doesn't provide all the libraries and tools which come with Visual C++ (VC) which isn't free, unfortunately.

Try buying a full-fledged VC++, or even better, download [http://www.mingw.org/ MinGW]

The libraries that can be obtained free of charge are:

Paths:
(VCT3) Visual C++ Toolkit 2003 - C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib
(PSDK) Platform SDK - C:\Program Files\Microsoft Platform SDK\Lib
(NSDK) .NET 1.1 SDK - C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib

C runtime libs:
LIBC.LIB Single-threaded, static link (VCT3, NSDK)
LIBCMT.LIB Multithreaded, static link (VCT3, NSDK)
MSVCRT.LIB Multithreaded, dynamic link (import library for MSVCR71.DLL) (NSDK)
LIBCD.LIB Single-threaded, static link (debug) (VCT3, NSDK)
LIBCMTD.LIB Multithreaded, static link (debug) (NSDK)
MSVCRTD.LIB Multithreaded, dynamic link (import library for MSVCR71D.DLL) (debug) (NSDK)

C++ libs:
LIBCP.LIB Single-threaded, static link (VCT3, PSDK)
LIBCPMT.LIB Multithreaded, static link (VCT3)
MSVCPRT.LIB Multithreaded, dynamic link (import library for MSVCP71.dll) (none)
LIBCPD.LIB Single-threaded, static link (debug) (VCT3)
LIBCPMTD.LIB Multithreaded, static link (debug) (none)
MSVCPRTD.LIB Multithreaded, dynamic link (import library for MSVCP71D.DLL) (debug) (none)

Try setting the library linker directories to:
C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib
C:\Program Files\Microsoft Platform SDK\Lib
C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
in that order.

The ones listed as (none) above are actually present in the IA64 and AMD64 subdirectories of the PSDK lib directory. Not sure if these would work on 32-bit windows, however, they may if they are
meant to work in 32-bit compatibility mode on the 64-bit processors. Worth a try. Otherwise, you
can link statically to the C++ library instead of using MSVCP71.dll. If you really want to link against MSVCP71.dll you can try to create MSVCP71.LIB from the dll using lib.exe and sed. Search google for "exports.sed" for detailed steps.

See also: [http://wiki.tcl.tk/2435 tclsh script to extract import .lib from (any?) DLL (MinGW)]

See also: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_c_run.2d.time_libraries.asp

See also: http://sapdb.2scale.net/moin.cgi/MS_20C_2b_2b_20Toolkit

==== Q: I get this error when compiling: Symbol "isascii" was not found in "codeblocks.dll" ====

'''A:''' Make sure you didn't mix up the MSVC headers or libs with the MinGW ones.

==== Q: My build fails with multiple ''undefined reference'' errors? ====

''Example:''
undefined reference to `WSACleanup@8
undefined reference to `WSACleanup@0

'''A:''' Most of the time it is because the required library is not linked with your project. Go to ''Project->Build options...->Linker settings (tab)'' and add the required library or libraries.

If the error includes a line number, it is likely that this is a problem with your code. Track down down your function declarations and implementations. Ensure they all match up, are spelled correctly, and have the correct scope resolution.

''VERY'' often you can get help by just googling for the name of the undefined reference, for this example its "WSACleanup". Usually one of the first links is the SDK documentation, like [http://msdn.microsoft.com/en-us/library/windows/desktop/ms741549%28v=vs.85%29.aspx this from MSDN for WSACleanup]. You'll find there a lot useful information, including what libraries you need to link against, as for the exsample:
'''Requirements'''
* Minimum supported client: Windows 2000 Professional
* Minimum supported server: Windows 2000 Server
* Header: '''Winsock2.h'''
* Library: '''Ws2_32'''.lib
* DLL: '''Ws2_32.dll'''
The header file '''Winsock2.h''' you need to include in your sources. Most likely you have done that already because otherwise you would have gotten a compiler error unable to find the function declaration. The library you need to link against, you can remove any prefix like "lib" and the file extension like ".lib", ".a" or ".so" - so just type "'''Ws2_32'''" in the linker options. Also make sure you have added the path to that library in the linker include path's options, otherwise the linker will complain that it cannot find that library you want to link against. You also know, that you should distribute '''Ws2_32.dll''' for the runtime version of you app, luckily this one usually ships with Windows anyways, so no need to do something here.

==== Q: My build fails in the compile/link/run step with a ''Permission denied'' error? ====

'''A:''' There are several possible causes for this:

# The output directory does not have read/write access.
#* Either change control settings on the output directory, or move the project to different location.
# A previous instance of the executable failed to terminate properly.
#* Open your system's equivalent of Process/Task Manager, search the list for the name of the executable Code::Blocks is trying to output, and terminate it.
#* Logging off or rebooting will achieve the same effect.
# The executable is open.
#* If the executable is open in a hex-editor or actively being run, close it.
# Security software is interfering.
#* The target file is locked while an antivirus programming is scanning it; either wait a few seconds for the antivirus scan to finish, set an exception in the antivirus settings, or (temporarily) disable the antivirus program.
#* Firewalls with very strict settings sometimes block execution; try reducing the firewall's settings or adding an exception.
#* Switching security software may have left traces behind that are interfering; hunt down the remnants of the old antivirus/firewall software and remove them.
# The file/library cannot be found.
#* Double check all of the compiler and linker [[FAQ-Compiling (general)#Q: I would like to compile a project using some non-standard libraries. How can I indicate to CodeBlocks that these libraries and include files exist?|search directories]] (including any [[Global compiler variables|variables]] they may be using) are properly setup.
# Code::Blocks was improperly installed.
#* Mixing binaries from a stable release and a nightly build (or even two different nightly builds) is highly likely to cause a slew of problems; [[Installing Code::Blocks|reinstall Code::Blocks]] in an empty directory.
# Multiple installed compilers are interfering with each other.
#* If they are not required to keep, completely remove all but the most used compiler.
#* If several compilers are required, ensure that '''none''' of them are in the ''system'' path (this is so that Code::Blocks will be able to manage all paths).
#* Also, do not place any compilers in their default installation path (for example <tt>C:\MinGW</tt>), as some compilers are hard-coded to look for headers in a default path ''before'' searching their own respective directories.
# On windows 7, the service "Application Experience" is not running [http://stackoverflow.com/questions/7655471/ld-exe-cannot-open-output-file-permission-denied#answer-7904469 as explained on stackoverflow].
See also: [/index.php/topic,15047.0.html Permission denied forums discussion]

==== Q: My build fails to link due to ''multiple definition of xyz'' errors? ====

'''A:''' GCC 4.6.1 mingw target (Windows) is known to occasionally (and erroneously) report this if link-time optimization (<tt>-flto</tt>) is used.

First, of course, check that no token has been defined multiple times. If the source code is clean, and yet the errors persist, adding linker switch (''Project->Build options...->Linker settings (tab)'')
-Wl,--allow-multiple-definition
will enable the code to link.

See also: [http://sourceware.org/bugzilla/show_bug.cgi?id=12762 Bug 12762]

==== Q: How can I change the language of the compiler (gcc) output to english? ====

'''A:''' Codeblocks 12.11 or higher: Settings->Environment->Environment Variables. Add "LC_ALL" with value "C". ->Set Now -> Ok

Since a few releases gcc is localized. This can make difficult to find (google ;) ) solutions for specific problems. With this setting the output is again in english.

!! this can break displaying of non-aschii characters so you can also use LC_ALL = en_US.utf8 (/index.php/topic,17579.msg120613.html#msg120613)

----

Return to '''[[FAQ]]'''.

WxWindowsQuickRef

2013-05-11T03:45:09Z

WardXmodem: When steps followed, newer releases add a step, seeking doc on that

[[Category:User Documentation]]
'''''A beginner's quick reference for setting up wxWidgets with Code::Blocks in Windows''''' 
Supported compilers: MinGW or MSVC

[http://shiningray.cn/windows-shang-pei-zhi-codeblocks-wxwidgets.html Chinese Translation]

'''Important Requirements:'''
* '''Recent version of Code::Blocks''' - You need to have successfully installed and run a recent version of Code::Blocks -- either [https://www.codeblocks.org/downloads/26 the 12.11 release] or [/index.php/board,20.0.html a recent nightly build].

* '''Windows compiler''' - You need to have correctly installed either
**the [http://www.mingw.org/ MinGW/GCC] free compiler (or one of its forks), or
**[http://msdn.microsoft.com/vstudio/ Microsoft Visual C++] (the [http://www.microsoft.com/visualstudio/eng/products/visual-studio-express-products Express editions] are free, but you must also install the [http://www.microsoft.com/en-us/download/details.aspx?id=8279 Platform SDK]).
When downloading an official Code::Blocks release, you have the option of downloading a bundle package that includes a full MinGW/GCC toolchain.

* '''Path properly defined''' - Ensure that the folder containing the compiler executables (typically C:\Program Files\CodeBlocks\bin, or C:\MinGW32\bin) is in your [http://vlaurie.com/computers2/Articles/environment.htm#editing Windows PATH environment variable].

== Download wxWidgets Source Code ==
wxWidgets is distributed in source code format, and you need to compile it into a library before you can use it in your own programs.

The current recommended version of wxWidgets to use is '''2.8.12'''. [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.12-Setup.exe Click here to download the wxWidgets 2.8.12 sources for Windows] (wxMSW-2.8.12-Setup.exe; 12.2 MB). You can check [http://www.wxwidgets.org/downloads/ the wxWidgets download page] to see if a newer stable version is available. '''It is highly recommended that you install the sources to a path without spaces.''' You should choose a volume with at least 300 MB of free space.

'' '''wxPack''' is no longer recommended for use, as it is built with a much older version of GCC.''

== Build wxWidgets ==
* Open up a command prompt for building. If you are using MinGW/GCC, simply use the standard Windows command shell (open the Start menu, click "Run...", enter "cmd" and hit OK). If you are using MSVC, you should use the special command shell which sets up the correct environment variables for you. If you use a version of MSVC which required you to download the Platform SDK separately, ensure that whichever command environment you use includes the Platform SDK tools and paths as well as the standard compiler tools and paths.
* Change to the wxWidgets build directory (where <wxWidgets> is the path you extracted the sources to; typically C:\wxWidgets-2.8.12):
cd /D <wxWidgets>\build\msw
''Note: the <code>/D</code> flag after <code>cd</code> may be omitted from the command; it simply allows command prompt to change drives if necessary.
* Execute the build command. The recommended command to use for '''MinGW/GCC''' is:
mingw32-make -f makefile.gcc BUILD=release SHARED=1 MONOLITHIC=1 UNICODE=1 CXXFLAGS=-fno-keep-inline-dllexport
* The recommended command to use for '''MSVC''' is:
nmake -f makefile.vc BUILD=release SHARED=1 MONOLITHIC=1 UNICODE=1
* This step will generally take a long time; faster PCs may expect 30-minute build times, and slower PCs can take as much as several hours.
* If using more recent versions of GCC, many warnings will occur during the build. This can slow the build process noticeably; you may want to redirect the warnings to a text file by appending "2>errlog.txt" to the build command, or supress them entirely by appending "2>nul".

The "CXXFLAGS=-fno-keep-inline-dllexport" option is necessary with recent versions of GCC (not with MSVC), to prevent problems with memory usage when performing the final link step on the monolithic DLL.

See the section below titled "wxWidgets build options explained" for details on the meaning of the BUILD, SHARED, MONOLITHIC, and UNICODE options. These options are critically important, because they define the basic wxWidgets development environment you will be using. You must duplicate them exactly when running Code::Blocks' wxWidgets project wizard.

== Create a wxWidgets project in Code::Blocks ==
* On the Code::Blocks Start Page, select "Create a new project"; alternatively, open the File menu, highlight "New" and select "Project..."
* Select "wxWidgets project"
# The first page is an introduction, which you can choose to skip in the future.
# Select which version of wxWidgets you will be using. If you followed the instructions above, you should select "wxWidgets 2.8.x".
# Set your project title and location.
# Enter author details if you wish (not required).
# ''At this point wiki member WardXmodem's gives a "select your GUI options" - can someone detail their meanings?''
# Select options for automatic code and file generation.
# Select wxWidgets' location. It's highly recommended that you use a global variable for this: enter "$(#wx)" (without quotes). If you haven't already defined this global variable, the global variables dialog will appear; for the base path, select your wxWidgets installation location. You don't need to fill in the other paths.
# Select debug and/or release configurations for your project. The debug configuration at least is recommended.
# Choose your wxWidgets build options. '''These must match the options used when you built wxWidgets!''' If you followed the directions above, select all three of the options under "wxWidgets Library Settings". The other settings on this page are not related to the wxWidgets build options; you may use them or not as you prefer. In order to avoid using a debug wxWidgets build (as recommended), you must select "Configure Advanced options" and then leave "Use __WXDEBUG__ and Debug wxWidgets lib" unchecked on the next page.
# Select additional libraries if required. You should not need to select any of these for normal usage.

== Build and Run ==
Select "Build and run" (F9) to, well, build and run. If all goes well, your wxWidgets basic program should appear.

== wxWidgets Build Options Explained ==
''What do the BUILD, SHARED, MONOLITHIC, and UNICODE options mean?''

=== BUILD ===
BUILD controls whether a debug version (BUILD=debug) or release version (BUILD=release) of wxWidgets itself is built. In the vast majority of cases you will only need a release version of wxWidgets, since you won't be interesting in debugging wxWidgets itself. You can still create debug builds of your own programs that link to a release build of wxWidgets.
* A '''debug''' build of wxWidgets creates libraries with a "d" suffix -- for example, "libwxmsw28d.a"/"wxmsw28d_gcc_custom.dll".
* A '''debug''' build of wxWidgets creates the folder "mswd" or "mswud" in the wxWidgets library output folder.
* A '''release''' build of wxWidgets creates libraries ''without'' the "d" suffix -- for example, "libwxmsw28.a"/"wxmsw28_gcc_custom.dll".
* A '''release''' build of wxWidgets creates the folder "msw" or "mswu" in the wxWidgets library output folder.

=== SHARED ===
SHARED controls whether a DLL (SHARED=1) or static (SHARED=0) version of wxWidgets is built. With a DLL build, compile times are faster and the executable size is smaller. The total size of a single executable plus the wxWidgets DLL is greater, but multiple executables can use the same DLL.
* A '''DLL''' build of wxWidgets creates import libraries (such as libwxmsw28.a) and DLLs (such as wxmsw28_gcc_custom.dll). You must include the DLL when you distribute your program.
* A '''static''' build of wxWidgets creates static libraries only (such as libwxmsw28.a), and you do not need to distribute a wxWidgets DLL.

=== MONOLITHIC ===
MONOLITHIC controls whether a single library (MONOLITHIC=1) or multiple component libraries (MONOLITHIC=0) are built. With a monolithic build, project setup and development are much easier, and you only have one DLL to distribute if you're using a DLL build. With a non-monolithic (multilib) build, several different libraries are built and you can avoid linking with the entire wxWidgets codebase for programs that don't need it. You do have to ensure that you choose the correct component libraries.
* A '''monolithic''' build of wxWidgets creates a single wxWidgets import library (such as libwxmsw28.a) and a single DLL (such as wxmsw28_gcc_custom.dll).
* A '''multilib''' build of wxWidgets creates multiple import libraries (libwx28_base.a, etc.) and multiple DLLs.
* Additional '''static''' libraries are always created with any wxWidgets build (libwxexpat.a, libwxjpeg.a, etc.). These libraries do not normally need to be used with DLL builds of wxWidgets, but they are required when using static builds.

=== UNICODE ===
UNICODE controls whether wxWidgets and your program use wide-character strings with Unicode support. Most programs for Windows 2000 and later should do so. Earlier versions of Windows don't have the necessary Unicode support. You should always use wxWidget's _("string") and _T("string") macros to ensure that your hardcoded strings are the correct type.
* A '''Unicode''' (UNICODE=1) build of wxWidgets creates libraries with a "u" suffix -- for example, "libwxmsw28u.a"/"wxmsw28u_gcc_custom.dll".
* A '''Unicode''' build of wxWidgets creates the folder "mswu" or "mswud" in the wxWidgets library output folder.
* An '''ANSI''' (UNICODE=0) build of wxWidgets creates libraries ''without'' the "u" suffix -- for example, "libwxmsw28.a"/"wxmsw28_gcc_custom.dll".
* An '''ANSI''' build of wxWidgets creates the folder "msw" or "mswd" in the wxWidgets library output folder.

== Frequently Asked Questions ==

'''I get errors like "wx/setup.h: No such file or directory"'''

You're missing an important compiler search path in your build options. Make sure you choose the correct wxWidgets build configuration when running the wxWidgets project wizard. If re-running the wizard isn't an option, then open your project's build options and add "$(#wx.lib)\gcc_dll\mswu" (assuming a monolithic Unicode DLL build) to the compiler search paths.

'''I get errors like "cannot find -lwxmsw28u"'''

You have an incorrect link library in your build options. Make sure you choose the correct wxWidgets build configuration when running the wxWidgets project wizard. If re-running the wizard isn't an option, determine which version of the library is built and adjust the library name in your build options accordingly.

'''I get errors like "undefined reference to _Unwind_*"'''

wxWidgets was built with a different version of GCC than the one you're currently using. You need to rebuild wxWidgets with the same version of GCC that you use to compile your program.

==See also==
Forum thread - [/index.php?topic=5359.0 Newbie problem in setting up wxwidgets and Codeblocks]

WxSmith tutorial: Hello world

2013-05-07T18:04:30Z

WardXmodem: VERY minor - ]]or changed to ]]<space>or to avoid word run-together

[[Category:wxSmith Documentation]]
= Tutorial 1. "Hello, World!" =

In this first tutorial, we will use wxSmith to put the words "Hello, World!" on the screen. Ever since the appearance of ''The C Programming Language'' in 1978, writing such a program has been the traditional first step in learning nearly every computer language.

Before we start, you must either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages mentioned here:
* Windows users should see the wiki page:[[Compiling wxWidgets 2.8.6 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]] or [[WxWindowsQuickRef]]. There are two ways to install the wxWidgets libraries, You can download the wxWidgets source and compile it yourself, or you can download the wxPack from [http://wxpack.sourceforge.net/] and install it. The wxPack contains a pre-compiled wxWidgets library, so you can save a lot of time by that route.

*Ubuntu Linux users can install wxWidgets from the Ubuntu repositories. Be sure to install also '''build-essential''' to get the C++ compiler.

We will assume that you have wxWidgets ready and working with Code::Blocks. You should probably create a directory with a name something like CBProjects for saving your work on these tutorials. Each tutorial will be a separate "project" and will occupy a file in this directory.

After downloading and installing Code::Blocks, double-click its icon on the desktop to start it. Here is the Code::Blocks opening window:

[[Image:1a.png]]

Click "Create a New Project" and then find and click the wxWidgets Project icon, pointed to by the cursor in the screenshot below.

[[Image:wxs_tut01_002.png]]

The next screen is a "Welcome" screen. Unless you just enjoy being welcomed by the program, you will check the box which eliminates it on future startups.

The next screen looks like this:

[[Image:wxs_tut01_003.png]]

Select wxWidgets 2.8x and click the "Next >" button at the bottom of the screen.

That brings you to the window where you specify the Project title and folder where you want to save the project. Other fields are then filled automatically. I chose “Plain” as the Project title and the other fields then adjusted to look like this:

[[Image:1c.png]]

Then click the “Next >” button at the bottom.
The next screen, shown below, allows you to mark your work with your identity. Fill in what you wish.

[[Image:1d.png]]

That brings up the window for choosing the GUI builder you want to use, wxSmith or FormBuilder. We choose, of course, wxSmith.

[[Image:1e.png]]

Click the "Next" button at the bottom.

The next screen specifies what C++ compiler we want to use and whether we want a debug build (with extra code for debugging) or a smaller release build for use by others. We will go for the GNU CPP compiler and both build options, to be put in separate subfolders.

[[Image:1f.png]]

The final screen of this sort asks whether we want to use the standard, default, configuration or to use Advanced options. We will take the default. But, at the bottom, we choose to “Create and use precompiled headers" which speeds up compilations after the first.

[[Image:1g.png]]

On the form where we chose the directory for saving the project, we chose a real directory, but that choice may lead to problems when you want to compile your project on other computers. Another choice is to use the '''Global Variable system'''. To open the dialog below or modify or change this global variable, you should click on the Code::Blocks main menu item '''Settings | Global variables'''. That brings up the Global Variables Editor.

When you use it, the location of the wxWidgets library is read from the variable you supply. This means that the location of the wxWidgets directory is not hard-coded inside your project, but is stored inside the global configuration of Code::Blocks. When your project is opened on a different computer, it will use that comoputer's configuration. The easiest option to use this global variable is to leave ''$(#wx)'' which means to use the global variable named ''wx''. This name is reserved for wxWidgets and should be chosen in most cases.

When you use the global variable for the first time, it will ask for the wxWidgets directory. The only thing you need to do here is to enter a valid location in ''base'' field. This is required only for the first time since Code::Blocks will automatically use this setting for other projects you create.

==Overview of the Interactive Development Environment (IDE)==

At the end of this preliminary sequence of forms we come to the Code::Blocks main IDE window. It should look something like this:

[[Image:1h.png]]

In the middle of the right side of the window, under the word “Plainframe.wxs”, is a panel with two square icons on the left; the one on the left brings up the menu bar editor while the one on the right brings up the status bar editor. We will return to the menu bar editor in the next tutorial. Below this panel and looking like a field of dots is the Editor window, where we will see both the GUI forms which we build and the C++ code we write. In the lower left corner of the whole window is the Properties/Events window, which will allow us to set properties of the component we are working on or to pick events, such as “OnClick” , to which we need to respond. To show properties, click on the left icon; to show events, click on the right icon marked {} to suggest C++ code.

Above the Properties/Events window is the Management window with three tabs, Projects, Symbols, and Resources. If all three tabs are not visible, drag the right border of the window to the right to reveal all three. (A “resource” in wxSmith parlance usually means a “form” or "window".) Above the Management window is a panel with several small but useful icons to
*Build the program, or
*Run it, or
*Build and run it, or
*Rebuild it, or
*Abort it. 
When you run the cursor over them, the tool tips will tell you which is which.

Now look back to the Editor window. First of all, note that the window can be configured to use different colors,fonts and font sizes. Click "Settings ..." on the Code::Blocks main menu, and then "Editor". The screens are more or less self-explanatory.

Now back to the Editor window. Across the top you see three black square called drag handles. They have been set to cover a space larger than can be seen, but scrolling down reveals the whole field.

As an experienced programmer, you know there has got to be some code somewhere but you don't see it. To reveal it, double left click in the field of dots. Presto, there is the C++ code, and the *PlainMain.cpp tab has appeared above it. Clicking back on the Plainframe.wxs should return you to the view of the form, still the field of dots. (Again, it is important to have CB 10.04 or later.) In fact, we still have not seen all of the code. In particular, you will search in vain for the all-important OnInit() routine that starts the program. You can find it, however, by clicking Search | Find in Files and searching for OnInit with the scope of the search set to be “Project files”. The search finds it, sure enough, in PlainApp.cpp and opens this module in the Editor window.

We don't need OnInit right now, but we do need to make a change in PlainMain.cpp. Click on it in the bar above the editor, and its code appears in the editor.

Sometimes a program has a lot to do when the user clicks the close icon in the program's title bar, so wxSmith generates a frame for writing the code for those actions but it provides no code. Consequently, if we ran our program just as initially written by wxSmith, we won't be able to close it by just clicking that icon. To fix that inconvenient problem, find the spot in the code with these lines:

<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
}
</pre>

Add the call to the Close() function so that the spot looks like this:
<pre>
void PlainFrame::OnClose(wxCloseEvent& event)
{
Close();
}
</pre>

Remember to make this change immediately whenever you start a new project.

You can now build and run this super-simple program. To do so, you can do any one of three equivalent things: 
* in the top menu bar, click Build | Build and run.
* find and click the icon that looks like a right-pointing triangle in front of a cogwheel. Hovering the mouse pointer over it will show the tool tip “Build and run”.
* tap the F9 key.

If all goes well, you will see a window come up with a menu of two items: “File” and “Help”. Try the “Help” menu item first. Then you can use “File | Quit” or the exit icon on the title bar to exit the program.

''If you are using Ubuntu and get no main menu bar when you run this program, you have fallen victim to Ubuntu bug 662077. Beginning with release 10.10, Ubuntu releases have had a bug causing programs built with wxSmith to fail to show their main menu bar. If this bug affects you, you may want to uninstall appmenu-gtk. You do that by clicking Applications | Software Sources, then using the search window to find appmenu-gtk. Clicking on it will allow you to choose to remove it.''

Well, so far we have a program that runs and quits, but it does not yet display "Hello, World!". That's next.

== Hello, World! ==

We now turn to the classic first program, namely getting the words “Hello, World!” onto the screen. The text could be added directly into the frame, as in GUI designers for a single operating sytem; but we need to learn to use sizers for cross-platform programming. What are sizers?

If you have been working with Java or Qt, you may remember something called Layout managers. The implementation in wxWidgets differs a little but does almost the same thing.

When adding components into windows you must somehow specify their position and size. wxWidgets tries to automate this process, and it uses sizers to do so. They automatically position and size window components, and they can also set the size of the window so that everything fits inside.

Sizers have one big advantage over direct placement of components. When you write cross-platform applications, you cannot assume that fonts, buttons, and so on have the same size on different operating systems. This problem can even occur on the same platform when using different window themes. When you use sizers, you don't have to worry about those problems. All sizing and placement is done automatically. Moreover, sizers can even reposition and resize window components when the main window changes size.

With that background, let's get started. When you look at the wxSmith editor, you'll notice that the area of the window is surrounded by eight black boxes or drag handles.

[[Image:wxs_tut01_009.png]]

These drag handles surround the currently selected item. In our case it's a whole window. Adding new components to the window is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking somewhere on the resource. As you can see here,

[[Image:wxs_tut01_010.png]]

when you keep your mouse cursor over a component in the palette, it will show its name. That feature may help you find components until you become familiar with their icons.

Let's add a new wxPanel component to our window; it is the fourth icon from the left on the standard tab. You will see that when you click the wxPanel item and then move the cursor over the editor, some part of the editor will change color. That's intentional and is used to show where on the window the new item will be added.

After the wxPanel is in place, you will notice that the background color of the window has changed to light gray. Now our window will look much more like other windows. Note that currently the selection changed to the added panel but since its size is equal to the frame's, it's hard to find out what's really selected. To make sure that wxPanel is selected, click somewhere on the light gray area of our window (Note to Linux users: wxFrame and wxPanel usually have the same background so it may look like nothing has changed; you may ensure that there's a wxPanel by looking into the resource browser).

If you want to see the selection exactly or select items that overlap, you can use the resource browser. To show it, click on the resources tab located in the same place where the project browser is:

[[Image:wxs_tut01_011.png]]

The resource tab consists of two parts. The first is the resource tree which shows the structure of your resources and the second one is the property browser which is common in GUI designers. Inside the resource tree you can find the currently selected item. In our case it is the wxPanel class we added before. The selected item also shows the name of this item: Panel1. This name is basically the variable which can be used to access this component in your code.

We added a new component by selecting the place for it. This is wxSmith's default behavior. However, there is another mode of adding items. In this mode, the new item is added right after you click on the palette's button. The position of the new item is relative to the current selection - just like a cursor in text editors. Basically we can add new items into three different positions relative to the selection:
* Before the selected widget
* After the selected widget
* Into the selected widget.
This insertion mode can be changed by clicking one of the four "placement" buttons on the right side of the editor:

[[Image:wxs_tut01_012.png]]

The uppermost is the mode we used - "point by mouse". The next one means "add into", followed by "add before", and the last one means "add after". The current mode is shown by a red check mark on the button.

Sometimes a few selection modes are disabled because they are not valid for the currently selected item. For example, you cannot add any component into the wxButton component since wxWidgets declares it as one that cannot have child components. Similarly, when the main component (the window) is selected, you won't be able to add anything after it or before it.

Ooops! I said we would use sizers and then forgot all about them! We have to get rid of that wxPanel. Select the panel and then click on the red X button just below the four buttons we have been describing. It looks like this:

[[Image:wxs_tut01_014.png]]

When you click this button, it deletes the current selection, so if the panel didn't disappear, make sure it's selected and click the button again. Now we should have returned to the state at the beginning.

To use sizers, first we have to add a sizer into the main frame and then add the wxPanel into it.
Sizers are available in the Layout tab on the palette. Switch to it and select wxBoxSizer:

[[Image:wxs_tut01_013.png]]

This sizer tries to position items in one line, either horizontal or vertical. Horizontal is the default, and we will use it.

After adding the sizer, two things have changed. The first is that our window now has a red border. This means that there is a sizer attached to it. When you look into the resource browser, you will also see that the sizer has been added. (You may need to click on the editor area to refresh the selection on the resource browser.) The second change is that the size of the window has shrunk to a small box. That is as it should be because the sizer is responsible for resizing the window to be no bigger than necessary to be visible and accommodate its components, and so far there are no components.

Now let's add our wxPanel. Make sure that you add it into the sizer, not into the main frame. After you do so, you will see something like this:

[[Image:wxs_tut01_015.png]]

Here we can see our panel surrounded by drag boxes. There's also some dark gray border around it (it won't be visible on Linux). Each component added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between components. But in our case we should get rid of it to get a better looking window. To do so, we will have to change a property inside the property browser. Search for border size and change it from 5 to 0:

[[Image:wxs_tut01_016.png]]

Now when we have our panel adjusted, we can finally add the "Hello world" text. Since we will also use sizers to manage items added into wxPanel, we have to repeat the addition of wxBoxSizer into wxPanel. After the sizer is in its place, switch back into the '''Standard''' tab on the palette and add a wxStaticText control:

[[Image:wxs_tut01_017.png]]

With an eye to the future and for practice with adding components, let's add also a button next to the wxStaticText. First, click on wxButton. If you still have the "point by mouse" insertion mode turned on, then when you put the mouse over the wxStaticText component half of that component will be colored in light blue. When the left half of the text is highlighted, the new item will be added before the existing component; and when the right half is highlighted, the new component will be added after the existing one. Let's add the button after the text. Now we should have this content:

[[Image:wxs_tut01_018.png]]

Now let's finally set our "Hello, World!" text. The wxStaticText control which we added before has the text "Label" on it. It is the default text set to all newly created wxStaticText classes. We will change it using the property browser similarly to changing the border size in the wxPanel class. To do so, select the wxStaticText component in our window, then find the Label property in the property browser and change it to "Hello, World!":

[[Image:Wxs_tut01_019.png]]

If you want two or more lines of text on the wxStaticText control. click on the "..." button at the right end of the “Label” line or put "\n" inside the text, as in C formats.

At this point, you can click the "Build and run" and the program should run and show the magic words in the static text control. We could quit in triumph at this point, but the button we have put on the form is still a dud; clicking on it will do nothing. Let's give it a function.

Before going further, we need to deal with a question you may be asking. Why did we, after putting a box sizer onto our main window, proceed to put a wxPanel into it and then put another box sizer onto the panel? What is the point of the panel? Why not just put our two buttons into the first box sizer and eliminate the panel and second box sizer? The answer is that the panel gives us control of the background. We didn't use it, but it is often useful to be able to control it. In fact, these first three steps will be used in structuring every window used in these tutorials. To review, these three steps are:
* Put a box sizer on the window
* Put a panel into the first box of the sizer
* Put a sizer of some sort onto the panel.

== Responding to the Click of a Button ==

Since buttons usually cause something to happen when clicked, let's make our button close the window. The first thing we should do is to change the text shown on the button to tell the user what the button does. It is done just as in the case of the wxStaticText widget. Select the button, find "Label" in the property browser and set it to "Close" (or anything you like).

The second thing is to assign an event handler to this button. Basically, event handlers are functions which are called when some "event" occurs. In our case instead of "event" we could say more descriptively " a click on the button" because that is what we want to process. Like other GUI designers, wxSmith can automatically generate the framework code for such handlers. To bring up that ability, switch the property browser to the event browser by clicking on the second icon at the top of the property browser. The icon looks like {} to suggest C++ code.

[[Image:1Event_Icon.png]]

After you click on this icon, you will see all events supported by the currently selected component. The wxButton class supports only one event, the EVT_BUTTON event, so only this one is shown. When you click on this event and drop down the combo box, you will see the available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

If you select '''-- None --''' no handler function will be automatically assigned to this event. (But it may always be set manually.) Selecting '''-- Add new handler --''' will generate a frame for the code of the new handler function. Below are shown other event handlers known to wxSmith which can be assigned to this event. We can see here OnQuit and OnAbout. Those handlers were created by wizard. We could use the OnQuit handler, but to see what happens, let's write our own handler. Select the '''Add new handler''' option. You will be asked for a name for the handler. This name is simply the name of the function which will be called as a reaction to this event. wxSmith will suggest the name OnButton1Click, and we may as well use it.

When you enter a new handler name, wxSmith will generate the framing code of a new handler function by that name, open the program file with the proper source code and put the cursor inside the handler function. (You may need to scroll up or down to show the line with cursor.) This function is a member of the class we have been building, so it can access all of functions in that class, including the one called '''Close()''', which was created by the wizard. So when we want to close our window we just call the '''Close()''' function. The result looks like this:

[[Image:Wxs_tut01_022.png]]

Build and run our project. It should show our "Hello, World!" text and our "Close" button. Click the Close button, and it should close.

This is end of this first tutorial, I hope that you followed it easily and are beginning to feel comfortable with Code::Blocks and wxSmith.

The tutorial was originally written by BYO, the creator of wxSmith. It was revised in March 2012 by Grouch to take account of changes in Code::Blocks, add a few clarifications, and change the accent in the English from youthful Polish to elderly American.

----

<center>'''[[WxSmith tutorials|Index]] | [[Wxsmith tutorial: Working with items|Next]]'''</center>