Code::Blocks - User contributions [en]

WxSmith tutorial: Hello world

2012-05-30T09:14:43Z

Greenbreen: Fixed some typos

[[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 it 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]]

On the main menu, Click File | 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 wante 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 speed 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 onto which 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>

Code::Blocks and Cross Compilers

2012-05-29T12:56:14Z

Greenbreen: /* Setup Code::Blocks to use the Cross Compiler */ Removed 2nd hyphen from i586-mingw32-msvc

[[Category:User Documentation]]

This Document will describe how to setup Code::Blocks to use it with a cross compiler. The idea is to create a easy way to develop software under a platform such as Linux, and create an executable for another platform e.g. Windows without booting to the native Operating System.

=Compiling Windows binaries on Linux=
This will describe how to setup your Linux box to compile your code for the Windows platform using
[http://www.mingw.org/ MinGW] (Minimalist GNU for Windows). Depending on your distribution, the installation of the needed packages can differ.

==Installing MinGW ==
===Ubuntu 6.06===

Install the [http://www.mingw.org/ mingw] package from the [https://help.ubuntu.com/community/Repositories/Ubuntu Universe Repository], using synaptics or with the following command:

sudo apt-get install mingw32

==Setup Code::Blocks to use the Cross Compiler==
To let Code::Blocks know about your cross compiler you have to create a new compiler profile. Go to Settings->Compiler and Debugger Settings and create a copy of the current selected compiler. Type in a Name for the new profile e.g. cross_linux and hit enter.

[[Image:Settings compiler debugger name.png]]

Now you will have to change some directories for the new cross compiler. You will need to setup the directories for Compiler, Linker, and Resource Compiler. For every entry you have to put: /usr/i586-mingw32msvc. The pictures below show how it should look like.

[[Image:Settings_compiler_debugger_compiler.png]]

[[Image:Settings_compiler_debugger_directories.png]]

[[Image:Settings_compiler_debugger_Resource_compiler.png]]

The last step is to tell Code::Blocks where and what your cross compiler binaries are. Just select the directory where you have copied all the compilers binaries ( /usr/i586-mingw32msvc/ ) and setup the executables as shown in the picture below.
[[Image:Settings_compiler_debugger_programms.png]]

Now you can start a new project or open an existing project, and if you want to make a cross compilation for Windows platforms, just go to Project->Build Options and select your cross compiler. Remember that you will have to rebuild the whole project. You can test your build with [http://www.winehq.org/ Wine].

==Tips from the forum==
The following has been copied from a forum article originally posted by visualphoenix:

Today I managed to finish figuring out how to set up the build options for cross compiling, debugging and running windows executables for projects built with Code::Blocks using linux... As such, I decided it was time to sign up for the c::b forums and post a howto in case anyone else was interested in knowing what I did...

The following is how I did this on Ubuntu 'Dapper Drake' Linux:

'''Step 1:'''
Install MingW32 for linux
# sudo apt-get install mingw32

'''Step 2:'''
Settings->Compiler and debugger settings
Select GNU GCC Compiler and click the Copy button.
Name this: MingW32 Compiler

'''Step 3:'''
Click the Compiler tab and then click the #defines tab and add the following:
WINVER=0x0400
__WIN95__
__GNUWIN32__
STRICT
HAVE_W32API_H
__WXMSW__
__WINDOWS__

Click the Linker tab and the following under "Other Linker Options":
-lstdc++
-lgcc
-lodbc32
-lwsock32
-lwinspool
-lwinmm
-lshell32
-lcomctl32
-lctl3d32
-lodbc32
-ladvapi32
-lodbc32
-lwsock32
-lopengl32
-lglu32
-lole32
-loleaut32
-luuid

'''Note:''' Not all of these are REQUIRED... As I have been recently messing with compiling apps for windows with OGL and DX9 support I have realized that there are some additions I have needed to add here... I will update accordingly when I know more.

'''Step 4:'''
Click the Directories tab and the Compiler tab.
Modify the path to read the following (where ix86 is your architecture type):
/usr/i586-mingw32msvc/include

Click the Directories tab and the Linker tab:
Modify the path to read the following (where ix86 is your architecture type):
/usr/i586-mingw32msvc/lib

Click the Directories tab and the Resource Compiler tab:
Modify the path to read the following (where ix86 is your architecture type):
/usr/i586-mingw32msvc/include

'''Step 5:'''
Click the Programs tab:
C compiler: i586-mingw32msvc-gcc
C++ compiler: i586-mingw32msvc-g++
Linker for dynamic libs: i586-mingw32msvc-g++
Linker for static libs: i586-mingw32msvc-ar
Debugger: i586-mingw32msvc-gdb **** MORE ON THIS LATER ****
Click OK and save your changes.

'''Step 6:'''
Ubuntu's mingw32 package and from what I can tell, MingW32 in general doesn't really have a solid gdb option for debugging natively in Linux so we're going to work around this using wine and mingw32's latest insight build for windows

Install Wine
# sudo apt-get install wine

'''Step 7:'''
Download Insight from the
[http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=82725&release_id=371590 Insight homepage].

'''Step 8:'''
Once you download insight.exe, extract the archive using wine:
wine insight.exe

I extracted this to my desktop

'''Step 9:'''
Move the insight folder to /opt. the path should now look like
/opt/insight/bin/gdb.exe

'''Step 10:'''
create a shell script in /usr/bin:
('''Note:''' shell scripts should start with a hash (#) bang (!), ie: "# ! / bin / sh " [with no spaces] but when I add that the forum post tanks)
# sudo gedit /usr/bin/i586-mingw32msvc-gdb
and add the following:
wine /opt/insight/bin/gdb.exe "$@"
Save the file and quit gedit

'''Step 11:'''
# sudo chmod +x /usr/bin/i586-mingw32msvc-gdb

Now we have a way to execute the windows version of mingw32's gdb for windows in linux using our shell script wrapper

'''Step 12:'''
Create a new console application project in Code::Blocks. Using the wizard select the MingW32 Compiler option.

'''Step 13:'''
Right click the project and go to properties. Click the Targets tab and set the Output Filename to be whatever you want with a .exe file extension. Make sure the type is a Console Application.

'''Step 14:'''
When I reached this step, compiled and tried to run my application I realized that for some reason Code::Blocks was trying to execute my .exe through /usr/bin/wine-auto (which I do not have)... So I created a simlink to wine:
# sudo ln -s /usr/bin/wine /usr/bin/wine-auto

'''Step 15:'''
Hit F9 in Code::Blocks and the hello world application runs!! YAY!
Set a breakpoint on line 5 and hit F8 and the application breaks in the debugger!! Woot!
Now you can successfully compile, execute, and debug windows applications in Linux using Code::Blocks!!!

Wxsmith tutorial: Working with items

2010-12-26T18:08:29Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing the item will also change properties in the browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Usually when you must specify size (or other size-related thing) you provide a value in pixels. Alternatively you can specify values in a unit called a '''Dialog Unit'''. A '''Dialog Unit'' is usually a little bit bigger than one pixel and it's size depends of the size of the current font (actually it's the size of the font of some item's parent which does have a font). This is useful when you want some values to be proportional to the size of text presented in the window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful ones. It works similarly to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all columns resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide a list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing a list of numbers separated using comma (,). Numbers should start from 0, so if you would like the second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is a specialized sizer with one purpose - to provide a set of standard buttons with respect to the platform's look and feel. This sizer has a predefined list of components which it can handle - all are buttons and you can manage them using the sizer's properties. You cannot add your custom items into this sizer.

Each button on this sizer has two properties in the sizer - whether the button should be enabled (for example wxID_OK for OK button) and its label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have a label). It's also very probable that labels will be provided with language-specific strings (depending on the current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's an example of the sizer (note that labels are in Polish and they mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on a linux box. You may see that the buttons have an extra image which is not available for standard buttons. With such a layout, users of the application will feel more comfortable, and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have the same buttons but without images and they would be in a different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" palette page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizers when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with a dividing line (it's called a sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static text, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll briefly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, a very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It doesn't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's the user enter some text. It's basic functionality allows entering one-line text. After changing its properties it may become a more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be a separate resource, it can also be added as another resource's component. This item may be used as background for other components. It has a few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has a few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set the size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides a drop-down list with available options. It works similar to wxComboBox but you cannot enter your own value. It can be used in situations when the user should use one of several available options. An event is generated when the user changes the selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides a drop-down list similarly to wxChoice. In the case of this item, the user can select one of the available values or enter his own if the item is not in a Read-Only state. A very good example of its usage is to provide some text entry with a stored list of previously entered values (like in search boxes). Like wxChoice, changing the selection generates an event. Additionally, changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides a list where you can select one or more items. Changing the item or double-clicking on it generates an event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in the form of tabs. Additionally, wxChoicebook and wxCombobook are also available but are not described here. Changing the selected notebook generates two events: one when the page starts to change (before change) and one when the page is finished changing (after change).

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check boxes may be used to map boolean values. Additionally, 2-state boxes can also be generated (with values: yes/no/unspecified). Changing the value emits an event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works similarly to check boxes. The difference is that only one radiobox in a group can be selected. Groups may be defined by using wxRB_GROUP style - a radiobox which has this style set starts a new group. Changing the selected radiobox emits an event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item, also named Progress Bar, can be used to show the progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only a window which seems hung).

That's the end of this tutorial. I presented some basic information about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also a very useful technique absolutely required for more complex resources.

WxWindowsQuickRef

2010-12-21T05:21:54Z

Greenbreen: Added link to forum thread that helped me resolve errors

[[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 10.05 release] or [/index.php/board,20.0.html a recent nightly build].


* '''Windows compiler''' - You need to have correctly installed one of three options
**[http://www.mingw.org/ MinGW/GCC] free compiler, gcc-core, gcc-g++, binutils, w32api, and mingw32-make packages are required, or
**[http://msdn.microsoft.com/vstudio/ Microsoft's compilers] (the [http://msdn.microsoft.com/vstudio/express/ Express editions] are free, but you must also install the [http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb Platform SDK]), or
**[https://www.codeblocks.org/downloads/5#windows latest stable release of Code::Blocks] includes a MinGW-bundled compiler which includes all necessary packages

* '''Path properly defined.'''
** Ensure that the folder containing the compiler executables (typically C:\Program Files\CodeBlocks\bin) is in your [http://vlaurie.com/computers2/Articles/environment.htm#editing Windows PATH environment variable]. The path environment variable is changed by
***right-clicking on 'my computer',
***selecting properties,
***click the advanced tab,
***click the 'Environment Variables' button at the bottom.

To verify the path is set correctly, open a DOS prompt and enter the command: mingw32-gcc, a reply of 'Not recognized' indicates a problem. 'no input files' means that the program was found and that the path environment variable is correct. For example...

Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
C:\>mingw32-gcc
mingw32-gcc: no input files
C:\>

== Download wxWidgets ==
You can choose to download the wxWidgets source code and compile it yourself, or download the "wxPack", a precompiled version.
* '''The wxWidgets sources''' are a much smaller download, but you must also spend some time compiling them.
* '''wxPack''' is a much larger download, but you don't have to spend time compiling it or worry about build options.

=== wxWidgets Sources ===
The current recommended version of wxWidgets to use is '''2.8.10'''. [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.10-Setup.exe Click here to download the wxWidgets 2.8.10 sources for Windows] (wxMSW-2.8.10-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 ===
wxPack makes the next step of building wxWidgets unnecessary. The current stable release of wxPack is '''v2.8.8.04''', based on wxWidgets 2.8.8. [http://downloads.sourceforge.net/wxpack/wxPack_v2.8.8.04.exe?download Click here to download wxPack v2.8.8.04] (wxPack_v2.8.8.04.exe, 315.9 MB). You can check [http://wxpack.sourceforge.net/Main/Downloads the wxPack download page] to see if a newer stable version is available. '''It is highly recommended that you install wxPack in a path without spaces.''' You should choose a volume with at least 700 MB of free space for MSVC, or 2.2 GB of free space for MinGW/GCC.

== Build wxWidgets ==
''This step is unnecessary if you are using '''wxPack''' ''

* 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.9):
cd <wxWidgets>\build\msw
* 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
* 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".

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).
# 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". '''If you are using wxPack:''' wxPack includes each version, so you may select whichever options you prefer. 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.

==External Links==
[/index.php?topic=5359.0 Newbie problem in setting up wxwidgets and Codeblocks]

WxSmith tutorial: Hello world

2010-12-12T18:12:51Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]
= "Hello world" Tutorial =

Hi, in this tutorial we will write a very basic application that will use wxSmith(which is a smart tool for GUI design), called "Hello world". "Hello World" is the traditional first program for many computer languages so in keeping with this time honored tradition, it should be your first step in learning wxSmith.

Before we start you will have to either compile wxWidgets or download precompiled binaries and header files. These steps are described on the wiki pages below:

* windows user see the wiki page:[[Compiling wxWidgets 2.6.2 to develop Code::Blocks (MSW)]] or [[Installing Code::Blocks from source on Windows]]or [[WxWindowsQuickRef]]. There are two method to install the wxWidgets libraries, one is you can download the wxWidgets source and compile your self. The other is you can download the wxPack from [http://wxpack.sourceforge.net/], then install it, the wxPack will give a pre-compiled wxWidgets library, so you can save a lot of time.

The most important thing is that you have get the wxWidgets ready working with code::blocks. Now, let's make some project :)

== Creating wxWidgets project ==

The easiest and the preferred way is to create wxWidgets project using project wizard. It starts like creating any other project using ''New project'' menu:

[[Image:wxs_tut01_001.png]]

Then to create wxWidgets application, let's choose wxWidgets icon:

[[Image:wxs_tut01_002.png]]

After you click "Go" button, Code::Blocks will bring up the wizard window. It consist of several pages where you can enter some options for your project. I'll describe few pages better since they may cause problems for new users.

At the very beginning the wizard asks you which version of wxWidgets you want to use:

[[Image:wxs_tut01_003.png]]

The best option for now is to use wxWidgets 2.8.x since it is stable and has few features not present in wxWidgets 2.6.x series. Also wxSmith aims to provide support for latest stable version of wxWidgets.

On another wizard page you choose what GUI designer will be used and what type of application should be generated:

[[Image:wxs_tut01_004.png]]

If you want your application to work with wxSmith check the wxSmith designer option. You also have available the check box for the wxFormBuilder, although this program is not covered in the tutorials presented here. The other option let's you choose whether your application will be created using wxFrame or wxDialog. Both options will lead to a valid wxWidgets application but wxFrame is the preferred choice since it's a more common usage of wxWidgets and the wxDialog-based applications are not as flexible as wxFrame-based applications.

On another page you may choose the location of your wxWidgets library:

[[Image:wxs_tut01_005.png]]

You can choose real directory here, but that may lead to problems when your project should also compile on other computers. Another choice is to use '''Global Variable system''' ( to open the dialog below or modify or change this global variable, you should click on the menu '''Settings->Global variables''') available in Code::Blocks.

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

When you use global variable for the first time, it will ask for wxWidgets directory. The only thing you need to do here is to enter 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.

[[Image:wxs_tut01_006.png]]

On the next step, wizard will ask you for configuration of wxWidgets library. Since wxWidgets may be compiled differently, each compilation type should also be threated differently inside your project. This step may be little bit confusing for new users since it require some knowledge about build process of wxWidgets. But if you used wiki pages that I've put at the beginning of this tutorial to compile wxWidgets, set your configuration to this one:

[[Image:wxs_tut01_007.png]]

Here is a brief explanation of these options
* '''use wxWidgets DLL''' : If checked, when you create an executable file, it link to wxWidgets dynamic link library, So, your exe file should run with some wxWidgets DLL files. If unchecked, your executable file's size will be larger, but it can run without wxWidgets DLL's support.
* '''wxWidgets is built as monolithic library''' : If checked, your target build file will link to the monolithic library of wxWidgets. see [[WxWindowsQuickRef#wxWidgets_Build_Options_Explained]] for more details.
* '''Enable unicode''' : If your program will support some international language other than English, such Chinese, Japanese, you can check on this option.
* '''Create and use precompiled header(PCH)''' : It will speed up building your program. see [http://en.wikipedia.org/wiki/Precompiled_header PCH] for more details.'''Note''' that I've also checked the option to use precompiled headers (PCH) since it can really speed-up the compilation of wxWidgets applications on some compilers (especially GCC).

When you follow another wizard pages, you may occasionally see message box saying that debug configuration can not be found. This is because the wxWidgets library was build using release mode (the ''BUILD=release'' option used for make). If you want real debug library, you can recompile your wxWidgets by using ''BUILD=debug''. Project may also be tuned to work with release version on both debug and release build targets (the way to do this is presented at the end of this tutorial).

After project is created and initialized properly, Code::Blocks will look like this:

[[Image:wxs_tut01_008.png]]

Now when you select ''Release'' build target and press Compile, it should create wxWidgets application. But before you run it, you will probably need to copy wxWidgets dlls (from ''lib\gcc_dll'' inside directory where your copy of wxWidgets resides) to project's directory. When your application is ready and runs without problems, we can jump to the next point.

== Let's add some fireworks ==

Now it's time to fill the empty frame with some "Hello World" message. This text could be added directly into the frame, just like in most commercial GUI designers. But we will learn to use [http://wiki.wxwidgets.org/WxSizer sizers]. But what's that?

If you have been working with java you will remember something called Layout managers. Implementation in wxWidgets differs a little bit but it does almost the same thing.

Ok, but let's put some explanation here:
Usually when adding items into windows you must specify the item's position and size. wxWidgets tries to automate this process and it uses sizers for that. They are automatically positioning and sizing window items and they can also set the size of the window to fit all items inside. Sizers have one big advantage. When you write cross-platform applications, you cannot assume that fonts, buttons, etc. are sized the same on different operating systems. This can even occur on the same platform when using window themes. When you use sizers, you don't have to worry about that. All sizing is done automatically. And one more thing - sizers can even reposition and resize window items when the main window changes size.

Now since we have some background knowledge, it's time to add something.

When you look at the wxSmith editor, you'll notice that the area of window is surrounded by eight black boxes.

[[Image:wxs_tut01_009.png]]

These black boxes are surrounding a currently selected item. In our case it's a whole window.
Adding new items is simply done by clicking on one of the buttons in the palette at the bottom of the editor and then clicking some position on the resource.

[[Image:wxs_tut01_010.png]]

As you can see here, when you keep your mouse cursor over a component, it will show its name. That may help to find items when you're not familiar with their icons.

Let's add a new wxPanel component to our window - this is the fourth icon from the left. You may see that when you click the wxPanel item and then move the cursor over the resource, some part of the editor will change colour. That's intentional and used to show onto which part of the resource the new item will be added.

After wxPanel is ready you will notice that the background colour of the window 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 item by selecting the place for the new item. 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 can be changed by clicking one of 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 show by a red check mark on the button.
Sometimes a few selection modes are disabled. This means that they are not valid for the currently selected item. For example you cannot add any item into the wxButton component since wxWidgets declares it as one that cannot have child items. And when the main component (the window) is selected, you won't be able to add anything after it or before it.

Now let's assume that we've made a mistake and want to delete an item that we have just added. In fact we have a small mistake and will have to delete wxPanel. To this, click on the red X button:

[[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.

The mistake made here is that we've added wxPanel directly into the main frame. But as I've said before, we will be using sizers to manage the window's content. To use sizers, first we have to add a sizer into the main frame and then add 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 by default and we will use this.

After adding sizer, two things have changed. First is that our window now has a red border. This means that there's 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 thing is that the size of the window has shrunk to a small box. That's correct since the sizer is also responsible for resizing items.

Now let's add wxPanel. Make sure that we will add it into the sizer, not the main frame. After we do this, 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 item added into the sizer can be surrounded by such a border. It's useful when you want to have spacing between items. But in our case we should get rid of it to get a more proper window. To do so, we will have to change a property inside the property browser. Search for border size and change it 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 wxStaticText:

[[Image:wxs_tut01_017.png]]

Because this text looks so ''lonely'', let's add a button next to it by clicking on wxButton. Note that if you still have the "point by mouse" insertion mode turned on, half of the wxStaticText item will be coloured in light blue when you put the mouse over it. This is a hint for you: when the left half of the text is highlighted, the new item will be added before it, and when the right half is highlighted, it will be added after the text. So 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 it select our text first, find the '''Label''' property and change it to "Hello world":

[[Image:Wxs_tut01_019.png]]

You can also set multi line text by clicking on the "..." button or putting "\n" inside text (just like in c strings).

== Let's react - making close button ==

Now let's do something with the button. Since buttons usually react when somebody clicks them, let's make it close the window. First thing we should do is to change text shown on button to notify user about function assigned to it. It is done just like in case of text - select button, find "Label" property and set it to "Close" (or anything you want ;) ).

Second thing is to assign event handler to this button. Basically event handlers are function which are called when some "event" occurs. In our case instead of "event" we could say "click on button" because that we want to process. As many GUI designer, wxSmith can automatically generate such handlers. They are accessed through property browser just like other properties. To switch to events you have to click second icon at the top of property browser (don't worry, those icons are going to change to something more self-explanatory):

[[Image:Wxs_tut01_020.png]]

After you click on this icon, you will see all events supported by currently selected item. wxButton class support only EVT_BUTTON event so only this one is shown. When you click on this event and expand combo box you will see available options and handlers for this event:

[[Image:Wxs_tut01_021.png]]

When you select '''-- None --''' there won't be handler function automatically assigned to this event (it may always be set manually), selecting '''-- Add new handler --''' will generate 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. So let's create new handler. We could use one of those defined, but since we haven't looked into source code yet, we don't know what they do. After you select new handler option, you will be asked for name of handler. This is simply name of function which will be called as a reaction for event.

When you enter new handler name, wxSmith will generate new handler function, open file with proper source code and put cursor inside handler function (note that you may need to press up or down cursor to show the line with cursor). Note that this function is member of class called for example '''HelloWorldFrame'''. wxSmith creates one such class for each resource. Since event handler function is member of this class, you have access to all the window from it. So when we want to close our window we just call '''Close''' function:

[[Image:Wxs_tut01_022.png]]

After compiling our project it will show our "Hello world" and "Close" button.

This is end of this tutorial, I hope that it showed some basics of wxSmith. If you have any problems with it or think that some parts are unclear, please contact me (byo) on forum.

WxSmith extensions

2010-12-06T15:49:09Z

Greenbreen: Minor edits for clarity

Welcome to wxSmith extensions wiki page. This page contains a few tutorials which show how to extend wxSmith's functionality. It also contains a set of extensions which are being worked on now. If you would like to add some extra functionality to wxSmith and want to share your results, please take a look at the [[wxSmith extensions list]] page. You can check there who is working on particular extensions and add your own info to prevent other developers from working on the same feature as you.

[[Category:Code::Blocks Documentation]]
[[Category:Developer Documentation]]
[[Category:wxSmith extensions]]

== Tutorials ==

we have prepared a few tutorials which will show you how to add your own extensions to wxSmith. They describe parts of wxSmith essential to extensions support. They also show real examples on how to extend wxSmith.

* Tutorial 1: [[Creating a plugin which adds new item into wxSmith]]
* Tutorial 2: [[wxSmith tutorial: Adding basic properties into items|Adding basic properties]]
* Tutorial 3: [[wxSmith tutorial: Adding advanced properties into items|Adding advanced properties]]
* Tutorial 4: [[wxSmith tutorial: More on code and preview generation|More on code and preview generation]]
* Tutorial 5: [[wxSmith tutorial: Adding support for events in custom items]]

== Extensions list ==

On [[wxSmith extensions list|this]] page you can see the list of wxSmith extensions. It will contain extensions which are done, are being worked on and which are not worked on yet. You will also find there information on how to add your code into the main Code::Blocks source.

WxSmith tutorial: Creating items with custom paint and mouse handling

2010-12-06T15:42:42Z

Greenbreen: Minor edits for clarity

= Warning: unfinished =

Welcome back :) We've already learned nice techniques of working with wxSmith in previous tutorials and now it's time for something even better. Usually when writing some more advanced application, it turns out that none of the items provided by wxWidgets fits our purposes, especially when we need to present some data in graphical form. Hopefully as with almost all GUI toolkits, wxWidgets is also prepared for this and gives us the possibility to create an item with custom drawing and mouse handling - this allows us to create any item we like.

= Creating an item with the custom paint procedure =

Before we start creating our customized item, some background knowledge is needed.
The first thing you should know is how wxWidgets draws items.

Most items have custom paint procedures provided by the operating system or some other toolkit available in the system (like gtk+). In the case of such items, when the OS posts a request to repaint the item, either this message is forwarded by wxWidgets back into the system or even the whole procedure is done without any wxWidgets' intervention. Unfortunately this means that we cannot replace the paint procedure for most items and even if it would work on some platforms, it won't on others. From the items available in wxSmith, only wxPanel is guaranteed to work with the custom paint procedure.

Now if we overwrite painting on wxPanel, wxWidgets will post two events on each paint request:
* erase background event (EVT_ERASE_BACKGROUND)
* paint event (EVT_PAINT)

The first one is used to prepare the area occupied by our item before adding content and the second one is used to do the actual drawing. We don't have to override both events so we can draw just a custom background or just custom content, leaving the background as the default one.

The second thing you should know before writing a custom paint method is that wxWidgets uses wxDC objects to draw. In the case of the erase background event, this object is provided within the event; in the case of the paint event, we must create this object manually. To get more information about wxDC and drawing functions, take a look at [http://docs.wxwidgets.org/stable/wx_wxdc.html#wxdc this page in the wxWidgets documentation].

= Creating a simple resource and overriding the paint method =

Now let's create some simple window. For our purposes we need some wxPanel inside the window which we will work on:

[[Image:wxs_tut07_001.png]]

Now let's go to the event's tab in the properties browser. You may see that wxPanel can process many more events than other items. That's because it can be used as a base for custom items which may have a custom handler for any standard event. Ok, let's find the EVT_PAINT method (it should be at the top) and add a new empty event.

The first thing we should do inside the handler is to create the wxDC object we will use. If you look at the wxWidgets documentation you may read that not doing so causes wxWidgets to go into an infinite loop because the paint method will be called over and over again.

There are a few types of wxDC objects we could use here. The most commonly used is wxPaintDC:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
'''wxPaintDC dc( Panel1 );'''
}

You can see that we passed the panel's pointer as an argument - wxPaintDC require a pointer to the item we will draw on in its constructor. Remember not to use the ''this'' pointer.

Now let's add some drawing code - just some diagonal line to test whether drawing does work:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
wxPaintDC dc( Panel1 );
'''dc.DrawLine( 0, 0, 100, 100 );'''
}

Now if we run our application, the window will look like this:

[[Image:wxs_tut07_002.png]]

WxSmith tutorial: Creating items with custom paint and mouse handling

2010-12-06T15:31:44Z

Greenbreen: Minor edits for clarity

= Warning: unfinished =

Welcome back :) We've already learned nice techniques of working with wxSmith in previous tutorials and now it's time for something even better. Usually when writing some more advanced application, it turns out that none of the items provided by wxWidgets fits our purposes, especially when we need to present some data in graphical form. Hopefully as with almost all GUI toolkits, wxWidgets is also prepared for this and gives us the possibility to create an item with custom drawing and mouse handling - this allows us to create any item we like.

= Creating an item with the custom paint procedure =

Before we start creating our customized item, some background knowledge is needed.
The first thing you should know is how wxWidgets draws items.

Most items have custom paint procedures provided by the operating system or some other toolkit available in the system (like gtk+). In the case of such items, when the OS posts a request to repaint the item, either this message is forwarded by wxWidgets back into the system or even the whole procedure is done without any wxWidgets' intervention. Unfortunately this means that we cannot replace the paint procedure for most items and even if it would work on some platforms, it won't on others. From the items available in wxSmith, only wxPanel is guaranteed to work with the custom paint procedure.

Now if we overwrite painting on wxPanel, wxWidgets will post two events on each paint request:
* erase background event (EVT_ERASE_BACKGROUND)
* paint event (EVT_PAINT)

The first one is used to prepare the area occupied by our item before adding content and the second one is used to do the actual drawing. We don't have to override both events so we can draw just a custom background or just custom content, leaving the background as the default one.

The second thing you should know before writing a custom paint method is that wxWidgets uses wxDC objects to draw. In the case of the erase background event, this object is provided within the event; in the case of the paint event, we must create this object manually. To get more information about wxDC and drawing functions, take a look at [http://docs.wxwidgets.org/stable/wx_wxdc.html#wxdc this page in the wxWidgets documentation].

= Creating simple resource and overriding paint method =

Now let's create some simple window. For our purposes we need some wxPanel inside the window which we will work on:

[[Image:wxs_tut07_001.png]]

Now let's go to event's tab in properties browser. You may see that wxPanel can process much more events than other items. That's because it can be use as base for custom items which may have custom handler for any standard event. Ok, let's find EVT_PAINT method (sohuld be at the top) and add new empty event.

The first thing we should do inside the handler is to create wxDC object we will use. If you look at wxWidgets documentation you may read that not doing so causes wxWidgets to go into infinite loop because paint method will be recalled over and over again.

There are few types of wxDC objects we could use here. The most commonly used is wxPaintDC:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
'''wxPaintDC dc( Panel1 );'''
}

You can see that we passed panel's pointer as argument - wxPaintDC require pointer to item we will draw on on it's constructor. Remember not to use ''this'' opinter.

Now let's add some drawing code - just some diagonal line to test whether drawing does work:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
wxPaintDC dc( Panel1 );
'''dc.DrawLine( 0, 0, 100, 100 );'''
}

Now if we run our aplication, the window will look like this:

[[Image:wxs_tut07_002.png]]

WxSmith tutorial: Creating items with custom paint and mouse handling

2010-12-06T15:22:04Z

Greenbreen: Minor edits for clarity

= Warning: unfinished =

Welcome back :) We've already learned nice techniques of working with wxSmith in previous tutorials and now it's time for something even better. Usually when writing some more advanced application, it turns out that none of the items provided by wxWidgets fits our purposes, especially when we need to present some data in graphical form. Hopefully as with almost all GUI toolkits, wxWidgets is also prepared for this and gives us the possibility to create an item with custom drawing and mouse handling - this allows us to create any item we like.

= Creating item with custom paint procedure =

Before we start creating our customized item, some background knowledge is needed.
First thing you should know is how wxWidgets draws items.

Most of items have custom paint procedures provided by operating system or some other toolkit available in system (like gtk+). In case of such items, when OS posts request to repaint item, either such message is forwarded by wxWidgets back into system or even the whole procedure is done without any wxWidgets' intervention. Unfortunately this means that we can not replace paint procedure in case of all items and even if it would work on some platforms, it won't on others. From items available in wxSmith, only wxPanel is guaranteed to work with custom paint procedure.

Now if we overwrite painting on wxPanel, wxWidgets will post two events on each paint request:
* erase background event (EVT_ERASE_BACKGROUND)
* paint event (EVT_PAINT)

First one is used to prepare area occupied by our item before adding content and the second one is used to do actual drawing. We don't have to override both events so we can only draw custom background or custom content leaving background as default one.

Second thing you should know before writing custom paint method is that wxWidgets uses wxDC objects to draw. In case of erase background event, this object is provided within event, in case of paint event, we must create such object manually. To get more informations about wxDC and drawing functions, take look at [http://docs.wxwidgets.org/stable/wx_wxdc.html#wxdc this page in wxWidgets documentation].

= Creating simple resource and overriding paint method =

Now let's create some simple window. For our purposes we need some wxPanel inside the window which we will work on:

[[Image:wxs_tut07_001.png]]

Now let's go to event's tab in properties browser. You may see that wxPanel can process much more events than other items. That's because it can be use as base for custom items which may have custom handler for any standard event. Ok, let's find EVT_PAINT method (sohuld be at the top) and add new empty event.

The first thing we should do inside the handler is to create wxDC object we will use. If you look at wxWidgets documentation you may read that not doing so causes wxWidgets to go into infinite loop because paint method will be recalled over and over again.

There are few types of wxDC objects we could use here. The most commonly used is wxPaintDC:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
'''wxPaintDC dc( Panel1 );'''
}

You can see that we passed panel's pointer as argument - wxPaintDC require pointer to item we will draw on on it's constructor. Remember not to use ''this'' opinter.

Now let's add some drawing code - just some diagonal line to test whether drawing does work:

void Tutorial7Dialog::OnPanel1Paint(wxPaintEvent& event)
{
wxPaintDC dc( Panel1 );
'''dc.DrawLine( 0, 0, 100, 100 );'''
}

Now if we run our aplication, the window will look like this:

[[Image:wxs_tut07_002.png]]

WxSmith tutorial: Accessing items in resource

2010-12-05T18:29:36Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading the value from wxTextCtrl =

Now let's read something that's written by the user. We will use the wxTextCtrl (with variable TextCtrl1) for this and show the text using a standard message box. Let's double click the '''Read text''' button and change the code to the following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read the value from the TextCtrl and store it inside a variable of type wxString. wxString is wxWidgets implementation of a string object and this library uses it as a base for string representation.

In the second line we call the '''wxMessageBox''' function which shows a standard message box just like it was a modal dialog.

Usually items which provide content entered by the user have two member functions: GetValue and SetValue. You can use them to read and write the content of such items.

= Changing the value of wxGauge =

Now let's mix reading and writing of an item's value in one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written earlier that those functions usually exist in items where the usercan enter some value. Well it's not a golden rule and there are exceptions from it like in the case of this item :).

Ok, let's add the handler for the third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In the first line we generate a new progress value by reading the current one and adding 10 to it. In the second line we prevent the value from getting out of range (by default wxGauge has a range set to 0..100 - this can be changed in properties). In the third line we write the new value into the gauge.

= Using the value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's a wxSlider and text saying that it changes font size. We will change the font of this label. But we will have to update the font size in two steps:

* As long as the user drags the slider we should change the font size only
* When the user finishes dragging we should layout the window because the size of the text changes

wxSlider provides two events that can be used right for this purpose. The first is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. The second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when the user finishes dragging.

Because we use events which are not default we would have to add them through the properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for the required events and choose '''Add new handler''' from the drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get the font used by the StaticText control by using the '''GetFont()''' function, change the font's size by using '''SetPointSize()''' and write the font back by using the '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adapt the positions of items to the new environment just like in the case of changing the label in wxStaticText. In the second line we recalculate the minimal size of the window making sure that all items will have enough space.

= Changing an item's colour =

The last thing we will do in this tutorial is to change the colour of some item. As in the case of fonts we will change the label on the left side of the '''Change''' button. Since we will use the standard event of this button, we can add an event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to the variable '''OldColour'''. In the next line we call the '''wxGetColourFromUser''' function which opens a dialog where we can choose a colour.

The '''NewColour.IsOk()''' call is required because if the user cancels the colour selection it will return false.

At the end we set the new colour by using the '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More information =

We've reached the end of this tutorial. I showed only a few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-05T18:28:23Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading the value from wxTextCtrl =

Now let's read something that's written by the user. We will use the wxTextCtrl (with variable TextCtrl1) for this and show the text using a standard message box. Let's double click the '''Read text''' button and change the code to the following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read the value from the TextCtrl and store it inside a variable of type wxString. wxString is wxWidgets implementation of a string object and this library uses it as a base for string representation.

In the second line we call the '''wxMessageBox''' function which shows a standard message box just like it was a modal dialog.

Usually items which provide content entered by the user have two member functions: GetValue and SetValue. You can use them to read and write the content of such items.

= Changing the value of wxGauge =

Now let's mix reading and writing of an item's value in one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written earlier that those functions usually exist in items where the usercan enter some value. Well it's not a golden rule and there are exceptions from it like in the case of this item :).

Ok, let's add the handler for the third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In the first line we generate a new progress value by reading the current one and adding 10 to it. In the second line we prevent the value from getting out of range (by default wxGauge has a range set to 0..100 - this can be changed in properties). In the third line we write the new value into the gauge.

= Using the value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's a wxSlider and text saying that it changes font size. We will change the font of this label. But we will have to update the font size in two steps:

* As long as the user drags the slider we should change the font size only
* When the user finishes dragging we should layout the window because the size of the text changes

wxSlider provides two events that can be used right for this purpose. The first is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. The second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when the user finishes dragging.

Because we use events which are not default we would have to add them through the properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for the required events and choose '''Add new handler''' from the drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get the font used by the StaticText control by using the '''GetFont()''' function, change the font's size by using '''SetPointSize()''' and write the font back by using the '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adapt the positions of items to the new environment just like in the case of changing the label in wxStaticText. In the second line we recalculate the minimal size of the window making sure that all items will have enough space.

= Changing an item's colour =

The last thing we will do in this tutorial is to change the colour of some item. As in the case of fonts we will change the label on the left side of the '''Change''' button. Since we will use the standard event of this button, we can add an event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to the variable '''OldColour'''. In the next line we call the '''wxGetColourFromUser''' function which opens a dialog where we can choose a colour.

The '''NewColour.IsOk()''' call is required because if the user cancels the colour selection it will return false.

At the end we set the new colour by using the '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-05T18:16:50Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading the value from wxTextCtrl =

Now let's read something that's written by the user. We will use the wxTextCtrl (with variable TextCtrl1) for this and show the text using a standard message box. Let's double click the '''Read text''' button and change the code to the following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read the value from the TextCtrl and store it inside a variable of type wxString. wxString is wxWidgets implementation of a string object and this library uses it as a base for string representation.

In the second line we call the '''wxMessageBox''' function which shows a standard message box just like it was a modal dialog.

Usually items which provide content entered by the user have two member functions: GetValue and SetValue. You can use them to read and write the content of such items.

= Changing the value of wxGauge =

Now let's mix reading and writing of an item's value in one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written earlier that those functions usually exist in items where the usercan enter some value. Well it's not a golden rule and there are exceptions from it like in the case of this item :).

Ok, let's add the handler for the third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In the first line we generate a new progress value by reading the current one and adding 10 to it. In the second line we prevent the value from getting out of range (by default wxGauge has a range set to 0..100 - this can be changed in properties). In the third line we write the new value into the gauge.

= Using the value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's a wxSlider and text saying that it changes font size. We will change the font of this label. But we will have to update the font size in two steps:

* As long as the user drags the slider we should change the font size only
* When the user finishes dragging we should layout the window because the size of the text changes

wxSlider provides two events that can be used right for this purpose. The first is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. The second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when the user finishes dragging.

Because we use events which are not default we would have to add them through the properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for the required events and choose '''Add new handler''' from the drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get the font used by the StaticText control by using the '''GetFont()''' function, change the font's size by using '''SetPointSize()''' and write the font back by using the '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adapt the positions of items to the new environment just like in the case of changing the label in wxStaticText. In the second line we recalculate the minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-03T17:04:34Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading the value from wxTextCtrl =

Now let's read something that's written by the user. We will use the wxTextCtrl (with variable TextCtrl1) for this and show the text using a standard message box. Let's double click the '''Read text''' button and change the code to the following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read the value from the TextCtrl and store it inside a variable of type wxString. wxString is wxWidgets implementation of a string object and this library uses it as a base for string representation.

In the second line we call the '''wxMessageBox''' function which shows a standard message box just like it was a modal dialog.

Usually items which provide content entered by the user have two member functions: GetValue and SetValue. You can use them to read and write the content of such items.

= Changing the value of wxGauge =

Now let's mix reading and writing of an item's value in one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written earlier that those functions usually exist in items where the usercan enter some value. Well it's not a golden rule and there are exceptions from it like in the case of this item :).

Ok, let's add the handler for the third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In the first line we generate a new progress value by reading the current one and adding 10 to it. In the second line we prevent the value from getting out of range (by default wxGauge has a range set to 0..100 - this can be changed in properties). In the third line we write the new value into the gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-03T16:57:28Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading the value from wxTextCtrl =

Now let's read something that's written by the user. We will use the wxTextCtrl (with variable TextCtrl1) for this and show the text using a standard message box. Let's double click the '''Read text''' button and change the code to the following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read the value from the TextCtrl and store it inside a variable of type wxString. wxString is wxWidgets implementation of a string object and this library uses it as a base for string representation.

In the second line we call the '''wxMessageBox''' function which shows a standard message box just like it was a modal dialog.

Usually items which provide content entered by the user have two member functions: GetValue and SetValue. You can use them to read and write the content of such items.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-03T16:50:20Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing the label in wxStaticText =

Ok, let's do some basic exercise by changing the label of the first wxStaticText. To do this double click on the button next to it to generate an event handler and change the code to the following:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In the first line of the function body we used the '''SetLabel()''' function to change the text of the label. Because the length of the text changes, we must recalculate positions, which is done by calling the '''Layout()''' function.

Static items (those which can't be changed by the user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for the string:
_("Label changed")
instead of a simple
"Label changed"

There are two advantages to such an approach:
* By adding _(...) around our string we prepare our application for the translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for the translation of the "Label changed" text in a strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In the case of a unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using the '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce the proper code.

There's an alternative version of the string macro which works similarly to _(...) which is written in the form _T(...) or wxT(...). It works like the _() one but the string is never translated.

= Reading value from wxTextCtrl =

Now let's read something that's written by user. We will use wxTextCtrl (with variable TextCtrl1) for this and show the text using standard message box. Let's double click the '''Read text''' button and change the code to following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read value from TextCtrl and store it inside variable of type wxString. wxString is wxWidgets implementation of string object and this library uses it as base for string representation.

In the second line we call '''wxMessageBox''' function which shows standard message box just like it was modal dialog.

Usually items which provide content entered by user have two member functions: GetValue and SetValue. You can use them to read and write content of such item.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-03T16:41:18Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of the used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you cannot provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing label in wxStaticText =

Ok, let's do some basic excercise by changing label of first wxStaticText. To do this double click on button next to it to generate event handler and change the code to following thing:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In first line of function body we used '''SetLabel()''' function to change text of label. Because length of the text changes, we must recalculate positions which is done by calling '''Layout()''' function.

In case of static items (those which can't be changed by user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for string:
_("Label changed")
instead of simple
"Label changed"

There are two advantages of such approach:
* By adding _(...) around our string we prepare our application for translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for translaction of "Label changed" text in strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In case of unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce proper code.

There's alternative version of string macro which works simillarily to _(...) which is written in form _T(...) or wxT(...). It works like _() one but the string is never translated.

= Reading value from wxTextCtrl =

Now let's read something that's written by user. We will use wxTextCtrl (with variable TextCtrl1) for this and show the text using standard message box. Let's double click the '''Read text''' button and change the code to following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read value from TextCtrl and store it inside variable of type wxString. wxString is wxWidgets implementation of string object and this library uses it as base for string representation.

In the second line we call '''wxMessageBox''' function which shows standard message box just like it was modal dialog.

Usually items which provide content entered by user have two member functions: GetValue and SetValue. You can use them to read and write content of such item.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-02T17:05:56Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of the resource class =

If you add an item in the editor, in most cases wxSmith will add a new member variable into the resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In the case of the window we created it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such a member variable will also have the following properties:
* '''Var name''' - name of used variable
* '''Is member''' - switch whether this item should be accessible through a class member variable

So if you want to change the name used to access the item, '''Var name''' is the right property to change.

wxSmith forces a few restrictions on variable names. The most obvious is that each variable name must be a valid c++ identifier so you can not provide special characters or even spaces. Another limitations is that variable names must be unique.
If the name is invalid, wxSmith will automatically replace it with a name that matches the criteria.

= Changing label in wxStaticText =

Ok, let's do some basic excercise by changing label of first wxStaticText. To do this double click on button next to it to generate event handler and change the code to following thing:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In first line of function body we used '''SetLabel()''' function to change text of label. Because length of the text changes, we must recalculate positions which is done by calling '''Layout()''' function.

In case of static items (those which can't be changed by user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for string:
_("Label changed")
instead of simple
"Label changed"

There are two advantages of such approach:
* By adding _(...) around our string we prepare our application for translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for translaction of "Label changed" text in strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In case of unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce proper code.

There's alternative version of string macro which works simillarily to _(...) which is written in form _T(...) or wxT(...). It works like _() one but the string is never translated.

= Reading value from wxTextCtrl =

Now let's read something that's written by user. We will use wxTextCtrl (with variable TextCtrl1) for this and show the text using standard message box. Let's double click the '''Read text''' button and change the code to following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read value from TextCtrl and store it inside variable of type wxString. wxString is wxWidgets implementation of string object and this library uses it as base for string representation.

In the second line we call '''wxMessageBox''' function which shows standard message box just like it was modal dialog.

Usually items which provide content entered by user have two member functions: GetValue and SetValue. You can use them to read and write content of such item.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-02T16:56:50Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding a few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In the first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons in the right column. Below there is wxSlider which will be used to change the size of the font - I've changed its '''Max''' property to 30 to limit the size range. Below there's a button which will be used to change the colours of some items.

= Accessing items through members of resource class =

If you add item in editor, in most cases wxSmith will add new member variable into resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In case of window we crated it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such member variable will also have following properties:
* '''Var name''' - name of used variable
* '''Is member''' - switch whether this item should be accessible through class member variable

So if you want to change name used to access item, '''Var name''' is right property to change.

wxSmith forces few restrictions on variable names. Most obvious is that each variable name must be valid c++ identifier so you can not provide special characters or even spaces. Another limitations is that variable names must be unique.
If name is invalid, wxSmith will automatically replace it with name that matches criteria.

= Changing label in wxStaticText =

Ok, let's do some basic excercise by changing label of first wxStaticText. To do this double click on button next to it to generate event handler and change the code to following thing:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In first line of function body we used '''SetLabel()''' function to change text of label. Because length of the text changes, we must recalculate positions which is done by calling '''Layout()''' function.

In case of static items (those which can't be changed by user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for string:
_("Label changed")
instead of simple
"Label changed"

There are two advantages of such approach:
* By adding _(...) around our string we prepare our application for translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for translaction of "Label changed" text in strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In case of unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce proper code.

There's alternative version of string macro which works simillarily to _(...) which is written in form _T(...) or wxT(...). It works like _() one but the string is never translated.

= Reading value from wxTextCtrl =

Now let's read something that's written by user. We will use wxTextCtrl (with variable TextCtrl1) for this and show the text using standard message box. Let's double click the '''Read text''' button and change the code to following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read value from TextCtrl and store it inside variable of type wxString. wxString is wxWidgets implementation of string object and this library uses it as base for string representation.

In the second line we call '''wxMessageBox''' function which shows standard message box just like it was modal dialog.

Usually items which provide content entered by user have two member functions: GetValue and SetValue. You can use them to read and write content of such item.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Accessing items in resource

2010-12-02T16:53:02Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Accessing items in a resource =

Welcome to the next tutorial. This time I'll show you how to access items in a resource. I'll show you some basics - for example how to read data from text boxes, change labels, and some more advanced things like changing colours and fonts while the application is running. As usual we will start with an empty application. You shouldn't have any problems with it - all instructions are in the first tutorial.

= Adding few items we will work on =

In this tutorial we will work on items so let's add some:

[[Image:wxs_tut06_001.png]]

In this resource wxFlexGridSizer with 2 columns is used as background. In first three rows we have wxStaticText, wxTextCtrl and wxGauge - we will operate on them using buttons on the right column. Below there is wxSlider which will be used to change size of font - I've changed it's '''Max''' property to 30 to limit size range. Below there's button which will be used to change colours of some items.

= Accessing items through members of resource class =

If you add item in editor, in most cases wxSmith will add new member variable into resource's c++ class. All those members are listed inside <code>//(*Declarations ... //*)</code> code blocks. In case of window we crated it should look like this:

...
class Tutorial_6Frame: public wxFrame
{
...

//(*Declarations(Tutorial_6Frame)
wxSlider* Slider1;
wxButton* Button4;
wxStaticText* StaticText2;
wxButton* Button1;
wxGauge* Gauge1;
wxStaticText* StaticText1;
wxStaticText* StaticText3;
wxButton* Button2;
wxButton* Button3;
wxStatusBar* StatusBar1;
wxTextCtrl* TextCtrl1;
//*)
...
};
...

Each item which has such member variable will also have following properties:
* '''Var name''' - name of used variable
* '''Is member''' - switch whether this item should be accessible through class member variable

So if you want to change name used to access item, '''Var name''' is right property to change.

wxSmith forces few restrictions on variable names. Most obvious is that each variable name must be valid c++ identifier so you can not provide special characters or even spaces. Another limitations is that variable names must be unique.
If name is invalid, wxSmith will automatically replace it with name that matches criteria.

= Changing label in wxStaticText =

Ok, let's do some basic excercise by changing label of first wxStaticText. To do this double click on button next to it to generate event handler and change the code to following thing:

void Tutorial_6Frame::OnButton1Click(wxCommandEvent& event)
{
StaticText1->SetLabel(_("Label changed"));
Layout();
}

In first line of function body we used '''SetLabel()''' function to change text of label. Because length of the text changes, we must recalculate positions which is done by calling '''Layout()''' function.

In case of static items (those which can't be changed by user) usually have two functions: GetLabel and SetLabel which read and write content presented by this item.

You may wonder why we used some weird notation for string:
_("Label changed")
instead of simple
"Label changed"

There are two advantages of such approach:
* By adding _(...) around our string we prepare our application for translation process. wxWidgets can help developing multilanguage applications and when some some different language will be used, it will automatically search for translaction of "Label changed" text in strings database.
* wxWidgets may be provided in two versions: with unicode support and without it (ansi build). In case of unicode version, we would have to use unicode strings: '''L"Label changed"''' and in case of ansi version we would have to use standard string notation: '''"Label changed"'''. Using '''_(...)''' macro grants that no matter what wxWidgets version is used, it will always produce proper code.

There's alternative version of string macro which works simillarily to _(...) which is written in form _T(...) or wxT(...). It works like _() one but the string is never translated.

= Reading value from wxTextCtrl =

Now let's read something that's written by user. We will use wxTextCtrl (with variable TextCtrl1) for this and show the text using standard message box. Let's double click the '''Read text''' button and change the code to following:

void Tutorial_6Frame::OnButton2Click(wxCommandEvent& event)
{
wxString Text = TextCtrl1->GetValue();
wxMessageBox(_("User entered text:\n") + Text);
}

In the first line we read value from TextCtrl and store it inside variable of type wxString. wxString is wxWidgets implementation of string object and this library uses it as base for string representation.

In the second line we call '''wxMessageBox''' function which shows standard message box just like it was modal dialog.

Usually items which provide content entered by user have two member functions: GetValue and SetValue. You can use them to read and write content of such item.

= Changing value of wxGauge =

Now let's mix reading and writing of item's value on one function. We will use wxGauge for this. We will use it's two member functions: GetValue and SetValue. I've written ealier that those functions usually exist in items where user can enter some value. Well it's not a gold rule and there are exceptions from it like in case of this item :).

Ok, let's add handler for third button:

void Tutorial_6Frame::OnButton3Click(wxCommandEvent& event)
{
int NewValue = Gauge1->GetValue()+10;
if ( NewValue > 100 ) NewValue = 0;
Gauge1->SetValue(NewValue);
}

In first line we generate new value of progress by reading current one and adding 10 to it. In second line we prevent the value from getting out of range (by default wxGauge has range set to 0..100 - this can be changed in properties). In third line we write new value into gauge.

= Using value from wxSlider to change font size =

Now let's do something more advanced. In our resource there's wxSlider and text saying that it changes font size. We will change font of this label. But we will have to update font size in two steps:

* As long as user draggs the slider we should change font size only
* When user finishes dragging we should layout window because size of text changes

wxSlider provides two events that can be used right for this purpose. First is '''EVT_COMMAND_SCROLL_THUMB_TRACK''' which is fired while dragging the slider. Second is '''EVT_COMMAND_SCROLL_THUMB_RELEASE''' which is fired when user finishes dragging.

Because we use events which are not default we would have to add them through properties browser. You can switch between editing standard properties and events by clicking on buttons at the top of browser:

[[Image:wxs_tut06_002.png]].

If you switch to events, search for required events and choose '''Add new handler''' from drop-down list.
Here's the code for '''EVT_COMMAND_SCROLL_THUMB_TRACK''' handler:

void Tutorial_6Frame::OnSlider1CmdScrollThumbTrack(wxScrollEvent& event)
{
wxFont Font = StaticText2->GetFont();
Font.SetPointSize( Slider1->GetValue() );
StaticText2->SetFont(Font);
}

Here we get font used by StaticText control by using '''GetFont()''' function, change font's size by using '''GetPointSize()''' and write font back by using '''SetFont()''' function. '''GetFont()''' and '''SetFont()''' are available in most items.

Now let's code '''EVT_COMMAND_SCROLL_THUMB_RELEASE''':

void Tutorial_6Frame::OnSlider1CmdScrollThumbRelease(wxScrollEvent& event)
{
Layout();
GetSizer()->SetSizeHints(this);
}

In the first line we adopt positions of items to new environment just like in case of changing label in wxStaticText. In the second line we recalculate minimal size of the window making sure that all items will have enough space.

= Changing item's colour =

Last thing we will do in this tutorial is to change colour of some item. As in case of fonts we will change label on the left side of '''Change''' button. Since we will use standard event of this button, we can add event handler by double-clicking on it. And here's the code:

void Tutorial_6Frame::OnButton4Click(wxCommandEvent& event)
{
wxColour OldColour = StaticText3->GetForegroundColour();
wxColour NewColour = wxGetColourFromUser(this,OldColour);

if ( NewColour.IsOk() )
{
StaticText3->SetForegroundColour(NewColour);
}
}

At the beginning we read current colour to variable '''OldColour'''. In next lie we call '''wxGetColourFromUser''' function which opens dialog where we can choose colour.

The '''NewColour.IsOk()''' call is required because if user cancels colour selection it will return false.

At the end we set new colour by using '''SetForegroundColour''' function.

Header file to include in the tut....main.h file: '''#include <wx/colordlg.h>'''

= More informations =

We reached end of this tutorial. I showed only few operations on items and there's much more you can do. For more details you can check wxWidgets' documentation available [http://www.wxwidgets.org/manuals/stable/wx_contents.html here].

WxSmith tutorial: Using wxPanel resources

2010-12-02T16:50:40Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside a frame or dialog. We can use the main resource created inside the wizard. Assuming that you've read the previous tutorials, creating a simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding the wxPanel using a "Custom" item ==

In this tutorial I'll show you two methods of embedding an external wxPanel inside another resource.
The first one uses a "Custom" item which can be used to add any kind of resource not known to wxSmith.

So let's create the wxPanel resource. Note that using this embedding method will affect the initial configuration of the resource.
We want the id, size and position of our panel to be controlled by the parent resource so make sure that we add them into the panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into the panel:

[[Image:wxs_tut05_003.png]]

The final step is to add a "Custom" item into the main window and configure it properly. The custom icon is the last one in the "Standard palette" identified by this icon:

[[Image:wxs_tut05_004.png]]

A new item will be shown as a black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust the custom item's properties.

The first thing we will adjust is the "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds the code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into the creating code:
* $(THIS) is replaced by the name of the variable for this item
* $(CLASS) is replaced by the name of the item's class
* $(PARENT) is replaced by the name of the parent item (it's granted that it will be a pointer to a class derived from wxWindow)
* $(ID) is replaced by the value of the ID property
* $(POS) is replaced by the value of the position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by the value of the size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by the style property - since custom items doesn't have a predefined set of styles, it's treated as a normal string
* $(NAME) is replaced by the generated name (which is equivalent to the string representation of the item's identifier)

The default code template creates a standard item which uses the default set of properties. Let's replace it by a value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give the name of the header file with our external resource in the "Include file" property. I've created the wxPanel with the name "InternalPanel" so the header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including a local file.

The last property to adjust is the "Class name" - we need to put the name of our panel here; in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

The second way in which an external resource may be used is through a normal wxPanel.
If you look closer, you'll find that most of the items have a property called "Class name" - this is the name of the class which will be used as the item's type. By default it contains the name of the original class in wxWidgets. Changing it will notify wxSmith that a different class will be used instead.

So to put our own panel here we can add a "normal" panel into the main resource and change the class name to the name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in the case of the "original" class.

So let's take a look at the wxWidgets documentation. Here's the declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in the case of the previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we cannot easily add default values of our custom args).

Now that our panel is ready we can add it to the main resource - let's add a "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to the name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into the sources to make our project compile. In the previous solution it was done automatically through properties. Now we don't have such a system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in the resource will remove our change). Note that we need to add it to the header file of the main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easy methods of creating complex windows from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also a nice feature request to allow adding external panels in a more natural way (just by a few clicks) which will probably make other methods obsolete. But I hope that I gave you enough information to build nice compound resources so far :)

WxSmith tutorial: Using wxPanel resources

2010-12-01T17:04:08Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside a frame or dialog. We can use the main resource created inside the wizard. Assuming that you've read the previous tutorials, creating a simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding the wxPanel using a "Custom" item ==

In this tutorial I'll show you two methods of embedding an external wxPanel inside another resource.
The first one uses a "Custom" item which can be used to add any kind of resource not known to wxSmith.

So let's create the wxPanel resource. Note that using this embedding method will affect the initial configuration of the resource.
We want the id, size and position of our panel to be controlled by the parent resource so make sure that we add them into the panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into the panel:

[[Image:wxs_tut05_003.png]]

The final step is to add a "Custom" item into the main window and configure it properly. The custom icon is the last one in the "Standard palette" identified by this icon:

[[Image:wxs_tut05_004.png]]

A new item will be shown as a black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust the custom item's properties.

The first thing we will adjust is the "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds the code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into the creating code:
* $(THIS) is replaced by the name of the variable for this item
* $(CLASS) is replaced by the name of the item's class
* $(PARENT) is replaced by the name of the parent item (it's granted that it will be a pointer to a class derived from wxWindow)
* $(ID) is replaced by the value of the ID property
* $(POS) is replaced by the value of the position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by the value of the size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by the style property - since custom items doesn't have a predefined set of styles, it's treated as a normal string
* $(NAME) is replaced by the generated name (which is equivalent to the string representation of the item's identifier)

The default code template creates a standard item which uses the default set of properties. Let's replace it by a value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give the name of the header file with our external resource in the "Include file" property. I've created the wxPanel with the name "InternalPanel" so the header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including a local file.

The last property to adjust is the "Class name" - we need to put the name of our panel here; in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

The second way in which an external resource may be used is through a normal wxPanel.
If you look closer, you'll find that most of the items have a property called "Class name" - this is the name of the class which will be used as the item's type. By default it contains the name of the original class in wxWidgets. Changing it will notify wxSmith that a different class will be used instead.

So to put our own panel here we can add a "normal" panel into the main resource and change the class name to the name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in the case of the "original" class.

So let's take a look at the wxWidgets documentation. Here's the declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in the case of the previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we cannot easily add default values of our custom args).

Now that our panel is ready we can add it to the main resource - let's add a "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to the name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into sources to make our project compile. In previous solution it was done automaticaly through properties. Now we don't have such system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in resource will remove our change). Note that we need to add it to header file of main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easiest methods of creating complex window from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also nice feature request to allow adding external panels int more natural way (just by few clicks) which will probably make other methods obsolete. But I hope that I gave you enough informations to build nice compound resources so far :)

WxSmith tutorial: Using wxPanel resources

2010-11-30T16:05:51Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside a frame or dialog. We can use the main resource created inside the wizard. Assuming that you've read the previous tutorials, creating a simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding the wxPanel using a "Custom" item ==

In this tutorial I'll show you two methods of embedding an external wxPanel inside another resource.
The first one uses a "Custom" item which can be used to add any kind of resource not known to wxSmith.

So let's create the wxPanel resource. Note that using this embedding method will affect the initial configuration of the resource.
We want the id, size and position of our panel to be controlled by the parent resource so make sure that we add them into the panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into the panel:

[[Image:wxs_tut05_003.png]]

The final step is to add a "Custom" item into the main window and configure it properly. The custom icon is the last one in the "Standard palette" identified by this icon:

[[Image:wxs_tut05_004.png]]

A new item will be shown as a black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust the custom item's properties.

The first thing we will adjust is the "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds the code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into the creating code:
* $(THIS) is replaced by the name of the variable for this item
* $(CLASS) is replaced by the name of the item's class
* $(PARENT) is replaced by the name of the parent item (it's granted that it will be a pointer to a class derived from wxWindow)
* $(ID) is replaced by the value of the ID property
* $(POS) is replaced by the value of the position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by the value of the size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by the style property - since custom items doesn't have a predefined set of styles, it's treated as a normal string
* $(NAME) is replaced by the generated name (which is equivalent to the string representation of the item's identifier)

The default code template creates a standard item which uses the default set of properties. Let's replace it by a value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give the name of the header file with our external resource in the "Include file" property. I've created the wxPanel with the name "InternalPanel" so the header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including a local file.

The last property to adjust is the "Class name" - we need to put the name of our panel here; in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

Secend way in which external resource may be used is through normal wxPanel.
If you look closer, you'll find that most of items have property called "Class name" - this is the name of class which will be used as item's type. Bu default it contains name of original class in wxWidgets. Changing it will notify that different class will be used instead.

So to put our own panel here we can add "normal" panel into main resource and change class name to name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in case of "original" class.

So let's take a look at the wxWidgets documentation and here's declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in case of previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we can not easily add default values of our custom args).

Now that our panel is ready we can add it to main resource - let's add "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into sources to make our project compile. In previous solution it was done automaticaly through properties. Now we don't have such system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in resource will remove our change). Note that we need to add it to header file of main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easiest methods of creating complex window from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also nice feature request to allow adding external panels int more natural way (just by few clicks) which will probably make other methods obsolete. But I hope that I gave you enough informations to build nice compound resources so far :)

WxSmith tutorial: Using wxPanel resources

2010-11-29T19:11:57Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside a frame or dialog. We can use the main resource created inside the wizard. Assuming that you've read the previous tutorials, creating a simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding the wxPanel using a "Custom" item ==

In this tutorial I'll show you two methods of embedding an external wxPanel inside another resource.
The first one uses a "Custom" item which can be used to add any kind of resource not known to wxSmith.

So let's create the wxPanel resource. Note that using this embedding method will affect the initial configuration of the resource.
We want the id, size and position of our panel to be controlled by the parent resource so make sure that we add them into the panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into the panel:

[[Image:wxs_tut05_003.png]]

The final step is to add a "Custom" item into the main window and configure it properly. The custom icon is the last one in the "Standard palette" identified by this icon:

[[Image:wxs_tut05_004.png]]

A new item will be shown as a black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust the custom item's properties.

The first thing we will adjust is the "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds the code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into ceating code:
* $(THIS) is replaced by name of variable for this item
* $(CLASS) is replaced by name of item's class
* $(PARENT) is replaced by name of parent item (it's granted that it will be a pointer to class derived from wxWindow)
* $(ID) is replaced by value of Id property
* $(POS) is replaced by value of position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by value of size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by style property - since custom item doesn't have predefined set of styles, it's threated as normal string
* $(NAME) is replaced by generated name (which is equivalent to string representation of item's identifier)

The default code template creates standard item which uses default set of properties. Let's replace it by value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give name of header file with our external resource in the "Include file" property. I've created wxPanel with name "InterlanPanel" so header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including local file.

The last property to adjust is the "Class name" - we need to put name of our panel here, in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

Secend way in which external resource may be used is through normal wxPanel.
If you look closer, you'll find that most of items have property called "Class name" - this is the name of class which will be used as item's type. Bu default it contains name of original class in wxWidgets. Changing it will notify that different class will be used instead.

So to put our own panel here we can add "normal" panel into main resource and change class name to name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in case of "original" class.

So let's take a look at the wxWidgets documentation and here's declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in case of previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we can not easily add default values of our custom args).

Now that our panel is ready we can add it to main resource - let's add "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into sources to make our project compile. In previous solution it was done automaticaly through properties. Now we don't have such system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in resource will remove our change). Note that we need to add it to header file of main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easiest methods of creating complex window from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also nice feature request to allow adding external panels int more natural way (just by few clicks) which will probably make other methods obsolete. But I hope that I gave you enough informations to build nice compound resources so far :)

WxSmith tutorial: Using wxPanel resources

2010-11-29T18:43:26Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside a frame or dialog. We can use the main resource created inside the wizard. Assuming that you've read the previous tutorials, creating a simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding wxPanel using "Custom" item ==

In this tutorial I'll show you two methds of embedding external wxPanel inside another resource.
First one use "Custom" item which can be used to any kind of resource not know to wxSmith.

So let's create wxPanel resource. Note that used embedding method will affect initial configuration of resource.
We want id, size and position of our panel to be controlled by parent resource so make sure that we add them into panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into panel:

[[Image:wxs_tut05_003.png]]

Final step is to add "Custom" item into main window and configure it properly. Custom icon is the last one in the "Standard palete" identified by this icon:

[[Image:wxs_tut05_004.png]]

New item will be shown as black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust custom item's properties.

First thing we will adjust is "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into ceating code:
* $(THIS) is replaced by name of variable for this item
* $(CLASS) is replaced by name of item's class
* $(PARENT) is replaced by name of parent item (it's granted that it will be a pointer to class derived from wxWindow)
* $(ID) is replaced by value of Id property
* $(POS) is replaced by value of position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by value of size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by style property - since custom item doesn't have predefined set of styles, it's threated as normal string
* $(NAME) is replaced by generated name (which is equivalent to string representation of item's identifier)

The default code template creates standard item which uses default set of properties. Let's replace it by value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give name of header file with our external resource in the "Include file" property. I've created wxPanel with name "InterlanPanel" so header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including local file.

The last property to adjust is the "Class name" - we need to put name of our panel here, in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

Secend way in which external resource may be used is through normal wxPanel.
If you look closer, you'll find that most of items have property called "Class name" - this is the name of class which will be used as item's type. Bu default it contains name of original class in wxWidgets. Changing it will notify that different class will be used instead.

So to put our own panel here we can add "normal" panel into main resource and change class name to name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in case of "original" class.

So let's take a look at the wxWidgets documentation and here's declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in case of previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we can not easily add default values of our custom args).

Now that our panel is ready we can add it to main resource - let's add "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into sources to make our project compile. In previous solution it was done automaticaly through properties. Now we don't have such system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in resource will remove our change). Note that we need to add it to header file of main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easiest methods of creating complex window from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also nice feature request to allow adding external panels int more natural way (just by few clicks) which will probably make other methods obsolete. But I hope that I gave you enough informations to build nice compound resources so far :)

WxSmith tutorial: Using wxPanel resources

2010-11-28T19:00:45Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Using wxPanel resources =

In some cases, one resource must be split into a few smaller parts. Such a split gives a few advantages: it helps with multiple people working on the same project, it may give you a cleaner view over really complex resources and it may help to divide source code for logical parts in case of several functionalities in one window. In this tutorial I'll show you how to create such resources.

== Creating our playground ==

wxPanel resources can not live as independent items - they must be placed inside frame or dialog. We can use main resource created inside wizard. Assuming that you've read previous tutorials, creating simple window shouldn't be a big problem for you :).

