docs/doxygen/overviews/helloworld.h

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