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

removed useless spaces

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51911 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-02-19 13:28:24 +00:00
parent 4411a6b6b5
commit 36c9828f70
71 changed files with 5417 additions and 5409 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/doxygen/overviews/app.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page app_overview wxApp overview
Classes: #wxApp
A wxWidgets application does not have a @e main procedure; the equivalent is the
#OnInit member defined for a class derived from wxApp.
@@ -18,7 +18,7 @@
returns a boolean value which indicates whether processing should continue (@true) or not (@false).
You call wxApp::SetTopWindow to let wxWidgets know
about the top window.
Note that the program's command line arguments, represented by @e argc
Note that the program's command line arguments, represented by @e argc
and @e argv, are available from within wxApp member functions.
An application closes by destroying all windows. Because all frames must
be destroyed for the application to exit, it is advisable to use parent
@@ -27,44 +27,44 @@
is to explicitly delete child frames in the top-level frame's #wxCloseEvent
handler.
In emergencies the #wxExit function can be called to kill the
application however normally the application shuts down automatically,
application however normally the application shuts down automatically,
@ref appshutdown_overview.
An example of defining an application follows:
@code
class DerivedApp : public wxApp
{
public:
virtual bool OnInit();
};
IMPLEMENT_APP(DerivedApp)
bool DerivedApp::OnInit()
{
wxFrame *the_frame = new wxFrame(@NULL, ID_MYFRAME, argv[0]);
...
the_frame-Show(@true);
SetTopWindow(the_frame);
return @true;
}
@endcode
Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically create an instance of the application object
at the appropriate point in wxWidgets initialization. Previous versions of wxWidgets used
to rely on the creation of a global application object, but this is no longer recommended,
because required global initialization may not have been performed at application object
construction time.
You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp function which returns
a reference to the application object. Otherwise you can only use the global
a reference to the application object. Otherwise you can only use the global
@c wxTheApp pointer which is of type @c wxApp *.
@ref appshutdown_overview
@section wxappshutdownoverview Application shutdown
The application normally shuts down when the last of its top level windows is
closed. This is normally the expected behaviour and means that it is enough to
call #Close() in response to the @c "Exit" menu
@@ -72,18 +72,18 @@
desirable wxApp::SetExitOnFrameDelete can
be called to change it. Note that starting from wxWidgets 2.3.3 such logic
doesn't apply for the windows shown before the program enters the main loop: in
other words, you can safely show a dialog from
other words, you can safely show a dialog from
wxApp::OnInit and not be afraid that your application
terminates when this dialog -- which is the last top level window for the
moment -- is closed.
Another aspect of the application shutdown is #OnExit
Another aspect of the application shutdown is #OnExit
which is called when the application exits but @e before wxWidgets cleans up
its internal structures. You should delete all wxWidgets object that you
created by the time OnExit finishes. In particular, do @b not destroy them
from application class' destructor!
For example, this code may crash:
@code
class MyApp : public wxApp
{
@@ -92,12 +92,12 @@
...
};
@endcode
The reason for that is that @c m_helpCtrl is a member object and is
thus destroyed from MyApp destructor. But MyApp object is deleted after
wxWidgets structures that wxCHMHelpController depends on were
The reason for that is that @c m_helpCtrl is a member object and is
thus destroyed from MyApp destructor. But MyApp object is deleted after
wxWidgets structures that wxCHMHelpController depends on were
uninitialized! The solution is to destroy HelpCtrl in @e OnExit:
@code
class MyApp : public wxApp
{
@@ -105,21 +105,21 @@
wxCHMHelpController *m_helpCtrl;
...
};
bool MyApp::OnInit()
{
...
m_helpCtrl = new wxCHMHelpController;
...
}
int MyApp::OnExit()
{
delete m_helpCtrl;
return 0;
}
@endcode
*/

338
docs/doxygen/overviews/arc.h
View File

@@ -7,54 +7,54 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page arc_overview Archive formats such as zip
The archive classes handle archive formats such as zip, tar, rar and cab.
Currently #wxZip
and #wxTar classes are included.
For each archive type, there are the following classes (using zip here
as an example):
#wxZipInputStream
Input stream
#wxZipOutputStream
Output stream
#wxZipEntry
Holds the meta-data for an
entry (e.g. filename, timestamp, etc.)
There are also abstract wxArchive classes that can be used to write code
that can handle any of the archive types,
see '@ref arcgeneric_overview'.
@@ -65,42 +65,42 @@
(see '@ref arcnoseek_overview').
@b See also
#wxFileSystem
@ref arccreate_overview
@ref arcextract_overview
@ref arcmodify_overview
@ref arcbyname_overview
@ref arcgeneric_overview
@ref arcnoseek_overview
@section wxarccreate Creating an archive
@ref arc_overview
Call #PutNextEntry() to
create each new entry in the archive, then write the entry's data.
Another call to PutNextEntry() closes the current entry and begins the next.
For example:
@code
wxFFileOutputStream out(_T("test.zip"));
wxZipOutputStream zip(out);
wxTextOutputStream txt(zip);
wxString sep(wxFileName::GetPathSeparator());
zip.PutNextEntry(_T("entry1.txt"));
txt _T("Some text for entry1.txt\n");
zip.PutNextEntry(_T("subdir") + sep + _T("entry2.txt"));
txt _T("Some text for subdir/entry2.txt\n");
@endcode
The name of each entry can be a full path, which makes it possible to
store entries in subdirectories.
@section wxarcextract Extracting an archive
@ref arc_overview
#GetNextEntry() returns a pointer
to entry object containing the meta-data for the next entry in the archive
@@ -108,13 +108,13 @@
entry's data. Eof() becomes @true after an attempt has been made to read past
the end of the entry's data.
When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
@code
auto_ptrwxZipEntry entry;
wxFFileInputStream in(_T("test.zip"));
wxZipInputStream zip(in);
while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL)
{
// access meta-data
@@ -122,11 +122,11 @@
// read 'zip' to access the entry's data
}
@endcode
@section wxarcmodify Modifying an archive
@ref arc_overview
To modify an existing archive, write a new copy of the archive to a new file,
making any necessary changes along the way and transferring any unchanged
@@ -141,38 +141,38 @@
archive. #wxTempFileOutputStream can
be helpful to do this.
For example to delete all entries matching the pattern "*.txt":
@code
auto_ptrwxFFileInputStream in(new wxFFileInputStream(_T("test.zip")));
wxTempFileOutputStream out(_T("test.zip"));
wxZipInputStream inzip(*in);
wxZipOutputStream outzip(out);
auto_ptrwxZipEntry entry;
// transfer any meta-data for the archive as a whole (the zip comment
// in the case of zip)
outzip.CopyArchiveMetaData(inzip);
// call CopyEntry for each entry except those matching the pattern
while (entry.reset(inzip.GetNextEntry()), entry.get() != @NULL)
if (!entry-GetName().Matches(_T("*.txt")))
if (!outzip.CopyEntry(entry.release(), inzip))
break;
// close the input stream by releasing the pointer to it, do this
// before closing the output stream so that the file can be replaced
in.reset();
// you can check for success as follows
bool success = inzip.Eof() && outzip.Close() && out.Commit();
@endcode
@section wxarcbyname Looking up an archive entry by name
@ref arc_overview
Also see #wxFileSystem for a higher level interface that is
more convenient for accessing archive entries by name.
@@ -192,43 +192,43 @@
So to avoid ambiguity when searching for an entry matching a local name,
it is better to convert the local name to the archive's internal format
and search for that:
@code
auto_ptrwxZipEntry entry;
// convert the local name we are looking for into the internal format
wxString name = wxZipEntry::GetInternalName(localname);
// open the zip
wxFFileInputStream in(_T("test.zip"));
wxZipInputStream zip(in);
// call GetNextEntry() until the required internal name is found
do {
entry.reset(zip.GetNextEntry());
}
while (entry.get() != @NULL && entry-GetInternalName() != name);
if (entry.get() != @NULL) {
// read the entry's data...
}
@endcode
To access several entries randomly, it is most efficient to transfer the
entire catalogue of entries to a container such as a std::map or a
#wxHashMap then entries looked up by name can be
opened using the #OpenEntry() method.
@code
WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog);
ZipCatalog::iterator it;
wxZipEntry *entry;
ZipCatalog cat;
// open the zip
wxFFileInputStream in(_T("test.zip"));
wxZipInputStream zip(in);
// load the zip catalog
while ((entry = zip.GetNextEntry()) != @NULL) {
wxZipEntry*& current = cat[entry-GetInternalName()];
@@ -237,17 +237,17 @@
delete current;
current = entry;
}
// open an entry by name
if ((it = cat.find(wxZipEntry::GetInternalName(localname))) != cat.end()) {
zip.OpenEntry(*it-second);
// ... now read entry's data
}
@endcode
To open more than one entry simultaneously you need more than one
underlying stream on the same archive:
@code
// opening another entry without closing the first requires another
// input stream for the same file
@@ -256,57 +256,57 @@
if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end())
zip2.OpenEntry(*it-second);
@endcode
@section wxarcgeneric Generic archive programming
@ref arc_overview
Also see #wxFileSystem for a higher level interface that
can handle archive files in a generic way.
The specific archive classes, such as the wxZip classes, inherit from
the following abstract classes which can be used to write code that can
handle any of the archive types:
#wxArchiveInputStream
Input stream
#wxArchiveOutputStream
Output stream
#wxArchiveEntry
Holds the meta-data for an
entry (e.g. filename)
In order to able to write generic code it's necessary to be able to create
instances of the classes without knowing which archive type is being used.
To allow this there is a class factory for each archive type, derived from
@@ -314,29 +314,29 @@
the other classes.
For example, given @e wxArchiveClassFactory* factory, streams and
entries can be created like this:
@code
// create streams without knowing their type
auto_ptrwxArchiveInputStream inarc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
// create an empty entry object
auto_ptrwxArchiveEntry entry(factory-NewEntry());
@endcode
For the factory itself, the static member
wxArchiveClassFactory::Find().
can be used to find a class factory that can handle a given file
extension or mime type. For example, given @e filename:
@code
const wxArchiveClassFactory *factory;
factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
if (factory)
stream = factory-NewStream(new wxFFileInputStream(filename));
@endcode
@e Find does not give away ownership of the returned pointer, so it
does not need to be deleted.
There are similar class factories for the filter streams that handle the
@@ -344,10 +344,10 @@
These can be found using
wxFilterClassFactory::Find().
For example, to list the contents of archive @e filename:
@code
auto_ptrwxInputStream in(new wxFFileInputStream(filename));
if (in-IsOk())
{
// look for a filter handler, e.g. for '.gz'
@@ -358,14 +358,14 @@
// pop the extension, so if it was '.tar.gz' it is now just '.tar'
filename = fcf-PopExtension(filename);
}
// look for a archive handler, e.g. for '.zip' or '.tar'
const wxArchiveClassFactory *acf;
acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
if (acf) {
auto_ptrwxArchiveInputStream arc(acf-NewStream(in.release()));
auto_ptrwxArchiveEntry entry;
// list the contents of the archive
while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL)
std::wcout entry-GetName().c_str() "\n";
@@ -375,17 +375,17 @@
}
}
@endcode
@section wxarcnoseek Archives on non-seekable streams
@ref arc_overview
In general, handling archives on non-seekable streams is done in the same
way as for seekable streams, with a few caveats.
The main limitation is that accessing entries randomly using
#OpenEntry()
is not possible, the entries can only be accessed sequentially in the order
#OpenEntry()
is not possible, the entries can only be accessed sequentially in the order
they are stored within the archive.
For each archive type, there will also be other limitations which will
depend on the order the entries' meta-data is stored within the archive.
@@ -405,7 +405,7 @@
@b GetNextEntry and the weak reference mechanism
Some archive formats do not store all an entry's meta-data before the
entry's data (zip is an example). In this case, when reading from a
non-seekable stream, #GetNextEntry()
non-seekable stream, #GetNextEntry()
can only return a partially populated #wxArchiveEntry
object - not all the fields are set.
The input stream then keeps a weak reference to the entry object and
@@ -417,38 +417,38 @@
when the worst case must be assumed, you can rely on all the fields
of wxArchiveEntry being fully populated when GetNextEntry() returns,
with the the following exceptions:
#GetSize()
Guaranteed to be
available after the entry has been read to #Eof(),
or #CloseEntry() has been called
#IsReadOnly()
Guaranteed to
be available after the end of the archive has been reached, i.e. after
GetNextEntry() returns @NULL and Eof() is @true
This mechanism allows #CopyEntry()
to always fully preserve entries' meta-data. No matter what order order
the meta-data occurs within the archive, the input stream will always
@@ -461,30 +461,30 @@
This is the usual way to modify an entry's meta-data, simply set the
required field before writing it with
#CopyEntry():
@code
auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
auto_ptrwxArchiveEntry entry;
outarc-CopyArchiveMetaData(*arc);
while (entry.reset(arc-GetNextEntry()), entry.get() != @NULL) {
if (entry-GetName() == from)
entry-SetName(to);
if (!outarc-CopyEntry(entry.release(), *arc))
break;
}
bool success = arc-Eof() && outarc-Close();
@endcode
However, for non-seekable streams, this technique cannot be used for
fields such as #IsReadOnly(),
which are not necessarily set when
#GetNextEntry() returns. In
this case a #wxArchiveNotifier can be used:
@code
class MyNotifier : public wxArchiveNotifier
{
@@ -492,36 +492,36 @@
void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(@false); }
};
@endcode
The meta-data changes are done in your notifier's
#OnEntryUpdated() method,
then #SetNotifier() is called before
CopyEntry():
@code
auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
auto_ptrwxArchiveEntry entry;
MyNotifier notifier;
outarc-CopyArchiveMetaData(*arc);
while (entry.reset(arc-GetNextEntry()), entry.get() != @NULL) {
entry-SetNotifier(notifier);
if (!outarc-CopyEntry(entry.release(), *arc))
break;
}
bool success = arc-Eof() && outarc-Close();
@endcode
SetNotifier() calls OnEntryUpdated() immediately, then the input
stream calls it again whenever it sets more fields in the entry. Since
OnEntryUpdated() will be called at least once, this technique always
works even when it is not strictly necessary to use it. For example,
changing the entry name can be done this way too and it works on seekable
streams as well as non-seekable.
*/

10
docs/doxygen/overviews/aui.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page aui_overview wxAUI overview
Class: #wxAuiManager, #wxAuiPaneInfo
wxAUI stands for Advanced User Interface and the wxAUI framework
aims to give its user a cutting edge interface for use with the
@@ -44,7 +44,7 @@
platforms. Use existing wxWidgets code where possible, such as sizer
implementation for frame management. Use classes included in wxCore
and wxBase only. Use standard wxWidgets coding conventions.
*/

