]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/hworld.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / hworld.tex
... / ...
CommitLineData
1\section{wxWidgets Hello World sample}\label{helloworld}
2
3As many people have requested a mini-sample to be published here
4so that some quick judgment concerning syntax
5and basic principles can be made, you can now look at wxWidgets'
6"Hello World":
7
8You have to include wxWidgets' header files, of course. This can
9be done on a file by file basis (such as \#include "wx/window.h")
10or using one global include (\#include "wx/wx.h"). This is
11also useful on platforms which support precompiled headers such
12as all major compilers on the Windows platform.
13
14\begin{verbatim}
15//
16// file name: hworld.cpp
17//
18// purpose: wxWidgets "Hello world"
19//
20
21// For compilers that support precompilation, includes "wx/wx.h".
22#include "wx/wxprec.h"
23
24#ifdef __BORLANDC__
25 #pragma hdrstop
26#endif
27
28#ifndef WX_PRECOMP
29 #include "wx/wx.h"
30#endif
31\end{verbatim}
32
33Practically every app should define a new class derived from wxApp.
34By overriding wxApp's OnInit() the program can be initialized,
35e.g. by creating a new main window.
36
37\begin{verbatim}
38class MyApp: public wxApp
39{
40 virtual bool OnInit();
41};
42\end{verbatim}
43
44The main window is created by deriving a class from wxFrame and
45giving it a menu and a status bar in its constructor. Also, any class
46that wishes to respond to any "event" (such as mouse clicks or
47messages from the menu or a button) must declare an event table
48using the macro below. Finally, the way to react to such events
49must be done in "handlers". In our sample, we react to two menu items,
50one for "Quit" and one for displaying an "About" window. These
51handlers should not be virtual.
52
53\begin{verbatim}
54class MyFrame: public wxFrame
55{
56public:
57 MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
58
59 void OnQuit(wxCommandEvent& event);
60 void OnAbout(wxCommandEvent& event);
61
62private:
63 DECLARE_EVENT_TABLE()
64};
65\end{verbatim}
66
67In order to be able to react to a menu command, it must be given a unique
68identifier such as a const or an enum.
69
70\begin{verbatim}
71enum
72{
73 ID_Quit = 1,
74 ID_About,
75};
76\end{verbatim}
77
78We then proceed to actually implement an event table in which the events
79are routed to their respective handler functions in the class MyFrame.
80There are predefined macros for routing all common events, ranging from
81the selection of a list box entry to a resize event when a user resizes
82a window on the screen. If -1 is given as the ID, the given handler will be
83invoked for any event of the specified type, so that you could add just
84one entry in the event table for all menu commands or all button commands etc.
85The origin of the event can still be distinguished in the event handler as
86the (only) parameter in an event handler is a reference to a wxEvent object,
87which holds various information about the event (such as the ID of and a
88pointer to the class, which emitted the event).
89
90\begin{verbatim}
91BEGIN_EVENT_TABLE(MyFrame, wxFrame)
92 EVT_MENU(ID_Quit, MyFrame::OnQuit)
93 EVT_MENU(ID_About, MyFrame::OnAbout)
94END_EVENT_TABLE()
95\end{verbatim}
96
97As in all programs there must be a "main" function. Under wxWidgets main is implemented
98using this macro, which creates an application instance and starts the program.
99
100\begin{verbatim}
101IMPLEMENT_APP(MyApp)
102\end{verbatim}
103
104As mentioned above, wxApp::OnInit() is called upon startup and should be
105used to initialize the program, maybe showing a "splash screen" and creating
106the main window (or several). The frame should get a title bar text ("Hello World")
107and a position and start-up size. One frame can also be declared to be the
108top window. Returning true indicates a successful initialization.
109
110\begin{verbatim}
111bool MyApp::OnInit()
112{
113 MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
114 frame->Show( true );
115 SetTopWindow( frame );
116 return true;
117}
118\end{verbatim}
119
120In the constructor of the main window (or later on) we create a menu with two menu
121items as well as a status bar to be shown at the bottom of the main window. Both have
122to be "announced" to the frame with respective calls.
123
124\begin{verbatim}
125MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
126 : wxFrame((wxFrame *)NULL, -1, title, pos, size)
127{
128 wxMenu *menuFile = new wxMenu;
129
130 menuFile->Append( ID_About, "&About..." );
131 menuFile->AppendSeparator();
132 menuFile->Append( ID_Quit, "E&xit" );
133
134 wxMenuBar *menuBar = new wxMenuBar;
135 menuBar->Append( menuFile, "&File" );
136
137 SetMenuBar( menuBar );
138
139 CreateStatusBar();
140 SetStatusText( "Welcome to wxWidgets!" );
141}
142\end{verbatim}
143
144Here are the actual event handlers. MyFrame::OnQuit() closes the main window
145by calling Close(). The parameter true indicates that other windows have no veto
146power such as after asking "Do you really want to close?". If there is no other
147main window left, the application will quit.
148
149\begin{verbatim}
150void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
151{
152 Close( true );
153}
154\end{verbatim}
155
156MyFrame::OnAbout() will display a small window with some text in it. In this
157case a typical "About" window with information about the program.
158
159\begin{verbatim}
160void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
161{
162 wxMessageBox( "This is a wxWidgets' Hello world sample",
163 "About Hello World", wxOK | wxICON_INFORMATION );
164}
165\end{verbatim}
166