Virtualize showing/hiding the pages in wxBookCtrlBase.

[wxWidgets.git] / docs / doxygen / overviews / helloworld.h

diff --git a/docs/doxygen/overviews/helloworld.h b/docs/doxygen/overviews/helloworld.h
index d19670c21f0260f2c6c03def685783026e86c721..ff5c20d2878cb38415e64e24cc3930ba5a2a766a 100644 (file)
--- a/docs/doxygen/overviews/helloworld.h
+++ b/docs/doxygen/overviews/helloworld.h
@@ -3,49 +3,44 @@
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_helloworld Hello World Example
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_helloworld Hello World Example
 

-Many people have requested a mini-sample to be published here
-so that some quick judgment concerning syntax
-and basic principles can be made, so here we go.
+This page shows a very simple wxWidgets program that can be used as a skeleton
+for your own code. While it does nothing very useful, it introduces a couple of
+important concepts and explains how to write a working wxWidgets application.

 
 First, you have to include wxWidgets' header files, of course. This can
 
 First, you have to include wxWidgets' header files, of course. This can

-be done on a file by file basis (such as <tt>@#include "wx/window.h"</tt>)
-or using one global include (<tt>@#include "wx/wx.h"</tt>). This is
-also useful on platforms which support precompiled headers such
-as all major compilers on the Windows platform and GCC on Unix platforms.
+be done on a file by file basis (such as @c wx/window.h) or using one
+global include (@c wx/wx.h) which includes most of the commonly needed headers
+(although not all of them as there are simply too many wxWidgets headers to
+pull in all of them). For the platforms with support for precompiled headers,
+as indicated by @c WX_PRECOMP, this global header is already included by @c
+wx/wxprec.h so we only include it for the other ones:

 
 @code
 
 @code

-//
-// file name: hworld.cpp
-//
-//   purpose: wxWidgets "Hello world"
-//
+//   wxWidgets "Hello world" Program

 
 // For compilers that support precompilation, includes "wx/wx.h".
 
 // For compilers that support precompilation, includes "wx/wx.h".

-#include "wx/wxprec.h"
-
-#ifdef __BORLANDC__
-    #pragma hdrstop
-#endif
+#include <wx/wxprec.h>

 
 #ifndef WX_PRECOMP
 
 #ifndef WX_PRECOMP

-    #include "wx/wx.h"
+    #include <wx/wx.h>

 #endif
 @endcode
 
 #endif
 @endcode
 

-Practically every app should define a new class derived from wxApp.
-By overriding wxApp's OnInit() the program can be initialized,
-e.g. by creating a new main window.
+Practically every app should define a new class derived from wxApp. By
+overriding wxApp's OnInit() virtual method the program can be initialized, e.g.
+by creating a new main window.

 
 @code
 class MyApp: public wxApp
 {
 
 @code
 class MyApp: public wxApp
 {

+public:

     virtual bool OnInit();
 };
 @endcode
     virtual bool OnInit();
 };
 @endcode


@@ -57,8 +52,10 @@ messages from the menu or a button) must declare an event table
 using the macro below.
 
 Finally, the way to react to such events must be done in "handlers".
 using the macro below.
 
 Finally, the way to react to such events must be done in "handlers".

-In our sample, we react to two menu items, one for "Quit" and one for
-displaying an "About" window. These handlers should not be virtual.
+In our sample, we react to three menu items, one for our custom menu
+command and two for the standard "Exit" and "About" commands (any program
+should normally implement the latter two). Notice that these handlers
+don't need to be neither virtual nor public.

 
 @code
 class MyFrame: public wxFrame
 
 @code
 class MyFrame: public wxFrame


@@ -66,31 +63,33 @@ class MyFrame: public wxFrame
 public:
     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 
 public:
     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 

-    void OnQuit(wxCommandEvent& event);
+private:
+    void OnHello(wxCommandEvent& event);
+    void OnExit(wxCommandEvent& event);

     void OnAbout(wxCommandEvent& event);
 
     void OnAbout(wxCommandEvent& event);
 

-private:
-    DECLARE_EVENT_TABLE()
+    wxDECLARE_EVENT_TABLE();

 };
 @endcode
 
 In order to be able to react to a menu command, it must be given a unique
 };
 @endcode
 
 In order to be able to react to a menu command, it must be given a unique