188
docs/doxygen/overviews/backwardcompatibility.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page backwardcompatibility_overview Backward compatibility
Many of the GUIs and platforms supported by wxWidgets are continuously
evolving, and some of the new platforms wxWidgets now supports were quite
unimaginable even a few years ago. In this environment wxWidgets must also
@@ -22,17 +22,17 @@
@ref sourcecompatibility_overview
@ref libbincompatibility_overview
@ref appbincompatibility_overview
@section versionnumbering The version numbering scheme
wxWidgets version numbers can have up to four components, with trailing
zeros sometimes omitted:
@code
major.minor.release.sub-release
@endcode
A stable release of wxWidgets will have an even number for @c minor, e.g. @c 2.6.0.
Stable, in this context, means that the API is not changing. In truth, some
changes are permitted, but only those that are backward compatible. For
@@ -54,9 +54,9 @@
incompatibilities. Compatibility is not broken gratuitously however, so
many applications will require no changes or only small changes to work
with the new version.
@section sourcecompatibility Source level compatibility
Later releases from a stable branch are backward compatible with earlier
releases from the same branch at the source level.
This means that, for example, if you develop your application using
@@ -68,90 +68,92 @@
binary compatibility' below.
Between minor versions, for example between @c 2.2.x, @c 2.4.x and @c 2.6.x, there will be some incompatibilities. Wherever possible the old way
of doing something is kept alongside the new for a time wrapped inside:
@code
#if WXWIN_COMPATIBILITY_2_4
/* deprecated feature */
...
#endif
@endcode
By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
to 1 for the previous stable branch, for example
in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
for @c 2.6.x. Earlier than that, obsolete features are removed.
These macros can be changed in @c setup.h. Or on UNIX-like systems you can
set them using the @c --disable-compat24 and @c --enable-compat22
options to @c configure.
They can be useful in two ways:
Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
find uses of deprecated features in your program.
Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
compile a program developed using @c 2.2.x that no longer compiles
with @c 2.6.x.
A program requiring one of these macros to be 1 will become
incompatible with some future version of wxWidgets, and you should consider
updating it.
@section libbincompatibility Library binary compatibility
For some platforms, releases from a stable branch are not only source level
compatible but can also be binary compatible.
Binary compatibility makes it possible to get the maximum benefit from
using shared libraries, also known as dynamic link libraries (DLLs) on
Windows or dynamic shared libraries on OS X.
For example, suppose several applications are installed on a system requiring
wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
backward compatible with the earlier versions, it should be enough to
install just wxWidgets @c 2.6.2 shared libraries, and all the applications
should be able to use them. If binary compatibility is not supported, then all
the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
installed side by side.
Achieving this, without the user being required to have the source code
and recompile everything, places many extra constraints on the changes
that can be made within the stable branch. So it is not supported for all
platforms, and not for all versions of wxWidgets. To date it has mainly
been supported by wxGTK for UNIX-like platforms.
Another practical consideration is that for binary compatibility to work,
all the applications and libraries must have been compiled with compilers
that are capable of producing compatible code; that is, they must use the
same ABI (Application Binary Interface). Unfortunately most different C++
compilers do not produce code compatible with each other, and often even
different versions of the same compiler are not compatible.
@section appbincompatibility Application binary compatibility
The most important aspect of binary compatibility is that applications
compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work
with shared libraries of a later binary compatible version, for example @c 2.6.2.
The converse can also be useful however. That is, it can be useful for a
developer using a later version, e.g. @c 2.6.2 to be able to create binary
application packages that will work with all binary compatible versions of
the shared library starting with, for example @c 2.6.0.
To do this the developer must, of course, avoid any features not available
in the earlier versions. However this is not necessarily enough; in some
cases an application compiled with a later version may depend on it even
though the same code would compile fine against an earlier version.
To help with this, a preprocessor symbol @c wxABI_VERSION can be defined
during the compilation of the application (this would usually be done in the
application's makefile or project settings). It should be set to the lowest
version that is being targeted, as a number with two decimal digits for each
component, for example @c wxABI_VERSION=20600 for @c 2.6.0.
Setting @c wxABI_VERSION should prevent the application from implicitly
depending on a later version of wxWidgets, and also disables any new features
in the API, giving a compile time check that the source is compatible with
the versions of wxWidgets being targeted.
Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when
each new development branch is created. Therefore it is only useful to help
achieve compatibility with earlier versions with the same major
and even minor version numbers. It won't, for example, help you write
code compatible with @c 2.4.x using wxWidgets @c 2.6.x.
*/
...
#endif
@endcode
By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
to 1 for the previous stable branch, for example
in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
for @c 2.6.x. Earlier than that, obsolete features are removed.
These macros can be changed in @c setup.h. Or on UNIX-like systems you can
set them using the @c --disable-compat24 and @c --enable-compat22
options to @c configure.
They can be useful in two ways:
Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
find uses of deprecated features in your program.
Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
compile a program developed using @c 2.2.x that no longer compiles
with @c 2.6.x.
A program requiring one of these macros to be 1 will become
incompatible with some future version of wxWidgets, and you should consider
updating it.
@section libbincompatibility Library binary compatibility
For some platforms, releases from a stable branch are not only source level
compatible but can also be binary compatible.
Binary compatibility makes it possible to get the maximum benefit from
using shared libraries, also known as dynamic link libraries (DLLs) on
Windows or dynamic shared libraries on OS X.
For example, suppose several applications are installed on a system requiring
wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
backward compatible with the earlier versions, it should be enough to
install just wxWidgets @c 2.6.2 shared libraries, and all the applications
should be able to use them. If binary compatibility is not supported, then all
the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
installed side by side.
Achieving this, without the user being required to have the source code
and recompile everything, places many extra constraints on the changes
that can be made within the stable branch. So it is not supported for all
platforms, and not for all versions of wxWidgets. To date it has mainly
been supported by wxGTK for UNIX-like platforms.
Another practical consideration is that for binary compatibility to work,
all the applications and libraries must have been compiled with compilers
that are capable of producing compatible code;
that is, they must use the
same ABI (Application Binary Interface). Unfortunately most different C++
compilers do not produce code compatible with each other, and often even
different versions of the same compiler are not compatible.
@section appbincompatibility Application binary compatibility
The most important aspect of binary compatibility is that applications
compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work
with shared libraries of a later binary compatible version, for example @c 2.6.2.
The converse can also be useful however. That is, it can be useful for a
developer using a later version, e.g. @c 2.6.2 to be able to create binary
application packages that will work with all binary compatible versions of
the shared library starting with, for example @c 2.6.0.
To do this the developer must, of course, avoid any features not available
in the earlier versions. However this is not necessarily enough;
in some
cases an application compiled with a later version may depend on it even
though the same code would compile fine against an earlier version.
To help with this, a preprocessor symbol @c wxABI_VERSION can be defined
during the compilation of the application (this would usually be done in the
application's makefile or project settings). It should be set to the lowest
version that is being targeted, as a number with two decimal digits for each
component, for example @c wxABI_VERSION=20600 for @c 2.6.0.
Setting @c wxABI_VERSION should prevent the application from implicitly
depending on a later version of wxWidgets, and also disables any new features
in the API, giving a compile time check that the source is compatible with
the versions of wxWidgets being targeted.
Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when
each new development branch is created. Therefore it is only useful to help
achieve compatibility with earlier versions with the same major
and even minor version numbers. It won't, for example, help you write
code compatible with @c 2.4.x using wxWidgets @c 2.6.x.
*/

112
docs/doxygen/overviews/bitmap.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page bitmap_overview Bitmaps and icons overview
Classes: #wxBitmap, #wxBitmapHandler, #wxIcon, #wxCursor.
The wxBitmap class encapsulates the concept of a platform-dependent bitmap,
either monochrome or colour. Platform-specific methods for creating a
@@ -24,30 +24,30 @@
All wxWidgets platforms support XPMs for small bitmaps and icons.
You may include the XPM inline as below, since it's C code, or you
can load it at run-time.
@code
#include "mondrian.xpm"
@endcode
Sometimes you wish to use a .ico resource on Windows, and XPMs on
other platforms (for example to take advantage of Windows' support for multiple icon resolutions).
A macro, #wxICON, is available which creates an icon using an XPM
on the appropriate platform, or an icon resource on Windows.
@code
wxIcon icon(wxICON(mondrian));
// Equivalent to:
#if defined(__WXGTK__) || defined(__WXMOTIF__)
wxIcon icon(mondrian_xpm);
#endif
#if defined(__WXMSW__)
wxIcon icon("mondrian");
#endif
@endcode
There is also a corresponding #wxBITMAP macro which allows
to create the bitmaps in much the same way as #wxICON creates
icons. It assumes that bitmaps live in resources under Windows or OS2 and XPM
@@ -55,11 +55,11 @@
included before this macro is used, of course, and the name of the bitmap
should be the same as the resource name under Windows with @c _xpm
suffix). For example:
@code
// an easy and portable way to create a bitmap
wxBitmap bmp(wxBITMAP(bmpname));
// which is roughly equivalent to the following
#if defined(__WXMSW__) || defined(__WXPM__)
wxBitmap bmp("bmpname", wxBITMAP_TYPE_RESOURCE);
@@ -67,17 +67,17 @@
wxBitmap bmp(bmpname_xpm, wxBITMAP_TYPE_XPM);
#endif
@endcode
You should always use wxICON and wxBITMAP macros because they work for any
platform (unlike the code above which doesn't deal with wxMac, wxX11, ...) and
are more short and clear than versions with @c #ifdefs. Even better,
use the same XPMs on all platforms.
@ref supportedbitmapformats_overview
@ref bitmaphandlers_overview
@section supportedbitmapformats Supported bitmap file formats
The following lists the formats handled on different platforms. Note
that missing or partially-implemented formats are automatically supplemented
by the #wxImage to load the data, and then converting
@@ -89,79 +89,79 @@
very differently, depending on colour depths and platform.
@b wxBitmap
Under Windows, wxBitmap may load the following formats:
Windows bitmap resource (wxBITMAP_TYPE_BMP_RESOURCE)
Windows bitmap file (wxBITMAP_TYPE_BMP)
XPM data and file (wxBITMAP_TYPE_XPM)
All formats that are supported by the #wxImage class.
Under wxGTK, wxBitmap may load the following formats:
XPM data and file (wxBITMAP_TYPE_XPM)
All formats that are supported by the #wxImage class.
Under wxMotif and wxX11, wxBitmap may load the following formats:
XBM data and file (wxBITMAP_TYPE_XBM)
XPM data and file (wxBITMAP_TYPE_XPM)
All formats that are supported by the #wxImage class.
@b wxIcon
Under Windows, wxIcon may load the following formats:
Windows icon resource (wxBITMAP_TYPE_ICO_RESOURCE)
Windows icon file (wxBITMAP_TYPE_ICO)
XPM data and file (wxBITMAP_TYPE_XPM)
Under wxGTK, wxIcon may load the following formats:
XPM data and file (wxBITMAP_TYPE_XPM)
All formats that are supported by the #wxImage class.
Under wxMotif and wxX11, wxIcon may load the following formats:
XBM data and file (wxBITMAP_TYPE_XBM)
XPM data and file (wxBITMAP_TYPE_XPM)
All formats that are supported by the #wxImage class.
@b wxCursor
Under Windows, wxCursor may load the following formats:
Windows cursor resource (wxBITMAP_TYPE_CUR_RESOURCE)
Windows cursor file (wxBITMAP_TYPE_CUR)
Windows icon file (wxBITMAP_TYPE_ICO)
Windows bitmap file (wxBITMAP_TYPE_BMP)
Under wxGTK, wxCursor may load the following formats (in additional
to stock cursors):
None (stock cursors only).
Under wxMotif and wxX11, wxCursor may load the following formats:
XBM data and file (wxBITMAP_TYPE_XBM)
@section bitmaphandlers Bitmap format handlers
To provide extensibility, the functionality for loading and saving bitmap formats
is not implemented in the wxBitmap class, but in a number of handler classes,
derived from wxBitmapHandler. There is a static list of handlers which wxBitmap
@@ -172,7 +172,7 @@
then call the static function wxBitmap::AddHandler.
@b Note: bitmap handlers are not implemented on all platforms, and new ones rarely need
to be implemented since wxImage can be used for loading most formats, as noted earlier.
*/

244
docs/doxygen/overviews/bookctrl.h
View File

@@ -7,167 +7,167 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page bookctrl_overview wxBookCtrl overview
Classes: #wxNotebook, #wxListbook, #wxChoicebook,
#wxTreebook, #wxToolbook
#Introduction
@ref bestbookctrl_overview
@section wxbookctrlintro Introduction
A book control is a convenient way of displaying multiple pages of information,
displayed one page at a time. wxWidgets has five variants of this control:
#wxNotebook: uses a row of tabs
#wxListbook: controlled by a #wxListCtrl
#wxChoicebook: controlled by a #wxChoice
#wxTreebook: controlled by a #wxTreeCtrl
#wxToolbook: controlled by a #wxToolBar
See @ref samplenotebook_overview for an example of wxBookCtrl usage.
@section wxbestbookctrl Best book
wxBookCtrl is mapped to the class best suited for a given platform.
Currently it provides #wxChoicebook for smartphones equipped with
WinCE, and #wxNotebook for all other platforms. The mapping consists of:
wxBookCtrl
wxChoicebook or wxNotebook
wxBookCtrlEvent
wxChoicebookEvent or wxNotebookEvent
wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGED
wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGED or wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED
wxEVT_COMMAND_BOOKCTRL_PAGE_CHANGING
wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING or wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING
EVT_BOOKCTRL_PAGE_CHANGED(id, fn)
EVT_CHOICEBOOK_PAGE_CHANGED(id, fn) or EVT_NOTEBOOK_PAGE_CHANGED(id, fn)
EVT_BOOKCTRL_PAGE_CHANGING(id, fn)
EVT_CHOICEBOOK_PAGE_CHANGING(id, fn) or EVT_NOTEBOOK_PAGE_CHANGING(id, fn)
For orientation of the book controller, use following flags in style:
@b wxBK_TOP
controller above pages
@b wxBK_BOTTOM
controller below pages
@b wxBK_LEFT
controller on the left
@b wxBK_RIGHT
controller on the right
@b wxBK_DEFAULT
native controller placement
*/

16
docs/doxygen/overviews/bufferclasses.h
View File

@@ -7,23 +7,23 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page bufferclasses_overview Buffer classes overview
wxWidgets uses two classes of classes for dealing with buffers in memory.
The first is one for dealing with character buffers, namely wxCharBuffer for char pointer or multi-byte c strings and wxWCharBuffer for wchar_t pointer or wide character c strings.
Secondly, wxWidgets uses, although only rarely currently, wxMemoryBuffer for dealing with raw buffers in memory.
@ref cbov_overview
@section wxcbov wxXCharBuffer Overview
@b General Usage
As mentioned, wxCharBuffer and its wide character variant wxWCharBuffer deal with c strings in memory. They have two constructors, one in which you pass the c string you want them to have a copy of, and another where you specify the size of the buffer in memory in characters you want.
wxCharBuffer and its variant only contain the c string as a member, so they can be used safely to c functions with variable arguments such as printf. They also contain standard assignment, character access operators and a copy constructor.
@b Destruction
It should be noted that on destruction wxCharBuffer and its wide character variant delete the c string that hold onto. If you want to get the pointer to the buffer and don't want wxCharBuffer to delete it on destruction, use the member function release to do so.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page commondialogs_overview Common dialogs overview
Classes: #wxColourDialog, #wxFontDialog,
#wxPrintDialog, #wxFileDialog,
#wxDirDialog, #wxTextEntryDialog,
@@ -36,10 +36,10 @@
@ref messagedialog_overview
@ref singlechoicedialog_overview
@ref multichoicedialog_overview
@section wxcolourdialogoverview wxColourDialog overview
Classes: #wxColourDialog, #wxColourData
The wxColourDialog presents a colour selector to the user, and returns
with colour information.
@@ -69,7 +69,7 @@
a grey scale for the custom colours. If the user did not cancel
the dialog, the application retrieves the selected colour and
uses it to set the background of a window.
@code
wxColourData data;
data.SetChooseFull(@true);
@@ -78,7 +78,7 @@
wxColour colour(i*16, i*16, i*16);
data.SetCustomColour(i, colour);
}
wxColourDialog dialog(this, );
if (dialog.ShowModal() == wxID_OK)
{
@@ -90,11 +90,11 @@
myWindow-Refresh();
}
@endcode
@section wxfontdialogoverview wxFontDialog overview
Classes: #wxFontDialog, #wxFontData
The wxFontDialog presents a font selector to the user, and returns
with font and colour information.
@@ -117,12 +117,12 @@
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;
data.SetInitialFont(canvasFont);
data.SetColour(canvasTextColour);
wxFontDialog dialog(this, );
if (dialog.ShowModal() == wxID_OK)
{
@@ -132,19 +132,19 @@
myWindow-Refresh();
}
@endcode
@section wxprintdialogoverview 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
an excerpt from this example.
@section wxfiledialogoverview 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
@@ -163,51 +163,51 @@
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:
@code
"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
@endcode
@section wxdirdialogoverview wxDirDialog overview
Classes: #wxDirDialog
This dialog shows a directory selector dialog, allowing the user to select a single
directory.
@section wxtextentrydialogoverview 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
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
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
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
Classes: #wxMultiChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one or more of them.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page config_overview 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
@@ -20,16 +20,16 @@
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.
On the other hand, the features provided make them very useful for storing all
kinds of small to medium volumes of hierarchically-organized, heterogeneous
data. In short, this is a place where you can conveniently stuff all your data
@@ -41,7 +41,7 @@
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
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
@@ -50,9 +50,9 @@
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
details (including how to read/write these entries) may be found in
the documentation for #wxConfigBase.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page constraints_overview Constraints overview
Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint.
@b Note: constraints are now deprecated and you should use #sizers instead.
Objects of class wxLayoutConstraint can be associated with a window to define
@@ -17,8 +17,8 @@
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
@@ -27,8 +27,8 @@
@b height: represents the height of the window
@b centreX: represents the horizontal centre point of the window
@b centreY: represents the vertical centre point of the window
The constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
To calculate the position and size of the control, the layout algorithm needs to
@@ -39,20 +39,20 @@
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
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 (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
@section constraintlayoutdetails 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
@@ -83,7 +83,7 @@
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
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.
Because the algorithm is iterative, the order in which constraints are considered is
@@ -95,82 +95,82 @@
right border IsSameAs(parent, wxRight) and then create the first one by
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
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-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));
// Set constraints for panel subwindow
wxLayoutConstraints *c1 = new wxLayoutConstraints;
c1-left.SameAs (frame, wxLeft);
c1-top.SameAs (frame, wxTop);
c1-right.PercentOf (frame, wxWidth, 50);
c1-height.PercentOf (frame, wxHeight, 50);
frame-panel-SetConstraints(c1);
// Set constraints for scrollWindow subwindow
wxLayoutConstraints *c2 = new wxLayoutConstraints;
c2-left.SameAs (frame-panel, wxRight);
c2-top.SameAs (frame, wxTop);
c2-right.SameAs (frame, wxRight);
c2-height.PercentOf (frame, wxHeight, 50);
frame-scrollWindow-SetConstraints(c2);
// Set constraints for text subwindow
wxLayoutConstraints *c3 = new wxLayoutConstraints;
c3-left.SameAs (frame, wxLeft);
c3-top.Below (frame-panel);
c3-right.SameAs (frame, wxRight);
c3-bottom.SameAs (frame, wxBottom);
frame-text_window-SetConstraints(c3);
@endcode
@section panelitemlayoutexample 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
takes up 40 percent of the panel width, and the multitext item takes up
the remainder of the width. Margins of 5 pixels are used.
@code
// Create some panel items
wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ;
wxLayoutConstraints *b1 = new wxLayoutConstraints;
b1-centreX.SameAs (frame-panel, wxCentreX);
b1-top.SameAs (frame-panel, wxTop, 5);
b1-width.PercentOf (frame-panel, wxWidth, 80);
b1-height.PercentOf (frame-panel, wxHeight, 10);
btn1-SetConstraints(b1);
wxListBox *list = new wxListBox(frame-panel, -1, "A list",
wxPoint(-1, -1), wxSize(200, 100));
wxLayoutConstraints *b2 = new wxLayoutConstraints;
b2-top.Below (btn1, 5);
b2-left.SameAs (frame-panel, wxLeft, 5);
b2-width.PercentOf (frame-panel, wxWidth, 40);
b2-bottom.SameAs (frame-panel, wxBottom, 5);
list-SetConstraints(b2);
wxTextCtrl *mtext = new wxTextCtrl(frame-panel, -1, "Multiline text", "Some text",
wxPoint(-1, -1), wxSize(150, 100), wxTE_MULTILINE);
wxLayoutConstraints *b3 = new wxLayoutConstraints;
b3-top.Below (btn1, 5);
b3-left.RightOf (list, 5);
@@ -178,7 +178,7 @@
b3-bottom.SameAs (frame-panel, wxBottom, 5);
mtext-SetConstraints(b3);
@endcode
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page container_overview 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
@@ -28,7 +28,7 @@
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
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
@@ -48,7 +48,7 @@
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
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
@@ -59,7 +59,7 @@
wxArrayString is somewhat special: it is an optimized version of wxArray which
uses its knowledge about #wxString reference counting
schema.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page dataobject_overview wxDataObject overview
Classes: #wxDataObject,
#wxClipboard,
#wxDataFormat,
@@ -22,7 +22,7 @@
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
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
@@ -38,43 +38,43 @@
should do.
#The data provider (source) duties
#The data receiver (target) duties
@section wxdataobjectsource The data provider (source) duties
The data provider is responsible for creating a
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
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
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).
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
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
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
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
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
data itself may be requested by calling
wxDropTarget::GetData method which fills
the data object.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page datetime_overview Date and time classes overview
Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
#Introduction
@ref alldatetimeclasses_overview
@@ -20,89 +20,89 @@
#Daylight saving time (DST)
@ref tdateholidays_overview
#Compatibility
@section introductiontowxdatetime Introduction
wxWidgets provides a set of powerful classes to work with dates and times. Some
of the supported features of #wxDateTime class are:
Wide range
The range of supported dates goes from about 4714 B.C. to
some 480 million years in the future.
Precision
Not using floating point calculations anywhere ensures that
the date calculations don't suffer from rounding errors.
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
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 -
moment in time, there are also two classes -
#wxTimeSpan and #wxDateSpan - which
represent the intervals of time.
There are also helper classes which are used together with wxDateTime:
There are also helper classes which are used together with wxDateTime:
#wxDateTimeHolidayAuthority which is used
to determine whether a given date is a holiday or not and
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
superseded by wxDateTime.
@section wxdatetimecharacteristics wxDateTime characteristics
#wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
however this is not visible to the class users (in particular, dates prior to
@@ -116,7 +116,7 @@
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
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
@@ -124,13 +124,13 @@
region, dependent). Future versions will probably have Julian calendar support
as well and support for other calendars (Maya, Hebrew, Chinese...) is not
ruled out.
@section dateandtimespansdifference 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
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.
@@ -139,7 +139,7 @@
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
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
this kind is not always well-defined. Consider, for example, Jan 31 + '1
@@ -153,78 +153,78 @@
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
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:
@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.
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
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
which take the broken down date assume that these values are for the local
@@ -240,9 +240,9 @@
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
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
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
@@ -257,16 +257,16 @@
usually you will just use one of the @ref datetime_overview and
let the conversion constructor do the job.
I.e. you would just write
@code
wxDateTime dt(...whatever...);
printf("The time is %s in local time zone", dt.FormatTime().c_str());
printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
@endcode
@section tdatedst 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
@@ -280,18 +280,18 @@
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
TODO.
@section tdatecompatibility 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.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page dc_overview Device context overview
Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
#wxMetafileDC, #wxMemoryDC, #wxPrinterDC,
#wxScreenDC, #wxClientDC, #wxPaintDC,
@@ -21,8 +21,8 @@
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.
@@ -30,11 +30,11 @@
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.
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)
{
@@ -42,12 +42,12 @@
DrawMyPicture(dc);
}
@endcode
Try to write code so it is parameterised by wxDC - if you do this, the same piece of code may
write to a number of different devices, by passing a different device context. This doesn't
work for everything (for example not all device contexts support bitmap drawing) but
will work most of the time.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page debugging_overview Debugging overview
Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
@ref logfunctions_overview, @ref debugmacros_overview
Various classes, functions and macros are provided in wxWidgets to help you debug
@@ -41,12 +41,12 @@
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
@@ -59,28 +59,28 @@
#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)
{
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
Class: #wxDebugContext
wxDebugContext is a class for performing various debugging and memory tracing
@@ -93,27 +93,27 @@
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::SetFile("c:\\temp\\debug.log");
wxString *thing = new wxString;
char *ordinaryNonObject = new char[1000];
wxDebugContext::Dump();
wxDebugContext::PrintStatistics();
@endcode
You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it
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.
*/

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

@@ -7,30 +7,30 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page dialog_overview 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.
For a set of dialog convenience functions, including file selection, see
@ref dialogfunctions_overview.
See also #wxTopLevelWindow and #wxWindow for inherited
member functions. Validation of data in controls is covered in @ref validator_overview.
@ref autoscrollingdialogs_overview
@section autoscrollingdialogs Automatic scrolling dialogs
As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxWidgets applications to adapt
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
@@ -44,8 +44,8 @@
standard adapter class wxStandardDialogLayoutAdapter) will
make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog.
This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or wxDialog::ShowModal:
If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, the pages are made scrollable and
no other adaptation is done.
wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
@@ -56,8 +56,8 @@
All the children apart from standard buttons are reparented onto a new #wxScrolledWindow object,
using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and
standard button sizer.
@b Customising scrolling adaptation
In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxWidgets will
search for standard buttons by setting wxDialog::SetLayoutAdaptationLevel. By default,
@@ -70,8 +70,8 @@
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 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,
@@ -79,11 +79,11 @@
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.
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;
@@ -91,13 +91,13 @@
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.
@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.
*/

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

@@ -7,14 +7,14 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page dnd_overview Drag and drop overview
Classes: #wxDataObject,
#wxTextDataObject,
#wxDropSource,
#wxDropTarget,
#wxTextDropTarget,
Classes: #wxDataObject,
#wxTextDataObject,
#wxDropSource,
#wxDropTarget,
#wxTextDropTarget,
#wxFileDropTarget
Note that wxUSE_DRAG_AND_DROP must be defined in setup.h in order
to use drag and drop in wxWidgets.
@@ -27,25 +27,25 @@
class.
To be a @e drag source, i.e. to provide the data which may be dragged by
the user elsewhere, you should implement the following steps:
@b Preparation: First of all, a data object must be created and
initialized with the data you wish to drag. For example:
@code
wxTextDataObject my_data("This text will be dragged.");
@endcode
@b Drag start: To start the dragging process (typically in response to a
mouse click) you must call wxDropSource::DoDragDrop
like this:
@code
wxDropSource dragSource( this );
dragSource.SetData( my_data );
wxDragResult result = dragSource.DoDragDrop( TRUE );
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
@@ -54,42 +54,44 @@
are called - see below.
@b Processing the result: DoDragDrop() returns an @e effect code which
is one of the values of @c wxDragResult enum (explained #here):
@code
switch (result)
{
case wxDragCopy: /* copy the data */ break;
case wxDragMove: /* move the data */ break;
default: /* do nothing */ break;
}
@endcode
To be a @e drop target, i.e. to receive the data dropped by the user you should
follow the instructions below:
@b Initialization: For a window to be a drop target, it needs to have
an associated #wxDropTarget object. Normally, you will
call wxWindow::SetDropTarget during window
creation associating your drop target with it. You must derive a class from
wxDropTarget and override its pure virtual methods. Alternatively, you may
derive from #wxTextDropTarget or
#wxFileDropTarget and override their OnDropText()
or OnDropFiles() method.
@b Drop: When the user releases the mouse over a window, wxWidgets
asks the associated wxDropTarget object if it accepts the data. For this,
a #wxDataObject must be associated with the drop target
and this data object will be responsible for the format negotiation between
the drag source and the drop target. If all goes well, then #OnData
will get called and the wxDataObject belonging to the drop target can get
filled with data.
@b The end: After processing the data, DoDragDrop() returns either
wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
and Alt at the moment of the drop. There is currently no way for the drop
target to change this return code.
*/
{
case wxDragCopy: /* copy the data */ break;
case wxDragMove: /* move the data */
break;
default: /* do nothing */
break;
}
@endcode
To be a @e drop target, i.e. to receive the data dropped by the user you should
follow the instructions below:
@b Initialization: For a window to be a drop target, it needs to have
an associated #wxDropTarget object. Normally, you will
call wxWindow::SetDropTarget during window
creation associating your drop target with it. You must derive a class from
wxDropTarget and override its pure virtual methods. Alternatively, you may
derive from #wxTextDropTarget or
#wxFileDropTarget and override their OnDropText()
or OnDropFiles() method.
@b Drop: When the user releases the mouse over a window, wxWidgets
asks the associated wxDropTarget object if it accepts the data. For this,
a #wxDataObject must be associated with the drop target
and this data object will be responsible for the format negotiation between
the drag source and the drop target. If all goes well, then #OnData
will get called and the wxDataObject belonging to the drop target can get
filled with data.
@b The end: After processing the data, DoDragDrop() returns either
wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
and Alt at the moment of the drop. There is currently no way for the drop
target to change this return code.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page docview_overview Document/view overview
Classes: #wxDocument, #wxView, #wxDocTemplate,
#wxDocManager, #wxDocParentFrame, #wxDocChildFrame,
#wxDocMDIParentFrame, #wxDocMDIChildFrame,
@@ -29,8 +29,8 @@
The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour.
These are the overall steps involved in creating an application based on the document/view framework:
Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization.
Define any subwindows
@@ -45,37 +45,37 @@
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.
Note that to activate framework functionality, you need to use some or all of
the wxWidgets @ref predefinedids_overview in your menus.
@b wxPerl note: The document/view framework is available in wxPerl. To use it,
you will need the following statements in your application code:
@code
use Wx::DocView;
use Wx ':docview'; # import constants (optional)
@endcode
@ref document_overview
@ref view_overview
@ref doctemplate_overview
@@ -84,10 +84,10 @@
@ref commandprocessor_overview
@ref filehistory_overview
@ref predefinedids_overview
@section wxdocumentoverview wxDocument overview
@ref docview_overview
Class: #wxDocument
The wxDocument class can be used to model an application's file-based
@@ -117,9 +117,9 @@
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
Class: #wxView
The wxView class can be used to model the viewing and editing component of
@@ -138,9 +138,9 @@
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
Class: #wxDocTemplate
The wxDocTemplate class is used to model the relationship between a
@@ -176,9 +176,9 @@
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
@ref docview_overview
Class: #wxDocManager
The wxDocManager class is part of the document/view framework supported by wxWidgets,
@@ -192,9 +192,9 @@
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
Classes: #wxCommand, #wxCommandProcessor
wxCommand is a base class for modelling an application command,
@@ -214,17 +214,17 @@
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
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
Classes: #wxFileHistory, #wxDocManager
wxFileHistory encapsulates functionality to record the last few files visited, and
@@ -245,19 +245,19 @@
@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)
EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
END_EVENT_TABLE()
void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
{
Close();
}
void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
{
wxString f(m_docManager-GetHistoryFile(event.GetId() - wxID_FILE1));
@@ -265,16 +265,16 @@
(void)m_docManager-CreateDocument(f, wxDOC_SILENT);
}
@endcode
@section predefinedids 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.
wxID_OPEN (5000)
wxID_CLOSE (5001)
wxID_NEW (5002)
@@ -288,7 +288,7 @@
wxID_PRINT (5010)
wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012)
*/

82
docs/doxygen/overviews/envvars.h
View File

@@ -7,36 +7,36 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page envvars_overview Environment variables
This section describes all environment variables that affect execution of
wxWidgets programs.
@c WXTRACE
(Debug build only.)
This variable can be set to a comma-separated list of trace masks used in
#wxLogTrace calls;
wxLog::AddTraceMask is called for every mask
in the list during wxWidgets initialization.
@c WXPREFIX
(Unix only.)
Overrides installation prefix. Normally, the prefix
is hard-coded and is the same as the value passed to @c configure via
@@ -44,32 +44,32 @@
@c /usr/local or @c /usr). You can set WXPREFIX if you are for example
distributing a binary version of an application and you don't know in advance
where it will be installed.
@c WXMODE
(wxMGL only.)
Sets MGL video mode. The value must be in form
@e widthx@e height-@e depth. The default is @c 640x480-16.
@c WXSTDERR
(wxMGL only.)
Redirects stderr output to a file.
*/

1192
docs/doxygen/overviews/eventhandling.h
View File

File diff suppressed because it is too large Load Diff

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

@@ -7,16 +7,16 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page exceptions_overview C++ exceptions overview
#Introduction
@ref exceptionstrategies_overview
#Technicalities
@section exceptionintroduction Introduction
wxWidgets had been started long before the exceptions were introduced in C++ so
it is not very surprising that it is not built around using them as some more
modern C++ libraries are. For instance, the library doesn't throw exceptions to
@@ -28,10 +28,10 @@
still doesn't use the exceptions by itself but it should be now safe to use the
exceptions in the user code and the library tries to help you with this. Please
note that making the library exception-safe is still work in progress.
@section exceptionstrategies Strategies for exceptions handling
There are several choice for using the exceptions in wxWidgets programs. First
of all, you may not use them at all. As stated above, the library doesn't throw
any exceptions by itself and so you don't have to worry about exceptions at all
@@ -40,27 +40,27 @@
Another strategy is to use exceptions only to signal truly fatal errors. In
this case you probably don't expect to recover from them and the default
behaviour -- to simply terminate the program -- may be appropriate. If it is
not, you may override #OnUnhandledException()
not, you may override #OnUnhandledException()
in your wxApp-derived class to perform any clean up tasks. Note, however, that
any information about the exact exception type is lost when this function is
called, so if you need you should override #OnRun() and
add a try/catch clause around the call of the base class version. This would
allow you to catch any exceptions generated during the execution of the main
event loop. To deal with the exceptions which may arise during the program
startup and/or shutdown you should insert try/catch clauses in
startup and/or shutdown you should insert try/catch clauses in
#OnInit() and/or #OnExit() as well.
Finally, you may also want to continue running even when certain exceptions
occur. If all of your exceptions may happen only in the event handlers of a
single class (or only in the classes derived from it), you may centralize your
exception handling code in #ProcessEvent
exception handling code in #ProcessEvent
method of this class. If this is impractical, you may also consider overriding
the wxApp::HandleEvent() which allows you to handle
all the exceptions thrown by any event handler.
@section exceptionstechnicalities Technicalities
To use any kind of exception support in the library you need to build it with
To use any kind of exception support in the library you need to build it with
@c wxUSE_EXCEPTIONS set to 1. This should be the case by default but
if it isn't, you should edit the @c include/wx/msw/setup.h file under
Windows or run @c configure with @c --enable-exceptions argument
@@ -68,9 +68,9 @@
On the other hand, if you do not plan to use exceptions, setting this
flag to 0 or using @c --disable-exceptions could result in a leaner and
slightly faster library.
As for any other library feature, there is a #sample
As for any other library feature, there is a #sample
showing how to use it. Please look at its sources for further information.
*/