Let's start with something like this:

[[Image:wxs_tut05_001.png]]

== Adding wxPanel using "Custom" item ==

In this tutorial I'll show you two methds of embedding external wxPanel inside another resource.
First one use "Custom" item which can be used to any kind of resource not know to wxSmith.

So let's create wxPanel resource. Note that used embedding method will affect initial configuration of resource.
We want id, size and position of our panel to be controlled by parent resource so make sure that we add them into panel's constructor:

[[Image:wxs_tut05_002.png]]

Now let's add some content into panel:

[[Image:wxs_tut05_003.png]]

Final step is to add "Custom" item into main window and configure it properly. Custom icon is the last one in the "Standard palete" identified by this icon:

[[Image:wxs_tut05_004.png]]

New item will be shown as black square with three question marks on the top. Let's resize it a little bit:

[[Image:wxs_tut05_005.png]]

Now we need to adjust custom item's properties.

First thing we will adjust is "Creating code" property. As the name says, here we will be able to adjust the way wxSmith adds code responsible for creating this item. The default value is:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE),$(STYLE),wxDefaultValidator,$(NAME));

You may find that there are some macros used. They are here to help you map other properties of this item into ceating code:
* $(THIS) is replaced by name of variable for this item
* $(CLASS) is replaced by name of item's class
* $(PARENT) is replaced by name of parent item (it's granted that it will be a pointer to class derived from wxWindow)
* $(ID) is replaced by value of Id property
* $(POS) is replaced by value of position property (it may be adjusted by using drag boxes)
* $(SIZE) is replaced by value of size property (it may be adjusted by using drag boxes)
* $(STYLE) is replaced by style property - since custom item doesn't have predefined set of styles, it's threated as normal string
* $(NAME) is replaced by generated name (which is equivalent to string representation of item's identifier)

The default code template creates standard item which uses default set of properties. Let's replace it by value corresponding to our panel's constructor:

$(THIS) = new $(CLASS)($(PARENT),$(ID),$(POS),$(SIZE));

Now we have to give name of header file with our external resource in the "Include file" property. I've created wxPanel with name "InterlanPanel" so header will be "InternalPanel.h". Also let's check the "Use "" for include..." since we're including local file.

The last property to adjust is the "Class name" - we need to put name of our panel here, in my case it's "InternalPanel". When we do this, our embedded resource is ready:

[[Image:wxs_tut05_006.png]]

== Adding custom panel through standard wxPanel ==

Secend way in which external resource may be used is through normal wxPanel.
If you look closer, you'll find that most of items have property called "Class name" - this is the name of class which will be used as item's type. Bu default it contains name of original class in wxWidgets. Changing it will notify that different class will be used instead.

So to put our own panel here we can add "normal" panel into main resource and change class name to name of our internal resource. So far it's easy but there's one requirement to this technique - our internal resource must have exactly the same constructor arguments as in case of "original" class.

So let's take a look at the wxWidgets documentation and here's declaration of wxPanel's constructor:

wxPanel( wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
long style = wxTAB_TRAVERSAL, const wxString& name = "panel")

Now let's create our own internal resource. We will have to adjust constructor arguments as in case of previous method:

[[Image:wxs_tut05_007.png]]

Note that I've added custom arguments and turned off all default values (it's required since we can not easily add default values of our custom args).

Now that our panel is ready we can add it to main resource - let's add "normal" panel first:

[[Image:wxs_tut05_008.png]]

and change "Class name" property to name of our resource (in my case it's InternalResource2).

We still need to add #include "InternalResource2.h" into sources to make our project compile. In previous solution it was done automaticaly through properties. Now we don't have such system so let's add it manually (remember to put our include outside wxSmith's code section, otherwise any change in resource will remove our change). Note that we need to add it to header file of main resource:

//(*Headers(Tutorial5Dialog)
#include <wx/sizer.h>
#include <wx/panel.h>
#include "InternalPanel.h"
#include <wx/dialog.h>
//*)
'''#include "InternalResource2.h"'''

Now we can run our application:

[[Image:wxs_tut05_009.png]]

I've presented two easiest methods of creating complex window from smaller resources. Perhaps you could find other ways to do it (if you do so, you can extend this tutorial :) ). On wxSmith's wishlist there's also nice feature request to allow adding external panels int more natural way (just by few clicks) which will probably make other methods obsolete. But I hope that I gave you enough informations to build nice compound resources so far :)

WxSmith tutorial: Working with multiple resources

2010-11-28T18:53:57Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_001.png]]

