Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

another batch of topic overviews reviewing

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52014 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-02-22 22:05:22 +00:00
parent 975bcfda0d
commit d54cf7ff13
16 changed files with 686 additions and 592 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/doxygen/Doxyfile
View File

@@ -82,6 +82,9 @@ ALIASES += true="<b><tt>true</tt></b>"
ALIASES += false="<b><tt>false</tt></b>" ALIASES += false="<b><tt>false</tt></b>"
ALIASES += NULL="<b><tt>NULL</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 # table aliases for 2 and 3 column tables
ALIASES += beginTable="<center><table class='doctable'>" ALIASES += beginTable="<center><table class='doctable'>"
ALIASES += beginInvisibleTable="<center><table class='doctable' border='0'>" ALIASES += beginInvisibleTable="<center><table class='doctable' border='0'>"
@@ -122,17 +125,20 @@ ALIASES += itemdef{9}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9</td></tr>"
ALIASES += itemdef{10}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9,\10</td></tr>" ALIASES += itemdef{10}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9,\10</td></tr>"
ALIASES += endDefList="</table>" 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 # NOTE: these are important as you can't write in the docs
# just #ifdef since the # character is used by Doxygen # just #ifdef since the # character is used by Doxygen
# for explicit linking; use the following aliases instead! # for explicit linking; use the following aliases instead!
ALIASES += ifdef="<b><tt>\#ifdef</tt></b>" # However to avoid overwriting e.g. \if Doxygen command the _ character is postfixed
ALIASES += ifndef="<b><tt>\#ifndef</tt></b>" ALIASES += ifdef_="<b><tt>\#ifdef</tt></b>"
ALIASES += if="<b><tt>\#if</tt></b>" # NOTE: this overrides the Doxygen \if command ALIASES += ifndef_="<b><tt>\#ifndef</tt></b>"
ALIASES += endif="<b><tt>\#endif</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"
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
@@ -160,7 +166,10 @@ GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES GENERATE_DEPRECATEDLIST= YES
# can contain WXPERL_MANUAL, WXPYTHON_MANUAL keywords
ENABLED_SECTIONS = ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30 MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES SHOW_USED_FILES = YES
SHOW_DIRECTORIES = NO SHOW_DIRECTORIES = NO

18
docs/doxygen/mainpages/const_cpp.h
View File