12
docs/doxygen/overviews/file.h
View File

@@ -7,10 +7,10 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page file_overview File classes and functions overview
Classes: #wxFile, #wxDir, #wxTempFile,
Classes: #wxFile, #wxDir, #wxTempFile,
#wxTextFile
Functions: see @ref filefunctions_overview.
wxWidgets provides some functions and classes to facilitate working with files.
@@ -32,7 +32,7 @@
wxDir is a helper class for enumerating the files or subdirectories of a
directory. It may be used to enumerate all files, only files satisfying the
given template mask or only non-hidden files.
*/

160
docs/doxygen/overviews/font.h
View File

@@ -7,101 +7,101 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page font_overview wxFont overview
Class: #wxFont, #wxFontDialog
A font is an object which determines the appearance of text, primarily
when drawing text to a window or device context. A font is determined by
the following parameters (not all of them have to be specified, of course):
Point size
This is the standard way of referring to text size.
Family
Supported families are:
@b wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN.
@b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.
Style
The value can be @b wxNORMAL, wxSLANT or @b wxITALIC.
Weight
The value can be @b wxNORMAL, wxLIGHT or @b wxBOLD.
Underlining
The value can be @true or @false.
Face name
An optional string specifying the actual typeface to be used. If @NULL,
a default typeface will chosen based on the family.
Encoding
The font encoding (see @b wxFONTENCODING_XXX
constants and the @ref fontencoding_overview for more
details)
Specifying a family, rather than a specific typeface name, ensures a degree of
portability across platforms because a suitable font will be chosen for the
given font family, however it doesn't allow to choose a font precisely as the
@@ -113,26 +113,26 @@
standard Windows fonts, or if allowing the user to specify a face name, store
the family name with any file that might be transported to a different Windows
machine or other platform.
@b Note: There is currently a difference between the appearance
of fonts on the two platforms, if the mapping mode is anything other than
wxMM_TEXT. Under X, font size is always specified in points. Under MS
Windows, the unit for text is points but the text is scaled according to the
current mapping mode. However, user scaling on a device context will also
scale fonts under both environments.
@ref nativefontinformation_overview
@section nativefontinformation Native font information
An alternative way of choosing fonts is to use the native font description.
This is the only acceptable solution if the user is allowed to choose the font
using the #wxFontDialog because the selected font cannot
be described using only the family name and so, if only family name is stored
permanently, the user would almost surely see a different font in the program
later.
Instead, you should store the value returned by
Instead, you should store the value returned by
wxFont::GetNativeFontInfoDesc and pass
it to wxFont::SetNativeFontInfo later to
recreate exactly the same font.
@@ -142,7 +142,7 @@
implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods
are available for all the ports and should be used to make your program work
correctly when they are implemented later.
*/

160
docs/doxygen/overviews/fontencoding.h
View File

@@ -7,114 +7,114 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page fontencoding_overview Font encoding overview
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
note that we will only discuss 8-bit fonts here and not
#Unicode.
Font encoding support is ensured by several classes:
#wxFont itself, but also
#wxFontEnumerator and
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):
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).
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).
wxFONTENCODING_ISO8859_1..15
ISO8859 family encodings which are
usually used by all non-Microsoft operating systems
wxFONTENCODING_KOI8
Standard Cyrillic encoding for the Internet
(but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251)
wxFONTENCODING_CP1250
Microsoft analogue of ISO8859-2
wxFONTENCODING_CP1251
Microsoft analogue of ISO8859-5
wxFONTENCODING_CP1252
Microsoft analogue of ISO8859-1
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
@@ -129,13 +129,13 @@
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
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
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.
@@ -147,7 +147,7 @@
All these topics are illustrated by the @ref samplefont_overview;
please refer to it and the documentation of the classes mentioned here for
further explanations.
*/

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

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page fs_overview wxFileSystem
The wxHTML library uses a @b virtual file systems mechanism
similar to the one used in Midnight Commander, Dos Navigator,
FAR or almost any modern file manager. It allows the user to access
@@ -17,8 +17,8 @@
generated files that exist only in memory are also supported.
@b Classes
Three classes are used in order to provide virtual file systems mechanism:
The #wxFSFile class provides information
about opened file (name, input stream, mime type and anchor).
The #wxFileSystem class is the interface.
@@ -29,111 +29,111 @@
the VFS mechanism. You can derive your own handler and pass it to
wxFileSystem's AddHandler() method. In the new handler you only need to
override the OpenFile() and CanOpen() methods.
@b Locations
Locations (aka filenames aka addresses) are constructed from four parts:
@b protocol - handler can recognize if it is able to open a
file by checking its protocol. Examples are "http", "file" or "ftp".
@b right location - is the name of file within the protocol.
In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
@b anchor - an anchor is optional and is usually not present.
In "index.htm#chapter2" the anchor is "chapter2".
@b left location - this is usually an empty string.
@b left location - this is usually an empty string.
It is used by 'local' protocols such as ZIP.
See Combined Protocols paragraph for details.
@b Combined Protocols
The left location precedes the protocol in the URL string.
The left location precedes the protocol in the URL string.
It is not used by global protocols like HTTP but it becomes handy when nesting
protocols - for example you may want to access files in a ZIP archive:
file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax
In this example, the protocol is "zip", right location is
"reference/fopen.htm", anchor is "syntax" and left location
is "file:archives/cpp_doc.zip".
is "file:archives/cpp_doc.zip".
There are @b two protocols used in this example: "zip" and "file".
@b File Systems Included in wxHTML
The following virtual file system handlers are part of wxWidgets so far:
@b wxArchiveFSHandler
A handler for archives such as zip
and tar. Include file is wx/fs_arc.h. URLs examples:
"archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
@b wxFilterFSHandler
A handler for compression schemes such
as gzip. Header is wx/fs_filter.h. URLs are in the form, e.g.:
"document.ps.gz#gzip:".
@b wxInternetFSHandler
A handler for accessing documents
via HTTP or FTP protocols. Include file is wx/fs_inet.h.
@b wxMemoryFSHandler
This handler allows you to access
This handler allows you to access
data stored in memory (such as bitmaps) as if they were regular files.
See @ref memoryfshandler_overview for details.
Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g.
Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g.
"memory:myfile.htm"
In addition, wxFileSystem itself can access local files.
@b Initializing file system handlers
Use wxFileSystem::AddHandler to initialize
a handler, for example:
@code
#include wx/fs_mem.h
...
bool MyApp::OnInit()
{
wxFileSystem::AddHandler(new wxMemoryFSHandler);
...
}
@endcode
*/

58
docs/doxygen/overviews/grid.h
View File

@@ -7,77 +7,77 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page grid_overview wxGrid classes overview
Classes: #wxGrid
#Introduction
@ref simplewxgridexample_overview
@ref complexwxgridexample_overview
@ref gridclassesrelations_overview
@ref keyboardandmouseinwxgrid_overview
@section introductiontowxgrid Introduction
wxGrid and its related classes are used for displaying and editing tabular data.
@section simplewxgridexample Getting started: a simple example
For simple applications you need only refer to the wxGrid class in your
code. This example shows how you might create a grid in a frame or
dialog constructor and illustrates some of the formatting functions.
dialog constructor and illustrates some of the formatting functions.
@code
// Create a wxGrid object
grid = new wxGrid( this,
-1,
wxPoint( 0, 0 ),
wxSize( 400, 300 ) );
// Then we call CreateGrid to set the dimensions of the grid
// (100 rows and 10 columns in this example)
grid-CreateGrid( 100, 10 );
// We can set the sizes of individual rows and columns
// in pixels
grid-SetRowSize( 0, 60 );
grid-SetColSize( 0, 120 );
// And set grid cell contents as strings
grid-SetCellValue( 0, 0, "wxGrid is good" );
// We can specify that some cells are read-only
grid-SetCellValue( 0, 3, "This is read-only" );
grid-SetReadOnly( 0, 3 );
// Colours can be specified for grid cell contents
grid-SetCellValue(3, 3, "green on grey");
grid-SetCellTextColour(3, 3, *wxGREEN);
grid-SetCellBackgroundColour(3, 3, *wxLIGHT_GREY);
// We can specify the some cells will store numeric
// values rather than strings. Here we set grid column 5
// to hold floating point values displayed with width of 6
// We can specify the some cells will store numeric
// values rather than strings. Here we set grid column 5
// to hold floating point values displayed with width of 6
// and precision of 2
grid-SetColFormatFloat(5, 6, 2);
grid-SetCellValue(0, 6, "3.1415");
@endcode
@section complexwxgridexample A more complex example
Yet to be written
@section wxgridclassesrelations How the wxGrid classes relate to each other
Yet to be written
@section keyboardandmouseinwxgrid Keyboard and mouse actions
Yet to be written
*/

82
docs/doxygen/overviews/helloworld.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page helloworld_overview wxWidgets Hello World sample
As many people have requested a mini-sample to be published here
so that some quick judgment concerning syntax
and basic principles can be made, you can now look at wxWidgets'
@@ -19,63 +19,63 @@
or using one global include (#include "wx/wx.h"). This is
also useful on platforms which support precompiled headers such
as all major compilers on the Windows platform.
@code
//
// file name: hworld.cpp
//
// purpose: wxWidgets "Hello world"
//
// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"
#ifdef __BORLANDC__
#pragma hdrstop
#endif
#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif
@endcode
Practically every app should define a new class derived from wxApp.
By overriding wxApp's OnInit() the program can be initialized,
e.g. by creating a new main window.
e.g. by creating a new main window.
@code
class MyApp: public wxApp
{
virtual bool OnInit();
};
@endcode
The main window is created by deriving a class from wxFrame and
The main window is created by deriving a class from wxFrame and
giving it a menu and a status bar in its constructor. Also, any class
that wishes to respond to any "event" (such as mouse clicks or
messages from the menu or a button) must declare an event table
using the macro below. Finally, the way to react to such events
must be done in "handlers". In our sample, we react to two menu items,
messages from the menu or a button) must declare an event table
using the macro below. Finally, the way to react to such events
must be done in "handlers". In our sample, we react to two menu items,
one for "Quit" and one for displaying an "About" window. These
handlers should not be virtual.
@code
class MyFrame: public wxFrame
{
public:
MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);
private:
DECLARE_EVENT_TABLE()
};
@endcode
In order to be able to react to a menu command, it must be given a unique
identifier such as a const or an enum.
@code
enum
{
@@ -83,7 +83,7 @@
ID_About,
};
@endcode
We then proceed to actually implement an event table in which the events
are routed to their respective handler functions in the class MyFrame.
There are predefined macros for routing all common events, ranging from
@@ -95,27 +95,27 @@
the (only) parameter in an event handler is a reference to a wxEvent object,
which holds various information about the event (such as the ID of and a
pointer to the class, which emitted the event).
@code
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(ID_Quit, MyFrame::OnQuit)
EVT_MENU(ID_About, MyFrame::OnAbout)
END_EVENT_TABLE()
@endcode
As in all programs there must be a "main" function. Under wxWidgets main is implemented
using this macro, which creates an application instance and starts the program.
@code
IMPLEMENT_APP(MyApp)
@endcode
As mentioned above, wxApp::OnInit() is called upon startup and should be
used to initialize the program, maybe showing a "splash screen" and creating
the main window (or several). The frame should get a title bar text ("Hello World")
and a position and start-up size. One frame can also be declared to be the
top window. Returning @true indicates a successful initialization.
@code
bool MyApp::OnInit()
{
@@ -125,46 +125,46 @@
return @true;
}
@endcode
In the constructor of the main window (or later on) we create a menu with two menu
items as well as a status bar to be shown at the bottom of the main window. Both have
In the constructor of the main window (or later on) we create a menu with two menu
items as well as a status bar to be shown at the bottom of the main window. Both have
to be "announced" to the frame with respective calls.
@code
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)@NULL, -1, title, pos, size)
{
wxMenu *menuFile = new wxMenu;
menuFile-Append( ID_About, "" );
menuFile-AppendSeparator();
menuFile-Append( ID_Quit, "E" );
wxMenuBar *menuBar = new wxMenuBar;
menuBar-Append( menuFile, "" );
SetMenuBar( menuBar );
CreateStatusBar();
SetStatusText( "Welcome to wxWidgets!" );
}
@endcode
Here are the actual event handlers. MyFrame::OnQuit() closes the main window
by calling Close(). The parameter @true indicates that other windows have no veto
power such as after asking "Do you really want to close?". If there is no other
power such as after asking "Do you really want to close?". If there is no other
main window left, the application will quit.
@code
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close( @true );
}
@endcode
MyFrame::OnAbout() will display a small window with some text in it. In this
case a typical "About" window with information about the program.
@code
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
@@ -172,7 +172,7 @@
"About Hello World", wxOK | wxICON_INFORMATION );
}
@endcode
*/

222
docs/doxygen/overviews/html.h
View File

@@ -7,15 +7,15 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page html_overview wxHTML overview
The wxHTML library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try #http://www.mozilla.org.
wxHTML can be used as a generic rich text viewer - for example to display
wxHTML can be used as a generic rich text viewer - for example to display
a nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a #wxFileSystem
database searching. There is a #wxFileSystem
class which allows you to use your own virtual file systems.
wxHtmlWindow supports tag handlers. This means that you can easily
extend wxHtml library with new, unsupported tags. Not only that,
@@ -30,19 +30,19 @@
@ref cells_overview
@ref handlers_overview
@ref htmltagssupported_overview
@section wxhtmlquickstart wxHTML quick start
@b Displaying HTML
First of all, you must include wx/wxhtml.h.
Class #wxHtmlWindow (derived from wxScrolledWindow)
is used to display HTML documents.
It has two important methods: #LoadPage
It has two important methods: #LoadPage
and #SetPage.
LoadPage loads and displays HTML file while SetPage displays directly the
passed @b string. See the example:
@code
mywin - LoadPage("test.htm");
mywin - SetPage("htmlbody"
@@ -50,25 +50,25 @@
"Some error occurred :-H)"
"/body/hmtl");
@endcode
@b Displaying Help
See #wxHtmlHelpController.
@b Setting up wxHtmlWindow
Because wxHtmlWindow is derived from wxScrolledWindow and not from
wxFrame, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is
the title of HTML page displayed somewhere and the frame's titlebar is
the ideal place for it.
wxHtmlWindow provides 2 methods in order to handle this:
#SetRelatedFrame and
#SetRelatedStatusBar.
wxHtmlWindow provides 2 methods in order to handle this:
#SetRelatedFrame and
#SetRelatedStatusBar.
See the example:
@code
html = new wxHtmlWindow(this);
html - SetRelatedFrame(this, "HTML : %%s");
html - SetRelatedStatusBar(0);
@endcode
The first command associates the HTML object with its parent frame
(this points to wxFrame object there) and sets the format of the title.
Page title "Hello, world!" will be displayed as "HTML : Hello, world!"
@@ -78,30 +78,30 @@
@b Customizing wxHtmlWindow
You can customize wxHtmlWindow by setting font size, font face and
borders (space between border of window and displayed HTML). Related functions:
#SetFonts
#SetBorders
#ReadCustomization
#WriteCustomization
The last two functions are used to store user customization info wxConfig stuff
(for example in the registry under Windows, or in a dotfile under Unix).
@section printing HTML Printing
The wxHTML library provides printing facilities with several levels of complexity.
The easiest way to print an HTML document is to use
The wxHTML library provides printing facilities with several levels of complexity.
The easiest way to print an HTML document is to use
@ref htmleasyprinting_overview. It lets you print HTML documents with only one
command and you don't have to worry about deriving from the wxPrintout class at all. It is only a simple wrapper around the
command and you don't have to worry about deriving from the wxPrintout class at all. It is only a simple wrapper around the
#wxHtmlPrintout, normal wxWidgets printout class.
And finally there is the low level class #wxHtmlDCRenderer which you can use to
render HTML into a rectangular area on any DC. It supports rendering into multiple rectangles with the same
width. (The most common use of this is placing one rectangle on each page or printing into two columns.)
@section helpformat Help Files Format
wxHTML library uses a reduced version of MS HTML Workshop format.
Tex2RTF can produce these files when generating HTML, if you set @b htmlWorkshopFiles to @b @true in
your tex2rtf.ini file.
@@ -111,34 +111,34 @@
for wxHTML (or helpview) to read; and the .zip file can optionally be renamed to .htb.
@b Header file (.hhp)
Header file must contain these lines (and may contain additional lines which are ignored) :
@code
Contents file=filename.hhc
Index file=filename.hhk
Title=title of your book
Default topic=default page to be displayed.htm
@endcode
All filenames (including the Default topic) are relative to the
All filenames (including the Default topic) are relative to the
location of .hhp file.
@b Localization note: In addition, .hhp file may contain line
@code
Charset=rfc_charset
@endcode
which specifies what charset (e.g. "iso8859_1") was used in contents
and index files. Please note that this line is incompatible with
MS HTML Help Workshop and it would either silently remove it or complain
with some error. See also
with some error. See also
@ref nonenglish_overview.
@b Contents file (.hhc)
Contents file has HTML syntax and it can be parsed by regular HTML parser. It contains exactly one list
(@c ul....@c /ul statement):
@code
ul
li object type="text/sitemap"
param name="Name" value="@topic name@"
param name="ID" value=@numeric_id@
@@ -149,19 +149,19 @@
param name="ID" value=@numeric_id@
param name="Local" value="@filename.htm@"
/object
...
...
/ul
@endcode
You can modify value attributes of param tags. @e topic name is name of chapter/topic as is displayed in
contents, @e filename.htm is HTML page name (relative to .hhp file) and @e numeric_id is optional
contents, @e filename.htm is HTML page name (relative to .hhp file) and @e numeric_id is optional
- it is used only when you use wxHtmlHelpController::Display(int)
Items in the list may be nested - one @c li statement may contain a @c ul sub-statement:
@code
ul
li object type="text/sitemap"
param name="Name" value="Top node"
param name="Local" value="top.htm"
@@ -173,33 +173,33 @@
/object
...
/ul
li object type="text/sitemap"
param name="Name" value="Another Top"
param name="Local" value="top2.htm"
/object
...
...
/ul
@endcode
@b Index file (.hhk)
Index files have same format as contents file except that ID params are ignored and sublists are @b not
Index files have same format as contents file except that ID params are ignored and sublists are @b not
allowed.
@section filters Input Filters
The wxHTML library provides a mechanism for reading and displaying
files of many different file formats.
files of many different file formats.
wxHtmlWindow::LoadPage can load not
only HTML files but any known file. To make a file type known to wxHtmlWindow
you must create a #wxHtmlFilter filter and
register it using wxHtmlWindow::AddFilter.
@section cells Cells and Containers
This article describes mechanism used by
#wxHtmlWinParser and
This article describes mechanism used by
#wxHtmlWinParser and
#wxHtmlWindow to parse and display HTML documents.
@b Cells
You can divide any text (or HTML) into small fragments. Let's call these
@@ -209,54 +209,54 @@
See #wxHtmlCell.
@b Containers
Container is kind of cell that may contain sub-cells. Its size depends
on number and sizes of its sub-cells (and also depends on width of window).
See #wxHtmlContainerCell,
on number and sizes of its sub-cells (and also depends on width of window).
See #wxHtmlContainerCell,
wxHtmlCell::Layout.
This image shows the cells and containers:
@b Using Containers in Tag Handler
#wxHtmlWinParser provides a user-friendly way
of managing containers. It is based on the idea of opening and closing containers.
Use #OpenContainer to open new
a container @e within an already opened container. This new container is a
a container @e within an already opened container. This new container is a
@e sub-container of the old one. (If you want to create a new container with
the same depth level you can call @c CloseContainer(); OpenContainer();.)
Use #CloseContainer to close the
Use #CloseContainer to close the
container. This doesn't create a new container with same depth level but
it returns "control" to the parent container.
See explanation:
There clearly must be same number of calls to OpenContainer as to
CloseContainer.
@b Example
This code creates a new paragraph (container at same depth level)
with "Hello, world!":
@code
m_WParser - CloseContainer();
c = m_WParser - OpenContainer();
m_WParser - AddText("Hello, ");
m_WParser - AddText("world!");
m_WParser - CloseContainer();
m_WParser - OpenContainer();
@endcode
and here is image of the situation:
You can see that there was an opened container before the code was executed.
We closed it, created our own container, then closed our container and opened
new container. The result was that we had @e same depth level after
executing. This is general rule that should be followed by tag handlers:
leave depth level of containers unmodified (in other words, number of
OpenContainer and CloseContainer calls should be same within #HandleTag's body).
Notice that it would be usually better to use
Notice that it would be usually better to use
wxHtmlContainerCell::InsertCell instead
of adding text to the parser directly.
@section handlers Tag Handlers
The wxHTML library provides architecture of pluggable @e tag handlers.
Tag handler is class that understands particular HTML tag (or tags) and is
able to interpret it.
@@ -268,26 +268,26 @@
@b How it works
Common tag handler's #HandleTag method
works in four steps:
Save state of parent parser into local variables
Change parser state according to tag's params
Parse text between the tag and paired ending tag (if present)
Restore original parser state
See #wxHtmlWinParser for methods for modifying
parser's state. In general you can do things like opening/closing containers,
changing colors, fonts etc.
@b Providing own tag handlers
You should create new .cpp file and place following lines into it:
You should create new .cpp file and place following lines into it:
@code
#include mod_templ.h
#include forcelink.h
FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
@endcode
Then you must define handlers and one module.
@b Tag handlers
The handler is derived from #wxHtmlWinTagHandler
@@ -301,58 +301,58 @@
Starts handler definition. @e name is handler identifier (in fact
part of class name), @e tags is string containing list of tags
supported by this handler (in uppercase). This macro derives new class from
wxHtmlWinTagHandler and implements it is
wxHtmlWinTagHandler and implements it is
#GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
@b TAG_HANDLER_VARS
This macro starts block of variables definitions. (Variables are identical
to class attributes.) Example:
@code
TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
TAG_HANDLER_VARS
int my_int_var;
wxString something_else;
wxString something_else;
TAG_HANDLER_END(VARS_ONLY)
@endcode
This macro is used only in rare cases.
@b TAG_HANDLER_CONSTR(@e name)
This macro supplies object constructor. @e name is same name as the one
from TAG_HANDLER_BEGIN macro. Body of constructor follow after
this macro (you must use and ). Example:
@code
TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
TAG_HANDLER_VARS
int my_int_var;
TAG_HANDLER_CONSTR(vars2)
{ // !!!!!!
my_int_var = 666;
} // !!!!!!
my_int_var = 666;
} // !!!!!!
TAG_HANDLER_END(VARS2)
@endcode
Never used in wxHTML :-)
@b TAG_HANDLER_PROC(@e varib)
This is very important macro. It defines #HandleTag
method. @e varib is name of parameter passed to the method, usually
@e tag. Body of method follows after this macro.
Note than you must use and ! Example:
@code
TAG_HANDLER_BEGIN(TITLE, "TITLE")
TAG_HANDLER_PROC(tag)
{
printf("TITLE found...\n");
}
printf("TITLE found...\n");
}
TAG_HANDLER_END(TITLE)
@endcode
@b TAG_HANDLER_END(@e name)
Ends definition of tag handler @e name.
Ends definition of tag handler @e name.
@b Tags Modules
You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
TAGS_MODULE_END to inherit new module from
#wxHtmlTagsModule and to create instance of it.
See macros reference:
@@ -365,7 +365,7 @@
@b TAGS_MODULE_END(@e modname)
Ends the definition of module.
@b Example:
@code
TAGS_MODULE_BEGIN(Examples)
TAGS_MODULE_ADD(VARS_ONLY)
@@ -373,32 +373,32 @@
TAGS_MODULE_ADD(TITLE)
TAGS_MODULE_END(Examples)
@endcode
@section htmltagssupported Tags supported by wxHTML
wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it
wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it
is possible to display @e simple HTML documents with it. (For example it works fine with pages created
in Netscape Composer or generated by tex2rtf).
Following tables list all tags known to wxHTML, together with supported parameters.
A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is
either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent. Unless stated
either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent. Unless stated
otherwise, wxHTML is case-insensitive.
@b Table of common parameter values
We will use these substitutions in tags descriptions:
@code
[alignment] CENTER
LEFT
RIGHT
JUSTIFY
[v_alignment] TOP
BOTTOM
CENTER
[color] HTML 4.0-compliant colour specification
[fontsize] -2
-1
+0
@@ -413,23 +413,23 @@
5
6
7
[pixels] integer value that represents dimension in pixels
[percent] i%
[percent] i%
where i is integer
[url] an URL
[url] an URL
[string] text string
[coords] c(1),c(2),c(3),...,c(n)
where c(i) is integer
@endcode
@b List of supported tags
@code
A NAME=[string]
HREF=[url]
@@ -519,7 +519,7 @@
U
UL
@endcode
*/

