]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/helloworld.h
Implement hatched/stippled pens/brushes in wxGraphicsContext for Cairo.
[wxWidgets.git] / docs / doxygen / overviews / helloworld.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: helloworld.h
3 // Purpose: topic overview
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
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