Getting Into the Details: The Window
Now let’s move on to some details. The OnInit function of the MyApp class creates an instance of MyFrame, passing the title of the window to the constructor. Simply creating the instance of the class doesn’t actually cause a window to open, however. To open the window, you have to call the instance’s Show function.
If you’re familiar with various windowing-system APIs (such as Win32), you’re likely also familiar with an event loop of sorts that you must write—in the case of Win32, this is the while (GetMessage()) loop. With wxWidgets, thankfully, all of this message-looping junk is abstracted away from you so you don’t have to mess with it. The designers of wxWidgets took an excellent approach whereby the library has the code for the main entry point into the program. To get your own code in place, you derive classes and override functions—always a good way to go with a sound object-oriented library.
The MyFrame class represents your main window, and is derived from wxFrame. The wxFrame class is part of wxWidgets; the MyFrame class is your own class that you create for your application. (You’re free to use whatever name you like.) Inside the MyFrame constructor, you create the controls that will be inside your window. In Listing 1, I did quite a bit of work. Here’s the procedure I used:
- Create an icon for the window. (That line came right from one of the samples.)
- Create a menu bar. You create menu bars programmatically, even though various operating systems let you specify menus in resource files and attach these resources to your executables. To create the menu bar, I created two drop-down menus: a File menu and a Help menu, each of class wxMenu.
- Add a single menu item to each drop-down menu.
- Start piecing the menus together by first creating a main menu bar of class wxMenuBar. I appended the two drop-down menu instances to the menu bar instance. Then I called SetMenuBar, which is a function inherited from wxFrame, passing the menu bar instance. Pretty easy.
- Create a status bar to put at the bottom of the window. Again, that’s easy: I just called CreateStatusBar, which is a function inherited from wxFrame. I passed in the number 2, which gives the status bar two portions in which text can appear.
- Place text in the status bar. This process is trivial: Just call SetStatusText, passing the text to appear and a number representing the portion of the status bar in which to put the text (the first is 0). Like CreateStatusBar, SetStatusText is a member of wxFrame, which means that the function is available throughout your frame functions, making status bar text updates extremely quick.
- After creating the menu bar and status bar, create a book control. This is the wxWidgets name for a set of tabbed pages; the class is wxBookCtrl. As shown in Figures 1–3, my sample program has three tabs at the top. To create the book control, you first create a new instance of the wxBookCtrl class. Unlike the main window class, with controls you don’t derive a new class; instead, you just create an instance of the class, passing the owner window instance and a control ID.
- After creating the book control, create the first of the three tabbed pages. Each is an instance of wxPanel, which is a general-purpose control for holding other controls. When I created the wxPanel instance, I passed the book control into the constructor, because this panel will be part of the book control. However, after I added some controls to the panel (which I’ll explain next), I still had to add the panel to the book manually by calling the panel’s AddPage function and passing the panel, a name for the tab, and optionally a true value if I wanted this tab to be active when the program starts.
- Add the controls. This is the fun part! To add a couple of buttons to the
panel, for example, you just create instances of the wxButton class, passing the
panel to the constructor along with an ID for the button, text to appear on the
button, and position and size information. Here’s a sample call from
new wxButton( panel, BUTTON1, _T("Button &1"), wxPoint(50,30), wxSize(100,30) );
Notice that the first parameter is the panel I just created. If I weren’t using a book control and instead intended to put these buttons right on the window itself, I would simply pass the instance of MyFrame for the first parameter instead; and since this code is in the MyFrame member code, the first parameter would simply be this, like so:
new wxButton( this, BUTTON1, _T("Button &1"), wxPoint(50,30), wxSize(100,30) );
Incidentally, some C++ programmers might find it odd to call new but not save the results back into a variable, in this manner:
somevar = new someclass()
Normally, if you don’t save the result away, you would end up with a memory leak. But not here. wxWidgets is saving away the instance through the control’s constructor. You can save the instance if you need to use the control later in your own code. In the case of this button, I don’t need to refer to the button elsewhere, but later I create a list box control and I need to access its members; thus, I save away the list box. I’ll show you that process next.
- Finish off by adding the panel through AddPage.
Okay, that’s the first panel. The next panel is a list box, which is created in a similar fashion:
- Create an array of strings that will be used to fill the list box. (The items in the array are really instances of wxString.) Then create another panel as before.
- Create the list box. Creating the list box is much like creating a button, except that in this case I also passed in the list of strings, as well as an optional flag, wxLB_SORT, which means that I wanted the list box to remain sorted. If you choose to leave out this sorting flag, the items will display in the same order as they are in the array. Also, this flag parameter is optional, so if you don’t want any additional flags, don’t pass anything at all.
- After passing the second panel to the constructor for the list box, you don’t need to do anything more to create the list box. However, I planned to access the list box later in my code, so I saved the results of the new operator to a variable called listbox1, which I made a member of my MyFrame class.
- Add the new panel to the book control as a page by calling AddPage.
For the third and final panel, I decided to demonstrate a really nice feature of wxWidgets. Typically, when you create a program in a windowing environment, the users will have the ability to resize the window. When windows resize, you’ll often want to resize a control inside the window. Look again at the third tab in Figure 4. Notice that the text control has a border that takes up almost the whole window. In fact, if you resize the window, the text control will grow with the window, always taking up most of the window.
Figure 4 The text control grows with the window when you resize.
The wxWidgets library has classes that provide the capabilities to resize any controls you want resized when a containing window or panel is resized. The book control I’m using here has this feature built in by default; if I resize the window, the book control resizes with the window. The text control that I’m going to put on the third panel, however, doesn’t have that capability, so we’ll need to add it.
To allow for automatic resizing, wxWidgets includes several layout classes that automate the resizing of controls. In this case, we’ll use the wxBoxSizer class, which lets you arrange controls on a panel in a stacked or horizontal fashion; certain controls of your choosing maintain their size while the remaining controls grow or shrink with the window.
Let’s get started:
- Create a panel and pass the wxBoxSizer instance to the panel by calling the
panel = new wxPanel(book); wxBoxSizer *mysizer = new wxBoxSizer( wxVERTICAL ); panel->SetSizer(mysizer);
I arbitrarily chose a vertical pattern, although horizontal would work just as well, since we have only one control.
- Create the text control:
textLog = new wxTextCtrl(panel, TEXTBOX1, _T("Log\n"), wxPoint(0, 250), wxSize(100, 50), wxTE_MULTILINE);
- Most of these parameters are just like those with the button and list box. The third parameter is the initial text to put inside the control. The final parameter, wxTE_MULTILINE, means that we want the text control to be able to hold multiple lines of text, not just a single line.
- Add the text control into the sizer:
mysizer->Add(textLog, 1, wxEXPAND | wxALL, 5);
Let’s examine those parameters a little more closely:
- The first parameter is the text control.
- The second parameter is a proportion value. When you have multiple controls stacked in a single sizer, the number for the second parameter is the ratio of the sum, representing how much space the control should occupy. For example, if you have two controls stacked, and one control takes up 3/4 of the space and the other takes up 1/4, you would specify 3 for the first control and 1 for the second control in each respective call to mysizer->Add(). Since the sum of 3 and 1 is 4, the first control would get 3/4 of the space, and the second would get 1/4 of the space. (If you want any control to be fixed in size, pass 0. Such a control would get a fixed size, and the other controls would be divided up with their respective proportions within the remaining space.)
- The third parameter is a set of flags. The first flag I’m passing is wxEXPAND, which means that the control will be expanded throughout its space. (I could have used wxSHAPED, which would expand the control as much as possible while maintaining a constant ratio of its length to its width.) The second flag I’m passing is wxALL, which refers to the next parameter; this next and final parameter is the size of the border to place around the controls. I’m placing 5 pixels around the control so its border doesn’t go right up against the edge of the containing panel. The wxALL flag means that this value of 5 pixels applies to all four sides. (Other options, which can be combined with OR (|) operators, are wxTOP, wxBOTTOM, wxLEFT, and wxRIGHT.)
- After adding the text control to the panel, add the panel to the book control as before, by calling AddPage.