12
docs/doxygen/overviews/imagelist.h
View File

@@ -7,18 +7,18 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page imagelist_overview wxImageList overview
Classes: #wxImageList
An image list is a list of images that may have transparent areas.
The class helps an application organise a collection of images
so that they can be referenced by integer index instead of by
pointer.
Image lists are used in #wxNotebook,
Image lists are used in #wxNotebook,
#wxListCtrl, #wxTreeCtrl and
some other control classes.
*/

26
docs/doxygen/overviews/internationalization.h
View File

@@ -7,15 +7,15 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page internationalization_overview Internationalization
Although internationalization of an application (i18n for short) involves far
more than just translating its text messages to another message - date, time and
currency formats need changing too, some languages are written left to right
and others right to left, character encoding may differ and many other things
may need changing too - it is a necessary first step. wxWidgets provides
facilities for message translation with its
facilities for message translation with its
#wxLocale class and is itself fully translated into several
languages. Please consult wxWidgets home page for the most up-to-date
translations - and if you translate it into one of the languages not done
@@ -34,10 +34,10 @@
with @e msgfmt program (part of gettext package) and have the extension .mo.
Only the binary files are needed during program execution.
The program i18n involves several steps:
Translating the strings in the program text using
#wxGetTranslation or equivalently the
Translating the strings in the program text using
#wxGetTranslation or equivalently the
#_() macro.
Extracting the strings to be translated from the program: this uses the
work done in the previous step because @c xgettext program used for string
@@ -51,7 +51,7 @@
language(s). It involves editing the .po file.
Compiling the .po file into .mo file to be used by the program.
Installing the .mo files with your application in the appropriate
location for the target system which is the one returned by
location for the target system which is the one returned by
wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages).
If the message catalogs are not installed in this default location you may
explicitly use #AddCatalogLookupPathPrefix() to
@@ -59,8 +59,8 @@
default directory.
Setting the appropriate locale in your program to use the strings for the
given language: see #wxLocale.
See also the http://www.gnu.org/software/gettext/manual/gettext.html.
See also @ref nonenglish_overview.
It focuses on handling charsets related problems.
@@ -73,7 +73,7 @@
code can recognise them even when translated. wxWidgets does not provide translations for all of these
currently. wxWidgets does not yet handle translated special key names such as Backspace,
End, Insert, etc.
*/

76
docs/doxygen/overviews/ipc.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page ipc_overview Interprocess communication overview
Classes: #wxServer,
#wxConnection,
#wxClient
@@ -17,16 +17,16 @@
interprocess communication and network programming. This section
only discusses one family of classes -- the DDE-like protocol --
but here's a list of other useful classes:
#wxSocketEvent,
#wxSocketBase,
#wxSocketClient,
#wxSocketServer: classes for the low-level TCP/IP API.
#wxProtocol, #wxURL, #wxFTP, #wxHTTP: classes
for programming popular Internet protocols.
wxWidgets' DDE-like protocol is a high-level protocol based on
Windows DDE. There are two implementations of this DDE-like
protocol: one using real DDE running on Windows only, and another
@@ -47,8 +47,8 @@
equivalent wxTCP... and wxDDE... classes can be used in much the
same way.
Three classes are central to the DDE-like API:
wxClient. This represents the client application, and is used
only within a client program.
wxServer. This represents the server application, and is used
@@ -57,8 +57,8 @@
client to the server - both the client and the server use an
instance of this class, one per connection. Most DDE transactions
operate on this object.
Messages between applications are usually identified by three
variables: connection object, topic name and item name. A data
string is a fourth element of some messages. To create a
@@ -82,8 +82,8 @@
overriding virtual functions in your class derived from
wxConnection allows you to handle the DDE messages.
To create a working server, the programmer must:
Derive a class from wxConnection, providing handlers for various messages sent to the server
side of a wxConnection (e.g. OnExecute, OnRequest, OnPoke). Only
the handlers actually required by the application need to be
@@ -94,11 +94,11 @@
derived connection class if the connection is accepted.
Create an instance of your server object and call Create to
activate it, giving it a service name.
To create a working client, the programmer must:
Derive a class from wxConnection, providing handlers for various
messages sent to the client side of a wxConnection (e.g.
OnAdvise). Only the handlers actually required by the application
@@ -115,19 +115,19 @@
a connection object of the derived class if the connection is
successful.
Use the wxConnection member functions to send messages to the server.
@ref datatransfer_overview
#Examples
@ref ddedetails_overview
@section datatransfer Data transfer
These are the ways that data can be transferred from one
application to another. These are methods of wxConnection.
@b Execute: the client calls the server with a data string representing
a command to be executed. This succeeds or fails, depending on the
server's willingness to answer. If the client wants to find the result
@@ -143,22 +143,22 @@
@b Advise: The client asks to be advised of any change in data
associated with a particular item. If the server agrees, the server will
send an OnAdvise message to the client along with the item and data.
The default data type is wxCF_TEXT (ASCII text), and the default data
size is the length of the null-terminated string. Windows-specific data
types could also be used on the PC.
@section ipcexamples Examples
See the sample programs @e server and @e client in the IPC
samples directory. Run the server, then the client. This demonstrates
using the Execute, Request, and Poke commands from the client, together
with an Advise loop: selecting an item in the server list box causes
that item to be highlighted in the client list box.
@section ddedetails More DDE details
A wxClient object initiates the client part of a client-server
DDE-like (Dynamic Data Exchange) conversation (available in both
Windows and Unix).
@@ -171,7 +171,7 @@
member can return a wxConnection of the required class, when a
connection is made.
For example:
@code
class MyConnection: public wxConnection {
public:
@@ -180,14 +180,14 @@
bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format)
{ wxMessageBox(topic, data); }
};
class MyClient: public wxClient {
public:
MyClient(void) {}
wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
};
@endcode
Here, @b MyConnection will respond to
#OnAdvise messages sent by the
server by displaying a message box.
@@ -201,16 +201,16 @@
request for a connection is accepted, and the client then
requests an @e Advise loop from the server (an Advise loop is
where the server calls the client when data has changed).
@code
wxString server = "4242";
wxString hostName;
wxGetHostName(hostName);
// Create a new client
MyClient *client = new MyClient;
connection = (MyConnection *)client-MakeConnection(hostName, server, "IPC TEST");
if (!connection)
{
wxMessageBox("Failed to make connection to server", "Client Demo Error");
@@ -218,7 +218,7 @@
}
connection-StartAdvise("Item");
@endcode
*/

10
docs/doxygen/overviews/listctrl.h
View File

@@ -7,12 +7,12 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page listctrl_overview wxListCtrl overview
Classes: #wxListCtrl, #wxImageList
Sorry, this topic has yet to be written.
*/

80
docs/doxygen/overviews/log.h
View File

@@ -7,29 +7,31 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page log_overview wxLog classes overview
Classes: #wxLog,
#wxLogStderr,
#wxLogStream,
#wxLogTextCtrl,
#wxLogWindow,
#wxLogGui,
#wxLogNull,
#wxLogBuffer,
#wxLogChain,
#wxLogInterposer,
#wxLogInterposerTemp,
#wxStreamToTextRedirector
This is a general overview of logging classes provided by wxWidgets. The word
logging here has a broad sense, including all of the program output, not only
@@ -42,8 +44,8 @@
the same syntax as @e printf() or @e vprintf() , i.e. they take the
format string as the first argument and respectively a variable number of
arguments or a variable argument list pointer. Here are all of them:
@b wxLogFatalError which is like @e wxLogError, but also
terminates the program with the exit code 3 (using @e abort() standard
function). Unlike for all the other logging functions, this function can't be
@@ -70,7 +72,7 @@
does anything at all in the debug mode (when the preprocessor symbol
__WXDEBUG__ is defined) and expands to nothing in release mode (otherwise).
@b Tip: under Windows, you must either run the program under debugger or
use a 3rd party program such as #DbgView
use a 3rd party program such as #DbgView
to actually see the debug output.
@b wxLogTrace as @b wxLogDebug only does something in debug
build. The reason for making it a separate function from it is that usually
@@ -78,15 +80,15 @@
from other debug messages which would be flooded in them. Moreover, the second
version of this function takes a trace mask as the first argument which allows
to further restrict the amount of messages generated.
The usage of these functions should be fairly straightforward, however it may
be asked why not use the other logging facilities, such as C standard stdio
functions or C++ streams. The short answer is that they're all very good
generic mechanisms, but are not really adapted for wxWidgets, while the log
classes are. Some of advantages in using wxWidgets log functions are:
@b Portability It is a common practice to use @e printf()
statements or cout/cerr C++ streams for writing out some (debug or otherwise)
information.
@@ -94,16 +96,16 @@
under Windows where the stdout of GUI programs is not assigned to anything.
Thus, you might view @e wxLogMessage() as a simple substitute for @e printf().
You can also redirect the @e wxLogXXX calls to @e cout by just writing:
@code
wxLog *logger=new wxLogStream();
wxLog::SetActiveTarget(logger);
@endcode
Finally, there is also a possibility to redirect the output sent to @e cout
to a #wxTextCtrl by using the
Finally, there is also a possibility to redirect the output sent to @e cout
to a #wxTextCtrl by using the
#wxStreamToTextRedirector class.
@b Flexibility The output of wxLog functions can be redirected or
suppressed entirely based on their importance, which is either impossible or
@@ -120,8 +122,8 @@
situation, the exact error code (and the corresponding error message) will be
given to the user together with "high level" message about data file writing
error.
After having enumerated all the functions which are normally used to log the
messages, and why would you want to use them we now describe how all this
works.
@@ -142,8 +144,8 @@
There are some predefined classes deriving from wxLog and which might be
helpful to see how you can create a new log target class and, of course, may
also be used without any change. There are:
@b wxLogStderr This class logs messages to a @e FILE *, using
stderr by default as its name suggests.
@b wxLogStream This class has the same functionality as wxLogStderr,
@@ -155,32 +157,34 @@
collects all messages generated by the application and also passes them to the
previous active log target. The log window frame has a menu allowing user to
clear the log, close it completely or save all messages to file.
@b wxLogBuffer This target collects all the logged messages in an
internal buffer allowing to show them later to the user all at once.
@b wxLogNull The last log class is quite particular: it doesn't do
anything. The objects of this class may be instantiated to (temporarily)
suppress output of @e wxLogXXX() functions. As an example, trying to open a
non-existing file will usually provoke an error message, but if for some
reasons it is unwanted, just use this construction:
@code
wxFile file;
// wxFile.Open() normally complains if file can't be opened, we don't want it
{
wxLogNull logNo;
if ( !file.Open("bar") )
... process error ourselves ...
} // ~wxLogNull called, old log sink restored
wxLogMessage("..."); // ok
@endcode
The log targets can also be combined: for example you may wish to redirect the
messages somewhere else (for example, to a log file) but also process them as
normally. For this the #wxLogChain, #wxLogInterposer and
#wxLogInterposerTemp can be used.
*/

82
docs/doxygen/overviews/mbconvclasses.h
View File

@@ -7,12 +7,12 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page mbconvclasses_overview wxMBConv classes overview
Classes: #wxMBConv, wxMBConvLibc,
#wxMBConvUTF7, #wxMBConvUTF8,
#wxCSConv,
Classes: #wxMBConv, wxMBConvLibc,
#wxMBConvUTF7, #wxMBConvUTF8,
#wxCSConv,
#wxMBConvUTF16, #wxMBConvUTF32
The wxMBConv classes in wxWidgets enable an Unicode-aware application to
easily convert between Unicode and the variety of 8-bit encoding systems still
@@ -24,10 +24,10 @@
#wxCSConv
@ref convertingstrings_overview
@ref convertingbuffers_overview
@section needforconversion Background: The need for conversion
As programs are becoming more and more globalized, and users exchange documents
across country boundaries as never before, applications increasingly need to
take into account all the different character sets in use around the world. It
@@ -43,9 +43,9 @@
Unicode data from one Unicode-aware system to another may need encoding to an
8-bit multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to
pass unhindered through any traditional transport channels.
@section conversionandwxstring Background: The wxString class
If you have compiled wxWidgets in Unicode mode, the wxChar type will become
identical to wchar_t rather than char, and a wxString stores wxChars. Hence,
all wxString manipulation in your application will then operate on Unicode
@@ -56,18 +56,18 @@
data over a network, or processing a text file for some other application. You
need a way to quickly convert your easily-handled Unicode data to and from a
traditional 8-bit encoding. And this is what the wxMBConv classes do.
@section wxmbconvclasses wxMBConv classes
The base class for all these conversions is the wxMBConv class (which itself
implements standard libc locale conversion). Derived classes include
wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which
implement different kinds of conversions. You can also derive your own class
for your own custom encoding and use it, should you need it. All you need to do
is override the MB2WC and WC2MB methods.
@section wxmbconvobjects wxMBConv objects
Several of the wxWidgets-provided wxMBConv classes have predefined instances
(wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use
these predefined objects directly, or you can instantiate your own objects.
@@ -75,9 +75,9 @@
interface is supposed to use, in the case that the user interface is not
Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or
wxConvLocal, depending on which works best on the current platform.
@section wxcsconvclass wxCSConv
The wxCSConv class is special because when it is instantiated, you can tell it
which character set it should use, which makes it meaningful to keep many
instances of them around, each with a different character set (or you can
@@ -85,94 +85,94 @@
The predefined wxCSConv instance, wxConvLocal, is preset to use the
default user character set, but you should rarely need to use it directly,
it is better to go through wxConvCurrent.
@section convertingstrings Converting strings
Once you have chosen which object you want to use to convert your text,
here is how you would use them with wxString. These examples all assume
that you are using a Unicode build of wxWidgets, although they will still
compile in a non-Unicode build (they just won't convert anything).
Example 1: Constructing a wxString from input in current encoding.
@code
wxString str(input_data, *wxConvCurrent);
@endcode
Example 2: Input in UTF-8 encoding.
@code
wxString str(input_data, wxConvUTF8);
@endcode
Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly.
@code
wxString str(input_data, wxCSConv(wxT("koi8-r")));
@endcode
Example 4: Printing a wxString to stdout in UTF-8 encoding.
@code
puts(str.mb_str(wxConvUTF8));
@endcode
Example 5: Printing a wxString to stdout in custom encoding.
Using preconstructed wxCSConv instance.
@code
wxCSConv cust(user_encoding);
printf("Data: %s\n", (const char*) str.mb_str(cust));
@endcode
Note: Since mb_str() returns a temporary wxCharBuffer to hold the result
of the conversion, you need to explicitly cast it to const char* if you use
it in a vararg context (like with printf).
@section convertingbuffers Converting buffers
If you have specialized needs, or just don't want to use wxString, you
can also use the conversion methods of the conversion objects directly.
This can even be useful if you need to do conversion in a non-Unicode
build of wxWidgets; converting a string from UTF-8 to the current
encoding should be possible by doing this:
@code
wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);
@endcode
Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode
string. The wxString constructor then converts it back to an 8-bit character
set using the passed conversion object, *wxConvCurrent. (In a Unicode build
of wxWidgets, the constructor ignores the passed conversion object and
retains the Unicode data.)
This could also be done by first making a wxString of the original data:
@code
wxString input_str(input_data);
wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent);
@endcode
To print a wxChar buffer to a non-Unicode stdout:
@code
printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data));
@endcode
If you need to do more complex processing on the converted data, you
may want to store the temporary buffer in a local variable:
@code
const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data);
const char *tmp_str = (const char*) tmp_buf;
printf("Data: %s\n", tmp_str);
process_data(tmp_str);
@endcode
If a conversion had taken place in cWX2MB (i.e. in a Unicode build),
the buffer will be deallocated as soon as tmp_buf goes out of scope.
(The macro wxWX2MBbuf reflects the correct return value of cWX2MB
(either char* or wxCharBuffer), except for the const.)
*/

60
docs/doxygen/overviews/nonenglish.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page nonenglish_overview Writing non-English applications
This article describes how to write applications that communicate with
the user in a language other than English. Unfortunately many languages use
different charsets under Unix and Windows (and other platforms, to make
@@ -17,9 +17,9 @@
many characters that it is impossible to use the same texts under all
platforms.
The wxWidgets library provides a mechanism that helps you avoid distributing many
identical, only differently encoded, packages with your application
identical, only differently encoded, packages with your application
(e.g. help files and menu items in iso8859-13 and windows-1257). Thanks
to this mechanism you can, for example, distribute only iso8859-13 data
to this mechanism you can, for example, distribute only iso8859-13 data
and it will be handled transparently under all systems.
Please read #Internationalization which
describes the locales concept.
@@ -27,11 +27,11 @@
used, any encodings are meant and any encodings may be substituted there.
@b Locales
The best way to ensure correctly displayed texts in a GUI across platforms
is to use locales. Write your in-code messages in English or without
diacritics and put real messages into the message catalog (see
is to use locales. Write your in-code messages in English or without
diacritics and put real messages into the message catalog (see
#Internationalization).
A standard .po file begins with a header like this:
@code
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR Free Software Foundation, Inc.
@@ -48,18 +48,18 @@
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"
@endcode
Note this particular line:
@code
"Content-Type: text/plain; charset=CHARSET\n"
@endcode
It specifies the charset used by the catalog. All strings in the catalog
are encoded using this charset.
You have to fill in proper charset information. Your .po file may look like this
after doing so:
after doing so:
@code
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR Free Software Foundation, Inc.
@@ -76,7 +76,7 @@
"Content-Type: text/plain; charset=iso8859-2\n"
"Content-Transfer-Encoding: 8bit\n"
@endcode
(Make sure that the header is @b not marked as @e fuzzy.)
wxWidgets is able to use this catalog under any supported platform
(although iso8859-2 is a Unix encoding and is normally not understood by
@@ -97,25 +97,25 @@
in the source code to English and putting the original strings into message
catalog, you may configure wxWidgets to use non-English msgids and translate to
English using message catalogs:
If you use the program @c xgettext to extract the strings from
the source code, specify the option @c --from-code=source code charset.
Specify the source code language and charset as arguments to
wxLocale::AddCatalog. For example:
@code
locale.AddCatalog(_T("myapp"),
wxLANGUAGE_GERMAN, _T("iso-8859-1"));
@endcode
@b Font mapping
You can use @ref mbconvclasses_overview and
You can use @ref mbconvclasses_overview and
#wxFontMapper to display text:
@code
if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename))
{
@@ -132,7 +132,7 @@
}
...display text...
@endcode
@b Converting data
You may want to store all program data (created documents etc.) in
the same encoding, let's say @c utf-8. You can use
@@ -143,21 +143,21 @@
If you're using #wxHtmlHelpController there is
no problem at all. You only need to make sure that all the HTML files contain
the META tag, e.g.
@code
meta http-equiv="Content-Type" content="text/html; charset=iso8859-2"
@endcode
and that the hhp project file contains one additional line in the @c OPTIONS
section:
@code
Charset=iso8859-2
@endcode
This additional entry tells the HTML help controller what encoding is used
in contents and index tables.
*/

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

@@ -7,18 +7,18 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page printing_overview Printing overview
Classes: #wxPrintout,
#wxPrinter,
#wxPrintPreview,
#wxPrinterDC,
#wxPostScriptDC,
#wxPrintDialog,
#wxPrintData,
#wxPrintDialogData,
#wxPageSetupDialog,
Classes: #wxPrintout,
#wxPrinter,
#wxPrintPreview,
#wxPrinterDC,
#wxPostScriptDC,
#wxPrintDialog,
#wxPrintData,
#wxPrintDialogData,
#wxPageSetupDialog,
#wxPageSetupDialogData
The printing framework relies on the application to provide classes whose member
functions can respond to particular requests, such as 'print this page' or 'does
@@ -42,10 +42,10 @@
@ref topic16_overview
@ref topic17_overview
@ref topic18_overview
@section topic9 #wxPrintout
A document's printing ability is represented in an application by a derived
wxPrintout class. This class prints a page on request, and can be passed to the
Print function of a wxPrinter object to actually print the document, or can be
@@ -55,7 +55,7 @@
Notice the use of MyPrintout for both printing and previewing. All the preview
user interface functionality is taken care of by wxWidgets. For more details on how
MyPrintout is defined, please look at the printout sample code.
@code
case WXPRINT_PRINT:
{
@@ -75,7 +75,7 @@
break;
}
@endcode
Class #wxPrintout assembles the printed page and (using
your subclass's overrides) writes requested pages to a #wxDC that
is passed to it. This wxDC could be a #wxMemoryDC (for
@@ -96,24 +96,24 @@
can easily map your image to the printout withough getting into the details of
screen and printer PPI and scaling. See the printing sample for examples of how
these routines are used.
@section topic10 #wxPrinter
Class wxPrinter encapsulates the platform-dependent print function with a common
interface. In most cases, you will not need to derive a class from wxPrinter;
simply create a wxPrinter object in your Print function as in the example above.
@section topic11 #wxPrintPreview
Class wxPrintPreview manages the print preview process. Among other things, it
constructs the wxDCs that get passed to your wxPrintout subclass for printing
and manages the display of multiple pages, a zoomable preview image, and so
forth. In most cases you will use this class as-is, but you can create your own
subclass, for example, to change the layout or contents of the preview window.
@section topic12 #wxPrinterDC
Class wxPrinterDC is the wxDC that represents the actual printed page under MSW
and Mac. During printing, an object of this class will be passed to your derived
wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the
@@ -133,9 +133,9 @@
wxPrinterDC-specific function
wxPrinterDC::GetPaperRect returns the paper
rectangle of the given wxPrinterDC.
@section topic13 #wxPostScriptDC
Class wxPostScriptDC is the wxDC that represents the actual printed page under
GTK and other PostScript printing. During printing, an object of this class will
be passed to your derived wxPrintout object to draw upon. The size of the
@@ -144,17 +144,17 @@
Unlike a wxPrinterDC, there is no distinction between the page rectangle and the
paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the
entire sheet of paper.
@section topic14 #wxPrintDialog
Class wxPrintDialog puts up the standard print dialog, which allows you to
select the page range for printing (as well as many other print settings, which
may vary from platform to platform). You provide an object of type
#wxPrintDialogData to the wxPrintDialog at
construction, which is used to populate the dialog.
@section topic15 #wxPrintData
Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to
initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data
member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially,
@@ -162,17 +162,17 @@
configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You
might wish to create a global instance of this object to provide call-to-call
persistence to your application's print settings.
@section topic16 #wxPrintDialogData
Class wxPrintDialogData contains the settings entered by the user in the print
dialog. It contains such things as page range, number of copies, and so forth.
In most cases, you won't need to access this information; the framework takes
care of asking your wxPrintout derived object for the pages requested by the
user.
@section topic17 #wxPageSetupDialog
Class wxPageSetupDialog puts up the standard page setup dialog, which allows you
to specify the orientation, paper size, and related settings. You provide it
with a wxPageSetupDialogData object at intialization, which is used to populate
@@ -183,9 +183,9 @@
wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a
wxPageSetupDialogData object in its constructor) to provide this capability; see
the printing sample for an example.
@section topic18 #wxPageSetupDialogData
Class wxPageSetupDialogData contains settings affecting the page size (paper
size), orientation, margins, and so forth. Note that not all platforms populate
all fields; for example, the MSW page setup dialog lets you set the page margins
@@ -198,7 +198,7 @@
queries these data structures to get information like the printed page range
(from the wxPrintDialogData) or the paper size and/or page orientation (from the
wxPageSetupDialogData).
*/

72
docs/doxygen/overviews/python.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page python_overview wxPython overview
This topic was written by Robin Dunn, author of the wxPython wrapper.
@ref pwhat_overview
@ref pwhy_overview
@@ -17,10 +17,10 @@
@ref pusing_overview
@ref pclasses_overview
@ref phelp_overview
@section wxpwhat What is wxPython?
wxPython is a blending of the wxWidgets GUI classes and the
#Python programming language.
@b Python
@@ -53,9 +53,9 @@
toolkit (wxGTK) on most Unix/X-windows platforms. See the wxPython
website #http://wxPython.org/ for
details about getting wxPython working for you.
@section wxpwhy Why use wxPython?
So why would you want to use wxPython over just C++ and wxWidgets?
Personally I prefer using Python for everything. I only use C++ when I
absolutely have to eke more performance out of an algorithm, and even
@@ -68,9 +68,9 @@
application in a few hours with Python that would normally take a few
days or longer with C++. Converting a wxPython app to a C++/wxWidgets app
should be a straight forward task.
@section wxpother Other Python GUIs
There are other GUI solutions out there for Python.
@b Tkinter
Tkinter is the de facto standard GUI for Python. It is available
@@ -107,9 +107,9 @@
wrappers around some C or C++ toolkit or another, and most are not
cross-platform compatible. See @ref Graphics_overview
for a listing of a few of them.
@section wxpusing Using wxPython
@b First things first...
I'm not going to try and teach the Python language here. You can do
that at the http://www.python.org/doc/tut/tut.html.
@@ -119,14 +119,14 @@
program in the @c wxPython/demo directory, named @c DialogUnits.py. If your
Python and wxPython are properly installed, you should be able to run
it by issuing this command:
@b @c python DialogUnits.py
@code
001: ## import all of the wxPython GUI package
002: from wxPython.wx import *
@@ -203,12 +203,12 @@
073: app.MainLoop() # Tell it to start processing events
074:
@endcode
@b Things to notice
At line 2 the wxPython classes, constants, and etc. are imported
into the current module's namespace. If you prefer to reduce
namespace pollution you can use "@c from wxPython import wx" and
@@ -255,17 +255,17 @@
ignore it for now.) The call to @c MainLoop at line 73 starts the event
loop which continues until the application terminates or all the top
level windows are closed.
@section wxpclasses wxWidgets classes implemented in wxPython
The following classes are supported in wxPython. Most provide nearly
full implementations of the public interfaces specified in the C++
documentation, others are less so. They will all be brought as close
as possible to the C++ spec over time.
#wxAcceleratorEntry
#wxAcceleratorTable
#wxActivateEvent
@@ -447,11 +447,11 @@
#wxWindowDC
#wxWindow
#wxZipFSHandler
@section wxphelp Where to go for help
Since wxPython is a blending of multiple technologies, help comes from
multiple sources. See
#http://wxpython.org/ for details on
@@ -461,7 +461,7 @@
#http://lists.wxwindows.org/mailman/listinfo/wxpython-users
Or you can send mail directly to the list using this address:
wxpython-users@lists.wxwindows.org
*/

