@page overview_app wxApp overview
- Classes: #wxApp
+ Classes: wxApp
+
+
+ @li @ref overview_app_shutdown
+
+
+ <hr>
+
+
A wxWidgets application does not have a @e main procedure; the equivalent is the
- #OnInit member defined for a class derived from wxApp.
+ wxApp::OnInit member defined for a class derived from wxApp.
@e OnInit will usually create a top window as a bare minimum.
Unlike in earlier versions of wxWidgets, OnInit does not return a frame. Instead it
be destroyed for the application to exit, it is advisable to use parent
frames wherever possible when creating new frames, so that deleting the
top level frame will automatically delete child frames. The alternative
- is to explicitly delete child frames in the top-level frame's #wxCloseEvent
+ 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
+ In emergencies the wxExit function can be called to kill the
application however normally the application shuts down automatically,
see @ref overview_app_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 command if your program has a single
- top level window. If this behaviour is not desirable wxApp::SetExitOnFrameDelete can
- be called to change it.
+ call wxWindow::Close() in response to the @c "Exit" menu command if your program has a
+ single top level window. If this behaviour is not 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
- 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.
+ Note that 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 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 wxApp::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.
+++ /dev/null
-/////////////////////////////////////////////////////////////////////////////
-// Name: arc.h
-// Purpose: topic overview
-// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
-/////////////////////////////////////////////////////////////////////////////
-
-/*!
-
- @page overview_arc 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):
-
- @li wxZipInputStream: input stream
- @li wxZipOutputStream: output stream
- @li 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 overview_arc_generic.
-
- Also see #wxFileSystem for a higher level interface that
- can handle archive files in a generic way.
-
- The classes are designed to handle archives on both seekable streams such
- as disk files, or non-seekable streams such as pipes and sockets
- (see @ref overview_arc_noseek).
-
- See also #wxFileSystem.
-
- @li @ref overview_arc_create
- @li @ref overview_arc_extract
- @li @ref overview_arc_modify
- @li @ref overview_arc_byname
- @li @ref overview_arc_generic
- @li @ref overview_arc_noseek
-
-
- <hr>
-
-
- @section overview_arc_create Creating an archive
-
- 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 overview_arc_extract Extracting an archive
-
- #GetNextEntry() returns a pointer to entry object containing the meta-data for
- the next entry in the archive (and gives away ownership).
-
- Reading from the input stream then returns the 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_ptr<wxZipEntry> entry;
-
- wxFFileInputStream in(_T("test.zip"));
- wxZipInputStream zip(in);
-
- while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL)
- {
- // access meta-data
- wxString name = entry-GetName();
- // read 'zip' to access the entry's data
- }
- @endcode
-
-
-
- @section overview_arc_modify Modifying an archive
-
- 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
- entries using #CopyEntry().
-
- For archive types which compress entry data, CopyEntry() is likely to be
- much more efficient than transferring the data using Read() and Write()
- since it will copy them without decompressing and recompressing them.
-
- In general modifications are not possible without rewriting the archive,
- though it may be possible in some limited cases. Even then, rewriting the
- archive is usually a better choice since a failure can be handled without
- losing the whole archive. #wxTempFileOutputStream can be helpful to do this.
-
- For example to delete all entries matching the pattern "*.txt":
-
- @code
- auto_ptr<wxFFileInputStream> in(new wxFFileInputStream(_T("test.zip")));
- wxTempFileOutputStream out(_T("test.zip"));
-
- wxZipInputStream inzip(*in);
- wxZipOutputStream outzip(out);
-
- auto_ptr<wxZipEntry> 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 overview_arc_byname Looking up an archive entry by name
-
- Also see #wxFileSystem for a higher level interface that is
- more convenient for accessing archive entries by name.
-
- To open just one entry in an archive, the most efficient way is
- to simply search for it linearly by calling #GetNextEntry() until the
- required entry is found. This works both for archives on seekable and
- non-seekable streams.
-
- The format of filenames in the archive is likely to be different
- from the local filename format. For example zips and tars use
- unix style names, with forward slashes as the path separator,
- and absolute paths are not allowed. So if on Windows the file
- "C:\MYDIR\MYFILE.TXT" is stored, then when reading the entry back #GetName()
- will return "MYDIR\MYFILE.TXT". The conversion into the internal format
- and back has lost some information.
-
- 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_ptr<wxZipEntry> 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()];
- // some archive formats can have multiple entries with the same name
- // (e.g. tar) though it is an error in the case of zip
- 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
- wxFFileInputStream in2(_T("test.zip"));
- wxZipInputStream zip2(in2);
- if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end())
- zip2.OpenEntry(*it-second);
- @endcode
-
-
-
- @section overview_arc_generic Generic archive programming
-
- 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:
-
- @li wxArchiveInputStream: input stream
- @li wxArchiveOutputStream: output stream
- @li 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
- #wxArchiveClassFactory, that can create 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_ptr<wxArchiveInputStream> inarc(factory-NewStream(in));
- auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
-
- // create an empty entry object
- auto_ptr<wxArchiveEntry> 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
- compression and decompression of a single stream, such as wxGzipInputStream.
- These can be found using wxFilterClassFactory::Find().
-
- For example, to list the contents of archive @e filename:
-
- @code
- auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));
-
- if (in-IsOk())
- {
- // look for a filter handler, e.g. for '.gz'
- const wxFilterClassFactory *fcf;
- fcf = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
- if (fcf) {
- in.reset(fcf-NewStream(in.release()));
- // 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_ptr<wxArchiveInputStream> arc(acf-NewStream(in.release()));
- auto_ptr<wxArchiveEntry> entry;
-
- // list the contents of the archive
- while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL)
- std::wcout entry-GetName().c_str() "\n";
- }
- else {
- wxLogError(_T("can't handle '%s'"), filename.c_str());
- }
- }
- @endcode
-
-
-
- @section overview_arc_noseek Archives on non-seekable streams
-
- 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
- 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.
- These are not too difficult to deal with, and are outlined below.
-
- @b PutNextEntry and the entry size
- When writing archives, some archive formats store the entry size before
- the entry's data (tar has this limitation, zip doesn't). In this case
- the entry's size must be passed to #PutNextEntry() or an error occurs.
-
- This is only an issue on non-seekable streams, since otherwise the archive
- output stream can seek back and fix up the header once the size of the
- entry is known.
-
- For generic programming, one way to handle this is to supply the size
- whenever it is known, and rely on the error message from the output
- stream when the operation is not supported.
-
- @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() 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
- updates it when more meta-data becomes available. A weak reference being
- one that does not prevent you from deleting the wxArchiveEntry object - the
- input stream only attempts to update it if it is still around.
-
- The documentation for each archive entry type gives the details
- of what meta-data becomes available and when. For generic programming,
- 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:
-
- @li GetSize(): Guaranteed to be available after the entry has been read to #Eof(),
- or #CloseEntry() has been called
-
- @li 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 have read it before the output stream must write it.
-
- @b wxArchiveNotifier
- Notifier objects can be used to get a notification whenever an input
- stream updates a #wxArchiveEntry object's data
- via the weak reference mechanism.
-
- Consider the following code which renames an entry in an archive.
- This is the usual way to modify an entry's meta-data, simply set the
- required field before writing it with #CopyEntry():
-
- @code
- auto_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
- auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
- auto_ptr<wxArchiveEntry> 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
- {
- public:
- 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_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
- auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
- auto_ptr<wxArchiveEntry> 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.
-
-*/
-
--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// Name: archive.h
+// Purpose: topic overview
+// Author: wxWidgets team
+// RCS-ID: $Id$
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/*!
+
+ @page overview_arc 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):
+
+ @li wxZipInputStream: input stream
+ @li wxZipOutputStream: output stream
+ @li 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 overview_arc_generic.
+
+ Also see wxFileSystem for a higher level interface that
+ can handle archive files in a generic way.
+
+ The classes are designed to handle archives on both seekable streams such
+ as disk files, or non-seekable streams such as pipes and sockets
+ (see @ref overview_arc_noseek).
+
+ See also wxFileSystem.
+
+ @li @ref overview_arc_create
+ @li @ref overview_arc_extract
+ @li @ref overview_arc_modify
+ @li @ref overview_arc_byname
+ @li @ref overview_arc_generic
+ @li @ref overview_arc_noseek
+
+
+ <hr>
+
+
+ @section overview_arc_create Creating an archive
+
+ Call wxArchiveOutputStream::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 overview_arc_extract Extracting an archive
+
+ wxArchiveInputStream::GetNextEntry() returns a pointer to entry object containing the
+ meta-data for the next entry in the archive (and gives away ownership).
+
+ Reading from the input stream then returns the 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_ptr<wxZipEntry> entry;
+
+ wxFFileInputStream in(_T("test.zip"));
+ wxZipInputStream zip(in);
+
+ while (entry.reset(zip.GetNextEntry()), entry.get() != NULL)
+ {
+ // access meta-data
+ wxString name = entry->GetName();
+ // read 'zip' to access the entry's data
+ }
+ @endcode
+
+
+
+ @section overview_arc_modify Modifying an archive
+
+ 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
+ entries using wxArchiveOutputStream::CopyEntry().
+
+ For archive types which compress entry data, CopyEntry() is likely to be
+ much more efficient than transferring the data using Read() and Write()
+ since it will copy them without decompressing and recompressing them.
+
+ In general modifications are not possible without rewriting the archive,
+ though it may be possible in some limited cases. Even then, rewriting the
+ archive is usually a better choice since a failure can be handled without
+ losing the whole archive. wxTempFileOutputStream can be helpful to do this.
+
+ For example to delete all entries matching the pattern "*.txt":
+
+ @code
+ auto_ptr<wxFFileInputStream> in(new wxFFileInputStream(_T("test.zip")));
+ wxTempFileOutputStream out(_T("test.zip"));
+
+ wxZipInputStream inzip(*in);
+ wxZipOutputStream outzip(out);
+
+ auto_ptr<wxZipEntry> 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 overview_arc_byname Looking up an archive entry by name
+
+ Also see wxFileSystem for a higher level interface that is
+ more convenient for accessing archive entries by name.
+
+ To open just one entry in an archive, the most efficient way is
+ to simply search for it linearly by calling wxArchiveInputStream::GetNextEntry()
+ until the required entry is found. This works both for archives on seekable and
+ non-seekable streams.
+
+ The format of filenames in the archive is likely to be different
+ from the local filename format. For example zips and tars use
+ unix style names, with forward slashes as the path separator,
+ and absolute paths are not allowed. So if on Windows the file
+ "C:\MYDIR\MYFILE.TXT" is stored, then when reading the entry back
+ wxArchiveEntry::GetName() will return "MYDIR\MYFILE.TXT".
+ The conversion into the internal format and back has lost some information.
+
+ 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_ptr<wxZipEntry> 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
+ wxArchiveInputStream::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()];
+ // some archive formats can have multiple entries with the same name
+ // (e.g. tar) though it is an error in the case of zip
+ 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
+ wxFFileInputStream in2(_T("test.zip"));
+ wxZipInputStream zip2(in2);
+ if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end())
+ zip2.OpenEntry(*it->second);
+ @endcode
+
+
+
+ @section overview_arc_generic Generic archive programming
+
+ 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:
+
+ @li wxArchiveInputStream: input stream
+ @li wxArchiveOutputStream: output stream
+ @li 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
+ wxArchiveClassFactory, that can create 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_ptr<wxArchiveInputStream> inarc(factory->NewStream(in));
+ auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
+
+ // create an empty entry object
+ auto_ptr<wxArchiveEntry> 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
+ compression and decompression of a single stream, such as wxGzipInputStream.
+ These can be found using wxFilterClassFactory::Find().
+
+ For example, to list the contents of archive @e filename:
+
+ @code
+ auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));
+
+ if (in->IsOk())
+ {
+ // look for a filter handler, e.g. for '.gz'
+ const wxFilterClassFactory *fcf;
+ fcf = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+ if (fcf) {
+ in.reset(fcf->NewStream(in.release()));
+ // 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_ptr<wxArchiveInputStream> arc(acf->NewStream(in.release()));
+ auto_ptr<wxArchiveEntry> entry;
+
+ // list the contents of the archive
+ while ((entry.reset(arc->GetNextEntry())), entry.get() != NULL)
+ std::wcout << entry->GetName().c_str() << "\n";
+ }
+ else {
+ wxLogError(_T("can't handle '%s'"), filename.c_str());
+ }
+ }
+ @endcode
+
+
+
+ @section overview_arc_noseek Archives on non-seekable streams
+
+ 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
+ wxArchiveInputStream::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.
+ These are not too difficult to deal with, and are outlined below.
+
+ @subsection overview_arc_noseek_entrysize PutNextEntry and the entry size
+
+ When writing archives, some archive formats store the entry size before
+ the entry's data (tar has this limitation, zip doesn't). In this case
+ the entry's size must be passed to wxArchiveOutputStream::PutNextEntry()
+ or an error occurs.
+
+ This is only an issue on non-seekable streams, since otherwise the archive
+ output stream can seek back and fix up the header once the size of the
+ entry is known.
+
+ For generic programming, one way to handle this is to supply the size
+ whenever it is known, and rely on the error message from the output
+ stream when the operation is not supported.
+
+ @subsection overview_arc_noseek_weak 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, wxArchiveInputStream::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
+ updates it when more meta-data becomes available. A weak reference being
+ one that does not prevent you from deleting the wxArchiveEntry object - the
+ input stream only attempts to update it if it is still around.
+
+ The documentation for each archive entry type gives the details
+ of what meta-data becomes available and when. For generic programming,
+ 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:
+
+ @li wxArchiveEntry::GetSize(): guaranteed to be available after the
+ entry has been read to wxInputStream::Eof(), or wxArchiveInputStream::CloseEntry()
+ has been called
+
+ @li wxArchiveEntry::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 wxArchiveOutputStream::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 have read it before the output
+ stream must write it.
+
+ @subsection overview_arc_noseek_notifier wxArchiveNotifier
+
+ Notifier objects can be used to get a notification whenever an input
+ stream updates a wxArchiveEntry object's data via the weak reference mechanism.
+
+ Consider the following code which renames an entry in an archive.
+ This is the usual way to modify an entry's meta-data, simply set the
+ required field before writing it with wxArchiveOutputStream::CopyEntry():
+
+ @code
+ auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
+ auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
+ auto_ptr<wxArchiveEntry> 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 wxArchiveEntry::IsReadOnly(), which are not necessarily set when
+ wxArchiveInputStream::GetNextEntry() returns.
+
+ In this case a wxArchiveNotifier can be used:
+
+ @code
+ class MyNotifier : public wxArchiveNotifier
+ {
+ public:
+ void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(false); }
+ };
+ @endcode
+
+ The meta-data changes are done in your notifier's wxArchiveNotifier::OnEntryUpdated()
+ method, then wxArchiveEntry::SetNotifier() is called before CopyEntry():
+
+ @code
+ auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
+ auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
+ auto_ptr<wxArchiveEntry> 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.
+
+*/
+
@page overview_aui wxAUI overview
- Class: #wxAuiManager, #wxAuiPaneInfo
+ 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
wxAUI attempts to encapsulate the following aspects of the user interface:
- @b Frame Management:
+ @li @ref overview_aui_frame
+ @li @ref overview_aui_toolbar
+ @li @ref overview_aui_modeless
+ @li @ref overview_aui_lnf
+
+ <hr>
+
+
+ @section overview_aui_frame Frame Management
+
Frame management provides the means to open, move and hide common
controls that are needed to interact with the document, and allow these
configurations to be saved into different perspectives and loaded at a
later time.
- @b Toolbars:
+ @subsection overview_aui_toolbar Toolbars
+
Toolbars are a specialized subset of the frame management system and
should behave similarly to other docked components. However, they also
require additional functionality, such as "spring-loaded" rebar support,
"chevron" buttons and end-user customizability.
- @b Modeless Controls:
+ @subsection overview_aui_modeless Modeless Controls
+
Modeless controls expose a tool palette or set of options that float
above the application content while allowing it to be accessed. Usually
accessed by the toolbar, these controls disappear when an option is
selected, but may also be "torn off" the toolbar into a floating frame
of their own.
- @b Look and Feel:
+ @subsection overview_aui_lnf Look and Feel
+
Look and feel encompasses the way controls are drawn, both when shown
statically as well as when they are being moved. This aspect of user
interface design incorporates "special effects" such as transparent
@page overview_bitmap Bitmaps and icons overview
- Classes: #wxBitmap, #wxBitmapHandler, #wxIcon, #wxCursor.
+ 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
required.
A bitmap created dynamically or loaded from a file can be selected
- into a memory device context (instance of #wxMemoryDC). This
+ into a memory device context (instance of wxMemoryDC). This
enables the bitmap to be copied to a window or memory device context
using wxDC::Blit, or to be used as a drawing surface.
- See #wxMemoryDC for an example of drawing onto a bitmap.
+ See wxMemoryDC for an example of drawing onto a bitmap.
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
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
+ by the wxImage to load the data, and then converting
it to wxBitmap form. Note that using wxImage is the preferred way to
load images in wxWidgets, with the exception of resources (XPM-files or
native Windows resources).
whereas wxBitmap can store pixel data very differently, depending on colour
depths and platform.
- @b wxBitmap
+ @subsection overview_bitmap_supportedformats_bmp wxBitmap
+
Under Windows, wxBitmap may load the following formats:
@li Windows bitmap resource (wxBITMAP_TYPE_BMP_RESOURCE)
@li Windows bitmap file (wxBITMAP_TYPE_BMP)
@li XPM data and file (wxBITMAP_TYPE_XPM)
- @li All formats that are supported by the #wxImage class.
+ @li All formats that are supported by the wxImage class.
Under wxGTK, wxBitmap may load the following formats:
@li XPM data and file (wxBITMAP_TYPE_XPM)
- @li All formats that are supported by the #wxImage class.
+ @li All formats that are supported by the wxImage class.
Under wxMotif and wxX11, wxBitmap may load the following formats:
@li XBM data and file (wxBITMAP_TYPE_XBM)
@li XPM data and file (wxBITMAP_TYPE_XPM)
- @li All formats that are supported by the #wxImage class.
+ @li All formats that are supported by the wxImage class.
+
+ @subsection overview_bitmap_supportedformats_icon wxIcon
- @b wxIcon
Under Windows, wxIcon may load the following formats:
@li Windows icon resource (wxBITMAP_TYPE_ICO_RESOURCE)
Under wxGTK, wxIcon may load the following formats:
@li XPM data and file (wxBITMAP_TYPE_XPM)
- @li All formats that are supported by the #wxImage class.
+ @li All formats that are supported by the wxImage class.
Under wxMotif and wxX11, wxIcon may load the following formats:
@li XBM data and file (wxBITMAP_TYPE_XBM)
@li XPM data and file (wxBITMAP_TYPE_XPM)
- @li All formats that are supported by the #wxImage class.
+ @li All formats that are supported by the wxImage class.
+
+ @subsection overview_bitmap_supportedformats_cursor wxCursor
- @b wxCursor
Under Windows, wxCursor may load the following formats:
@li Windows cursor resource (wxBITMAP_TYPE_CUR_RESOURCE)
To add a handler object to wxBitmap, your application needs to include the header
which implements it, and 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.
+ @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.
*/
@page overview_bookctrl wxBookCtrl overview
- Classes: #wxNotebook, #wxListbook, #wxChoicebook, #wxTreebook, #wxToolbook
+ Classes: wxNotebook, wxListbook, wxChoicebook, wxTreebook, wxToolbook
@section overview_bookctrl_intro Introduction
displayed one page at a time. wxWidgets has five variants of this control:
@li wxNotebook: uses a row of tabs
- @li wxListbook: controlled by a #wxListCtrl
- @li wxChoicebook: controlled by a #wxChoice
- @li wxTreebook: controlled by a #wxTreeCtrl
- @li wxToolbook: controlled by a #wxToolBar
+ @li wxListbook: controlled by a wxListCtrl
+ @li wxChoicebook: controlled by a wxChoice
+ @li wxTreebook: controlled by a wxTreeCtrl
+ @li wxToolbook: controlled by a wxToolBar
- See @ref samplenotebook_overview for an example of wxBookCtrl usage.
+ See @ref page_utils_samples_notebook for an example of wxBookCtrl usage.
@section overview_bookctrl_bestbookctrl 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:
+ Currently it provides wxChoicebook for smartphones equipped with
+ WinCE, and wxNotebook for all other platforms. The mapping consists of:
@beginTable
@row2col{wxBookCtrl, wxChoicebook or wxNotebook}
@page overview_cmndlg Common dialogs overview
- Classes: #wxColourDialog, #wxFontDialog, #wxPrintDialog, #wxFileDialog,
- #wxDirDialog, #wxTextEntryDialog, #wxPasswordEntryDialog,
- #wxMessageDialog, #wxSingleChoiceDialog, #wxMultiChoiceDialog
+ Classes: wxColourDialog, wxFontDialog, wxPrintDialog, wxFileDialog,
+ wxDirDialog, wxTextEntryDialog, wxPasswordEntryDialog,
+ wxMessageDialog, wxSingleChoiceDialog, wxMultiChoiceDialog
Common dialog classes and functions encapsulate commonly-needed dialog box requirements.
They are all 'modal', grabbing the flow of control until the user dismisses the dialog,
@section overview_cmndlg_colour wxColourDialog overview
- Classes: #wxColourDialog, #wxColourData
+ Classes: wxColourDialog, wxColourData
The wxColourDialog presents a colour selector to the user, and returns
with colour information.
@section overview_cmndlg_font wxFontDialog overview
- Classes: #wxFontDialog, #wxFontData
+ Classes: wxFontDialog, wxFontData
The wxFontDialog presents a font selector to the user, and returns
with font and colour information.
@section overview_cmndlg_print wxPrintDialog overview
- Classes: #wxPrintDialog, #wxPrintData
+ Classes: wxPrintDialog, wxPrintData
This class represents the print and print setup common dialogs.
- You may obtain a #wxPrinterDC device context from
+ You may obtain a wxPrinterDC device context from
a successfully dismissed print dialog.
The samples/printing example shows how to use it: see @ref overview_printing for
@section overview_cmndlg_file wxFileDialog overview
- Classes: #wxFileDialog
+ Classes: wxFileDialog
Pops up a file selector box. In Windows and GTK2.4+, this is the common
file selector dialog. In X, this is a file selector box with somewhat less
@section overview_cmndlg_dir wxDirDialog overview
- Classes: #wxDirDialog
+ Classes: wxDirDialog
This dialog shows a directory selector dialog, allowing the user to select
a single directory.
@section overview_cmndlg_textentry wxTextEntryDialog overview
- Classes: #wxTextEntryDialog
+ Classes: wxTextEntryDialog
This is a dialog with a text entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
@section overview_cmndlg_password wxPasswordEntryDialog overview
- Classes: #wxPasswordEntryDialog
+ Classes: wxPasswordEntryDialog
This is a dialog with a password entry field. The value that the user
entered is obtained using wxTextEntryDialog::GetValue.
@section overview_cmndlg_msg wxMessageDialog overview
- Classes: #wxMessageDialog
+ Classes: wxMessageDialog
This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No.
Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.
@section overview_cmndlg_singlechoice wxSingleChoiceDialog overview
- Classes: #wxSingleChoiceDialog
+ Classes: wxSingleChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one of them. The selection can be obtained from the dialog as an index,
@section overview_cmndlg_multichoice wxMultiChoiceDialog overview
- Classes: #wxMultiChoiceDialog
+ Classes: wxMultiChoiceDialog
This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
select one or more of them.
@page overview_config wxConfig classes overview
- Classes: #wxConfig
+ Classes: wxConfigBase
This overview briefly describes what the config classes are and what they are
for. All the details about how to use them may be found in the description of
- the #wxConfigBase class and the documentation of the
+ the wxConfigBase class and the documentation of the
file, registry and INI file based implementations mentions all the
features/limitations specific to each one of these versions.
There are groups of entries and the entries themselves. Each entry contains either
a string or a number (or a boolean value; support for other types of data such as
dates or timestamps is planned) and is identified by the full path to it: something
- like /MyApp/UserPreferences/Colors/Foreground.
+ like @c /MyApp/UserPreferences/Colors/Foreground.
The previous elements in the path are the group names, and each name may
contain an arbitrary number of entries and subgroups.
The path components are @b always separated with a slash,
even though some implementations use the backslash internally. Further
details (including how to read/write these entries) may be found in
- the documentation for #wxConfigBase.
+ the documentation for wxConfigBase.
*/
@page overview_constraints Constraints overview
- Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint.
+ Classes: wxLayoutConstraints, wxIndividualLayoutConstraint.
@note Constraints are now deprecated and you should use sizers instead (see wxSizer).
constraints. To call it you can either call wxWindow::SetAutoLayout if the parent
window is a frame, panel or a dialog to tell default OnSize handlers to call Layout
automatically whenever the window size changes, or override OnSize and call
- Layout yourself (note that you do have to call #Layout yourself if the parent
+ Layout yourself (note that you do have to call wxWindow::Layout yourself if the parent
window is not a frame, panel or dialog).
@li @ref overview_constraints_layout
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));
+ 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);
+ 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);
+ 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);
+ 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);
+ 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);
+ 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);
+ frame->text_window->SetConstraints(c3);
@endcode
@code
// Create some panel items
- wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ;
+ 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);
+ 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));
+ 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);
+ 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);
+ 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);
- b3-right.SameAs (frame-panel, wxRight, 5);
- b3-bottom.SameAs (frame-panel, wxBottom, 5);
- mtext-SetConstraints(b3);
+ b3->top.Below (btn1, 5);
+ b3->left.RightOf (list, 5);
+ b3->right.SameAs (frame->panel, wxRight, 5);
+ b3->bottom.SameAs (frame->panel, wxBottom, 5);
+ mtext->SetConstraints(b3);
@endcode
*/
@page overview_container Container classes overview
- Classes: #wxList<T>, #wxArray<T>, #wxVector<T>
+ Classes: wxList<T>, wxArray<T>, wxVector<T>
wxWidgets uses itself several container classes including doubly-linked lists
and dynamic arrays (i.e. arrays which expand automatically when they become
As array classes never delete the items they contain anyhow, there is
no WX_DEFINE_ARRAY macro for them.
- Examples of usage of these macros may be found in #wxList and #wxArray documentation.
+ Examples of usage of these macros may be found in wxList and wxArray documentation.
Finally, wxWidgets predefines several commonly used container classes. wxList
is defined for compatibility with previous versions as a list containing
array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
wxArrayString. The first three store elements of corresponding types, but
wxArrayString is somewhat special: it is an optimized version of wxArray which
- uses its knowledge about #wxString reference counting schema.
+ uses its knowledge about wxString reference counting schema.
*/
@page overview_dataobject wxDataObject overview
- Classes: #wxDataObject, #wxClipboard, #wxDataFormat, #wxDropSource, #wxDropTarget
+ Classes: wxDataObject, wxClipboard, wxDataFormat, wxDropSource, wxDropTarget
- See also: @ref overview_dnd and @ref overview_samplednd
+ See also: @ref overview_dnd and @ref page_utils_samples_dnd
This overview discusses data transfer through clipboard or drag and drop.
In wxWidgets, these two ways to transfer data (either between different
clipboard support for free and vice versa.
At the heart of both clipboard and drag and drop operations lies the
- #wxDataObject class. The objects of this class (or, to
+ wxDataObject class. The objects of this class (or, to
be precise, classes derived from it) represent the data which is being carried
by the mouse during drag and drop operation or copied to or pasted from the
clipboard. wxDataObject is a "smart" piece of data because it knows which
one position to another in a word processor. Let us describe what each of them
should do.
- @li The data provider (source) duties
- @li The data receiver (target) duties
+ @li @ref overview_dataobject_source
+ @li @ref overview_dataobject_target
+
+
+ <hr>
@section overview_dataobject_source The data provider (source) duties
- The data provider is responsible for creating a #wxDataObject containing the
+ The data provider is responsible for creating a wxDataObject containing the
data to be transferred. Then it should either pass it to the clipboard using
- #SetData function or to #wxDropSource and call #DoDragDrop function.
+ wxClipboard::SetData function or to wxDropSource and call wxDropSource::DoDragDrop
+ function.
The only (but important) difference is that the object for the clipboard
transfer must always be created on the heap (i.e. using @c new) and it will
be freed by the clipboard when it is no longer needed (indeed, it is not known
in advance when, if ever, the data will be pasted from the clipboard). On the
other hand, the object for drag and drop operation must only exist while
- #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).
+ wxDropSource::DoDragDrop executes and may be safely deleted afterwards and so
+ can be created either on heap or on stack (i.e. as a local variable).
Another small difference is that in the case of clipboard operation, the
application usually knows in advance whether it copies or cuts (i.e. copies and
deletes) data - in fact, this usually depends on which menu item the user
chose. But for drag and drop it can only know it after
- #DoDragDrop returns (from its return value).
+ wxDropSource::DoDragDrop returns (from its return value).
@section overview_dataobject_target The data receiver (target) duties
To receive (paste in usual terminology) data from the clipboard, you should
- create a #wxDataObject derived class which supports the data formats you need
+ create a wxDataObject derived class which supports the data formats you need
and pass it as argument to wxClipboard::GetData. If it returns @false,
-
- no data in (any of) the supported format(s) is available. If it returns @true,
+ no data in (any of) the supported format(s) is available. If it returns @true,
the data has been successfully transferred to wxDataObject.
For drag and drop case, the wxDropTarget::OnData virtual function will be called
@page overview_datetime Date and time classes overview
- Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
+ Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
@li @ref overview_datetime_introduction
@li @ref overview_datetime_classes
@section overview_datetime_introduction Introduction
wxWidgets provides a set of powerful classes to work with dates and times. Some
- of the supported features of #wxDateTime class are:
+ of the supported features of wxDateTime class are:
@li Wide range: the range of supported dates goes from about 4714 B.C. to
some 480 million years in the future.
@section overview_datetime_classes All date/time classes at a glance
- There are 3 main classes declared in @c wx/datetime.h: except #wxDateTime itself
+ There are 3 main classes declared in @c wx/datetime.h: except wxDateTime itself
which represents an absolute moment in time, there are also two classes -
- #wxTimeSpan and #wxDateSpan - which represent the intervals of time.
+ wxTimeSpan and wxDateSpan - which represent the intervals of time.
There are also helper classes which are used together with wxDateTime:
- #wxDateTimeHolidayAuthority which is used to determine whether a given date
- is a holiday or not and #wxDateTimeWorkDays which is a derivation of this
+ wxDateTimeHolidayAuthority which is used to determine whether a given date
+ is a holiday or not and wxDateTimeWorkDays which is a derivation of this
class for which (only) Saturdays and Sundays are the holidays. See more about
- these classes in the discussion of the #holidays.
+ these classes in the discussion of the holidays (see @ref overview_datetime_holidays).
Finally, in other parts of this manual you may find mentions of wxDate and
wxTime classes. @ref overview_datetime_compat are obsolete and
@section overview_datetime_characteristics wxDateTime characteristics
- #wxDateTime stores the time as a signed number of
+ wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
however this is not visible to the class users (in particular, dates prior to
the Epoch are handled just as well (or as bad) as the dates after it). But it
Finally, the internal representation is time zone independent (always in GMT)
and the time zones only come into play when a date is broken into
- year/month/day components. See more about #timezones below.
+ year/month/day components. See more about timezones below
+ (see @ref overview_datetime_timezones).
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
describe a time interval.
First, there is the direct and self-explaining way implemented by
- #wxTimeSpan: it is just a difference in milliseconds
+ wxTimeSpan: it is just a difference in milliseconds
between two moments in time. Adding or subtracting such an interval to
wxDateTime is always well-defined and is a fast operation.
the year is leap or not).
This is why there is another class for representing such intervals called
- #wxDateSpan. It handles these sort of operations in the
+ 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
month': this will give Feb 28 (or 29), i.e. the last day of February and not
In this (rare) case, you are still limited to the local time zone when
constructing wxDateTime objects, i.e. there is no way to construct a
wxDateTime corresponding to the given date in, say, Pacific Standard Time.
- To do it, you will need to call #ToTimezone or #MakeTimezone methods to adjust
- the date for the target time zone. There are also special versions of these functions
- #ToUTC and #MakeUTC for the most common case - when the date should be constructed in UTC.
+ To do it, you will need to call wxDateTime::ToTimezone or wxDateTime::MakeTimezone
+ methods to adjust the date for the target time zone. There are also special
+ versions of these functions wxDateTime::ToUTC and wxDateTime::MakeUTC for
+ the most common case - when the date should be constructed in UTC.
You also can just retrieve the value for some time zone without converting the
object to it first. For this you may pass TimeZone argument to any of the
(any information about other ones appreciated!) and even for them the rules
may perfectly well change in the future.
- The time zone handling #methods use these functions
- too, so they are subject to the same limitations.
+ The time zone handling methods (see @ref overview_datetime_timezones) use
+ these functions too, so they are subject to the same limitations.
@page overview_dc Device context overview
- Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
- #wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxScreenDC, #wxClientDC,
- #wxPaintDC, #wxWindowDC.
+ Classes: wxBufferedDC, wxBufferedPaintDC, wxDC, wxPostScriptDC,
+ wxMetafileDC, wxMemoryDC, wxPrinterDC, wxScreenDC, wxClientDC,
+ wxPaintDC, wxWindowDC.
A wxDC is a @e device context onto which graphics and text can be drawn.
The device context is intended to represent a number of output devices in a
generic way, with the same API being used throughout.
Some device contexts are created temporarily in order to draw on a window.
- This is @true of #wxScreenDC, #wxClientDC, #wxPaintDC, and #wxWindowDC.
+ This is @true of wxScreenDC, wxClientDC, wxPaintDC, and wxWindowDC.
The following describes the differences between these device contexts and
when you should use them.
@li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
@li @b wxClientDC. Use this to paint on the client area of window (the part without
- borders and other decorations), but do not use it from within an #wxPaintEvent.
+ borders and other decorations), but do not use it from within an wxPaintEvent.
@li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
- within a #wxPaintEvent.
+ within a wxPaintEvent.
@li @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
This may not be available on non-Windows platforms.
@page overview_debugging Debugging overview
- Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
- @ref overview_logfunctions, @ref overview_debugmacros
+ Classes, functions and macros: wxDebugContext, wxObject, wxLog,
+ @ref overview_logfunctions, @ref overview_debugmacros
Various classes, functions and macros are provided in wxWidgets to help you debug
your application. Most of these are only available if you compile both wxWidgets,
@section overview_debugging_dbgctx wxDebugContext
- #wxDebugContext is a class that never gets instantiated, but ties together
+ wxDebugContext is a class that never gets instantiated, but ties together
various static functions and variables. It allows you to dump all objects to that stream,
write statistics about object allocation, and check memory for errors.
@section overview_debugging_dbgctx2 wxDebugContext overview
- Class: #wxDebugContext
+ Class: wxDebugContext
wxDebugContext is a class for performing various debugging and memory tracing operations.
@page overview_dialog wxDialog overview
- Classes: #wxDialog, #wxDialogLayoutAdapter
+ Classes: wxDialog, wxDialogLayoutAdapter
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
For a set of dialog convenience functions, including file selection, see
@ref overview_dialogfunctions.
- See also #wxTopLevelWindow and #wxWindow for inherited
+ See also wxTopLevelWindow and wxWindow for inherited
member functions. Validation of data in controls is covered in @ref overview_validator.
imperative for wxWidgets applications to adapt to these platforms without putting
too much burden on the programmer. One area where wxWidgets can help is in adapting
dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
- wxDialog therefore supplies a global #wxDialogLayoutAdapter class that implements
+ wxDialog therefore supplies a global wxDialogLayoutAdapter class that implements
automatic scrolling adaptation for most sizer-based custom dialogs.
Many applications should therefore be able to adapt to small displays with little
@li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
the pages are made scrollable and no other adaptation is done.
- @li wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
- @li If that search failed, wxWidgets looks for a horizontal #wxBoxSizer with one or more
+ @li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the non-scrolling part.
+ @li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one or more
standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
- and adds them to a #wxStdDialogButtonSizer.
+ and adds them to a wxStdDialogButtonSizer.
If no standard buttons were found, the whole dialog content will scroll.
- @li All the children apart from standard buttons are reparented onto a new #wxScrolledWindow
+ @li All the children apart from standard buttons are reparented onto a new wxScrolledWindow
object, using the old top-level sizer for the scrolled window and creating a new top-level
sizer to lay out the scrolled window and standard button sizer.
You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
treated as standard buttons for the non-scrolling area.
- You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
+ You can derive your own class from wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
and perform the adaptation.
You can help make sure that your dialogs will continue to function after adaptation by:
@li avoiding the above situations and assumptions;
- @li using #wxStdDialogButtonSizer;
+ @li using wxStdDialogButtonSizer;
@li only making assumptions about hierarchy immediately after the dialog is created;
@li using an intermediate sizer under the main sizer, a @false top-level sizer that
can be relied on to exist for the purposes of manipulating child sizers and windows;
@page overview_dnd Drag and drop overview
- Classes: #wxDataObject, #wxTextDataObject, #wxDropSource, #wxDropTarget,
- #wxTextDropTarget, #wxFileDropTarget
+ Classes: wxDataObject, wxTextDataObject, wxDropSource, wxDropTarget,
+ wxTextDropTarget, wxFileDropTarget
Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order
to use drag and drop in wxWidgets.
- See also: @ref overview_dataobject and @ref samplednd_overview.
+ See also: @ref overview_dataobject and @ref page_utils_samples_dnd.
It may be noted that data transfer to and from the clipboard is quite
similar to data transfer with drag and drop and the code to implement
these two types is almost the same. In particular, both data transfer
- mechanisms store data in some kind of #wxDataObject and identify its format(s)
- using the #wxDataFormat class.
+ mechanisms store data in some kind of wxDataObject and identify its format(s)
+ using the wxDataFormat class.
To be a @e drag source, i.e. to provide the data which may be dragged by
the user elsewhere, you should implement the following steps:
@endcode
@li @b Dragging: The call to DoDragDrop() blocks the program until the user releases
- the mouse button (unless you override the #GiveFeedback function to do something
- special). When the mouse moves in a window of a program which understands the
- same drag-and-drop protocol (any program under Windows or any program supporting
- the XDnD protocol under X Windows), the corresponding #wxDropTarget methods
+ the mouse button (unless you override the wxDropSource::GiveFeedback function to
+ do something special). When the mouse moves in a window of a program which understands
+ the same drag-and-drop protocol (any program under Windows or any program supporting
+ the XDnD protocol under X Windows), the corresponding wxDropTarget methods
are called - see below.
@li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which
- is one of the values of @c wxDragResult enum (explained #here):
+ is one of the values of @c wxDragResult enum (explained in wxDropTarget page):
@code
switch (result)
follow the instructions below:
@li @b Initialization: For a window to be a drop target, it needs to have
- an associated #wxDropTarget object. Normally, you will call wxWindow::SetDropTarget
- during window creation associating your drop target with it. You must derive a class from
- wxDropTarget and override its pure virtual methods. Alternatively, you may
- derive from #wxTextDropTarget or #wxFileDropTarget and override their OnDropText()
+ an associated wxDropTarget object. Normally, you will call wxWindow::SetDropTarget
+ during window creation associating your drop target with it. You must derive a class
+ from wxDropTarget and override its pure virtual methods. Alternatively, you may
+ derive from wxTextDropTarget or wxFileDropTarget and override their OnDropText()
or OnDropFiles() method.
@li @b Drop: When the user releases the mouse over a window, wxWidgets
asks the associated wxDropTarget object if it accepts the data. For this,
- a #wxDataObject must be associated with the drop target and this data object will
+ 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.
+ If all goes well, then wxDropTarget::OnData will get called and the wxDataObject belonging
+ to the drop target can get filled with data.
@li <b>The end</b>: After processing the data, DoDragDrop() returns either
wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift
@page overview_docview Document/view overview
- Classes: #wxDocument, #wxView, #wxDocTemplate, #wxDocManager, #wxDocParentFrame,
- #wxDocChildFrame, #wxDocMDIParentFrame, #wxDocMDIChildFrame,
- #wxCommand, #wxCommandProcessor
+ Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame,
+ wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame,
+ wxCommand, wxCommandProcessor
The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application.
@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
or a command history editor.
- @li Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
+ @li Override wxView::OnCreatePrintout to create an instance of a derived wxPrintout
class, to provide multi-page document facilities.
@li Override wxDocManager::SelectDocumentPath to provide a different file selector.
@li Limit the maximum number of open documents and the maximum number of undo commands.
@section overview_docview_wxdoc wxDocument overview
- Class: #wxDocument
+ Class: wxDocument
The wxDocument class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocTemplate and #wxDocManager classes.
+ and cooperates with the wxView, wxDocTemplate and wxDocManager classes.
Using this framework can save a lot of routine user-interface programming,
since a range of menu commands -- such as open, save, save as -- are supported
automatically.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create document objects on demand. When you create
- a #wxDocTemplate object on application initialization, you
+ a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
@section overview_docview_wxview wxView overview
- Class: #wxView
+ Class: wxView
The wxView class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework
- supported by wxWidgets, and cooperates with the #wxDocument, #wxDocTemplate
- and #wxDocManager classes.
+ supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
+ and wxDocManager classes.
See the example application in @c samples/docview.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create view objects on demand. When you create
- a #wxDocTemplate object on application initialization, you
+ a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
@section overview_docview_wxdoctemplate wxDocTemplate overview
- Class: #wxDocTemplate
+ Class: wxDocTemplate
The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document
simplified.
wxDocTemplate is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocument and #wxDocManager classes.
+ and cooperates with the wxView, wxDocument and wxDocManager classes.
See the example application in @c samples/docview.
@section overview_docview_wxdocmanager wxDocManager overview
- Class: #wxDocManager
+ Class: wxDocManager
The wxDocManager class is part of the document/view framework supported by wxWidgets,
- and cooperates with the #wxView, #wxDocument and #wxDocTemplate classes.
+ and cooperates with the wxView, wxDocument and wxDocTemplate classes.
A wxDocManager instance coordinates documents, views and document templates.
It keeps a list of document and template instances, and much functionality is routed
@section overview_docview_wxcommand wxCommand overview
- Classes: #wxCommand, #wxCommandProcessor
+ Classes: wxCommand, wxCommandProcessor
wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
as an object which can be manipulated by a framework or application.
When a user interface event occurs, the application @e submits a command
- to a #wxCommandProcessor object to execute and store.
+ to a wxCommandProcessor object to execute and store.
The wxWidgets document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses
@section overview_docview_wxcommandproc wxCommandProcessor overview
- Classes: #wxCommandProcessor, #wxCommand
+ 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
@section overview_docview_filehistory wxFileHistory overview
- Classes: #wxFileHistory, #wxDocManager
+ Classes: wxFileHistory, wxDocManager
wxFileHistory encapsulates functionality to record the last few files visited, and
to allow the user to quickly load these files using the list appended to the File menu.
Please notice that currently if the history already contained filenames when UseMenu()
is called (e.g. when initializing a second MDI child frame), the menu is not automatically
initialized with the existing filenames in the history and so you need to call
- #AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
+ wxFileHistory::AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9.
@page overview_eventhandling Event handling overview
- Classes: #wxEvtHandler, #wxWindow, #wxEvent
+ Classes: wxEvtHandler, wxWindow, wxEvent
@li @ref overview_eventhandling_introduction
@li @ref overview_eventhandling_processing
member function in a derived class will not have any effect. These member
functions take an event argument, and the class of event differs according to
the type of event and the class of the originating window. For size events,
- #wxSizeEvent is used. For menu commands and most control commands
- (such as button presses), #wxCommandEvent is used. When controls get more
- complicated, then specific event classes are used, such as #wxTreeEvent for
- events from #wxTreeCtrl windows.
+ wxSizeEvent is used. For menu commands and most control commands
+ (such as button presses), wxCommandEvent is used. When controls get more
+ complicated, then specific event classes are used, such as wxTreeEvent for
+ events from wxTreeCtrl windows.
As well as the event table in the implementation file, there must also be a
DECLARE_EVENT_TABLE macro somewhere in the class declaration. For example:
Finally, if you don't like using macros for static initialization of the event
tables you may also use wxEvtHandler::Connect to
connect the events to the handlers dynamically, during run-time. See the
- @ref sampleevent_overview for an example of doing it.
+ @ref page_utils_samples_event for an example of doing it.
To summarize, instead of explicitly calling the base class version as you
would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),
- you should instead call #Skip.
+ you should instead call wxEvent::Skip.
In practice, this would look like this if the derived text control only
accepts 'a' to 'z' and 'A' to 'Z':
@li If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
the function skips to step (6).
@li If the object is a wxWindow, @b ProcessEvent is recursively called on the window's
- #wxValidator. If this returns @true, the function exits.
+ wxValidator. If this returns @true, the function exits.
@li @b SearchEventTable is called for this event handler. If this fails, the base
class table is tried, and so on until no more tables exist or an appropriate
function was found, in which case the function exits.
may be very difficult, if not impossible, to track down all the dialogs which
may be popped up in a complex program (remember that some are created
automatically by wxWidgets). If you need to specify a different behaviour for
- some reason, you can use #SetExtraStyle(wxWS_EX_BLOCK_EVENTS)
+ some reason, you can use wxWindow::SetExtraStyle(wxWS_EX_BLOCK_EVENTS)
explicitly to prevent the events from being propagated beyond the given window
or unset this flag for the dialogs which have it on by default.
handler in the library itself. As this quite often causes confusion for users,
here is a list of system events which will NOT get sent to the parent's event handler:
- @li #wxEvent: The event base class
- @li #wxActivateEvent: A window or application activation event
- @li #wxCloseEvent: A close window or end session event
- @li #wxEraseEvent: An erase background event
- @li #wxFocusEvent: A window focus event
- @li #wxKeyEvent: A keypress event
- @li #wxIdleEvent: An idle event
- @li #wxInitDialogEvent: A dialog initialisation event
- @li #wxJoystickEvent: A joystick event
- @li #wxMenuEvent: A menu event
- @li #wxMouseEvent: A mouse event
- @li #wxMoveEvent: A move event
- @li #wxPaintEvent: A paint event
- @li #wxQueryLayoutInfoEvent: Used to query layout information
- @li #wxSetCursorEvent: Used for special cursor processing based on current mouse position
- @li #wxSizeEvent: A size event
- @li #wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
- @li #wxSysColourChangedEvent: A system colour change event
+ @li wxEvent: The event base class
+ @li wxActivateEvent: A window or application activation event
+ @li wxCloseEvent: A close window or end session event
+ @li wxEraseEvent: An erase background event
+ @li wxFocusEvent: A window focus event
+ @li wxKeyEvent: A keypress event
+ @li wxIdleEvent: An idle event
+ @li wxInitDialogEvent: A dialog initialisation event
+ @li wxJoystickEvent: A joystick event
+ @li wxMenuEvent: A menu event
+ @li wxMouseEvent: A mouse event
+ @li wxMoveEvent: A move event
+ @li wxPaintEvent: A paint event
+ @li wxQueryLayoutInfoEvent: Used to query layout information
+ @li wxSetCursorEvent: Used for special cursor processing based on current mouse position
+ @li wxSizeEvent: A size event
+ @li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
+ @li wxSysColourChangedEvent: A system colour change event
In some cases, it might be desired by the programmer to get a certain number
of system events in a parent window, for example all key events sent to, but not
@section overview_eventhandling_prog Events generated by the user vs programmatically generated events
- While generically #wxEvents can be generated both by user
- actions (e.g. resize of a #wxWindow) and by calls to functions
- (e.g. wxWindow::SetSize), wxWidgets controls normally send #wxCommandEvent-derived
+ While generically wxEvents can be generated both by user
+ actions (e.g. resize of a wxWindow) and by calls to functions
+ (e.g. wxWindow::SetSize), wxWidgets controls normally send wxCommandEvent-derived
events only for the user-generated events. The only @b exceptions to this rule are:
@li wxNotebook::AddPage: No event-free alternatives
@li wxTreeCtrl::Delete: No event-free alternatives
@li wxTreeCtrl::DeleteAllItems: No event-free alternatives
@li wxTreeCtrl::EditLabel: No event-free alternatives
- @li All #wxTextCtrl methods
+ @li All wxTextCtrl methods
wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other
- functions, such as #Replace or #WriteText don't have event-free equivalents.
+ functions, such as wxTextCtrl::Replace or wxTextCtrl::WriteText don't have event-free
+ equivalents.
In order to define a new event type, there are principally two choices.
One is to define a entirely new event class (typically deriving from
- #wxEvent or #wxCommandEvent.
+ wxEvent or wxCommandEvent.
The other is to use the existing event classes and give them an new event
type. You'll have to define and declare a new event type using either way,
You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro
since it is used only for backwards compatibility with wxWidgets 2.0.x based
applications where you have to give the event type ID an explicit value.
- See also the @ref sampleevent_overview for an example of code
+ See also the @ref page_utils_samples_event for an example of code
defining and working with the custom event types.
@subsection overview_eventhandling_custom_existing Using existing event classes
- If you just want to use a #wxCommandEvent with
+ If you just want to use a wxCommandEvent with
a new event type, you can then use one of the generic event table macros
listed below, without having to define a new macro yourself. This also
has the advantage that you won't have to define a new wxEvent::Clone()
class wxPlotEvent: public wxNotifyEvent
{
public:
- wxPlotEvent( wxEventType commandType = wxEVT_@NULL, int id = 0 );
+ wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );
// accessors
wxPlotCurve *GetCurve()
#define EVT_PLOT(id, fn) \
DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \
(wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \
- wxStaticCastEvent( wxPlotEventFunction, & fn ), (wxObject *) @NULL ),
+ wxStaticCastEvent( wxPlotEventFunction, & fn ), (wxObject *) NULL ),
// code implementing the event type and the event class
// user code intercepting the event
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
- EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)
+ EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)
END_EVENT_TABLE()
void MyFrame::OnPlot( wxPlotEvent )
wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() );
event.SetEventObject( this );
event.SetCurve( m_curve );
- GetEventHandler()-ProcessEvent( event );
+ GetEventHandler()->ProcessEvent( event );
}
@endcode
library code wasn't exception-safe and so an exception propagating through it
could result in memory and/or resource leaks, and also not very convenient.
- Starting from the version 2.5.1 wxWidgets becomes more exception-friendly. It
- still doesn't use the exceptions by itself but it should be now safe to use the
+ wxWidgets is exception-friendly.
+ It 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.
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 wxApp::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
+ called, so if you need you should override wxApp::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
- #OnInit() and/or #OnExit() as well.
+ wxApp::OnInit() and/or wxApp::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 wxApp::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.
@page overview_file File classes and functions overview
- Classes: #wxFile, #wxDir, #wxTempFile, #wxTextFile
+ Classes: wxFile, wxDir, wxTempFile, wxTextFile
Functions: see @ref filefunctions_overview.
wxWidgets provides some functions and classes to facilitate working with files.
As usual, the accent is put on cross-platform features which explains, for
- example, the #wxTextFile class which may be used to convert
+ example, the wxTextFile class which may be used to convert
between different types of text files (DOS/Unix/Mac).
wxFile may be used for low-level IO. It contains all the usual functions to work
with files (opening/closing, reading/writing, seeking, and so on) but compared with
using standard C functions, has error checking (in case of an error a message
- is logged using #wxLog facilities) and closes the file
+ is logged using wxLog facilities) and closes the file
automatically in the destructor which may be quite convenient.
wxTempFile is a very small file designed to make replacing the files contents
- safer - see its #documentation for more details.
+ safer - see its documentation for more details.
wxTextFile is a general purpose class for working with small text files on line
by line basis. It is especially well suited for working with configuration files
Three classes are used in order to provide virtual file systems mechanism:
- @li The #wxFSFile class provides information
+ @li The wxFSFile class provides information
about opened file (name, input stream, mime type and anchor).
- @li The #wxFileSystem class is the interface.
+ @li The wxFileSystem class is the interface.
Its main methods are ChangePathTo() and OpenFile(). This class
is most often used by the end user.
- @li The #wxFileSystemHandler is the core
+ @li The wxFileSystemHandler is the core
of virtual file systems mechanism. You can derive your own handler and pass
it to 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
@page overview_font wxFont overview
- Class: #wxFont, #wxFontDialog
+ 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
a default typeface will chosen based on the family.}
@itemdef{Encoding,
The font encoding (see @b wxFONTENCODING_XXX
- constants and the @ref fontencoding_overview for more
- details)}
+ constants and the @ref overview_fontencoding for more details)}
@endDefList
Specifying a family, rather than a specific typeface name, ensures a degree of
current mapping mode. However, user scaling on a device context will also
scale fonts under both environments.
+ @li @ref overview_font_nativeinfo
+
+
+ <hr>
@section overview_font_nativeinfo 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
+ 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.
used almost universally now to represent the letters of the English alphabet
and some other common characters. However, it is not enough to represent the
letters of foreign alphabets and here other encodings come into play. Please
- note that we will only discuss 8-bit fonts here and not #Unicode.
+ note that we will only discuss 8-bit fonts here and not Unicode
+ (see @ref overview_unicode).
Font encoding support is ensured by several classes:
- #wxFont itself, but also #wxFontEnumerator and
- #wxFontMapper. wxFont encoding support is reflected by
- a (new) constructor parameter @e encoding which takes one of the following
- values (elements of enumeration type @c wxFontEncoding):
+ wxFont itself, but also wxFontEnumerator and wxFontMapper. wxFont encoding
+ support is reflected by a (new) constructor parameter @e encoding which takes
+ one of the following values (elements of enumeration type @c wxFontEncoding):
@beginDefList
@itemdef{wxFONTENCODING_SYSTEM,
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
- #wxFontEnumerator will never return one, even if
- the user has installed a KOI8 font on his system.
+ wxFontEnumerator will never return one, even if the user has installed a KOI8
+ font on his system.
- To solve this problem, a #wxFontMapper class is provided.
+ To solve this problem, a wxFontMapper class is provided.
This class stores the mapping between the encodings and the font face
- names which support them in #wxConfig object. Of
+ names which support them in wxConfig object. Of
course, it would be fairly useless if it tried to determine these mappings by
itself, so, instead, it (optionally) asks the user and remembers his answers
so that the next time the program will automatically choose the correct font.
- All these topics are illustrated by the @ref samplefont_overview;
+ All these topics are illustrated by the @ref page_utils_samples_font;
please refer to it and the documentation of the classes mentioned here for
further explanations.
@page overview_grid wxGrid classes overview
- Classes: #wxGrid
+ Classes: wxGrid
@li @ref overview_grid_intro
@li @ref overview_grid_simpleexample
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 class which allows you to use
+ 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
First of all, you must include @c wx/wxhtml.h.
- Class #wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents.
+ Class wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents.
It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::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"
+ mywin -> LoadPage("test.htm");
+ mywin -> SetPage("htmlbody"
"h1Error/h1"
"Some error occurred :-H)"
"/body/hmtl");
@subsection overview_html_quickstart_disphelp Displaying Help
- See #wxHtmlHelpController.
+ See wxHtmlHelpController.
@subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
@code
html = new wxHtmlWindow(this);
- html - SetRelatedFrame(this, "HTML : %%s");
- html - SetRelatedStatusBar(0);
+ html -> SetRelatedFrame(this, "HTML : %%s");
+ html -> SetRelatedStatusBar(0);
@endcode
The first command associates the HTML object with its parent frame
@section overview_html_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 @ref htmleasyprinting_overview.
+ The easiest way to print an HTML document is to use @ref overview_htmleasyprinting.
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
- #wxHtmlPrintout, normal wxWidgets printout class.
+ wxHtmlPrintout, normal wxWidgets printout class.
- And finally there is the low level class #wxHtmlDCRenderer which you can use to
+ 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
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 @true in your tex2rtf.ini file.
- (See #wxHtmlHelpController for help controller description.)
+ (See wxHtmlHelpController for help controller description.)
A @b book consists of three files: the header file, the contents file
and the index file.
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
+ To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter and
register it using wxHtmlWindow::AddFilter.
@section overview_html_cells Cells and Containers
- This article describes mechanism used by #wxHtmlWinParser and
- #wxHtmlWindow to parse and display HTML documents.
+ This article describes mechanism used by wxHtmlWinParser and
+ wxHtmlWindow to parse and display HTML documents.
@subsection overview_html_cells_cells Cells
fragments @b cells. Cell is for example one word, horizontal line, image
or any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers).
- See #wxHtmlCell.
+ See wxHtmlCell.
@subsection overview_html_cells_containers 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, wxHtmlCell::Layout.
+ See wxHtmlContainerCell, wxHtmlCell::Layout.
This image shows the cells and containers: @image html contbox.bmp
@subsection overview_html_cells_conttaghandler Using Containers in Tag Handler
- #wxHtmlWinParser provides a user-friendly way of managing containers.
+ 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.
+ Use wxHtmlWinParser::OpenContainer to open new 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 container. This doesn't create a new container
- with same depth level but it returns "control" to the parent container.
+ Use wxHtmlWinParser::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: @image html cont.bmp
There clearly must be same number of calls to OpenContainer as to
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).
+ OpenContainer and CloseContainer calls should be same within
+ wxHtmlTagHandler::HandleTag's body).
Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
of adding text to the parser directly.
Tag handler is class that understands particular HTML tag (or tags) and is
able to interpret it.
- #wxHtmlWinParser has a static table of @b modules.
+ wxHtmlWinParser has a static table of @b modules.
Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
object is constructed all modules are scanned and handlers are added
to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
@subsection overview_html_handlers_howworks How it works
- Common tag handler's #HandleTag method works in four steps:
+ Common tag handler's wxHtmlTagHandler::HandleTag method works in four steps:
@li Save state of parent parser into local variables
@li Change parser state according to tag's params
@li Parse text between the tag and paired ending tag (if present)
@li Restore original parser state
- See #wxHtmlWinParser for methods for modifying parser's state.
+ See wxHtmlWinParser for methods for modifying parser's state.
In general you can do things like opening/closing containers, changing colors, fonts etc.
@subsection overview_html_handlers_custom Providing own tag handlers
@subsection overview_html_handlers_tag Tag handlers
- The handler is derived from #wxHtmlWinTagHandler (or directly from #wxHtmlTagHandler).
+ The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler).
You can use set of macros to define the handler (see src/html/m_*.cpp files
for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro
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 #GetSupportedTags method.
+ wxHtmlWinTagHandler and implements it is wxHtmlTagHandler::GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
@li @b TAG_HANDLER_VARS:
Never used in wxHTML :-)
@li @b TAG_HANDLER_PROC(@e varib):
- This is very important macro. It defines #HandleTag
+ This is very important macro. It defines wxHtmlTagHandler::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 } !
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.
+ wxHtmlTagsModule and to create instance of it.
See macros reference:
projects / wxWidgets.git / commitdiff
