docs/doxygen/overviews/helloworld.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        helloworld
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page helloworld_overview wxWidgets Hello World sample
  12
  13  As 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, you can now look at wxWidgets'
  16  "Hello World":
  17  You have to include wxWidgets' header files, of course. This can
  18  be done on a file by file basis (such as #include "wx/window.h")
  19  or using one global include (#include "wx/wx.h"). This is
  20  also useful on platforms which support precompiled headers such
  21  as all major compilers on the Windows platform.
  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. Finally, the way to react to such events
  58  must be done in "handlers". In our sample, we react to two menu items,
  59  one for "Quit" and one for displaying an "About" window. These
  60  handlers should not be virtual.
  61
  62  @code
  63  class MyFrame: public wxFrame
  64  {
  65  public:
  66      MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
  67
  68      void OnQuit(wxCommandEvent& event);
  69      void OnAbout(wxCommandEvent& event);
  70
  71  private:
  72      DECLARE_EVENT_TABLE()
  73  };
  74  @endcode
  75
  76  In order to be able to react to a menu command, it must be given a unique
  77  identifier such as a const or an enum.
  78
  79  @code
  80  enum
  81  {
  82      ID_Quit = 1,
  83      ID_About,
  84  };
  85  @endcode
  86
  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  There are predefined macros for routing all common events, ranging from
  90  the selection of a list box entry to a resize event when a user resizes
  91  a window on the screen. If -1 is given as the ID, the given handler will be
  92  invoked for any event of the specified type, so that you could add just
  93  one entry in the event table for all menu commands or all button commands etc.
  94  The origin of the event can still be distinguished in the event handler as
  95  the (only) parameter in an event handler is a reference to a wxEvent object,
  96  which holds various information about the event (such as the ID of and a
  97  pointer to the class, which emitted the event).
  98
  99  @code
 100  BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 101      EVT_MENU(ID_Quit,  MyFrame::OnQuit)
 102      EVT_MENU(ID_About, MyFrame::OnAbout)
 103  END_EVENT_TABLE()
 104  @endcode
 105
 106  As in all programs there must be a "main" function. Under wxWidgets main is implemented
 107  using this macro, which creates an application instance and starts the program.
 108
 109  @code
 110  IMPLEMENT_APP(MyApp)
 111  @endcode
 112
 113  As mentioned above, wxApp::OnInit() is called upon startup and should be
 114  used to initialize the program, maybe showing a "splash screen" and creating
 115  the main window (or several). The frame should get a title bar text ("Hello World")
 116  and a position and start-up size. One frame can also be declared to be the
 117  top window. Returning @true indicates a successful initialization.
 118
 119  @code
 120  bool MyApp::OnInit()
 121  {
 122      MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
 123      frame-Show( @true );
 124      SetTopWindow( frame );
 125      return @true;
 126  }
 127  @endcode
 128
 129  In the constructor of the main window (or later on) we create a menu with two menu
 130  items as well as a status bar to be shown at the bottom of the main window. Both have
 131  to be "announced" to the frame with respective calls.
 132
 133  @code
 134  MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 135         : wxFrame((wxFrame *)@NULL, -1, title, pos, size)
 136  {
 137      wxMenu *menuFile = new wxMenu;
 138
 139      menuFile-Append( ID_About, "" );
 140      menuFile-AppendSeparator();
 141      menuFile-Append( ID_Quit, "E" );
 142
 143      wxMenuBar *menuBar = new wxMenuBar;
 144      menuBar-Append( menuFile, "" );
 145
 146      SetMenuBar( menuBar );
 147
 148      CreateStatusBar();
 149      SetStatusText( "Welcome to wxWidgets!" );
 150  }
 151  @endcode
 152
 153  Here are the actual event handlers. MyFrame::OnQuit() closes the main window
 154  by calling Close(). The parameter @true indicates that other windows have no veto
 155  power such as after asking "Do you really want to close?". If there is no other
 156  main window left, the application will quit.
 157
 158  @code
 159  void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 160  {
 161      Close( @true );
 162  }
 163  @endcode
 164
 165  MyFrame::OnAbout() will display a small window with some text in it. In this
 166  case a typical "About" window with information about the program.
 167
 168  @code
 169  void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 170  {
 171      wxMessageBox( "This is a wxWidgets' Hello world sample",
 172                    "About Hello World", wxOK | wxICON_INFORMATION );
 173  }
 174  @endcode
 175
 176  */
 177
 178