10
docs/doxygen/overviews/referencenotes.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page referencenotes_overview Notes on using the reference
In the descriptions of the wxWidgets classes and their member
functions, note that descriptions of inherited member functions are not
duplicated in derived classes unless their behaviour is different. So in
@@ -26,7 +26,7 @@
used by wxWidgets.
The member functions are given in alphabetical order except for
constructors and destructors which appear first.
*/

3312
docs/doxygen/overviews/resyn.h
View File

File diff suppressed because it is too large Load Diff

192
docs/doxygen/overviews/richtextctrl.h
View File

@@ -7,25 +7,25 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page richtextctrl_overview wxRichTextCtrl overview
@b Major classes: #wxRichTextCtrl, #wxRichTextBuffer, #wxRichTextEvent
@b Helper classes: #wxTextAttr, #wxRichTextRange
@b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler,
@b File handler classes: #wxRichTextFileHandler, #wxRichTextHTMLHandler,
#wxRichTextXMLHandler
@b Style classes: #wxRichTextCharacterStyleDefinition,
#wxRichTextParagraphStyleDefinition,
#wxRichTextListStyleDefinition,
@b Style classes: #wxRichTextCharacterStyleDefinition,
#wxRichTextParagraphStyleDefinition,
#wxRichTextListStyleDefinition,
#wxRichTextStyleSheet
@b Additional controls: #wxRichTextStyleComboCtrl,
#wxRichTextStyleListBox,
@b Additional controls: #wxRichTextStyleComboCtrl,
#wxRichTextStyleListBox,
#wxRichTextStyleListCtrl
@b Printing classes: #wxRichTextPrinting,
#wxRichTextPrintout,
@b Printing classes: #wxRichTextPrinting,
#wxRichTextPrintout,
#wxRichTextHeaderFooterData
@b Dialog classes: #wxRichTextStyleOrganiserDialog,
#wxRichTextFormattingDialog,
@b Dialog classes: #wxRichTextStyleOrganiserDialog,
#wxRichTextFormattingDialog,
#wxSymbolPickerDialog
wxRichTextCtrl provides a generic implementation of a rich text editor that can handle different character
styles, paragraph formatting, and images. It's aimed at editing 'natural' language text - if you need an editor
@@ -58,62 +58,62 @@
former case.
A good way to understand wxRichTextCtrl's capabilities is to compile and run the
sample, @c samples/richtext, and browse the code. The following screenshot shows the sample in action:
@b Example
The following code is taken from the sample, and adds text and styles to a rich text control programmatically.
@code
wxRichTextCtrl* richTextCtrl = new wxRichTextCtrl(splitter, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(200, 200), wxVSCROLL|wxHSCROLL|wxBORDER_NONE|wxWANTS_CHARS);
wxFont textFont = wxFont(12, wxROMAN, wxNORMAL, wxNORMAL);
wxFont boldFont = wxFont(12, wxROMAN, wxNORMAL, wxBOLD);
wxFont italicFont = wxFont(12, wxROMAN, wxITALIC, wxNORMAL);
wxFont font(12, wxROMAN, wxNORMAL, wxNORMAL);
m_richTextCtrl-SetFont(font);
wxRichTextCtrl& r = richTextCtrl;
r.BeginSuppressUndo();
r.BeginParagraphSpacing(0, 20);
r.BeginAlignment(wxTEXT_ALIGNMENT_CENTRE);
r.BeginBold();
r.BeginFontSize(14);
r.WriteText(wxT("Welcome to wxRichTextCtrl, a wxWidgets control for editing and presenting styled text and images"));
r.EndFontSize();
r.Newline();
r.BeginItalic();
r.WriteText(wxT("by Julian Smart"));
r.EndItalic();
r.EndBold();
r.Newline();
r.WriteImage(wxBitmap(zebra_xpm));
r.EndAlignment();
r.Newline();
r.Newline();
r.WriteText(wxT("What can you do with this thing? "));
r.WriteImage(wxBitmap(smiley_xpm));
r.WriteText(wxT(" Well, you can change text "));
r.BeginTextColour(wxColour(255, 0, 0));
r.WriteText(wxT("colour, like this red bit."));
r.EndTextColour();
r.BeginTextColour(wxColour(0, 0, 255));
r.WriteText(wxT(" And this blue bit."));
r.EndTextColour();
r.WriteText(wxT(" Naturally you can make things "));
r.BeginBold();
r.WriteText(wxT("bold "));
@@ -124,57 +124,57 @@
r.BeginUnderline();
r.WriteText(wxT("or underlined."));
r.EndUnderline();
r.BeginFontSize(14);
r.WriteText(wxT(" Different font sizes on the same line is allowed, too."));
r.EndFontSize();
r.WriteText(wxT(" Next we'll show an indented paragraph."));
r.BeginLeftIndent(60);
r.Newline();
r.WriteText(wxT("Indented paragraph."));
r.EndLeftIndent();
r.Newline();
r.WriteText(wxT("Next, we'll show a first-line indent, achieved using BeginLeftIndent(100, -40)."));
r.BeginLeftIndent(100, -40);
r.Newline();
r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter."));
r.EndLeftIndent();
r.Newline();
r.WriteText(wxT("Numbered bullets are possible, again using subindents:"));
r.BeginNumberedBullet(1, 100, 60);
r.Newline();
r.WriteText(wxT("This is my first item. Note that wxRichTextCtrl doesn't automatically do numbering, but this will be added later."));
r.EndNumberedBullet();
r.BeginNumberedBullet(2, 100, 60);
r.Newline();
r.WriteText(wxT("This is my second item."));
r.EndNumberedBullet();
r.Newline();
r.WriteText(wxT("The following paragraph is right-indented:"));
r.BeginRightIndent(200);
r.Newline();
r.WriteText(wxT("It was in January, the most down-trodden month of an Edinburgh winter. An attractive woman came into the cafe, which is nothing remarkable."));
r.EndRightIndent();
r.Newline();
wxArrayInt tabs;
tabs.Add(400);
tabs.Add(600);
@@ -184,42 +184,42 @@
attr.SetFlags(wxTEXT_ATTR_TABS);
attr.SetTabs(tabs);
r.SetDefaultStyle(attr);
r.WriteText(wxT("This line contains tabs:\tFirst tab\tSecond tab\tThird tab"));
r.Newline();
r.WriteText(wxT("Other notable features of wxRichTextCtrl include:"));
r.BeginSymbolBullet(wxT('*'), 100, 60);
r.Newline();
r.WriteText(wxT("Compatibility with wxTextCtrl API"));
r.EndSymbolBullet();
r.WriteText(wxT("Note: this sample content was generated programmatically from within the MyFrame constructor in the demo. The images were loaded from inline XPMs. Enjoy wxRichTextCtrl!"));
r.EndSuppressUndo();
@endcode
@ref topic19_overview
@ref richtextctrldialogs_overview
@ref topic22_overview
@ref topic23_overview
@section topic19 Programming with wxRichTextCtrl
@section topic20 Starting to use wxRichTextCtrl
You need to include @c wx/richtext/richtextctrl.h in your source, and link
with the appropriate wxWidgets library with @c richtext suffix. Put the rich text
library first in your link line to avoid unresolved symbols.
Then you can create a wxRichTextCtrl, with the wxWANT_CHARS style if you want tabs to
be processed by the control rather than being used for navigation between controls.
@section topic21 wxRichTextCtrl and styles
Styling attributes are represented by #wxTextAttr.
When setting a style, the flags of the attribute object determine which
attributes are applied. When querying a style, the passed flags are ignored
@@ -229,8 +229,8 @@
the content may be responsible for contributing different attributes to the final
style you see on the screen.
There are four main notions of style within a control:
@b Basic style: the fundamental style of a control, onto which any other
styles are layered. It provides default attributes, and changing the basic style
may immediately change the look of the content depending on what other styles
@@ -244,20 +244,20 @@
to wxRichTextCtrl::SetStyleEx.
@b Character style: characters within each paragraph can have attributes.
A single character, or a run of characters, can have a particular set of attributes.
The character style can be with wxRichTextCtrl::SetStyle or
The character style can be with wxRichTextCtrl::SetStyle or
wxRichTextCtrl::SetStyleEx.
@b Default style: this is the 'current' style that determines the
style of content that is subsequently typed, pasted or programmatically inserted.
The default style is set with wxRichTextCtrl::SetDefaultStyle.
What you see on the screen is the dynamically @e combined style, found by merging
the first three of the above style types (the fourth is only a guide for future content
insertion and therefore does not affect the currently displayed content).
To make all this more concrete, here are examples of where you might set these different
styles:
You might set the @b basic style to have a Times Roman font in 12 point,
left-aligned, with two millimetres of spacing after each paragraph.
You might set the @b paragraph style (for one particular paragraph) to
@@ -265,14 +265,14 @@
You might set the @b character style of one particular word to bold.
You might set the @b default style to be underlined, for subsequent
inserted text.
Naturally you can do any of these things either using your own UI, or programmatically.
The basic wxTextCtrl doesn't make the same distinctions as wxRichTextCtrl regarding
attribute storage. So we need finer control when setting and retrieving
attributes. wxRichTextCtrl::SetStyleEx takes a @e flags parameter:
wxRICHTEXT_SETSTYLE_OPTIMIZE specifies that the style should be changed only if
the combined attributes are different from the attributes for the current object. This is important when
applying styling that has been edited by the user, because he has just edited the @e combined (visible)
@@ -283,8 +283,8 @@
wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY specifies that only content objects (text or images) within the given range
should take on the attributes.
wxRICHTEXT_SETSTYLE_WITH_UNDO specifies that the operation should be undoable.
It's great to be able to change arbitrary attributes in a wxRichTextCtrl, but
it can be unwieldy for the user or programmer to set attributes separately. Word processors have collections
of styles that you can tailor or use as-is, and this means that you can set a heading with one click
@@ -301,9 +301,9 @@
It relies on the fact that when you apply a named style, the style definition name is recorded in the
content. So ApplyStyleSheet works by finding the paragraph attributes with style names and re-applying the definition's
attributes to the paragraph. Currently, this works with paragraph and list style definitions only.
@section wxrichtextctrldialogs wxRichTextCtrl dialogs
wxRichTextCtrl comes with standard dialogs to make it easier to implement
text editing functionality.
#wxRichTextFormattingDialog can be used
@@ -323,9 +323,9 @@
#wxSymbolPickerDialog lets the user insert a symbol from
a specified font. It has no wxRichTextCtrl dependencies besides being included in
the rich text library.
@section topic22 How wxRichTextCtrl is implemented
Data representation is handled by wxRichTextBuffer, and a wxRichTextCtrl
always has one such buffer.
The content is represented by a hierarchy of objects, all derived from
@@ -357,25 +357,25 @@
to several objects with the same style where just one would do. So
a Defragment function is called when updating the control's display, to ensure that
the minimum number of objects is used.
@section topic23 wxRichTextCtrl roadmap
@b Bugs
This is an incomplete list of bugs.
Moving the caret up at the beginning of a line sometimes incorrectly positions the
caret.
As the selection is expanded, the text jumps slightly due to kerning differences between
drawing a single text string versus drawing several fragments separately. This could
be improved by using wxDC::GetPartialTextExtents to calculate exactly where the separate fragments
should be drawn. Note that this problem also applies to separation of text fragments due to difference in their attributes.
@b Features
This is a list of some of the features that have yet to be implemented. Help with them will be appreciated.
RTF input and output
Conversion from HTML
Open Office input and output
@@ -387,12 +387,12 @@
Borders
Text frames
Justified text, in print/preview at least
There are also things that could be done to take advantage of the underlying text capabilities of the platform;
higher-level text formatting APIs are available on some platforms, such as Mac OS X, and some of translation from
high level to low level wxDC API is unnecessary. However this would require additions to the wxWidgets API.
*/

10
docs/doxygen/overviews/roughguide.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page roughguide_overview Writing a wxWidgets application: a rough guide
To set a wxWidgets application going, you will need to derive a #wxApp class and
override wxApp::OnInit.
An application must have a top-level #wxFrame or #wxDialog window.
@@ -48,7 +48,7 @@
and you may find it handy to maintain and search a list of paths using #wxPathList.
There's a #miscellany of operating system and other functions.
See also @ref classesbycat_overview for a list of classes.
*/

40
docs/doxygen/overviews/runtimeclass.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page runtimeclass_overview Runtime class information (aka RTTI) overview
Classes: #wxObject, #wxClassInfo.
One of the failings of C++ used to be that no run-time information was provided
about a class and its position in the inheritance hierarchy.
@@ -54,58 +54,58 @@
can simply call wxClassInfo::CreateObject.
#wxClassInfo
#Example
@section wxclassinfooverview wxClassInfo
#Runtime class information (aka RTTI) overview
Class: #wxClassInfo
This class stores meta-information about classes. An application
may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS
to record run-time information about a class, including:
its position in the inheritance hierarchy;
the base class name(s) (up to two base classes are permitted);
a string representation of the class name;
a function that can be called to construct an instance of this class.
The DECLARE_... macros declare a static wxClassInfo variable in a class, which is initialized
by macros of the form IMPLEMENT_... in the implementation C++ file. Classes whose instances may be
constructed dynamically are given a global constructor function which returns a new object.
You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame).
You can get the wxClassInfo for an object using wxObject::GetClassInfo.
See also #wxObject and #wxCreateDynamicObject.
@section runtimeclassinformationexample Example
In a header file frame.h:
@code
class wxFrame : public wxWindow
{
DECLARE_DYNAMIC_CLASS(wxFrame)
private:
wxString m_title;
public:
...
};
@endcode
In a C++ file frame.cpp:
@code
IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
wxFrame::wxFrame()
{
...
}
@endcode
*/