@@ -15,7 +15,7 @@
by category (and sorted by alphabetical order inside each category). 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 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 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_guisystem
@li @ref page_cppconst_os @li @ref page_cppconst_os
@@ -161,14 +161,14 @@
@itemdef{__VISAGECPP__, IBM Visual Age (OS/2)} @itemdef{__VISAGECPP__, IBM Visual Age (OS/2)}
@itemdef{__VISUALC__, Microsoft Visual C++, see also wxCHECK_VISUALC_VERSION. @itemdef{__VISUALC__, Microsoft Visual C++, see also wxCHECK_VISUALC_VERSION.
The value of this macro corresponds to the compiler version: The value of this macro corresponds to the compiler version:
$1020$ for $4.2$ (the first supported version), $1100$ for @c 1020 for @c 4.2 (the first supported version), @c 1100 for
$5.0$, $1200$ for $6.0$ and so on. For convenience, the symbols @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 __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.} for compiler version being precisely 7.}
@itemdef{__XLC__, AIX compiler} @itemdef{__XLC__, AIX compiler}
@itemdef{__WATCOMC__, Watcom C++. The value of this macro corresponds to @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} @itemdef{_WIN32_WCE, Windows CE version}
@endDefList @endDefList
@@ -208,20 +208,20 @@
@itemdef{wxUSE_XXX, @itemdef{wxUSE_XXX,
if defined as $1$, feature XXX is active, see the if defined as $1$, feature XXX is active, see the
@ref page_wxusedef (the symbols of this form are always defined, @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, @itemdef{WX_PRECOMP,
is defined if precompiled headers (PCH) are in use. In is defined if precompiled headers (PCH) are in use. In
this case, @c wx/wxprec.h includes @c wx/wx.h which, in turn, 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 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 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 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.} 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, @itemdef{wxUSE_GUI,
this particular feature test macro is defined to $1$ this particular feature test macro is defined to $1$
when compiling or using the library with the GUI features activated, 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, @itemdef{wxUSE_BASE,
only used by wxWidgets internally (defined as $1$ when only used by wxWidgets internally (defined as $1$ when
building wxBase code, either as a standalone library or as part of the building wxBase code, either as a standalone library or as part of the

2
docs/doxygen/mainpages/const_wxusedef.h
View File

@@ -16,7 +16,7 @@
category). These symbols are always defined and whether the given feature is 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, 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 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_multi
@li @ref page_wxusedef_unix @li @ref page_wxusedef_unix

2
docs/doxygen/mainpages/topics.h
View File

@@ -93,7 +93,7 @@
@li @subpage overview_html @li @subpage overview_html
@li @subpage overview_richtextctrl @li @subpage overview_richtextctrl
@li @subpage overview_aui @li @subpage overview_aui
@li @subpage overview_commondialogs @li @subpage overview_cmndlg
@li @subpage overview_toolbar @li @subpage overview_toolbar
@li @subpage overview_grid @li @subpage overview_grid
@li @subpage overview_treectrl @li @subpage overview_treectrl

128
docs/doxygen/overviews/commondialogs.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: commondialogs // Name: commondialogs.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,17 +8,16 @@
/*! /*!
@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. 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, They are all 'modal', grabbing the flow of control until the user dismisses the dialog,
to make them easy to use within an application. to make them easy to use within an application.
Some dialogs have both platform-dependent and platform-independent implementations, Some dialogs have both platform-dependent and platform-independent implementations,
so that if underlying windowing systems do not provide the required functionality, 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 the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
@@ -26,24 +25,32 @@
for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog 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 on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
used, for testing or other purposes. 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 Classes: #wxColourDialog, #wxColourData
The wxColourDialog presents a colour selector to the user, and returns The wxColourDialog presents a colour selector to the user, and returns
with colour information. 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 Under Windows, the native colour selector common dialog is used. This
presents a dialog box with three main regions: at the top left, a 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 palette of 48 commonly-used colours is shown. Under this, there is a
@@ -51,7 +58,9 @@
desired. Additionally, the user may open up the dialog box to show 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 a right-hand panel containing controls to select a precise colour, and add
it to the custom colour palette. 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 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 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 standard and 16 custom colours are presented, with the right-hand area
@@ -62,7 +71,9 @@
are not optional in the generic colour selector. The generic colour are not optional in the generic colour selector. The generic colour
selector is also available under MS Windows; use the name selector is also available under MS Windows; use the name
wxGenericColourDialog. wxGenericColourDialog.
@b Example
@subsection overview_cmndlg_colour_example Example
In the samples/dialogs directory, there is an example of using In the samples/dialogs directory, there is an example of using
the wxColourDialog class. Here is an excerpt, which the wxColourDialog class. Here is an excerpt, which
sets various parameters of a wxColourData object, including sets various parameters of a wxColourData object, including
@@ -72,14 +83,14 @@
@code @code
wxColourData data; wxColourData data;
data.SetChooseFull(@true); data.SetChooseFull(true);
for (int i = 0; i 16; i++) for (int i = 0; i 16; i++)
{ {
wxColour colour(i*16, i*16, i*16); wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour); data.SetCustomColour(i, colour);
} }
wxColourDialog dialog(this, ); wxColourDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK) if (dialog.ShowModal() == wxID_OK)
{ {
wxColourData retData = dialog.GetColourData(); wxColourData retData = dialog.GetColourData();
@@ -93,12 +104,15 @@
@section wxfontdialogoverview wxFontDialog overview @section overview_cmndlg_font wxFontDialog overview
Classes: #wxFontDialog, #wxFontData Classes: #wxFontDialog, #wxFontData
The wxFontDialog presents a font selector to the user, and returns The wxFontDialog presents a font selector to the user, and returns
with font and colour information. 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 Under Windows, the native font selector common dialog is used. This
presents a dialog box with controls for font name, point size, style, weight, presents a dialog box with controls for font name, point size, style, weight,
underlining, strikeout and text foreground colour. A sample of the underlining, strikeout and text foreground colour. A sample of the
@@ -107,13 +121,17 @@
conventions, strikeout is ignored and a font family (such as conventions, strikeout is ignored and a font family (such as
Swiss or Modern) is deduced from the actual font name (such as Arial Swiss or Modern) is deduced from the actual font name (such as Arial
or Courier). 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. Under non-MS Windows platforms, the font selector is simpler.
Controls for font family, point size, style, weight, Controls for font family, point size, style, weight,
underlining and text foreground colour are provided, and underlining and text foreground colour are provided, and
a sample is shown upon a white background. The generic font selector a sample is shown upon a white background. The generic font selector
is also available under MS Windows; use the name wxGenericFontDialog. 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 In the samples/dialogs directory, there is an example of using
the wxFontDialog class. The application uses the returned font the wxFontDialog class. The application uses the returned font
and colour for drawing text on a canvas. Here is an excerpt: and colour for drawing text on a canvas. Here is an excerpt:
@@ -123,7 +141,7 @@
data.SetInitialFont(canvasFont); data.SetInitialFont(canvasFont);
data.SetColour(canvasTextColour); data.SetColour(canvasTextColour);
wxFontDialog dialog(this, ); wxFontDialog dialog(this, &data);
if (dialog.ShowModal() == wxID_OK) if (dialog.ShowModal() == wxID_OK)
{ {
wxFontData retData = dialog.GetFontData(); wxFontData retData = dialog.GetFontData();
@@ -134,33 +152,42 @@
@endcode @endcode
@section wxprintdialogoverview wxPrintDialog overview
@section overview_cmndlg_print wxPrintDialog overview
Classes: #wxPrintDialog, #wxPrintData Classes: #wxPrintDialog, #wxPrintData
This class represents the print and print setup common dialogs. This class represents the print and print setup common dialogs.
You may obtain a #wxPrinterDC device context from You may obtain a #wxPrinterDC device context from
a successfully dismissed print dialog. 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. an excerpt from this example.
@section wxfiledialogoverview wxFileDialog overview
@section overview_cmndlg_file wxFileDialog overview
Classes: #wxFileDialog Classes: #wxFileDialog
Pops up a file selector box. In Windows and GTK2.4+, this is the common 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 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. 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 "", If path is "", the current directory will be used. If filename is "",
no default filename will be supplied. The wildcard determines what files no default filename will be supplied. The wildcard determines what files
are displayed in the file selector, and file extension supplies a type 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, 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_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0. wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.
Both the X and Windows versions implement a wildcard filter. Typing a Both the X and Windows versions implement a wildcard filter. Typing a
filename containing wildcards (*, ?) in the filename text item, and filename containing wildcards (*, ?) in the filename text item, and
clicking on Ok, will result in only those files matching the pattern being 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 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 wildcard filter being inserted in the filename text item; the filter is
ignored if a default name is supplied. ignored if a default name is supplied.
The wildcard may be a specification for multiple The wildcard may be a specification for multiple
types of file with a description for each, such as: types of file with a description for each, such as:
@@ -169,45 +196,62 @@
@endcode @endcode
@section wxdirdialogoverview wxDirDialog overview
@section overview_cmndlg_dir wxDirDialog overview
Classes: #wxDirDialog 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 Classes: #wxTextEntryDialog
This is a dialog with a text entry field. The value that the user This is a dialog with a text entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue. entered is obtained using wxTextEntryDialog::GetValue.
@section wxpasswordentrydialogoverview wxPasswordEntryDialog overview
@section overview_cmndlg_password wxPasswordEntryDialog overview
Classes: #wxPasswordEntryDialog Classes: #wxPasswordEntryDialog
This is a dialog with a password entry field. The value that the user This is a dialog with a password entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue. entered is obtained using wxTextEntryDialog::GetValue.
@section wxmessagedialogoverview wxMessageDialog overview
@section overview_cmndlg_msg wxMessageDialog overview
Classes: #wxMessageDialog Classes: #wxMessageDialog
This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No. 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. Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.
The return value of wxMessageDialog::ShowModal indicates The return value of wxMessageDialog::ShowModal indicates
which button the user pressed. which button the user pressed.
@section wxsinglechoicedialogoverview wxSingleChoiceDialog overview
@section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
Classes: #wxSingleChoiceDialog Classes: #wxSingleChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can 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, select one of them. The selection can be obtained from the dialog as an index,
a string or client data. a string or client data.
@section wxmultichoicedialogoverview wxMultiChoiceDialog overview
@section overview_cmndlg_multichoice wxMultiChoiceDialog overview
Classes: #wxMultiChoiceDialog Classes: #wxMultiChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one or more of them. select one or more of them.
*/ */

38
docs/doxygen/overviews/config.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: config // Name: config.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,51 +8,55 @@
/*! /*!
@page config_overview wxConfig classes overview @page overview_config wxConfig classes overview
Classes: #wxConfig Classes: #wxConfig
This overview briefly describes what the config classes are and what they are 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 for. All the details about how to use them may be found in the description of
the #wxConfigBase class and the documentation of the the #wxConfigBase class and the documentation of the
file, registry and INI file based implementations mentions all the file, registry and INI file based implementations mentions all the
features/limitations specific to each one of these versions. features/limitations specific to each one of these versions.
The config classes provide a way to store some application configuration The config classes provide a way to store some application configuration
information. They were especially designed for this usage and, although may 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 probably be used for many other things as well, should be limited to it. It
means that this information should be: means that this information should be:
@li Typed, i.e. strings or numbers for the moment.
Typed, i.e. strings or numbers for the moment. You can not store You can not store binary data, for example.
binary data, for example. @li Small. For instance, it is not recommended to use the Windows
Small. For instance, it is not recommended to use the Windows
registry for amounts of data more than a couple of kilobytes. registry for amounts of data more than a couple of kilobytes.
Not performance critical, neither from speed nor from a memory @li Not performance critical, neither from speed nor from a memory
consumption point of view. consumption point of view.
On the other hand, the features provided make them very useful for storing all On the other hand, the features provided make them very useful for storing all
kinds of small to medium volumes of hierarchically-organized, heterogeneous kinds of small to medium volumes of hierarchically-organized, heterogeneous
data. In short, this is a place where you can conveniently stuff all your data data. In short, this is a place where you can conveniently stuff all your data
(numbers and strings) organizing it in a tree where you use the (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 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. 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 From another point of view, they provide an interface which hides the
differences between the Windows registry and the standard Unix text format differences between the Windows registry and the standard Unix text format
configuration files. Other (future) implementations of wxConfigBase might also configuration files. Other (future) implementations of wxConfigBase might also
understand GTK resource files or their analogues on the KDE side. understand GTK resource files or their analogues on the KDE side.
In any case, each implementation of wxConfigBase does its best to 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 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. 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 There are groups of entries and the entries themselves. Each entry contains either
timestamps is planned) and is identified by the full path to it: something a string or a number (or a boolean value; support for other types of data such as
like /MyApp/UserPreferences/Colors/Foreground. The previous elements in the dates or timestamps is planned) and is identified by the full path to it: something
path are the group names, and each name may contain an arbitrary number of entries like /MyApp/UserPreferences/Colors/Foreground.
and subgroups. The path components are @b always separated with a slash,
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 even though some implementations use the backslash internally. Further
details (including how to read/write these entries) may be found in details (including how to read/write these entries) may be found in
the documentation for #wxConfigBase. the documentation for #wxConfigBase.
*/ */

63
docs/doxygen/overviews/constraints.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: constraints // Name: constraints.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,17 +8,19 @@
/*! /*!
@page constraints_overview Constraints overview @page overview_constraints Constraints overview
Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint. 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 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 way it is laid out, with respect to its siblings or the parent.
The class consists of the following eight constraints of class wxIndividualLayoutConstraint, The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
some or all of which should be accessed directly to set the appropriate some or all of which should be accessed directly to set the appropriate
constraints. constraints.
@b left: represents the left hand edge of the window @b left: represents the left hand edge of the window
@b right: represents the right 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 top: represents the top edge of the window
@@ -28,45 +30,52 @@
@b centreX: represents the horizontal centre point of the window @b centreX: represents the horizontal centre point of the window
@b centreY: represents the vertical 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, The constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints. 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 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 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. 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 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 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 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 often have the default size (e.g. the buttons whose size is determined by their
label). label).
The constrains calculation is done in wxWindow::Layout
function which evaluates constraints. To call it you can either call The constrains calculation is done in wxWindow::Layout function which evaluates
wxWindow::SetAutoLayout if the parent window constraints. To call it you can either call wxWindow::SetAutoLayout if the parent
is a frame, panel or a dialog to tell default OnSize handlers to call Layout 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 automatically whenever the window size changes, or override OnSize and call
Layout yourself (note that you do have to call Layout yourself (note that you do have to call #Layout yourself if the parent
#Layout yourself if the parent window is not a window is not a frame, panel or dialog).
frame, panel or dialog).
@ref constraintlayoutdetails_overview @li @ref overview_constraints_layout
@ref layoutexamples_overview @li @ref overview_constraints_examples
@section constraintlayoutdetails Constraint layout: more details <hr>
@section overview_constraints_layout Constraint layout: more details
By default, windows do not have a wxLayoutConstraints object. In this case, much layout 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 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 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 statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
takes care of resizing the child to always fill the frame. takes care of resizing the child to always fill the frame.
To avoid the need for these rather awkward calculations, the user can create 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. 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, 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, 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. 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 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 the children of a window, then the layout for the grandchildren, and so on.
on. Note that this differs markedly from native Motif layout, where
Note that this differs markedly from native Motif layout, where
constraints can ripple upwards and can eventually change the frame constraints can ripple upwards and can eventually change the frame
window or dialog box size. We assume in wxWidgets that the @e user is 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 always 'boss' and specifies the size of the outer window, to which
@@ -74,15 +83,17 @@
circumstances, but it suffices for most situations, and the circumstances, but it suffices for most situations, and the
simplification avoids some of the nightmarish problems associated with simplification avoids some of the nightmarish problems associated with
programming Motif. programming Motif.
When the user sets constraints, many of the constraints for windows When the user sets constraints, many of the constraints for windows
edges and dimensions remain unconstrained. For a given window, edges and dimensions remain unconstrained. For a given window,
the wxWindow::Layout algorithm first resets all constraints the wxWindow::Layout algorithm first resets all constraints
in all children to have unknown edge or dimension values, and then iterates through the constraints, in all children to have unknown edge or dimension values, and then iterates
evaluating them. For unconstrained edges and dimensions, it through the constraints, evaluating them. For unconstrained edges and dimensions,
tries to find the value using known relationships that always hold. For example, 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 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 both are currently known. For edges and dimensions with user-supplied constraints, these
constraints are evaluated if the inputs of the constraint are known. constraints are evaluated if the inputs of the constraint are known.
The algorithm stops when all child edges and dimension are known (success), or 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). 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. It then sets all the window positions and sizes according to the values it has found.
@@ -96,10 +107,11 @@
specifying that it should be LeftOf() the second one than to do in a more specifying that it should be LeftOf() the second one than to do in a more
natural left-to-right order. 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, This example specifies a panel and a window side by side,
with a text subwindow below it. with a text subwindow below it.
@@ -140,7 +152,7 @@
@endcode @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 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 it horizontally. A listbox and multitext item are placed below it. The listbox
@@ -179,6 +191,5 @@
mtext-SetConstraints(b3); mtext-SetConstraints(b3);
@endcode @endcode
*/ */

50
docs/doxygen/overviews/container.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: container // Name: container.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,48 +8,57 @@
/*! /*!
@page container_overview Container classes overview @page overview_container Container classes overview
Classes: #wxListT, #wxArrayT, #wxVectorT Classes: #wxListT, #wxArrayT, #wxVectorT
wxWidgets uses itself several container classes including doubly-linked lists wxWidgets uses itself several container classes including doubly-linked lists
and dynamic arrays (i.e. arrays which expand automatically when they become and dynamic arrays (i.e. arrays which expand automatically when they become
full). For both historical and portability reasons wxWidgets does not full). For both historical and portability reasons wxWidgets does not use STL
use STL which provides the standard implementation of many container classes in which provides the standard implementation of many container classes in C++.
C++. First of all, wxWidgets has existed since well before STL was written, and
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 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 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 will allow to base future versions of wxWidgets on STL - but this is not yet
the case. the case.
wxWidgets container classes don't pretend to be as powerful or full as STL 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++ 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 compiler. They're used internally by wxWidgets, but may, of course, be used in
your programs as well if you wish. your programs as well if you wish.
The list classes in wxWidgets are doubly-linked lists which may either own the 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 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 removed from the list or the list itself is destroyed) or just store the
pointers depending on whether you called or not pointers depending on whether you called or not wxList::DeleteContents method.
wxList::DeleteContents method.
Dynamic arrays resemble C arrays but with two important differences: they Dynamic arrays resemble C arrays but with two important differences: they
provide run-time range checking in debug builds and they automatically expand 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 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", 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 "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
own the object pointers to which they store. own the object pointers to which they store.
For the same portability reasons, the container classes implementation in wxWidgets 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 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 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 lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
the dynamic arrays. The "DECLARE" macro declares a the dynamic arrays.
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" The "DECLARE" macro declares a new container class containing the elements of
classes must be inserted in your program in a place where the @b full given type and is needed for all three types of container classes: lists,
declaration of container element class is in scope (i.e. not just forward arrays and objarrays. The "DEFINE" classes must be inserted in your program
declaration), otherwise destructors of the container elements will not be in a place where the @b full declaration of container element class is in scope
called! As array classes never delete the items they contain anyhow, there is (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. 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 Finally, wxWidgets predefines several commonly used container classes. wxList
is defined for compatibility with previous versions as a list containing 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 wxObjects and wxStringList as a list of C-style strings (char *), both of these
@@ -57,9 +66,6 @@
array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
wxArrayString. The first three store elements of corresponding types, but wxArrayString. The first three store elements of corresponding types, but
wxArrayString is somewhat special: it is an optimized version of wxArray which wxArrayString is somewhat special: it is an optimized version of wxArray which
uses its knowledge about #wxString reference counting uses its knowledge about #wxString reference counting schema.
schema.
*/
*/

65
docs/doxygen/overviews/dataobject.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dataobject // Name: dataobject.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,20 +8,19 @@
/*! /*!
@page dataobject_overview wxDataObject overview @page overview_dataobject wxDataObject overview
Classes: #wxDataObject, Classes: #wxDataObject, #wxClipboard, #wxDataFormat, #wxDropSource, #wxDropTarget
#wxClipboard,
#wxDataFormat, See also: @ref overview_dnd and @ref overview_samplednd
#wxDropSource,
#wxDropTarget This overview discusses data transfer through clipboard or drag and drop.
See also: @ref dnd_overview and @ref samplednd_overview In wxWidgets, these two ways to transfer data (either between different
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 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 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 words, if you implement drag and drop support for your application, you get
clipboard support for free and vice versa. clipboard support for free and vice versa.
At the heart of both clipboard and drag and drop operations lies the At the heart of both clipboard and drag and drop operations lies the
#wxDataObject class. The objects of this class (or, to #wxDataObject class. The objects of this class (or, to
be precise, classes derived from it) represent the data which is being carried be precise, classes derived from it) represent the data which is being carried
@@ -31,50 +30,50 @@
render itself in any of them (see GetDataHere). It can also receive its value 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. from the outside in a format it supports if it implements the SetData method.
Please see the documentation of this class for more details. Please see the documentation of this class for more details.
Both clipboard and drag and drop operations have two sides: the source and 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 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 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 one position to another in a word processor. Let us describe what each of them
should do. 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 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 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 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 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 other hand, the object for drag and drop operation must only exist while
#DoDragDrop executes and may be safely deleted #DoDragDrop executes and may be safely deleted afterwards and so can be
afterwards and so can be created either on heap or on stack (i.e. as a local created either on heap or on stack (i.e. as a local variable).
variable).
Another small difference is that in the case of clipboard operation, the 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 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 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 chose. But for drag and drop it can only know it after
#DoDragDrop returns (from its return value). #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 To receive (paste in usual terminology) data from the clipboard, you should
create a #wxDataObject derived class which supports the create a #wxDataObject derived class which supports the data formats you need
data formats you need and pass it as argument to and pass it as argument to wxClipboard::GetData. If it returns @false,
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.
*/ 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.
*/

201
docs/doxygen/overviews/datetime.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: datetime // Name: datetime.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,100 +8,64 @@
/*! /*!
@page datetime_overview Date and time classes overview @page overview_datetime Date and time classes overview
Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
#Introduction
@ref alldatetimeclasses_overview @li @ref overview_datetime_introduction
@ref datetimecharacteristics_overview @li @ref overview_datetime_classes
@ref dateandtimespansdifference_overview @li @ref overview_datetime_characteristics
@ref tdatearithm_overview @li @ref overview_datetime_timespandiff
@ref tdatetimezones_overview @li @ref overview_datetime_arithmetics
#Daylight saving time (DST) @li @ref overview_datetime_timezones
@ref tdateholidays_overview @li @ref overview_datetime_dst
#Compatibility @li @ref overview_datetime_holidays
@li @ref overview_datetime_compat
@section introductiontowxdatetime Introduction <hr>
@section overview_datetime_introduction Introduction
wxWidgets provides a set of powerful classes to work with dates and times. Some wxWidgets provides a set of powerful classes to work with dates and times. Some
of the supported features of #wxDateTime class are: of the supported features of #wxDateTime class are:
@li Wide range: the range of supported dates goes from about 4714 B.C. to
Wide range
The range of supported dates goes from about 4714 B.C. to
some 480 million years in the future. some 480 million years in the future.
@li Precision: not using floating point calculations anywhere ensures that
Precision
Not using floating point calculations anywhere ensures that
the date calculations don't suffer from rounding errors. the date calculations don't suffer from rounding errors.
@li Many features: not only all usual calculations with dates are supported,
Many features
Not only all usual calculations with dates are supported,
but also more exotic week and year day calculations, work day testing, standard 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 astronomical functions, conversion to and from strings in either strict or free
format. format.
@li Efficiency: objects of wxDateTime are small (8 bytes) and working with
Efficiency
Objects of wxDateTime are small (8 bytes) and working with
them is fast them is fast
@section overview_datetime_classes 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.
@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 also helper classes which are used together with wxDateTime: There are also helper classes which are used together with wxDateTime:
#wxDateTimeHolidayAuthority which is used #wxDateTimeHolidayAuthority which is used to determine whether a given date
to determine whether a given date is a holiday or not and is a holiday or not and #wxDateTimeWorkDays which is a derivation of this
#wxDateTimeWorkDays which is a derivation of this
class for which (only) Saturdays and Sundays are the holidays. See more about class for which (only) Saturdays and Sundays are the holidays. See more about
these classes in the discussion of the #holidays. these classes in the discussion of the #holidays.
Finally, in other parts of this manual you may find mentions of wxDate and 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. superseded by wxDateTime.
@section wxdatetimecharacteristics wxDateTime characteristics
@section overview_datetime_characteristics wxDateTime characteristics
#wxDateTime stores the time as a signed number of #wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 - milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
@@ -109,15 +73,17 @@
the Epoch are handled just as well (or as bad) as the dates after it). But it 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 does mean that the best resolution which can be achieved with this class is 1
millisecond. millisecond.
The size of wxDateTime object is 8 bytes because it is represented as a 64 bit 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 integer. The resulting range of supported dates is thus approximatively 580
million years, but due to the current limitations in the Gregorian calendar 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 support, only dates from Nov 24, 4714BC are supported (this is subject to
change if there is sufficient interest in doing it). change if there is sufficient interest in doing it).
Finally, the internal representation is time zone independent (always in GMT) 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 and the time zones only come into play when a date is broken into
year/month/day components. See more about #timezones year/month/day components. See more about #timezones below.
below.
Currently, the only supported calendar is Gregorian one (which is used even 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 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 first done on Oct 15, 1582 but is, generally speaking, country, and even
@@ -125,20 +91,25 @@
as well and support for other calendars (Maya, Hebrew, Chinese...) is not as well and support for other calendars (Maya, Hebrew, Chinese...) is not
ruled out. 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 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 time (and hence only one wxDateTime class), there are at least two methods to
describe a time interval. describe a time interval.
First, there is the direct and self-explaining way implemented by First, there is the direct and self-explaining way implemented by
#wxTimeSpan: it is just a difference in milliseconds #wxTimeSpan: it is just a difference in milliseconds
between two moments in time. Adding or subtracting such an interval to between two moments in time. Adding or subtracting such an interval to
wxDateTime is always well-defined and is a fast operation. wxDateTime is always well-defined and is a fast operation.
But in the daily life other, calendar-dependent time interval specifications are 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 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 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 month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
the year is leap or not). the year is leap or not).
This is why there is another class for representing such intervals called This is why there is another class for representing such intervals called
#wxDateSpan. It handles these sort of operations in the #wxDateSpan. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals of most natural way possible, but note that manipulating with intervals of
@@ -148,82 +119,47 @@
still might be surprised to notice that now subtracting back the same 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 interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
with! with!
So, unless you plan to implement some kind of natural language parsing in the 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 program, you should probably use wxTimeSpan instead of wxDateSpan (which is
also more efficient). However, wxDateSpan may be very useful in situations 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 when you do need to understand what 'in a month' means (of course, it is
just @c wxDateTime::Now() + wxDateSpan::Month()). 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 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 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 operation, even though multiplying either of the time span classes by a number
is perfectly valid. 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
@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 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. can be added together giving another object of the same class.
@li @b Subtraction: the same types of operations as above are
@b Subtraction
the same types of operations as above are
allowed and, additionally, a difference between two wxDateTime objects can be allowed and, additionally, a difference between two wxDateTime objects can be
taken and this will yield wxTimeSpan. taken and this will yield wxTimeSpan.
@li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
@b Multiplication
a wxTimeSpan or wxDateSpan object can be
multiplied by an integer number resulting in an object of the same type. multiplied by an integer number resulting in an object of the same type.
@li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
@b Unary minus
a wxTimeSpan or wxDateSpan object may finally be
negated giving an interval of the same magnitude but of opposite time negated giving an interval of the same magnitude but of opposite time
direction. direction.
For all these operations there are corresponding global (overloaded) operators For all these operations there are corresponding global (overloaded) operators
and also member functions which are synonyms for them: Add(), Subtract() and and also member functions which are synonyms for them: Add(), Subtract() and
Multiply(). Unary minus as well as composite assignment operations (like +=) Multiply(). Unary minus as well as composite assignment operations (like +=)
are only implemented as members and Neg() is the synonym for unary minus. 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 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 the local time zone. Because of this, all wxDateTime constructors and setters
@@ -234,28 +170,31 @@
second...) will also return the correct values for the local time zone by 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 default, so, generally, doing the natural things will lead to natural and
correct results. correct results.
If you only want to do this, you may safely skip the rest of this section. 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 However, if you want to work with different time zones, you should read it to
the end. the end.
In this (rare) case, you are still limited to the local time zone when 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 constructing wxDateTime objects, i.e. there is no way to construct a
wxDateTime corresponding to the given date in, say, Pacific Standard Time. wxDateTime corresponding to the given date in, say, Pacific Standard Time.
To do it, you will need to call #ToTimezone or To do it, you will need to call #ToTimezone or #MakeTimezone methods to adjust
#MakeTimezone methods to adjust the date for the date for the target time zone. There are also special versions of these functions
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.
#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 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 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 methods which are affected by the time zone (all methods getting date
components and the date formatting ones, for example). In particular, the components and the date formatting ones, for example). In particular, the
Format() family of methods accepts a TimeZone parameter and this allows to Format() family of methods accepts a TimeZone parameter and this allows to
simply print time in any time zone. simply print time in any time zone.
To see how to do it, the last issue to address is how to construct a TimeZone 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 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 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. let the conversion constructor do the job.
I.e. you would just write I.e. you would just write
@code @code
@@ -265,33 +204,39 @@
@endcode @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 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 left to the operating system which is supposed to be configured by the
administrator to behave correctly. Unfortunately, when doing calculations with administrator to behave correctly. Unfortunately, when doing calculations with
date outside of the range supported by the standard library, we are forced to date outside of the range supported by the standard library, we are forced to
deal with these issues ourselves. deal with these issues ourselves.
Several functions are provided to calculate the beginning and end of DST in 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 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 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 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 (any information about other ones appreciated!) and even for them the rules
may perfectly well change in the future. may perfectly well change in the future.
The time zone handling #methods use these functions The time zone handling #methods use these functions
too, so they are subject to the same limitations. too, so they are subject to the same limitations.
@section tdateholidays wxDateTime and Holidays
@section overview_datetime_holidays wxDateTime and Holidays
TODO. TODO.
@section tdatecompatibility Compatibility
@section overview_datetime_compat Compatibility
The old classes for date/time manipulations ported from wxWidgets version 1.xx 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 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 them is strongly discouraged because they have a few quirks/bugs and were not
'Y2K' compatible. 'Y2K' compatible.
*/ */

34
docs/doxygen/overviews/dc.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dc // Name: dc.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,30 +8,29 @@
/*! /*!
@page dc_overview Device context overview @page overview_dc Device context overview
Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC, Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
#wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxScreenDC, #wxClientDC,
#wxScreenDC, #wxClientDC, #wxPaintDC, #wxPaintDC, #wxWindowDC.
#wxWindowDC.
A wxDC is a @e device context onto which graphics and text can be drawn. 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, The device context is intended to represent a number of output devices in a
with the same API being used throughout. generic way, with the same API being used throughout.
Some device contexts are created temporarily in order to draw on a window. Some device contexts are created temporarily in order to draw on a window.
This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC, This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC, and #wxWindowDC.
and #wxWindowDC. The following describes the differences between The following describes the differences between these device contexts and
these device contexts and when you should use them. when you should use them.
@li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
@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
@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. 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 @li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
within a #wxPaintEvent. within a #wxPaintEvent.
@b wxWindowDC. Use this to paint on the whole area of a window, including decorations. @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. 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 To use a client, paint or window device context, create an object on the stack with
the window as argument, for example: the window as argument, for example:
@@ -48,6 +47,5 @@
work for everything (for example not all device contexts support bitmap drawing) but work for everything (for example not all device contexts support bitmap drawing) but
will work most of the time. will work most of the time.
*/ */

77
docs/doxygen/overviews/debugging.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: debugging // Name: debugging.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,22 +8,29 @@
/*! /*!
@page debugging_overview Debugging overview @page overview_debugging Debugging overview
Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog, 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 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. Most of these are only available if you compile both wxWidgets,
your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol 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 defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
code that should be active only in debug mode. 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 #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 various static functions and variables. It allows you to dump all objects to that stream,
check memory for errors. 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 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 from a wxWidgets class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application. give valuable information about the state of the application.
If you have difficulty tracking down a memory leak, recompile If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
appropriate places. They will tell you what objects have not yet been appropriate places. They will tell you what objects have not yet been
@@ -32,65 +39,75 @@
will give you information about the problem. (How much information depends on the operating system 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 and compiler -- some systems don't allow all memory logging to be enabled). See the
memcheck sample for example of usage. 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 For wxDebugContext to do its work, the @e new and @e delete operators for wxObject
about dynamically allocated objects (but not statically declared have been redefined to store extra information about dynamically allocated objects
objects). This slows down a debugging version of an application, but can (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 find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object). underwrites (writing to memory in front of the object).
If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and 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: wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
@code @code
#define new new(__FILE__,__LINE__) #define new new(__FILE__,__LINE__)
@endcode @endcode
All occurrences of 'new' in wxWidgets and your own application will use 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 the overridden form of the operator with two extra arguments. This means that
output (and error messages reporting memory problems) will tell you what 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 file and on what line you allocated the object. Unfortunately not all
compilers allow this definition to work properly, but most do. 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, 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 scattering wxASSERTs liberally to test for problems in your code as early as possible.
will save a surprising amount of time in the long run. 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 #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 is not @true. You can also use #wxASSERT_MSG to supply your
own helpful error message. For example: own helpful error message. For example:
@code @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 @endcode
The message box allows you to continue execution or abort the program. If you are running 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. 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 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 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 no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output); to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call (for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity. Check to check memory blocks for integrity.
Here's an example of use. The SetCheckpoint ensures that only the Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped. allocations done after the checkpoint will be dumped.
@@ -111,9 +128,9 @@
at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled 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 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. just to make use of the error logging facility.
Note: wxDebugContext::SetFile has a problem at present, so use the default stream 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. Eventually the logging will be done through the wxLog facilities instead.
*/ */

143
docs/doxygen/overviews/dialog.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dialog // Name: dialog.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,96 +8,121 @@
/*! /*!
@page dialog_overview wxDialog overview @page overview_dialog wxDialog overview
Classes: #wxDialog, #wxDialogLayoutAdapter Classes: #wxDialog, #wxDialogLayoutAdapter
A dialog box is similar to a panel, in that it is a window which can 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: be used for placing controls, with the following exceptions:
@li A surrounding frame is implicitly created.
A surrounding frame is implicitly created. @li Extra functionality is automatically given to the dialog box,
Extra functionality is automatically given to the dialog box,
such as tabbing between items (currently Windows only). such as tabbing between items (currently Windows only).
If the dialog box is @e modal, the calling program is blocked @li If the dialog box is @e modal, the calling program is blocked
until the dialog box is dismissed. until the dialog box is dismissed.
For a set of dialog convenience functions, including file selection, see For a set of dialog convenience functions, including file selection, see
@ref dialogfunctions_overview. @ref overview_dialogfunctions.
See also #wxTopLevelWindow and #wxWindow for inherited See also #wxTopLevelWindow and #wxWindow for inherited
member functions. Validation of data in controls is covered in @ref validator_overview. member functions. Validation of data in controls is covered in @ref overview_validator.
@ref autoscrollingdialogs_overview
@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 @section overview_dialog_autoscrolling Automatic scrolling dialogs
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 As an ever greater variety of mobile hardware comes to market, it becomes more
a global #wxDialogLayoutAdapter class that implements automatic scrolling adaptation for most sizer-based custom dialogs. imperative for wxWidgets applications to adapt to these platforms without putting
Many applications should therefore be able to adapt to small displays with little or no work, as far as dialogs are concerned. too much burden on the programmer. One area where wxWidgets can help is in adapting
By default this adaptation is off. To switch scrolling adaptation on globally in your application, call the static function dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
wxDialog::EnableLayoutAdaptation passing @true. You can also adjust adaptation on a per-dialog basis by calling wxDialog therefore supplies a global #wxDialogLayoutAdapter class that implements
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. 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. 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 With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
standard adapter class wxStandardDialogLayoutAdapter) will standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog. 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: 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,
If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, the pages are made scrollable and the pages are made scrollable and no other adaptation is done.
no other adaptation is done. @li wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
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
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. 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. @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. 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, @li All the children apart from standard buttons are reparented onto a new #wxScrolledWindow
using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and object, using the old top-level sizer for the scrolled window and creating a new top-level
standard button sizer. sizer to lay out the scrolled window and standard button sizer.
@b Customising scrolling adaptation @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, In addition to switching adaptation on and off globally and per dialog,
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 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 You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
treated as standard buttons for the non-scrolling area. treated as standard buttons for the non-scrolling area.
You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override 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. the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation in a class derived from wxDialog. and perform the adaptation.
@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. You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation
in a class derived from wxDialog.
The dialog doesn't use sizers. @subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
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, Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
you can derive a new adapter class from wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return an instance of your own class. and may fail in the following situations:
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 @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. until Show or ShowModal is called.
You can help make sure that your dialogs will continue to function after adaptation by: You can help make sure that your dialogs will continue to function after adaptation by:
@li avoiding the above situations and assumptions;
avoiding the above situations and assumptions; @li using #wxStdDialogButtonSizer;
using #wxStdDialogButtonSizer; @li only making assumptions about hierarchy immediately after the dialog is created;
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
using an intermediate sizer under the main sizer, a @false top-level sizer that can be relied on to exist can be relied on to exist for the purposes of manipulating child sizers and windows;
for the purposes of manipulating child sizers and windows; @li overriding wxDialog::GetContentWindow to return a book control if your dialog implements
overriding wxDialog::GetContentWindow to return a book control if your dialog implements pages: wxWidgets will then only make the pages pages: wxWidgets will then only make the pages scrollable.
scrollable.
@b wxPropertySheetDialog and wxWizard @subsection overview_dialog_propertysheet 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.
*/

100
docs/doxygen/overviews/dnd.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dnd // Name: dnd.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,90 +8,88 @@
/*! /*!
@page dnd_overview Drag and drop overview @page overview_dnd Drag and drop overview
Classes: #wxDataObject, Classes: #wxDataObject, #wxTextDataObject, #wxDropSource, #wxDropTarget,
#wxTextDataObject, #wxTextDropTarget, #wxFileDropTarget
#wxDropSource,
#wxDropTarget, Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
#wxTextDropTarget,
#wxFileDropTarget
Note that wxUSE_DRAG_AND_DROP must be defined in setup.h in order
to use drag and drop in wxWidgets. 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 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 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 these two types is almost the same. In particular, both data transfer
mechanisms store data in some kind of #wxDataObject mechanisms store data in some kind of #wxDataObject and identify its format(s)
and identify its format(s) using the #wxDataFormat using the #wxDataFormat class.
class.
To be a @e drag source, i.e. to provide the data which may be dragged by 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: the user elsewhere, you should implement the following steps:
@li @b Preparation: First of all, a data object must be created and
@b Preparation: First of all, a data object must be created and
initialized with the data you wish to drag. For example: initialized with the data you wish to drag. For example:
@code @code
wxTextDataObject my_data("This text will be dragged."); wxTextDataObject my_data("This text will be dragged.");
@endcode @endcode
@b Drag start: To start the dragging process (typically in response to a @li <b>Drag start</b>: To start the dragging process (typically in response to a
mouse click) you must call wxDropSource::DoDragDrop mouse click) you must call wxDropSource::DoDragDrop like this:
like this:
@code @code
wxDropSource dragSource( this ); wxDropSource dragSource( this );
dragSource.SetData( my_data ); dragSource.SetData( my_data );
wxDragResult result = dragSource.DoDragDrop( TRUE ); wxDragResult result = dragSource.DoDragDrop( true );
@endcode @endcode
@b Dragging: The call to DoDragDrop() blocks the program until the user releases the @li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
mouse button (unless you override the #GiveFeedback function the mouse button (unless you override the #GiveFeedback function to do something
to do something special). When the mouse moves in a window of a program which understands the 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 same drag-and-drop protocol (any program under Windows or any program supporting
XDnD protocol under X Windows), the corresponding #wxDropTarget methods the XDnD protocol under X Windows), the corresponding #wxDropTarget methods
are called - see below. are called - see below.
@b Processing the result: DoDragDrop() returns an @e effect code which
@li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
is one of the values of @c wxDragResult enum (explained #here): is one of the values of @c wxDragResult enum (explained #here):
@code @code
switch (result) switch (result)
{ {
case wxDragCopy: /* copy the data */ break; case wxDragCopy:
case wxDragMove: /* move the data */ // copy the data
break; break;
default: /* do nothing */ case wxDragMove:
break; // move the data
} break;
@endcode 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:
To be a @e drop target, i.e. to receive the data dropped by the user you should @li @b Initialization: For a window to be a drop target, it needs to have
follow the instructions below: 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
@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 wxDropTarget and override its pure virtual methods. Alternatively, you may
derive from #wxTextDropTarget or derive from #wxTextDropTarget or #wxFileDropTarget and override their OnDropText()
#wxFileDropTarget and override their OnDropText()
or OnDropFiles() method. or OnDropFiles() method.
@b Drop: When the user releases the mouse over a window, wxWidgets
@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, asks the associated wxDropTarget object if it accepts the data. For this,
a #wxDataObject must be associated with the drop target a #wxDataObject must be associated with the drop target and this data object will
and this data object will be responsible for the format negotiation between be responsible for the format negotiation between the drag source and the drop target.
the drag source and the drop target. If all goes well, then #OnData If all goes well, then #OnData will get called and the wxDataObject belonging to
will get called and the wxDataObject belonging to the drop target can get the drop target can get filled with data.
filled with data.
@b The end: After processing the data, DoDragDrop() returns either @li <b>The end</b>: After processing the data, DoDragDrop() returns either
wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift 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 and Alt at the moment of the drop. There is currently no way for the drop
target to change this return code. target to change this return code.
*/ */

212
docs/doxygen/overviews/docview.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: docview // Name: docview.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,141 +8,160 @@
/*! /*!
@page docview_overview Document/view overview @page overview_docview Document/view overview
Classes: #wxDocument, #wxView, #wxDocTemplate, Classes: #wxDocument, #wxView, #wxDocTemplate, #wxDocManager, #wxDocParentFrame,
#wxDocManager, #wxDocParentFrame, #wxDocChildFrame, #wxDocChildFrame, #wxDocMDIParentFrame, #wxDocMDIChildFrame,
#wxDocMDIParentFrame, #wxDocMDIChildFrame,
#wxCommand, #wxCommandProcessor #wxCommand, #wxCommandProcessor
The document/view framework is found in most application frameworks, because it The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application. 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 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 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 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. 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. 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 The framework can provide many user-interface elements based on this model.
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 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 modifications, routing menu commands to appropriate (possibly default) code, even
some default print/preview functionality and support for command undo/redo. some default print/preview functionality and support for command undo/redo.
The framework is highly modular, allowing overriding and replacement of functionality The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour. 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:
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 @li Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization. member functions e.g. for input/output, drawing and initialization.
Define any subwindows @li Define any subwindows (such as a scrolled window) that are needed for the view(s).
(such as a scrolled window) that are needed for the view(s). You may need to route some events You may need to route some events to views or documents, for example OnPaint needs
to views or documents, for example OnPaint needs to be routed to wxView::OnDraw. to be routed to wxView::OnDraw.
Decide what style of interface you will use: Microsoft's MDI (multiple @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 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). 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 @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 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). 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 @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 as many wxDocTemplate instances as necessary to define relationships between documents and
views. For a simple application, there will be just one wxDocTemplate. 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 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 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 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. 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 Here are a few examples of the tailoring you can do to go beyond the default framework
behaviour: behaviour:
@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
or a command history editor. or a command history editor.
Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout @li Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
class, to provide multi-page document facilities. class, to provide multi-page document facilities.
Override wxDocManager::SelectDocumentPath to provide a different file selector. @li Override wxDocManager::SelectDocumentPath to provide a different file selector.
Limit the maximum number of open documents and the maximum number of undo commands. @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 Note that to activate framework functionality, you need to use some or all of
the wxWidgets @ref predefinedids_overview in your menus. the wxWidgets @ref predefinedids_overview in your menus.
@b wxPerl note: The document/view framework is available in wxPerl. To use it,
@beginWxPerlOnly
The document/view framework is available in wxPerl. To use it,
you will need the following statements in your application code: you will need the following statements in your application code:
@code @code
use Wx::DocView; use Wx::DocView;
use Wx ':docview'; # import constants (optional) use Wx ':docview'; # import constants (optional)
@endcode @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 <hr>
@ref view_overview
@ref doctemplate_overview
@ref docmanager_overview
@ref command_overview
@ref commandprocessor_overview
@ref filehistory_overview
@ref predefinedids_overview
@section wxdocumentoverview wxDocument overview @section overview_docview_wxdoc wxDocument overview
@ref docview_overview
Class: #wxDocument Class: #wxDocument
The wxDocument class can be used to model an application's file-based 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, data. It is part of the document/view framework supported by wxWidgets,
and cooperates with the #wxView, #wxDocTemplate and cooperates with the #wxView, #wxDocTemplate and #wxDocManager classes.
and #wxDocManager classes.
Using this framework can save a lot of routine user-interface programming, 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 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 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 data, are explicitly separated out in this model, and the concept of multiple
the same data is supported. @e views onto the same data is supported.
Note that the document/view model will suit many but not all styles of application. 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 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 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. files. But probably the majority of applications are document-based.
See the example application in @c samples/docview. See the example application in @c samples/docview.
To use the abstract wxDocument class, you need to derive a new class and override 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 at least the member functions SaveObject and LoadObject. SaveObject and
LoadObject will be called by the framework when the document needs to be saved LoadObject will be called by the framework when the document needs to be saved
or loaded. or loaded.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order 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 to allow the framework to create document objects on demand. When you create
a #wxDocTemplate object on application initialization, you a #wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class. 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 If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument objects dynamically, you must override wxDocTemplate::CreateDocument
to return an instance of the appropriate class. to return an instance of the appropriate class.
@section wxviewoverview wxView overview
@ref docview_overview
@section overview_docview_wxview wxView overview
Class: #wxView Class: #wxView
The wxView class can be used to model the viewing and editing component of 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, an application's file-based data. It is part of the document/view framework
and cooperates with the #wxDocument, #wxDocTemplate supported by wxWidgets, and cooperates with the #wxDocument, #wxDocTemplate
and #wxDocManager classes. and #wxDocManager classes.
See the example application in @c samples/docview. See the example application in @c samples/docview.
To use the abstract wxView class, you need to derive a new class and override 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 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. want to respond to menu commands from the frame containing the view.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order 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 to allow the framework to create view objects on demand. When you create
a #wxDocTemplate object on application initialization, you a #wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class. 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 If you do not wish to use the wxWidgets method of creating view
objects dynamically, you must override wxDocTemplate::CreateView objects dynamically, you must override wxDocTemplate::CreateView
to return an instance of the appropriate class. to return an instance of the appropriate class.
@section wxdoctemplateoverview wxDocTemplate overview
@ref docview_overview
@section overview_docview_wxdoctemplate wxDocTemplate overview
Class: #wxDocTemplate Class: #wxDocTemplate
The wxDocTemplate class is used to model the relationship between a The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document document class and a view class. The application creates a document
template object for each document/view pair. The list of document template object for each document/view pair. The list of document
@@ -150,6 +169,7 @@
documents and views. Each document template knows what file filters documents and views. Each document template knows what file filters
and default extension are appropriate for a document/view combination, and default extension are appropriate for a document/view combination,
and how to create a document or view. and how to create a document or view.
For example, you might write a small doodling application that can load 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 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, and a list of the segments -- then you would create one document class DoodleDocument,
@@ -159,94 +179,112 @@
document templates, but each would be passed a different view class. When 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 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 with a list of possible file filters -- one for each wxDocTemplate. Selecting
the filter selects the wxDocTemplate, and when the filter selects the wxDocTemplate, and when a file is selected, that template
a file is selected, that template will be used for creating a document will be used for creating a document and view.
and view.
For the case where an application has one document type and one view type, 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 a single document template is constructed, and dialogs will be appropriately
simplified. simplified.
wxDocTemplate is part of the document/view framework supported by wxWidgets, wxDocTemplate is part of the document/view framework supported by wxWidgets,
and cooperates with the #wxView, #wxDocument and cooperates with the #wxView, #wxDocument and #wxDocManager classes.
and #wxDocManager classes.
See the example application in @c samples/docview. See the example application in @c samples/docview.
To use the wxDocTemplate class, you do not need to derive a new class. 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 Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass)
CLASSINFO(YourViewClass) to allow dynamic instance creation. and CLASSINFO(YourViewClass) to allow dynamic instance creation.
If you do not wish to use the wxWidgets method of creating document If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class. 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 Class: #wxDocManager
The wxDocManager class is part of the document/view framework supported by wxWidgets, The wxDocManager class is part of the document/view framework supported by wxWidgets,
and cooperates with the #wxView, #wxDocument and cooperates with the #wxView, #wxDocument and #wxDocTemplate classes.
and #wxDocTemplate classes.
A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document A wxDocManager instance coordinates documents, views and document templates.
and template instances, and much functionality is routed through this object, such It keeps a list of document and template instances, and much functionality is routed
as providing selection and file dialogs. The application can use this class 'as is' or through this object, such as providing selection and file dialogs.
derive a class and override some members to extend or change the functionality. 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, Create an instance of this class near the beginning of your application initialization,
before any documents, views or templates are manipulated. before any documents, views or templates are manipulated.
There may be multiple wxDocManager instances in an application. There may be multiple wxDocManager instances in an application.
See the example application in @c samples/docview. See the example application in @c samples/docview.
@section wxcommandoverview wxCommand overview
@ref docview_overview
@section overview_docview_wxcommand wxCommand overview
Classes: #wxCommand, #wxCommandProcessor Classes: #wxCommand, #wxCommandProcessor
wxCommand is a base class for modelling an application command, wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to a toolbar button or any other means provided by the application to
change the data or view. change the data or view.
Instead of the application functionality being scattered around Instead of the application functionality being scattered around
switch statements and functions in a way that may be hard to switch statements and functions in a way that may be hard to
read and maintain, the functionality for a command is explicitly represented read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application. as an object which can be manipulated by a framework or application.
When a user interface event occurs, the application @e submits a command When a user interface event occurs, the application @e submits a command
to a #wxCommandProcessor object to execute and to a #wxCommandProcessor object to execute and store.
store.
The wxWidgets document/view framework handles Undo and Redo by use of The wxWidgets document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses wxCommand and wxCommandProcessor objects. You might find further uses
for wxCommand, such as implementing a macro facility that stores, loads for wxCommand, such as implementing a macro facility that stores, loads
and replays commands. and replays commands.
An application can derive a new class for every command, or, more likely, use An application can derive a new class for every command, or, more likely, use
one class parameterized with an integer or string command identifier. 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 Classes: #wxCommandProcessor, #wxCommand
wxCommandProcessor is a class that maintains a history of wxCommand wxCommandProcessor is a class that maintains a history of wxCommand
instances, with undo/redo functionality built-in. Derive a new class from this instances, with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour. if you want different behaviour.
@section wxfilehistoryoverview wxFileHistory overview
@ref docview_overview
@section overview_docview_filehistory wxFileHistory overview
Classes: #wxFileHistory, #wxDocManager Classes: #wxFileHistory, #wxDocManager
wxFileHistory encapsulates functionality to record the last few files visited, and 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. 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 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 to derive from it to allow different behaviour, such as popping up a scrolling
list of files. list of files.
By calling wxFileHistory::UseMenu() you can
associate a file menu with the file history. The menu will then be used for By calling wxFileHistory::UseMenu() you can associate a file menu with the file history.
appending filenames that are added to the history. Please notice that currently The menu will then be used for appending filenames that are added to the history.
if the history already contained filenames when UseMenu() is called (e.g. when
initializing a second MDI child frame), the menu is not automatically 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 initialized with the existing filenames in the history and so you need to call
#AddFilesToMenu() after UseMenu() #AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
explicitly in order to initialize the menu with the existing list of MRU files. the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
(otherwise an assertion failure is raised in debug builds).
The filenames are appended using menu identifiers in the range The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9.
@c wxID_FILE1 to @c wxID_FILE9.
In order to respond to a file load command from one of these identifiers, 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: you need to handle them using an event handler, for example:
@code @code
BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame) BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit) EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
@@ -260,7 +298,7 @@
void wxDocParentFrame::OnMRUFile(wxCommandEvent& event) 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()) if (!f.empty())
(void)m_docManager-CreateDocument(f, wxDOC_SILENT); (void)m_docManager-CreateDocument(f, wxDOC_SILENT);
} }
@@ -268,13 +306,13 @@
@section predefinedids wxWidgets predefined command identifiers @section overview_docview_predefid wxWidgets predefined command identifiers
To allow communication between the application's menus and the To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you document/view framework, several command identifiers are predefined for you
to use in menus. to use in menus.
@verbatim
wxID_OPEN (5000) wxID_OPEN (5000)
wxID_CLOSE (5001) wxID_CLOSE (5001)
wxID_NEW (5002) wxID_NEW (5002)
@@ -288,7 +326,7 @@
wxID_PRINT (5010) wxID_PRINT (5010)
wxID_PRINT_SETUP (5011) wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012) wxID_PREVIEW (5012)
@endverbatim
*/ */

2
docs/doxygen/overviews/printing.h
View File

@@ -8,7 +8,7 @@
/*! /*!
@page printing_overview Printing overview @page overview_printing Printing overview
Classes: #wxPrintout, Classes: #wxPrintout,
#wxPrinter, #wxPrinter,