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