-identifier such as a const or an enum.
+identifier which can be defined as a const variable or an enum element. The
+latter is often used because typically many such constants will be needed:

 
 @code
 enum
 {
 
 @code
 enum
 {

-    ID_Quit = 1,
-    ID_About,
+    ID_Hello = 1

 };
 @endcode
 
 };
 @endcode
 

+Notice that you don't need to define identifiers for the "About" and "Exit"

 We then proceed to actually implement an event table in which the events
 are routed to their respective handler functions in the class MyFrame.
 
 There are predefined macros for routing all common events, ranging from
 the selection of a list box entry to a resize event when a user resizes
 We then proceed to actually implement an event table in which the events
 are routed to their respective handler functions in the class MyFrame.
 
 There are predefined macros for routing all common events, ranging from
 the selection of a list box entry to a resize event when a user resizes

-a window on the screen. If -1 is given as the ID, the given handler will be
+a window on the screen. If @c wxID_ANY is given as the ID, the given handler will be

 invoked for any event of the specified type, so that you could add just
 one entry in the event table for all menu commands or all button commands etc.
 
 invoked for any event of the specified type, so that you could add just
 one entry in the event table for all menu commands or all button commands etc.
 


@@ -100,17 +99,18 @@ which holds various information about the event (such as the ID of and a
 pointer to the class, which emitted the event).
 
 @code
 pointer to the class, which emitted the event).
 
 @code

-BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-    EVT_MENU(ID_Quit,  MyFrame::OnQuit)
-    EVT_MENU(ID_About, MyFrame::OnAbout)
-END_EVENT_TABLE()
+wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    EVT_MENU(ID_Hello,   MyFrame::OnHello)
+    EVT_MENU(wxID_EXIT,  MyFrame::OnExit)
+    EVT_MENU(wxID_ABOUT, MyFrame::OnAbout)
+wxEND_EVENT_TABLE()

 @endcode
 
 As in all programs there must be a "main" function. Under wxWidgets main is implemented
 using this macro, which creates an application instance and starts the program.
 
 @code
 @endcode
 
 As in all programs there must be a "main" function. Under wxWidgets main is implemented
 using this macro, which creates an application instance and starts the program.
 
 @code

-IMPLEMENT_APP(MyApp)
+wxIMPLEMENT_APP(MyApp)

 @endcode
 
 As mentioned above, wxApp::OnInit() is called upon startup and should be
 @endcode
 
 As mentioned above, wxApp::OnInit() is called upon startup and should be


@@ -124,27 +124,30 @@ bool MyApp::OnInit()
 {
     MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
     frame->Show( true );
 {
     MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
     frame->Show( true );

-    SetTopWindow( frame );

     return true;
 }
 @endcode
 
     return true;
 }
 @endcode
 

-In the constructor of the main window (or later on) we create a menu with two menu
+In the constructor of the main window (or later on) we create a menu with our menu

 items as well as a status bar to be shown at the bottom of the main window. Both have
 items as well as a status bar to be shown at the bottom of the main window. Both have

-to be "announced" to the frame with respective calls.
+to be associated with the frame with respective calls.

 
 @code
 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 
 @code
 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)

-        : wxFrame((wxFrame *)NULL, -1, title, pos, size)
+        : wxFrame(NULL, wxID_ANY, title, pos, size)

 {
     wxMenu *menuFile = new wxMenu;
 {
     wxMenu *menuFile = new wxMenu;

-
-    menuFile->Append( ID_About, "" );
+    menuFile->Append(ID_Hello, "&Hello...\tCtrl-H",
+                     "Help string shown in status bar for this menu item");

     menuFile->AppendSeparator();
     menuFile->AppendSeparator();

-    menuFile->Append( ID_Quit, "E" );
+    menuFile->Append(wxID_EXIT);
+
+    wxMenu *menuHelp = new wxMenu;
+    menuHelp->Append(wxID_ABOUT);

 
     wxMenuBar *menuBar = new wxMenuBar;
 
     wxMenuBar *menuBar = new wxMenuBar;

-    menuBar->Append( menuFile, "" );
+    menuBar->Append( menuFile, "&File" );
+    menuBar->Append( menuHelp, "&Help" );

 
     SetMenuBar( menuBar );
 
 
     SetMenuBar( menuBar );
 


@@ -153,13 +156,19 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 }
 @endcode
 
 }
 @endcode
 

