X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/18f42b94df62068a19258b96ac7f569d4d3ba400..3fb8a2bcfb362fa35dadd142b0569059a784fbb3:/docs/doxygen/overviews/helloworld.h

diff --git a/docs/doxygen/overviews/helloworld.h b/docs/doxygen/overviews/helloworld.h
index fe1743958c..12c8ae1cfb 100644
--- a/docs/doxygen/overviews/helloworld.h
+++ b/docs/doxygen/overviews/helloworld.h
@@ -10,55 +10,53 @@
 
 @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.
+@tableofcontents
 
-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.
+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 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
-//
-// file name: hworld.cpp
-//
-//   purpose: wxWidgets "Hello world"
-//
+// wxWidgets "Hello world" Program
 
 // 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
-    #include "wx/wx.h"
+    #include <wx/wx.h>
 #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
 {
+public:
     virtual bool OnInit();
 };
 @endcode
 
-The main window is created by deriving a class from wxFrame and
-giving it a menu and a status bar in its constructor. Also, any class
-that wishes to respond to any "event" (such as mouse clicks or
-messages from the menu or a button) must declare an event table
-using the macro below.
+The main window is created by deriving a class from wxFrame and giving it a
+menu and a status bar in its constructor. Also, any class that wishes to
+respond to any "event" (such as mouse clicks or 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".
-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.
+Finally, the way to react to such events must be done in "handlers". 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
@@ -66,84 +64,92 @@ class MyFrame: public wxFrame
 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);
 
-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
-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
 {
-    ID_Quit = 1,
-    ID_About,
+    ID_Hello = 1
 };
 @endcode
 
-We then proceed to actually implement an event table in which the events
-are routed to their respective handler functions in the class MyFrame.
+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
-a window on the screen. If -1 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.
+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 @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.
 
-The origin of the event can still be distinguished in the event handler as
-the (only) parameter in an event handler is a reference to a wxEvent object,
-which holds various information about the event (such as the ID of and a
-pointer to the class, which emitted the event).
+The origin of the event can still be distinguished in the event handler as the
+(only) parameter in an event handler is a reference to a wxEvent object, which
+holds various information about the event (such as the ID of and a 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.
+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
-used to initialize the program, maybe showing a "splash screen" and creating
-the main window (or several). The frame should get a title bar text ("Hello World")
-and a position and start-up size. One frame can also be declared to be the
-top window. Returning @true indicates a successful initialization.
+As mentioned above, wxApp::OnInit() is called upon startup and should be used
+to initialize the program, maybe showing a "splash screen" and creating the
+main window (or several). The frame should get a title bar text ("Hello World")
+and a position and start-up size. One frame can also be declared to be the top
+window. Returning @true indicates a successful initialization.
 
 @code
 bool MyApp::OnInit()
 {
-    MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
+    MyFrame *frame = new MyFrame( "Hello World", wxPoint(50, 50), wxSize(450, 340) );
     frame->Show( true );
     return true;
 }
 @endcode
 
-In the constructor of the main window (or later on) we create a menu with two menu
-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.
+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 to be associated with the frame with respective calls.
 
 @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;
-
-    menuFile->Append( ID_About, "" );
+    menuFile->Append(ID_Hello, "&Hello...\tCtrl-H",
+                     "Help string shown in status bar for this menu item");
     menuFile->AppendSeparator();
-    menuFile->Append( ID_Quit, "E" );
+    menuFile->Append(wxID_EXIT);
+
+    wxMenu *menuHelp = new wxMenu;
+    menuHelp->Append(wxID_ABOUT);
 
     wxMenuBar *menuBar = new wxMenuBar;
-    menuBar->Append( menuFile, "" );
+    menuBar->Append( menuFile, "&File" );
+    menuBar->Append( menuHelp, "&Help" );
 
     SetMenuBar( menuBar );
 
@@ -152,13 +158,19 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 }
 @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
-void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
+void MyFrame::OnExit(wxCommandEvent& event)
 {
     Close( true );
 }
@@ -168,12 +180,112 @@ 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
-void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
+void MyFrame::OnAbout(wxCommandEvent& event)
 {
     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
+
+*/