608
docs/doxygen/overviews/samples.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page samples_overview wxWidgets samples
Probably the best way to learn wxWidgets is by reading the source of some 50+
samples provided with it. Many aspects of wxWidgets programming can be learnt
from them, but sometimes it is not simple to just choose the right sample to
@@ -27,60 +27,60 @@
generic controls, such as buttons, listboxes, checkboxes, comboboxes etc.
Other, more complicated controls, have their own samples. In this category you
may find the following samples showing the corresponding controls:
#wxCalendarCtrl
Calendar a.k.a. date picker control
#wxListCtrl
List view control
#wxTreeCtrl
Tree view control
#wxGrid
Grid control
Finally, it might be helpful to do a search in the entire sample directory if
you can't find the sample showing the control you are interested in by
name. Most classes contained in wxWidgets occur in at least one of the samples.
@ref sampleminimal_overview
@ref sampleanimate_overview
@ref sampleartprovider_overview
@@ -115,49 +115,49 @@
@ref sampletreectrl_overview
@ref samplewidgets_overview
@ref samplewizard_overview
@section sampleminimal Minimal sample
The minimal sample is what most people will know under the term Hello World,
i.e. a minimal program that doesn't demonstrate anything apart from what is
needed to write a program that will display a "hello" dialog. This is usually
a good starting point for learning how to use wxWidgets.
@section sampleanimate Animate sample
The @c animate sample shows how you can use #wxAnimationCtrl
control and shows concept of a platform-dependent animation encapsulated
in #wxAnimation.
@section sampleartprovider Art provider sample
The @c artprov sample shows how you can customize the look of standard
wxWidgets dialogs by replacing default bitmaps/icons with your own versions.
It also shows how you can use wxArtProvider to
get stock bitmaps for use in your application.
@section samplecalendar Calendar sample
This font shows the @ref calendarctrl_overview in action. It
shows how to configure the control (see the different options in the calendar
menu) and also how to process the notifications from it.
@section sampleconfig Config sample
This sample demonstrates the #wxConfig classes in a platform
independent way, i.e. it uses text based files to store a given configuration under
Unix and uses the Registry under Windows.
See @ref config_overview for the descriptions of all
features of this class.
@section samplecontrols Controls sample
The controls sample is the main test program for most simple controls used in
wxWidgets. The sample tests their basic functionality, events, placement,
modification in terms of colour and font as well as the possibility to change
@@ -168,181 +168,181 @@
notebook pages, advancing pages programmatically and vetoing a page change
by intercepting the #wxNotebookEvent.
The various controls tested are listed here:
#wxButton
Push button control, displaying text
#wxBitmapButton
Push button control, displaying a bitmap
#wxCheckBox
Checkbox control
#wxChoice
Choice control (a combobox without the editable area)
#wxComboBox
A choice with an editable area
#wxGauge
A control to represent a varying quantity, such as time remaining
#wxStaticBox
A static, or group box for visually grouping related controls
#wxListBox
A list of strings for single or multiple selection
wxSpinCtrl
A spin ctrl with a text field and a 'up-down' control
#wxSpinButton
A spin or 'up-down' control
#wxStaticText
One or more lines of non-editable text
#wxStaticBitmap
A control to display a bitmap
#wxRadioBox
A group of radio buttons
#wxRadioButton
A round button to be used with others in a mutually exclusive way
#wxSlider
A slider that can be dragged by the user
@section sampledebugrpt DebugRpt sample
This sample shows how to use #wxDebugReport class to
generate a debug report in case of a program crash or otherwise. On start up,
it proposes to either crash itself (by dereferencing a @NULL pointer) or
@@ -353,16 +353,16 @@
For the report processing part of the sample to work you should make available
a Web server accepting form uploads, otherwise
#wxDebugReportUpload will report an error.
@section sampledialogs Dialogs sample
This sample shows how to use the common dialogs available from wxWidgets. These
dialogs are described in detail in the @ref commondialogs_overview.
@section sampledialup Dialup sample
This sample shows the #wxDialUpManager
class. In the status bar, it displays the information gathered through its
interface: in particular, the current connection status (online or offline) and
@@ -372,10 +372,10 @@
Using the menu entries, you may also dial or hang up the line if you have a
modem attached and (this only makes sense for Windows) list the available
connections.
@section samplednd DnD sample
This sample shows both clipboard and drag and drop in action. It is quite non
trivial and may be safely used as a basis for implementing the clipboard and
drag and drop operations in a real-life program.
@@ -406,19 +406,19 @@
programs as well - try Write/Wordpad, for example).
Take a look at DnDShapeDataObject class to see how you may use
#wxDataObject to achieve this.
@section sampleevent Event sample
The event sample demonstrates various features of the wxWidgets events. It
shows using dynamic events and connecting/disconnecting the event handlers
during run time and also using
#PushEventHandler() and
#PopEventHandler().
@section sampleexcept Except(ions) sample
This very simple sample shows how to use C++ exceptions in wxWidgets programs,
i.e. where to catch the exception which may be thrown by the program code. It
doesn't do anything very exciting by itself, you need to study its code to
@@ -426,10 +426,10 @@
You need to build the library with @c wxUSE_EXCEPTIONS being set to 1
and compile your code with C++ exceptions support to be able to build this
sample.
@section sampleexec Exec sample
The exec sample demonstrates the #wxExecute and
#wxShell functions. Both of them are used to execute the
external programs and the sample shows how to do this synchronously (waiting
@@ -438,24 +438,24 @@
synchronous and asynchronous cases and how to kill the processes with
wxProcess::Kill and test for their existence with
wxProcess::Exists.
@section samplefont Font sample
The font sample demonstrates #wxFont,
#wxFontEnumerator and
#wxFontMapper classes. It allows you to see the fonts
available (to wxWidgets) on the computer and shows all characters of the
chosen font as well.
@section samplegrid Grid sample
TODO.
@section samplehtml HTML samples
Eight HTML samples (you can find them in directory @c samples/html)
cover all features of the HTML sub-library.
@b Test demonstrates how to create #wxHtmlWindow
@@ -477,10 +477,10 @@
#wxHtmlHelpController in your application
while @e Helpview is a simple tool that only pops up the help window and
displays help books given at command line.
@section sampleimage Image sample
The image sample demonstrates use of the #wxImage class
and shows how to download images in a variety of formats, currently PNG, GIF,
TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows two rectangles, one
@@ -497,10 +497,10 @@
replaced with red using wxImage::Replace.
This sample also contains the code for testing the image rotation and resizing
and using raw bitmap access, see the corresponding menu commands.
@section sampleinternat Internat(ionalization) sample
The not very clearly named internat sample demonstrates the wxWidgets
internationalization (i18n for short from now on) features. To be more
precise, it only shows localization support, i.e. support for translating the
@@ -508,10 +508,10 @@
changing the other aspects of the programs behaviour.
More information about this sample can be found in the @c readme.txt file in
its directory. Please see also @ref internationalization_overview.
@section samplelayout Layout sample
The layout sample demonstrates the two different layout systems offered
by wxWidgets. When starting the program, you will see a frame with some
controls and some graphics. The controls will change their size whenever
@@ -524,43 +524,43 @@
a #wxBoxSizer in a simple dialog and the other one
showing how to use sizers in connection with a #wxNotebook
class. See also #wxSizer.
@section samplelistctrl Listctrl sample
This sample shows the #wxListCtrl control. Different modes
supported by the control (list, icons, small icons, report) may be chosen from
the menu.
The sample also provides some timings for adding/deleting/sorting a lot of
(several thousands) items into the control.
@section samplemediaplayer Mediaplayer sample
This sample demonstrates how to use all the features of
#wxMediaCtrl and play various types of sound, video,
and other files.
It replaces the old dynamic sample.
@section samplenotebook Notebook sample
This samples shows #wxBookCtrl family of controls.
Although initially it was written to demonstrate #wxNotebook
only, it can now be also used to see #wxListbook,
#wxChoicebook and #wxTreebook in action.
Test each of the controls, their orientation, images and pages using commands through menu.
@section samplerender Render sample
This sample shows how to replace the default wxWidgets
#renderer and also how to write a shared library
(DLL) implementing a renderer and load and unload it during the run-time.
@section samplescrollsub Scroll subwindow sample
This sample demonstrates use of the #wxScrolledWindow
class including placing subwindows into it and drawing simple graphics. It uses the
#SetTargetWindow method and thus the effect
@@ -569,10 +569,10 @@
in particular using the wxWindow::IsExposed method with
the aim to prevent unnecessary drawing in the window and thus reducing or removing
flicker on screen.
@section samplesockets Sockets sample
The sockets sample demonstrates how to use the communication facilities
provided by #wxSocket. There are two different
applications in this sample: a server, which is implemented using a
@@ -610,46 +610,46 @@
There is also a URL test which shows how to use
the #wxURL class to fetch data from a given URL.
The sockets sample is work in progress. Some things to do:
More tests for basic socket functionality.
More tests for protocol classes (wxProtocol and its descendants).
Tests for the recently added (and still in alpha stage) datagram sockets.
New samples which actually do something useful (suggestions accepted).
@section samplesound Sound sample
The @c sound sample shows how to use #wxSound for simple
audio output (e.g. notifications).
@section samplestatbar Statbar sample
This sample shows how to create and use wxStatusBar. Although most of the
samples have a statusbar, they usually only create a default one and only
do it once.
Here you can see how to recreate the statusbar (with possibly different number
of fields) and how to use it to show icons/bitmaps and/or put arbitrary
controls into it.
@section sampletaborder Tab order sample
This sample allows to test keyboard navigation (mostly done using the
This sample allows to test keyboard navigation (mostly done using the
@c TAB key, hence the sample name) between different controls.
It shows the use of
wxWindow::MoveBeforeInTabOrder() and
It shows the use of
wxWindow::MoveBeforeInTabOrder() and
#MoveAfterInTabOrder() methods to change
the default order of the windows in the navigation chain and of
the default order of the windows in the navigation chain and of
wxWindow::Navigate() for moving focus along this
chain.
@section sampletext Text sample
This sample demonstrates four features: firstly the use and many variants of
the #wxTextCtrl class (single line, multi line, read only,
password, ignoring TAB, ignoring ENTER).
@@ -665,10 +665,10 @@
best known from pasting text to the XTerm program.
Last not least: some of the text controls have tooltips and the sample also shows
how tooltips can be centrally disabled and their latency controlled.
@section samplethread Thread sample
This sample demonstrates use of threads in connection with GUI programs.
There are two fundamentally different ways to use threads in GUI programs and
either way has to take care of the fact that the GUI library itself usually
@@ -684,14 +684,14 @@
and #wxMutexGuiLeave functions, both of which are
used and tested in the sample as well.
See also @ref thread_overview and #wxThread.
@section sampletoolbar Toolbar sample
The toolbar sample shows the #wxToolBar class in action.
The following things are demonstrated:
Creating the toolbar using wxToolBar::AddTool
and wxToolBar::AddControl: see
MyApp::InitToolbar in the sample.
@@ -701,8 +701,8 @@
Using wxToolBar::DeleteTool and
wxToolBar::InsertTool to dynamically update the
toolbar.
Some buttons in the main toolbar are check buttons, i.e. they stay checked when
pressed. On the platforms which support it, the sample also adds a combobox
to the toolbar showing how you can use arbitrary controls and not only buttons
@@ -711,10 +711,10 @@
see the radio toolbar buttons in action: the first three buttons form a radio
group, i.e. checking any of them automatically unchecks the previously
checked one.
@section sampletreectrl Treectrl sample
This sample demonstrates using the #wxTreeCtrl class. Here
you may see how to process various notification messages sent by this control
and also when they occur (by looking at the messages in the text control in
@@ -722,24 +722,24 @@
Adding, inserting and deleting items and branches from the tree as well as
sorting (in default alphabetical order as well as in custom one) is
demonstrated here as well - try the corresponding menu entries.
@section samplewidgets Widgets sample
The widgets sample is the main presentation program for most simple and advanced
native controls and complex generic widgets provided by wxWidgets.
The sample tests their basic functionality, events, placement, modification
in terms of colour and font as well as the possibility to change
the controls programmatically, such as adding an item to a list box etc.
All widgets are categorized for easy browsing.
@section samplewizard Wizard sample
This sample shows the so-called wizard dialog (implemented using
#wxWizard and related classes). It shows almost all
features supported:
Using bitmaps with the wizard and changing them depending on the page
shown (notice that wxValidationPage in the sample has a different image from
the other ones)
@@ -754,7 +754,7 @@
but sometimes it depends on the user choices: wxCheckboxPage shows how to
dynamically decide which page to display next (see also
#wxWizardPage)
*/

116
docs/doxygen/overviews/scrolling.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page scrolling_overview Scrolling overview
Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar.
Scrollbars come in various guises in wxWidgets. All windows have the potential
to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window.
@@ -33,66 +33,66 @@
@b The scrollbar model
The function wxWindow::SetScrollbar gives a clue about
the way a scrollbar is modeled. This function takes the following arguments:
orientation
Which scrollbar: wxVERTICAL or wxHORIZONTAL.
position
The position of the scrollbar in scroll units.
visible
The size of the visible portion of the scrollbar, in scroll units.
range
The maximum position of the scrollbar.
refresh
Whether the scrollbar should be repainted.
@e orientation determines whether we're talking about
the built-in horizontal or vertical scrollbar.
@e position is simply the position of the 'thumb' (the bit you drag to scroll around).
@@ -110,12 +110,12 @@
Let's say you wish to display 50 lines of text, using the same font.
The window is sized so that you can only see 16 lines at a time.
You would use:
@code
SetScrollbar(wxVERTICAL, 0, 16, 50);
@endcode
Note that with the window at this size, the thumb position can never go
above 50 minus 16, or 34.
You can determine how many lines are currently visible by dividing the current view
@@ -125,7 +125,7 @@
scrollbar calculations and SetScrollbar
call into a function named AdjustScrollbars, which can be called initially and also
from your #wxSizeEvent handler function.
*/

184
docs/doxygen/overviews/sizer.h
View File

@@ -7,12 +7,12 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page sizer_overview Sizer overview
Classes: #wxSizer, #wxGridSizer,
#wxFlexGridSizer, #wxBoxSizer,
#wxStaticBoxSizer,
Classes: #wxSizer, #wxGridSizer,
#wxFlexGridSizer, #wxBoxSizer,
#wxStaticBoxSizer,
#CreateButtonSizer
Sizers, as represented by the wxSizer class and its descendants in
the wxWidgets class hierarchy, have become the method of choice to
@@ -32,10 +32,10 @@
@ref flexgridsizerprogramming_overview
@ref staticboxsizerprogramming_overview
#CreateButtonSizer
@section ideabehindsizers The idea behind sizers
The layout algorithm used by sizers in wxWidgets is closely related to layout
systems in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is
based upon the idea of individual subwindows reporting their minimal required
@@ -57,9 +57,9 @@
such as wrapping a static box around a dialog item (or another sizer). These sizers will
be discussed one by one in the text below. For more detailed information on how to use sizers
programmatically, please refer to the section @ref boxsizerprogramming_overview.
@section sizerscommonfeatures Common features
All sizers are containers, that is, they are used to lay out one dialog item (or several
dialog items), which they contain. Such items are sometimes referred to as the children
of the sizer. Independent of how the individual sizers lay out their children, all children
@@ -71,26 +71,26 @@
calculate their size (such as a checkbox) whereas others (such as a listbox)
don't have any natural width or height and thus require an explicit size. Some controls
can calculate their height, but not their width (e.g. a single line text control):
@b A border: The border is just empty space and is used to separate dialog items
in a dialog. This border can either be all around, or at any combination of sides
such as only above and below the control. The thickness of this border must be set
explicitly, typically 5 points. The following samples show dialogs with only one
dialog item (a button) and a border of 0, 5, and 10 pixels around the button:
@b An alignment: Often, a dialog item is given more space than its minimal size
plus its border. Depending on what flags are used for the respective dialog
item, the dialog item can be made to fill out the available space entirely, i.e.
@@ -98,9 +98,9 @@
the centre of the available space or to either side of the space. The following
sample shows a listbox and three buttons in a horizontal box sizer; one button
is centred, one is aligned at the top, one is aligned at the bottom:
@b A stretch factor: If a sizer contains more than one child and it is offered
more space than its children and their borders need, the question arises how to
distribute the surplus space among the children. For this purpose, a stretch
@@ -113,18 +113,18 @@
three buttons, the first one has a stretch factor of 1 and thus gets stretched,
whereas the other two buttons have a stretch factor of zero and keep their
initial width:
Within wxDesigner, this stretch factor gets set from the @e Option menu.
@section sizershiding Hiding controls using sizers
You can hide controls contained in sizers the same way you would hide any control,
using the wxWindow::Show method.
However, wxSizer also offers a separate method which can tell the sizer not to
However, wxSizer also offers a separate method which can tell the sizer not to
consider that control in its size calculations. To hide a window using the sizer,
call wxSizer::Show. You must then call Layout on the sizer
call wxSizer::Show. You must then call Layout on the sizer
to force an update.
This is useful when hiding parts of the interface, since you can avoid removing
the controls from the sizer and having to add them back later.
@@ -140,24 +140,24 @@
stretch factor determines how much the child can be stretched horizontally.
The following sample shows the same dialog as in the last sample,
only the box sizer is a vertical box sizer now:
@b wxStaticBoxSizer
#wxStaticBoxSixer is the same as a wxBoxSizer, but surrounded by a
static box. Here is a sample:
@b wxGridSizer
#wxGridSizer is a two-dimensional sizer. All children are given the
same size, which is the minimal size required by the biggest child, in
this case the text control in the left bottom border. Either the number
of columns or the number or rows is fixed and the grid sizer will grow
in the respectively other orientation if new children are added:
For programming information, see #wxGridSizer.
@b wxFlexGridSizer
Another two-dimensional sizer derived from
@@ -167,12 +167,12 @@
rows can be declared to be stretchable if the sizer is assigned
a size different from the one it requested. The following sample shows
the same dialog as the one above, but using a flex grid sizer:
@section boxsizerprogramming Programming with wxBoxSizer
The basic idea behind a #wxBoxSizer is that windows will most often be laid out in rather
simple basic geometry, typically in a row or a column or several hierarchies of either.
As an example, we will construct a dialog that will contain a text field at the top and
@@ -185,7 +185,7 @@
a thin border around all controls to make the dialog look nice and - to make matter worse -
the buttons shall be centred as the width of the dialog changes.
It is the unique feature of a box sizer, that it can grow in both directions (height and
width) but can distribute its growth in the main direction (horizontal for a row) @e unevenly
width) but can distribute its growth in the main direction (horizontal for a row) @e unevenly
among its children. In our example case, the vertical sizer is supposed to propagate all its
height changes to only the text area, not to the button area. This is determined by the @e proportion parameter
when adding a window (or another sizer) to a sizer. It is interpreted
@@ -209,17 +209,17 @@
Add() method using the binary or operator |. The sizer of the border also must be made known,
and it is the third parameter in the Add() method. This means, that the entire behaviour of
a sizer and its children can be controlled by the three parameters of the Add() method.
@code
// we want to get a dialog that is stretchable because it
// has a text ctrl at the top and two buttons at the bottom
MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString )
: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
{
wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
// create text ctrl with minimal size 100x60
topsizer-Add(
new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
@@ -227,8 +227,8 @@
wxEXPAND | // make horizontally stretchable
wxALL, // and make border all around
10 ); // set border width to 10
wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
button_sizer-Add(
new wxButton( this, wxID_OK, "OK" ),
@@ -240,103 +240,103 @@
0, // make horizontally unstretchable
wxALL, // make border all around (implicit top alignment)
10 ); // set border width to 10
topsizer-Add(
button_sizer,
0, // make vertically unstretchable
wxALIGN_CENTER ); // no border and centre horizontally
SetSizerAndFit(topsizer); // use the sizer for layout and size window
// accordingly and prevent it from being resized
// to smaller size
}
@endcode
Note that the new way of specifying flags to wxSizer is via #wxSizerFlags. This class greatly eases the burden of passing flags to a wxSizer.
Here's how you'd do the previous example with wxSizerFlags:
@code
// we want to get a dialog that is stretchable because it
// has a text ctrl at the top and two buttons at the bottom
MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString )
: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
{
wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
// create text ctrl with minimal size 100x60 that is horizontally and
// create text ctrl with minimal size 100x60 that is horizontally and
// vertically stretchable with a border width of 10
topsizer-Add(
new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
//create two buttons that are horizontally unstretchable,
//create two buttons that are horizontally unstretchable,
// with an all-around border with a width of 10 and implicit top alignment
button_sizer-Add(
new wxButton( this, wxID_OK, "OK" ),
wxSizerFlags(0).Align().Border(wxALL, 10));
wxSizerFlags(0).Align().Border(wxALL, 10));
button_sizer-Add(
new wxButton( this, wxID_CANCEL, "Cancel" ),
wxSizerFlags(0).Align().Border(wxALL, 10));
wxSizerFlags(0).Align().Border(wxALL, 10));
//create a sizer with no border and centered horizontally
topsizer-Add(
button_sizer,
wxSizerFlags(0).Center() );
wxSizerFlags(0).Center() );
SetSizerAndFit(topsizer); // use the sizer for layout and set size and hints
}
@endcode
@section gridsizerprogramming Programming with wxGridSizer
#wxGridSizer is a sizer which lays out its children in a two-dimensional
table with all table fields having the same size,
i.e. the width of each field is the width of the widest child,
the height of each field is the height of the tallest child.
@section flexgridsizerprogramming Programming with wxFlexGridSizer
#wxFlexGridSizer is a sizer which lays out its children in a two-dimensional
table with all table fields in one row having the same
height and all fields in one column having the same width, but all
rows or all columns are not necessarily the same height or width as in
the #wxGridSizer.
@section staticboxsizerprogramming Programming with wxStaticBoxSizer
#wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
box around the sizer. Note that this static box has to be created
box around the sizer. Note that this static box has to be created
separately.
@section createbuttonsizer CreateButtonSizer
As a convenience, CreateButtonSizer ( long flags ) can be used to create a standard button sizer
in which standard buttons are displayed. The following flags can be passed to this function:
@code
wxYES_NO // Add Yes/No subpanel
wxYES // return wxID_YES
wxNO // return wxID_NO
wxNO_DEFAULT // make the wxNO button the default, otherwise wxYES or wxOK button will be default
wxOK // return wxID_OK
wxCANCEL // return wxID_CANCEL
wxHELP // return wxID_HELP
wxFORWARD // return wxID_FORWARD
wxBACKWARD // return wxID_BACKWARD
wxSETUP // return wxID_SETUP
wxFORWARD // return wxID_FORWARD
wxBACKWARD // return wxID_BACKWARD
wxSETUP // return wxID_SETUP
wxMORE // return wxID_MORE
@endcode
*/

42
docs/doxygen/overviews/splitterwindow.h
View File

@@ -7,42 +7,42 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page splitterwindow_overview wxSplitterWindow overview
Classes: #wxSplitterWindow
The following screenshot shows the appearance of a splitter window with a horizontal split.
The style wxSP_3D has been used to show a 3D border and 3D sash.
#Example
@section wxsplitterwindowexample Example
The following fragment shows how to create a splitter window, creating two
subwindows and hiding one of them.
@code
splitter = new wxSplitterWindow(this, -1, wxPoint(0, 0), wxSize(400, 400), wxSP_3D);
leftWindow = new MyWindow(splitter);
leftWindow-SetScrollbars(20, 20, 50, 50);
rightWindow = new MyWindow(splitter);
rightWindow-SetScrollbars(20, 20, 50, 50);
rightWindow-Show(@false);
splitter-Initialize(leftWindow);
// Set this to prevent unsplitting
// splitter-SetMinimumPaneSize(20);
@endcode
The next fragment shows how the splitter window can be manipulated after creation.
@code
void MyFrame::OnSplitVertical(wxCommandEvent& event)
{
@@ -52,7 +52,7 @@
rightWindow-Show(@true);
splitter-SplitVertically( leftWindow, rightWindow );
}
void MyFrame::OnSplitHorizontal(wxCommandEvent& event)
{
if ( splitter-IsSplit() )
@@ -61,14 +61,14 @@
rightWindow-Show(@true);
splitter-SplitHorizontally( leftWindow, rightWindow );
}
void MyFrame::OnUnsplit(wxCommandEvent& event)
{
if ( splitter-IsSplit() )
splitter-Unsplit();
}
@endcode
*/

36
docs/doxygen/overviews/stream.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page stream_overview wxStreams overview
Classes: #wxStreamBase,
#wxStreamBuffer, #wxInputStream,
#wxOutputStream,
@@ -25,15 +25,15 @@
reliably compile and run on all supported platforms without dependence on a
particular release of libg++.
wxStreams is divided in two main parts:
the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
wxFilterIn/OutputStream
the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
wxStreamBase is the base definition of a stream. It defines, for example,
the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions
the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions
are really implemented by the "IO" classes.
wxInputStream and wxOutputStream inherit from it.
wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
@@ -53,38 +53,38 @@
@b Generic usage: an example
Usage is simple. We can take the example of wxFileInputStream and here is some sample
code:
@code
...
// The constructor initializes the stream buffer and open the file descriptor
// associated to the name of the file.
wxFileInputStream in_stream("the_file_to_be_read");
// Ok, read some bytes ... nb_datas is expressed in bytes.
in_stream.Read(data, nb_datas);
if (in_stream.LastError() != wxSTREAM_NOERROR) {
// Oh oh, something bad happens.
// For a complete list, look into the documentation at wxStreamBase.
}
// You can also inline all like this.
if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
// Do something.
}
// You can also get the last number of bytes REALLY put into the buffer.
size_t really_read = in_stream.LastRead();
// Ok, moves to the beginning of the stream. SeekI returns the last position
// Ok, moves to the beginning of the stream. SeekI returns the last position
// in the stream counted from the beginning.
off_t old_position = in_stream.SeekI(0, wxFromBeginning);
// What is my current position ?
off_t position = in_stream.TellI();
// wxFileInputStream will close the file descriptor on destruction.
@endcode
*/