-Here are the actual event handlers. MyFrame::OnQuit() closes the main window
-by calling Close(). The parameter @true indicates that other windows have no veto
-power such as after asking "Do you really want to close?". If there is no other
-main window left, the application will quit.
+Notice that we don't need to specify the labels for the standard menu items
+@c wxID_ABOUT and @c wxID_EXIT, they will be given standard (even correctly
+translated) labels and also standard accelerators correct for the current
+platform making your program behaviour more native. For this reason you should
+prefer reusing the standard ids (see @ref page_stockitems) if possible.
+
+Here are the standard event handlers implementations. MyFrame::OnExit() closes
+the main window by calling Close(). The parameter @true indicates that other
+windows have no veto power such as after asking "Do you really want to close?".
+If there is no other main window left, the application will quit.

 
 @code
 
 @code

-void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
+void MyFrame::OnExit(wxCommandEvent& event)

 {
     Close( true );
 }
 {
     Close( true );
 }


@@ -169,10 +178,109 @@ MyFrame::OnAbout() will display a small window with some text in it. In this
 case a typical "About" window with information about the program.
 
 @code
 case a typical "About" window with information about the program.
 
 @code

-void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
+void MyFrame::OnAbout(wxCommandEvent& event)

 {
     wxMessageBox( "This is a wxWidgets' Hello world sample",
 {
     wxMessageBox( "This is a wxWidgets' Hello world sample",

-                "About Hello World", wxOK | wxICON_INFORMATION );
+                  "About Hello World", wxOK | wxICON_INFORMATION );
+}
+@endcode
+
+The implementation of custom menu command handler may perform whatever task
+your program needs to do, in this case we will simply show a message from it as
+befits a hello world example:
+@code
+void MyFrame::OnHello(wxCommandEvent& event)
+{
+    wxLogMessage("Hello world from wxWidgets!");
+}
+@endcode
+
+Here is the entire program that can be copied and pasted:
+@code
+//   wxWidgets "Hello world" Program
+
+// For compilers that support precompilation, includes "wx/wx.h".
+#include <wx/wxprec.h>
+
+#ifndef WX_PRECOMP
+    #include <wx/wx.h>
+#endif
+
+class MyApp: public wxApp
+{
+public:
+    virtual bool OnInit();
+};
+
+class MyFrame: public wxFrame
+{
+public:
+    MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
+
+private:
+    void OnHello(wxCommandEvent& event);
+    void OnExit(wxCommandEvent& event);
+    void OnAbout(wxCommandEvent& event);
+
+    wxDECLARE_EVENT_TABLE();
+};
+
+enum
+{
+    ID_Hello = 1
+};
+
+wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    EVT_MENU(ID_Hello,   MyFrame::OnHello)
+    EVT_MENU(wxID_EXIT,  MyFrame::OnExit)
+    EVT_MENU(wxID_ABOUT, MyFrame::OnAbout)
+wxEND_EVENT_TABLE()
+
+wxIMPLEMENT_APP(MyApp);
+
+bool MyApp::OnInit()
+{
+    MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
+    frame->Show( true );
+    return true;
+}
+
+MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
+        : wxFrame(NULL, wxID_ANY, title, pos, size)
+{
+    wxMenu *menuFile = new wxMenu;
+    menuFile->Append(ID_Hello, "&Hello...\tCtrl-H",
+                     "Help string shown in status bar for this menu item");
+    menuFile->AppendSeparator();
+    menuFile->Append(wxID_EXIT);
+
+    wxMenu *menuHelp = new wxMenu;
+    menuHelp->Append(wxID_ABOUT);
+
+    wxMenuBar *menuBar = new wxMenuBar;
+    menuBar->Append( menuFile, "&File" );
+    menuBar->Append( menuHelp, "&Help" );
+
+    SetMenuBar( menuBar );
+
+    CreateStatusBar();
+    SetStatusText( "Welcome to wxWidgets!" );
+}
+
+void MyFrame::OnExit(wxCommandEvent& event)
+{
+    Close( true );
+}
+
+void MyFrame::OnAbout(wxCommandEvent& event)
+{
+    wxMessageBox( "This is a wxWidgets' Hello world sample",
+                  "About Hello World", wxOK | wxICON_INFORMATION );
+}
+
+void MyFrame::OnHello(wxCommandEvent& event)
+{
+    wxLogMessage("Hello world from wxWidgets!");

 }
 @endcode
 
 }
 @endcode