]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/helloworld.h
allow handling events in a function taking the base class of the event class correspo...
[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 license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10
11 @page overview_helloworld Hello World Example
12
13 Many people have requested a mini-sample to be published here
14 so that some quick judgment concerning syntax
15 and basic principles can be made, so here we go.
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 <tt>@#include "wx/window.h"</tt>)
19 or using one global include (<tt>@#include "wx/wx.h"</tt>). This is
20 also useful on platforms which support precompiled headers such
21 as all major compilers on the Windows platform and GCC on Unix platforms.
22
23 @code
24 //
25 // file name: hworld.cpp
26 //
27 // purpose: wxWidgets "Hello world"
28 //
29
30 // For compilers that support precompilation, includes "wx/wx.h".
31 #include "wx/wxprec.h"
32
33 #ifdef __BORLANDC__
34 #pragma hdrstop
35 #endif
36
37 #ifndef WX_PRECOMP
38 #include "wx/wx.h"
39 #endif
40 @endcode
41
42 Practically every app should define a new class derived from wxApp.
43 By overriding wxApp's OnInit() the program can be initialized,
44 e.g. by creating a new main window.
45
46 @code
47 class MyApp: public wxApp
48 {
49 virtual bool OnInit();
50 };
51 @endcode
52
53 The main window is created by deriving a class from wxFrame and
54 giving it a menu and a status bar in its constructor. Also, any class
55 that wishes to respond to any "event" (such as mouse clicks or
56 messages from the menu or a button) must declare an event table
57 using the macro below.
58
59 Finally, the way to react to such events must be done in "handlers".
60 In our sample, we react to two menu items, one for "Quit" and one for
61 displaying an "About" window. These handlers should not be virtual.
62
63 @code
64 class MyFrame: public wxFrame
65 {
66 public:
67 MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
68
69 void OnQuit(wxCommandEvent& event);
70 void OnAbout(wxCommandEvent& event);
71
72 private:
73 DECLARE_EVENT_TABLE()
74 };
75 @endcode
76
77 In order to be able to react to a menu command, it must be given a unique
78 identifier such as a const or an enum.
79
80 @code
81 enum
82 {
83 ID_Quit = 1,
84 ID_About,
85 };
86 @endcode
87
88 We then proceed to actually implement an event table in which the events
89 are routed to their respective handler functions in the class MyFrame.
90
91 There are predefined macros for routing all common events, ranging from
92 the selection of a list box entry to a resize event when a user resizes
93 a window on the screen. If -1 is given as the ID, the given handler will be
94 invoked for any event of the specified type, so that you could add just
95 one entry in the event table for all menu commands or all button commands etc.
96
97 The origin of the event can still be distinguished in the event handler as
98 the (only) parameter in an event handler is a reference to a wxEvent object,
99 which holds various information about the event (such as the ID of and a
100 pointer to the class, which emitted the event).
101
102 @code
103 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
104 EVT_MENU(ID_Quit, MyFrame::OnQuit)
105 EVT_MENU(ID_About, MyFrame::OnAbout)
106 END_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 IMPLEMENT_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 SetTopWindow( frame );
128 return true;
129 }
130 @endcode
131
132 In the constructor of the main window (or later on) we create a menu with two menu
133 items as well as a status bar to be shown at the bottom of the main window. Both have
134 to be "announced" to the frame with respective calls.
135
136 @code
137 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
138 : wxFrame((wxFrame *)NULL, -1, title, pos, size)
139 {
140 wxMenu *menuFile = new wxMenu;
141
142 menuFile->Append( ID_About, "" );
143 menuFile->AppendSeparator();
144 menuFile->Append( ID_Quit, "E" );
145
146 wxMenuBar *menuBar = new wxMenuBar;
147 menuBar->Append( menuFile, "" );
148
149 SetMenuBar( menuBar );
150
151 CreateStatusBar();
152 SetStatusText( "Welcome to wxWidgets!" );
153 }
154 @endcode
155
156 Here are the actual event handlers. MyFrame::OnQuit() closes the main window
157 by calling Close(). The parameter @true indicates that other windows have no veto
158 power such as after asking "Do you really want to close?". If there is no other
159 main window left, the application will quit.
160
161 @code
162 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
163 {
164 Close( true );
165 }
166 @endcode
167
168 MyFrame::OnAbout() will display a small window with some text in it. In this
169 case a typical "About" window with information about the program.
170
171 @code
172 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
173 {
174 wxMessageBox( "This is a wxWidgets' Hello world sample",
175 "About Hello World", wxOK | wxICON_INFORMATION );
176 }
177 @endcode
178
179 */
180