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