docs/latex/wx/hworld.tex

   1 \section{wxWindows Hello World sample}\label{helloworld}
   2
   3 As many people have requested a mini-sample to be published here
   4 so that some quick judgments concerning syntax
   5 and basic principles can be made, you can now look at wxWindows'
   6 "Hello World":
   7
   8 You have to include wxWindows' header files, of course. This can
   9 be done on a file by file basis (such as \#include "wx/window.h")
  10 or using one global include (\#include "wx/wx.h"). This is
  11 also useful on platforms which support precompiled headers such
  12 as all major compilers on the Windows platform.
  13
  14 \begin{verbatim}
  15 //
  16 // file name: hworld.cpp
  17 //
  18 //   purpose: wxWindows "Hello world"
  19 //
  20
  21 // For compilers that support precompilation, includes "wx/wx.h".
  22 #include "wx/wxprec.h"
  23
  24 #ifdef __BORLANDC__
  25     #pragma hdrstop
  26 #endif
  27
  28 #ifndef WX_PRECOMP
  29     #include "wx/wx.h"
  30 #endif
  31 \end{verbatim}
  32
  33 Practically every app should define a new class derived from wxApp.
  34 By overriding wxApp's OnInit() the program can be initialized,
  35 e.g. by creating a new main window.
  36
  37 \begin{verbatim}
  38 class MyApp: public wxApp
  39 {
  40     virtual bool OnInit();
  41 };
  42 \end{verbatim}
  43
  44 The main window is created by deriving a class from wxFrame and
  45 giving it a menu and a status bar in its constructor. Also, any class
  46 that wishes to respond to any "event" (such as mouse clicks or
  47 messages from the menu or a button) must declare an event table
  48 using the macro below. Finally, the way to react to such events
  49 must be done in "handlers". In our sample, we react to two menu items,
  50 one for "Quit" and one for displaying an "About" window. These
  51 handlers should not be virtual.
  52
  53 \begin{verbatim}
  54 class MyFrame: public wxFrame
  55 {
  56 public:
  57     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
  58
  59     void OnQuit(wxCommandEvent& event);
  60     void OnAbout(wxCommandEvent& event);
  61
  62 private:
  63     DECLARE_EVENT_TABLE()
  64 };
  65 \end{verbatim}
  66
  67 In order to be able to react to a menu command, it must be given a unique
  68 identifier such as a const or an enum.
  69
  70 \begin{verbatim}
  71 enum
  72 {
  73     ID_Quit = 1,
  74     ID_About,
  75 };
  76 \end{verbatim}
  77
  78 We then proceed to actually implement an event table in which the events
  79 are routed to their respective handler functions in the class MyFrame.
  80 There are predefined macros for routing all common events, ranging from
  81 the selection of a list box entry to a resize event when a user resizes
  82 a window on the screen. If -1 is given as the ID, the given handler will be
  83 invoked for any event of the specified type, so that you could add just
  84 one entry in the event table for all menu commands or all button commands etc.
  85 The origin of the event can still be distinguished in the event handler as
  86 the (only) parameter in an event handler is a reference to a wxEvent object,
  87 which holds various information about the event (such as the ID of and a
  88 pointer to the class, which emitted the event).
  89
  90 \begin{verbatim}
  91 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
  92     EVT_MENU(ID_Quit,  MyFrame::OnQuit)
  93     EVT_MENU(ID_About, MyFrame::OnAbout)
  94 END_EVENT_TABLE()
  95 \end{verbatim}
  96
  97 As in all programs there must be a "main" function. Under wxWindows main is implemented
  98 using this macro, which creates an application instance and starts the program.
  99
 100 \begin{verbatim}
 101 IMPLEMENT_APP(MyApp)
 102 \end{verbatim}
 103
 104 As mentioned above, wxApp::OnInit() is called upon startup and should be
 105 used to initialize the program, maybe showing a "splash screen" and creating
 106 the main window (or several). The frame should get a title bar text ("Hello World")
 107 and a position and start-up size. One frame can also be declared to be the
 108 top window. Returning TRUE indicates a successful initialization.
 109
 110 \begin{verbatim}
 111 bool MyApp::OnInit()
 112 {
 113     MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
 114     frame->Show( TRUE );
 115     SetTopWindow( frame );
 116     return TRUE;
 117 }
 118 \end{verbatim}
 119
 120 In the constructor of the main window (or later on) we create a menu with two menu
 121 items as well as a status bar to be shown at the bottom of the main window. Both have
 122 to be "announced" to the frame with respective calls.
 123
 124 \begin{verbatim}
 125 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 126        : wxFrame((wxFrame *)NULL, -1, title, pos, size)
 127 {
 128     wxMenu *menuFile = new wxMenu;
 129
 130     menuFile->Append( ID_About, "&About..." );
 131     menuFile->AppendSeparator();
 132     menuFile->Append( ID_Quit, "E&xit" );
 133
 134     wxMenuBar *menuBar = new wxMenuBar;
 135     menuBar->Append( menuFile, "&File" );
 136
 137     SetMenuBar( menuBar );
 138
 139     CreateStatusBar();
 140     SetStatusText( "Welcome to wxWindows!" );
 141 }
 142 \end{verbatim}
 143
 144 Here are the actual event handlers. MyFrame::OnQuit() closes the main window
 145 by calling Close(). The parameter TRUE indicates that other windows have no veto
 146 power such as after asking "Do you really want to close?". If there is no other
 147 main window left, the application will quit.
 148
 149 \begin{verbatim}
 150 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 151 {
 152     Close( TRUE );
 153 }
 154 \end{verbatim}
 155
 156 MyFrame::OnAbout() will display a small window with some text in it. In this
 157 case a typical "About" window with information about the program.
 158
 159 \begin{verbatim}
 160 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 161 {
 162     wxMessageBox( "This is a wxWindows' Hello world sample",
 163                   "About Hello World", wxOK | wxICON_INFORMATION );
 164 }
 165 \end{verbatim}
 166