moved the samples in a separate page so it has a summary of all the samples descriptions and so writing references to samples is shorter (@ref page_samples_xxx instead of @ref page_utils_samples_xxx)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52705 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-03-22 17:42:29 +00:00
parent e18e78a7cc
commit dc28cdf8d4
9 changed files with 1237 additions and 1150 deletions
+1
View File
@@ -20,6 +20,7 @@
@li @subpage page_introduction
@li @subpage page_multiplatform
@li @subpage page_utils
@li @subpage page_samples
@li @subpage page_strategies
@li @subpage page_libs
@li @subpage page_constants
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+1 -1
View File
@@ -38,7 +38,7 @@ displayed one page at a time. wxWidgets has five variants of this control:
@li wxTreebook: controlled by a wxTreeCtrl
@li wxToolbook: controlled by a wxToolBar
See the @ref page_utils_samples_notebook for an example of wxBookCtrl usage.
See the @ref page_samples_notebook for an example of wxBookCtrl usage.
@section overview_bookctrl_bestbookctrl Best Book
+52 -52
View File
@@ -8,75 +8,75 @@
/**
@page overview_dataobject wxDataObject Overview
@page overview_dataobject wxDataObject Overview
Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
See also: @ref overview_dnd and @ref page_utils_samples_dnd
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
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.
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
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.
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.
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.
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.
@li @ref overview_dataobject_source
@li @ref overview_dataobject_target
@li @ref overview_dataobject_source
@li @ref overview_dataobject_target
<hr>
<hr>
@section overview_dataobject_source 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
wxClipboard::SetData function or to wxDropSource and call wxDropSource::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
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
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).
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
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).
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).
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).
@section overview_dataobject_target 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.
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.
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.
*/
+56 -56
View File
@@ -8,54 +8,54 @@
/**
@page overview_dnd Drag and Drop Overview
@page overview_dnd Drag and Drop Overview
Classes: wxDataObject, wxTextDataObject, wxDropSource, wxDropTarget,
wxTextDropTarget, wxFileDropTarget
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.
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_utils_samples_dnd.
See also: @ref overview_dataobject and @ref page_samples_dnd.
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.
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.
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:
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:
@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
@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:
@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
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
the XDnD protocol under X Windows), the corresponding wxDropTarget methods
are called - see below.
@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):
@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)
{
@code
switch (result)
{
case wxDragCopy:
// copy the data
break;
@@ -65,31 +65,31 @@
default:
// do nothing
break;
}
@endcode
}
@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 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 wxDropTarget::OnData will get called and the wxDataObject belonging
to the drop target can get filled with data.
@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.
@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.
*/
File diff suppressed because it is too large Load Diff
+65 -65
View File
@@ -8,81 +8,81 @@
/**
@page overview_fontencoding Font Encodings
@page overview_fontencoding Font Encodings
wxWidgets has support for multiple font encodings.
wxWidgets has support for multiple font encodings.
By encoding we mean here the mapping between the character codes and the
letters. Probably the most well-known encoding is (7 bit) ASCII one which is
used almost universally now to represent the letters of the English alphabet
and some other common characters. However, it is not enough to represent the
letters of foreign alphabets and here other encodings come into play. Please
note that we will only discuss 8-bit fonts here and not Unicode
(see @ref overview_unicode).
By encoding we mean here the mapping between the character codes and the
letters. Probably the most well-known encoding is (7 bit) ASCII one which is
used almost universally now to represent the letters of the English alphabet
and some other common characters. However, it is not enough to represent the
letters of foreign alphabets and here other encodings come into play. Please
note that we will only discuss 8-bit fonts here and not Unicode
(see @ref overview_unicode).
Font encoding support is ensured by several classes:
wxFont itself, but also wxFontEnumerator and wxFontMapper. wxFont encoding
support is reflected by a (new) constructor parameter @e encoding which takes
one of the following values (elements of enumeration type @c wxFontEncoding):
Font encoding support is ensured by several classes:
wxFont itself, but also wxFontEnumerator and wxFontMapper. wxFont encoding
support is reflected by a (new) constructor parameter @e encoding which takes
one of the following values (elements of enumeration type @c wxFontEncoding):
@beginDefList
@itemdef{wxFONTENCODING_SYSTEM,
The default encoding of the underlying
operating system (notice that this might be a "foreign" encoding for foreign
versions of Windows 9x/NT).}
@itemdef{wxFONTENCODING_DEFAULT,
The applications default encoding as returned by wxFont::GetDefaultEncoding.
On program startup, the applications default encoding is the same as
wxFONTENCODING_SYSTEM, but may be changed to make all the fonts created later
to use it (by default).}
@itemdef{wxFONTENCODING_ISO8859_1..15,
ISO8859 family encodings which are
usually used by all non-Microsoft operating systems.}
@itemdef{wxFONTENCODING_KOI8,
Standard Cyrillic encoding for the Internet
(but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251).}
@itemdef{wxFONTENCODING_CP1250, Microsoft analogue of ISO8859-2}
@itemdef{wxFONTENCODING_CP1251, Microsoft analogue of ISO8859-5}
@itemdef{wxFONTENCODING_CP1252, Microsoft analogue of ISO8859-1}
@endDefList
@beginDefList
@itemdef{wxFONTENCODING_SYSTEM,
The default encoding of the underlying
operating system (notice that this might be a "foreign" encoding for foreign
versions of Windows 9x/NT).}
@itemdef{wxFONTENCODING_DEFAULT,
The applications default encoding as returned by wxFont::GetDefaultEncoding.
On program startup, the applications default encoding is the same as
wxFONTENCODING_SYSTEM, but may be changed to make all the fonts created later
to use it (by default).}
@itemdef{wxFONTENCODING_ISO8859_1..15,
ISO8859 family encodings which are
usually used by all non-Microsoft operating systems.}
@itemdef{wxFONTENCODING_KOI8,
Standard Cyrillic encoding for the Internet
(but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251).}
@itemdef{wxFONTENCODING_CP1250, Microsoft analogue of ISO8859-2}
@itemdef{wxFONTENCODING_CP1251, Microsoft analogue of ISO8859-5}
@itemdef{wxFONTENCODING_CP1252, Microsoft analogue of ISO8859-1}
@endDefList
As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones,
but there are (minor) differences even between ISO8859-1 (Latin1, ISO encoding
for Western Europe) and CP1251 (WinLatin1, standard code page for English
versions of Windows) and there are more of them for other encodings.
As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones,
but there are (minor) differences even between ISO8859-1 (Latin1, ISO encoding
for Western Europe) and CP1251 (WinLatin1, standard code page for English
versions of Windows) and there are more of them for other encodings.
The situation is particularly complicated with Cyrillic encodings for which
(more than) three incompatible encodings exist: KOI8 (the old standard, widely
used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
(WinCyrillic).
The situation is particularly complicated with Cyrillic encodings for which
(more than) three incompatible encodings exist: KOI8 (the old standard, widely
used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
(WinCyrillic).
This abundance of (incompatible) encodings should make it clear that using
encodings is less easy than it might seem. The problems arise both from the
fact that the standard encodings for the given language (say Russian, which is
written in Cyrillic) are different on different platforms and because the
fonts in the given encoding might just not be installed (this is especially a
problem with Unix, or, in general, non-Win32 systems).
This abundance of (incompatible) encodings should make it clear that using
encodings is less easy than it might seem. The problems arise both from the
fact that the standard encodings for the given language (say Russian, which is
written in Cyrillic) are different on different platforms and because the
fonts in the given encoding might just not be installed (this is especially a
problem with Unix, or, in general, non-Win32 systems).
To clarify, the wxFontEnumerator
class may be used to enumerate both all available encodings and to find the
facename(s) in which the given encoding exists. If you can find the font in
the correct encoding with wxFontEnumerator then your troubles are over, but,
unfortunately, sometimes this is not enough. For example, there is no standard
way (that I know of, please tell me if you do!) to find a font on a Windows system
for KOI8 encoding (only for WinCyrillic one which is quite different), so
wxFontEnumerator will never return one, even if the user has installed a KOI8
font on his system.
To clarify, the wxFontEnumerator
class may be used to enumerate both all available encodings and to find the
facename(s) in which the given encoding exists. If you can find the font in
the correct encoding with wxFontEnumerator then your troubles are over, but,
unfortunately, sometimes this is not enough. For example, there is no standard
way (that I know of, please tell me if you do!) to find a font on a Windows system
for KOI8 encoding (only for WinCyrillic one which is quite different), so
wxFontEnumerator will never return one, even if the user has installed a KOI8
font on his system.
To solve this problem, a wxFontMapper class is provided.
To solve this problem, a wxFontMapper class is provided.
This class stores the mapping between the encodings and the font face
names which support them in wxConfig object. Of
course, it would be fairly useless if it tried to determine these mappings by
itself, so, instead, it (optionally) asks the user and remembers his answers
so that the next time the program will automatically choose the correct font.
All these topics are illustrated by the @ref page_utils_samples_font;
please refer to it and the documentation of the classes mentioned here for
further explanations.
This class stores the mapping between the encodings and the font face
names which support them in wxConfig object. Of
course, it would be fairly useless if it tried to determine these mappings by
itself, so, instead, it (optionally) asks the user and remembers his answers
so that the next time the program will automatically choose the correct font.
All these topics are illustrated by the @ref page_samples_font;
please refer to it and the documentation of the classes mentioned here for
further explanations.
*/
@@ -84,7 +84,7 @@ translated special key names such as Backspace, End, Insert, etc.
@see
@li The gettext Manual: http://www.gnu.org/software/gettext/manual/gettext.html
@li @ref overview_nonenglish - It focuses on handling charsets related problems.
@li @ref page_utils_samples_internat - Shows you how all this looks in practice.
@li @ref page_samples_internat - Shows you how all this looks in practice.
*/