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

/////////////////////////////////////////////////////////////////////////////
// Name:        roughguide
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

@page overview_roughguide Writing a wxWidgets Application: A Rough Guide

To set a wxWidgets application going, you will need to derive a #wxApp class
and override wxApp::OnInit.

An application must have a top-level #wxFrame or #wxDialog window. Each frame
may contain one or more instances of classes such as #wxPanel,
#wxSplitterWindow or other windows and controls.

A frame can have a #wxMenuBar, a #wxToolBar, a status line, and a #wxIcon for
when the frame is iconized.

A #wxPanel is used to place controls (classes derived from #wxControl) which
are used for user interaction. Examples of controls are #wxButton, #wxCheckBox,
#wxChoice, #wxListBox, #wxRadioBox, #wxSlider.

Instances of #wxDialog can also be used for controls and they have the
advantage of not requiring a separate frame.

Instead of creating a dialog box and populating it with items, it is possible
to choose one of the convenient common dialog classes, such as #wxMessageDialog
and #wxFileDialog.

You never draw directly onto a window - you use a <em>device context</em> (DC).
#wxDC is the base for #wxClientDC, #wxPaintDC, #wxMemoryDC, #wxPostScriptDC,
#wxMemoryDC, #wxMetafileDC and #wxPrinterDC. If your drawing functions have
wxDC as a parameter, you can pass any of these DCs to the function, and thus
use the same code to draw to several different devices. You can draw using the
member functions of wxDC, such as wxDC::DrawLine and wxDC::DrawText. Control
colour on a window (#wxColour) with brushes (#wxBrush) and pens (#wxPen).

To intercept events, you add a DECLARE_EVENT_TABLE macro to the window class
declaration, and put a BEGIN_EVENT_TABLE ... END_EVENT_TABLE block in the
implementation file. Between these macros, you add event macros which map the
event (such as a mouse click) to a member function. These might override
predefined event handlers such as for #wxKeyEvent and #wxMouseEvent.

Most modern applications will have an on-line, hypertext help system; for this,
you need wxHelp and the #wxHelpController class to control wxHelp.

GUI applications aren't all graphical wizardry. List and hash table needs are
catered for by #wxList and #wxHashMap. You will undoubtedly need some
platform-independent @ref functions_file, and you may find it handy to
maintain and search a list of paths using #wxPathList. There's many
@ref functions_miscellany of operating system methods and other functions.

@seealso

@li @ref overview_classesbycat

*/
Commit	Line	Data
15b6757b FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: roughguide
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
36c9828f	10
a2968d85	11	@page overview_roughguide Writing a wxWidgets Application: A Rough Guide
36c9828f	12
a2968d85 BP	13	To set a wxWidgets application going, you will need to derive a #wxApp class
	14	and override wxApp::OnInit.
	15
	16	An application must have a top-level #wxFrame or #wxDialog window. Each frame
	17	may contain one or more instances of classes such as #wxPanel,
	18	#wxSplitterWindow or other windows and controls.
	19
	20	A frame can have a #wxMenuBar, a #wxToolBar, a status line, and a #wxIcon for
	21	when the frame is iconized.
	22
	23	A #wxPanel is used to place controls (classes derived from #wxControl) which
	24	are used for user interaction. Examples of controls are #wxButton, #wxCheckBox,
	25	#wxChoice, #wxListBox, #wxRadioBox, #wxSlider.
	26
	27	Instances of #wxDialog can also be used for controls and they have the
	28	advantage of not requiring a separate frame.
	29
	30	Instead of creating a dialog box and populating it with items, it is possible
	31	to choose one of the convenient common dialog classes, such as #wxMessageDialog
	32	and #wxFileDialog.
	33
	34	You never draw directly onto a window - you use a <em>device context</em> (DC).
	35	#wxDC is the base for #wxClientDC, #wxPaintDC, #wxMemoryDC, #wxPostScriptDC,
	36	#wxMemoryDC, #wxMetafileDC and #wxPrinterDC. If your drawing functions have
	37	wxDC as a parameter, you can pass any of these DCs to the function, and thus
	38	use the same code to draw to several different devices. You can draw using the
	39	member functions of wxDC, such as wxDC::DrawLine and wxDC::DrawText. Control
	40	colour on a window (#wxColour) with brushes (#wxBrush) and pens (#wxPen).
	41
	42	To intercept events, you add a DECLARE_EVENT_TABLE macro to the window class
	43	declaration, and put a BEGIN_EVENT_TABLE ... END_EVENT_TABLE block in the
	44	implementation file. Between these macros, you add event macros which map the
	45	event (such as a mouse click) to a member function. These might override
	46	predefined event handlers such as for #wxKeyEvent and #wxMouseEvent.
	47
	48	Most modern applications will have an on-line, hypertext help system; for this,
	49	you need wxHelp and the #wxHelpController class to control wxHelp.
	50
	51	GUI applications aren't all graphical wizardry. List and hash table needs are
	52	catered for by #wxList and #wxHashMap. You will undoubtedly need some
	53	platform-independent @ref functions_file, and you may find it handy to
	54	maintain and search a list of paths using #wxPathList. There's many
	55	@ref functions_miscellany of operating system methods and other functions.
	56
	57	@seealso
	58
	59	@li @ref overview_classesbycat
	60
	61	*/
36c9828f	62