Here we can configure the following parameters:

* Class name - it's the name of the class which will be generated for the resource. It will also be the name of a resource
* Header file - name of the header file with the class declaration
* Source file - name of the source file with the class definition
* Xrc file - if you check this option you can enter the name of an XRC file which will contain the XRC's structure (XRC files will be covered in another tutorial)
* Add XRC file to autoload list - this option is available only with XRC files and notifies wxSmith that it should automatically load the XRC file when the application starts.

Now let's change the name of the resource to something better like "FirstDialog". Note that if you change the class name, the names of the files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for a list of build target into which the new resource will be added. Select both debug and release and we can continue.

A new dialog is automatically opened in the editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add a wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using a dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such a dialog is shown, all other windows in the application are frozen until the dialog finishes its job. Such dialogs are useful when the user should quickly provide some information - for example the window used to configure a new resource was modal.

Now let's try to invoke our dialog. Generally such dialogs will pop-up in reaction to user action like choosing a menu option or clicking on a button. We will use the button since this approach is really easy.

Ok, let's switch into the main frame - the one that was opened right after creating the new project, and add a sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create an action for the button-click event. The easiest way is to double-click the button in the editor. wxSmith will automatically add a new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of the cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created the dialog's object notifying that ''this'' window (main frame) is the parent of dialog. In the second line we show the dialog. Note that the call to ShowModal() blocks until the dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add the following code next to the other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is a block of code that is automatically generated by wxSmith. Every block starts with a ''//(*BlockName'' comment and ends with a ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost next time you change something in the editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click the button on the main window, the dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using modeless dialog and frame windows =

