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 wxWidgets Hello World sample
  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