ALIASES += false="<b><tt>false</tt></b>"
ALIASES += NULL="<b><tt>NULL</tt></b>"
+# NOTE: we could put aliases also for e.g. @wxDefaultSize, @wxDefaultPosition, @wxID_ANY,
+# @wxEmptyString, @wxNullIcon, etc etc
+
# table aliases for 2 and 3 column tables
ALIASES += beginTable="<center><table class='doctable'>"
ALIASES += beginInvisibleTable="<center><table class='doctable' border='0'>"
ALIASES += itemdef{10}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9,\10</td></tr>"
ALIASES += endDefList="</table>"
-
-# NOTE: we could put aliases also for e.g. @wxDefaultSize, @wxDefaultPosition, @wxID_ANY,
-# @wxEmptyString, @wxNullIcon, etc etc
-
# NOTE: these are important as you can't write in the docs
# just #ifdef since the # character is used by Doxygen
# for explicit linking; use the following aliases instead!
-ALIASES += ifdef="<b><tt>\#ifdef</tt></b>"
-ALIASES += ifndef="<b><tt>\#ifndef</tt></b>"
-ALIASES += if="<b><tt>\#if</tt></b>" # NOTE: this overrides the Doxygen \if command
-ALIASES += endif="<b><tt>\#endif</tt></b>"
+# However to avoid overwriting e.g. \if Doxygen command the _ character is postfixed
+ALIASES += ifdef_="<b><tt>\#ifdef</tt></b>"
+ALIASES += ifndef_="<b><tt>\#ifndef</tt></b>"
+ALIASES += if_="<b><tt>\#if</tt></b>"
+ALIASES += endif_="<b><tt>\#endif</tt></b>"
+
+# See ENABLED_SECTIONS configuration key for more info about these:
+ALIASES += beginWxPerlOnly="\if WXPERL_MANUAL \n <b>wxPerl note</b>\n\n"
+ALIASES += endWxPerlOnly="\endif"
+ALIASES += beginWxPythonOnly="\if WXPYTHON_MANUAL \n <b>wxPython note</b>\n\n"
+ALIASES += endWxPythonOnly="\endif"
#---------------------------------------------------------------------------
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
+
+# can contain WXPERL_MANUAL, WXPYTHON_MANUAL keywords
ENABLED_SECTIONS =
+
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_DIRECTORIES = NO
by category (and sorted by alphabetical order inside each category).
All of these macros except for the @c wxUSE_XXX variety is defined if the
corresponding condition is @true and undefined if it isn't, so they should be
- always tested using @ifdef and not @if.
+ always tested using @ifdef_ and not @if_.
@li @ref page_cppconst_guisystem
@li @ref page_cppconst_os
@itemdef{__VISAGECPP__, IBM Visual Age (OS/2)}
@itemdef{__VISUALC__, Microsoft Visual C++, see also wxCHECK_VISUALC_VERSION.
The value of this macro corresponds to the compiler version:
- $1020$ for $4.2$ (the first supported version), $1100$ for
- $5.0$, $1200$ for $6.0$ and so on. For convenience, the symbols
+ @c 1020 for @c 4.2 (the first supported version), @c 1100 for
+ @c 5.0, @c 1200 for @c 6.0 and so on. For convenience, the symbols
__VISUALCn__ are also defined for each major compiler version from
- 5 to 9, i.e. you can use tests such @ifdef __VISUALC7__ to test
+ 5 to 9, i.e. you can use tests such @ifdef_ __VISUALC7__ to test
for compiler version being precisely 7.}
@itemdef{__XLC__, AIX compiler}
@itemdef{__WATCOMC__, Watcom C++. The value of this macro corresponds to
- the compiler version, $1100$ is $11.0$ and $1200$ is OpenWatcom.}
+ the compiler version, @c 1100 is @c 11.0 and @c 1200 is OpenWatcom.}
@itemdef{_WIN32_WCE, Windows CE version}
@endDefList
@itemdef{wxUSE_XXX,
if defined as $1$, feature XXX is active, see the
@ref page_wxusedef (the symbols of this form are always defined,
- use @if and not @ifdef to test for them)}
+ use @if_ and not @ifdef_ to test for them)}
@itemdef{WX_PRECOMP,
is defined if precompiled headers (PCH) are in use. In
this case, @c wx/wxprec.h includes @c wx/wx.h which, in turn,
includes a number of wxWidgets headers thus making it unnecessary to include
them explicitly. However if this is not defined, you do need to include them
and so the usual idiom which allows to support both cases is to first include
- @c wx/wxprec.h} and then, inside @ifndef WX_PRECOMP, individual
+ @c wx/wxprec.h} and then, inside @ifndef_ WX_PRECOMP, individual
headers you need.}
- @itemdef{_UNICODE and UNICODE, both are defined if wxUSE_UNICODE is set to $1$}
+ @itemdef{_UNICODE and UNICODE, both are defined if wxUSE_UNICODE is set to @c 1}
@itemdef{wxUSE_GUI,
this particular feature test macro is defined to $1$
when compiling or using the library with the GUI features activated,
- if it is defined as $0$, only wxBase is available.}
+ if it is defined as @c 0, only wxBase is available.}
@itemdef{wxUSE_BASE,
only used by wxWidgets internally (defined as $1$ when
building wxBase code, either as a standalone library or as part of the
category). These symbols are always defined and whether the given feature is
active or not depends on their value: if defined as @c 1, feature is active,
otherwise it is disabled. Because of this these symbols should be always tested
- using @if and not @ifdef.
+ using @if_ and not @ifdef_.
@li @ref page_wxusedef_multi
@li @ref page_wxusedef_unix
@li @subpage overview_html
@li @subpage overview_richtextctrl
@li @subpage overview_aui
- @li @subpage overview_commondialogs
+ @li @subpage overview_cmndlg
@li @subpage overview_toolbar
@li @subpage overview_grid
@li @subpage overview_treectrl
/////////////////////////////////////////////////////////////////////////////
-// Name: commondialogs
+// Name: commondialogs.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page commondialogs_overview Common dialogs overview
+ @page overview_cmndlg Common dialogs overview
+
+ Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog,
+ #wxDirDialog, #wxTextEntryDialog, #wxPasswordEntryDialog,
+ #wxMessageDialog, #wxSingleChoiceDialog, #wxMultiChoiceDialog
- Classes: #wxColourDialog, #wxFontDialog,
- #wxPrintDialog, #wxFileDialog,
- #wxDirDialog, #wxTextEntryDialog,
- #wxPasswordEntryDialog,
- #wxMessageDialog, #wxSingleChoiceDialog,
- #wxMultiChoiceDialog
Common dialog classes and functions encapsulate commonly-needed dialog box requirements.
They are all 'modal', grabbing the flow of control until the user dismisses the dialog,
to make them easy to use within an application.
+
Some dialogs have both platform-dependent and platform-independent implementations,
so that if underlying windowing systems do not provide the required functionality,
the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
used, for testing or other purposes.
- @ref colourdialog_overview
- @ref fontdialog_overview
- @ref printdialog_overview
- @ref filedialog_overview
- @ref dirdialog_overview
- @ref textentrydialog_overview
- @ref passwordentrydialog_overview
- @ref messagedialog_overview
- @ref singlechoicedialog_overview
- @ref multichoicedialog_overview
- @section wxcolourdialogoverview wxColourDialog overview
+ @li @ref overview_cmndlg_colour
+ @li @ref overview_cmndlg_font
+ @li @ref overview_cmndlg_print
+ @li @ref overview_cmndlg_file
+ @li @ref overview_cmndlg_dir
+ @li @ref overview_cmndlg_textentry
+ @li @ref overview_cmndlg_password
+ @li @ref overview_cmndlg_msg
+ @li @ref overview_cmndlg_singlechoice
+ @li @ref overview_cmndlg_multichoice
+
+
+ <hr>
+
+
+ @section overview_cmndlg_colour wxColourDialog overview
Classes: #wxColourDialog, #wxColourData
+
The wxColourDialog presents a colour selector to the user, and returns
with colour information.
- @b The MS Windows colour selector
+
+ @subsection overview_cmndlg_colour_msw The MS Windows colour selector
+
Under Windows, the native colour selector common dialog is used. This
presents a dialog box with three main regions: at the top left, a
palette of 48 commonly-used colours is shown. Under this, there is a
desired. Additionally, the user may open up the dialog box to show
a right-hand panel containing controls to select a precise colour, and add
it to the custom colour palette.
- @b The generic colour selector
+
+ @subsection overview_cmndlg_colour_generic The generic colour selector
+
Under non-MS Windows platforms, the colour selector is a simulation of
most of the features of the MS Windows selector. Two palettes of 48
standard and 16 custom colours are presented, with the right-hand area
are not optional in the generic colour selector. The generic colour
selector is also available under MS Windows; use the name
wxGenericColourDialog.
- @b Example
+
+ @subsection overview_cmndlg_colour_example Example
+
In the samples/dialogs directory, there is an example of using
the wxColourDialog class. Here is an excerpt, which
sets various parameters of a wxColourData object, including
uses it to set the background of a window.
@code
- wxColourData data;
- data.SetChooseFull(@true);
+ wxColourData data;
+ data.SetChooseFull(true);
for (int i = 0; i 16; i++)
{
wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour);
}
- wxColourDialog dialog(this, );
+ wxColourDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxColourData retData = dialog.GetColourData();
- @section wxfontdialogoverview wxFontDialog overview
+ @section overview_cmndlg_font wxFontDialog overview
Classes: #wxFontDialog, #wxFontData
+
The wxFontDialog presents a font selector to the user, and returns
with font and colour information.
- @b The MS Windows font selector
+
+ @subsection overview_cmndlg_font_msw The MS Windows font selector
+
Under Windows, the native font selector common dialog is used. This
presents a dialog box with controls for font name, point size, style, weight,
underlining, strikeout and text foreground colour. A sample of the
conventions, strikeout is ignored and a font family (such as
Swiss or Modern) is deduced from the actual font name (such as Arial
or Courier).
- @b The generic font selector
+
+ @subsection overview_cmndlg_font_generic The generic font selector
+
Under non-MS Windows platforms, the font selector is simpler.
Controls for font family, point size, style, weight,
underlining and text foreground colour are provided, and
a sample is shown upon a white background. The generic font selector
is also available under MS Windows; use the name wxGenericFontDialog.
- @b Example
+
+ @subsection overview_cmndlg_font_example Example
+
In the samples/dialogs directory, there is an example of using
the wxFontDialog class. The application uses the returned font
and colour for drawing text on a canvas. Here is an excerpt:
@code
- wxFontData data;
+ wxFontData data;
data.SetInitialFont(canvasFont);
data.SetColour(canvasTextColour);
- wxFontDialog dialog(this, );
+ wxFontDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK)
{
wxFontData retData = dialog.GetFontData();
@endcode
- @section wxprintdialogoverview wxPrintDialog overview
+
+ @section overview_cmndlg_print wxPrintDialog overview
Classes: #wxPrintDialog, #wxPrintData
+
This class represents the print and print setup common dialogs.
You may obtain a #wxPrinterDC device context from
a successfully dismissed print dialog.
- The samples/printing example shows how to use it: see @ref printing_overview for
+
+ The samples/printing example shows how to use it: see @ref overview_printing for
an excerpt from this example.
- @section wxfiledialogoverview wxFileDialog overview
+
+
+ @section overview_cmndlg_file wxFileDialog overview
Classes: #wxFileDialog
+
Pops up a file selector box. In Windows and GTK2.4+, this is the common
file selector dialog. In X, this is a file selector box with somewhat less
functionality. The path and filename are distinct elements of a full file pathname.
+
If path is "", the current directory will be used. If filename is "",
no default filename will be supplied. The wildcard determines what files
are displayed in the file selector, and file extension supplies a type
extension for the required filename. Flags may be a combination of wxFD_OPEN,
wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.
+
Both the X and Windows versions implement a wildcard filter. Typing a
filename containing wildcards (*, ?) in the filename text item, and
clicking on Ok, will result in only those files matching the pattern being
displayed. In the X version, supplying no default name will result in the
wildcard filter being inserted in the filename text item; the filter is
ignored if a default name is supplied.
+
The wildcard may be a specification for multiple
types of file with a description for each, such as:
@endcode
- @section wxdirdialogoverview wxDirDialog overview
+
+ @section overview_cmndlg_dir wxDirDialog overview
Classes: #wxDirDialog
- This dialog shows a directory selector dialog, allowing the user to select a single
- directory.
- @section wxtextentrydialogoverview wxTextEntryDialog overview
+ This dialog shows a directory selector dialog, allowing the user to select
+ a single directory.
+
+
+
+ @section overview_cmndlg_textentry wxTextEntryDialog overview
Classes: #wxTextEntryDialog
+
This is a dialog with a text entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
- @section wxpasswordentrydialogoverview wxPasswordEntryDialog overview
+
+
+ @section overview_cmndlg_password wxPasswordEntryDialog overview
Classes: #wxPasswordEntryDialog
+
This is a dialog with a password entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
- @section wxmessagedialogoverview wxMessageDialog overview
+
+
+ @section overview_cmndlg_msg wxMessageDialog overview
Classes: #wxMessageDialog
+
This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No.
Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.
+
The return value of wxMessageDialog::ShowModal indicates
which button the user pressed.
- @section wxsinglechoicedialogoverview wxSingleChoiceDialog overview
+
+
+ @section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
Classes: #wxSingleChoiceDialog
+
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one of them. The selection can be obtained from the dialog as an index,
a string or client data.
- @section wxmultichoicedialogoverview wxMultiChoiceDialog overview
+
+
+ @section overview_cmndlg_multichoice wxMultiChoiceDialog overview
Classes: #wxMultiChoiceDialog
+
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one or more of them.
- */
-
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: config
+// Name: config.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page config_overview wxConfig classes overview
+ @page overview_config wxConfig classes overview
Classes: #wxConfig
+
This overview briefly describes what the config classes are and what they are
for. All the details about how to use them may be found in the description of
the #wxConfigBase class and the documentation of the
file, registry and INI file based implementations mentions all the
features/limitations specific to each one of these versions.
+
The config classes provide a way to store some application configuration
information. They were especially designed for this usage and, although may
probably be used for many other things as well, should be limited to it. It
means that this information should be:
-
- Typed, i.e. strings or numbers for the moment. You can not store
- binary data, for example.
- Small. For instance, it is not recommended to use the Windows
- registry for amounts of data more than a couple of kilobytes.
- Not performance critical, neither from speed nor from a memory
- consumption point of view.
-
+ @li Typed, i.e. strings or numbers for the moment.
+ You can not store binary data, for example.
+ @li Small. For instance, it is not recommended to use the Windows
+ registry for amounts of data more than a couple of kilobytes.
+ @li Not performance critical, neither from speed nor from a memory
+ consumption point of view.
On the other hand, the features provided make them very useful for storing all
kinds of small to medium volumes of hierarchically-organized, heterogeneous
(numbers and strings) organizing it in a tree where you use the
filesystem-like paths to specify the location of a piece of data. In
particular, these classes were designed to be as easy to use as possible.
+
From another point of view, they provide an interface which hides the
differences between the Windows registry and the standard Unix text format
configuration files. Other (future) implementations of wxConfigBase might also
understand GTK resource files or their analogues on the KDE side.
+
In any case, each implementation of wxConfigBase does its best to
make the data look the same way everywhere. Due to limitations of the underlying
physical storage, it may not implement 100% of the base class functionality.
- There are groups of entries and the entries themselves. Each entry contains either a string or a number
- (or a boolean value; support for other types of data such as dates or
- timestamps is planned) and is identified by the full path to it: something
- like /MyApp/UserPreferences/Colors/Foreground. The previous elements in the
- path are the group names, and each name may contain an arbitrary number of entries
- and subgroups. The path components are @b always separated with a slash,
+
+ There are groups of entries and the entries themselves. Each entry contains either
+ a string or a number (or a boolean value; support for other types of data such as
+ dates or timestamps is planned) and is identified by the full path to it: something
+ like /MyApp/UserPreferences/Colors/Foreground.
+
+ The previous elements in the path are the group names, and each name may
+ contain an arbitrary number of entries and subgroups.
+
+ The path components are @b always separated with a slash,
even though some implementations use the backslash internally. Further
details (including how to read/write these entries) may be found in
the documentation for #wxConfigBase.
- */
-
-
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: constraints
+// Name: constraints.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page constraints_overview Constraints overview
+ @page overview_constraints Constraints overview
Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint.
- @b Note: constraints are now deprecated and you should use #sizers instead.
+
+ @note Constraints are now deprecated and you should use sizers instead (see wxSizer).
+
Objects of class wxLayoutConstraint can be associated with a window to define
the way it is laid out, with respect to its siblings or the parent.
+
The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
some or all of which should be accessed directly to set the appropriate
constraints.
-
@b left: represents the left hand edge of the window
@b right: represents the right hand edge of the window
@b top: represents the top edge of the window
@b centreX: represents the horizontal centre point of the window
@b centreY: represents the vertical centre point of the window
-
The constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
To calculate the position and size of the control, the layout algorithm needs to
know exactly 4 constraints (as it has 4 numbers to calculate from them), so you
should always set exactly 4 of the constraints from the above table.
+
If you want the controls height or width to have the default value, you may use
a special value for the constraint: wxAsIs. If the constraint is wxAsIs, the
dimension will not be changed which is useful for the dialog controls which
often have the default size (e.g. the buttons whose size is determined by their
label).
- The constrains calculation is done in wxWindow::Layout
- function which evaluates constraints. To call it you can either call
- wxWindow::SetAutoLayout if the parent window
- is a frame, panel or a dialog to tell default OnSize handlers to call Layout
+
+ The constrains calculation is done in wxWindow::Layout function which evaluates
+ constraints. To call it you can either call wxWindow::SetAutoLayout if the parent
+ window is a frame, panel or a dialog to tell default OnSize handlers to call Layout
automatically whenever the window size changes, or override OnSize and call
- Layout yourself (note that you do have to call
- #Layout yourself if the parent window is not a
- frame, panel or dialog).
- @ref constraintlayoutdetails_overview
- @ref layoutexamples_overview
+ Layout yourself (note that you do have to call #Layout yourself if the parent
+ window is not a frame, panel or dialog).
+
+ @li @ref overview_constraints_layout
+ @li @ref overview_constraints_examples
+
+ <hr>
- @section constraintlayoutdetails Constraint layout: more details
+
+ @section overview_constraints_layout Constraint layout: more details
By default, windows do not have a wxLayoutConstraints object. In this case, much layout
must be done explicitly, by performing calculations in OnSize members, except
for the case of frames that have exactly one subwindow (not counting toolbar and
statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
takes care of resizing the child to always fill the frame.
+
To avoid the need for these rather awkward calculations, the user can create
a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
This object contains a constraint for each of the window edges, two for the centre point,
and two for the window size. By setting some or all of these constraints appropriately,
the user can achieve quite complex layout by defining relationships between windows.
- In wxWidgets, each window can be constrained relative to either its @e siblings on the same window, or the @e parent. The layout algorithm
+
+ In wxWidgets, each window can be constrained relative to either its @e siblings
+ on the same window, or the @e parent. The layout algorithm
therefore operates in a top-down manner, finding the correct layout for
- the children of a window, then the layout for the grandchildren, and so
- on. Note that this differs markedly from native Motif layout, where
+ the children of a window, then the layout for the grandchildren, and so on.
+
+ Note that this differs markedly from native Motif layout, where
constraints can ripple upwards and can eventually change the frame
window or dialog box size. We assume in wxWidgets that the @e user is
always 'boss' and specifies the size of the outer window, to which
circumstances, but it suffices for most situations, and the
simplification avoids some of the nightmarish problems associated with
programming Motif.
+
When the user sets constraints, many of the constraints for windows
edges and dimensions remain unconstrained. For a given window,
the wxWindow::Layout algorithm first resets all constraints
- in all children to have unknown edge or dimension values, and then iterates through the constraints,
- evaluating them. For unconstrained edges and dimensions, it
- tries to find the value using known relationships that always hold. For example,
+ in all children to have unknown edge or dimension values, and then iterates
+ through the constraints, evaluating them. For unconstrained edges and dimensions,
+ it tries to find the value using known relationships that always hold. For example,
an unconstrained @e width may be calculated from the @e left and @e right edges, if
both are currently known. For edges and dimensions with user-supplied constraints, these
constraints are evaluated if the inputs of the constraint are known.
+
The algorithm stops when all child edges and dimension are known (success), or
there are unknown edges or dimensions but there has been no change in this cycle (failure).
It then sets all the window positions and sizes according to the values it has found.
specifying that it should be LeftOf() the second one than to do in a more
natural left-to-right order.
- @section layoutexamples Window layout examples
- @section subwindowlayoutexample Example 1: subwindow layout
+ @section overview_constraints_examples Window layout examples
+
+ @subsection overview_constraints_example1 Example 1: subwindow layout
This example specifies a panel and a window side by side,
with a text subwindow below it.
@code
- frame-panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0);
+ frame-panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0);
frame-scrollWindow = new MyScrolledWindow(frame, -1, wxPoint(0, 0), wxSize(400, 400), wxRETAINED);
frame-text_window = new MyTextWindow(frame, -1, wxPoint(0, 250), wxSize(400, 250));
@endcode
- @section panelitemlayoutexample Example 2: panel item layout
+ @subsection overview_constraints_example2 Example 2: panel item layout
This example sizes a button width to 80 percent of the panel width, and centres
it horizontally. A listbox and multitext item are placed below it. The listbox
the remainder of the width. Margins of 5 pixels are used.
@code
- // Create some panel items
+ // Create some panel items
wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ;
wxLayoutConstraints *b1 = new wxLayoutConstraints;
mtext-SetConstraints(b3);
@endcode
- */
-
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: container
+// Name: container.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page container_overview Container classes overview
+ @page overview_container Container classes overview
Classes: #wxListT, #wxArrayT, #wxVectorT
+
wxWidgets uses itself several container classes including doubly-linked lists
and dynamic arrays (i.e. arrays which expand automatically when they become
- full). For both historical and portability reasons wxWidgets does not
- use STL which provides the standard implementation of many container classes in
- C++. First of all, wxWidgets has existed since well before STL was written, and
+ full). For both historical and portability reasons wxWidgets does not use STL
+ which provides the standard implementation of many container classes in C++.
+
+ First of all, wxWidgets has existed since well before STL was written, and
secondly we don't believe that today compilers can deal really well with all of
- STL classes (this is especially @true for some less common platforms). Of
+ STL classes (this is especially true for some less common platforms). Of
course, the compilers are evolving quite rapidly and hopefully their progress
will allow to base future versions of wxWidgets on STL - but this is not yet
the case.
+
wxWidgets container classes don't pretend to be as powerful or full as STL
ones, but they are quite useful and may be compiled with absolutely any C++
compiler. They're used internally by wxWidgets, but may, of course, be used in
your programs as well if you wish.
+
The list classes in wxWidgets are doubly-linked lists which may either own the
objects they contain (meaning that the list deletes the object when it is
removed from the list or the list itself is destroyed) or just store the
- pointers depending on whether you called or not
- wxList::DeleteContents method.
+ pointers depending on whether you called or not wxList::DeleteContents method.
+
Dynamic arrays resemble C arrays but with two important differences: they
provide run-time range checking in debug builds and they automatically expand
the allocated memory when there is no more space for new items. They come in
two sorts: the "plain" arrays which store either built-in types such as "char",
"int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
own the object pointers to which they store.
+
For the same portability reasons, the container classes implementation in wxWidgets
does not use templates, but is rather based on C preprocessor i.e. is done with
the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
- the dynamic arrays. The "DECLARE" macro declares a
- new container class containing the elements of given type and is needed for all
- three types of container classes: lists, arrays and objarrays. The "DEFINE"
- classes must be inserted in your program in a place where the @b full
- declaration of container element class is in scope (i.e. not just forward
- declaration), otherwise destructors of the container elements will not be
- called! As array classes never delete the items they contain anyhow, there is
+ the dynamic arrays.
+
+ The "DECLARE" macro declares a new container class containing the elements of
+ given type and is needed for all three types of container classes: lists,
+ arrays and objarrays. The "DEFINE" classes must be inserted in your program
+ in a place where the @b full declaration of container element class is in scope
+ (i.e. not just forward declaration), otherwise destructors of the container
+ elements will not be called!
+
+ As array classes never delete the items they contain anyhow, there is
no WX_DEFINE_ARRAY macro for them.
- Examples of usage of these macros may be found in #wxList and
- #wxArray documentation.
+
+ Examples of usage of these macros may be found in #wxList and #wxArray documentation.
+
Finally, wxWidgets predefines several commonly used container classes. wxList
is defined for compatibility with previous versions as a list containing
wxObjects and wxStringList as a list of C-style strings (char *), both of these
array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
wxArrayString. The first three store elements of corresponding types, but
wxArrayString is somewhat special: it is an optimized version of wxArray which
- uses its knowledge about #wxString reference counting
- schema.
-
- */
-
+ uses its knowledge about #wxString reference counting schema.
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: dataobject
+// Name: dataobject.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page dataobject_overview wxDataObject overview
+ @page overview_dataobject wxDataObject overview
- Classes: #wxDataObject,
- #wxClipboard,
- #wxDataFormat,
- #wxDropSource,
- #wxDropTarget
- See also: @ref dnd_overview and @ref samplednd_overview
- This overview discusses data transfer through clipboard or drag and drop. In
- wxWidgets, these two ways to transfer data (either between different
+ Classes: #wxDataObject, #wxClipboard, #wxDataFormat, #wxDropSource, #wxDropTarget
+
+ See also: @ref overview_dnd and @ref overview_samplednd
+
+ This overview discusses data transfer through clipboard or drag and drop.
+ In wxWidgets, these two ways to transfer data (either between different
applications or inside one and the same) are very similar which allows to
implement both of them using almost the same code - or, in other
words, if you implement drag and drop support for your application, you get
clipboard support for free and vice versa.
+
At the heart of both clipboard and drag and drop operations lies the
#wxDataObject class. The objects of this class (or, to
be precise, classes derived from it) represent the data which is being carried
render itself in any of them (see GetDataHere). It can also receive its value
from the outside in a format it supports if it implements the SetData method.
Please see the documentation of this class for more details.
+
Both clipboard and drag and drop operations have two sides: the source and
target, the data provider and the data receiver. These which may be in the same
application and even the same window when, for example, you drag some text from
one position to another in a word processor. Let us describe what each of them
should do.
- #The data provider (source) duties
- #The data receiver (target) duties
+
+ @li The data provider (source) duties
+ @li The data receiver (target) duties
- @section wxdataobjectsource The data provider (source) duties
+ @section overview_dataobject_source The data provider (source) duties
+
+ The data provider is responsible for creating a #wxDataObject containing the
+ data to be transferred. Then it should either pass it to the clipboard using
+ #SetData function or to #wxDropSource and call #DoDragDrop function.
- The data provider is responsible for creating a
- #wxDataObject containing the data to be
- transferred. Then it should either pass it to the clipboard using
- #SetData function or to
- #wxDropSource and call
- #DoDragDrop function.
The only (but important) difference is that the object for the clipboard
transfer must always be created on the heap (i.e. using @c new) and it will
be freed by the clipboard when it is no longer needed (indeed, it is not known
in advance when, if ever, the data will be pasted from the clipboard). On the
other hand, the object for drag and drop operation must only exist while
- #DoDragDrop executes and may be safely deleted
- afterwards and so can be created either on heap or on stack (i.e. as a local
- variable).
+ #DoDragDrop executes and may be safely deleted afterwards and so can be
+ created either on heap or on stack (i.e. as a local variable).
+
Another small difference is that in the case of clipboard operation, the
application usually knows in advance whether it copies or cuts (i.e. copies and
deletes) data - in fact, this usually depends on which menu item the user
chose. But for drag and drop it can only know it after
#DoDragDrop returns (from its return value).
- @section wxdataobjecttarget The data receiver (target) duties
+
+ @section overview_dataobject_target The data receiver (target) duties
To receive (paste in usual terminology) data from the clipboard, you should
- create a #wxDataObject derived class which supports the
- data formats you need and pass it as argument to
- wxClipboard::GetData. If it returns @false,
- no data in (any of) the supported format(s) is available. If it returns @true, the data has been successfully transferred to wxDataObject.
- For drag and drop case, the wxDropTarget::OnData
- virtual function will be called when a data object is dropped, from which the
- data itself may be requested by calling
- wxDropTarget::GetData method which fills
- the data object.
-
- */
+ create a #wxDataObject derived class which supports the data formats you need
+ and pass it as argument to wxClipboard::GetData. If it returns @false,
+
+ no data in (any of) the supported format(s) is available. If it returns @true,
+ the data has been successfully transferred to wxDataObject.
+
+ For drag and drop case, the wxDropTarget::OnData virtual function will be called
+ when a data object is dropped, from which the data itself may be requested by calling
+ wxDropTarget::GetData method which fills the data object.
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: datetime
+// Name: datetime.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page datetime_overview Date and time classes overview
+ @page overview_datetime Date and time classes overview
Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
- #Introduction
- @ref alldatetimeclasses_overview
- @ref datetimecharacteristics_overview
- @ref dateandtimespansdifference_overview
- @ref tdatearithm_overview
- @ref tdatetimezones_overview
- #Daylight saving time (DST)
- @ref tdateholidays_overview
- #Compatibility
-
-
- @section introductiontowxdatetime Introduction
-
- wxWidgets provides a set of powerful classes to work with dates and times. Some
- of the supported features of #wxDateTime class are:
-
-
-
-
-
-
-
- Wide range
-
-
-
-
- The range of supported dates goes from about 4714 B.C. to
- some 480 million years in the future.
-
-
-
-
-
- Precision
-
-
-
-
- Not using floating point calculations anywhere ensures that
- the date calculations don't suffer from rounding errors.
-
+ @li @ref overview_datetime_introduction
+ @li @ref overview_datetime_classes
+ @li @ref overview_datetime_characteristics
+ @li @ref overview_datetime_timespandiff
+ @li @ref overview_datetime_arithmetics
+ @li @ref overview_datetime_timezones
+ @li @ref overview_datetime_dst
+ @li @ref overview_datetime_holidays
+ @li @ref overview_datetime_compat
+ <hr>
- Many features
-
-
-
-
- Not only all usual calculations with dates are supported,
- but also more exotic week and year day calculations, work day testing, standard
- astronomical functions, conversion to and from strings in either strict or free
- format.
-
-
-
-
-
- Efficiency
+ @section overview_datetime_introduction Introduction
+ wxWidgets provides a set of powerful classes to work with dates and times. Some
+ of the supported features of #wxDateTime class are:
+ @li Wide range: the range of supported dates goes from about 4714 B.C. to
+ some 480 million years in the future.
- Objects of wxDateTime are small (8 bytes) and working with
- them is fast
+ @li Precision: not using floating point calculations anywhere ensures that
+ the date calculations don't suffer from rounding errors.
+ @li Many features: not only all usual calculations with dates are supported,
+ but also more exotic week and year day calculations, work day testing, standard
+ astronomical functions, conversion to and from strings in either strict or free
+ format.
+ @li Efficiency: objects of wxDateTime are small (8 bytes) and working with
+ them is fast
+ @section overview_datetime_classes All date/time classes at a glance
- @section alldatetimeclasses All date/time classes at a glance
+ There are 3 main classes declared in @c wx/datetime.h: except #wxDateTime itself
+ which represents an absolute moment in time, there are also two classes -
+ #wxTimeSpan and #wxDateSpan - which represent the intervals of time.
- There are 3 main classes declared in @c wx/datetime.h: except
- #wxDateTime itself which represents an absolute
- moment in time, there are also two classes -
- #wxTimeSpan and #wxDateSpan - which
- represent the intervals of time.
There are also helper classes which are used together with wxDateTime:
- #wxDateTimeHolidayAuthority which is used
- to determine whether a given date is a holiday or not and
- #wxDateTimeWorkDays which is a derivation of this
+ #wxDateTimeHolidayAuthority which is used to determine whether a given date
+ is a holiday or not and #wxDateTimeWorkDays which is a derivation of this
class for which (only) Saturdays and Sundays are the holidays. See more about
these classes in the discussion of the #holidays.
+
Finally, in other parts of this manual you may find mentions of wxDate and
- wxTime classes. @ref tdatecompatibility_overview are obsolete and
+ wxTime classes. @ref overview_datetime_compat are obsolete and
superseded by wxDateTime.
- @section wxdatetimecharacteristics wxDateTime characteristics
+
+
+ @section overview_datetime_characteristics wxDateTime characteristics
#wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
the Epoch are handled just as well (or as bad) as the dates after it). But it
does mean that the best resolution which can be achieved with this class is 1
millisecond.
+
The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
integer. The resulting range of supported dates is thus approximatively 580
million years, but due to the current limitations in the Gregorian calendar
support, only dates from Nov 24, 4714BC are supported (this is subject to
change if there is sufficient interest in doing it).
+
Finally, the internal representation is time zone independent (always in GMT)
and the time zones only come into play when a date is broken into
- year/month/day components. See more about #timezones
- below.
+ year/month/day components. See more about #timezones below.
+
Currently, the only supported calendar is Gregorian one (which is used even
for the dates prior to the historic introduction of this calendar which was
first done on Oct 15, 1582 but is, generally speaking, country, and even
as well and support for other calendars (Maya, Hebrew, Chinese...) is not
ruled out.
- @section dateandtimespansdifference Difference between wxDateSpan and wxTimeSpan
+
+
+ @section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
While there is only one logical way to represent an absolute moment in the
time (and hence only one wxDateTime class), there are at least two methods to
describe a time interval.
+
First, there is the direct and self-explaining way implemented by
#wxTimeSpan: it is just a difference in milliseconds
between two moments in time. Adding or subtracting such an interval to
wxDateTime is always well-defined and is a fast operation.
+
But in the daily life other, calendar-dependent time interval specifications are
used. For example, 'one month later' is commonly used. However, it is clear
that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one
month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
the year is leap or not).
+
This is why there is another class for representing such intervals called
#wxDateSpan. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals of
still might be surprised to notice that now subtracting back the same
interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
with!
+
So, unless you plan to implement some kind of natural language parsing in the
program, you should probably use wxTimeSpan instead of wxDateSpan (which is
also more efficient). However, wxDateSpan may be very useful in situations
when you do need to understand what 'in a month' means (of course, it is
just @c wxDateTime::Now() + wxDateSpan::Month()).
- @section tdatearithm Date arithmetics
+
+
+ @section overview_datetime_arithmetics Date arithmetics
Many different operations may be performed with the dates, however not all of
them make sense. For example, multiplying a date by a number is an invalid
operation, even though multiplying either of the time span classes by a number
is perfectly valid.
- Here is what can be done:
+ Here is what can be done:
+ @li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime
+ resulting in a new wxDateTime object and also 2 objects of the same span class
+ can be added together giving another object of the same class.
+ @li @b Subtraction: the same types of operations as above are
+ allowed and, additionally, a difference between two wxDateTime objects can be
+ taken and this will yield wxTimeSpan.
+ @li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
+ multiplied by an integer number resulting in an object of the same type.
-
- @b Addition
-
-
-
-
- a wxTimeSpan or wxDateSpan can be added to wxDateTime
- resulting in a new wxDateTime object and also 2 objects of the same span class
- can be added together giving another object of the same class.
-
-
-
-
-
- @b Subtraction
-
-
-
-
- the same types of operations as above are
- allowed and, additionally, a difference between two wxDateTime objects can be
- taken and this will yield wxTimeSpan.
-
-
-
-
-
- @b Multiplication
-
-
-
-
- a wxTimeSpan or wxDateSpan object can be
- multiplied by an integer number resulting in an object of the same type.
-
-
-
-
-
- @b Unary minus
-
-
-
-
- a wxTimeSpan or wxDateSpan object may finally be
- negated giving an interval of the same magnitude but of opposite time
- direction.
-
-
-
-
+ @li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
+ negated giving an interval of the same magnitude but of opposite time
+ direction.
For all these operations there are corresponding global (overloaded) operators
and also member functions which are synonyms for them: Add(), Subtract() and
Multiply(). Unary minus as well as composite assignment operations (like +=)
are only implemented as members and Neg() is the synonym for unary minus.
- @section tdatetimezones Time zone considerations
+
+
+ @section overview_datetime_timezones Time zone considerations
Although the time is always stored internally in GMT, you will usually work in
the local time zone. Because of this, all wxDateTime constructors and setters
second...) will also return the correct values for the local time zone by
default, so, generally, doing the natural things will lead to natural and
correct results.
+
If you only want to do this, you may safely skip the rest of this section.
However, if you want to work with different time zones, you should read it to
the end.
+
In this (rare) case, you are still limited to the local time zone when
constructing wxDateTime objects, i.e. there is no way to construct a
wxDateTime corresponding to the given date in, say, Pacific Standard Time.
- To do it, you will need to call #ToTimezone or
- #MakeTimezone methods to adjust the date for
- the target time zone. There are also special versions of these functions
- #ToUTC and #MakeUTC for
- the most common case - when the date should be constructed in UTC.
+ To do it, you will need to call #ToTimezone or #MakeTimezone methods to adjust
+ the date for the target time zone. There are also special versions of these functions
+ #ToUTC and #MakeUTC for the most common case - when the date should be constructed in UTC.
+
You also can just retrieve the value for some time zone without converting the
object to it first. For this you may pass TimeZone argument to any of the
methods which are affected by the time zone (all methods getting date
components and the date formatting ones, for example). In particular, the
Format() family of methods accepts a TimeZone parameter and this allows to
simply print time in any time zone.
+
To see how to do it, the last issue to address is how to construct a TimeZone
object which must be passed to all these methods. First of all, you may construct
it manually by specifying the time zone offset in seconds from GMT, but
- usually you will just use one of the @ref datetime_overview and
+ usually you will just use one of the @ref overview_datetime and
let the conversion constructor do the job.
+
I.e. you would just write
@code
@endcode
- @section tdatedst Daylight saving time (DST)
+
+ @section overview_datetime_dst Daylight saving time (DST)
DST (a.k.a. 'summer time') handling is always a delicate task which is better
left to the operating system which is supposed to be configured by the
administrator to behave correctly. Unfortunately, when doing calculations with
date outside of the range supported by the standard library, we are forced to
deal with these issues ourselves.
+
Several functions are provided to calculate the beginning and end of DST in
the given year and to determine whether it is in effect at the given moment or
not, but they should not be considered as absolutely correct because, first of
all, they only work more or less correctly for only a handful of countries
(any information about other ones appreciated!) and even for them the rules
may perfectly well change in the future.
+
The time zone handling #methods use these functions
too, so they are subject to the same limitations.
- @section tdateholidays wxDateTime and Holidays
+
+
+ @section overview_datetime_holidays wxDateTime and Holidays
TODO.
- @section tdatecompatibility Compatibility
+
+
+ @section overview_datetime_compat Compatibility
The old classes for date/time manipulations ported from wxWidgets version 1.xx
are still included but are reimplemented in terms of wxDateTime. However, using
them is strongly discouraged because they have a few quirks/bugs and were not
'Y2K' compatible.
- */
-
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: dc
+// Name: dc.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page dc_overview Device context overview
+ @page overview_dc Device context overview
Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
- #wxMetafileDC, #wxMemoryDC, #wxPrinterDC,
- #wxScreenDC, #wxClientDC, #wxPaintDC,
- #wxWindowDC.
- A wxDC is a @e device context onto which graphics and text can be drawn.
- The device context is intended to represent a number of output devices in a generic way,
- with the same API being used throughout.
- Some device contexts are created temporarily in order to draw on a window.
- This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC,
- and #wxWindowDC. The following describes the differences between
- these device contexts and when you should use them.
-
+ #wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxScreenDC, #wxClientDC,
+ #wxPaintDC, #wxWindowDC.
- @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
- @b wxClientDC. Use this to paint on the client area of window (the part without
- borders and other decorations), but do not use it from within an #wxPaintEvent.
- @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
- within a #wxPaintEvent.
- @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
- This may not be available on non-Windows platforms.
+ A wxDC is a @e device context onto which graphics and text can be drawn.
+ The device context is intended to represent a number of output devices in a
+ generic way, with the same API being used throughout.
+ Some device contexts are created temporarily in order to draw on a window.
+ This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC, and #wxWindowDC.
+ The following describes the differences between these device contexts and
+ when you should use them.
+
+ @li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
+ @li @b wxClientDC. Use this to paint on the client area of window (the part without
+ borders and other decorations), but do not use it from within an #wxPaintEvent.
+ @li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
+ within a #wxPaintEvent.
+ @li @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
+ This may not be available on non-Windows platforms.
To use a client, paint or window device context, create an object on the stack with
the window as argument, for example:
@code
- void MyWindow::OnMyCmd(wxCommandEvent& event)
+ void MyWindow::OnMyCmd(wxCommandEvent& event)
{
wxClientDC dc(window);
DrawMyPicture(dc);
work for everything (for example not all device contexts support bitmap drawing) but
will work most of the time.
- */
-
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: debugging
+// Name: debugging.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page debugging_overview Debugging overview
+ @page overview_debugging Debugging overview
Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
- @ref logfunctions_overview, @ref debugmacros_overview
+ @ref overview_logfunctions, @ref overview_debugmacros
+
Various classes, functions and macros are provided in wxWidgets to help you debug
your application. Most of these are only available if you compile both wxWidgets,
your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
code that should be active only in debug mode.
- @b wxDebugContext
+
+
+
+ @section overview_debugging_dbgctx wxDebugContext
+
#wxDebugContext is a class that never gets instantiated, but ties together
- various static functions and variables. It allows you to dump all objects to that stream, write statistics about object allocation, and
- check memory for errors.
+ various static functions and variables. It allows you to dump all objects to that stream,
+ write statistics about object allocation, and check memory for errors.
+
It is good practice to define a wxObject::Dump member function for each class you derive
from a wxWidgets class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application.
+
If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
appropriate places. They will tell you what objects have not yet been
will give you information about the problem. (How much information depends on the operating system
and compiler -- some systems don't allow all memory logging to be enabled). See the
memcheck sample for example of usage.
- For wxDebugContext to do its work, the @e new and @e delete
- operators for wxObject have been redefined to store extra information
- about dynamically allocated objects (but not statically declared
- objects). This slows down a debugging version of an application, but can
+
+ For wxDebugContext to do its work, the @e new and @e delete operators for wxObject
+ have been redefined to store extra information about dynamically allocated objects
+ (but not statically declared objects).
+
+ This slows down a debugging version of an application, but can
find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object).
+
If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
-
@code
#define new new(__FILE__,__LINE__)
@endcode
All occurrences of 'new' in wxWidgets and your own application will use
- the overridden form of the operator with two extra arguments. This means that the debugging
- output (and error messages reporting memory problems) will tell you what
+ the overridden form of the operator with two extra arguments. This means that
+ the debugging output (and error messages reporting memory problems) will tell you what
file and on what line you allocated the object. Unfortunately not all
compilers allow this definition to work properly, but most do.
- @b Debug macros
+
+
+
+ @section overview_debugging_dbgmacros Debug macros
+
You should also use @ref debugmacros_overview as part of a 'defensive programming' strategy,
- scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking
- will save a surprising amount of time in the long run.
+ scattering wxASSERTs liberally to test for problems in your code as early as possible.
+ Forward thinking will save a surprising amount of time in the long run.
+
#wxASSERT is used to pop up an error message box when a condition
is not @true. You can also use #wxASSERT_MSG to supply your
own helpful error message. For example:
-
@code
- void MyClass::MyFunction(wxObject* object)
+ void MyClass::MyFunction(wxObject* object)
{
- wxASSERT_MSG( (object != @NULL), "object should not be @NULL in MyFunction!" );
+ wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" );
...
};
@endcode
-
The message box allows you to continue execution or abort the program. If you are running
the application inside a debugger, you will be able to see exactly where the problem was.
- @b Logging functions
- You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in debug mode;
- it will do nothing for non-debugging code.
- @ref debugcontext_overview
- @section wxdebugcontextoverview wxDebugContext overview
- @ref debugging_overview
+ @section overview_debugging_logging Logging functions
+
+ You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in
+ debug mode; it will do nothing for non-debugging code.
+
+
+
+ @section overview_debugging_dbgctx2 wxDebugContext overview
+
Class: #wxDebugContext
- wxDebugContext is a class for performing various debugging and memory tracing
- operations.
+
+ wxDebugContext is a class for performing various debugging and memory tracing operations.
+
This class has only static data and function members, and there should be
no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity.
+
Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped.
@code
- wxDebugContext::SetCheckpoint();
+ wxDebugContext::SetCheckpoint();
wxDebugContext::SetFile("c:\\temp\\debug.log");
at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
in non-debug mode because you may not wish to recompile wxWidgets and your entire application
just to make use of the error logging facility.
- Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead.
- Eventually the logging will be done through the wxLog facilities instead.
- */
+ @note wxDebugContext::SetFile has a problem at present, so use the default stream instead.
+ Eventually the logging will be done through the wxLog facilities instead.
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: dialog
+// Name: dialog.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page dialog_overview wxDialog overview
+ @page overview_dialog wxDialog overview
Classes: #wxDialog, #wxDialogLayoutAdapter
+
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
-
- A surrounding frame is implicitly created.
- Extra functionality is automatically given to the dialog box,
- such as tabbing between items (currently Windows only).
- If the dialog box is @e modal, the calling program is blocked
- until the dialog box is dismissed.
-
+ @li A surrounding frame is implicitly created.
+ @li Extra functionality is automatically given to the dialog box,
+ such as tabbing between items (currently Windows only).
+ @li If the dialog box is @e modal, the calling program is blocked
+ until the dialog box is dismissed.
For a set of dialog convenience functions, including file selection, see
- @ref dialogfunctions_overview.
+ @ref overview_dialogfunctions.
+
See also #wxTopLevelWindow and #wxWindow for inherited
- member functions. Validation of data in controls is covered in @ref validator_overview.
- @ref autoscrollingdialogs_overview
+ member functions. Validation of data in controls is covered in @ref overview_validator.
+
+
+ @section overview_dialog_autoscrolling Automatic scrolling dialogs
- @section autoscrollingdialogs Automatic scrolling dialogs
+ As an ever greater variety of mobile hardware comes to market, it becomes more
+ imperative for wxWidgets applications to adapt to these platforms without putting
+ too much burden on the programmer. One area where wxWidgets can help is in adapting
+ dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
+ wxDialog therefore supplies a global #wxDialogLayoutAdapter class that implements
+ automatic scrolling adaptation for most sizer-based custom dialogs.
+
+ Many applications should therefore be able to adapt to small displays with little
+ or no work, as far as dialogs are concerned.
+ By default this adaptation is off. To switch scrolling adaptation on globally in
+ your application, call the static function wxDialog::EnableLayoutAdaptation passing @true.
+ You can also adjust adaptation on a per-dialog basis by calling
+ wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT
+ (use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
- As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxWidgets applications to adapt
- to these platforms without putting too much burden on the programmer. One area where wxWidgets can help is in adapting
- dialogs for the lower resolution screens that inevitably accompany a smaller form factor. wxDialog therefore supplies
- a global #wxDialogLayoutAdapter class that implements automatic scrolling adaptation for most sizer-based custom dialogs.
- Many applications should therefore be able to adapt to small displays with little or no work, as far as dialogs are concerned.
- By default this adaptation is off. To switch scrolling adaptation on globally in your application, call the static function
- wxDialog::EnableLayoutAdaptation passing @true. You can also adjust adaptation on a per-dialog basis by calling
- wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT (use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
The last two modes override the global adaptation setting.
With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
- standard adapter class wxStandardDialogLayoutAdapter) will
- make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog.
- This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or wxDialog::ShowModal:
-
-
- If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, the pages are made scrollable and
- no other adaptation is done.
- wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
- If that search failed, wxWidgets looks for a horizontal #wxBoxSizer with one or more
- standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
- If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer) and adds them to a #wxStdDialogButtonSizer.
- If no standard buttons were found, the whole dialog content will scroll.
- All the children apart from standard buttons are reparented onto a new #wxScrolledWindow object,
- using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and
- standard button sizer.
-
-
- @b Customising scrolling adaptation
- In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxWidgets will
- search for standard buttons by setting wxDialog::SetLayoutAdaptationLevel. By default,
- all the steps described above will be performed but by setting the level to 1, for example, you can choose to only look for wxStdDialogButtonSizer.
+ standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
+ leaving standard buttons in a non-scrolling part at the bottom of the dialog.
+ This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from
+ within wxDialog::Show or wxDialog::ShowModal:
+
+ @li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
+ the pages are made scrollable and no other adaptation is done.
+ @li wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
+ @li If that search failed, wxWidgets looks for a horizontal #wxBoxSizer with one or more
+ standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
+ @li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
+ and adds them to a #wxStdDialogButtonSizer.
+ If no standard buttons were found, the whole dialog content will scroll.
+ @li All the children apart from standard buttons are reparented onto a new #wxScrolledWindow
+ object, using the old top-level sizer for the scrolled window and creating a new top-level
+ sizer to lay out the scrolled window and standard button sizer.
+
+
+ @subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
+
+ In addition to switching adaptation on and off globally and per dialog,
+ you can choose how aggressively wxWidgets will search for standard buttons by setting
+ wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above will be
+ performed but by setting the level to 1, for example, you can choose to only look for
+ wxStdDialogButtonSizer.
+
You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
treated as standard buttons for the non-scrolling area.
+
You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
- the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability and perform the adaptation.
- You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation in a class derived from wxDialog.
- @b Situations where automatic scrolling adaptation may fail
- Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations.
+ the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
+ and perform the adaptation.
+
+ You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation
+ in a class derived from wxDialog.
+
+ @subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
- The dialog doesn't use sizers.
- The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class.
- The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally,
- you can derive a new adapter class from wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return an instance of your own class.
- The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls.
- The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However, the original sizer hierarchy will still hold
- until Show or ShowModal is called.
+ Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
+ and may fail in the following situations:
+ @li The dialog doesn't use sizers.
+ @li The dialog implementation makes assumptions about the window hierarchy,
+ for example getting the parent of a control and casting to the dialog class.
+ @li The dialog does custom painting and/or event handling not handled by the scrolled window.
+ If this problem can be solved globally, you can derive a new adapter class from
+ wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return
+ an instance of your own class.
+ @li The dialog has unusual layout, for example a vertical sizer containing a mixture of
+ standard buttons and other controls.
+ @li The dialog makes assumptions about the sizer hierarchy, for example to show or hide
+ children of the top-level sizer. However, the original sizer hierarchy will still hold
+ until Show or ShowModal is called.
You can help make sure that your dialogs will continue to function after adaptation by:
+ @li avoiding the above situations and assumptions;
+ @li using #wxStdDialogButtonSizer;
+ @li only making assumptions about hierarchy immediately after the dialog is created;
+ @li using an intermediate sizer under the main sizer, a @false top-level sizer that
+ can be relied on to exist for the purposes of manipulating child sizers and windows;
+ @li overriding wxDialog::GetContentWindow to return a book control if your dialog implements
+ pages: wxWidgets will then only make the pages scrollable.
- avoiding the above situations and assumptions;
- using #wxStdDialogButtonSizer;
- only making assumptions about hierarchy immediately after the dialog is created;
- using an intermediate sizer under the main sizer, a @false top-level sizer that can be relied on to exist
- for the purposes of manipulating child sizers and windows;
- overriding wxDialog::GetContentWindow to return a book control if your dialog implements pages: wxWidgets will then only make the pages
- scrollable.
+ @subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard
- @b wxPropertySheetDialog and wxWizard
- Adaptation for wxPropertySheetDialog is always done by simply making the pages scrollable, since wxDialog::GetContentWindow returns
- the dialog's book control and this is handled by the standard layout adapter.
- wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather than the global adapter: again, only the wizard pages are made scrollable.
+ Adaptation for wxPropertySheetDialog is always done by simply making the pages
+ scrollable, since wxDialog::GetContentWindow returns the dialog's book control and
+ this is handled by the standard layout adapter.
- */
+ wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather
+ than the global adapter: again, only the wizard pages are made scrollable.
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: dnd
+// Name: dnd.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page dnd_overview Drag and drop overview
+ @page overview_dnd Drag and drop overview
- Classes: #wxDataObject,
- #wxTextDataObject,
- #wxDropSource,
- #wxDropTarget,
- #wxTextDropTarget,
- #wxFileDropTarget
- Note that wxUSE_DRAG_AND_DROP must be defined in setup.h in order
+ Classes: #wxDataObject, #wxTextDataObject, #wxDropSource, #wxDropTarget,
+ #wxTextDropTarget, #wxFileDropTarget
+
+ Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
to use drag and drop in wxWidgets.
- See also: @ref dataobject_overview and @ref samplednd_overview
+
+ See also: @ref overview_dataobject and @ref samplednd_overview.
+
It may be noted that data transfer to and from the clipboard is quite
similar to data transfer with drag and drop and the code to implement
these two types is almost the same. In particular, both data transfer
- mechanisms store data in some kind of #wxDataObject
- and identify its format(s) using the #wxDataFormat
- class.
+ mechanisms store data in some kind of #wxDataObject and identify its format(s)
+ using the #wxDataFormat class.
+
To be a @e drag source, i.e. to provide the data which may be dragged by
the user elsewhere, you should implement the following steps:
-
- @b Preparation: First of all, a data object must be created and
- initialized with the data you wish to drag. For example:
-
- @code
- wxTextDataObject my_data("This text will be dragged.");
- @endcode
-
- @b Drag start: To start the dragging process (typically in response to a
- mouse click) you must call wxDropSource::DoDragDrop
- like this:
-
- @code
- wxDropSource dragSource( this );
- dragSource.SetData( my_data );
- wxDragResult result = dragSource.DoDragDrop( TRUE );
- @endcode
-
- @b Dragging: The call to DoDragDrop() blocks the program until the user releases the
- mouse button (unless you override the #GiveFeedback function
- to do something special). When the mouse moves in a window of a program which understands the
- same drag-and-drop protocol (any program under Windows or any program supporting the
- XDnD protocol under X Windows), the corresponding #wxDropTarget methods
- are called - see below.
- @b Processing the result: DoDragDrop() returns an @e effect code which
- is one of the values of @c wxDragResult enum (explained #here):
-
- @code
- switch (result)
- {
- case wxDragCopy: /* copy the data */ break;
-case wxDragMove: /* move the data */
-break;
-default: /* do nothing */
-break;
-}
-@endcode
-
-
-
-To be a @e drop target, i.e. to receive the data dropped by the user you should
-follow the instructions below:
-
-
-@b Initialization: For a window to be a drop target, it needs to have
-an associated #wxDropTarget object. Normally, you will
-call wxWindow::SetDropTarget during window
-creation associating your drop target with it. You must derive a class from
- wxDropTarget and override its pure virtual methods. Alternatively, you may
- derive from #wxTextDropTarget or
-#wxFileDropTarget and override their OnDropText()
- or OnDropFiles() method.
- @b Drop: When the user releases the mouse over a window, wxWidgets
- asks the associated wxDropTarget object if it accepts the data. For this,
- a #wxDataObject must be associated with the drop target
- and this data object will be responsible for the format negotiation between
- the drag source and the drop target. If all goes well, then #OnData
- will get called and the wxDataObject belonging to the drop target can get
- filled with data.
- @b The end: After processing the data, DoDragDrop() returns either
- wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
- and Alt at the moment of the drop. There is currently no way for the drop
- target to change this return code.
-
- */
-
+ @li @b Preparation: First of all, a data object must be created and
+ initialized with the data you wish to drag. For example:
+
+ @code
+ wxTextDataObject my_data("This text will be dragged.");
+ @endcode
+
+ @li <b>Drag start</b>: To start the dragging process (typically in response to a
+ mouse click) you must call wxDropSource::DoDragDrop like this:
+
+ @code
+ wxDropSource dragSource( this );
+ dragSource.SetData( my_data );
+ wxDragResult result = dragSource.DoDragDrop( true );
+ @endcode
+
+ @li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
+ the mouse button (unless you override the #GiveFeedback function to do something
+ special). When the mouse moves in a window of a program which understands the
+ same drag-and-drop protocol (any program under Windows or any program supporting
+ the XDnD protocol under X Windows), the corresponding #wxDropTarget methods
+ are called - see below.
+
+ @li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
+ is one of the values of @c wxDragResult enum (explained #here):
+
+ @code
+ switch (result)
+ {
+ case wxDragCopy:
+ // copy the data
+ break;
+ case wxDragMove:
+ // move the data
+ break;
+ default:
+ // do nothing
+ break;
+ }
+ @endcode
+
+
+ To be a @e drop target, i.e. to receive the data dropped by the user you should
+ follow the instructions below:
+
+ @li @b Initialization: For a window to be a drop target, it needs to have
+ an associated #wxDropTarget object. Normally, you will call wxWindow::SetDropTarget
+ during window creation associating your drop target with it. You must derive a class from
+ wxDropTarget and override its pure virtual methods. Alternatively, you may
+ derive from #wxTextDropTarget or #wxFileDropTarget and override their OnDropText()
+ or OnDropFiles() method.
+
+ @li @b Drop: When the user releases the mouse over a window, wxWidgets
+ asks the associated wxDropTarget object if it accepts the data. For this,
+ a #wxDataObject must be associated with the drop target and this data object will
+ be responsible for the format negotiation between the drag source and the drop target.
+ If all goes well, then #OnData will get called and the wxDataObject belonging to
+ the drop target can get filled with data.
+
+ @li <b>The end</b>: After processing the data, DoDragDrop() returns either
+ wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
+ and Alt at the moment of the drop. There is currently no way for the drop
+ target to change this return code.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: docview
+// Name: docview.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page docview_overview Document/view overview
+ @page overview_docview Document/view overview
+
+ Classes: #wxDocument, #wxView, #wxDocTemplate, #wxDocManager, #wxDocParentFrame,
+ #wxDocChildFrame, #wxDocMDIParentFrame, #wxDocMDIChildFrame,
+ #wxCommand, #wxCommandProcessor
- Classes: #wxDocument, #wxView, #wxDocTemplate,
- #wxDocManager, #wxDocParentFrame, #wxDocChildFrame,
- #wxDocMDIParentFrame, #wxDocMDIChildFrame,
- #wxCommand, #wxCommandProcessor
The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application.
+
The idea is that you can model your application primarily in terms of @e documents to store data
and provide interface-independent operations upon it, and @e views to visualise and manipulate
the data. Documents know how to do input and output given stream objects, and views are responsible
for taking input from physical windows and performing the manipulation on the document data.
+
If a document's data changes, all views should be updated to reflect the change.
- The framework can provide many user-interface elements based on this model. Once you have defined
- your own classes and the relationships between them, the framework takes care
- of popping up file selectors, opening and closing files, asking the user to save
+ The framework can provide many user-interface elements based on this model.
+
+ Once you have defined your own classes and the relationships between them, the framework
+ takes care of popping up file selectors, opening and closing files, asking the user to save
modifications, routing menu commands to appropriate (possibly default) code, even
some default print/preview functionality and support for command undo/redo.
+
The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour.
- These are the overall steps involved in creating an application based on the document/view framework:
-
-
- Define your own document and view classes, overriding a minimal set of
- member functions e.g. for input/output, drawing and initialization.
- Define any subwindows
- (such as a scrolled window) that are needed for the view(s). You may need to route some events
- to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
- Decide what style of interface you will use: Microsoft's MDI (multiple
- document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
- for each document), or single-window (one document open at a time, as in Windows Write).
- Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
- of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
- you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
- Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
- as many wxDocTemplate instances as necessary to define relationships between documents and
- views. For a simple application, there will be just one wxDocTemplate.
+ These are the overall steps involved in creating an application based on the
+ document/view framework:
+
+ @li Define your own document and view classes, overriding a minimal set of
+ member functions e.g. for input/output, drawing and initialization.
+ @li Define any subwindows (such as a scrolled window) that are needed for the view(s).
+ You may need to route some events to views or documents, for example OnPaint needs
+ to be routed to wxView::OnDraw.
+ @li Decide what style of interface you will use: Microsoft's MDI (multiple
+ document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
+ for each document), or single-window (one document open at a time, as in Windows Write).
+ @li Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
+ of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
+ you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
+ @li Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
+ as many wxDocTemplate instances as necessary to define relationships between documents and
+ views. For a simple application, there will be just one wxDocTemplate.
If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
and use wxCommandProcessor::Submit instead of directly executing code. The framework will
take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and
wxID_REDO menu items are defined in the view menu.
+
Here are a few examples of the tailoring you can do to go beyond the default framework
behaviour:
-
- Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
- or a command history editor.
- Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
- class, to provide multi-page document facilities.
- Override wxDocManager::SelectDocumentPath to provide a different file selector.
- Limit the maximum number of open documents and the maximum number of undo commands.
-
+ @li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
+ or a command history editor.
+ @li Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
+ class, to provide multi-page document facilities.
+ @li Override wxDocManager::SelectDocumentPath to provide a different file selector.
+ @li Limit the maximum number of open documents and the maximum number of undo commands.
Note that to activate framework functionality, you need to use some or all of
the wxWidgets @ref predefinedids_overview in your menus.
- @b wxPerl note: The document/view framework is available in wxPerl. To use it,
- you will need the following statements in your application code:
-
+ @beginWxPerlOnly
+ The document/view framework is available in wxPerl. To use it,
+ you will need the following statements in your application code:
@code
use Wx::DocView;
use Wx ':docview'; # import constants (optional)
@endcode
+ @endWxPerlOnly
+ @li @ref overview_docview_wxdoc
+ @li @ref overview_docview_wxview
+ @li @ref overview_docview_wxdoctemplate
+ @li @ref overview_docview_wxdocmanager
+ @li @ref overview_docview_wxcommand
+ @li @ref overview_docview_wxcommandproc
+ @li @ref overview_docview_filehistory
+ @li @ref overview_docview_predefid
- @ref document_overview
- @ref view_overview
- @ref doctemplate_overview
- @ref docmanager_overview
- @ref command_overview
- @ref commandprocessor_overview
- @ref filehistory_overview
- @ref predefinedids_overview
+ <hr>
- @section wxdocumentoverview wxDocument overview
- @ref docview_overview
+ @section overview_docview_wxdoc wxDocument overview
+
Class: #wxDocument
+
The wxDocument class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocTemplate
- and #wxDocManager classes.
+ and cooperates with the #wxView, #wxDocTemplate and #wxDocManager classes.
Using this framework can save a lot of routine user-interface programming,
- since a range of menu commands -- such as open, save, save as -- are supported automatically.
+ since a range of menu commands -- such as open, save, save as -- are supported
+ automatically.
+
The programmer just needs to define a minimal set of classes and member functions
for the framework to call when necessary. Data, and the means to view and edit
- the data, are explicitly separated out in this model, and the concept of multiple @e views onto
- the same data is supported.
+ the data, are explicitly separated out in this model, and the concept of multiple
+ @e views onto the same data is supported.
+
Note that the document/view model will suit many but not all styles of application.
For example, it would be overkill for a simple file conversion utility, where there
may be no call for @e views on @e documents or the ability to open, edit and save
files. But probably the majority of applications are document-based.
+
See the example application in @c samples/docview.
To use the abstract wxDocument class, you need to derive a new class and override
at least the member functions SaveObject and LoadObject. SaveObject and
LoadObject will be called by the framework when the document needs to be saved
or loaded.
+
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create document objects on demand. When you create
a #wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
+
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
to return an instance of the appropriate class.
- @section wxviewoverview wxView overview
- @ref docview_overview
+
+ @section overview_docview_wxview wxView overview
+
Class: #wxView
+
The wxView class can be used to model the viewing and editing component of
- an application's file-based data. It is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxDocument, #wxDocTemplate
+ an application's file-based data. It is part of the document/view framework
+ supported by wxWidgets, and cooperates with the #wxDocument, #wxDocTemplate
and #wxDocManager classes.
+
See the example application in @c samples/docview.
+
To use the abstract wxView class, you need to derive a new class and override
at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
want to respond to menu commands from the frame containing the view.
+
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create view objects on demand. When you create
a #wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
+
If you do not wish to use the wxWidgets method of creating view
objects dynamically, you must override wxDocTemplate::CreateView
to return an instance of the appropriate class.
- @section wxdoctemplateoverview wxDocTemplate overview
- @ref docview_overview
+
+ @section overview_docview_wxdoctemplate wxDocTemplate overview
+
Class: #wxDocTemplate
+
The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document
template object for each document/view pair. The list of document
documents and views. Each document template knows what file filters
and default extension are appropriate for a document/view combination,
and how to create a document or view.
+
For example, you might write a small doodling application that can load
and save lists of line segments. If you had two views of the data -- graphical,
and a list of the segments -- then you would create one document class DoodleDocument,
document templates, but each would be passed a different view class. When
the user clicks on the Open menu item, the file selector is displayed
with a list of possible file filters -- one for each wxDocTemplate. Selecting
- the filter selects the wxDocTemplate, and when
- a file is selected, that template will be used for creating a document
- and view.
+ the filter selects the wxDocTemplate, and when a file is selected, that template
+ will be used for creating a document and view.
+
For the case where an application has one document type and one view type,
a single document template is constructed, and dialogs will be appropriately
simplified.
+
wxDocTemplate is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocument
- and #wxDocManager classes.
+ and cooperates with the #wxView, #wxDocument and #wxDocManager classes.
+
See the example application in @c samples/docview.
+
To use the wxDocTemplate class, you do not need to derive a new class.
- Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) and
- CLASSINFO(YourViewClass) to allow dynamic instance creation.
+ Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass)
+ and CLASSINFO(YourViewClass) to allow dynamic instance creation.
+
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class.
- @e NOTE: the document template has nothing to do with the C++ template construct.
- @section wxdocmanageroverview wxDocManager overview
+ @note The document template has nothing to do with the C++ template construct.
+
+
+
+ @section overview_docview_wxdocmanager wxDocManager overview
- @ref docview_overview
Class: #wxDocManager
+
The wxDocManager class is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocument
- and #wxDocTemplate classes.
- A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document
- and template instances, and much functionality is routed through this object, such
- as providing selection and file dialogs. The application can use this class 'as is' or
- derive a class and override some members to extend or change the functionality.
+ and cooperates with the #wxView, #wxDocument and #wxDocTemplate classes.
+
+ A wxDocManager instance coordinates documents, views and document templates.
+ It keeps a list of document and template instances, and much functionality is routed
+ through this object, such as providing selection and file dialogs.
+ The application can use this class 'as is' or derive a class and override some members
+ to extend or change the functionality.
+
Create an instance of this class near the beginning of your application initialization,
before any documents, views or templates are manipulated.
+
There may be multiple wxDocManager instances in an application.
See the example application in @c samples/docview.
- @section wxcommandoverview wxCommand overview
- @ref docview_overview
+
+ @section overview_docview_wxcommand wxCommand overview
+
Classes: #wxCommand, #wxCommandProcessor
+
wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to
change the data or view.
+
Instead of the application functionality being scattered around
switch statements and functions in a way that may be hard to
read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application.
+
When a user interface event occurs, the application @e submits a command
- to a #wxCommandProcessor object to execute and
- store.
+ to a #wxCommandProcessor object to execute and store.
+
The wxWidgets document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses
for wxCommand, such as implementing a macro facility that stores, loads
and replays commands.
+
An application can derive a new class for every command, or, more likely, use
one class parameterized with an integer or string command identifier.
- @section wxcommandprocessoroverview wxCommandProcessor overview
- @ref docview_overview
+
+ @section overview_docview_wxcommandproc wxCommandProcessor overview
+
Classes: #wxCommandProcessor, #wxCommand
+
wxCommandProcessor is a class that maintains a history of wxCommand
instances, with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour.
- @section wxfilehistoryoverview wxFileHistory overview
- @ref docview_overview
+
+ @section overview_docview_filehistory wxFileHistory overview
+
Classes: #wxFileHistory, #wxDocManager
+
wxFileHistory encapsulates functionality to record the last few files visited, and
to allow the user to quickly load these files using the list appended to the File menu.
Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
to derive from it to allow different behaviour, such as popping up a scrolling
list of files.
- By calling wxFileHistory::UseMenu() you can
- associate a file menu with the file history. The menu will then be used for
- appending filenames that are added to the history. Please notice that currently
- if the history already contained filenames when UseMenu() is called (e.g. when
- initializing a second MDI child frame), the menu is not automatically
+
+ By calling wxFileHistory::UseMenu() you can associate a file menu with the file history.
+ The menu will then be used for appending filenames that are added to the history.
+
+ Please notice that currently if the history already contained filenames when UseMenu()
+ is called (e.g. when initializing a second MDI child frame), the menu is not automatically
initialized with the existing filenames in the history and so you need to call
- #AddFilesToMenu() after UseMenu()
- explicitly in order to initialize the menu with the existing list of MRU files.
- (otherwise an assertion failure is raised in debug builds).
- The filenames are appended using menu identifiers in the range
- @c wxID_FILE1 to @c wxID_FILE9.
+ #AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
+ the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
+
+ The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9.
+
In order to respond to a file load command from one of these identifiers,
you need to handle them using an event handler, for example:
-
@code
BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
{
- wxString f(m_docManager-GetHistoryFile(event.GetId() - wxID_FILE1));
+ wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
if (!f.empty())
(void)m_docManager-CreateDocument(f, wxDOC_SILENT);
}
- @section predefinedids wxWidgets predefined command identifiers
+ @section overview_docview_predefid wxWidgets predefined command identifiers
To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you
to use in menus.
-
+ @verbatim
wxID_OPEN (5000)
wxID_CLOSE (5001)
wxID_NEW (5002)
wxID_PRINT (5010)
wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012)
+ @endverbatim
- */
-
+*/
/*!
- @page printing_overview Printing overview
+ @page overview_printing Printing overview
Classes: #wxPrintout,
#wxPrinter,
projects / wxWidgets.git / commitdiff