Another way to show a window is as a modeless window. In such cases the new window does not block other windows in the application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as its object (the instance of the resource's c++ class). So we cannot use the same approach as in the case of a modal dialog. In modal mode an object was created as a local variable of the event handler. We could do this only because the ShowModal method was blocking as long as the dialog was shown.
Now we will have to create objects using the new operator because the objects must exist after leaving the handler function and also because windows not using modal mode will delete such objects automatically when the window is closed.

To allow creating the FirstFrame class we should add '''#include "FirstFrame.h"''' into the list of includes just like in the case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to the main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add a handler to the ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click the ''Add new dialog'' or ''Add new frame'' button, a new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-28T18:51:15Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_001.png]]

Here we can configure the following parameters:

* Class name - it's the name of the class which will be generated for the resource. It will also be the name of a resource
* Header file - name of the header file with the class declaration
* Source file - name of the source file with the class definition
* Xrc file - if you check this option you can enter the name of an XRC file which will contain the XRC's structure (XRC files will be covered in another tutorial)
* Add XRC file to autoload list - this option is available only with XRC files and notifies wxSmith that it should automatically load the XRC file when the application starts.

Now let's change the name of the resource to something better like "FirstDialog". Note that if you change the class name, the names of the files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for a list of build target into which the new resource will be added. Select both debug and release and we can continue.

