← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to docs/doxygen/overviews/helloworld.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/doxygen/overviews/helloworld.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        helloworld.h
 
3
// Purpose:     topic overview
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: helloworld.h 69684 2011-11-05 11:55:00Z FM $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/**
 
10
 
 
11
@page overview_helloworld Hello World Example
 
12
 
 
13
This page shows a very simple wxWidgets program that can be used as a skeleton
 
14
for your own code. While it does nothing very useful, it introduces a couple of
 
15
important concepts and explains how to write a working wxWidgets application.
 
16
 
 
17
First, you have to include wxWidgets' header files, of course. This can
 
18
be done on a file by file basis (such as @c wx/window.h) or using one
 
19
global include (@c wx/wx.h) which includes most of the commonly needed headers
 
20
(although not all of them as there are simply too many wxWidgets headers to
 
21
pull in all of them). For the platforms with support for precompiled headers,
 
22
as indicated by @c WX_PRECOMP, this global header is already included by @c
 
23
wx/wxprec.h so we only include it for the other ones:
 
24
 
 
25
@code
 
26
//   wxWidgets "Hello world" Program
 
27
 
 
28
// For compilers that support precompilation, includes "wx/wx.h".
 
29
#include <wx/wxprec.h>
 
30
 
 
31
#ifndef WX_PRECOMP
 
32
    #include <wx/wx.h>
 
33
#endif
 
34
@endcode
 
35
 
 
36
Practically every app should define a new class derived from wxApp. By
 
37
overriding wxApp's OnInit() virtual method the program can be initialized, e.g.
 
38
by creating a new main window.
 
39
 
 
40
@code
 
41
class MyApp: public wxApp
 
42
{
 
43
public:
 
44
    virtual bool OnInit();
 
45
};
 
46
@endcode
 
47
 
 
48
The main window is created by deriving a class from wxFrame and
 
49
giving it a menu and a status bar in its constructor. Also, any class
 
50
that wishes to respond to any "event" (such as mouse clicks or
 
51
messages from the menu or a button) must declare an event table
 
52
using the macro below.
 
53
 
 
54
Finally, the way to react to such events must be done in "handlers".
 
55
In our sample, we react to three menu items, one for our custom menu
 
56
command and two for the standard "Exit" and "About" commands (any program
 
57
should normally implement the latter two). Notice that these handlers
 
58
don't need to be neither virtual nor public.
 
59
 
 
60
@code
 
61
class MyFrame: public wxFrame
 
62
{
 
63
public:
 
64
    MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 
65
 
 
66
private:
 
67
    void OnHello(wxCommandEvent& event);
 
68
    void OnExit(wxCommandEvent& event);
 
69
    void OnAbout(wxCommandEvent& event);
 
70
 
 
71
    wxDECLARE_EVENT_TABLE();
 
72
};
 
73
@endcode
 
74
 
 
75
In order to be able to react to a menu command, it must be given a unique
 
76
identifier which can be defined as a const variable or an enum element. The
 
77
latter is often used because typically many such constants will be needed:
 
78
 
 
79
@code
 
80
enum
 
81
{
 
82
    ID_Hello = 1
 
83
};
 
84
@endcode
 
85
 
 
86
Notice that you don't need to define identifiers for the "About" and "Exit"
 
87
We then proceed to actually implement an event table in which the events
 
88
are routed to their respective handler functions in the class MyFrame.
 
89
 
 
90
There are predefined macros for routing all common events, ranging from
 
91
the selection of a list box entry to a resize event when a user resizes
 
92
a window on the screen. If @c wxID_ANY is given as the ID, the given handler will be
 
93
invoked for any event of the specified type, so that you could add just
 
94
one entry in the event table for all menu commands or all button commands etc.
 
95
 
 
96
The origin of the event can still be distinguished in the event handler as
 
97
the (only) parameter in an event handler is a reference to a wxEvent object,
 
98
which holds various information about the event (such as the ID of and a
 
99
pointer to the class, which emitted the event).
 
100
 
 
101
@code
 
102
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
 
103
    EVT_MENU(ID_Hello,   MyFrame::OnHello)
 
104
    EVT_MENU(wxID_EXIT,  MyFrame::OnExit)
 
105
    EVT_MENU(wxID_ABOUT, MyFrame::OnAbout)
 
106
wxEND_EVENT_TABLE()
 
107
@endcode
 
108
 
 
109
As in all programs there must be a "main" function. Under wxWidgets main is implemented
 
110
using this macro, which creates an application instance and starts the program.
 
111
 
 
112
@code
 
113
wxIMPLEMENT_APP(MyApp)
 
114
@endcode
 
115
 
 
116
As mentioned above, wxApp::OnInit() is called upon startup and should be
 
117
used to initialize the program, maybe showing a "splash screen" and creating
 
118
the main window (or several). The frame should get a title bar text ("Hello World")
 
119
and a position and start-up size. One frame can also be declared to be the
 
120
top window. Returning @true indicates a successful initialization.
 
121
 
 
122
@code
 
123
bool MyApp::OnInit()
 
124
{
 
125
    MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
 
126
    frame->Show( true );
 
127
    return true;
 
128
}
 
129
@endcode
 
130
 
 
131
In the constructor of the main window (or later on) we create a menu with our menu
 
132
items as well as a status bar to be shown at the bottom of the main window. Both have
 
133
to be associated with the frame with respective calls.
 
134
 
 
135
@code
 
136
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 
137
        : wxFrame(NULL, wxID_ANY, title, pos, size)
 
138
{
 
139
    wxMenu *menuFile = new wxMenu;
 
140
    menuFile->Append(ID_Hello, "&Hello...\tCtrl-H",
 
141
                     "Help string shown in status bar for this menu item");
 
142
    menuFile->AppendSeparator();
 
143
    menuFile->Append(wxID_EXIT);
 
144
 
 
145
    wxMenu *menuHelp = new wxMenu;
 
146
    menuHelp->Append(wxID_ABOUT);
 
147
 
 
148
    wxMenuBar *menuBar = new wxMenuBar;
 
149
    menuBar->Append( menuFile, "&File" );
 
150
    menuBar->Append( menuHelp, "&Help" );
 
151
 
 
152
    SetMenuBar( menuBar );
 
153
 
 
154
    CreateStatusBar();
 
155
    SetStatusText( "Welcome to wxWidgets!" );
 
156
}
 
157
@endcode
 
158
 
 
159
Notice that we don't need to specify the labels for the standard menu items
 
160
@c wxID_ABOUT and @c wxID_EXIT, they will be given standard (even correctly
 
161
translated) labels and also standard accelerators correct for the current
 
162
platform making your program behaviour more native. For this reason you should
 
163
prefer reusing the standard ids (see @ref page_stockitems) if possible.
 
164
 
 
165
Here are the standard event handlers implementations. MyFrame::OnExit() closes
 
166
the main window by calling Close(). The parameter @true indicates that other
 
167
windows have no veto power such as after asking "Do you really want to close?".
 
168
If there is no other main window left, the application will quit.
 
169
 
 
170
@code
 
171
void MyFrame::OnExit(wxCommandEvent& event)
 
172
{
 
173
    Close( true );
 
174
}
 
175
@endcode
 
176
 
 
177
MyFrame::OnAbout() will display a small window with some text in it. In this
 
178
case a typical "About" window with information about the program.
 
179
 
 
180
@code
 
181
void MyFrame::OnAbout(wxCommandEvent& event)
 
182
{
 
183
    wxMessageBox( "This is a wxWidgets' Hello world sample",
 
184
                  "About Hello World", wxOK | wxICON_INFORMATION );
 
185
}
 
186
@endcode
 
187
 
 
188
The implementation of custom menu command handler may perform whatever task
 
189
your program needs to do, in this case we will simply show a message from it as
 
190
befits a hello world example:
 
191
@code
 
192
void MyFrame::OnHello(wxCommandEvent& event)
 
193
{
 
194
    wxLogMessage("Hello world from wxWidgets!");
 
195
}
 
196
@endcode
 
197
 
 
198
Here is the entire program that can be copied and pasted:
 
199
@code
 
200
//   wxWidgets "Hello world" Program
 
201
 
 
202
// For compilers that support precompilation, includes "wx/wx.h".
 
203
#include <wx/wxprec.h>
 
204
 
 
205
#ifndef WX_PRECOMP
 
206
    #include <wx/wx.h>
 
207
#endif
 
208
 
 
209
class MyApp: public wxApp
 
210
{
 
211
public:
 
212
    virtual bool OnInit();
 
213
};
 
214
 
 
215
class MyFrame: public wxFrame
 
216
{
 
217
public:
 
218
    MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 
219
 
 
220
private:
 
221
    void OnHello(wxCommandEvent& event);
 
222
    void OnExit(wxCommandEvent& event);
 
223
    void OnAbout(wxCommandEvent& event);
 
224
 
 
225
    wxDECLARE_EVENT_TABLE();
 
226
};
 
227
 
 
228
enum
 
229
{
 
230
    ID_Hello = 1
 
231
};
 
232
 
 
233
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
 
234
    EVT_MENU(ID_Hello,   MyFrame::OnHello)
 
235
    EVT_MENU(wxID_EXIT,  MyFrame::OnExit)
 
236
    EVT_MENU(wxID_ABOUT, MyFrame::OnAbout)
 
237
wxEND_EVENT_TABLE()
 
238
 
 
239
wxIMPLEMENT_APP(MyApp);
 
240
 
 
241
bool MyApp::OnInit()
 
242
{
 
243
    MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
 
244
    frame->Show( true );
 
245
    return true;
 
246
}
 
247
 
 
248
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 
249
        : wxFrame(NULL, wxID_ANY, title, pos, size)
 
250
{
 
251
    wxMenu *menuFile = new wxMenu;
 
252
    menuFile->Append(ID_Hello, "&Hello...\tCtrl-H",
 
253
                     "Help string shown in status bar for this menu item");
 
254
    menuFile->AppendSeparator();
 
255
    menuFile->Append(wxID_EXIT);
 
256
 
 
257
    wxMenu *menuHelp = new wxMenu;
 
258
    menuHelp->Append(wxID_ABOUT);
 
259
 
 
260
    wxMenuBar *menuBar = new wxMenuBar;
 
261
    menuBar->Append( menuFile, "&File" );
 
262
    menuBar->Append( menuHelp, "&Help" );
 
263
 
 
264
    SetMenuBar( menuBar );
 
265
 
 
266
    CreateStatusBar();
 
267
    SetStatusText( "Welcome to wxWidgets!" );
 
268
}
 
269
 
 
270
void MyFrame::OnExit(wxCommandEvent& event)
 
271
{
 
272
    Close( true );
 
273
}
 
274
 
 
275
void MyFrame::OnAbout(wxCommandEvent& event)
 
276
{
 
277
    wxMessageBox( "This is a wxWidgets' Hello world sample",
 
278
                  "About Hello World", wxOK | wxICON_INFORMATION );
 
279
}
 
280
 
 
281
void MyFrame::OnHello(wxCommandEvent& event)
 
282
{
 
283
    wxLogMessage("Hello world from wxWidgets!");
 
284
}
 
285
@endcode
 
286
 
 
287
*/
 
288