116
docs/doxygen/overviews/string.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page string_overview wxString overview
Classes: #wxString, #wxArrayString, #wxStringTokenizer
#Introduction
@ref otherstringclasses_overview
@@ -17,11 +17,11 @@
@ref relatedtostring_overview
@ref stringrefcount_overview
@ref stringtuning_overview
@section introductiontowxstring Introduction
wxString is a class which represents a character string of arbitrary length (limited by
wxString is a class which represents a character string of arbitrary length (limited by
@e MAX_INT which is usually 2147483647 on 32 bit machines) and containing
arbitrary characters. The ASCII NUL character is allowed, but be aware that
in the current string implementation some methods might not work correctly
@@ -34,11 +34,11 @@
access to individual characters, string concatenation and comparison, substring
extraction, case conversion, trimming and padding (with spaces), searching and
replacing and both C-like #Printf() and stream-like
insertion functions as well as much more - see #wxString
insertion functions as well as much more - see #wxString
for a list of all functions.
@section otherstringclasses Comparison of wxString to other string classes
The advantages of using a special string class instead of working directly with
C strings are so obvious that there is a huge number of such classes available.
The most important advantage is the need to always
@@ -46,36 +46,36 @@
inevitably leads to buffer overflows. At last, C++ has a standard string class
(std::string). So why the need for wxString?
There are several advantages:
@b Efficiency This class was made to be as efficient as possible: both
in terms of size (each wxString objects takes exactly the same space as a @e char * pointer, sing @ref stringrefcount_overview) and speed.
It also provides performance @ref stringtuning_overview
It also provides performance @ref stringtuning_overview
which may be enabled to fine tune the memory allocation strategy for your
particular application - and the gain might be quite big.
@b Compatibility This class tries to combine almost full compatibility
with the old wxWidgets 1.xx wxString class, some reminiscence to MFC CString
class and 90% of the functionality of std::string class.
@b Rich set of functions Some of the functions present in wxString are
very useful but don't exist in most of other string classes: for example,
#AfterFirst,
#BeforeLast, #operator
very useful but don't exist in most of other string classes: for example,
#AfterFirst,
#BeforeLast, #operator
or #Printf. Of course, all the standard string
operations are supported as well.
@b Unicode wxString is Unicode friendly: it allows to easily convert
to and from ANSI and Unicode strings in any build mode (see the
to and from ANSI and Unicode strings in any build mode (see the
@ref unicode_overview for more details) and maps to either
@c string or @c wstring transparently depending on the current mode.
@b Used by wxWidgets And, of course, this class is used everywhere
inside wxWidgets so there is no performance loss which would result from
conversions of objects of any other string class (including std::string) to
wxString internally by wxWidgets.
However, there are several problems as well. The most important one is probably
that there are often several functions to do exactly the same thing: for
example, to get the length of the string either one of
length(), #Len() or
example, to get the length of the string either one of
length(), #Len() or
#Length() may be used. The first function, as almost
all the other functions in lowercase, is std::string compatible. The second one
is "native" wxString version and the last one is wxWidgets 1.xx way. So the
@@ -89,46 +89,46 @@
In the situations where there is no corresponding std::string function, please
try to use the new wxString methods and not the old wxWidgets 1.xx variants
which are deprecated and may disappear in future versions.
@section wxstringadvices Some advice about using wxString
Probably the main trap with using this class is the implicit conversion operator to
Probably the main trap with using this class is the implicit conversion operator to
@e const char *. It is advised that you use #c_str()
instead to clearly indicate when the conversion is done. Specifically, the
danger of this implicit conversion may be seen in the following code fragment:
@code
// this function converts the input string to uppercase, output it to the screen
// and returns the result
const char *SayHELLO(const wxString& input)
{
wxString output = input.Upper();
printf("Hello, %s!\n", output);
return output;
}
@endcode
There are two nasty bugs in these three lines. First of them is in the call to the
There are two nasty bugs in these three lines. First of them is in the call to the
@e printf() function. Although the implicit conversion to C strings is applied
automatically by the compiler in the case of
@code
puts(output);
@endcode
because the argument of @e puts() is known to be of the type @e const char *,
this is @b not done for @e printf() which is a function with variable
number of arguments (and whose arguments are of unknown types). So this call may
do anything at all (including displaying the correct string on screen), although
the most likely result is a program crash. The solution is to use
the most likely result is a program crash. The solution is to use
#c_str(): just replace this line with
@code
printf("Hello, %s!\n", output.c_str());
@endcode
The second bug is that returning @e output doesn't work. The implicit cast is
used again, so the code compiles, but as it returns a pointer to a buffer
belonging to a local variable which is deleted as soon as the function exits,
@@ -136,13 +136,13 @@
just make the function return wxString instead of a C string.
This leads us to the following general advice: all functions taking string
arguments should take @e const wxString (this makes assignment to the
strings inside the function faster because of
strings inside the function faster because of
@ref stringrefcount_overview) and all functions returning
strings should return @e wxString - this makes it safe to return local
variables.
@section relatedtostring Other string related functions and classes
As most programs use character strings, the standard C library provides quite
a few functions to work with them. Unfortunately, some of them have rather
counter-intuitive behaviour (like strncpy() which doesn't always terminate the
@@ -151,17 +151,17 @@
functions are not standard at all. This is why in addition to all wxString
functions, there are also a few global string functions which try to correct
these problems: #wxIsEmpty() verifies whether the string
is empty (returning @true for @NULL pointers),
is empty (returning @true for @NULL pointers),
#wxStrlen() also handles @NULLs correctly and returns 0 for
them and #wxStricmp() is just a platform-independent
version of case-insensitive string comparison function known either as
stricmp() or strcasecmp() on different platforms.
The @c wx/string.h header also defines #wxSnprintf
The @c wx/string.h header also defines #wxSnprintf
and #wxVsnprintf functions which should be used instead
of the inherently dangerous standard @c sprintf() and which use @c snprintf() instead which does buffer size checks whenever possible. Of
course, you may also use wxString::Printf which is
also safe.
There is another class which might be useful when working with wxString:
There is another class which might be useful when working with wxString:
#wxStringTokenizer. It is helpful when a string must
be broken into tokens and replaces the standard C library @e strtok() function.
And the very last string-related class is #wxArrayString: it
@@ -169,68 +169,68 @@
with strings. Please note that this class is specially optimized (using its
knowledge of the internal structure of wxString) for storing strings and so it is
vastly better from a performance point of view than a wxObjectArray of wxStrings.
@section wxstringrefcount Reference counting and why you shouldn't care about it
All considerations for wxObject-derived @ref trefcount_overview objects
are valid also for wxString, even if it does not derive from wxObject.
Probably the unique case when you might want to think about reference
counting is when a string character is taken from a string which is not a
constant (or a constant reference). In this case, due to C++ rules, the
"read-only" @e operator[] (which is the same as
#GetChar()) cannot be chosen and the "read/write"
@e operator[] (the same as
"read-only" @e operator[] (which is the same as
#GetChar()) cannot be chosen and the "read/write"
@e operator[] (the same as
#GetWritableChar()) is used instead. As the
call to this operator may modify the string, its data is unshared (COW is done)
and so if the string was really shared there is some performance loss (both in
terms of speed and memory consumption). In the rare cases when this may be
important, you might prefer using #GetChar() instead
of the array subscript operator for this reasons. Please note that
of the array subscript operator for this reasons. Please note that
#at() method has the same problem as the subscript operator in
this situation and so using it is not really better. Also note that if all
string arguments to your functions are passed as @e const wxString (see the
section @ref stringadvices_overview) this situation will almost
never arise because for constant references the correct operator is called automatically.
@section wxstringtuning Tuning wxString for your application
@b Note: this section is strictly about performance issues and is
absolutely not necessary to read for using wxString class. Please skip it unless
you feel familiar with profilers and relative tools. If you do read it, please
also read the preceding section about
also read the preceding section about
@ref stringrefcount_overview.
For the performance reasons wxString doesn't allocate exactly the amount of
memory needed for each string. Instead, it adds a small amount of space to each
allocated block which allows it to not reallocate memory (a relatively
expensive operation) too often as when, for example, a string is constructed by
subsequently adding one character at a time to it, as for example in:
@code
// delete all vowels from the string
wxString DeleteAllVowels(const wxString& original)
{
wxString result;
size_t len = original.length();
for ( size_t n = 0; n len; n++ )
{
if ( strchr("aeuio", tolower(original[n])) == @NULL )
result += original[n];
}
return result;
}
@endcode
This is quite a common situation and not allocating extra memory at all would
lead to very bad performance in this case because there would be as many memory
(re)allocations as there are consonants in the original string. Allocating too
much extra memory would help to improve the speed in this situation, but due to
a great number of wxString objects typically used in a program would also
increase the memory consumption too much.
The very best solution in precisely this case would be to use
The very best solution in precisely this case would be to use
#Alloc() function to preallocate, for example, len bytes
from the beginning - this will lead to exactly one memory allocation being
performed (because the result is at most as long as the original string).
@@ -256,7 +256,7 @@
really consider fine tuning wxString for your application).
It goes without saying that a profiler should be used to measure the precise
difference the change to EXTRA_ALLOC makes to your program.
*/

24
docs/doxygen/overviews/thread.h
View File

@@ -7,16 +7,16 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page thread_overview Multithreading overview
Classes: #wxThread, #wxMutex,
#wxCriticalSection,
Classes: #wxThread, #wxMutex,
#wxCriticalSection,
#wxCondition
wxWidgets provides a complete set of classes encapsulating objects necessary in
multithreaded (MT) programs: the #thread class itself and different
synchronization objects: #mutexes and
@ref criticalsection_overview with
synchronization objects: #mutexes and
@ref criticalsection_overview with
#conditions. The thread API in wxWidgets resembles to
POSIX1.c threads API (a.k.a. pthreads), although several functions have
different names and some features inspired by Win32 thread API are there as
@@ -31,7 +31,7 @@
new thread for each new client), but in others it might be a very poor choice
(example: launching a separate thread when doing a long computation to show a
progress dialog). Other implementation choices are available: for the progress
dialog example it is far better to do the calculations in the
dialog example it is far better to do the calculations in the
@ref idleevent_overview or even simply do everything at once
but call wxWindow::Update() periodically to update
the screen.
@@ -44,7 +44,7 @@
more robust and will undoubtedly save you countless problems (example: under
Win32 a thread can only access GDI objects such as pens, brushes, c created by
itself and not by the other threads).
For communication between secondary threads and the main thread, you may use
For communication between secondary threads and the main thread, you may use
wxEvtHandler::AddPendingEvent
or its short version #wxPostEvent. These functions
have a thread-safe implementation so that they can be used as they are for
@@ -52,10 +52,10 @@
to send messages to the worker threads and you will need to use the available
synchronization classes to implement the solution which suits your needs
yourself. In particular, please note that it is not enough to derive
your class from #wxThread and
your class from #wxThread and
#wxEvtHandler to send messages to it: in fact, this does
not work at all.
*/

42
docs/doxygen/overviews/tipprovider.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page tipprovider_overview wxTipProvider
This is the class used together with #wxShowTip function.
It must implement #GetTip function and return the
current tip from it (different tip each time it is called).
@@ -30,42 +30,42 @@
wxTipProvider::GetTip
wxTipProvider::PreprocessTip
wxCurrentTipProvider::GetCurrentTip
@section wxtipproviderctor wxTipProvider::wxTipProvider
@b @b wxTipProvider(@b size_t@e currentTip)
Constructor.
@e currentTip
The starting tip index.
@section wxtipprovidergettip wxTipProvider::GetTip
@b #wxString @b GetTip()
Return the text of the current tip and pass to the next one. This function is
pure virtual, it should be implemented in the derived classes.
@section wxtipproviderpreprocesstip wxTipProvider::PreprocessTip
@b virtual #wxString @b PreProcessTip(@b const #wxString&@e tip)
Returns a modified tip. This function will be called immediately after read,
and before being check whether it is a comment, an empty string or a string
to translate. You can optionally override this in your custom user-derived class
to optionally to modify the tip as soon as it is read. You can return any
modification to the string. If you return wxEmptyString, then this tip is
and before being check whether it is a comment, an empty string or a string
to translate. You can optionally override this in your custom user-derived class
to optionally to modify the tip as soon as it is read. You can return any
modification to the string. If you return wxEmptyString, then this tip is
skipped, and the next one is read.
@section wxtipprovidergetcurrenttip wxCurrentTipProvider::GetCurrentTip
@b size_t @b GetCurrentTip() @b const
Returns the index of the current tip (i.e. the one which would be returned by
Returns the index of the current tip (i.e. the one which would be returned by
GetTip).
The program usually remembers the value returned by this function after calling
The program usually remembers the value returned by this function after calling
#wxShowTip. Note that it is not the same as the value which
was passed to wxShowTip + 1 because the user might have pressed the "Next"
button in the tip dialog.
*/

46
docs/doxygen/overviews/tips.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page tips_overview wxTipProvider overview
Many "modern" Windows programs have a feature (some would say annoyance) of
presenting the user tips at program startup. While this is probably useless to
the advanced users of the program, the experience shows that the tips may be
@@ -17,7 +17,7 @@
For a wxWidgets programmer, implementing this feature is extremely easy. To
show a tip, it is enough to just call #wxShowTip function
like this:
@code
if ( ...show tips at startup?... )
{
@@ -26,13 +26,13 @@
delete tipProvider;
}
@endcode
Of course, you need to get the text of the tips from somewhere - in the example
above, the text is supposed to be in the file tips.txt from where it is read by
the @e tip provider. The tip provider is just an object of a class deriving
from #wxTipProvider. It has to implement one pure
virtual function of the base class: #GetTip.
In the case of the tip provider created by
In the case of the tip provider created by
#wxCreateFileTipProvider, the tips are just
the lines of the text file.
If you want to implement your own tip provider (for example, if you wish to
@@ -44,33 +44,33 @@
also need to remember whether to show tips or not (you shouldn't do it if the
user unchecked "Show tips on startup" checkbox in the dialog), you will
probably want to store both the index of the
last shown tip (as returned by
last shown tip (as returned by
wxTipProvider::GetCurrentTip and the flag
telling whether to show the tips at startup at all.
In a tips.txt file, lines that begin with a # character are considered comments
and are automatically skipped. Blank lines and lines only having spaces are also
In a tips.txt file, lines that begin with a # character are considered comments
and are automatically skipped. Blank lines and lines only having spaces are also
skipped.
You can easily add runtime-translation capacity by placing each line of the
tips.txt file inside the usual translation macro. For example, your tips.txt
You can easily add runtime-translation capacity by placing each line of the
tips.txt file inside the usual translation macro. For example, your tips.txt
file would look like this:
@code
_("This is my first tip")
_("This is my second tip")
@endcode
Now add your tips.txt file into the list of files that gettext searches
for translatable strings. The tips will thus get included into your
generated .po file catalog and be translated at runtime along with the rest of
your application's translatable strings.
Note1: Each line in the tips.txt file needs to strictly begin with exactly the
3 characters of underscore-parenthesis-doublequote, and end with
doublequote-parenthesis, as shown above.
Now add your tips.txt file into the list of files that gettext searches
for translatable strings. The tips will thus get included into your
generated .po file catalog and be translated at runtime along with the rest of
your application's translatable strings.
Note1: Each line in the tips.txt file needs to strictly begin with exactly the
3 characters of underscore-parenthesis-doublequote, and end with
doublequote-parenthesis, as shown above.
Note2: Remember to escape any doublequote characters within the tip string with
a backslash-doublequote.
See the dialogs program in your samples folder for a working example inside a
See the dialogs program in your samples folder for a working example inside a
program.
*/

112
docs/doxygen/overviews/toolbar.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page toolbar_overview Toolbar overview
Classes: #wxToolBar
The toolbar family of classes allows an application to use toolbars
in a variety of configurations and styles.
@@ -25,8 +25,8 @@
For each platform, the symbol @b wxToolBar is defined to be one of the
specific toolbar classes.
The following is a summary of the toolbar classes and their differences.
@b wxToolBarBase. This is a base class with pure virtual functions,
and should not be used directly.
@b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
@@ -45,8 +45,8 @@
Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
look is used, with a border that is highlighted when the cursor moves over the buttons.
A toolbar might appear as a single row of images under
the menubar, or it might be in a separate frame layout in several rows
and columns. The class handles the layout of the images, unless explicit
@@ -64,24 +64,24 @@
one bitmap for each tool, because the toolbar generates all three images (normal,
depressed and checked) from the single bitmap you give it.
@ref usingtoolbarlibrary_overview
@section usingtoolbarlibrary Using the toolbar library
Include @c "wx/toolbar.h", or if using a class directly, one of:
@c "wx/msw/tbarmsw.h for wxToolBarMSW
@c "wx/msw/tbar95.h for wxToolBar95
@c "wx/tbarsmpl.h for wxToolBarSimple
Example of toolbar use are given in the sample program "toolbar''. The
source is given below. In fact it is out of date because recommended
practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
overriding OnLeftClick.
@code
/////////////////////////////////////////////////////////////////////////////
// Name: test.cpp
@@ -91,25 +91,25 @@
// Created: 04/01/98
// RCS-ID: $Id: ttoolbar.tex 47878 2007-08-05 10:10:37Z JS $
// Copyright: (c) Julian Smart
// License: wxWindows license
// License: wxWindows license
/////////////////////////////////////////////////////////////////////////////
// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"
#ifdef __BORLANDC__
#pragma hdrstop
#endif
#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif
#include "wx/toolbar.h"
#include wx/log.h
#include "test.h"
#if defined(__WXGTK__) || defined(__WXMOTIF__)
#include "mondrian.xpm"
#include "bitmaps/new.xpm"
@@ -121,9 +121,9 @@
#include "bitmaps/preview.xpm"
#include "bitmaps/help.xpm"
#endif
IMPLEMENT_APP(MyApp)
// The `main program' equivalent, creating the windows and returning the
// main frame
bool MyApp::OnInit(void)
@@ -131,53 +131,53 @@
// Create the main frame window
MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
wxPoint(100, 100), wxSize(450, 300));
// Give it a status line
frame-CreateStatusBar();
// Give it an icon
frame-SetIcon(wxICON(mondrian));
// Make a menubar
wxMenu *fileMenu = new wxMenu;
fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
wxMenu *helpMenu = new wxMenu;
helpMenu-Append(wxID_HELP, "", "About toolbar sample");
wxMenuBar* menuBar = new wxMenuBar;
menuBar-Append(fileMenu, "");
menuBar-Append(helpMenu, "");
// Associate the menu bar with the frame
frame-SetMenuBar(menuBar);
// Create the toolbar
frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
frame-GetToolBar()-SetMargins( 2, 2 );
InitToolbar(frame-GetToolBar());
// Force a resize. This should probably be replaced by a call to a wxFrame
// function that lays out default decorations and the remaining content window.
wxSizeEvent event(wxSize(-1, -1), frame-GetId());
frame-OnSize(event);
frame-Show(@true);
frame-SetStatusText("Hello, wxWidgets");
SetTopWindow(frame);
return @true;
}
bool MyApp::InitToolbar(wxToolBar* toolBar)
{
// Set up toolbar
wxBitmap* toolBarBitmaps[8];
#ifdef __WXMSW__
toolBarBitmaps[0] = new wxBitmap("icon1");
toolBarBitmaps[1] = new wxBitmap("icon2");
@@ -197,14 +197,14 @@
toolBarBitmaps[6] = new wxBitmap( print_xpm );
toolBarBitmaps[7] = new wxBitmap( help_xpm );
#endif
#ifdef __WXMSW__
int width = 24;
#else
int width = 16;
#endif
int currentX = 5;
toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
currentX += width + 5;
toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
@@ -223,19 +223,19 @@
currentX += width + 5;
toolBar-AddSeparator();
toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
toolBar-Realize();
// Can delete the bitmaps since they're reference counted
int i;
for (i = 0; i 8; i++)
delete toolBarBitmaps[i];
return @true;
}
// wxID_HELP will be processed for the 'About' menu and the toolbar help button.
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
EVT_MENU(wxID_HELP, MyFrame::OnAbout)
@@ -243,7 +243,7 @@
EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
END_EVENT_TABLE()
// Define my frame constructor
MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
const wxSize& size, long style):
@@ -251,31 +251,31 @@
{
m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
}
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close(@true);
}
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
(void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
}
// Define the behaviour for the frame closing
// - must delete all frames except for the main one.
void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
{
Destroy();
}
void MyFrame::OnToolLeftClick(wxCommandEvent& event)
{
wxString str;
str.Printf("Clicked on tool %d", event.GetId());
SetStatusText(str);
}
void MyFrame::OnToolEnter(wxCommandEvent& event)
{
if (event.GetSelection() -1)
@@ -288,7 +288,7 @@
SetStatusText("");
}
@endcode
*/

42
docs/doxygen/overviews/treectrl.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page treectrl_overview wxTreeCtrl overview
Classes: #wxTreeCtrl, #wxImageList
The tree control displays its items in a tree like structure. Each item has its
own (optional) icon and a label. An item may be either collapsed (meaning that
@@ -17,36 +17,36 @@
shown). Each item in the tree is identified by its @e itemId which is of
opaque data type @e wxTreeItemId. You can test whether an item is valid
by calling wxTreeItemId::IsOk.
The items text and image may be retrieved and changed with
#GetItemText/#SetItemText
and
The items text and image may be retrieved and changed with
#GetItemText/#SetItemText
and
#GetItemImage/#SetItemImage.
In fact, an item may even have two images associated with it: the normal one
and another one for selected state which is set/retrieved with
#SetItemSelectedImage/#GetItemSelectedImage
and another one for selected state which is set/retrieved with
#SetItemSelectedImage/#GetItemSelectedImage
functions, but this functionality might be unavailable on some platforms.
Tree items have several attributes: an item may be selected or not, visible or
not, bold or not. It may also be expanded or collapsed. All these attributes
may be retrieved with the corresponding functions:
#IsSelected,
#IsVisible, #IsBold
may be retrieved with the corresponding functions:
#IsSelected,
#IsVisible, #IsBold
and #IsExpanded. Only one item at a time may be
selected, selecting another one (with
selected, selecting another one (with
#SelectItem) automatically unselects the
previously selected one.
In addition to its icon and label, a user-specific data structure may be associated
with all tree items. If you wish to do it, you should derive a class from @e wxTreeItemData which is a very simple class having only one function @e GetId() which returns the id of the item this data is associated with. This
data will be freed by the control itself when the associated item is deleted
(all items are deleted when the control is destroyed), so you shouldn't delete
it yourself (if you do it, you should call
it yourself (if you do it, you should call
#SetItemData(@NULL) to prevent the tree from
deleting the pointer second time). The associated data may be retrieved with
deleting the pointer second time). The associated data may be retrieved with
#GetItemData() function.
Working with trees is relatively straightforward if all the items are added to
the tree at the moment of its creation. However, for large trees it may be
very inefficient. To improve the performance you may want to delay adding the
items to the tree until the branch containing the items is expanded: so, in the
beginning, only the root item is created (with
beginning, only the root item is created (with
#AddRoot). Other items are added when
EVT_TREE_ITEM_EXPANDING event is received: then all items lying immediately
under the item being expanded should be added, but, of course, only when this
@@ -60,16 +60,16 @@
require the caller to give them a @e cookie parameter: it is a number which
is opaque to the caller but is used by the tree control itself to allow
multiple enumerations to run simultaneously (this is explicitly allowed). The
only thing to remember is that the @e cookie passed to
#GetFirstChild and to
only thing to remember is that the @e cookie passed to
#GetFirstChild and to
#GetNextChild should be the same variable (and
that nothing should be done with it by the user code).
Among other features of the tree control are: item sorting with
Among other features of the tree control are: item sorting with
#SortChildren which uses the user-defined comparison
function #OnCompareItems (by default the
comparison is the alphabetic comparison of tree labels), hit testing
(determining to which portion of the control the given point belongs, useful
for implementing drag-and-drop in the tree) with
for implementing drag-and-drop in the tree) with
#HitTest and editing of the tree item labels in
place (see #EditLabel).
Finally, the tree control has a keyboard interface: the cursor navigation (arrow) keys
@@ -78,7 +78,7 @@
and toggle the current branch. Note, however, that DEL and INS keys do
nothing by default, but it is common to associate them with deleting an item from
a tree and inserting a new one into it.
*/

68
docs/doxygen/overviews/trefcount.h
View File

@@ -7,18 +7,18 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page trefcount_overview Reference counting
@ref refcount_overview
@ref refcountequality_overview
@ref refcountdestruct_overview
@ref refcountlist_overview
@ref object_overview
@section refcount Why you shouldn't care about it
Many wxWidgets objects use a technique known as @e reference counting, also known
as @e copy on write (COW).
This means that when an object is assigned to another, no copying really takes place:
@@ -32,9 +32,9 @@
transparently to the class users and that whether an object is shared or not
is not seen from the outside of the class - in any case, the result of any
operation on it is the same.
@section refcountequality Object comparison
The == and != operators of @ref refcountlist_overview
always do a @c deep comparison.
This means that the equality operator will return @true if two objects are
@@ -46,55 +46,55 @@
Also note that if you only need to do a @c shallow comparison between two
#wxObject-derived classes, you should not use the == and != operators
but rather the wxObject::IsSameAs function.
@section refcountdestruct Object destruction
When a COW object destructor is called, it may not delete the data: if it's shared,
the destructor will just decrement the shared data's reference count without destroying it.
Only when the destructor of the last object owning the data is called, the data is really
destroyed. As for all other COW-things, this happens transparently to the class users so
that you shouldn't care about it.
@section refcountlist List of reference-counted wxWidgets classes
The following classes in wxWidgets have efficient (i.e. fast) assignment operators
and copy constructors since they are reference-counted:
#wxAcceleratorTable
#wxAnimation
#wxBitmap
#wxBrush
#wxCursor
#wxFont
#wxIcon
#wxImage
#wxMetafile
#wxPalette
#wxPen
#wxRegion
#wxString
#wxVariant
#wxVariantData
Note that the list above reports the objects which are reference-counted in all ports of
wxWidgets; some ports may use this tecnique also for other classes.
@section wxobjectoverview Make your own reference-counted class
Reference counting can be implemented easily using #wxObject
and #wxObjectRefData classes. Alternatively, you
can also use the #wxObjectDataPtrT template.
@@ -104,18 +104,18 @@
the public interface which will be seen by the user of your class.
You'll probably want to add a function to your class which does the cast from
#wxObjectRefData to your class-specific shared data; e.g.:
@code
MyClassRefData *GetData() const { return wx_static_cast(MyClassRefData*, m_refData); }
@endcode
in fact, all times you'll need to read the data from your wxObject-derived class,
you'll need to call such function.
Very important, all times you need to actually modify the data placed inside your
wxObject-derived class, you must first call the wxObject::UnShare
function to be sure that the modifications won't affect other instances which are
eventually sharing your object's data.
*/

96
docs/doxygen/overviews/unicode.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page unicode_overview Unicode support in wxWidgets
This section briefly describes the state of the Unicode support in wxWidgets.
Read it if you want to know more about how to write programs able to work with
characters from languages other than English.
@@ -19,10 +19,10 @@
@ref unicodeoutsidewxw_overview
@ref unicodesettings_overview
@ref topic8_overview
@section whatisunicode What is Unicode?
wxWidgets has support for compiling in Unicode mode
on the platforms which support it. Unicode is a standard for character
encoding which addresses the shortcomings of the previous, 8 bit standards, by
@@ -41,24 +41,24 @@
from using Unicode because they will work more efficiently - there will be no
need for the system to convert all strings the program uses to/from Unicode
each time a system call is made.
@section unicodeandansi Unicode and ANSI modes
As not all platforms supported by wxWidgets support Unicode (fully) yet, in
many cases it is unwise to write a program which can only work in Unicode
environment. A better solution is to write programs in such way that they may
be compiled either in ANSI (traditional) mode or in the Unicode one.
This can be achieved quite simply by using the means provided by wxWidgets.
Basically, there are only a few things to watch out for:
Character type (@c char or @c wchar_t)
Literal strings (i.e. @c "Hello, world!" or @c '*')
String functions (@c strlen(), @c strcpy(), ...)
Special preprocessor tokens (@c __FILE__, @c __DATE__
Special preprocessor tokens (@c __FILE__, @c __DATE__
and @c __TIME__)
Let's look at them in order. First of all, each character in an Unicode
program takes 2 bytes instead of usual one, so another type should be used to
store the characters (@c char only holds 1 byte usually). This type is
@@ -73,69 +73,69 @@
Of course, the usual standard C functions don't work with @c wchar_t
strings, so another set of functions exists which do the same thing but accept
@c wchar_t * instead of @c char *. For example, a function to get the
length of a wide-character string is called @c wcslen() (compare with
length of a wide-character string is called @c wcslen() (compare with
@c strlen() - you see that the only difference is that the "str" prefix
standing for "string" has been replaced with "wcs" standing for "wide-character
string").
And finally, the standard preprocessor tokens enumerated above expand to ANSI
strings but it is more likely that Unicode strings are wanted in the Unicode
build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__
build. wxWidgets provides the macros @c __TFILE__, @c __TDATE__
and @c __TTIME__ which behave exactly as the standard ones except that
they produce ANSI strings in ANSI build and Unicode ones in the Unicode build.
To summarize, here is a brief example of how a program which can be compiled
in both ANSI and Unicode modes could look like:
@code
#ifdef __UNICODE__
wchar_t wch = L'*';
const wchar_t *ws = L"Hello, world!";
int len = wcslen(ws);
wprintf(L"Compiled at %s\n", __TDATE__);
#else // ANSI
char ch = '*';
const char *s = "Hello, world!";
int len = strlen(s);
printf("Compiled at %s\n", __DATE__);
#endif // Unicode/ANSI
@endcode
Of course, it would be nearly impossibly to write such programs if it had to
be done this way (try to imagine the number of @c #ifdef UNICODE an average
program would have had!). Luckily, there is another way - see the next
section.
@section unicodeinsidewxw Unicode support in wxWidgets
In wxWidgets, the code fragment from above should be written instead:
@code
wxChar ch = wxT('*');
wxString s = wxT("Hello, world!");
int len = s.Len();
@endcode
What happens here? First of all, you see that there are no more @c #ifdefs
at all. Instead, we define some types and macros which behave differently in
the Unicode and ANSI builds and allow us to avoid using conditional
compilation in the program itself.
We have a @c wxChar type which maps either on @c char or @c wchar_t
We have a @c wxChar type which maps either on @c char or @c wchar_t
depending on the mode in which program is being compiled. There is no need for
a separate type for strings though, because the standard
a separate type for strings though, because the standard
#wxString supports Unicode, i.e. it stores either ANSI or
Unicode strings depending on the compile mode.
Finally, there is a special #wxT() macro which should enclose all
literal strings in the program. As it is easy to see comparing the last
fragment with the one above, this macro expands to nothing in the (usual) ANSI
mode and prefixes @c 'L' to its argument in the Unicode mode.
The important conclusion is that if you use @c wxChar instead of
The important conclusion is that if you use @c wxChar instead of
@c char, avoid using C style strings and use @c wxString instead and
don't forget to enclose all string literals inside #wxT() macro, your
program automatically becomes (almost) Unicode compliant!
Just let us state once again the rules:
Always use @c wxChar instead of @c char
Always enclose literal string constants in #wxT() macro
unless they're already converted to the right representation (another standard
@@ -143,11 +143,11 @@
need for @c wxT() in this case) or you intend to pass the constant directly
to an external function which doesn't accept wide-character strings.
Use @c wxString instead of C style strings.
@section unicodeoutsidewxw Unicode and the outside world
We have seen that it was easy to write Unicode programs using wxWidgets types
and macros, but it has been also mentioned that it isn't quite enough.
Although everything works fine inside the program, things can get nasty when
@@ -155,46 +155,46 @@
ANSI strings (a notable exception is the entire Win32 API which accepts either
Unicode or ANSI strings and which thus makes it unnecessary to ever perform
any conversions in the program). GTK 2.0 only accepts UTF-8 strings.
To get an ANSI string from a wxString, you may use the
To get an ANSI string from a wxString, you may use the
mb_str() function which always returns an ANSI
string (independently of the mode - while the usual
string (independently of the mode - while the usual
#c_str() returns a pointer to the internal
representation which is either ASCII or Unicode). More rarely used, but still
useful, is wc_str() function which always returns
the Unicode string.
Sometimes it is also necessary to go from ANSI strings to wxStrings.
Sometimes it is also necessary to go from ANSI strings to wxStrings.
In this case, you can use the converter-constructor, as follows:
@code
const char* ascii_str = "Some text";
wxString str(ascii_str, wxConvUTF8);
@endcode
This code also compiles fine under a non-Unicode build of wxWidgets,
but in that case the converter is ignored.
For more information about converters and Unicode see
the @ref mbconvclasses_overview.
@section unicodesettings Unicode-related compilation settings
You should define @c wxUSE_UNICODE to 1 to compile your program in
Unicode mode. This currently works for wxMSW, wxGTK, wxMac and wxX11. If you
compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T
compile your program in ANSI mode you can still define @c wxUSE_WCHAR_T
to get some limited support for @c wchar_t type.
This will allow your program to perform conversions between Unicode strings and
ANSI ones (using @ref mbconvclasses_overview)
ANSI ones (using @ref mbconvclasses_overview)
and construct wxString objects from Unicode strings (presumably read
from some external file or elsewhere).
@section topic8 Traps for the unwary
Casting c_str() to void* is now char*, not wxChar*
Passing c_str(), mb_str() or wc_str() to variadic functions
doesn't work
*/

14
docs/doxygen/overviews/unixprinting.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page unixprinting_overview Printing under Unix (GTK+)
Printing under Unix has always been a cause of problems as Unix
does not provide a standard way to display text and graphics
on screen and print it to a printer using the same application
@@ -33,8 +33,8 @@
Note that the application will not require the GNOME print libraries
to be installed in order to run (there will be no dependency on
these libraries).
In version GTK+ 2.10, support for printing has been added to GTK+
itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of
In version GTK+ 2.10, support for printing has been added to GTK+
itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of
wxWidgets can make use of this feature
if wxWidgets is configured accordingly and if the GTK+ version is = 2.10.
You need to configure wxWidgets with the @e configure --with-gtkprint
@@ -45,7 +45,7 @@
Note that the application will not require a GTK+ version = 2.10
to be installed in order to run (there will be no dependency on
this version).
*/

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

@@ -7,10 +7,10 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page validator_overview wxValidator overview
Classes: #wxValidator, #wxTextValidator,
Classes: #wxValidator, #wxTextValidator,
#wxGenericValidator
The aim of the validator concept is to make dialogs very much easier to write.
A validator is an object that can be plugged into a control (such as a wxTextCtrl), and
@@ -18,27 +18,27 @@
and validating it. It also is able to intercept events generated
by the control, providing filtering behaviour without the need to derive a new control class.
You can use a stock validator, such as #wxTextValidator (which does text
control data transfer, validation and filtering) and
control data transfer, validation and filtering) and
#wxGenericValidator (which does data transfer for a range of controls);
or you can write your own.
@b Example
Here is an example of wxTextValidator usage.
@code
wxTextCtrl *txt1 = new wxTextCtrl(this, -1, wxT(""),
wxPoint(10, 10), wxSize(100, 80), 0,
wxTextValidator(wxFILTER_ALPHA, _data.m_string));
@endcode
In this example, the text validator object provides the following functionality:
It transfers the value of g_data.m_string (a wxString variable) to the wxTextCtrl when
the dialog is initialised.
It transfers the wxTextCtrl data back to this variable when the dialog is dismissed.
It filters input characters so that only alphabetic characters are allowed.
The validation and filtering of input is accomplished in two ways. When a character is input,
wxTextValidator checks the character against the allowed filter flag (wxFILTER_ALPHA in this case). If
the character is inappropriate, it is vetoed (does not appear) and a warning beep sounds.
@@ -76,11 +76,11 @@
function finds all the validators in the window's children and calls the TransferToWindow
function for each. Thus, data is transferred from C++ variables to the dialog
just as the dialog is being shown.
If you are using a window or panel instead of a dialog, you will need to
call wxWindow::InitDialog explicitly before showing the
window.
When the user clicks on a button, for example the OK button, the application should
first call wxWindow::Validate, which returns @false if
any of the child window validators failed to validate the window data. The button handler
@@ -90,7 +90,7 @@
or Show (if modeless).
In fact, wxDialog contains a default command event handler for the wxID_OK button. It goes like
this:
@code
void wxDialog::OnOK(wxCommandEvent& event)
{
@@ -106,12 +106,12 @@
}
}
@endcode
So if using validators and a normal OK button, you may not even need to write any
code for handling dialog dismissal.
If you load your dialog from a resource file, you will need to iterate through the controls
setting validators, since validators can't be specified in a dialog resource.
*/

20
docs/doxygen/overviews/windowdeletion.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page windowdeletion_overview Window deletion overview
Classes: #wxCloseEvent, #wxWindow
Window deletion can be a confusing subject, so this overview is provided
to help make it clear when and how you delete windows, or respond to user requests
@@ -24,7 +24,7 @@
(wxCloseEvent::CanVeto returns @false), the window should always be destroyed, otherwise there is the option to
ignore the request, or maybe wait until the user has answered a question
before deciding whether it is safe to close. The handler for EVT_CLOSE should
signal to the calling code if it does not destroy the window, by calling
signal to the calling code if it does not destroy the window, by calling
wxCloseEvent::Veto. Calling this provides useful information
to the calling code.
The wxCloseEvent handler should only call wxWindow::Destroy to
@@ -65,7 +65,7 @@
or not delete the window.
To update your code, you should provide an event table entry in your frame or
dialog, using the EVT_CLOSE macro. The event handler function might look like this:
@code
void MyFrame::OnCloseWindow(wxCloseEvent& event)
{
@@ -73,10 +73,10 @@
{
wxMessageDialog* dialog = new wxMessageDialog(this,
"Save changed data?", "My app", wxYES_NO|wxCANCEL);
int ans = dialog-ShowModal();
dialog-Destroy();
switch (ans)
{
case wxID_YES: // Save, then destroy, quitting app
@@ -97,7 +97,7 @@
}
}
@endcode
@b How do I exit the application gracefully?
A wxWidgets application automatically exits when the last top level window
(#wxFrame or #wxDialog), is destroyed. Put
@@ -113,7 +113,7 @@
close event handlers, though you can implement them if you wish. For consistency,
continue to use the wxWindow::Destroy function instead
of the @b delete operator when deleting these kinds of windows explicitly.
*/

26
docs/doxygen/overviews/windowids.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page windowids_overview Window IDs overview
@b See Also
#wxIdManager
wxWindow::NewControlId
@@ -17,14 +17,14 @@
#Introduction
@ref windowidstypes_overview
@ref windowidsusing_overview
@section windowidsoverviewintro Introduction
Various contols and other parts of wxWidgets need an ID. Sometimes the
ID may be directly provided by the use or have a predefined value, such as
@c wxID_OPEN. Often, however, the value of the ID is unimportant and is
created automatically by calling wxWindow::NewControlId
created automatically by calling wxWindow::NewControlId
or by passing @c wxID_ANY as the ID of an object.
There are two ways to generate an ID. One way, is to start at a negative number,
and for each new ID, return the next smallest number. This is fine for systems
@@ -42,9 +42,9 @@
another. This is accomplished by keeping a reference count for each of the IDs
that can possibly be returned by wxWindow::NewControlId.
Other IDs are not reference counted.
@section windowidsoverviewtypes Data types
A wxWindowID is just the integer type for a window ID. It should be used almost
everywhere. To help keep track of the count for the automatically generated IDs,
a new type, wxWindowIDRef exists, that can take the place of wxWindowID where needed.
@@ -61,15 +61,15 @@
wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId
as well as normal IDs. Reference counting is only done for the automatic IDs. Also,
wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID.
@section windowidsoverviewusing Using wxWindowIDRef
A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the
ID is not created again by wxWindow::NewControlId
at least until the wxWindowIDRef is destroyed, usually when the associated object is destroyed.
This is done already for windows, menu items, and tool bar items.
It should only be used in the main thread, as it is not thread safe.
*/

18
docs/doxygen/overviews/windowsizing.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page windowsizing_overview Window Sizing Overview
It can sometimes be confusing to keep track of the various
size-related attributes of a #wxWindow, how they
relate to each other, and how they interact with sizers. This document
@@ -27,15 +27,15 @@
wants to calculate its own best size based on its content. The default
@c DoGetBestSize() is designed for use in container windows,
such as #wxPanel, and works something like this:
If the window has a sizer then it is used to calculate the best size.
Otherwise if the window has layout constraints then that is used to calculate the best size.
Otherwise if the window has children then the best size is set to be large enough to show all the children.
Otherwise if there are no children then the window's min size will be used for the best size.
Otherwise if there is no min size set, then the current size is used for the best size.
@b MinSize: The min size of a widget is a size that is normally
explicitly set by the programmer either with the @c SetMinSize()
method or the @c SetSizeHints() method. Most controls will also
@@ -93,7 +93,7 @@
constraints instead of a sizer then the constraints algorithm is
run. The @c Layout() method is what is called by the default
@c EVT_SIZE handler for container windows.
*/

14
docs/doxygen/overviews/windowstyles.h
View File

@@ -7,21 +7,21 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page windowstyles_overview Window styles
Window styles are used to specify alternative behaviour and appearances for windows, when they are
created. The symbols are defined in such a way that they can be combined in a 'bit-list' using the
C++ @e bitwise-or operator. For example:
@code
wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER
@endcode
For the window styles specific to each window class, please see the documentation
for the window. Most windows can use the generic styles listed for #wxWindow in
addition to their own styles.
*/

230
docs/doxygen/overviews/xrc.h
View File

@@ -7,9 +7,9 @@
/////////////////////////////////////////////////////////////////////////////
/*!
@page xrc_overview XML-based resource system overview
Classes: #wxXmlResource, #wxXmlResourceHandler
The XML-based resource system, known as XRC, allows user interface elements such as
dialogs, menu bars and toolbars, to be stored in text files and loaded into
@@ -17,8 +17,8 @@
code (the former makes it possible to store all resources in a single file and the latter
is useful when you want to embed the resources into the executable).
There are several advantages to using XRC resources.
Recompiling and linking an application is not necessary if the
resources change.
If you use a dialog designer that generates C++ code, it can be hard
@@ -30,8 +30,8 @@
The XRC format is a wxWidgets standard,
and can be generated or postprocessed by any program that understands it. As it is based
on the XML standard, existing XML editors can be used for simple editing purposes.
XRC was written by Vaclav Slavik.
@ref xrcconcepts_overview
@ref binaryresourcefiles_overview
@@ -41,13 +41,13 @@
@ref xrcfileformat_overview
@ref xrccppheader_overview
@ref newresourcehandlers_overview
@section xrcconcepts XRC concepts
These are the typical steps for using XRC files in your application.
Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice;
If you are going to use @ref binaryresourcefiles_overview, install
wxFileSystem archive handler first with @c wxFileSystem::AddHandler(new wxArchiveFSHandler);
@@ -57,11 +57,11 @@
load it using for example @c wxXmlResource::Get()-LoadDialog(dlg, this, "dlg1");
set up event tables as usual but use the @c XRCID(str) macro to translate from XRC string names
to a suitable integer identifier, for example @c EVT_MENU(XRCID("quit"), MyFrame::OnQuit).
To create an XRC file, you can use one of the following methods.
Create the file by hand;
use #wxDesigner, a commercial dialog designer/RAD tool;
use #DialogBlocks, a commercial dialog editor;
@@ -69,8 +69,8 @@
dialog editor that you can find in the @c wxPython/tools subdirectory of the wxWidgets
CVS archive;
use #wxGlade, a GUI designer written in wxPython. At the moment it can generate Python, C++ and XRC;
A complete list of third-party tools that write to XRC can be found at #www.wxwidgets.org/lnk_tool.htm.
It is highly recommended that you use a resource editing tool, since it's fiddly writing
XRC files by hand.
@@ -78,58 +78,58 @@
You can pass an XRC file (XML-based text resource file)
or a @ref binaryresourcefiles_overview (extension ZIP or XRS) containing other XRC.
You can also use @ref embeddedresource_overview
@section binaryresourcefiles Using binary resource files
To compile binary resource files, use the command-line wxrc utility. It takes one or more file parameters
(the input XRC files) and the following switches and options:
-h (--help): show a help message
-v (--verbose): show verbose logging information
-c (--cpp-code): write C++ source rather than a XRS file
-e (--extra-cpp-code): if used together with -c, generates C++ header file
containing class definitions for the windows defined by the XRC file (see special subsection)
containing class definitions for the windows defined by the XRC file (see special subsection)
-u (--uncompressed): do not compress XML files (C++ only)
-g (--gettext): output underscore-wrapped strings that poEdit or gettext can scan. Outputs to stdout, or a file if -o is used
-n (--function) name: specify C++ function name (use with -c)
-o (--output) filename: specify the output file, such as resource.xrs or resource.cpp
-l (--list-of-handlers) filename: output a list of necessary handlers to this file
For example:
@code
% wxrc resource.xrc
% wxrc resource.xrc -o resource.xrs
% wxrc resource.xrc -v -c -o resource.cpp
@endcode
@b Note
XRS file is essentially a renamed ZIP archive which means that you can manipulate
it with standard ZIP tools. Note that if you are using XRS files, you have
to initialize the #wxFileSystem archive handler first! It is a simple
thing to do:
@code
#include wx/filesys.h
#include wx/fs_arc.h
...
wxFileSystem::AddHandler(new wxArchiveFSHandler);
@endcode
@section embeddedresource Using embedded resources
It is sometimes useful to embed resources in the executable itself instead
of loading an external file (e.g. when your app is small and consists only of one
exe file). XRC provides means to convert resources into regular C++ file that
can be compiled and included in the executable.
can be compiled and included in the executable.
Use the @c -c switch to
@c wxrc utility to produce C++ file with embedded resources. This file will
contain a function called @e InitXmlResource (unless you override this with
a command line switch). Use it to load the resource:
@code
extern void InitXmlResource(); // defined in generated file
...
@@ -137,124 +137,124 @@
InitXmlResource();
...
@endcode
@section xrccppsample XRC C++ sample
This is the C++ source file (xrcdemo.cpp) for the XRC sample.
@code
#include "wx/wx.h"
#include "wx/image.h"
#include "wx/xrc/xmlres.h"
// the application icon
#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
#include "rc/appicon.xpm"
#endif
// ----------------------------------------------------------------------------
// private classes
// ----------------------------------------------------------------------------
// Define a new application type, each program should derive a class from wxApp
class MyApp : public wxApp
{
public:
// override base class virtuals
// ----------------------------
// this one is called on application startup and is a good place for the app
// initialization (doing it here and not in the ctor allows to have an error
// return: if OnInit() returns @false, the application terminates)
virtual bool OnInit();
};
// Define a new frame type: this is going to be our main frame
class MyFrame : public wxFrame
{
public:
// ctor(s)
MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
// event handlers (these functions should _not_ be virtual)
void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);
void OnDlg1(wxCommandEvent& event);
void OnDlg2(wxCommandEvent& event);
private:
// any class wishing to process wxWidgets events must use this macro
DECLARE_EVENT_TABLE()
};
// ----------------------------------------------------------------------------
// event tables and other macros for wxWidgets
// ----------------------------------------------------------------------------
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit)
EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout)
EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1)
EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2)
END_EVENT_TABLE()
IMPLEMENT_APP(MyApp)
// ----------------------------------------------------------------------------
// the application class
// ----------------------------------------------------------------------------
// 'Main program' equivalent: the program execution "starts" here
bool MyApp::OnInit()
{
wxImage::AddHandler(new wxGIFHandler);
wxXmlResource::Get()-InitAllHandlers();
wxXmlResource::Get()-Load("rc/resource.xrc");
MyFrame *frame = new MyFrame("XML resources demo",
wxPoint(50, 50), wxSize(450, 340));
frame-Show(@true);
return @true;
}
// ----------------------------------------------------------------------------
// main frame
// ----------------------------------------------------------------------------
// frame constructor
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)@NULL, -1, title, pos, size)
{
SetIcon(wxICON(appicon));
SetMenuBar(wxXmlResource::Get()-LoadMenuBar("mainmenu"));
SetToolBar(wxXmlResource::Get()-LoadToolBar(this, "toolbar"));
}
// event handlers
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
// @true is to force the frame to close
Close(@true);
}
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
wxString msg;
msg.Printf( _T("This is the about dialog of XML resources demo.\n")
_T("Welcome to %s"), wxVERSION_STRING);
wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this);
}
void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
wxXmlResource::Get()-LoadDialog(, this, "dlg1");
dlg.ShowModal();
}
void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
@@ -262,12 +262,12 @@
dlg.ShowModal();
}
@endcode
@section xrcsample XRC resource file sample
This is the XML file (resource.xrc) for the XRC sample.
@code
?xml version="1.0"?
resource version="2.3.0.1"
@@ -424,15 +424,15 @@
/object
/resource
@endcode
@section xrcfileformat XRC file format
Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets
distribution.
@section xrccppheader C++ header file generation
Using the @c -e switch together with @c -c, a C++ header file is written
containing class definitions for the GUI windows defined in the XRC file.
This code generation can make it easier to use XRC and automate program
@@ -441,13 +441,13 @@
programmer from dealing with most of the XRC specifics (e.g. @c XRCCTRL).
For each top level window defined in the XRC file a C++ class definition is
generated, containing as class members the named widgets of the window.
A default constructor for each class is also generated. Inside the constructor
all XRC loading is done and all class members representing widgets are initialized.
A default constructor for each class is also generated. Inside the constructor
all XRC loading is done and all class members representing widgets are initialized.
A simple example will help understand how the scheme works. Suppose you have
a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame (any
a XRC file defining a top level window @c TestWnd_Base, which subclasses @c wxFrame (any
other class like @c wxDialog will do also), and has subwidgets @c wxTextCtrl A and @c wxButton B.
The XRC file and corresponding class definition in the header file will be something like:
@code
?xml version="1.0"?
resource version="2.3.0.1"
@@ -469,13 +469,13 @@
/object
/object
/resource
class TestWnd_Base : public wxFrame {
protected:
wxTextCtrl* A;
wxButton* B;
private:
void InitWidgetsFromXRC(){
wxXmlResource::Get()-LoadObject(this,@NULL,"TestWnd","wxFrame");
@@ -488,110 +488,110 @@
}
};
@endcode
The generated window class can be used as basis for the full window class. The
class members which represent widgets may be accessed by name instead of using
@c XRCCTRL every time you wish to reference them (note that they are @c protected class members),
@c XRCCTRL every time you wish to reference them (note that they are @c protected class members),
though you must still use @c XRCID to refer to widget IDs in the event
table.
table.
Example:
@code
#include "resource.h"
class TestWnd : public TestWnd_Base {
public:
TestWnd(){
// A, B already initialised at this point
A-SetValue("Updated in TestWnd::TestWnd");
B-SetValue("Nice :)");
}
void OnBPressed(wxEvent& event){
Close();
}
DECLARE_EVENT_TABLE();
public:
TestWnd(){
// A, B already initialised at this point
A-SetValue("Updated in TestWnd::TestWnd");
B-SetValue("Nice :)");
}
void OnBPressed(wxEvent& event){
Close();
}
DECLARE_EVENT_TABLE();
};
BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base)
EVT_BUTTON(XRCID("B"),TestWnd::OnBPressed)
END_EVENT_TABLE()
@endcode
It is also possible to access the wxSizerItem of a sizer that is part of
a resource. This can be done using @c XRCSIZERITEM as shown. The
resource file can have something like this for a sizer item.
@code
object class="spacer" name="area"
size400, 300/size
/object
@endcode
The code can then access the sizer item by using @c XRCSIZERITEM and
@c XRCID together.
@code
wxSizerItem* item = XRCSIZERITEM(*this, "area");
@endcode
@section newresourcehandlers Adding new resource handlers
Adding a new resource handler is pretty easy.
Typically, to add an handler for the @c MyControl class, you'll want to create
the @c xh_mycontrol.h @c xh_mycontrol.cpp files.
The header needs to contains the @c MyControlXmlHandler class definition:
@code
class MyControlXmlHandler : public wxXmlResourceHandler
{
public:
// Constructor.
MyControlXmlHandler();
// Creates the control and returns a pointer to it.
virtual wxObject *DoCreateResource();
// Returns @true if we know how to create a control for the given node.
virtual bool CanHandle(wxXmlNode *node);
// Register with wxWidgets' dynamic class subsystem.
DECLARE_DYNAMIC_CLASS(MyControlXmlHandler)
};
@endcode
The implementation of your custom XML handler will typically look as:
@code
// Register with wxWidgets' dynamic class subsystem.
IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler)
MyControlXmlHandler::MyControlXmlHandler()
{
// this call adds support for all wxWindows class styles
// (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc)
AddWindowStyles();
// if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE
// you should use:
// XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE);
}
wxObject *MyControlXmlHandler::DoCreateResource()
{
// the following macro will init a pointer named "control"
// with a new instance of the MyControl class, but will NOT
// Create() it!
XRC_MAKE_INSTANCE(control, MyControl)
// this is the point where you'll typically need to do the most
// important changes: here the control is created and initialized.
// You'll want to use the wxXmlResourceHandler's getters to
// do most of your work.
// If e.g. the MyControl::Create function looks like:
//
// bool MyControl::Create(wxWindow *parent, int id,
// bool MyControl::Create(wxWindow *parent, int id,
// const wxBitmap , const wxPoint ,
// const wxBitmap , const wxPoint ,
// const wxString , const wxFont ,
@@ -623,12 +623,12 @@
GetText(wxT("the-title")),
GetFont(wxT("title-font")),
GetPosition(), GetSize(), GetStyle(), GetName());
SetupWindow(control);
return control;
}
bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
{
// this function tells XRC system that this handler can parse
@@ -636,11 +636,11 @@
return IsOfClass(node, wxT("MyControl"));
}
@endcode
You may want to check the #wxXmlResourceHandler documentation
to see how many built-in getters it contains. It's very easy to retrieve also complex structures
out of XRC files using them.
*/