A new dialog is automatically opened in the editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add a wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using a dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such a dialog is shown, all other windows in the application are frozen until the dialog finishes its job. Such dialogs are useful when the user should quickly provide some information - for example the window used to configure a new resource was modal.

Now let's try to invoke our dialog. Generally such dialogs will pop-up in reaction to user action like choosing a menu option or clicking on a button. We will use the button since this approach is really easy.

Ok, let's switch into the main frame - the one that was opened right after creating the new project, and add a sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create an action for the button-click event. The easiest way is to double-click the button in the editor. wxSmith will automatically add a new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of the cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created the dialog's object notifying that ''this'' window (main frame) is the parent of dialog. In the second line we show the dialog. Note that the call to ShowModal() blocks until the dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add the following code next to the other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is a block of code that is automatically generated by wxSmith. Every block starts with a ''//(*BlockName'' comment and ends with a ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost next time you change something in the editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click the button on the main window, the dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using modeless dialog and frame windows =

Another way to show windows is as a modeless window. In such cases the new window does not block other windows in the application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as its object (the instance of the resource's c++ class). So we cannot use the same approach as in the case of a modal dialog. In modal mode an object was created as a local variable of the event handler. We could do this only because the ShowModal method was blocking as long as the dialog was shown.
Now we will have to create objects using the new operator because the objects must exist after leaving the handler function and also because windows not using modal mode will delete such objects automatically when the window is closed.

To allow creating the FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in the case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to the main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add a handler to the ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click the ''Add new dialog'' or ''Add new frame'' button, a new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-27T20:00:58Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_001.png]]

Here we can configure the following parameters:

* Class name - it's the name of the class which will be generated for the resource. It will also be the name of a resource
* Header file - name of the header file with the class declaration
* Source file - name of the source file with the class definition
* Xrc file - if you check this option you can enter the name of an XRC file which will contain the XRC's structure (XRC files will be covered in another tutorial)
* Add XRC file to autoload list - this option is available only with XRC files and notifies wxSmith that it should automatically load the XRC file when the application starts.

Now let's change the name of the resource to something better like "FirstDialog". Note that if you change the class name, the names of the files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for a list of build target into which the new resource will be added. Select both debug and release and we can continue.

A new dialog is automatically opened in the editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add a wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using a dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such a dialog is shown, all other windows in the application are frozen until the dialog finishes its job. Such dialogs are useful when the user should quickly provide some information - for example the window used to configure a new resource was modal.

Now let's try to invoke our dialog. Generally such dialogs will pop-up in reaction to user action like choosing a menu option or clicking on a button. We will use the button since this approach is really easy.

Ok, let's switch into the main frame - the one that was opened right after creating the new project, and add a sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create an action for the button-click event. The easiest way is to double-click the button in the editor. wxSmith will automatically add a new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of the cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created the dialog's object notifying that ''this'' window (main frame) is the parent of dialog. In the second line we show the dialog. Note that the call to ShowModal() blocks until the dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add the following code next to the other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is a block of code that is automatically generated by wxSmith. Every block starts with a ''//(*BlockName'' comment and ends with a ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost next time you change something in the editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click the button on the main window, the dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-27T19:51:43Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_001.png]]

Here we can configure the following parameters:

* Class name - it's the name of the class which will be generated for the resource. It will also be the name of a resource
* Header file - name of the header file with the class declaration
* Source file - name of the source file with the class definition
* Xrc file - if you check this option you can enter the name of an XRC file which will contain the XRC's structure (XRC files will be covered in another tutorial)
* Add XRC file to autoload list - this option is available only with XRC files and notifies wxSmith that it should automatically load the XRC file when the application starts.

Now let's change the name of the resource to something better like "FirstDialog". Note that if you change the class name, the names of the files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for a list of build target into which the new resource will be added. Select both debug and release and we can continue.

A new dialog is automatically opened in the editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add a wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such dialog is shown, all other windows in the application are frozen as long as the dialog finishes it's job. Such dialogs are usefull when user should quickly provide some informations - for example the window used to configure new resource was modal.

Now let's try to invoke our dialog. Generally such dialog will pop-up as reaction for user action like choosing menu option or clicking on button. We will use he button since this approach is really easy.

Ok, let's switch into main frame - the one that was opened right after creating new project, and add sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create action for button-click event. The easiest way is to double-click the button in editor. wxSmith will automatically add new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created dialog's object notifying that ''this'' window (main frame) is parent of dialog. In the second line we show the dialog. Note that call to ShowModal() blocks untill dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add following code next to other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is block of code that is automatically generated by wxSmith. Every block starts with ''//(*BlockName'' comment and ends with ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost net time you change something in editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click button on main window, dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-26T15:55:25Z

Greenbreen: Changed image to imputed intended image

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_001.png]]

Here we can configure following parameters:

* Class name - it's name of class which will be generated for the resource. It will also be a name of resource
* Header file - name of header file with class declaration
* Source file - name of source file with class definition
* Xrc file - if you check this option you can enter name of XRC file which will contain XRC's structure (XRC files will be covered in other tutorial)
* Add XRC file to autoload list - this option is aailable only with XRC file and notifies wxSmith that it should automatically load XRC file when the application starts.

Now let's change name of resource to something better like "FirstDialog". Note that if you change class name, names of files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for list of build target into which new resource will be added. Select both debug and release and we can continue.

New dialog is automatically opened in editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add some wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such dialog is shown, all other windows in the application are frozen as long as the dialog finishes it's job. Such dialogs are usefull when user should quickly provide some informations - for example the window used to configure new resource was modal.

Now let's try to invoke our dialog. Generally such dialog will pop-up as reaction for user action like choosing menu option or clicking on button. We will use he button since this approach is really easy.

Ok, let's switch into main frame - the one that was opened right after creating new project, and add sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create action for button-click event. The easiest way is to double-click the button in editor. wxSmith will automatically add new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created dialog's object notifying that ''this'' window (main frame) is parent of dialog. In the second line we show the dialog. Note that call to ShowModal() blocks untill dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add following code next to other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is block of code that is automatically generated by wxSmith. Every block starts with ''//(*BlockName'' comment and ends with ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost net time you change something in editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click button on main window, dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-26T15:49:47Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding a few dialogs =

New resources can be added from the '''wxSmith''' menu. You can find the following options there:

* '''Add wxPanel''' - this will add a new panel into the resource
* '''Add wxDialog''' - this adds a new dialog window
* '''Add wxFrame''' - this adds a new frame window.

Ok, let's add a new wxDialog. If you choose this option it will show the following window:

[[Image:wxs_tut04_005.png]]

Here we can configure following parameters:

* Class name - it's name of class which will be generated for the resource. It will also be a name of resource
* Header file - name of header file with class declaration
* Source file - name of source file with class definition
* Xrc file - if you check this option you can enter name of XRC file which will contain XRC's structure (XRC files will be covered in other tutorial)
* Add XRC file to autoload list - this option is aailable only with XRC file and notifies wxSmith that it should automatically load XRC file when the application starts.

Now let's change name of resource to something better like "FirstDialog". Note that if you change class name, names of files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for list of build target into which new resource will be added. Select both debug and release and we can continue.

New dialog is automatically opened in editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add some wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such dialog is shown, all other windows in the application are frozen as long as the dialog finishes it's job. Such dialogs are usefull when user should quickly provide some informations - for example the window used to configure new resource was modal.

Now let's try to invoke our dialog. Generally such dialog will pop-up as reaction for user action like choosing menu option or clicking on button. We will use he button since this approach is really easy.

Ok, let's switch into main frame - the one that was opened right after creating new project, and add sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create action for button-click event. The easiest way is to double-click the button in editor. wxSmith will automatically add new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created dialog's object notifying that ''this'' window (main frame) is parent of dialog. In the second line we show the dialog. Note that call to ShowModal() blocks untill dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add following code next to other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is block of code that is automatically generated by wxSmith. Every block starts with ''//(*BlockName'' comment and ends with ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost net time you change something in editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click button on main window, dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-26T15:43:36Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with an empty project. You can find information on how to do this in the first tutorial. Remember to create a frame-based application and select wxSmith as the main RAD designer. Also let's name the project "Tutorial 4".

If the empty application compiles and runs fine, we can advance to the next step.

= Adding few dialogs =

New resources can be added from '''wxSmith''' menu. You can find following options there:

* '''Add wxPanel''' - this will add new panel into resource
* '''Add wxDialog''' - this adds new dialog window
* '''Add wxFrame''' - this adds new frame window.

Ok, let's add new wxDialog. If you choose this option it will show following window:

[[Image:wxs_tut04_005.png]]

Here we can configure following parameters:

* Class name - it's name of class which will be generated for the resource. It will also be a name of resource
* Header file - name of header file with class declaration
* Source file - name of source file with class definition
* Xrc file - if you check this option you can enter name of XRC file which will contain XRC's structure (XRC files will be covered in other tutorial)
* Add XRC file to autoload list - this option is aailable only with XRC file and notifies wxSmith that it should automatically load XRC file when the application starts.

Now let's change name of resource to something better like "FirstDialog". Note that if you change class name, names of files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for list of build target into which new resource will be added. Select both debug and release and we can continue.

New dialog is automatically opened in editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add some wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such dialog is shown, all other windows in the application are frozen as long as the dialog finishes it's job. Such dialogs are usefull when user should quickly provide some informations - for example the window used to configure new resource was modal.

Now let's try to invoke our dialog. Generally such dialog will pop-up as reaction for user action like choosing menu option or clicking on button. We will use he button since this approach is really easy.

Ok, let's switch into main frame - the one that was opened right after creating new project, and add sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create action for button-click event. The easiest way is to double-click the button in editor. wxSmith will automatically add new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created dialog's object notifying that ''this'' window (main frame) is parent of dialog. In the second line we show the dialog. Note that call to ShowModal() blocks untill dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add following code next to other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is block of code that is automatically generated by wxSmith. Every block starts with ''//(*BlockName'' comment and ends with ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost net time you change something in editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click button on main window, dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Working with multiple resources

2010-11-26T15:33:00Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with multiple resources =

Hello. In this tutorial I'll show you how to create an application with more than one window. I'll also show how to invoke one window from another. At the end we will learn how to change the main window in project settings.

So let's start.

= Creating empty project =

As usual we will start with empty project. You can find informations on how to do this in the first tutorial. Remember to crate frame-based application and select wxSmith as main RAD designer. Also let's name the project "Tutorial 4".

If empty application compiles and runs fine we can advance to next step.

= Adding few dialogs =

New resources can be added from '''wxSmith''' menu. You can find following options there:

* '''Add wxPanel''' - this will add new panel into resource
* '''Add wxDialog''' - this adds new dialog window
* '''Add wxFrame''' - this adds new frame window.

Ok, let's add new wxDialog. If you choose this option it will show following window:

[[Image:wxs_tut04_005.png]]

Here we can configure following parameters:

* Class name - it's name of class which will be generated for the resource. It will also be a name of resource
* Header file - name of header file with class declaration
* Source file - name of source file with class definition
* Xrc file - if you check this option you can enter name of XRC file which will contain XRC's structure (XRC files will be covered in other tutorial)
* Add XRC file to autoload list - this option is aailable only with XRC file and notifies wxSmith that it should automatically load XRC file when the application starts.

Now let's change name of resource to something better like "FirstDialog". Note that if you change class name, names of files are also updated (they are updated as long as you don't change them manually). After clicking OK you will be prompted for list of build target into which new resource will be added. Select both debug and release and we can continue.

New dialog is automatically opened in editor. Let's add some simple content:

[[Image:wxs_tut04_002.png]]

