Fixed appearance images to use Doxygen @image command (Doxygen will now copy files automatically), and cleaned up some more overviews.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72871 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -10,18 +10,10 @@
|
||||
|
||||
@page overview_cpp_rtti_disabled Caveats When Not Using C++ RTTI
|
||||
|
||||
@li @ref overview_cpp_rtti_disabled_intro
|
||||
@li @ref overview_cpp_rtti_disabled_bind
|
||||
@li @ref overview_cpp_rtti_disabled_wxany
|
||||
@tableofcontents
|
||||
|
||||
@see
|
||||
@see @ref overview_rtti, wxEvtHandler::Bind(), wxAny
|
||||
|
||||
@li @ref overview_rtti
|
||||
@li wxEvtHandler::Bind()
|
||||
@li wxAny
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_cpp_rtti_disabled_intro Introduction
|
||||
@@ -43,6 +35,7 @@ created in one physical binary may not be recognized as its correct type when
|
||||
used in another one.
|
||||
|
||||
|
||||
|
||||
@section overview_cpp_rtti_disabled_bind Bind() Issues
|
||||
|
||||
wxWidgets 2.9.0 introduced a new @ref overview_events_bind system, using
|
||||
@@ -57,6 +50,7 @@ Also, if you only bind and unbind same event handler inside same binary, you
|
||||
should be fine.
|
||||
|
||||
|
||||
|
||||
@section overview_cpp_rtti_disabled_wxany wxAny Issues
|
||||
|
||||
wxAny is a dynamic type class which transparently uses templates to generate
|
||||
@@ -92,4 +86,3 @@ library that called the WX_IMPLEMENT_ANY_VALUE_TYPE() macro, and WXIMPORT
|
||||
otherwise.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -8,57 +8,53 @@
|
||||
|
||||
/**
|
||||
|
||||
@page overview_customwidgets Creating a custom widget
|
||||
@page overview_customwidgets Creating a Custom Widget
|
||||
|
||||
@li @ref overview_customwidgets_whenwhy
|
||||
@li @ref overview_customwidgets_how
|
||||
@tableofcontents
|
||||
|
||||
<hr>
|
||||
Typically combining the existing @ref group_class_ctrl controls in wxDialogs
|
||||
and wxFrames is sufficient to fullfill any GUI design. Using the wxWidgets
|
||||
standard controls makes your GUI looks native on all ports and is obviously
|
||||
easier and faster.
|
||||
|
||||
However there are situations where you need to show some particular kind of
|
||||
data which is not suited to any existing control. In these cases rather than
|
||||
hacking an existing control for something it has not been conceived for, it's
|
||||
better to write a new widget.
|
||||
|
||||
|
||||
@section overview_customwidgets_whenwhy When and why you should write your custom widget
|
||||
|
||||
Typically combining the existing @ref group_class_ctrl controls in wxDialogs and
|
||||
wxFrames is sufficient to fullfill any GUI design.
|
||||
Using the wxWidgets standard controls makes your GUI looks native on all ports
|
||||
and is obviously easier and faster.
|
||||
|
||||
However there are situations where you need to show some particular kind of data
|
||||
which is not suited to any existing control.
|
||||
In these cases rather than hacking an existing control for something it has not
|
||||
been conceived for, it's better to write a new widget.
|
||||
|
||||
|
||||
@section overview_customwidgets_how How to write the custom widget
|
||||
@section overview_customwidgets_how Writing a Custom Widget
|
||||
|
||||
There are at least two very different ways to implement a new widget.
|
||||
|
||||
The first is to build it upon wxWidgets existing classes, thus deriving it from
|
||||
wxControl or wxWindow. In this way you'll get a @b generic widget.
|
||||
This method has the advantage that writing a single
|
||||
implementation works on all ports; the disadvantage is that it the widget will
|
||||
look the same on all platforms, and thus it may not integrate well with the
|
||||
native look and feel.
|
||||
wxControl or wxWindow. In this way you'll get a @b generic widget. This method
|
||||
has the advantage that writing a single implementation works on all ports; the
|
||||
disadvantage is that it the widget will look the same on all platforms, and
|
||||
thus it may not integrate well with the native look and feel.
|
||||
|
||||
The second method is to build it directly upon the native toolkits of the platforms you
|
||||
want to support (e.g. GTK+, Carbon and GDI). In this way you'll get a @b native widget.
|
||||
This method in fact has the advantage of a native look and feel but requires different
|
||||
implementations and thus more work.
|
||||
The second method is to build it directly upon the native toolkits of the
|
||||
platforms you want to support (e.g. GTK+, Carbon and GDI). In this way you'll
|
||||
get a @b native widget. This method in fact has the advantage of a native look
|
||||
and feel but requires different implementations and thus more work.
|
||||
|
||||
In both cases you'll want to better explore some hot topics like:
|
||||
- @ref overview_windowsizing
|
||||
- @ref overview_events_custom to implement your custom widget's events.
|
||||
You will probably need also to gain some familiarity with the wxWidgets sources,
|
||||
since you'll need to interface with some undocumented wxWidgets internal mechanisms.
|
||||
|
||||
You will probably need also to gain some familiarity with the wxWidgets
|
||||
sources, since you'll need to interface with some undocumented wxWidgets
|
||||
internal mechanisms.
|
||||
|
||||
|
||||
@subsection overview_customwidgets_how_generic Writing a generic widget
|
||||
|
||||
@subsection overview_customwidgets_how_generic Writing a Generic Widget
|
||||
|
||||
Generic widgets are typically derived from wxControl or wxWindow.
|
||||
They are easy to write. The typical "template" is as follows:
|
||||
|
||||
@code
|
||||
|
||||
enum MySpecialWidgetStyles
|
||||
{
|
||||
SWS_LOOK_CRAZY = 1,
|
||||
@@ -120,12 +116,11 @@ private:
|
||||
|
||||
|
||||
|
||||
@subsection overview_customwidgets_how_native Writing a native widget
|
||||
@subsection overview_customwidgets_how_native Writing a Native Widget
|
||||
|
||||
Writing a native widget is typically more difficult as it requires you to
|
||||
know the APIs of the platforms you want to support.
|
||||
See @ref page_port_nativedocs for links to the documentation manuals of the
|
||||
various toolkits.
|
||||
Writing a native widget is typically more difficult as it requires you to know
|
||||
the APIs of the platforms you want to support. See @ref page_port_nativedocs
|
||||
for links to the documentation manuals of the various toolkits.
|
||||
|
||||
The organization used by wxWidgets consists in:
|
||||
- declaring the common interface of the control in a generic header, using
|
||||
@@ -141,4 +136,3 @@ The organization used by wxWidgets consists in:
|
||||
and @c "src/msw/button.cpp" files.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -10,26 +10,24 @@
|
||||
|
||||
@page overview_dataobject wxDataObject Overview
|
||||
|
||||
Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
|
||||
@tableofcontents
|
||||
|
||||
See also: @ref overview_dnd and @ref page_samples_dnd
|
||||
|
||||
This overview discusses data transfer through clipboard or drag and drop.
|
||||
In wxWidgets, these two ways to transfer data (either between different
|
||||
This overview discusses data transfer through clipboard or drag and drop. In
|
||||
wxWidgets, these two ways to transfer data (either between different
|
||||
applications or inside one and the same) are very similar which allows to
|
||||
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.
|
||||
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
|
||||
by the mouse during drag and drop operation or copied to or pasted from the
|
||||
clipboard. wxDataObject is a "smart" piece of data because it knows which
|
||||
formats it supports (see GetFormatCount and GetAllFormats) and knows how to
|
||||
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.
|
||||
wxDataObject class. The objects of this class (or, to be precise, classes
|
||||
derived from it) represent the data which is being carried by the mouse during
|
||||
drag and drop operation or copied to or pasted from the clipboard. wxDataObject
|
||||
is a "smart" piece of data because it knows which formats it supports (see
|
||||
GetFormatCount and GetAllFormats) and knows how to 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
|
||||
@@ -37,24 +35,21 @@ 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.
|
||||
|
||||
@li @ref overview_dataobject_source
|
||||
@li @ref overview_dataobject_target
|
||||
@see @ref overview_dnd, @ref group_class_dnd, @ref page_samples_dnd
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_dataobject_source The data provider (source) duties
|
||||
@section overview_dataobject_source The Data Provider (Source)
|
||||
|
||||
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
|
||||
wxClipboard::SetData function or to wxDropSource and call wxDropSource::DoDragDrop
|
||||
function.
|
||||
wxClipboard::SetData function or to wxDropSource and call
|
||||
wxDropSource::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
|
||||
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
|
||||
wxDropSource::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).
|
||||
@@ -62,11 +57,12 @@ 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
|
||||
wxDropSource::DoDragDrop returns (from its return value).
|
||||
chose. But for drag and drop it can only know it after wxDropSource::DoDragDrop
|
||||
returns (from its return value).
|
||||
|
||||
|
||||
@section overview_dataobject_target The data receiver (target) duties
|
||||
|
||||
@section overview_dataobject_target The Data Receiver (Target)
|
||||
|
||||
To receive (paste in usual terminology) data from the clipboard, you should
|
||||
create a wxDataObject derived class which supports the data formats you need
|
||||
@@ -74,9 +70,8 @@ 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.
|
||||
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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -10,62 +10,40 @@
|
||||
|
||||
@page overview_datetime Date and Time
|
||||
|
||||
Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
|
||||
|
||||
@li @ref overview_datetime_introduction
|
||||
@li @ref overview_datetime_classes
|
||||
@li @ref overview_datetime_characteristics
|
||||
@li @ref overview_datetime_timespandiff
|
||||
@li @ref overview_datetime_arithmetics
|
||||
@li @ref overview_datetime_timezones
|
||||
@li @ref overview_datetime_dst
|
||||
@li @ref overview_datetime_holidays
|
||||
@li @ref overview_datetime_compat
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_datetime_introduction Introduction
|
||||
@tableofcontents
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
class for which (only) Saturdays and Sundays are the holidays. See more about
|
||||
these classes in the discussion of the holidays (see @ref overview_datetime_holidays).
|
||||
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 (see
|
||||
@ref overview_datetime_holidays).
|
||||
|
||||
Finally, in other parts of this manual you may find mentions of wxDate and
|
||||
wxTime classes. @ref overview_datetime_compat are obsolete and
|
||||
superseded by wxDateTime.
|
||||
wxTime classes. @ref overview_datetime_compat are obsolete and superseded by
|
||||
wxDateTime.
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_characteristics 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 -
|
||||
@@ -94,7 +72,7 @@ ruled out.
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
|
||||
@section overview_datetime_timespandiff 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
|
||||
@@ -129,7 +107,7 @@ just @c wxDateTime::Now() + wxDateSpan::Month()).
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_arithmetics 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
|
||||
@@ -141,14 +119,11 @@ 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.
|
||||
|
||||
@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.
|
||||
@@ -160,7 +135,7 @@ are only implemented as members and Neg() is the synonym for unary minus.
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_timezones 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
|
||||
@@ -207,7 +182,7 @@ printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
|
||||
|
||||
|
||||
|
||||
@section overview_datetime_dst 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
|
||||
|
||||
@@ -10,10 +10,6 @@
|
||||
|
||||
@page overview_dc Device Contexts
|
||||
|
||||
Classes: wxBufferedDC, wxBufferedPaintDC, wxDC, wxPostScriptDC,
|
||||
wxMetafileDC, wxMemoryDC, wxPrinterDC, wxScreenDC, wxClientDC,
|
||||
wxPaintDC, wxWindowDC.
|
||||
|
||||
A wxDC is a @e device context onto which graphics and text can be drawn.
|
||||
The device context is intended to represent a number of output devices in a
|
||||
generic way, with the same API being used throughout.
|
||||
@@ -47,5 +43,6 @@ write to a number of different devices, by passing a different device context. T
|
||||
work for everything (for example not all device contexts support bitmap drawing) but
|
||||
will work most of the time.
|
||||
|
||||
*/
|
||||
@see @ref group_class_dc
|
||||
|
||||
*/
|
||||
|
||||
@@ -11,19 +11,22 @@
|
||||
|
||||
@page overview_debugging Debugging
|
||||
|
||||
Classes, functions and macros: wxLog, @ref group_funcmacro_log, @ref group_funcmacro_debug
|
||||
@tableofcontents
|
||||
|
||||
Various classes, functions and macros are provided in wxWidgets to help you debug
|
||||
your application: @ref overview_debugging_dbgmacros allow you to insert various
|
||||
checks in your application which can be compiled out or disabled in release
|
||||
builds but are extremely useful while developing and @ref
|
||||
overview_debugging_logging which are not limited to debugging but are also
|
||||
useful for inserting traces into your application code. Both assertions and
|
||||
debug logging are also used by wxWidgets itself so you may encounter them even
|
||||
if you don't use either of these features yourself.
|
||||
Various classes, functions and macros are provided in wxWidgets to help you
|
||||
debug your application. Assertion macros allow you to insert various checks in
|
||||
your application which can be compiled out or disabled in release builds but
|
||||
are extremely useful while developing. Logging functions are also provided
|
||||
which are useful for inserting traces into your application code as well as
|
||||
debugging. Both assertions and debug logging are also used by wxWidgets itself
|
||||
so you may encounter them even if you don't use either of these features
|
||||
yourself.
|
||||
|
||||
@see wxLog, @ref group_funcmacro_log, @ref group_funcmacro_debug
|
||||
|
||||
|
||||
@section overview_debugging_config Configuring debugging support
|
||||
|
||||
@section overview_debugging_config Configuring Debug Support
|
||||
|
||||
Starting with wxWidgets 2.9.1 debugging features are always available by
|
||||
default (and not only in a special "debug" build of the library) and you need
|
||||
@@ -42,8 +45,8 @@ yourself.
|
||||
|
||||
Also notice that it is possible to build your own application with a different
|
||||
value of wxDEBUG_LEVEL than the one which was used for wxWidgets itself. E.g.
|
||||
you may be using an official binary version of the library which will have
|
||||
been compiled with default @code wxDEBUG_LEVEL == 1 @endcode but still predefine
|
||||
you may be using an official binary version of the library which will have been
|
||||
compiled with default @code wxDEBUG_LEVEL == 1 @endcode but still predefine
|
||||
wxDEBUG_LEVEL as 0 for your own code.
|
||||
|
||||
On the other hand, if you do want to keep the asserts even in production
|
||||
@@ -56,7 +59,8 @@ application log file or maybe notify the user about the problem in some more
|
||||
user-friendly way.
|
||||
|
||||
|
||||
@section overview_debugging_dbgmacros Assertion macros
|
||||
|
||||
@section overview_debugging_dbgmacros Assertion Macros
|
||||
|
||||
wxASSERT(), wxFAIL(), wxCHECK() as well as their other variants (see @ref
|
||||
group_funcmacro_debug) are similar to the standard assert() macro but are more
|
||||
@@ -101,12 +105,9 @@ message box in the @ref page_samples_except.
|
||||
|
||||
|
||||
|
||||
@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_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.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -10,92 +10,95 @@
|
||||
|
||||
@page overview_dialog wxDialog Overview
|
||||
|
||||
@tableofcontents
|
||||
|
||||
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 dialog box is similar to a panel, in that it is a window which can be used
|
||||
for placing controls, with the following exceptions:
|
||||
|
||||
@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.
|
||||
@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 group_funcmacro_dialog.
|
||||
|
||||
See also wxTopLevelWindow and wxWindow for inherited
|
||||
member functions. Validation of data in controls is covered in @ref overview_validator.
|
||||
|
||||
|
||||
@li @ref overview_dialog_autoscrolling
|
||||
|
||||
|
||||
<hr>
|
||||
See also wxTopLevelWindow and wxWindow for inherited member functions.
|
||||
Validation of data in controls is covered in @ref overview_validator.
|
||||
|
||||
|
||||
|
||||
@section overview_dialog_autoscrolling Automatic scrolling dialogs
|
||||
@section overview_dialog_autoscrolling Automatic Scrolled 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.
|
||||
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.
|
||||
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:
|
||||
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:
|
||||
|
||||
@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.
|
||||
@li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the
|
||||
non-scrolling part.
|
||||
@li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one
|
||||
or more standard buttons, with identifiers such as @c wxID_OK and
|
||||
@c wxID_CANCEL.
|
||||
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any
|
||||
kind of sizer) and adds them to a wxStdDialogButtonSizer. If no standard
|
||||
buttons were found, the whole dialog content will scroll.
|
||||
@li All the children apart from standard buttons are reparented onto a new
|
||||
::wxScrolledWindow object, using the old top-level sizer for the scrolled
|
||||
window and creating a new top-level sizer to lay out the scrolled window
|
||||
and standard button sizer.
|
||||
|
||||
|
||||
@subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
|
||||
@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.
|
||||
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 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 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.
|
||||
You can also override wxDialog::CanDoLayoutAdaptation and
|
||||
wxDialog::DoLayoutAdaptation in a class derived from wxDialog.
|
||||
|
||||
|
||||
@subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
|
||||
@subsection overview_dialog_autoscrolling_fail Where Scrolling Adaptation May Fail
|
||||
|
||||
Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
|
||||
and may fail in the following situations:
|
||||
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,
|
||||
@@ -110,7 +113,8 @@ and may fail in the following situations:
|
||||
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:
|
||||
You can help make sure that your dialogs will continue to function after
|
||||
adaptation by:
|
||||
|
||||
@li avoiding the above situations and assumptions;
|
||||
@li using wxStdDialogButtonSizer;
|
||||
@@ -124,11 +128,11 @@ You can help make sure that your dialogs will continue to function after adaptat
|
||||
@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.
|
||||
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.
|
||||
wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions
|
||||
rather than the global adapter: again, only the wizard pages are made
|
||||
scrollable.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -10,13 +10,7 @@
|
||||
|
||||
@page overview_dnd Drag and Drop Overview
|
||||
|
||||
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 overview_dataobject and @ref page_samples_dnd.
|
||||
@tableofcontents
|
||||
|
||||
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
|
||||
@@ -24,35 +18,39 @@ 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.
|
||||
|
||||
To be a @e drag source, i.e. to provide the data which may be dragged by
|
||||
Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
|
||||
to use drag and drop in wxWidgets.
|
||||
|
||||
@see @ref overview_dataobject, @ref group_class_dnd, @ref page_samples_dnd
|
||||
|
||||
|
||||
|
||||
@section overview_dnd_dropsource Drop Source Requirements
|
||||
|
||||
To be a @e "drop 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
|
||||
|
||||
@li <b>Drag start</b>: To start the dragging process (typically in response to a
|
||||
mouse click) you must call wxDropSource::DoDragDrop like this:
|
||||
|
||||
@code
|
||||
wxDropSource dragSource( this );
|
||||
dragSource.SetData( my_data );
|
||||
wxDragResult result = dragSource.DoDragDrop( true );
|
||||
@endcode
|
||||
|
||||
@li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
|
||||
the mouse button (unless you override the wxDropSource::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
|
||||
@li @b Dragging: The call to DoDragDrop() blocks the program until the user
|
||||
releases the mouse button (unless you override the
|
||||
wxDropSource::GiveFeedback function to do something special). When the
|
||||
mouse moves in a window of a program which understands the same
|
||||
drag-and-drop protocol (any program under Windows or any program supporting
|
||||
the XDnD protocol under X Windows), the corresponding wxDropTarget methods
|
||||
are called - see below.
|
||||
|
||||
@li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
|
||||
is one of the values of @c wxDragResult enum (explained in wxDropTarget page):
|
||||
|
||||
@code
|
||||
switch (result)
|
||||
{
|
||||
@@ -69,7 +67,10 @@ the user elsewhere, you should implement the following steps:
|
||||
@endcode
|
||||
|
||||
|
||||
To be a @e drop target, i.e. to receive the data dropped by the user you should
|
||||
|
||||
@section overview_dnd_droptarget Drop Target Requirements
|
||||
|
||||
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
|
||||
@@ -78,18 +79,15 @@ follow the instructions below:
|
||||
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 wxDropTarget::OnData will get called and the wxDataObject belonging
|
||||
to the drop target can get filled with data.
|
||||
|
||||
@li <b>The end</b>: After processing the data, DoDragDrop() returns either
|
||||
wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
|
||||
and Alt at the moment of the drop. There is currently no way for the drop
|
||||
target to change this return code.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@@ -10,177 +10,168 @@
|
||||
|
||||
@page overview_docview Document/View Framework
|
||||
|
||||
Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame,
|
||||
wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame,
|
||||
wxCommand, wxCommandProcessor
|
||||
@tableofcontents
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
modifications, routing menu commands to appropriate (possibly default) code, even
|
||||
some default print/preview functionality and support for command undo/redo.
|
||||
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.
|
||||
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:
|
||||
|
||||
@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 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.
|
||||
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.
|
||||
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:
|
||||
Here are a few examples of the tailoring you can do to go beyond the default
|
||||
framework behaviour:
|
||||
|
||||
@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.
|
||||
@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 overview_docview_predefid in your menus.
|
||||
|
||||
@beginWxPerlOnly
|
||||
The document/view framework is available in wxPerl. To use it,
|
||||
you will need the following statements in your application code:
|
||||
The document/view framework is available in wxPerl. To use it, you will need
|
||||
the following statements in your application code:
|
||||
|
||||
@code
|
||||
@code{.pl}
|
||||
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
|
||||
|
||||
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_docview_wxdoc wxDocument overview
|
||||
|
||||
Class: wxDocument
|
||||
|
||||
The wxDocument class can be used to model an application's file-based
|
||||
data. It is part of the document/view framework supported by wxWidgets,
|
||||
and cooperates with the wxView, wxDocTemplate and wxDocManager classes.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
@see @ref group_class_docview,
|
||||
|
||||
|
||||
|
||||
@section overview_docview_wxview wxView overview
|
||||
@section overview_docview_wxdoc wxDocument Overview
|
||||
|
||||
Class: wxView
|
||||
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. 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.
|
||||
|
||||
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
|
||||
and wxDocManager classes.
|
||||
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.
|
||||
|
||||
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 overview_docview_wxview wxView Overview
|
||||
|
||||
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 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.
|
||||
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.
|
||||
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.
|
||||
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 overview_docview_wxdoctemplate wxDocTemplate 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 templates managed by the
|
||||
wxDocManager instance is used to create 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.
|
||||
|
||||
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
|
||||
templates managed by the wxDocManager instance is used to create
|
||||
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,
|
||||
and two view classes (DoodleGraphicView and DoodleListView). You would also
|
||||
need two document templates, one for the graphical view and another for the
|
||||
list view. You would pass the same document class and default file extension to both
|
||||
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.
|
||||
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, and two view classes (DoodleGraphicView and DoodleListView).
|
||||
You would also need two document templates, one for the graphical view and
|
||||
another for the list view. You would pass the same document class and default
|
||||
file extension to both 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.
|
||||
|
||||
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
|
||||
@@ -191,9 +182,10 @@ 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.
|
||||
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.
|
||||
|
||||
If you do not wish to use the wxWidgets method of creating document
|
||||
objects dynamically, you must override wxDocTemplate::CreateDocument
|
||||
@@ -203,87 +195,81 @@ and wxDocTemplate::CreateView to return instances of the appropriate class.
|
||||
|
||||
|
||||
|
||||
@section overview_docview_wxdocmanager wxDocManager overview
|
||||
@section overview_docview_wxdocmanager wxDocManager 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
There may be multiple wxDocManager instances in an application. See the example
|
||||
application in @c samples/docview.
|
||||
|
||||
|
||||
|
||||
@section overview_docview_wxcommand wxCommand 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
When a user interface event occurs, the application @e submits a command
|
||||
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.
|
||||
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 overview_docview_wxcommandproc wxCommandProcessor 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.
|
||||
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 overview_docview_filehistory wxFileHistory 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.
|
||||
|
||||
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.
|
||||
|
||||
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 wxFileHistory::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).
|
||||
|
||||
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
|
||||
wxFileHistory::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.
|
||||
|
||||
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:
|
||||
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)
|
||||
@@ -306,11 +292,10 @@ void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
|
||||
|
||||
|
||||
|
||||
@section overview_docview_predefid wxWidgets predefined command identifiers
|
||||
@section overview_docview_predefid 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.
|
||||
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)
|
||||
@@ -329,4 +314,3 @@ wxID_PREVIEW (5012)
|
||||
@endverbatim
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user