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

fixing the topic overviews

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51979 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-02-21 21:46:03 +00:00
parent 378cb81280
commit e0a4791892
6 changed files with 318 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
docs/doxygen/mainpages/topics.h
View File

@@ -27,81 +27,81 @@
@section page_topics_starting Starting with wxWidgets @section page_topics_starting Starting with wxWidgets
@li @subpage referencenotes_overview @li @subpage overview_referencenotes
@li @subpage roughguide_overview @li @subpage overview_roughguide
@li @subpage helloworld_overview @li @subpage overview_helloworld
@li @subpage samples_overview @li @subpage overview_samples
@li @subpage python_overview @li @subpage overview_python
@section page_topics_programming Programming with wxWidgets @section page_topics_programming Programming with wxWidgets
@li @subpage backwardcompatibility_overview @li @subpage overview_backwardcompat
@li @subpage runtimeclass_overview @li @subpage overview_runtimeclass
@li @subpage trefcount_overview @li @subpage overview_trefcount
@li @subpage app_overview @li @subpage overview_app
@li @subpage unicode_overview @li @subpage overview_unicode
@li @subpage mbconvclasses_overview @li @subpage overview_mbconvclasses
@li @subpage internationalization_overview @li @subpage overview_internationalization
@li @subpage nonenglish_overview @li @subpage overview_nonenglish
@li @subpage debugging_overview @li @subpage overview_debugging
@li @subpage log_overview @li @subpage overview_log
@li @subpage eventhandling_overview @li @subpage overview_eventhandling
@li @subpage exceptions_overview @li @subpage overview_exceptions
@li @subpage windowstyles_overview @li @subpage overview_windowstyles
@li @subpage windowdeletion_overview @li @subpage overview_windowdeletion
@li @subpage windowids_overview @li @subpage overview_windowids
@li @subpage envvars_overview @li @subpage overview_envvars
@section page_topics_nongui Overviews of non-GUI classes @section page_topics_nongui Overviews of non-GUI classes
@li @subpage string_overview @li @subpage overview_string
@li @subpage bufferclasses_overview @li @subpage overview_bufferclasses
@li @subpage datetime_overview @li @subpage overview_datetime
@li @subpage container_overview @li @subpage overview_container
@li @subpage file_overview @li @subpage overview_file
@li @subpage stream_overview @li @subpage overview_stream
@li @subpage thread_overview @li @subpage overview_thread
@li @subpage config_overview @li @subpage overview_config
@li @subpage fs_overview @li @subpage overview_fs
@li @subpage resyn_overview @li @subpage overview_resyn
@li @subpage arc_overview @li @subpage overview_arc
@li @subpage ipc_overview @li @subpage overview_ipc
@section page_topics_drawing Drawing related classes @section page_topics_drawing Drawing related classes
@li @subpage dc_overview @li @subpage overview_dc
@li @subpage bitmap_overview @li @subpage overview_bitmap
@li @subpage font_overview @li @subpage overview_font
@li @subpage fontencoding_overview @li @subpage overview_fontencoding
@li @subpage printing_overview @li @subpage overview_printing
@li @subpage unixprinting_overview @li @subpage overview_unixprinting
@section page_topics_gui Overviews of GUI classes @section page_topics_gui Overviews of GUI classes
@li @subpage sizer_overview @li @subpage overview_sizer
@li @subpage xrc_overview @li @subpage overview_xrc
@li @subpage windowsizing_overview @li @subpage overview_windowsizing
@li @subpage scrolling_overview @li @subpage overview_scrolling
@li @subpage dialog_overview @li @subpage overview_dialog
@li @subpage validator_overview @li @subpage overview_validator
@li @subpage dataobject_overview @li @subpage overview_dataobject
@li @subpage dnd_overview @li @subpage overview_dnd
@li @subpage constraints_overview @li @subpage overview_constraints
@section page_topics_indivctrl Overviews of individual controls @section page_topics_indivctrl Overviews of individual controls
@li @subpage html_overview @li @subpage overview_html
@li @subpage richtextctrl_overview @li @subpage overview_richtextctrl
@li @subpage aui_overview @li @subpage overview_aui
@li @subpage commondialogs_overview @li @subpage overview_commondialogs
@li @subpage toolbar_overview @li @subpage overview_toolbar
@li @subpage grid_overview @li @subpage overview_grid
@li @subpage treectrl_overview @li @subpage overview_treectrl
@li @subpage listctrl_overview @li @subpage overview_listctrl
@li @subpage splitterwindow_overview @li @subpage overview_splitterwindow
@li @subpage imagelist_overview @li @subpage overview_imagelist
@li @subpage bookctrl_overview @li @subpage overview_bookctrl
@li @subpage tips_overview @li @subpage overview_tips
@li @subpage docview_overview @li @subpage overview_docview
*/ */

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: app // Name: app.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,27 +8,31 @@
/*! /*!
@page app_overview wxApp overview @page overview_app wxApp overview
Classes: #wxApp Classes: #wxApp
A wxWidgets application does not have a @e main procedure; the equivalent is the A wxWidgets application does not have a @e main procedure; the equivalent is the
#OnInit member defined for a class derived from wxApp. #OnInit member defined for a class derived from wxApp.
@e OnInit will usually create a top window as a bare minimum. @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 Unlike in earlier versions of wxWidgets, OnInit does not return a frame. Instead it
returns a boolean value which indicates whether processing should continue (@true) or not (@false). returns a boolean value which indicates whether processing should continue (@true)
You call wxApp::SetTopWindow to let wxWidgets know or not (@false). You call wxApp::SetTopWindow to let wxWidgets know about the top window.
about the top window.
Note that the program's command line arguments, represented by @e argc Note that the program's command line arguments, represented by @e argc
and @e argv, are available from within wxApp member functions. and @e argv, are available from within wxApp member functions.
An application closes by destroying all windows. Because all frames must An application closes by destroying all windows. Because all frames must
be destroyed for the application to exit, it is advisable to use parent be destroyed for the application to exit, it is advisable to use parent
frames wherever possible when creating new frames, so that deleting the frames wherever possible when creating new frames, so that deleting the
top level frame will automatically delete child frames. The alternative 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. 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, application however normally the application shuts down automatically,
@ref appshutdown_overview. see @ref overview_app_shutdown.
An example of defining an application follows: An example of defining an application follows:
@code @code
@@ -51,37 +55,37 @@
} }
@endcode @endcode
Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically create an instance of the application object Note the use of IMPLEMENT_APP(appClass), which allows wxWidgets to dynamically create
at the appropriate point in wxWidgets initialization. Previous versions of wxWidgets used an instance of the application object at the appropriate point in wxWidgets initialization.
to rely on the creation of a global application object, but this is no longer recommended, Previous versions of wxWidgets used to rely on the creation of a global application object,
because required global initialization may not have been performed at application object but this is no longer recommended, because required global initialization may not have
construction time. been performed at application object construction time.
You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp function which returns
a reference to the application object. Otherwise you can only use the global You can also use DECLARE_APP(appClass) in a header file to declare the wxGetApp function
which returns a reference to the application object. Otherwise you can only use the global
@c wxTheApp pointer which is of type @c wxApp *. @c wxTheApp pointer which is of type @c wxApp *.
@ref appshutdown_overview
@section wxappshutdownoverview Application shutdown @section overview_app_shutdown Application shutdown
The application normally shuts down when the last of its top level windows is 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 closed. This is normally the expected behaviour and means that it is enough to
call #Close() in response to the @c "Exit" menu call #Close() in response to the @c "Exit" menu command if your program has a single
command if your program has a single top level window. If this behaviour is not top level window. If this behaviour is not desirable wxApp::SetExitOnFrameDelete can
desirable wxApp::SetExitOnFrameDelete can be called to change it.
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 Note that starting from wxWidgets 2.3.3 such logic doesn't apply for the windows shown
other words, you can safely show a dialog from 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 wxApp::OnInit and not be afraid that your application terminates when this dialog --
terminates when this dialog -- which is the last top level window for the which is the last top level window for the moment -- is closed.
moment -- is closed.
Another aspect of the application shutdown is #OnExit Another aspect of the application shutdown is #OnExit
which is called when the application exits but @e before wxWidgets cleans up which is called when the application exits but @e before wxWidgets cleans up
its internal structures. You should delete all wxWidgets object that you its internal structures. You should delete all wxWidgets object that you
created by the time OnExit finishes. In particular, do @b not destroy them created by the time OnExit finishes.
from application class' destructor!
In particular, do @b not destroy them from application class' destructor!
For example, this code may crash: For example, this code may crash:
@code @code
@@ -122,4 +126,3 @@
*/ */

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: arc // Name: arc.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,77 +8,44 @@
/*! /*!
@page arc_overview Archive formats such as zip @page overview_arc Archive formats such as zip
The archive classes handle archive formats such as zip, tar, rar and cab. The archive classes handle archive formats such as zip, tar, rar and cab.
Currently #wxZip Currently #wxZip and #wxTar classes are included.
and #wxTar classes are included.
For each archive type, there are the following classes (using zip here For each archive type, there are the following classes (using zip here
as an example): 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.)
#wxZipInputStream
Input stream
#wxZipOutputStream
Output stream
#wxZipEntry
Holds the meta-data for an
entry (e.g. filename, timestamp, etc.)
There are also abstract wxArchive classes that can be used to write code There are also abstract wxArchive classes that can be used to write code
that can handle any of the archive types, that can handle any of the archive types, see @ref overview_arc_generic.
see '@ref arcgeneric_overview'.
Also see #wxFileSystem for a higher level interface that Also see #wxFileSystem for a higher level interface that
can handle archive files in a generic way. can handle archive files in a generic way.
The classes are designed to handle archives on both seekable streams such The classes are designed to handle archives on both seekable streams such
as disk files, or non-seekable streams such as pipes and sockets as disk files, or non-seekable streams such as pipes and sockets
(see '@ref arcnoseek_overview'). (see @ref overview_arc_noseek).
@b See also
#wxFileSystem
@ref arccreate_overview See also #wxFileSystem.
@ref arcextract_overview
@ref arcmodify_overview @li @ref overview_arc_create
@ref arcbyname_overview @li @ref overview_arc_extract
@ref arcgeneric_overview @li @ref overview_arc_modify
@ref arcnoseek_overview @li @ref overview_arc_byname
@li @ref overview_arc_generic
@li @ref overview_arc_noseek
@section wxarccreate Creating an archive <hr>
@ref arc_overview
Call #PutNextEntry() to @section overview_arc_create Creating an archive
create each new entry in the archive, then write the entry's data.
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. Another call to PutNextEntry() closes the current entry and begins the next.
For example: For example:
@@ -99,18 +66,18 @@
store entries in subdirectories. store entries in subdirectories.
@section wxarcextract Extracting an archive @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.
@ref arc_overview
#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(). When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
@code @code
auto_ptrwxZipEntry entry; auto_ptr<wxZipEntry> entry;
wxFFileInputStream in(_T("test.zip")); wxFFileInputStream in(_T("test.zip"));
wxZipInputStream zip(in); wxZipInputStream zip(in);
@@ -125,31 +92,31 @@
@section wxarcmodify Modifying an archive @section overview_arc_modify Modifying an archive
@ref arc_overview
To modify an existing archive, write a new copy of the archive to a new file, 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 making any necessary changes along the way and transferring any unchanged
entries using #CopyEntry(). entries using #CopyEntry().
For archive types which compress entry data, CopyEntry() is likely to be For archive types which compress entry data, CopyEntry() is likely to be
much more efficient than transferring the data using Read() and Write() much more efficient than transferring the data using Read() and Write()
since it will copy them without decompressing and recompressing them. since it will copy them without decompressing and recompressing them.
In general modifications are not possible without rewriting the archive, In general modifications are not possible without rewriting the archive,
though it may be possible in some limited cases. Even then, rewriting the 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 archive is usually a better choice since a failure can be handled without
losing the whole losing the whole archive. #wxTempFileOutputStream can be helpful to do this.
archive. #wxTempFileOutputStream can
be helpful to do this.
For example to delete all entries matching the pattern "*.txt": For example to delete all entries matching the pattern "*.txt":
@code @code
auto_ptrwxFFileInputStream in(new wxFFileInputStream(_T("test.zip"))); auto_ptr<wxFFileInputStream> in(new wxFFileInputStream(_T("test.zip")));
wxTempFileOutputStream out(_T("test.zip")); wxTempFileOutputStream out(_T("test.zip"));
wxZipInputStream inzip(*in); wxZipInputStream inzip(*in);
wxZipOutputStream outzip(out); wxZipOutputStream outzip(out);
auto_ptrwxZipEntry entry; auto_ptr<wxZipEntry> entry;
// transfer any meta-data for the archive as a whole (the zip comment // transfer any meta-data for the archive as a whole (the zip comment
// in the case of zip) // in the case of zip)
@@ -171,30 +138,30 @@
@section wxarcbyname Looking up an archive entry by name @section overview_arc_byname Looking up an archive entry by name
@ref arc_overview
Also see #wxFileSystem for a higher level interface that is Also see #wxFileSystem for a higher level interface that is
more convenient for accessing archive entries by name. more convenient for accessing archive entries by name.
To open just one entry in an archive, the most efficient way is To open just one entry in an archive, the most efficient way is
to simply search for it linearly by calling to simply search for it linearly by calling #GetNextEntry() until the
#GetNextEntry() until the
required entry is found. This works both for archives on seekable and required entry is found. This works both for archives on seekable and
non-seekable streams. non-seekable streams.
The format of filenames in the archive is likely to be different The format of filenames in the archive is likely to be different
from the local filename format. For example zips and tars use from the local filename format. For example zips and tars use
unix style names, with forward slashes as the path separator, unix style names, with forward slashes as the path separator,
and absolute paths are not allowed. So if on Windows the file and absolute paths are not allowed. So if on Windows the file
"C:\MYDIR\MYFILE.TXT" is stored, then when reading "C:\MYDIR\MYFILE.TXT" is stored, then when reading the entry back #GetName()
the entry back #GetName() will return will return "MYDIR\MYFILE.TXT". The conversion into the internal format
"MYDIR\MYFILE.TXT". The conversion into the internal format
and back has lost some information. and back has lost some information.
So to avoid ambiguity when searching for an entry matching a local name, 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 it is better to convert the local name to the archive's internal format
and search for that: and search for that:
@code @code
auto_ptrwxZipEntry entry; auto_ptr<wxZipEntry> entry;
// convert the local name we are looking for into the internal format // convert the local name we are looking for into the internal format
wxString name = wxZipEntry::GetInternalName(localname); wxString name = wxZipEntry::GetInternalName(localname);
@@ -216,8 +183,7 @@
To access several entries randomly, it is most efficient to transfer the 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 entire catalogue of entries to a container such as a std::map or a
#wxHashMap then entries looked up by name can be #wxHashMap then entries looked up by name can be opened using the #OpenEntry() method.
opened using the #OpenEntry() method.
@code @code
WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog); WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog);
@@ -259,73 +225,38 @@
@section wxarcgeneric Generic archive programming @section overview_arc_generic Generic archive programming
@ref arc_overview
Also see #wxFileSystem for a higher level interface that Also see #wxFileSystem for a higher level interface that
can handle archive files in a generic way. can handle archive files in a generic way.
The specific archive classes, such as the wxZip classes, inherit from The specific archive classes, such as the wxZip classes, inherit from
the following abstract classes which can be used to write code that can the following abstract classes which can be used to write code that can
handle any of the archive types: 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)
#wxArchiveInputStream
Input stream
#wxArchiveOutputStream
Output stream
#wxArchiveEntry
Holds the meta-data for an
entry (e.g. filename)
In order to able to write generic code it's necessary to be able to create 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. 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 To allow this there is a class factory for each archive type, derived from
#wxArchiveClassFactory, that can create #wxArchiveClassFactory, that can create the other classes.
the other classes.
For example, given @e wxArchiveClassFactory* factory, streams and For example, given @e wxArchiveClassFactory* factory, streams and
entries can be created like this: entries can be created like this:
@code @code
// create streams without knowing their type // create streams without knowing their type
auto_ptrwxArchiveInputStream inarc(factory-NewStream(in)); auto_ptr<wxArchiveInputStream> inarc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
// create an empty entry object // create an empty entry object
auto_ptrwxArchiveEntry entry(factory-NewEntry()); auto_ptr<wxArchiveEntry> entry(factory-NewEntry());
@endcode @endcode
For the factory itself, the static member For the factory itself, the static member wxArchiveClassFactory::Find().
wxArchiveClassFactory::Find().
can be used to find a class factory that can handle a given file can be used to find a class factory that can handle a given file
extension or mime type. For example, given @e filename: extension or mime type. For example, given @e filename:
@@ -339,14 +270,15 @@
@e Find does not give away ownership of the returned pointer, so it @e Find does not give away ownership of the returned pointer, so it
does not need to be deleted. does not need to be deleted.
There are similar class factories for the filter streams that handle the There are similar class factories for the filter streams that handle the
compression and decompression of a single stream, such as wxGzipInputStream. compression and decompression of a single stream, such as wxGzipInputStream.
These can be found using These can be found using wxFilterClassFactory::Find().
wxFilterClassFactory::Find().
For example, to list the contents of archive @e filename: For example, to list the contents of archive @e filename:
@code @code
auto_ptrwxInputStream in(new wxFFileInputStream(filename)); auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));
if (in-IsOk()) if (in-IsOk())
{ {
@@ -363,8 +295,8 @@
const wxArchiveClassFactory *acf; const wxArchiveClassFactory *acf;
acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
if (acf) { if (acf) {
auto_ptrwxArchiveInputStream arc(acf-NewStream(in.release())); auto_ptr<wxArchiveInputStream> arc(acf-NewStream(in.release()));
auto_ptrwxArchiveEntry entry; auto_ptr<wxArchiveEntry> entry;
// list the contents of the archive // list the contents of the archive
while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL) while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL)
@@ -378,94 +310,72 @@
@section wxarcnoseek Archives on non-seekable streams @section overview_arc_noseek Archives on non-seekable streams
@ref arc_overview
In general, handling archives on non-seekable streams is done in the same In general, handling archives on non-seekable streams is done in the same
way as for seekable streams, with a few caveats. way as for seekable streams, with a few caveats.
The main limitation is that accessing entries randomly using
#OpenEntry() The main limitation is that accessing entries randomly using #OpenEntry()
is not possible, the entries can only be accessed sequentially in the order is not possible, the entries can only be accessed sequentially in the order
they are stored within the archive. they are stored within the archive.
For each archive type, there will also be other limitations which will 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. 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. These are not too difficult to deal with, and are outlined below.
@b PutNextEntry and the entry size @b PutNextEntry and the entry size
When writing archives, some archive formats store the entry size before 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 data (tar has this limitation, zip doesn't). In this case
the entry's size must be passed to the entry's size must be passed to #PutNextEntry() or an error occurs.
#PutNextEntry() or an error
occurs.
This is only an issue on non-seekable streams, since otherwise the archive 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 output stream can seek back and fix up the header once the size of the
entry is known. entry is known.
For generic programming, one way to handle this is to supply the size 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 whenever it is known, and rely on the error message from the output
stream when the operation is not supported. stream when the operation is not supported.
@b GetNextEntry and the weak reference mechanism @b GetNextEntry and the weak reference mechanism
Some archive formats do not store all an entry's meta-data before the 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 entry's data (zip is an example). In this case, when reading from a
non-seekable stream, #GetNextEntry() non-seekable stream, #GetNextEntry() can only return a partially populated
can only return a partially populated #wxArchiveEntry #wxArchiveEntry object - not all the fields are set.
object - not all the fields are set.
The input stream then keeps a weak reference to the entry object and 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 updates it when more meta-data becomes available. A weak reference being
one that does not prevent you from deleting the wxArchiveEntry object - the one that does not prevent you from deleting the wxArchiveEntry object - the
input stream only attempts to update it if it is still around. input stream only attempts to update it if it is still around.
The documentation for each archive entry type gives the details The documentation for each archive entry type gives the details
of what meta-data becomes available and when. For generic programming, 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 when the worst case must be assumed, you can rely on all the fields
of wxArchiveEntry being fully populated when GetNextEntry() returns, of wxArchiveEntry being fully populated when GetNextEntry() returns,
with the the following exceptions: with the the following exceptions:
@li GetSize(): Guaranteed to be available after the entry has been read to #Eof(),
#GetSize()
Guaranteed to be
available after the entry has been read to #Eof(),
or #CloseEntry() has been called 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.
#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 @b wxArchiveNotifier
Notifier objects can be used to get a notification whenever an input Notifier objects can be used to get a notification whenever an input
stream updates a #wxArchiveEntry object's data stream updates a #wxArchiveEntry object's data
via the weak reference mechanism. via the weak reference mechanism.
Consider the following code which renames an entry in an archive. 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 This is the usual way to modify an entry's meta-data, simply set the
required field before writing it with required field before writing it with #CopyEntry():
#CopyEntry():
@code @code
auto_ptrwxArchiveInputStream arc(factory-NewStream(in)); auto_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
auto_ptrwxArchiveEntry entry; auto_ptr<wxArchiveEntry> entry;
outarc-CopyArchiveMetaData(*arc); outarc-CopyArchiveMetaData(*arc);
@@ -480,10 +390,8 @@
@endcode @endcode
However, for non-seekable streams, this technique cannot be used for However, for non-seekable streams, this technique cannot be used for
fields such as #IsReadOnly(), fields such as #IsReadOnly(), which are not necessarily set when
which are not necessarily set when #GetNextEntry() returns. In this case a #wxArchiveNotifier can be used:
#GetNextEntry() returns. In
this case a #wxArchiveNotifier can be used:
@code @code
class MyNotifier : public wxArchiveNotifier class MyNotifier : public wxArchiveNotifier
@@ -493,15 +401,13 @@
}; };
@endcode @endcode
The meta-data changes are done in your notifier's The meta-data changes are done in your notifier's #OnEntryUpdated() method,
#OnEntryUpdated() method, then #SetNotifier() is called before CopyEntry():
then #SetNotifier() is called before
CopyEntry():
@code @code
auto_ptrwxArchiveInputStream arc(factory-NewStream(in)); auto_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out)); auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
auto_ptrwxArchiveEntry entry; auto_ptr<wxArchiveEntry> entry;
MyNotifier notifier; MyNotifier notifier;
outarc-CopyArchiveMetaData(*arc); outarc-CopyArchiveMetaData(*arc);
@@ -524,4 +430,3 @@
*/ */

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: aui // Name: aui.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,37 +8,44 @@
/*! /*!
@page aui_overview wxAUI overview @page overview_aui wxAUI overview
Class: #wxAuiManager, #wxAuiPaneInfo Class: #wxAuiManager, #wxAuiPaneInfo
wxAUI stands for Advanced User Interface and the wxAUI framework wxAUI stands for Advanced User Interface and the wxAUI framework
aims to give its user a cutting edge interface for use with the aims to give its user a cutting edge interface for use with the
wxWidgets based applications. The original wxAUI sources have wxWidgets based applications. The original wxAUI sources have
kindly been made available under the wxWindows licence kindly been made available under the wxWindows licence
by Kirix Corp. and they have since then been integrated into by Kirix Corp. and they have since then been integrated into
wxWidgets CVS and further improved. wxWidgets CVS and further improved.
wxAUI attempts to encapsulate the following aspects of the user interface: wxAUI attempts to encapsulate the following aspects of the user interface:
@b Frame Management: @b Frame Management:
Frame management provides the means to open, move and hide common Frame management provides the means to open, move and hide common
controls that are needed to interact with the document, and allow these controls that are needed to interact with the document, and allow these
configurations to be saved into different perspectives and loaded at a configurations to be saved into different perspectives and loaded at a
later time. later time.
@b Toolbars: @b Toolbars:
Toolbars are a specialized subset of the frame management system and Toolbars are a specialized subset of the frame management system and
should behave similarly to other docked components. However, they also should behave similarly to other docked components. However, they also
require additional functionality, such as "spring-loaded" rebar support, require additional functionality, such as "spring-loaded" rebar support,
"chevron" buttons and end-user customizability. "chevron" buttons and end-user customizability.
@b Modeless Controls: @b Modeless Controls:
Modeless controls expose a tool palette or set of options that float Modeless controls expose a tool palette or set of options that float
above the application content while allowing it to be accessed. Usually above the application content while allowing it to be accessed. Usually
accessed by the toolbar, these controls disappear when an option is accessed by the toolbar, these controls disappear when an option is
selected, but may also be "torn off" the toolbar into a floating frame selected, but may also be "torn off" the toolbar into a floating frame
of their own. of their own.
@b Look and Feel: @b Look and Feel:
Look and feel encompasses the way controls are drawn, both when shown 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 statically as well as when they are being moved. This aspect of user
interface design incorporates "special effects" such as transparent interface design incorporates "special effects" such as transparent
window dragging as well as frame animation. window dragging as well as frame animation.
wxAUI adheres to the following principles: wxAUI adheres to the following principles:
Use native floating frames to obtain a native look and feel for all Use native floating frames to obtain a native look and feel for all
platforms. Use existing wxWidgets code where possible, such as sizer platforms. Use existing wxWidgets code where possible, such as sizer
@@ -46,5 +53,3 @@
and wxBase only. Use standard wxWidgets coding conventions. and wxBase only. Use standard wxWidgets coding conventions.
*/ */

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: backwardcompatibility // Name: backwardcompatibility.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,23 +8,28 @@
/*! /*!
@page backwardcompatibility_overview Backward compatibility @page overview_backwardcompat Backward compatibility
Many of the GUIs and platforms supported by wxWidgets are continuously Many of the GUIs and platforms supported by wxWidgets are continuously
evolving, and some of the new platforms wxWidgets now supports were quite evolving, and some of the new platforms wxWidgets now supports were quite
unimaginable even a few years ago. In this environment wxWidgets must also unimaginable even a few years ago. In this environment wxWidgets must also
evolve in order to support these new features and platforms. evolve in order to support these new features and platforms.
However the goal of wxWidgets is not only to provide a consistent However the goal of wxWidgets is not only to provide a consistent
programming interface across many platforms, but also to provide an programming interface across many platforms, but also to provide an
interface that is reasonably stable over time, to help protect its users interface that is reasonably stable over time, to help protect its users
from some of the uncertainty of the future. from some of the uncertainty of the future.
@ref versionnumbering_overview
@ref sourcecompatibility_overview @li @ref overview_backwardcompat_versionnumbering
@ref libbincompatibility_overview @li @ref overview_backwardcompat_sourcecompat
@ref appbincompatibility_overview @li @ref overview_backwardcompat_libbincompat
@li @ref overview_backwardcompat_appbincompat
@section versionnumbering The version numbering scheme <hr>
@section overview_backwardcompat_versionnumbering The version numbering scheme
wxWidgets version numbers can have up to four components, with trailing wxWidgets version numbers can have up to four components, with trailing
zeros sometimes omitted: zeros sometimes omitted:
@@ -38,40 +43,49 @@
changes are permitted, but only those that are backward compatible. For changes are permitted, but only those that are backward compatible. For
example, you can expect later @c 2.6.x.x releases, such as @c 2.6.1 example, you can expect later @c 2.6.x.x releases, such as @c 2.6.1
and @c 2.6.2 to be backward compatible with their predecessor. and @c 2.6.2 to be backward compatible with their predecessor.
When it becomes necessary to make changes which are not wholly backward When it becomes necessary to make changes which are not wholly backward
compatible, the stable branch is forked, creating a new development compatible, the stable branch is forked, creating a new development
branch of wxWidgets. This development branch will have an odd number branch of wxWidgets. This development branch will have an odd number
for @c minor, for example @c 2.7.x.x. Releases from this branch are for @c minor, for example @c 2.7.x.x. Releases from this branch are
known as development snapshots. known as development snapshots.
The stable branch and the development branch will then be developed in The stable branch and the development branch will then be developed in
parallel for some time. When it is no longer useful to continue developing parallel for some time. When it is no longer useful to continue developing
the stable branch, the development branch is renamed and becomes a new the stable branch, the development branch is renamed and becomes a new
stable branch, for example @c 2.8.0. And the process begins again. stable branch, for example @c 2.8.0. And the process begins again.
This is how the tension between keeping the interface stable, and allowing This is how the tension between keeping the interface stable, and allowing
the library to evolve is managed. the library to evolve is managed.
You can expect the versions with the same major and even minor You can expect the versions with the same major and even minor
version number to be compatible, but between minor versions there will be version number to be compatible, but between minor versions there will be
incompatibilities. Compatibility is not broken gratuitously however, so incompatibilities. Compatibility is not broken gratuitously however, so
many applications will require no changes or only small changes to work many applications will require no changes or only small changes to work
with the new version. with the new version.
@section sourcecompatibility Source level compatibility
@section overview_backwardcompat_sourcecompat Source level compatibility
Later releases from a stable branch are backward compatible with earlier Later releases from a stable branch are backward compatible with earlier
releases from the same branch at the source level. releases from the same branch at the source level.
This means that, for example, if you develop your application using This means that, for example, if you develop your application using
wxWidgets @c 2.6.0 then it should also compile fine with all later @c 2.6.x versions. The converse is also @true providing you avoid any new wxWidgets @c 2.6.0 then it should also compile fine with all later @c 2.6.x versions.
The converse is also @true providing you avoid any new
features not present in the earlier version. For example if you develop features not present in the earlier version. For example if you develop
using @c 2.6.1 your program will compile fine with wxWidgets @c 2.6.0 using @c 2.6.1 your program will compile fine with wxWidgets @c 2.6.0
providing you don't use any @c 2.6.1 specific features. providing you don't use any @c 2.6.1 specific features.
For some platforms binary compatibility is also supported, see 'Library For some platforms binary compatibility is also supported, see 'Library
binary compatibility' below. binary compatibility' below.
Between minor versions, for example between @c 2.2.x, @c 2.4.x and @c 2.6.x, there will be some incompatibilities. Wherever possible the old way
of doing something is kept alongside the new for a time wrapped inside: Between minor versions, for example between @c 2.2.x, @c 2.4.x and @c 2.6.x, there
will be some incompatibilities. Wherever possible the old way of doing something
is kept alongside the new for a time wrapped inside:
@code @code
#if WXWIN_COMPATIBILITY_2_4 #if WXWIN_COMPATIBILITY_2_4
/* deprecated feature */ // deprecated feature
... ...
#endif #endif
@endcode @endcode
@@ -81,30 +95,34 @@ By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0 stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
for @c 2.6.x. Earlier than that, obsolete features are removed. for @c 2.6.x. Earlier than that, obsolete features are removed.
These macros can be changed in @c setup.h. Or on UNIX-like systems you can These macros can be changed in @c setup.h. Or on UNIX-like systems you can
set them using the @c --disable-compat24 and @c --enable-compat22 set them using the @c --disable-compat24 and @c --enable-compat22
options to @c configure. options to @c configure.
They can be useful in two ways: They can be useful in two ways:
@li changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
find uses of deprecated features in your program. find uses of deprecated features in your program.
Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to @li changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
compile a program developed using @c 2.2.x that no longer compiles compile a program developed using @c 2.2.x that no longer compiles
with @c 2.6.x. with @c 2.6.x.
A program requiring one of these macros to be 1 will become A program requiring one of these macros to be 1 will become
incompatible with some future version of wxWidgets, and you should consider incompatible with some future version of wxWidgets, and you should consider
updating it. updating it.
@section libbincompatibility Library binary compatibility
@section overview_backwardcompat_libbincompat Library binary compatibility
For some platforms, releases from a stable branch are not only source level For some platforms, releases from a stable branch are not only source level
compatible but can also be binary compatible. compatible but can also be binary compatible.
Binary compatibility makes it possible to get the maximum benefit from Binary compatibility makes it possible to get the maximum benefit from
using shared libraries, also known as dynamic link libraries (DLLs) on using shared libraries, also known as dynamic link libraries (DLLs) on
Windows or dynamic shared libraries on OS X. Windows or dynamic shared libraries on OS X.
For example, suppose several applications are installed on a system requiring For example, suppose several applications are installed on a system requiring
wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
backward compatible with the earlier versions, it should be enough to backward compatible with the earlier versions, it should be enough to
@@ -112,11 +130,13 @@ install just wxWidgets @c 2.6.2 shared libraries, and all the applications
should be able to use them. If binary compatibility is not supported, then all should be able to use them. If binary compatibility is not supported, then all
the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
installed side by side. installed side by side.
Achieving this, without the user being required to have the source code Achieving this, without the user being required to have the source code
and recompile everything, places many extra constraints on the changes and recompile everything, places many extra constraints on the changes
that can be made within the stable branch. So it is not supported for all that can be made within the stable branch. So it is not supported for all
platforms, and not for all versions of wxWidgets. To date it has mainly platforms, and not for all versions of wxWidgets. To date it has mainly
been supported by wxGTK for UNIX-like platforms. been supported by wxGTK for UNIX-like platforms.
Another practical consideration is that for binary compatibility to work, Another practical consideration is that for binary compatibility to work,
all the applications and libraries must have been compiled with compilers all the applications and libraries must have been compiled with compilers
that are capable of producing compatible code; that are capable of producing compatible code;
@@ -125,7 +145,9 @@ same ABI (Application Binary Interface). Unfortunately most different C++
compilers do not produce code compatible with each other, and often even compilers do not produce code compatible with each other, and often even
different versions of the same compiler are not compatible. different versions of the same compiler are not compatible.
@section appbincompatibility Application binary compatibility
@section overview_backwardcompat_appbincompat Application binary compatibility
The most important aspect of binary compatibility is that applications The most important aspect of binary compatibility is that applications
compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work
@@ -134,20 +156,23 @@ compilers do not produce code compatible with each other, and often even
developer using a later version, e.g. @c 2.6.2 to be able to create binary developer using a later version, e.g. @c 2.6.2 to be able to create binary
application packages that will work with all binary compatible versions of application packages that will work with all binary compatible versions of
the shared library starting with, for example @c 2.6.0. the shared library starting with, for example @c 2.6.0.
To do this the developer must, of course, avoid any features not available To do this the developer must, of course, avoid any features not available
in the earlier versions. However this is not necessarily enough; in the earlier versions. However this is not necessarily enough;
in some in some cases an application compiled with a later version may depend on it even
cases an application compiled with a later version may depend on it even
though the same code would compile fine against an earlier version. though the same code would compile fine against an earlier version.
To help with this, a preprocessor symbol @c wxABI_VERSION can be defined To help with this, a preprocessor symbol @c wxABI_VERSION can be defined
during the compilation of the application (this would usually be done in the during the compilation of the application (this would usually be done in the
application's makefile or project settings). It should be set to the lowest application's makefile or project settings). It should be set to the lowest
version that is being targeted, as a number with two decimal digits for each version that is being targeted, as a number with two decimal digits for each
component, for example @c wxABI_VERSION=20600 for @c 2.6.0. component, for example @c wxABI_VERSION=20600 for @c 2.6.0.
Setting @c wxABI_VERSION should prevent the application from implicitly Setting @c wxABI_VERSION should prevent the application from implicitly
depending on a later version of wxWidgets, and also disables any new features depending on a later version of wxWidgets, and also disables any new features
in the API, giving a compile time check that the source is compatible with in the API, giving a compile time check that the source is compatible with
the versions of wxWidgets being targeted. the versions of wxWidgets being targeted.
Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when Uses of @c wxABI_VERSION are stripped out of the wxWidgets sources when
each new development branch is created. Therefore it is only useful to help each new development branch is created. Therefore it is only useful to help
achieve compatibility with earlier versions with the same major achieve compatibility with earlier versions with the same major
@@ -156,4 +181,3 @@ during the compilation of the application (this would usually be done in the
*/ */

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

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: bitmap // Name: bitmap.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -175,4 +175,3 @@
*/ */