Now let's add some wxFrame resource (FirstFrame) and add some content into it:

[[Image:wxs_tut04_003.png]]

= Using dialog window in modal mode =

Dialogs can be shown in so-called modal mode. This means that when such dialog is shown, all other windows in the application are frozen as long as the dialog finishes it's job. Such dialogs are usefull when user should quickly provide some informations - for example the window used to configure new resource was modal.

Now let's try to invoke our dialog. Generally such dialog will pop-up as reaction for user action like choosing menu option or clicking on button. We will use he button since this approach is really easy.

Ok, let's switch into main frame - the one that was opened right after creating new project, and add sizer and button:

[[Image:wxs_tut04_004.png]]

Now we have to create action for button-click event. The easiest way is to double-click the button in editor. wxSmith will automatically add new event handler function:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
}

If you can't find this code, scroll down to the end of cpp file.

Now let's Invoke our dialog:

void Tutorial_4Frame::OnButton1Click(wxCommandEvent& event)
{
FirstDialog dialog(this);
dialog.ShowModal();
}

In the first added line we created dialog's object notifying that ''this'' window (main frame) is parent of dialog. In the second line we show the dialog. Note that call to ShowModal() blocks untill dialog is closed.

There's one more thing we need to add before our application compiles. Jump to the beginning of the file and add following code next to other includes:

#include "FirstDialog.h"

Note that you shouldn't add it inside code which looks like this:

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

This is block of code that is automatically generated by wxSmith. Every block starts with ''//(*BlockName'' comment and ends with ''//*)''. You may find other blocks in both header and source files. If you change their content, all changes will be lost net time you change something in editor.

To sum things up, headers section should look like this:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now we can compile and run our application- if you click button on main window, dialog will pop-up:

[[Image:wxs_tut04_005.png]]

= Using dialog and frame window in non-modal mode =

Another mode used to show windows is modal-less mode. In such case new window does not block other windows in application and two (or more) windows can cooperate in one application.

Before we add new code into our application there's one more thing you should know. Each window may exist only as long as it's object (instance of resource's c++ class). So we can not use same approach as in case of modal dialog. In modal mode object was created as local variable of event handler. We could do this only because ShowModal method was blocked as long as diaog was shown.
Now we will have to create objets using new opertor because objects must exist after leaving handler functin and also because windows not using modal mode will delete such objects automatically when window is closed.

To allow creating FirstFrame class we should add '''#include "FirstFrame.h"''' into list of includes just like in case of FirstDialog:

#include "wx_pch.h"
#include "Tutorial_4Main.h"
#include <wx/msgdlg.h>
#include "FirstDialog.h"
#include "FirstFrame.h"

//(*InternalHeaders(Tutorial_4Frame)
#include <wx/intl.h>
#include <wx/string.h>
//*)

Now let's add two more buttons to main frame:
* Add new dialog
* Add new frame

We can also name the first button to show what it does:

[[Image:wxs_tut04_006.png]]

Now let's add handler to ''Add new dialog'' button:

void Tutorial_4Frame::OnButton2Click(wxCommandEvent& event)
{
FirstDialog* dlg = new FirstDialog(this);
dlg->Show();
}

Analogically we can write the code for firstFrame:

void Tutorial_4Frame::OnButton3Click(wxCommandEvent& event)
{
FirstFrame* frm = new FirstFrame(this);
frm->Show();
}

Now each time we click ''Add new dialog'' or ''Add new frame'' buton, new window shows up.

This is the end of this tutorial. I hope that you learned some new useful things. In the next tutorial I'll show how to use the last type of resources, wxPanel, inside other resources.

See you.

WxSmith tutorial: Building more complex window

2010-11-26T15:29:37Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have a description of the CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such a list we would need some type of grid sizer. Ok, but the region has a wxStaticBoxSizer which aligns items only in one line. To overcome this limitation we can just add another sizer into the wxStaticBoxSizer and use the new one as the grid. From the two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because the row with descriptions may need some more space than the others). So let's add the new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check the '''Expand''' property of the new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - the first for the label and the second for the value, so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding the items we should have the following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's an alternative for wxDatePickerCtrl - wxCalendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove the wrong item (by using the 'delete' key or by pressing the 'X' button on the right side of the editor). After the change we can see that the generated calendar is quite large compared to the other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set the '''wxSUNKEN_BORDER''' style to add some nice border around the calendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have a few things to do now:
* First is to check the '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in the '''CD details''' region
* Third is to check the '''Expand''' property for all items with values in that region
* Fourth is to adjust items used to edit values in '''CD details''' region

The first three tasks are quite easy and I'll leave them to you :)

The fourth task will require a few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying the '''Text''' property so you should do this very quickly.

Now we have to set some values which could be chosen from the '''Type''' value. It's done by editing the '''Choices''' property of wxChoice. This is a more advanced value consisting of a few strings, and entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, a new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how the window resizes ==

We have the first version of our window. But it's not the end of our work. If we want it to be user-friendly, it should give the ability to resize. We can check it by either showing the preview or building and running the application. The latter is preferred since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* The regions did not expand vertically and stay centered
* The content of the second region did not react for the resize

The first problem should be caused by some missing '''Expand''' property so let's find it.

First we should check if the regions have the '''Expand''' property set: yes they do so this is not the problem. Generally in such situations we should continue checking in the parent item - this is wxBoxSizer which always expands. Next there's wxPanel, which we used to make a nice background, and voila: this one is missing the '''Expand''' property. So let's check it and test the result again - it works fine.

Now the second issue. Content inside the '''CD details''' pane was based on wxFlexGridSizer. If you look into the previous tutorial you may find out that this sizer has a special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, do we? ;) ) so let's set '''Growable cols''' to '''"1"''' (indexes are 0-based). Note that you may quickly find the wxFlexGridSizer by looking into the resource tree - we have only one such sizer in our project.

Now we have a more correct result:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left a few things in the first region. The buttons don't have new labels, and there's to much space between them and the list, so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels, so if we remove the border around buttons we would have more free space. But then the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to a few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove the top/bottom/left edge borders of the first button and the top/bottom/right edge borders of the second button we would remove the extra space but the buttons will still have some gap between them. Here's how the property should look for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-26T15:19:06Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have a description of the CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such a list we would need some type of grid sizer. Ok, but the region has a wxStaticBoxSizer which aligns items only in one line. To overcome this limitation we can just add another sizer into the wxStaticBoxSizer and use the new one as the grid. From the two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because the row with descriptions may need some more space than the others). So let's add the new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check the '''Expand''' property of the new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - the first for the label and the second for the value, so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding the items we should have the following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's an alternative for wxDatePickerCtrl - wxCalendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove the wrong item (by using the 'delete' key or by pressing the 'X' button on the right side of the editor). After the change we can see that the generated calendar is quite large compared to the other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set the '''wxSUNKEN_BORDER''' style to add some nice border around the calendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have a few things to do now:
* First is to check the '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in the '''CD details''' region
* Third is to check the '''Expand''' property for all items with values in that region
* Fourth is to adjust items used to edit values in '''CD details''' region

The first three tasks are quite easy and I'll leave them to you :)

The fourth task will require a few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying the '''Text''' property so you should do this very quickly.

Now we have to set some values which could be chosen from the '''Type''' value. It's done by editing the '''Choices''' property of wxChoice. This is a more advanced value consisting of a few strings, and entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, a new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how the window resizes ==

We have the first version of our window. But it's not the end of our work. If we want it to be user-friendly, it should give the ability to resize. We can check it by either showing the preview or building and running the application. The latter is preferred since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* The regions did not expand vertically and stay centered
* The content of the second region did not react for the resize

The first problem should be caused by some missing '''Expand''' property so let's find it.

First we should check if the regions have the '''Expand''' property set: yes they do so this is not the problem. Generally in such situations we should continue checking in the parent item - this is wxBoxSizer which always expands. Next there's wxPanel, which we used to make a nice background, and voila: this one is missing the '''Expand''' property. So let's check it and test the result again - it works fine.

Now the second issue. Content inside the '''CD details''' pane was based on wxFlexGridSizer. If you look into the previous tutorial you may find out that this sizer has a special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, do we? ;) ) so let's set '''Growable cols''' to '''"1"''' (indexes are 0-based). Note that you may quickly find the wxFlexGridSizer by looking into the resource tree - we have only one such sizer in our project.

Now we have a more correct result:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-25T20:01:48Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have a description of the CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such a list we would need some type of grid sizer. Ok, but the region has a wxStaticBoxSizer which aligns items only in one line. To overcome this limitation we can just add another sizer into the wxStaticBoxSizer and use the new one as the grid. From the two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because the row with descriptions may need some more space than the others). So let's add the new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check the '''Expand''' property of the new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - the first for the label and the second for the value, so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding the items we should have the following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's an alternative for wxDatePickerCtrl - wxCalendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove the wrong item (by using the 'delete' key or by pressing the 'X' button on the right side of the editor). After the change we can see that the generated calendar is quite large compared to the other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set the '''wxSUNKEN_BORDER''' style to add some nice border around the calendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have a few things to do now:
* First is to check the '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in the '''CD details''' region
* Third is to check the '''Expand''' property for all items with values in that region
* Fourth is to adjust items used to edit values in '''CD details''' region

The first three tasks are quite easy and I'll leave them to you :)

The fourth task will require a few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying the '''Text''' property so you should do this very quickly.

Now we have to set some values which could be chosen from the '''Type''' value. It's done by editing the '''Choices''' property of wxChoice. This is a more advanced value consisting of a few strings, and entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, a new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how the window resizes ==

We have the first version of our window. But it's not the end of our work. If we want it to be user-friendly, it should give the ability to resize. We can check it by either showing the preview or building and running the application. The latter is preferred since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* The regions did not expand vertically and stay centered
* The content of the second region did not react for the resize

The first problem should be caused by some missing '''Expand''' property so let's find it.

First we should check if the regions have the '''Expand''' property set: yes they do so this is not the problem. Generally in such situations we should continue checking in the parent item - this is wxBoxSizer which always expands. Next there's wxPanel, which we used to make a nice background, and voila: this one is missing the '''Expand''' property. So let's check it and test the result again - it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-25T19:51:25Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have a description of the CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such a list we would need some type of grid sizer. Ok, but the region has a wxStaticBoxSizer which aligns items only in one line. To overcome this limitation we can just add another sizer into the wxStaticBoxSizer and use the new one as the grid. From the two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because the row with descriptions may need some more space than the others). So let's add the new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check the '''Expand''' property of the new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - the first for the label and the second for the value, so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding the items we should have the following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's an alternative for wxDatePickerCtrl - wxCalendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove the wrong item (by using the 'delete' key or by pressing the 'X' button on the right side of the editor). After the change we can see that the generated calendar is quite large compared to the other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set the '''wxSUNKEN_BORDER''' style to add some nice border around the calendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have a few things to do now:
* First is to check the '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in the '''CD details''' region
* Third is to check the '''Expand''' property for all items with values in that region
* Fourth is to adjust items used to edit values in '''CD details''' region

The first three tasks are quite easy and I'll leave them to you :)

The fourth task will require a few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying the '''Text''' property so you should do this very quickly.

Now we have to set some values which could be chosen from the '''Type''' value. It's done by editing the '''Choices''' property of wxChoice. This is a more advanced value consisting of a few strings, and entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, a new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-24T20:14:53Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have a description of the CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such a list we would need some type of grid sizer. Ok, but the region has a wxStaticBoxSizer which aligns items only in one line. To overcome this limitation we can just add another sizer into the wxStaticBoxSizer and use the new one as the grid. From the two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because the row with descriptions may need some more space than the others). So let's add the new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check the '''Expand''' property of the new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - the first for the label and the second for the value, so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding the items we should have the following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's an alternative for wxDatePickerCtrl - wxCalendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove the wrong item (by using the 'delete' key or by pressing the 'X' button on the right side of the editor). After the change we can see that the generated calendar is quite large compared to the other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set the '''wxSUNKEN_BORDER''' style to add some nice border around the calendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have few things to do now:
* First is to check '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in '''CD details''' region
* Third is to check '''Expand''' property for all items with values in same region
* Fourth thing is to adjust items used to edit values in '''CD details''' region

First three tasks are quite easy and I'll leave them to you :)

Fourth task will require few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying '''Text''' property so you should do this very quickly.

Now we have to set some values which could be choosen from '''Type''' value. It's done by editing '''Choices''' property of wxChoice. This is more advanced value consisting of few strings to entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-24T19:58:35Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we cannot point to the wxListBox item - it cannot have children so wxSmith will try to add new items before or after it. After adding the button we would have such a result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in a horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer just for the buttons. So let's add wxBoxSizer right after the list and before the button:

[[Image:wxs_tut03_009.png]]

Now let's change the '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes for the button. We said in a previous tutorial that wxBoxSizer and wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the tallest item (list of CDs) and applied this height into all managed items. How to disable it? By setting the '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify the sizer that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clicking on the button and dragging it into the sizer. After that we can add the second button next to the first one:

[[Image:wxs_tut03_012.png]]

Now we can see that the list doesn't have the '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how resource currently looks in the application. We could by simply running it (F9) or by pressing the preview button on the right part of the wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run the application you will see that there's a menu and statusbar. On the preview they won't show up; wxSmith still misses a few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have description of CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such list we would need some grid sizer. Ok, but the region has wxStaticBoxSizer which align items only in one line. To overcome this limitation we can just add another sizer into wxStaticBoxSizer and use new one as the grid. From two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because row with description may need some more space than others). So let's add new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check '''Expand''' property of new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - first for the label and second for value so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding items we should have following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's alternative for wxDatePickerCtrl - wxCallendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove wrong item (by using 'delete' key or by pressing 'X' button on the right side of the editor). After the change we can see that generated callendar is quite but according to other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set '''wxSUNKEN_BORDER''' style to add some nice border around the callendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have few things to do now:
* First is to check '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in '''CD details''' region
* Third is to check '''Expand''' property for all items with values in same region
* Fourth thing is to adjust items used to edit values in '''CD details''' region

First three tasks are quite easy and I'll leave them to you :)

Fourth task will require few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying '''Text''' property so you should do this very quickly.

Now we have to set some values which could be choosen from '''Type''' value. It's done by editing '''Choices''' property of wxChoice. This is more advanced value consisting of few strings to entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-23T19:06:26Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some items which will show a list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on its '''Expand''' flag. To do this let's click on the second sizer and check its '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change the labels of the regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have the ability to add and delete a selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we can now point wxListBox item - it can not have children so wxSmith will try to add new item before or after it. After adding button we would have such result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer used only for buttons. So let's add wxBoxSizer right after the list and before button:

[[Image:wxs_tut03_009.png]]

Now let's change '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes to button. We said in previous tutorial that wxBoxSizer an wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the highest item (list of CDs) and applied this height into all managed items. How to disable it? By setting '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clickong on the button and dragging it into the sizer. After that we can add second button next to the first one:

[[Image:wxs_tut03_012.png]]

Nowe we can see that the list don't have '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how current work does look in the application. We could simply run it (F9) or by pressing the preview button on the right part of wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run application you will see that there's menu and statusbar, on the preview it won't show, wxSmith still misses few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have description of CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such list we would need some grid sizer. Ok, but the region has wxStaticBoxSizer which align items only in one line. To overcome this limitation we can just add another sizer into wxStaticBoxSizer and use new one as the grid. From two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because row with description may need some more space than others). So let's add new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check '''Expand''' property of new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - first for the label and second for value so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding items we should have following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's alternative for wxDatePickerCtrl - wxCallendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove wrong item (by using 'delete' key or by pressing 'X' button on the right side of the editor). After the change we can see that generated callendar is quite but according to other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set '''wxSUNKEN_BORDER''' style to add some nice border around the callendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have few things to do now:
* First is to check '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in '''CD details''' region
* Third is to check '''Expand''' property for all items with values in same region
* Fourth thing is to adjust items used to edit values in '''CD details''' region

First three tasks are quite easy and I'll leave them to you :)

Fourth task will require few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying '''Text''' property so you should do this very quickly.

Now we have to set some values which could be choosen from '''Type''' value. It's done by editing '''Choices''' property of wxChoice. This is more advanced value consisting of few strings to entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-23T19:01:16Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage our two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such situations I use wxStaticBoxSizer because we can mark regions and give some name to them. So let's add two wxStaticBoxSizer-s into the window. Be careful while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like in the picture. Note that now the resource is small but it will change when we will add some items into the regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some item which will show list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on it's '''Expand''' flag. To do this let's click on the second sizer and check it's '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change labels of regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have ability to add and delete selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we can now point wxListBox item - it can not have children so wxSmith will try to add new item before or after it. After adding button we would have such result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer used only for buttons. So let's add wxBoxSizer right after the list and before button:

[[Image:wxs_tut03_009.png]]

Now let's change '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes to button. We said in previous tutorial that wxBoxSizer an wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the highest item (list of CDs) and applied this height into all managed items. How to disable it? By setting '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clickong on the button and dragging it into the sizer. After that we can add second button next to the first one:

[[Image:wxs_tut03_012.png]]

Nowe we can see that the list don't have '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how current work does look in the application. We could simply run it (F9) or by pressing the preview button on the right part of wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run application you will see that there's menu and statusbar, on the preview it won't show, wxSmith still misses few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have description of CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such list we would need some grid sizer. Ok, but the region has wxStaticBoxSizer which align items only in one line. To overcome this limitation we can just add another sizer into wxStaticBoxSizer and use new one as the grid. From two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because row with description may need some more space than others). So let's add new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check '''Expand''' property of new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - first for the label and second for value so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding items we should have following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's alternative for wxDatePickerCtrl - wxCallendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove wrong item (by using 'delete' key or by pressing 'X' button on the right side of the editor). After the change we can see that generated callendar is quite but according to other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set '''wxSUNKEN_BORDER''' style to add some nice border around the callendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have few things to do now:
* First is to check '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in '''CD details''' region
* Third is to check '''Expand''' property for all items with values in same region
* Fourth thing is to adjust items used to edit values in '''CD details''' region

First three tasks are quite easy and I'll leave them to you :)

Fourth task will require few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying '''Text''' property so you should do this very quickly.

Now we have to set some values which could be choosen from '''Type''' value. It's done by editing '''Choices''' property of wxChoice. This is more advanced value consisting of few strings to entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

WxSmith tutorial: Building more complex window

2010-11-23T18:48:42Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Building more complex window =

Hi, in this tutorial I'll show you some examples of more complex windows. Actually it would look complex when you start working with wxSmith. After writing a few applications you will probably build a few resources with this or even higher complexity so don't be scared. I'm working with wxSmith almost every day (it's really the best way to find bugs and discover nice improvements and that's what I should do as it's creator ;)) and although it may look complex at the beginning, you can quickly get comfortable with it.

I also want you to know that as I'm writing the beginning of this tutorial, I'm also beginning to write the application - I didn't prepare a ready solution since I would like to show the process of creating a window in natural way (maybe even with some mistakes), so while writing the tutorial I'll also create the application.

We will start with an empty frame - if you've read the previous tutorials you should create one without problems.

== First task - some basic concepts ==

My proposition for an example application would be something to manage a colleciton of CD-roms. So at the beginning we should realize what should be presented at the main window. Let's say that we would have most of the information in the main window (although it may not be a very good assumption, it would help to show the creation of more complex resources).

I would like to have some list of CD-roms on the left and some details of the selected CD-rom on the right. So basically we have two regions in our window: one with the list and one with the details. I'd like also to use sizers because the application should be cross-platform and the main window should be resizable.

== Building skeleton ==

If want the application to look nice on both windows and linux, we should do some tricks presented in the first tutorial - we had to add an extra wxPanel into the frame to make the background better. Let's to the same thing here:

* First add wxBoxSizer directly into the resource
* Add wxPanel into that sizer
* Set size of border to 0 to make the panel cover entire window

Now we should have this result:

[[Image:wxs_tut03_001.png]]

Now let's add wxBoxSizer into it - this sizer will manage out two main regions. After that the tree structure should look like this:

[[Image:wxs_tut03_002.png]]

Now we can start filling those two regions - each one may have only one item (so the sizer we've just added will manage them). Usually in such sutiatuion I use wxStaticBoxSizer because we can mark regions and put some name for them. So let's add two wxStaticBoxSizer-s into the window. Be carefull while adding the second one because you may add it into the first region - always remember that parent for new items is always the item totally covered with blue:

[[Image:wxs_tut03_003.png]]

To add second sizer properly you must click on the border surrounding the first one just like on the picture. Note that now the resource is small but it will change when we will add some items into regions.

== Building the '''List of CDs''' region ==

Ok, now let's add some item which will show list of CDs. We can use wxListBox here:

[[Image:wxs_tut03_004.png]]

The list is rather small so let's resize it using drag-boxes to something bigger and higher:

[[Image:wxs_tut03_005.png]]

Ok, but the second sizer did not resize. That's right since we didn't turn on it's '''Expand''' flag. To do this let's click on the second sizer and check it's '''Expand'' property:

