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