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