[[Image:wxs_tut03_006.png]]

Now we can change labels of regions since they are fully visible now. To do this click on each region's sizer and change the '''Label''' property:

[[Image:wxs_tut03_007.png]]

Ok but we would like to have ability to add and delete selected cd - we will insert two buttons for this purpose in the first region. To add the button choose it from palette and add into the sizer. Note that we can now point wxListBox item - it can not have children so wxSmith will try to add new item before or after it. After adding button we would have such result:

[[Image:wxs_tut03_008.png]]

Hmm, the button should be under the list, not next to it. wxStaticBoxSizer did align items as it should - by default it aligns them in horizontal line. To change the direction to vertical, you can change the '''Orientation''' property of wxStaticBoxSizer. But before we change it let's predict one more thing. I would like to have two buttons instead of only one and I'd like them to be aligned horizontally. Since wxStaticBox will be changed to vertical mode, we will have to use another sizer used only for buttons. So let's add wxBoxSizer right after the list and before button:

[[Image:wxs_tut03_009.png]]

Now let's change '''Orientation''' of the wxStaticBoxSizer to vertical. After changing we have following result:

[[Image:wxs_tut03_010.png]]

We can see that something's wrong here. The wxBoxSizer is abnormally stretched and if we scroll the editor we can see that the same goes to button. We said in previous tutorial that wxBoxSizer an wxStaticBoxSizer are trying to keep same size of items in one direction - that's what happened here. wxStaticBoxSizer used the highest item (list of CDs) and applied this height into all managed items. How to disable it? By setting '''Proportion''' property of both wxBoxSizer and wxButton to 0. This will notify that those items shouldn't be used in height calculations:

[[Image:wxs_tut03_011.png]]

Now let's move the button into the wxBoxSizer - you can very easily do it by clickong on the button and dragging it into the sizer. After that we can add second button next to the first one:

[[Image:wxs_tut03_012.png]]

Nowe we can see that the list don't have '''Expand''' property set (otherwise it would be almost as wide as the region.

Now I'd like to see how current work does look in the application. We could simply run it (F9) or by pressing the preview button on the right part of wxSmith editor:

[[Image:wxs_tut03_013.png]]

(If you run application you will see that there's menu and statusbar, on the preview it won't show, wxSmith still misses few features ;) )

Our window looks good, not perfect but let's leave some polishing for later and fill the CD details region.

== Building '''CD details''' region ==

Inside CD details I'd like to have description of CD:
* Type (Music/Program/Backup/Other)
* Title
* Artist/Author
* Date of release
* Description

For such list we would need some grid sizer. Ok, but the region has wxStaticBoxSizer which align items only in one line. To overcome this limitation we can just add another sizer into wxStaticBoxSizer and use new one as the grid. From two available sizers I suggest wxFlexGridSizer (wxGridSizer would force all cells to have same size which wouldn't look good because row with description may need some more space than others). So let's add new sizer:
* Add wxFlexGridSizer into wxStaticBoxSizer
* Check '''Expand''' property of new item
* Set '''Border Size''' to 0 to avoid some unwanted border.

=== Adding items ===

Data presented here should be shown in two columns - first for the label and second for value so let's change the '''Cols''' property to 2. And now it's time to add the content. For labels we will use wxStaticText and for the value we will use different items:
* wxChoice for Type
* wxTextCtrl for Title, Artist/Author and Description
* wxDatePickerCtrl for Date of release

After adding items we should have following view:

[[Image:wxs_tut03_014.png]]

Hmm, as I've said at the beginning - I didn't prepared anything before writing this tutorial. And guess what. It looks like wxDatePickerCtrl is broken on linux and sometimes crashes C::B (I didn't check on windows), don't know yet whether it's in wxWidgets or wxSmith - I'll have to investigate it. So we will have to change wxDatePickerCtrl to something else or remove it.

There's alternative for wxDatePickerCtrl - wxCallendarCtrl so first let's try to replace wxDatePickerCtrl. First we will have to remove wrong item (by using 'delete' key or by pressing 'X' button on the right side of the editor). After the change we can see that generated callendar is quite but according to other items in this region. We can shrink it a little bit by checking '''wxCAL_SEQUENTIAL_MONTH_SELECTION''' inside the '''Style''' property but it will make the item harder to navigate. We can additionally set '''wxSUNKEN_BORDER''' style to add some nice border around the callendar. Ok, not perfect but acceptable ;)

Now we have this screen:

[[Image:wxs_tut03_015.png]]

=== Customizing and adjusting items ===

Ok, it looks like we have few things to do now:
* First is to check '''Expand''' property for the first region since (it didn't expand when the second region increased height)
* Second is to set proper labels for values in '''CD details''' region
* Third is to check '''Expand''' property for all items with values in same region
* Fourth thing is to adjust items used to edit values in '''CD details''' region

First three tasks are quite easy and I'll leave them to you :)

Fourth task will require few new things so I'll describe it better:

First let's remove text from text boxes - it's set by default but it would be better to have empty text by default. Text can be changed by modifying '''Text''' property so you should do this very quickly.

Now we have to set some values which could be choosen from '''Type''' value. It's done by editing '''Choices''' property of wxChoice. This is more advanced value consisting of few strings to entering it inside one line of text could be hard. Because of that, instead of text, there's a button on the right side. When you click it, new window will pop-up where you can enter choices:

Music
Program
Backup
Other

== Let's check how does the window resize ==

We have the first version of our window. But it's not the end of work. If we want it to be user-friendly, it should give ability to resize. We can check it by either showing preview or building and running application. The latter is preffered since it may produce better results. If the window will show, we should experiment by resizing it:

[[Image:wxs_tut03_016.png]]

We can see two wrong things in this window:
* Regions did not expand vertically and stay centered
* Content of second region did not react for the resize

The first problem should be cuased by some missing '''Expand''' property so let's find it.

First we should check if regions have '''Expand''' property set: yes they have so this is not the problem. Generally in such situations we should continue checking in parent item - this is wxBoxSizer which always expand. Next there's wxPanel we used to make nice background and voila: this one does miss the '''Expand''' property. So let's check it and test the result again and it works fine.

Now the second issue. Content inside '''CD details''' pane was based on wxFlexGridSizer. If you look into previous tutorial you may find out that this sizer has special property called '''Growable cols'''. Using this property we can set columns which should resize. I'd like the column with values to grow (we don't need more space for labels, dont we? ;) ) so let's set the '''Growable cols''' to '''"1"''' (idexes are 0-based). Note that you may quickly find the wxFlexGridSizer by ooking into resource tree - we have only one such sizer in our project.

Now we have some more correct results:

[[Image:wxs_tut03_017.png]]

== Continue polishing the window ==

As I look into our window I see that I left few things on the first region. Buttons don't have new labels and there's to much space between them and the list so we can update those things right now.

As usual I'll leave changing the Labels to you - those buttons should be called '''Add''' and '''Delete'''. And now let's remove the wasted space.

The space is added because each item inside sizers may have extra border. By default it's set to 5 pixels so if we remove the border around buttons we would have more free space. But than the buttons won't have any space between them.

To overcome this problem we could use another property related to border also called '''Border''' (jay, I have to fix the naming before someone notice it) which expands to few check-boxes. By checking or unchecking them we can enable or disable border at some item's edge. So if we remove top/bottom/left edge borders of the first button and top/bottom/right edge borders of the second button we would remove extra space but buttons will still have some gap between them. Here's how the property should look like for the first button:

[[Image:wxs_tut03_018.png]]

== Final words ==

Here we reach the end of this tutorial. Of course the window we've built is not in it's final shape and it could be adjusted - for example we could add some list remembering when and who borrowed the CD from us and who has it now, we could add some searching and so on. But to keep this tutorial quite short, I've decided to leave all those upgrades to you. I hope that you've learned something new and interesting here. Good bye and see you in next tutorial :)

Wxsmith tutorial: Working with items

2010-11-22T19:21:04Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful ones. It works similarly to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all columns resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide a list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing a list of numbers separated using comma (,). Numbers should start from 0, so if you would like the second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is a specialized sizer with one purpose - to provide a set of standard buttons with respect to the platform's look and feel. This sizer has a predefined list of components which it can handle - all are buttons and you can manage them using the sizer's properties. You cannot add your custom items into this sizer.

Each button on this sizer has two properties in the sizer - whether the button should be enabled (for example wxID_OK for OK button) and its label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have a label). It's also very probable that labels will be provided with language-specific strings (depending on the current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's an example of the sizer (note that labels are in Polish and they mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on a linux box. You may see that the buttons have an extra image which is not available for standard buttons. With such a layout, users of the application will feel more comfortable, and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have the same buttons but without images and they would be in a different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" palette page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizers when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with a dividing line (it's called a sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static text, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll briefly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, a very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It doesn't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's the user enter some text. It's basic functionality allows entering one-line text. After changing its properties it may become a more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be a separate resource, it can also be added as another resource's component. This item may be used as background for other components. It has a few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has a few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set the size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides a drop-down list with available options. It works similar to wxComboBox but you cannot enter your own value. It can be used in situations when the user should use one of several available options. An event is generated when the user changes the selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides a drop-down list similarly to wxChoice. In the case of this item, the user can select one of the available values or enter his own if the item is not in a Read-Only state. A very good example of its usage is to provide some text entry with a stored list of previously entered values (like in search boxes). Like wxChoice, changing the selection generates an event. Additionally, changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides a list where you can select one or more items. Changing the item or double-clicking on it generates an event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in the form of tabs. Additionally, wxChoicebook and wxCombobook are also available but are not described here. Changing the selected notebook generates two events: one when the page starts to change (before change) and one when the page is finished changing (after change).

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check boxes may be used to map boolean values. Additionally, 2-state boxes can also be generated (with values: yes/no/unspecified). Changing the value emits an event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works similarly to check boxes. The difference is that only one radiobox in a group can be selected. Groups may be defined by using wxRB_GROUP style - a radiobox which has this style set starts a new group. Changing the selected radiobox emits an event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item, also named Progress Bar, can be used to show the progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only a window which seems hung).

That's the end of this tutorial. I presented some basic information about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also a very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-22T19:02:11Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful ones. It works similarly to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all columns resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide a list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing a list of numbers separated using comma (,). Numbers should start from 0, so if you would like the second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is a specialized sizer with one purpose - to provide a set of standard buttons with respect to the platform's look and feel. This sizer has a predefined list of components which it can handle - all are buttons and you can manage them using the sizer's properties. You cannot add your custom items into this sizer.

Each button on this sizer has two properties in the sizer - whether the button should be enabled (for example wxID_OK for OK button) and its label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have a label). It's also very probable that labels will be provided with language-specific strings (depending on the current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's an example of the sizer (note that labels are in Polish and they mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on a linux box. You may see that the buttons have an extra image which is not available for standard buttons. With such a layout, users of the application will feel more comfortable, and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have the same buttons but without images and they would be in a different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" palette page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizers when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with a dividing line (it's called a sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T20:14:10Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful ones. It works similarly to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all columns resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide a list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing a list of numbers separated using comma (,). Numbers should start from 0, so if you would like the second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is a specialized sizer with one purpose - to provide a set of standard buttons with respect to the platform's look and feel. This sizer has a predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You cannot add your custom items into this sizer.

Each button on this sizer has two properties in the sizer - whether the button should be enabled (for example wxID_OK for OK button) and its label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have a label). It's also very probable that labels will be provided with language-specific strings (depending on the current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and they mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T20:09:13Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful ones. It works similarly to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all columns resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide a list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing a list of numbers separated using comma (,). Numbers should start from 0, so if you would like the second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is the specialized sizer with one purpose - provide set of standard buttons with respect to platform's look and feel. This sizer has predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You can not add your custom items into this sizer.

Each button on this sizer has two properties in sizer - whether button should be enabled (for example wxID_OK for OK button) and it's label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have label). It's also very probable that labels will be provided with language-specific strings (depending on current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and do mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T20:04:34Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is a little bit more advanced than wxBoxSizer because it aligns items on a grid, not on one line. You can specify the number of columns or number of rows in properties "Cols" and "Rows". By default the number of columns is set to 3 and number of rows is set to 0. When 0 is used, it means that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have the same width and all must have the same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widths of all columns. If an item won't use the whole cell, it will be surrounded by empty space.

In properties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is similar to using borders around managed components but with borders you would have to set borders for all items separately.

In the case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of a grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful one. It works simillarily to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all comuns do resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing list of numbers separated using coma (,). Numbers should start from 0, so if you would like second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is the specialized sizer with one purpose - provide set of standard buttons with respect to platform's look and feel. This sizer has predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You can not add your custom items into this sizer.

Each button on this sizer has two properties in sizer - whether button should be enabled (for example wxID_OK for OK button) and it's label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have label). It's also very probable that labels will be provided with language-specific strings (depending on current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and do mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T19:59:42Z

Greenbreen: Added article

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds an extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is little bit more advanced than wxBoxSizer because it does align items on grid, not on one line. You can specify number of columns or number of rows in properties "Cols" and "Rows". By default number of columns is set to 3 and number of rows is set to 0. When 0 is used, it does mean that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have same width and all must have same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widthts of all columns. If item won't use whole cell, it will be surrounded by empty space.

In propreties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is simillar to using borders around managed components but with borders you would have to set borders for all items separately.

In case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful one. It works simillarily to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all comuns do resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing list of numbers separated using coma (,). Numbers should start from 0, so if you would like second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is the specialized sizer with one purpose - provide set of standard buttons with respect to platform's look and feel. This sizer has predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You can not add your custom items into this sizer.

Each button on this sizer has two properties in sizer - whether button should be enabled (for example wxID_OK for OK button) and it's label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have label). It's also very probable that labels will be provided with language-specific strings (depending on current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and do mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T19:58:58Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when an item does not fill its available area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that its available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is little bit more advanced than wxBoxSizer because it does align items on grid, not on one line. You can specify number of columns or number of rows in properties "Cols" and "Rows". By default number of columns is set to 3 and number of rows is set to 0. When 0 is used, it does mean that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have same width and all must have same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widthts of all columns. If item won't use whole cell, it will be surrounded by empty space.

In propreties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is simillar to using borders around managed components but with borders you would have to set borders for all items separately.

In case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful one. It works simillarily to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all comuns do resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing list of numbers separated using coma (,). Numbers should start from 0, so if you would like second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is the specialized sizer with one purpose - provide set of standard buttons with respect to platform's look and feel. This sizer has predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You can not add your custom items into this sizer.

Each button on this sizer has two properties in sizer - whether button should be enabled (for example wxID_OK for OK button) and it's label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have label). It's also very probable that labels will be provided with language-specific strings (depending on current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and do mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.

Wxsmith tutorial: Working with items

2010-11-21T19:53:50Z

Greenbreen: Minor edits for clarity

[[Category:wxSmith Documentation]]

= Working with items =

Hi. In the [[wxSmith tutorial: Hello world|previous tutorial]] we learned how to create a small application using wxWidgets. We created a window with a few items inside. In this tutorial we will focus on wxWidgets items which form a resource. I'll show how you can add items into a resource, how to change them, and finally I'll describe a few of the most important and most useful items.

Note that all screenshots presented here were made on Linux but they should not be very different from the windows ones.

Ok, let's start.

== Create new application ==

We will start with empty wxWidgets project as our blackboard. Steps required to do this were described in [[wxSmith tutorial: Hello world|previous tutorial]] so if you have any problems you can look into it.

Let's select File->New->Project menu, and choose wxWidgets application there. When you're in the wizard, make sure that '''Preffered GUI Builder''' is set to '''wxSmith''' and '''Application type''' is set to '''Frame Based'''.

After the wizard generates a new project you should be able to compile and run it. The application should look like this:

[[Image:wxs_tut02_001.png]]

== Working with items ==

Each resource in wxSmith is made of items. All your buttons, text boxes, lists etc are items. Also some more abstract things like sizers, spacers (used to add empty space), menu entries or even timers are also called items in wxSmith. So basically anything that's inside the resource may be called an item. I'll also use the term component since it reflects the valid meaning too.

Actually each resource has one root item: for dialog window it would be wxDialog item, for frame window it would be wxFrame item and simillarily for panel it would be wxPanel item. If you walked through [[wxSmith tutorial: Hello world|previous tutorial]] you probably noticed that some items may have children - for example you insert sub-menus into menus, some items into sizers and so on. Those items may also have their children. This forms a structure of tree which is directly represented inside resource browser:

[[Image:wxs_tut02_008.png]]

In the picture above, you will see an example of such a tree. wxFontFaceEditorDlg is the currently opened resource with a root node of type wxDialog. We can see that this resource consists of a few sizers and buttons, one text area and some spacers. It's definitely a very simple resource. For more complicated resources, there could be more than 100 items and the tree browser may be helpful when locating them inside the editor.

Each item has its properties - these are usually some values which describe the item. Some of them may affect the way item looks, some may change the item's behavior, and some may be dedicated to programming facilities. You will also find that there is a set of properties available for almost every item - that's correct since many properties are generic like position and size.

wxSmith allow you to edit items inside the properties browser (the window which is usually under the resource browser). If you select an item either by selecting it in the resource browser or by clicking on it inside editor, the properties editor switches to edit its properties. Here's an example of the property browser:

[[Image:wxs_tut02_009.png]]

You can also use the Quick-Properties panel available after pressing the "Q" button on the right side of the editor:

[[Image:wxs_tut02_010.png]]

The purpose of this panel is to provide most common properties in user-friendly way. Unfortunately it's rarely used in wxSmith now and you will probably find it useful only while adjusting sizer-related settings.

The last and the easiest one is to operate directly on item inside editor - you can grab drag boxes and change item's size. You can also move item into another position by simply dragging the item into another place.

=== Excercise: playing with items ===

Ok, let's do some excercise. We started with empty window. First let's add wxFlexGridSizer into it - it's located in Layout pallete (you can find informations on how to add items in [[wxSmith tutorial: Hello world|previous tutorial]]). Now let's add following items into it adding each one after the previous: wxButton, wxStaticText, wxTextCtrl, wxRadioButton and wxCheckBox. The result should look like this:

[[Image:wxs_tut02_011.png]]

I've selected added items with light red border on the palette - all can be found on Standard category.

Now as we have our playground, let's change some items. First thing we will do is to change label and colour of the button. To do this let's click on it and move to properties window.

Label is the first property and it's quite easy to change - you can do it by clicking on the "Label" on the right and just typing new text.
Colour is little bit harder to find. Usually items have two colours - Background and Foreground colour. Background, as the name says, is used to fill item's background, Foreground on the other hand is used to paint some content onto background. Note that there's no strict interpretation of these colours so you should experiment to find out their meaning. In button, Background is what we need.
So let's find Background property - it's value can be changed by using combobox:

[[Image:wxs_tut02_012.png]]

On the list you may find set of predefined system colours. When you choose one of them, they will be read from current system settings making you application compatible with system theme. There are also two special entries - Default (which means that we do not want to set our colour) and Custom. When you select Custom, wxSmith will open colour dialog where you can choose any colour you want. I have choosen light green and here's the result:

[[Image:wxs_tut02_013.png]]

There are also other properties we could talk about, but the best way to learn them is to play with them, so I leave the discoveries to you :)

Now let's use a mouse.

Selected item have eight black boxes around it - these boxes can be used to change size of item. You will easily notice when mouse is over the black box because the cursor changes. So let's resize the wxTextCtrl (edit box):

[[Image:wxs_tut02_014.png]]

You may see that resizing item will also change properties in browser - '''Default Size''' is unchecked now and '''Width''' and '''Height''' is set to required values. There's also other property which seems to be untouched - '''Size in Dialog Units''', which is also related to size. I'll explain it better:
Ususally when you must specify size (or other size-related thing) you provide value in pixels. Alternatively you can specify values in unit called '''Dialog Unit'''. '''Dialog Unit'' is usually little bit bigger than one pixel and it's size depends of size of current font (actually it's size of font of some item's parent which does have a font). This is useful when you want some values to be proportional to size of text presented on window.
If you check '''Size in Dialog Units'', wxSmith will take care of it and sizes will be calculated in Dialog Units instead of pixels (although you will still be able to resize items naturally).

Now let's change position of radio box. Ok, but I've said that sizer is responsible for the positioning - that's right. We have limited possibilities to change position - inside one sizer we can only reorder items, for more complex resources we can also move item between two sizers and other areas where sizers do not apply.
Ok, back to our example, let's move the radio box to position where it would be right after the button. To do this click on the radio button and drag it onto button. When you start dragging you will notice that the area of sizer changed to blue colour - this is a helper to show you what will be the new parent of dragged item. When you move cursor onto button, half of it will become light-blue. This helper shows where new item will be placed - when the left half of pointed item is highlighted, dragged item will be added before it. When the right half is hightlighted, dragged item will be added after it. And when there's no highlighted item, new item will be added as the last child of the parent:

[[Image:wxs_tut02_015.png]]

When you drop the item, it will change it's position. Note that all the items after the new position also moved - that's correct because default settings of wxFlexGridSizer allow only 3 items in one row (this can be changed in property browser) so the items just adapted to the new order:

[[Image:wxs_tut02_016.png]]

Now let's learn a little bit about items available in wxSmith. I'll describe all supported sizers and a few important components from the Standard palette. Let's start with sizers.

== A few words about available sizers ==

Currently we know that sizers are responsible for automatically setting position and size of some components. But how do they do that? Well it depends on which sizer has been used, so what are the rules? The generic rule is that the sizer tries to use all its available space and place managed components in such way that they do not overlap. If the area available to the sizer is too small, it requests a bigger area, so you can be sure that no component will fall outside of the window (unfortunately you can not be sure that after such adjustments the window will be small enough to fit on the screen so be careful with that). Another rule which should be mentioned here is that sizers automatically set-up the minimum size required by the window. Basically when you edit window using sizers, you should be aware that you edit the smallest layout and without some tricks, you won't be able to resize window to something smaller.

Here's list of all sizers available in wxSmith:

=== wxBoxSizer ===

wxBoxSizer is the most basic sizer available in wxWidgets. It's purpose is to align components in one line - one next to another - either horizontally or vertically. This sizer also tries to keep some proportions between components - for a horizontal sizer you can set factors which will keep proportionality of widths and the height of the sizer area will be equal to the height of the tallest component. Analogically, vertical sizers keep heights proportional and the width will be taken as the widest component.

Here are examples of layout using box sizers (the first one is the horizontal one, the second is vertical one):

[[Image:wxs_tut02_002.png]]

In that example you may see that all components have the same width and height.

But let's assume that we want Button2 to be two times wider that Button1 and Button3 to be three times wider than Button1. This can be easily done by using the Proportion property of managed components. By default, the value of all components is set to 1 so they have equal size. Changing the Proportion of second button to 2 would mean that it should be 2 times wider that the first or third one.

Generally you can set any value you want here. One common technique is to set percentage values - for example setting proportions to values 20, 30 and 50 would mean that the first button should occupy 20% of the space, the second one 30% and the third one 50%. The special value 0 means that this item should be skipped in proportion calculations and it will won't automatically adjust it's size when the main window is resized.

So if we want to get 1:2:3 proportions, we set 1 for Button1, 2 for Button2 and 3 for Button3. And here is the result:

[[Image:wxs_tut02_003.png]]

Also note that if you create a resizable window and resize it, those 3 buttons will automatically grow and keep proportions (when you set Proportion to 0, such items won't grow).

The other dimension which is not controlled by Proportion property may be controlled using the "Expand" and "Shaped" properties. They are simple checkboxes. If you check the first one, the item will expand it's width/height and will get the size of the biggest item managed by the same sizer. Selecting "Shaped" will also make the item resize but such items will try to keep the initial proportion between width and height so it doesn't have to use all available space. The effect of the "Expand" and "Shaped" properties can be seen when items differ in width/height, here's the example:

[[Image:wxs_tut02_004.png]]

In this example, the first button is the one that has the biggest size of all three buttons. It's size will be used to adjust sizes of other buttons. The second one has "Expand" flag enabled and the third one does not. What can be seen here is that the third button did expand only in one dimension (the one managed by "Proportion" property), the second dimension was left untouched.

You may also note that when item does not fit the entire area, it is centered. That's default behavior which can be changed. In properties of components managed by sizer you will find properties called '''Horizontal align''' and '''Vertical align'''. Using these properties you can select where the item should be located when it's smaller that it's available area.

=== wxStaticBoxSizer ===

This sizer is simillar to wxBoxSizer with one exception: it adds extra static box around managed items:

[[Image:wxs_tut02_005.png]]

=== wxGridSizer ===

This sizer is little bit more advanced than wxBoxSizer because it does align items on grid, not on one line. You can specify number of columns or number of rows in properties "Cols" and "Rows". By default number of columns is set to 3 and number of rows is set to 0. When 0 is used, it does mean that sizer should automatically calculate this value to keep all managed components inside.

Also note that there's one assumption in wxWidgets - all cells must have same width and all must have same height. This mean that the tallest managed item will set the height of all rows and the widest one will set the widthts of all columns. If item won't use whole cell, it will be surrounded by empty space.

In propreties of wxGridsizer you can also find horizontal and vertical spacings. These values set the spacing added between items. The result of using them is simillar to using borders around managed components but with borders you would have to set borders for all items separately.

In case of wxGridSizer, the "Proportion" value is not used. But you may use "Expand", "Shaped" or placement properties to adjust the result.

Here's an example of grid sizer:

[[Image:wxs_tut02_006.png]]

=== wxFlexGridSizer ===

This is one of the very useful one. It works simillarily to wxGridSizer but it does not force all columns/rows to have same width/height. Also not all comuns do resize when there's more space available for the sizer. Comparing to wxGridSizer you will find two extra properties here: "Growable cols" and "Growable rows". In these properties you may provide list of columns / rows which should automatically resize (very useful to handle resizing of the window) by providing list of numbers separated using coma (,). Numbers should start from 0, so if you would like second and third column to resize, put "1,2" into "Growable cols".

Unfortunately you won't be able to set proportions other that 1:1 ("Proportion" property is also not used in this sizer).

=== wxStdDialogButtonSizer ===

This is the specialized sizer with one purpose - provide set of standard buttons with respect to platform's look and feel. This sizer has predefined list of components which it can handle - all are buttons and you can manage them using sizer's properties. You can not add your custom items into this sizer.

Each button on this sizer has two properties in sizer - whether button should be enabled (for example wxID_OK for OK button) and it's label. Note that labels for most buttons will be generated automatically and wxWidgets will skip them when it would be able to read labels from system settings (for example on linux only the Context Help button does not have label). It's also very probable that labels will be provided with language-specific strings (depending on current system language). Not all configurations of buttons are valid - they won't break the application but buttons will overlap (for example Yes and Ok).

Here's and example of the sizer (note that labels are in Polish and do mean: Help, Cancel, Apply and Ok):

[[Image:wxs_tut02_007.png]]

This screenshot was taken on linux box. You may see that buttons have some extra image which is not available for standard buttons. With such layout, users of the application will feel more comfortable and such 'small' things make users say that the GUI was designed very well ;). On windows the sizer would have same buttons but without images and they would be in different order - the one that is used on windows by default.

All those sizers can be found on the "Layout" pallete page. You can find two other items there which are not sizers but can be used for layout purposes.

The first one is Spacer. It can be added to other sizer when you simply need some empty space instead of any particular component. Spacers have only width and height.

The second one is wxSplitterWindow. When you use this component, you can add one or two child components into it and they will be separated with dividing line (it's called sash in wxWidgets). On the application you can drag it to dynamically adjust the size of managed items.

Now since we know something about sizers let's talk about other components.

== Useful components ==

wxWidgets provides all standard graphical components like static texts, buttons, edit boxes - all those are supported in wxSmith so you can build a nice working environment. I'll shortly describe those that are really useful in standard applications.

=== wxButton ===

[[Image:wxs_tut02_017.png]]

This is standard button, very common component. Its main purpose is to fire some event when you click on it and that's it.

=== wxStaticText ===

[[Image:wxs_tut02_018.png]]

This item only shows user-defined text on the window. It don't generate any events.

=== wxTextCtrl ===

[[Image:wxs_tut02_019.png]]

This item let's user enter some text. It's basic functinality allow to enter one-line text. After changing it's properties it may become more advanced multiline editor with support for different fonts, colours and text styles.

=== wxPanel ===

[[Image:wxs_tut02_020.png]]

Although this item may be separate resource, it can also be added as other resource's component. This item may be used as background for other components. It has few functionalities - it can be used as background in notebooks and it may be a place where you put items without sizers. But it also has few drawbacks - wxWidgets tends to do some tricks with wxPanel's size so it's not always possible to set size we really want.

=== wxChoice ===

[[Image:wxs_tut02_021.png]]

This item provides drop-down list with available options. It works simillar to wxComboBox but you can not enter your own value. It can be used in situations when user should use one of available options. Event is generated when user change selected item.

=== wxComboBox ===

[[Image:wxs_tut02_022.png]]

This item provides drop-down list simillarily to wxChoice. In case of this item, user can select one of available values or enter his own if the item is not in Read-Only state. Very good example of it's usage is to provide some text entry with stored list of previously entered values (like in search boxes). Simillarily to wxChoice, changing selection generates event. Additinoally changing the text and pressing enter also generates events.

=== wxListBox ===

[[Image:wxs_tut02_023.png]]

This item provides list where you can select one or more items. Changing item or double-clicking on it generates event.

=== wxNotebook ===

[[Image:wxs_tut02_024.png]]

Notebook is very useful for complex resources since it groups content in form of tabs. Addintionally wxChoicebook and wxCombobook are also available but are not described here. Changing selected notebook generates two events: one when the page starts to change (before change) and one when the page finished changing (after change)

=== wxCheckBox ===

[[Image:wxs_tut02_025.png]]

Check box may be used to map boolean values, additionally 2-state box can also be generated (with values: yes/no/unspecified). Changing value emits event.

=== wxRadioBox ===

[[Image:wxs_tut02_026.png]]

Radio box works simillarily to check boxes. The difference is that only one radiobox in group can be selected. Groups may be defined by using wxRB_GOUP style - radiobox which have this style set starts new group. Changing selected radiobox emits event.

=== wxGauge ===

[[Image:wxs_tut02_027.png]]

This item also named Progress Bar can be used to show progress of some operation. It's very useful when doing some intensive operations (users may get frustrated when they do not see any change but only window which seems to hang-up).

That's the end of this tutorial. I presented some basic informations about available items. If you want to learn more, the best way to do it is to experiment: add items, change properties, resize, move. You may try adding sizers into other sizers - this is also very useful technique absolutely required for more complex resources.