another batch of topic overviews reviewing

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52014 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile
index 4183ad3b69bff95a0dea8ce946d6a597d22149d3..a4bec74eeb0fa38a059c64763187dac8a7f55560 100644 (file)
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -82,6 +82,9 @@ ALIASES += true="<b><tt>true</tt></b>"
 ALIASES += false="<b><tt>false</tt></b>"
 ALIASES += NULL="<b><tt>NULL</tt></b>"
 
 ALIASES += false="<b><tt>false</tt></b>"
 ALIASES += NULL="<b><tt>NULL</tt></b>"
 

+# NOTE: we could put aliases also for e.g. @wxDefaultSize, @wxDefaultPosition, @wxID_ANY, 
+#       @wxEmptyString, @wxNullIcon, etc etc
+

 # table aliases for 2 and 3 column tables
 ALIASES += beginTable="<center><table class='doctable'>"
 ALIASES += beginInvisibleTable="<center><table class='doctable' border='0'>"
 # table aliases for 2 and 3 column tables
 ALIASES += beginTable="<center><table class='doctable'>"
 ALIASES += beginInvisibleTable="<center><table class='doctable' border='0'>"


@@ -122,17 +125,20 @@ ALIASES += itemdef{9}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9</td></tr>"
 ALIASES += itemdef{10}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9,\10</td></tr>"
 ALIASES += endDefList="</table>"
 
 ALIASES += itemdef{10}="<tr><td>\b \1</td> <td>\2,\3,\4,\5,\6,\7,\8,\9,\10</td></tr>"
 ALIASES += endDefList="</table>"
 

-
-# NOTE: we could put aliases also for e.g. @wxDefaultSize, @wxDefaultPosition, @wxID_ANY, 
-#       @wxEmptyString, @wxNullIcon, etc etc
-

 # NOTE: these are important as you can't write in the docs
 #       just #ifdef since the # character is used by Doxygen
 #       for explicit linking; use the following aliases instead!
 # NOTE: these are important as you can't write in the docs
 #       just #ifdef since the # character is used by Doxygen
 #       for explicit linking; use the following aliases instead!

-ALIASES += ifdef="<b><tt>\#ifdef</tt></b>"
-ALIASES += ifndef="<b><tt>\#ifndef</tt></b>"
-ALIASES += if="<b><tt>\#if</tt></b>"          # NOTE: this overrides the Doxygen \if command
-ALIASES += endif="<b><tt>\#endif</tt></b>"
+#       However to avoid overwriting e.g. \if Doxygen command the _ character is postfixed
+ALIASES += ifdef_="<b><tt>\#ifdef</tt></b>"
+ALIASES += ifndef_="<b><tt>\#ifndef</tt></b>"
+ALIASES += if_="<b><tt>\#if</tt></b>"
+ALIASES += endif_="<b><tt>\#endif</tt></b>"
+
+# See ENABLED_SECTIONS configuration key for more info about these:
+ALIASES += beginWxPerlOnly="\if WXPERL_MANUAL \n <b>wxPerl note</b>\n\n"
+ALIASES += endWxPerlOnly="\endif"
+ALIASES += beginWxPythonOnly="\if WXPYTHON_MANUAL \n <b>wxPython note</b>\n\n"
+ALIASES += endWxPythonOnly="\endif"

 
 
 #---------------------------------------------------------------------------
 
 
 #---------------------------------------------------------------------------


@@ -160,7 +166,10 @@ GENERATE_TODOLIST      = YES
 GENERATE_TESTLIST      = YES
 GENERATE_BUGLIST       = YES
 GENERATE_DEPRECATEDLIST= YES
 GENERATE_TESTLIST      = YES
 GENERATE_BUGLIST       = YES
 GENERATE_DEPRECATEDLIST= YES

+
+# can contain WXPERL_MANUAL, WXPYTHON_MANUAL keywords

 ENABLED_SECTIONS       = 
 ENABLED_SECTIONS       = 

+

 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = YES
 SHOW_DIRECTORIES       = NO
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = YES
 SHOW_DIRECTORIES       = NO

diff --git a/docs/doxygen/mainpages/const_cpp.h b/docs/doxygen/mainpages/const_cpp.h
index 3d280e1332943092902d860162caf5698996a255..f5b08d984cb62a1cfe0d92f753b1e96f38fd4f38 100644 (file)
--- a/docs/doxygen/mainpages/const_cpp.h
+++ b/docs/doxygen/mainpages/const_cpp.h
@@ -15,7 +15,7 @@
  by category (and sorted by alphabetical order inside each category).
  All of these macros except for the @c wxUSE_XXX variety is defined if the
  corresponding condition is @true and undefined if it isn't, so they should be
  by category (and sorted by alphabetical order inside each category).
  All of these macros except for the @c wxUSE_XXX variety is defined if the
  corresponding condition is @true and undefined if it isn't, so they should be

- always tested using @ifdef and not @if.
+ always tested using @ifdef_ and not @if_.

 
  @li @ref page_cppconst_guisystem
  @li @ref page_cppconst_os
 
  @li @ref page_cppconst_guisystem
  @li @ref page_cppconst_os


@@ -161,14 +161,14 @@
  @itemdef{__VISAGECPP__, IBM Visual Age (OS/2)}
  @itemdef{__VISUALC__, Microsoft Visual C++, see also wxCHECK_VISUALC_VERSION. 
                        The value of this macro corresponds to the compiler version: 
  @itemdef{__VISAGECPP__, IBM Visual Age (OS/2)}
  @itemdef{__VISUALC__, Microsoft Visual C++, see also wxCHECK_VISUALC_VERSION. 
                        The value of this macro corresponds to the compiler version: 

-                       $1020$ for $4.2$ (the first supported version), $1100$ for 
-                       $5.0$, $1200$ for $6.0$ and so on. For convenience, the symbols 
+                       @c 1020 for @c 4.2 (the first supported version), @c 1100 for 
+                       @c 5.0, @c 1200 for @c 6.0 and so on. For convenience, the symbols 

                        __VISUALCn__ are also defined for each major compiler version from
                        __VISUALCn__ are also defined for each major compiler version from

-                       5 to 9, i.e. you can use tests such @ifdef __VISUALC7__ to test
+                       5 to 9, i.e. you can use tests such @ifdef_ __VISUALC7__ to test

                        for compiler version being precisely 7.}
  @itemdef{__XLC__, AIX compiler}
  @itemdef{__WATCOMC__, Watcom C++. The value of this macro corresponds to
                        for compiler version being precisely 7.}
  @itemdef{__XLC__, AIX compiler}
  @itemdef{__WATCOMC__, Watcom C++. The value of this macro corresponds to

-                      the compiler version, $1100$ is $11.0$ and $1200$ is OpenWatcom.}
+                      the compiler version, @c 1100 is @c 11.0 and @c 1200 is OpenWatcom.}

  @itemdef{_WIN32_WCE, Windows CE version}
  @endDefList
 
  @itemdef{_WIN32_WCE, Windows CE version}
  @endDefList
 


@@ -208,20 +208,20 @@
  @itemdef{wxUSE_XXX,
           if defined as $1$, feature XXX is active, see the 
           @ref page_wxusedef (the symbols of this form are always defined,
  @itemdef{wxUSE_XXX,
           if defined as $1$, feature XXX is active, see the 
           @ref page_wxusedef (the symbols of this form are always defined,

-          use @if and not @ifdef to test for them)}
+          use @if_ and not @ifdef_ to test for them)}

  @itemdef{WX_PRECOMP,
           is defined if precompiled headers (PCH) are in use. In
           this case, @c wx/wxprec.h includes @c wx/wx.h which, in turn,
           includes a number of wxWidgets headers thus making it unnecessary to include
           them explicitly. However if this is not defined, you do need to include them
           and so the usual idiom which allows to support both cases is to first include
  @itemdef{WX_PRECOMP,
           is defined if precompiled headers (PCH) are in use. In
           this case, @c wx/wxprec.h includes @c wx/wx.h which, in turn,
           includes a number of wxWidgets headers thus making it unnecessary to include
           them explicitly. However if this is not defined, you do need to include them
           and so the usual idiom which allows to support both cases is to first include

-          @c wx/wxprec.h} and then, inside @ifndef WX_PRECOMP, individual
+          @c wx/wxprec.h} and then, inside @ifndef_ WX_PRECOMP, individual

           headers you need.}
           headers you need.}

- @itemdef{_UNICODE and UNICODE, both are defined if wxUSE_UNICODE is set to $1$}
+ @itemdef{_UNICODE and UNICODE, both are defined if wxUSE_UNICODE is set to @c 1}

  @itemdef{wxUSE_GUI,
           this particular feature test macro is defined to $1$
           when compiling or using the library with the GUI features activated,
  @itemdef{wxUSE_GUI,
           this particular feature test macro is defined to $1$
           when compiling or using the library with the GUI features activated,

-          if it is defined as $0$, only wxBase is available.}
+          if it is defined as @c 0, only wxBase is available.}

  @itemdef{wxUSE_BASE,
           only used by wxWidgets internally (defined as $1$ when
           building wxBase code, either as a standalone library or as part of the
  @itemdef{wxUSE_BASE,
           only used by wxWidgets internally (defined as $1$ when
           building wxBase code, either as a standalone library or as part of the

diff --git a/docs/doxygen/mainpages/const_wxusedef.h b/docs/doxygen/mainpages/const_wxusedef.h
index 2e70b837dd9b70bba0e454bdcdeeabfbd9e76166..bad7093fb4f2a3e8411fe2748150c712d14a2b49 100644 (file)
--- a/docs/doxygen/mainpages/const_wxusedef.h
+++ b/docs/doxygen/mainpages/const_wxusedef.h
@@ -16,7 +16,7 @@
  category). These symbols are always defined and whether the given feature is
  active or not depends on their value: if defined as @c 1, feature is active,
  otherwise it is disabled. Because of this these symbols should be always tested
  category). These symbols are always defined and whether the given feature is
  active or not depends on their value: if defined as @c 1, feature is active,
  otherwise it is disabled. Because of this these symbols should be always tested

- using @if and not @ifdef.
+ using @if_ and not @ifdef_.

 
  @li @ref page_wxusedef_multi
  @li @ref page_wxusedef_unix
 
  @li @ref page_wxusedef_multi
  @li @ref page_wxusedef_unix

diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h
index 9157a76f3db68fb194702d306657a1a35cc5e2a9..8c1d03154efc00dac91cc05f9aac9298847a39a5 100644 (file)
--- a/docs/doxygen/mainpages/topics.h
+++ b/docs/doxygen/mainpages/topics.h
@@ -93,7 +93,7 @@
  @li @subpage overview_html
  @li @subpage overview_richtextctrl
  @li @subpage overview_aui
  @li @subpage overview_html
  @li @subpage overview_richtextctrl
  @li @subpage overview_aui

- @li @subpage overview_commondialogs
+ @li @subpage overview_cmndlg

  @li @subpage overview_toolbar
  @li @subpage overview_grid
  @li @subpage overview_treectrl
  @li @subpage overview_toolbar
  @li @subpage overview_grid
  @li @subpage overview_treectrl

diff --git a/docs/doxygen/overviews/commondialogs.h b/docs/doxygen/overviews/commondialogs.h
index 29366afc745ab21e0ca26ca1da0ff12b6346e4cd..5f25531a48c2b7a613bff58d68c6580222c4dd33 100644 (file)
--- a/docs/doxygen/overviews/commondialogs.h
+++ b/docs/doxygen/overviews/commondialogs.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        commondialogs
+// Name:        commondialogs.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,17 +8,16 @@
 
 /*!
 
 
 /*!
 

- @page commondialogs_overview Common dialogs overview
+ @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,
  to make them easy to use within an application.
  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,
  to make them easy to use within an application.

+

  Some dialogs have both platform-dependent and platform-independent implementations,
  so that if underlying windowing systems do not provide the required functionality,
  the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog
  Some dialogs have both platform-dependent and platform-independent implementations,
  so that if underlying windowing systems do not provide the required functionality,
  the generic classes and functions can stand in. For example, under MS Windows, wxColourDialog


@@ -26,24 +25,32 @@
  for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
  on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
  used, for testing or other purposes.
  for other platforms, and a macro defines wxColourDialog to be the same as wxGenericColourDialog
  on non-MS Windows platforms. However, under MS Windows, the generic dialog can also be
  used, for testing or other purposes.

- @ref colourdialog_overview
- @ref fontdialog_overview
- @ref printdialog_overview
- @ref filedialog_overview
- @ref dirdialog_overview
- @ref textentrydialog_overview
- @ref passwordentrydialog_overview
- @ref messagedialog_overview
- @ref singlechoicedialog_overview
- @ref multichoicedialog_overview

 
 
 
 

- @section wxcolourdialogoverview wxColourDialog overview
+ @li @ref overview_cmndlg_colour
+ @li @ref overview_cmndlg_font
+ @li @ref overview_cmndlg_print
+ @li @ref overview_cmndlg_file
+ @li @ref overview_cmndlg_dir
+ @li @ref overview_cmndlg_textentry
+ @li @ref overview_cmndlg_password
+ @li @ref overview_cmndlg_msg
+ @li @ref overview_cmndlg_singlechoice
+ @li @ref overview_cmndlg_multichoice
+
+
+ <hr>
+
+
+ @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.
  The wxColourDialog presents a colour selector to the user, and returns
  with colour information.

- @b The MS Windows colour selector
+
+ @subsection overview_cmndlg_colour_msw The MS Windows colour selector
+

  Under Windows, the native colour selector common dialog is used. This
  presents a dialog box with three main regions: at the top left, a
  palette of 48 commonly-used colours is shown. Under this, there is a
  Under Windows, the native colour selector common dialog is used. This
  presents a dialog box with three main regions: at the top left, a
  palette of 48 commonly-used colours is shown. Under this, there is a


@@ -51,7 +58,9 @@
  desired. Additionally, the user may open up the dialog box to show
  a right-hand panel containing controls to select a precise colour, and add
  it to the custom colour palette.
  desired. Additionally, the user may open up the dialog box to show
  a right-hand panel containing controls to select a precise colour, and add
  it to the custom colour palette.

- @b The generic colour selector
+
+ @subsection overview_cmndlg_colour_generic The generic colour selector
+

  Under non-MS Windows platforms, the colour selector is a simulation of
  most of the features of the MS Windows selector. Two palettes of 48
  standard and 16 custom colours are presented, with the right-hand area
  Under non-MS Windows platforms, the colour selector is a simulation of
  most of the features of the MS Windows selector. Two palettes of 48
  standard and 16 custom colours are presented, with the right-hand area


@@ -62,7 +71,9 @@
  are not optional in the generic colour selector. The generic colour
  selector is also available under MS Windows; use the name
  wxGenericColourDialog.
  are not optional in the generic colour selector. The generic colour
  selector is also available under MS Windows; use the name
  wxGenericColourDialog.

- @b Example
+
+ @subsection overview_cmndlg_colour_example Example
+

  In the samples/dialogs directory, there is an example of using
  the wxColourDialog class. Here is an excerpt, which
  sets various parameters of a wxColourData object, including
  In the samples/dialogs directory, there is an example of using
  the wxColourDialog class. Here is an excerpt, which
  sets various parameters of a wxColourData object, including


@@ -71,15 +82,15 @@
  uses it to set the background of a window.
 
  @code
  uses it to set the background of a window.
 
  @code

- wxColourData data;
-   data.SetChooseFull(@true);
+   wxColourData data;
+   data.SetChooseFull(true);

    for (int i = 0; i  16; i++)
    {
      wxColour colour(i*16, i*16, i*16);
      data.SetCustomColour(i, colour);
    }
 
    for (int i = 0; i  16; i++)
    {
      wxColour colour(i*16, i*16, i*16);
      data.SetCustomColour(i, colour);
    }
 

-   wxColourDialog dialog(this, );
+   wxColourDialog dialog(this, &data);

    if (dialog.ShowModal() == wxID_OK)
    {
      wxColourData retData = dialog.GetColourData();
    if (dialog.ShowModal() == wxID_OK)
    {
      wxColourData retData = dialog.GetColourData();


@@ -93,12 +104,15 @@
 
 
 
 
 
 

- @section wxfontdialogoverview wxFontDialog overview
+ @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.
  The wxFontDialog presents a font selector to the user, and returns
  with font and colour information.

- @b The MS Windows font selector
+
+ @subsection overview_cmndlg_font_msw The MS Windows font selector
+

  Under Windows, the native font selector common dialog is used. This
  presents a dialog box with controls for font name, point size, style, weight,
  underlining, strikeout and text foreground colour. A sample of the
  Under Windows, the native font selector common dialog is used. This
  presents a dialog box with controls for font name, point size, style, weight,
  underlining, strikeout and text foreground colour. A sample of the


@@ -107,23 +121,27 @@
  conventions, strikeout is ignored and a font family (such as
  Swiss or Modern) is deduced from the actual font name (such as Arial
  or Courier).
  conventions, strikeout is ignored and a font family (such as
  Swiss or Modern) is deduced from the actual font name (such as Arial
  or Courier).

- @b The generic font selector
+
+ @subsection overview_cmndlg_font_generic The generic font selector
+

  Under non-MS Windows platforms, the font selector is simpler.
  Controls for font family, point size, style, weight,
  underlining and text foreground colour are provided, and
  a sample is shown upon a white background. The generic font selector
  is also available under MS Windows; use the name wxGenericFontDialog.
  Under non-MS Windows platforms, the font selector is simpler.
  Controls for font family, point size, style, weight,
  underlining and text foreground colour are provided, and
  a sample is shown upon a white background. The generic font selector
  is also available under MS Windows; use the name wxGenericFontDialog.

- @b Example
+
+ @subsection overview_cmndlg_font_example Example
+

  In the samples/dialogs directory, there is an example of using
  the wxFontDialog class. The application uses the returned font
  and colour for drawing text on a canvas. Here is an excerpt:
 
  @code
  In the samples/dialogs directory, there is an example of using
  the wxFontDialog class. The application uses the returned font
  and colour for drawing text on a canvas. Here is an excerpt:
 
  @code

- wxFontData data;
+   wxFontData data;

    data.SetInitialFont(canvasFont);
    data.SetColour(canvasTextColour);
 
    data.SetInitialFont(canvasFont);
    data.SetColour(canvasTextColour);
 

-   wxFontDialog dialog(this, );
+   wxFontDialog dialog(this, &data);

    if (dialog.ShowModal() == wxID_OK)
    {
      wxFontData retData = dialog.GetFontData();
    if (dialog.ShowModal() == wxID_OK)
    {
      wxFontData retData = dialog.GetFontData();


@@ -134,33 +152,42 @@
  @endcode
 
 
  @endcode
 
 

- @section wxprintdialogoverview wxPrintDialog overview
+
+ @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
  a successfully dismissed print dialog.
  This class represents the print and print setup common dialogs.
  You may obtain a #wxPrinterDC device context from
  a successfully dismissed print dialog.

- The samples/printing example shows how to use it: see @ref printing_overview for
+
+ The samples/printing example shows how to use it: see @ref overview_printing for

  an excerpt from this example.
 
  an excerpt from this example.
 

- @section wxfiledialogoverview wxFileDialog overview
+
+
+ @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
  functionality. The path and filename are distinct elements of a full file pathname.
  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
  functionality. The path and filename are distinct elements of a full file pathname.

+

  If path is "", the current directory will be used. If filename is "",
  no default filename will be supplied. The wildcard determines what files
  are displayed in the file selector, and file extension supplies a type
  extension for the required filename. Flags may be a combination of wxFD_OPEN,
  wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
  wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.
  If path is "", the current directory will be used. If filename is "",
  no default filename will be supplied. The wildcard determines what files
  are displayed in the file selector, and file extension supplies a type
  extension for the required filename. Flags may be a combination of wxFD_OPEN,
  wxFD_SAVE, wxFD_OVERWRITE_PROMPT, wxFD_HIDE_READONLY, wxFD_FILE_MUST_EXIST,
  wxFD_MULTIPLE, wxFD_CHANGE_DIR or 0.

+

  Both the X and Windows versions implement a wildcard filter. Typing a
  filename containing wildcards (*, ?) in the filename text item, and
  clicking on Ok, will result in only those files matching the pattern being
  displayed. In the X version, supplying no default name will result in the
  wildcard filter being inserted in the filename text item; the filter is
  ignored if a default name is supplied.
  Both the X and Windows versions implement a wildcard filter. Typing a
  filename containing wildcards (*, ?) in the filename text item, and
  clicking on Ok, will result in only those files matching the pattern being
  displayed. In the X version, supplying no default name will result in the
  wildcard filter being inserted in the filename text item; the filter is
  ignored if a default name is supplied.

+

  The wildcard may be a specification for multiple
  types of file with a description for each, such as:
 
  The wildcard may be a specification for multiple
  types of file with a description for each, such as:
 


@@ -169,45 +196,62 @@
  @endcode
 
 
  @endcode
 
 

- @section wxdirdialogoverview wxDirDialog overview
+
+ @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 wxtextentrydialogoverview wxTextEntryDialog overview
+ 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.
 
  This is a dialog with a text entry field. The value that the user
  entered is obtained using wxTextEntryDialog::GetValue.
 

- @section wxpasswordentrydialogoverview wxPasswordEntryDialog overview
+
+
+ @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.
 
  This is a dialog with a password entry field. The value that the user
  entered is obtained using wxTextEntryDialog::GetValue.
 

- @section wxmessagedialogoverview wxMessageDialog overview
+
+
+ @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.
  This dialog shows a message, plus buttons that can be chosen from OK, Cancel, Yes, and No.
  Under Windows, an optional icon can be shown, such as an exclamation mark or question mark.

+

  The return value of wxMessageDialog::ShowModal indicates
  which button the user pressed.
 
  The return value of wxMessageDialog::ShowModal indicates
  which button the user pressed.
 

- @section wxsinglechoicedialogoverview wxSingleChoiceDialog overview
+
+
+ @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,
  a string or client data.
 
  This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
  select one of them. The selection can be obtained from the dialog as an index,
  a string or client data.
 

- @section wxmultichoicedialogoverview wxMultiChoiceDialog overview
+
+
+ @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.
 
  This dialog shows a list of choices, plus OK and (optionally) Cancel. The user can
  select one or more of them.
 

- */
-
+*/

 
 

diff --git a/docs/doxygen/overviews/config.h b/docs/doxygen/overviews/config.h
index 2a3ab2c93d5717b80ea63d3cab4b0e64dcb208f4..656e53879651d9bb5c0ba9eb22affc891fd0f069 100644 (file)
--- a/docs/doxygen/overviews/config.h
+++ b/docs/doxygen/overviews/config.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        config
+// Name:        config.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,27 +8,27 @@
 
 /*!
 
 
 /*!
 

- @page config_overview wxConfig classes overview
+ @page overview_config wxConfig classes overview

 
  Classes: #wxConfig
 
  Classes: #wxConfig

+

  This overview briefly describes what the config classes are and what they are
  for. All the details about how to use them may be found in the description of
  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.
  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
  file, registry and INI file based implementations mentions all the
  features/limitations specific to each one of these versions.

+

  The config classes provide a way to store some application configuration
  information. They were especially designed for this usage and, although may
  probably be used for many other things as well, should be limited to it. It
  means that this information should be:
 
  The config classes provide a way to store some application configuration
  information. They were especially designed for this usage and, although may
  probably be used for many other things as well, should be limited to it. It
  means that this information should be:
 

-
-  Typed, i.e. strings or numbers for the moment. You can not store
- binary data, for example.
-  Small. For instance, it is not recommended to use the Windows
- registry for amounts of data more than a couple of kilobytes.
-  Not performance critical, neither from speed nor from a memory
- consumption point of view.
-
+ @li Typed, i.e. strings or numbers for the moment. 
+     You can not store binary data, for example.
+ @li Small. For instance, it is not recommended to use the Windows
+     registry for amounts of data more than a couple of kilobytes.
+ @li Not performance critical, neither from speed nor from a memory
+     consumption point of view.

 
  On the other hand, the features provided make them very useful for storing all
  kinds of small to medium volumes of hierarchically-organized, heterogeneous
 
  On the other hand, the features provided make them very useful for storing all
  kinds of small to medium volumes of hierarchically-organized, heterogeneous


@@ -36,23 +36,27 @@
  (numbers and strings) organizing it in a tree where you use the
  filesystem-like paths to specify the location of a piece of data. In
  particular, these classes were designed to be as easy to use as possible.
  (numbers and strings) organizing it in a tree where you use the
  filesystem-like paths to specify the location of a piece of data. In
  particular, these classes were designed to be as easy to use as possible.

+

  From another point of view, they provide an interface which hides the
  differences between the Windows registry and the standard Unix text format
  configuration files. Other (future) implementations of wxConfigBase might also
  understand GTK resource files or their analogues on the KDE side.
  From another point of view, they provide an interface which hides the
  differences between the Windows registry and the standard Unix text format
  configuration files. Other (future) implementations of wxConfigBase might also
  understand GTK resource files or their analogues on the KDE side.

+

  In any case, each implementation of wxConfigBase does its best to
  make the data look the same way everywhere. Due to limitations of the underlying
  physical storage, it may not implement 100% of the base class functionality.
  In any case, each implementation of wxConfigBase does its best to
  make the data look the same way everywhere. Due to limitations of the underlying
  physical storage, it may not implement 100% of the base class functionality.

- There are groups of entries and the entries themselves. Each entry contains either a string or a number
- (or a boolean value; support for other types of data such as dates or
- timestamps is planned) and is identified by the full path to it: something
- like /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,
+
+ 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. 
+
+ 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.
 
  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.
 

- */
-
-
+*/

diff --git a/docs/doxygen/overviews/constraints.h b/docs/doxygen/overviews/constraints.h
index 73c2a02ca6f844999923259f1ba6ed6490fa1c01..40ec4973c7c1775eb487a59cc382226ced4b87e0 100644 (file)
--- a/docs/doxygen/overviews/constraints.h
+++ b/docs/doxygen/overviews/constraints.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        constraints
+// Name:        constraints.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,17 +8,19 @@
 
 /*!
 
 
 /*!
 

- @page constraints_overview Constraints overview
+ @page overview_constraints Constraints overview

 
  Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint.
 
  Classes: #wxLayoutConstraints, #wxIndividualLayoutConstraint.

- @b Note: constraints are now deprecated and you should use #sizers instead.
+
+ @note Constraints are now deprecated and you should use sizers instead (see wxSizer).
+

  Objects of class wxLayoutConstraint can be associated with a window to define
  the way it is laid out, with respect to its siblings or the parent.
  Objects of class wxLayoutConstraint can be associated with a window to define
  the way it is laid out, with respect to its siblings or the parent.

+

  The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
  some or all of which should be accessed directly to set the appropriate
  constraints.
 
  The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
  some or all of which should be accessed directly to set the appropriate
  constraints.
 

-

   @b left: represents the left hand edge of the window
   @b right: represents the right hand edge of the window
   @b top: represents the top edge of the window
   @b left: represents the left hand edge of the window
   @b right: represents the right hand edge of the window
   @b top: represents the top edge of the window


@@ -28,45 +30,52 @@
   @b centreX: represents the horizontal centre point of the window
   @b centreY: represents the vertical centre point of the window
 
   @b centreX: represents the horizontal centre point of the window
   @b centreY: represents the vertical centre point of the window
 

-

  The constraints are initially set to have the relationship wxUnconstrained,
  which means that their values should be calculated by looking at known constraints.
  To calculate the position and size of the control, the layout algorithm needs to
  know exactly 4 constraints (as it has 4 numbers to calculate from them), so you
  should always set exactly 4 of the constraints from the above table.
  The constraints are initially set to have the relationship wxUnconstrained,
  which means that their values should be calculated by looking at known constraints.
  To calculate the position and size of the control, the layout algorithm needs to
  know exactly 4 constraints (as it has 4 numbers to calculate from them), so you
  should always set exactly 4 of the constraints from the above table.

+

  If you want the controls height or width to have the default value, you may use
  a special value for the constraint: wxAsIs. If the constraint is wxAsIs, the
  dimension will not be changed which is useful for the dialog controls which
  often have the default size (e.g. the buttons whose size is determined by their
  label).
  If you want the controls height or width to have the default value, you may use
  a special value for the constraint: wxAsIs. If the constraint is wxAsIs, the
  dimension will not be changed which is useful for the dialog controls which
  often have the default size (e.g. the buttons whose size is determined by their
  label).

- The constrains calculation is done in wxWindow::Layout
- function which evaluates constraints. To call it you can either call
- wxWindow::SetAutoLayout if the parent window
- is a frame, panel or a dialog to tell default OnSize handlers to call Layout
+
+ The constrains calculation is done in wxWindow::Layout function which evaluates 
+ constraints. To call it you can either call wxWindow::SetAutoLayout if the parent 
+ window is a frame, panel or a dialog to tell default OnSize handlers to call Layout

  automatically whenever the window size changes, or override OnSize and call
  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 window is not a
- frame, panel or dialog).
- @ref constraintlayoutdetails_overview
- @ref layoutexamples_overview
+ Layout yourself (note that you do have to call #Layout yourself if the parent 
+ window is not a frame, panel or dialog).
+
+ @li @ref overview_constraints_layout
+ @li @ref overview_constraints_examples
+

 
 

+ <hr>

 
 

- @section constraintlayoutdetails Constraint layout: more details
+
+ @section overview_constraints_layout Constraint layout: more details

 
  By default, windows do not have a wxLayoutConstraints object. In this case, much layout
  must be done explicitly, by performing calculations in OnSize members, except
  for the case of frames that have exactly one subwindow (not counting toolbar and
  statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
  takes care of resizing the child to always fill the frame.
 
  By default, windows do not have a wxLayoutConstraints object. In this case, much layout
  must be done explicitly, by performing calculations in OnSize members, except
  for the case of frames that have exactly one subwindow (not counting toolbar and
  statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
  takes care of resizing the child to always fill the frame.

+

  To avoid the need for these rather awkward calculations, the user can create
  a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
  This object contains a constraint for each of the window edges, two for the centre point,
  and two for the window size. By setting some or all of these constraints appropriately,
  the user can achieve quite complex layout by defining relationships between windows.
  To avoid the need for these rather awkward calculations, the user can create
  a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
  This object contains a constraint for each of the window edges, two for the centre point,
  and two for the window size. By setting some or all of these constraints appropriately,
  the user can achieve quite complex layout by defining relationships between windows.

- In wxWidgets, each window can be constrained relative to either its @e siblings on the same window, or the @e parent. The layout algorithm
+
+ In wxWidgets, each window can be constrained relative to either its @e siblings 
+ on the same window, or the @e parent. The layout algorithm

  therefore operates in a top-down manner, finding the correct layout for
  therefore operates in a top-down manner, finding the correct layout for

- the children of a window, then the layout for the grandchildren, and so
- on. Note that this differs markedly from native Motif layout, where
+ the children of a window, then the layout for the grandchildren, and so on. 
+
+ Note that this differs markedly from native Motif layout, where

  constraints can ripple upwards and can eventually change the frame
  window or dialog box size. We assume in wxWidgets that the @e user is
  always 'boss' and specifies the size of the outer window, to which
  constraints can ripple upwards and can eventually change the frame
  window or dialog box size. We assume in wxWidgets that the @e user is
  always 'boss' and specifies the size of the outer window, to which


@@ -74,15 +83,17 @@
  circumstances, but it suffices for most situations, and the
  simplification avoids some of the nightmarish problems associated with
  programming Motif.
  circumstances, but it suffices for most situations, and the
  simplification avoids some of the nightmarish problems associated with
  programming Motif.

+

  When the user sets constraints, many of the constraints for windows
  edges and dimensions remain unconstrained. For a given window,
  the wxWindow::Layout algorithm first resets all constraints
  When the user sets constraints, many of the constraints for windows
  edges and dimensions remain unconstrained. For a given window,
  the wxWindow::Layout algorithm first resets all constraints

- in all children to have unknown edge or dimension values, and then iterates through the constraints,
- evaluating them. For unconstrained edges and dimensions, it
- tries to find the value using known relationships that always hold. For example,
+ in all children to have unknown edge or dimension values, and then iterates 
+ through the constraints, evaluating them. For unconstrained edges and dimensions,
+ it tries to find the value using known relationships that always hold. For example,

  an unconstrained @e width may be calculated from the @e left and @e right edges, if
  both are currently known. For edges and dimensions with user-supplied constraints, these
  constraints are evaluated if the inputs of the constraint are known.
  an unconstrained @e width may be calculated from the @e left and @e right edges, if
  both are currently known. For edges and dimensions with user-supplied constraints, these
  constraints are evaluated if the inputs of the constraint are known.

+

  The algorithm stops when all child edges and dimension are known (success), or
  there are unknown edges or dimensions but there has been no change in this cycle (failure).
  It then sets all the window positions and sizes according to the values it has found.
  The algorithm stops when all child edges and dimension are known (success), or
  there are unknown edges or dimensions but there has been no change in this cycle (failure).
  It then sets all the window positions and sizes according to the values it has found.


@@ -96,16 +107,17 @@
  specifying that it should be LeftOf() the second one than to do in a more
  natural left-to-right order.
 
  specifying that it should be LeftOf() the second one than to do in a more
  natural left-to-right order.
 

- @section layoutexamples Window layout examples

 
 
 
 

- @section subwindowlayoutexample Example 1: subwindow layout
+ @section overview_constraints_examples Window layout examples
+
+ @subsection overview_constraints_example1 Example 1: subwindow layout

 
  This example specifies a panel and a window side by side,
  with a text subwindow below it.
 
  @code
 
  This example specifies a panel and a window side by side,
  with a text subwindow below it.
 
  @code

- frame-panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0);
+   frame-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-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));
 


@@ -140,7 +152,7 @@
  @endcode
 
 
  @endcode
 
 

- @section panelitemlayoutexample Example 2: panel item layout
+ @subsection overview_constraints_example2 Example 2: panel item layout

 
  This example sizes a button width to 80 percent of the panel width, and centres
  it horizontally. A listbox and multitext item are placed below it. The listbox
 
  This example sizes a button width to 80 percent of the panel width, and centres
  it horizontally. A listbox and multitext item are placed below it. The listbox


@@ -148,7 +160,7 @@
  the remainder of the width. Margins of 5 pixels are used.
 
  @code
  the remainder of the width. Margins of 5 pixels are used.
 
  @code

- // Create some panel items
+   // Create some panel items

    wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ;
 
    wxLayoutConstraints *b1 = new wxLayoutConstraints;
    wxButton *btn1 = new wxButton(frame-panel, -1, "A button") ;
 
    wxLayoutConstraints *b1 = new wxLayoutConstraints;


@@ -179,6 +191,5 @@
    mtext-SetConstraints(b3);
  @endcode
 
    mtext-SetConstraints(b3);
  @endcode
 

- */
-
+*/

 
 

diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h
index 796af3f3834525e21fc3c64b4678b677103dfe51..101147576e7ff4288af6b0d0c8bacfad18a799f9 100644 (file)
--- a/docs/doxygen/overviews/container.h
+++ b/docs/doxygen/overviews/container.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        container
+// Name:        container.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,48 +8,57 @@
 
 /*!
 
 
 /*!
 

- @page container_overview Container classes overview
+ @page overview_container Container classes overview

 
  Classes: #wxListT, #wxArrayT, #wxVectorT
 
  Classes: #wxListT, #wxArrayT, #wxVectorT

+

  wxWidgets uses itself several container classes including doubly-linked lists
  and dynamic arrays (i.e. arrays which expand automatically when they become
  wxWidgets uses itself several container classes including doubly-linked lists
  and dynamic arrays (i.e. arrays which expand automatically when they become

- full). For both historical and portability reasons wxWidgets does not
- use STL which provides the standard implementation of many container classes in
- C++. First of all, wxWidgets has existed since well before STL was written, and
+ full). For both historical and portability reasons wxWidgets does not use STL 
+ which provides the standard implementation of many container classes in C++.
+
+ First of all, wxWidgets has existed since well before STL was written, and

  secondly we don't believe that today compilers can deal really well with all of
  secondly we don't believe that today compilers can deal really well with all of

- STL classes (this is especially @true for some less common platforms). Of
+ STL classes (this is especially true for some less common platforms). Of

  course, the compilers are evolving quite rapidly and hopefully their progress
  will allow to base future versions of wxWidgets on STL - but this is not yet
  the case.
  course, the compilers are evolving quite rapidly and hopefully their progress
  will allow to base future versions of wxWidgets on STL - but this is not yet
  the case.

+

  wxWidgets container classes don't pretend to be as powerful or full as STL
  ones, but they are quite useful and may be compiled with absolutely any C++
  compiler. They're used internally by wxWidgets, but may, of course, be used in
  your programs as well if you wish.
  wxWidgets container classes don't pretend to be as powerful or full as STL
  ones, but they are quite useful and may be compiled with absolutely any C++
  compiler. They're used internally by wxWidgets, but may, of course, be used in
  your programs as well if you wish.

+

  The list classes in wxWidgets are doubly-linked lists which may either own the
  objects they contain (meaning that the list deletes the object when it is
  removed from the list or the list itself is destroyed) or just store the
  The list classes in wxWidgets are doubly-linked lists which may either own the
  objects they contain (meaning that the list deletes the object when it is
  removed from the list or the list itself is destroyed) or just store the

- pointers depending on whether you called or not
- wxList::DeleteContents method.
+ pointers depending on whether you called or not wxList::DeleteContents method.
+

  Dynamic arrays resemble C arrays but with two important differences: they
  provide run-time range checking in debug builds and they automatically expand
  the allocated memory when there is no more space for new items. They come in
  two sorts: the "plain" arrays which store either built-in types such as "char",
  "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
  own the object pointers to which they store.
  Dynamic arrays resemble C arrays but with two important differences: they
  provide run-time range checking in debug builds and they automatically expand
  the allocated memory when there is no more space for new items. They come in
  two sorts: the "plain" arrays which store either built-in types such as "char",
  "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
  own the object pointers to which they store.

+

  For the same portability reasons, the container classes implementation in wxWidgets
  does not use templates, but is rather based on C preprocessor i.e. is done with
  the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
  lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
  For the same portability reasons, the container classes implementation in wxWidgets
  does not use templates, but is rather based on C preprocessor i.e. is done with
  the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
  lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for

- the dynamic arrays. The "DECLARE" macro declares a
- new container class containing the elements of given type and is needed for all
- three types of container classes: lists, arrays and objarrays. The "DEFINE"
- classes must be inserted in your program in a place where the @b full
- declaration of container element class is in scope (i.e. not just forward
- declaration), otherwise destructors of the container elements will not be
- called! As array classes never delete the items they contain anyhow, there is
+ the dynamic arrays. 
+
+ The "DECLARE" macro declares a new container class containing the elements of 
+ given type and is needed for all three types of container classes: lists, 
+ arrays and objarrays. The "DEFINE" classes must be inserted in your program 
+ in a place where the @b full declaration of container element class is in scope 
+ (i.e. not just forward declaration), otherwise destructors of the container 
+ elements will not be called! 
+
+ As array classes never delete the items they contain anyhow, there is

  no WX_DEFINE_ARRAY macro for them.
  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
  wxObjects and wxStringList as a list of C-style strings (char *), both of these
  Finally, wxWidgets predefines several commonly used container classes. wxList
  is defined for compatibility with previous versions as a list containing
  wxObjects and wxStringList as a list of C-style strings (char *), both of these


@@ -57,9 +66,6 @@
  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
  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.

 
 

+*/

diff --git a/docs/doxygen/overviews/dataobject.h b/docs/doxygen/overviews/dataobject.h
index 78cfe7f8d88fb9c722d66dbd28b971f96d01813a..bf84f293b5e1681c273569151ad5319f4312db6a 100644 (file)
--- a/docs/doxygen/overviews/dataobject.h
+++ b/docs/doxygen/overviews/dataobject.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        dataobject
+// Name:        dataobject.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,20 +8,19 @@
 
 /*!
 
 
 /*!
 

- @page dataobject_overview wxDataObject overview
+ @page overview_dataobject wxDataObject overview

 
 

- Classes: #wxDataObject,
-  #wxClipboard,
-  #wxDataFormat,
-  #wxDropSource,
-  #wxDropTarget
- See also: @ref dnd_overview and @ref samplednd_overview
- This overview discusses data transfer through clipboard or drag and drop. In
- wxWidgets, these two ways to transfer data (either between different
+ Classes: #wxDataObject, #wxClipboard, #wxDataFormat, #wxDropSource, #wxDropTarget
+
+ See also: @ref overview_dnd and @ref overview_samplednd
+
+ This overview discusses data transfer through clipboard or drag and drop.
+ In wxWidgets, these two ways to transfer data (either between different

  applications or inside one and the same) are very similar which allows to
  implement both of them using almost the same code - or, in other
  words, if you implement drag and drop support for your application, you get
  clipboard support for free and vice versa.
  applications or inside one and the same) are very similar which allows to
  implement both of them using almost the same code - or, in other
  words, if you implement drag and drop support for your application, you get
  clipboard support for free and vice versa.

+

  At the heart of both clipboard and drag and drop operations lies the
  #wxDataObject class. The objects of this class (or, to
  be precise, classes derived from it) represent the data which is being carried
  At the heart of both clipboard and drag and drop operations lies the
  #wxDataObject class. The objects of this class (or, to
  be precise, classes derived from it) represent the data which is being carried


@@ -31,50 +30,50 @@
  render itself in any of them (see GetDataHere). It can also receive its value
  from the outside in a format it supports if it implements the SetData method.
  Please see the documentation of this class for more details.
  render itself in any of them (see GetDataHere). It can also receive its value
  from the outside in a format it supports if it implements the SetData method.
  Please see the documentation of this class for more details.

+

  Both clipboard and drag and drop operations have two sides: the source and
  target, the data provider and the data receiver. These which may be in the same
  application and even the same window when, for example, you drag some text from
  one position to another in a word processor. Let us describe what each of them
  should do.
  Both clipboard and drag and drop operations have two sides: the source and
  target, the data provider and the data receiver. These which may be in the same
  application and even the same window when, for example, you drag some text from
  one position to another in a word processor. Let us describe what each of them
  should do.

- #The data provider (source) duties
- #The data receiver (target) duties
+
+ @li The data provider (source) duties
+ @li The data receiver (target) duties

 
 
 
 

- @section wxdataobjectsource The data provider (source) duties
+ @section overview_dataobject_source The data provider (source) duties
+
+ The data provider is responsible for creating a #wxDataObject containing the 
+ data to be transferred. Then it should either pass it to the clipboard using
+ #SetData function or to #wxDropSource and call #DoDragDrop function.

 
 

- The data provider is responsible for creating a
- #wxDataObject containing the data to be
- transferred. Then it should either pass it to the clipboard using
- #SetData function or to
- #wxDropSource and call
- #DoDragDrop function.

  The only (but important) difference is that the object for the clipboard
  transfer must always be created on the heap (i.e. using @c new) and it will
  be freed by the clipboard when it is no longer needed (indeed, it is not known
  in advance when, if ever, the data will be pasted from the clipboard). On the
  other hand, the object for drag and drop operation must only exist while
  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).
+ #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).
 
  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).
 

- @section wxdataobjecttarget The data receiver (target) duties
+
+ @section overview_dataobject_target The data receiver (target) duties

 
  To receive (paste in usual terminology) data from the clipboard, you should
 
  To receive (paste in usual terminology) data from the clipboard, you should

- create a #wxDataObject derived class which supports the
- data formats you need and pass it as argument to
- wxClipboard::GetData. If it returns @false,
- no data in (any of) the supported format(s) is available. If it returns @true, the data has been successfully transferred to wxDataObject.
- For drag and drop case, the wxDropTarget::OnData
- virtual function will be called when a data object is dropped, from which the
- data itself may be requested by calling
- wxDropTarget::GetData method which fills
- the data object.
-
- */
+ create a #wxDataObject derived class which supports the data formats you need 
+ and pass it as argument to wxClipboard::GetData. If it returns @false,
+
+ no data in (any of) the supported format(s) is available. If it returns @true, 
+ the data has been successfully transferred to wxDataObject.
+
+ For drag and drop case, the wxDropTarget::OnData virtual function will be called 
+ when a data object is dropped, from which the data itself may be requested by calling
+ wxDropTarget::GetData method which fills the data object.

 
 

+*/

 
 

diff --git a/docs/doxygen/overviews/datetime.h b/docs/doxygen/overviews/datetime.h
index 756abb77fc15b68fd9f155a40a6bcc9528f6a979..a7aab071a496f3c6940673f80540a96a7fe17f0d 100644 (file)
--- a/docs/doxygen/overviews/datetime.h
+++ b/docs/doxygen/overviews/datetime.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        datetime
+// Name:        datetime.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,100 +8,64 @@
 
 /*!
 
 
 /*!
 

- @page datetime_overview Date and time classes overview
+ @page overview_datetime Date and time classes overview

 
  Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl
 
  Classes: #wxDateTime, #wxDateSpan, #wxTimeSpan, #wxCalendarCtrl

- #Introduction
- @ref alldatetimeclasses_overview
- @ref datetimecharacteristics_overview
- @ref dateandtimespansdifference_overview
- @ref tdatearithm_overview
- @ref tdatetimezones_overview
- #Daylight saving time (DST)
- @ref tdateholidays_overview
- #Compatibility
-
-
- @section introductiontowxdatetime Introduction
-
- wxWidgets provides a set of powerful classes to work with dates and times. Some
- of the supported features of #wxDateTime class are:
-
-
-
-
-
-
-
- Wide range
-
-
-
-
- The range of supported dates goes from about 4714 B.C. to
- some 480 million years in the future.
-
-
-
-
-
- Precision
-
-
-
-
- Not using floating point calculations anywhere ensures that
- the date calculations don't suffer from rounding errors.
-

 
 

+ @li @ref overview_datetime_introduction
+ @li @ref overview_datetime_classes
+ @li @ref overview_datetime_characteristics
+ @li @ref overview_datetime_timespandiff
+ @li @ref overview_datetime_arithmetics
+ @li @ref overview_datetime_timezones
+ @li @ref overview_datetime_dst
+ @li @ref overview_datetime_holidays
+ @li @ref overview_datetime_compat

 
 
 
 

+ <hr>

 
 

- Many features
-
-
-
-
- Not only all usual calculations with dates are supported,
- but also more exotic week and year day calculations, work day testing, standard
- astronomical functions, conversion to and from strings in either strict or free
- format.
-
-
-
-
-
- Efficiency

 
 

+ @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:

 
 

+ @li Wide range: the range of supported dates goes from about 4714 B.C. to
+     some 480 million years in the future.

 
 

- Objects of wxDateTime are small (8 bytes) and working with
- them is fast
+ @li Precision: not using floating point calculations anywhere ensures that
+     the date calculations don't suffer from rounding errors.

 
 

+ @li Many features: not only all usual calculations with dates are supported,
+     but also more exotic week and year day calculations, work day testing, standard
+     astronomical functions, conversion to and from strings in either strict or free
+    format.

 
 

+ @li Efficiency: objects of wxDateTime are small (8 bytes) and working with
+     them is fast

 
 
 
 
 
 

+ @section overview_datetime_classes All date/time classes at a glance

 
 

- @section alldatetimeclasses All date/time classes at a glance
+ There are 3 main classes declared in @c wx/datetime.h: except #wxDateTime itself 
+ which represents an absolute moment in time, there are also two classes -
+ #wxTimeSpan and #wxDateSpan - which represent the intervals of time.

 
 

- There are 3 main classes declared in @c wx/datetime.h: except
- #wxDateTime itself which represents an absolute
- moment in time, there are also two classes -
- #wxTimeSpan and #wxDateSpan - which
- represent the intervals of time.

  There are also helper classes which are used together with wxDateTime:
  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.
  class for which (only) Saturdays and Sundays are the holidays. See more about
  these classes in the discussion of the #holidays.

+

  Finally, in other parts of this manual you may find mentions of wxDate and
  Finally, in other parts of this manual you may find mentions of wxDate and

- wxTime classes. @ref tdatecompatibility_overview are obsolete and
+ wxTime classes. @ref overview_datetime_compat are obsolete and

  superseded by wxDateTime.
 
  superseded by wxDateTime.
 

- @section wxdatetimecharacteristics wxDateTime characteristics
+
+
+ @section overview_datetime_characteristics wxDateTime characteristics

 
  #wxDateTime stores the time as a signed number of
  milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
 
  #wxDateTime stores the time as a signed number of
  milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -


@@ -109,15 +73,17 @@
  the Epoch are handled just as well (or as bad) as the dates after it). But it
  does mean that the best resolution which can be achieved with this class is 1
  millisecond.
  the Epoch are handled just as well (or as bad) as the dates after it). But it
  does mean that the best resolution which can be achieved with this class is 1
  millisecond.

+

  The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
  integer. The resulting range of supported dates is thus approximatively 580
  million years, but due to the current limitations in the Gregorian calendar
  support, only dates from Nov 24, 4714BC are supported (this is subject to
  change if there is sufficient interest in doing it).
  The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
  integer. The resulting range of supported dates is thus approximatively 580
  million years, but due to the current limitations in the Gregorian calendar
  support, only dates from Nov 24, 4714BC are supported (this is subject to
  change if there is sufficient interest in doing it).

+

  Finally, the internal representation is time zone independent (always in GMT)
  and the time zones only come into play when a date is broken into
  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.
+

  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
  first done on Oct 15, 1582 but is, generally speaking, country, and even
  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
  first done on Oct 15, 1582 but is, generally speaking, country, and even


@@ -125,20 +91,25 @@
  as well and support for other calendars (Maya, Hebrew, Chinese...) is not
  ruled out.
 
  as well and support for other calendars (Maya, Hebrew, Chinese...) is not
  ruled out.
 

- @section dateandtimespansdifference Difference between wxDateSpan and wxTimeSpan
+
+
+ @section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan

 
  While there is only one logical way to represent an absolute moment in the
  time (and hence only one wxDateTime class), there are at least two methods to
  describe a time interval.
 
  While there is only one logical way to represent an absolute moment in the
  time (and hence only one wxDateTime class), there are at least two methods to
  describe a time interval.

+

  First, there is the direct and self-explaining way implemented by
  #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.
  First, there is the direct and self-explaining way implemented by
  #wxTimeSpan: it is just a difference in milliseconds
  between two moments in time. Adding or subtracting such an interval to
  wxDateTime is always well-defined and is a fast operation.

+

  But in the daily life other, calendar-dependent time interval specifications are
  used. For example, 'one month later' is commonly used. However, it is clear
  that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one
  month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
  the year is leap or not).
  But in the daily life other, calendar-dependent time interval specifications are
  used. For example, 'one month later' is commonly used. However, it is clear
  that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one
  month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
  the year is leap or not).

+

  This is why there is another class for representing such intervals called
  #wxDateSpan. It handles these sort of operations in the
  most natural way possible, but note that manipulating with intervals of
  This is why there is another class for representing such intervals called
  #wxDateSpan. It handles these sort of operations in the
  most natural way possible, but note that manipulating with intervals of


@@ -148,82 +119,47 @@
  still might be surprised to notice that now subtracting back the same
  interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
  with!
  still might be surprised to notice that now subtracting back the same
  interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
  with!

+

  So, unless you plan to implement some kind of natural language parsing in the
  program, you should probably use wxTimeSpan instead of wxDateSpan (which is
  also more efficient). However, wxDateSpan may be very useful in situations
  when you do need to understand what 'in a month' means (of course, it is
  just @c wxDateTime::Now() + wxDateSpan::Month()).
 
  So, unless you plan to implement some kind of natural language parsing in the
  program, you should probably use wxTimeSpan instead of wxDateSpan (which is
  also more efficient). However, wxDateSpan may be very useful in situations
  when you do need to understand what 'in a month' means (of course, it is
  just @c wxDateTime::Now() + wxDateSpan::Month()).
 

- @section tdatearithm Date arithmetics
+
+
+ @section overview_datetime_arithmetics Date arithmetics

 
  Many different operations may be performed with the dates, however not all of
  them make sense. For example, multiplying a date by a number is an invalid
  operation, even though multiplying either of the time span classes by a number
  is perfectly valid.
 
  Many different operations may be performed with the dates, however not all of
  them make sense. For example, multiplying a date by a number is an invalid
  operation, even though multiplying either of the time span classes by a number
  is perfectly valid.

- Here is what can be done:

 
 

+ Here is what can be done:

 
 

+ @li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime
+     resulting in a new wxDateTime object and also 2 objects of the same span class
+     can be added together giving another object of the same class.

 
 

+ @li @b Subtraction: the same types of operations as above are
+     allowed and, additionally, a difference between two wxDateTime objects can be
+     taken and this will yield wxTimeSpan.

 
 

+ @li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
+     multiplied by an integer number resulting in an object of the same type.

 
 

-
- @b Addition
-
-
-
-
- a wxTimeSpan or wxDateSpan can be added to wxDateTime
- resulting in a new wxDateTime object and also 2 objects of the same span class
- can be added together giving another object of the same class.
-
-
-
-
-
- @b Subtraction
-
-
-
-
- the same types of operations as above are
- allowed and, additionally, a difference between two wxDateTime objects can be
- taken and this will yield wxTimeSpan.
-
-
-
-
-
- @b Multiplication
-
-
-
-
- a wxTimeSpan or wxDateSpan object can be
- multiplied by an integer number resulting in an object of the same type.
-
-
-
-
-
- @b Unary minus
-
-
-
-
- a wxTimeSpan or wxDateSpan object may finally be
- negated giving an interval of the same magnitude but of opposite time
- direction.
-
-
-
-
+ @li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
+     negated giving an interval of the same magnitude but of opposite time
+     direction.

 
  For all these operations there are corresponding global (overloaded) operators
  and also member functions which are synonyms for them: Add(), Subtract() and
  Multiply(). Unary minus as well as composite assignment operations (like +=)
  are only implemented as members and Neg() is the synonym for unary minus.
 
 
  For all these operations there are corresponding global (overloaded) operators
  and also member functions which are synonyms for them: Add(), Subtract() and
  Multiply(). Unary minus as well as composite assignment operations (like +=)
  are only implemented as members and Neg() is the synonym for unary minus.
 

- @section tdatetimezones Time zone considerations
+
+
+ @section overview_datetime_timezones Time zone considerations

 
  Although the time is always stored internally in GMT, you will usually work in
  the local time zone. Because of this, all wxDateTime constructors and setters
 
  Although the time is always stored internally in GMT, you will usually work in
  the local time zone. Because of this, all wxDateTime constructors and setters


@@ -234,28 +170,31 @@
  second...) will also return the correct values for the local time zone by
  default, so, generally, doing the natural things will lead to natural and
  correct results.
  second...) will also return the correct values for the local time zone by
  default, so, generally, doing the natural things will lead to natural and
  correct results.

+

  If you only want to do this, you may safely skip the rest of this section.
  However, if you want to work with different time zones, you should read it to
  the end.
  If you only want to do this, you may safely skip the rest of this section.
  However, if you want to work with different time zones, you should read it to
  the end.

+

  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.
  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 #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.
+

  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
  methods which are affected by the time zone (all methods getting date
  components and the date formatting ones, for example). In particular, the
  Format() family of methods accepts a TimeZone parameter and this allows to
  simply print time in any time zone.
  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
  methods which are affected by the time zone (all methods getting date
  components and the date formatting ones, for example). In particular, the
  Format() family of methods accepts a TimeZone parameter and this allows to
  simply print time in any time zone.

+

  To see how to do it, the last issue to address is how to construct a TimeZone
  object which must be passed to all these methods. First of all, you may construct
  it manually by specifying the time zone offset in seconds from GMT, but
  To see how to do it, the last issue to address is how to construct a TimeZone
  object which must be passed to all these methods. First of all, you may construct
  it manually by specifying the time zone offset in seconds from GMT, but

- usually you will just use one of the @ref datetime_overview and
+ usually you will just use one of the @ref overview_datetime and

  let the conversion constructor do the job.
  let the conversion constructor do the job.

+

  I.e. you would just write
 
  @code
  I.e. you would just write
 
  @code


@@ -265,33 +204,39 @@
  @endcode
 
 
  @endcode
 
 

- @section tdatedst Daylight saving time (DST)
+
+ @section overview_datetime_dst Daylight saving time (DST)

 
  DST (a.k.a. 'summer time') handling is always a delicate task which is better
  left to the operating system which is supposed to be configured by the
  administrator to behave correctly. Unfortunately, when doing calculations with
  date outside of the range supported by the standard library, we are forced to
  deal with these issues ourselves.
 
  DST (a.k.a. 'summer time') handling is always a delicate task which is better
  left to the operating system which is supposed to be configured by the
  administrator to behave correctly. Unfortunately, when doing calculations with
  date outside of the range supported by the standard library, we are forced to
  deal with these issues ourselves.

+

  Several functions are provided to calculate the beginning and end of DST in
  the given year and to determine whether it is in effect at the given moment or
  not, but they should not be considered as absolutely correct because, first of
  all, they only work more or less correctly for only a handful of countries
  (any information about other ones appreciated!) and even for them the rules
  may perfectly well change in the future.
  Several functions are provided to calculate the beginning and end of DST in
  the given year and to determine whether it is in effect at the given moment or
  not, but they should not be considered as absolutely correct because, first of
  all, they only work more or less correctly for only a handful of countries
  (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 use these functions
  too, so they are subject to the same limitations.
 

- @section tdateholidays wxDateTime and Holidays
+
+
+ @section overview_datetime_holidays wxDateTime and Holidays

 
  TODO.
 
 
  TODO.
 

- @section tdatecompatibility Compatibility
+
+
+ @section overview_datetime_compat Compatibility

 
  The old classes for date/time manipulations ported from wxWidgets version 1.xx
  are still included but are reimplemented in terms of wxDateTime. However, using
  them is strongly discouraged because they have a few quirks/bugs and were not
  'Y2K' compatible.
 
 
  The old classes for date/time manipulations ported from wxWidgets version 1.xx
  are still included but are reimplemented in terms of wxDateTime. However, using
  them is strongly discouraged because they have a few quirks/bugs and were not
  'Y2K' compatible.
 

- */
-
+*/

 
 

diff --git a/docs/doxygen/overviews/dc.h b/docs/doxygen/overviews/dc.h
index bfcbc7275ae2990ae4f0cbc14b7b86b4321d2664..69c496d21788fe5b0d9dcc23331327cd442386b5 100644 (file)
--- a/docs/doxygen/overviews/dc.h
+++ b/docs/doxygen/overviews/dc.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        dc
+// Name:        dc.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,35 +8,34 @@
 
 /*!
 
 
 /*!
 

- @page dc_overview Device context overview
+ @page overview_dc Device context overview

 
  Classes: #wxBufferedDC, #wxBufferedPaintDC, #wxDC, #wxPostScriptDC,
 
  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. The following describes the differences between
- these device contexts and when you should use them.
-
+          #wxMetafileDC, #wxMemoryDC, #wxPrinterDC, #wxScreenDC, #wxClientDC, 
+          #wxPaintDC, #wxWindowDC.

 
 

-  @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
-  @b wxClientDC. Use this to paint on the client area of window (the part without
- borders and other decorations), but do not use it from within an #wxPaintEvent.
-  @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
- within a #wxPaintEvent.
-  @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
- This may not be available on non-Windows platforms.
+ 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. 
+ 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.
+ @li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
+     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.

 
  To use a client, paint or window device context, create an object on the stack with
  the window as argument, for example:
 
  @code
 
  To use a client, paint or window device context, create an object on the stack with
  the window as argument, for example:
 
  @code

- void MyWindow::OnMyCmd(wxCommandEvent& event)
+   void MyWindow::OnMyCmd(wxCommandEvent& event)

    {
      wxClientDC dc(window);
      DrawMyPicture(dc);
    {
      wxClientDC dc(window);
      DrawMyPicture(dc);


@@ -48,6 +47,5 @@
  work for everything (for example not all device contexts support bitmap drawing) but
  will work most of the time.
 
  work for everything (for example not all device contexts support bitmap drawing) but
  will work most of the time.
 

- */
-
+*/

 
 

diff --git a/docs/doxygen/overviews/debugging.h b/docs/doxygen/overviews/debugging.h
index 3274dc9cba7a0a2e12e20c18ef0bd24d54e476d6..fbac7ff7c7cdb62a8b1b43048ffe479a496e7e8c 100644 (file)
--- a/docs/doxygen/overviews/debugging.h
+++ b/docs/doxygen/overviews/debugging.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        debugging
+// Name:        debugging.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,22 +8,29 @@
 
 /*!
 
 
 /*!
 

- @page debugging_overview Debugging overview
+ @page overview_debugging Debugging overview

 
  Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
 
  Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,

- @ref logfunctions_overview, @ref debugmacros_overview
+ @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,
  your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
  defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
  code that should be active only in debug mode.
  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,
  your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
  defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
  code that should be active only in debug mode.

- @b wxDebugContext
+
+
+
+ @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.
+ 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.
+

  It is good practice to define a wxObject::Dump member function for each class you derive
  from a wxWidgets class, so that wxDebugContext::Dump can call it and
  give valuable information about the state of the application.
  It is good practice to define a wxObject::Dump member function for each class you derive
  from a wxWidgets class, so that wxDebugContext::Dump can call it and
  give valuable information about the state of the application.

+

  If you have difficulty tracking down a memory leak, recompile
  in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
  appropriate places. They will tell you what objects have not yet been
  If you have difficulty tracking down a memory leak, recompile
  in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
  appropriate places. They will tell you what objects have not yet been


@@ -32,70 +39,80 @@
  will give you information about the problem. (How much information depends on the operating system
  and compiler -- some systems don't allow all memory logging to be enabled). See the
  memcheck sample for example of usage.
  will give you information about the problem. (How much information depends on the operating system
  and compiler -- some systems don't allow all memory logging to be enabled). See the
  memcheck sample for example of usage.

- For wxDebugContext to do its work, the @e new and @e delete
- operators for wxObject have been redefined to store extra information
- about dynamically allocated objects (but not statically declared
- objects). This slows down a debugging version of an application, but can
+
+ For wxDebugContext to do its work, the @e new and @e delete operators for wxObject 
+ have been redefined to store extra information about dynamically allocated objects 
+ (but not statically declared objects). 
+
+ This slows down a debugging version of an application, but can

  find difficult-to-detect memory leaks (objects are not
  deallocated), overwrites (writing past the end of your object) and
  underwrites (writing to memory in front of the object).
  find difficult-to-detect memory leaks (objects are not
  deallocated), overwrites (writing past the end of your object) and
  underwrites (writing to memory in front of the object).

+

  If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
  wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
 
  If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
  wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
 

-

  @code
  #define new new(__FILE__,__LINE__)
  @endcode
 
  All occurrences of 'new' in wxWidgets and your own application will use
  @code
  #define new new(__FILE__,__LINE__)
  @endcode
 
  All occurrences of 'new' in wxWidgets and your own application will use

- the overridden form of the operator with two extra arguments. This means that the debugging
- output (and error messages reporting memory problems) will tell you what
+ the overridden form of the operator with two extra arguments. This means that 
+ the debugging output (and error messages reporting memory problems) will tell you what

  file and on what line you allocated the object. Unfortunately not all
  compilers allow this definition to work properly, but most do.
  file and on what line you allocated the object. Unfortunately not all
  compilers allow this definition to work properly, but most do.

- @b Debug macros
+
+
+
+ @section overview_debugging_dbgmacros Debug macros
+

  You should also use @ref debugmacros_overview as part of a 'defensive programming' strategy,
  You should also use @ref debugmacros_overview as part of a 'defensive programming' strategy,

- scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking
- will save a surprising amount of time in the long run.
+ scattering wxASSERTs liberally to test for problems in your code as early as possible.
+ Forward thinking will save a surprising amount of time in the long run.
+

  #wxASSERT is used to pop up an error message box when a condition
  is not @true. You can also use #wxASSERT_MSG to supply your
  own helpful error message. For example:
 
  #wxASSERT is used to pop up an error message box when a condition
  is not @true. You can also use #wxASSERT_MSG to supply your
  own helpful error message. For example:
 

-

  @code
  @code

- void MyClass::MyFunction(wxObject* object)
+   void MyClass::MyFunction(wxObject* object)

    {
    {

-       wxASSERT_MSG( (object != @NULL), "object should not be @NULL in MyFunction!" );
+       wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" );

 
        ...
    };
  @endcode
 
 
        ...
    };
  @endcode
 

-

  The message box allows you to continue execution or abort the program. If you are running
  the application inside a debugger, you will be able to see exactly where the problem was.
  The message box allows you to continue execution or abort the program. If you are running
  the application inside a debugger, you will be able to see exactly where the problem was.

- @b Logging functions
- You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in debug mode;
- it will do nothing for non-debugging code.
- @ref debugcontext_overview

 
 
 
 

- @section wxdebugcontextoverview wxDebugContext overview

 
 

- @ref debugging_overview
+ @section overview_debugging_logging Logging functions
+
+ You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in 
+ debug mode; it will do nothing for non-debugging code.
+
+
+
+ @section overview_debugging_dbgctx2 wxDebugContext overview
+

  Class: #wxDebugContext
  Class: #wxDebugContext

- wxDebugContext is a class for performing various debugging and memory tracing
- operations.
+
+ wxDebugContext is a class for performing various debugging and memory tracing operations.
+

  This class has only static data and function members, and there should be
  no instances. Probably the most useful members are SetFile (for directing output
  to a file, instead of the default standard error or debugger output);
  Dump (for dumping the dynamically allocated objects) and PrintStatistics
  (for dumping information about allocation of objects). You can also call
  Check to check memory blocks for integrity.
  This class has only static data and function members, and there should be
  no instances. Probably the most useful members are SetFile (for directing output
  to a file, instead of the default standard error or debugger output);
  Dump (for dumping the dynamically allocated objects) and PrintStatistics
  (for dumping information about allocation of objects). You can also call
  Check to check memory blocks for integrity.

+

  Here's an example of use. The SetCheckpoint ensures that only the
  allocations done after the checkpoint will be dumped.
 
  @code
  Here's an example of use. The SetCheckpoint ensures that only the
  allocations done after the checkpoint will be dumped.
 
  @code

- wxDebugContext::SetCheckpoint();
+   wxDebugContext::SetCheckpoint();

 
    wxDebugContext::SetFile("c:\\temp\\debug.log");
 
 
    wxDebugContext::SetFile("c:\\temp\\debug.log");
 


@@ -111,9 +128,9 @@
  at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
  in non-debug mode because you may not wish to recompile wxWidgets and your entire application
  just to make use of the error logging facility.
  at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
  in non-debug mode because you may not wish to recompile wxWidgets and your entire application
  just to make use of the error logging facility.

- Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead.
- Eventually the logging will be done through the wxLog facilities instead.

 
 

- */
+ @note wxDebugContext::SetFile has a problem at present, so use the default stream instead.
+       Eventually the logging will be done through the wxLog facilities instead.

 
 

+*/

 
 

diff --git a/docs/doxygen/overviews/dialog.h b/docs/doxygen/overviews/dialog.h
index 17c8e291030da90bf975858a0c94974d632aee02..bc01b3b4ace1cffde265427d3f183ffce91138c4 100644 (file)
--- a/docs/doxygen/overviews/dialog.h
+++ b/docs/doxygen/overviews/dialog.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        dialog
+// Name:        dialog.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,96 +8,121 @@
 
 /*!
 
 
 /*!
 

- @page dialog_overview wxDialog overview
+ @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:
 
  A dialog box is similar to a panel, in that it is a window which can
  be used for placing controls, with the following exceptions:
 

-
-  A surrounding frame is implicitly created.
-  Extra functionality is automatically given to the dialog box,
-   such as tabbing between items (currently Windows only).
-  If the dialog box is @e modal, the calling program is blocked
-   until the dialog box is dismissed.
-
+ @li A surrounding frame is implicitly created.
+ @li Extra functionality is automatically given to the dialog box,
+     such as tabbing between items (currently Windows only).
+ @li If the dialog box is @e modal, the calling program is blocked
+     until the dialog box is dismissed.

 
  For a set of dialog convenience functions, including file selection, see
 
  For a set of dialog convenience functions, including file selection, see

- @ref dialogfunctions_overview.
+ @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 validator_overview.
- @ref autoscrollingdialogs_overview
+ member functions. Validation of data in controls is covered in @ref overview_validator.
+
+

 
 

+ @section overview_dialog_autoscrolling Automatic scrolling dialogs

 
 

- @section autoscrollingdialogs Automatic scrolling dialogs
+ As an ever greater variety of mobile hardware comes to market, it becomes more 
+ imperative for wxWidgets applications to adapt to these platforms without putting 
+ too much burden on the programmer. One area where wxWidgets can help is in adapting
+ dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
+ wxDialog therefore supplies a global #wxDialogLayoutAdapter class that implements 
+ automatic scrolling adaptation for most sizer-based custom dialogs.
+
+ Many applications should therefore be able to adapt to small displays with little 
+ or no work, as far as dialogs are concerned.
+ By default this adaptation is off. To switch scrolling adaptation on globally in 
+ your application, call the static function wxDialog::EnableLayoutAdaptation passing @true.
+ You can also adjust adaptation on a per-dialog basis by calling
+ wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT 
+ (use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.

 
 

- As an ever greater variety of mobile hardware comes to market, it becomes more imperative for wxWidgets applications to adapt
- to these platforms without putting too much burden on the programmer. One area where wxWidgets can help is in adapting
- dialogs for the lower resolution screens that inevitably accompany a smaller form factor. wxDialog therefore supplies
- a global #wxDialogLayoutAdapter class that implements automatic scrolling adaptation for most sizer-based custom dialogs.
- Many applications should therefore be able to adapt to small displays with little or no work, as far as dialogs are concerned.
- By default this adaptation is off. To switch scrolling adaptation on globally in your application, call the static function
- wxDialog::EnableLayoutAdaptation passing @true. You can also adjust adaptation on a per-dialog basis by calling
- wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT (use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.

  The last two modes override the global adaptation setting.
  With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
  The last two modes override the global adaptation setting.
  With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the

- standard adapter class wxStandardDialogLayoutAdapter) will
- make part of the dialog scrolling, leaving standard buttons in a non-scrolling part at the bottom of the dialog.
- This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or wxDialog::ShowModal:
-
-
-  If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, the pages are made scrollable and
- no other adaptation is done.
-  wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
-  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.
-  If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer) and adds them to a #wxStdDialogButtonSizer.
- If no standard buttons were found, the whole dialog content will scroll.
-  All the children apart from standard buttons are reparented onto a new #wxScrolledWindow object,
- using the old top-level sizer for the scrolled window and creating a new top-level sizer to lay out the scrolled window and
- standard button sizer.
-
-
- @b Customising scrolling adaptation
- In addition to switching adaptation on and off globally and per dialog, you can choose how aggressively wxWidgets will
- search for standard buttons by setting wxDialog::SetLayoutAdaptationLevel. By default,
- all the steps described above will be performed but by setting the level to 1, for example, you can choose to only look for wxStdDialogButtonSizer.
+ standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
+ leaving standard buttons in a non-scrolling part at the bottom of the dialog.
+ This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from 
+ within wxDialog::Show or wxDialog::ShowModal:
+
+ @li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase, 
+     the pages are made scrollable and no other adaptation is done.
+ @li wxWidgets looks for a #wxStdDialogButtonSizer and uses it for the non-scrolling part.
+ @li If that search failed, wxWidgets looks for a horizontal #wxBoxSizer with one or more
+     standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
+ @li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
+     and adds them to a #wxStdDialogButtonSizer.
+     If no standard buttons were found, the whole dialog content will scroll.
+ @li All the children apart from standard buttons are reparented onto a new #wxScrolledWindow 
+     object, using the old top-level sizer for the scrolled window and creating a new top-level 
+     sizer to lay out the scrolled window and standard button sizer.
+
+
+ @subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
+
+ In addition to switching adaptation on and off globally and per dialog, 
+ you can choose how aggressively wxWidgets will search for standard buttons by setting
+ wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above will be 
+ performed but by setting the level to 1, for example, you can choose to only look for 
+ wxStdDialogButtonSizer.
+

  You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
  treated as standard buttons for the non-scrolling area.
  You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
  treated as standard buttons for the non-scrolling area.

+

  You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
  wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
  You can derive your own class from #wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
  wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override

- the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability and perform the adaptation.
- You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation in a class derived from wxDialog.
- @b Situations where automatic scrolling adaptation may fail
- Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations.
+ the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
+ and perform the adaptation.
+
+ You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation 
+ in a class derived from wxDialog.
+

 
 

+ @subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail

 
 

-  The dialog doesn't use sizers.
-  The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class.
-  The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally,
- you can derive a new adapter class from wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return an instance of your own class.
-  The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls.
-  The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However, the original sizer hierarchy will still hold
- until Show or ShowModal is called.
+ Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
+ and may fail in the following situations:

 
 

+ @li The dialog doesn't use sizers.
+ @li The dialog implementation makes assumptions about the window hierarchy,
+     for example getting the parent of a control and casting to the dialog class.
+ @li The dialog does custom painting and/or event handling not handled by the scrolled window. 
+     If this problem can be solved globally, you can derive a new adapter class from
+     wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return 
+     an instance of your own class.
+ @li The dialog has unusual layout, for example a vertical sizer containing a mixture of 
+     standard buttons and other controls.
+ @li The dialog makes assumptions about the sizer hierarchy, for example to show or hide 
+     children of the top-level sizer. However, the original sizer hierarchy will still hold
+     until Show or ShowModal is called.

 
  You can help make sure that your dialogs will continue to function after adaptation by:
 
 
  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 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;
+ @li overriding wxDialog::GetContentWindow to return a book control if your dialog implements 
+     pages: wxWidgets will then only make the pages scrollable.

 
 

-  avoiding the above situations and assumptions;
-  using #wxStdDialogButtonSizer;
-  only making assumptions about hierarchy immediately after the dialog is created;
-  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;
-  overriding wxDialog::GetContentWindow to return a book control if your dialog implements pages: wxWidgets will then only make the pages
- scrollable.

 
 

+ @subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard

 
 

- @b wxPropertySheetDialog and wxWizard
- Adaptation for wxPropertySheetDialog is always done by simply making the pages scrollable, since wxDialog::GetContentWindow returns
- the dialog's book control and this is handled by the standard layout adapter.
- wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather than the global adapter: again, only the wizard pages are made scrollable.
+ Adaptation for wxPropertySheetDialog is always done by simply making the pages 
+ scrollable, since wxDialog::GetContentWindow returns the dialog's book control and 
+ this is handled by the standard layout adapter.

 
 

- */
+ wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather 
+ than the global adapter: again, only the wizard pages are made scrollable.

 
 

+*/

 
 

diff --git a/docs/doxygen/overviews/dnd.h b/docs/doxygen/overviews/dnd.h
index d60b9a962177b1554ec9c7fcda739d9fd7af6cb4..0a8c6ece37d83e1da141a0c770fbc73aae456b74 100644 (file)
--- a/docs/doxygen/overviews/dnd.h
+++ b/docs/doxygen/overviews/dnd.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        dnd
+// Name:        dnd.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,90 +8,88 @@
 
 /*!
 
 
 /*!
 

- @page dnd_overview Drag and drop overview
+ @page overview_dnd Drag and drop overview

 
 

- Classes: #wxDataObject,
- #wxTextDataObject,
- #wxDropSource,
- #wxDropTarget,
- #wxTextDropTarget,
- #wxFileDropTarget
- Note that wxUSE_DRAG_AND_DROP must be defined in setup.h in order
+ 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.
  to use drag and drop in wxWidgets.

- See also: @ref dataobject_overview and @ref samplednd_overview
+
+ See also: @ref overview_dataobject and @ref samplednd_overview.
+

  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
  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:
 
  To be a @e drag source, i.e. to provide the data which may be dragged by
  the user elsewhere, you should implement the following steps:
 

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

 
 

diff --git a/docs/doxygen/overviews/docview.h b/docs/doxygen/overviews/docview.h
index dd35e477bc686449d48d35ddd082f662cd655198..1749361d4cf77871adae2789423bdcf0ba3b10bd 100644 (file)
--- a/docs/doxygen/overviews/docview.h
+++ b/docs/doxygen/overviews/docview.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        docview
+// Name:        docview.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,141 +8,160 @@
 
 /*!
 
 
 /*!
 

- @page docview_overview Document/view overview
+ @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.
  The document/view framework is found in most application frameworks, because it
  can dramatically simplify the code required to build many kinds of application.

+

  The idea is that you can model your application primarily in terms of @e documents to store data
  and provide interface-independent operations upon it, and @e views to visualise and manipulate
  the data. Documents know how to do input and output given stream objects, and views are responsible
  for taking input from physical windows and performing the manipulation on the document data.
  The idea is that you can model your application primarily in terms of @e documents to store data
  and provide interface-independent operations upon it, and @e views to visualise and manipulate
  the data. Documents know how to do input and output given stream objects, and views are responsible
  for taking input from physical windows and performing the manipulation on the document data.

+

  If a document's data changes, all views should be updated to reflect the change.
  If a document's data changes, all views should be updated to reflect the change.

- The framework can provide many user-interface elements based on this model. Once you have defined
- your own classes and the relationships between them, the framework takes care
- of popping up file selectors, opening and closing files, asking the user to save
+ The framework can provide many user-interface elements based on this model.
+
+ Once you have defined your own classes and the relationships between them, the framework 
+ takes care of popping up file selectors, opening and closing files, asking the user to save

  modifications, routing menu commands to appropriate (possibly default) code, even
  some default print/preview functionality and support for command undo/redo.
  modifications, routing menu commands to appropriate (possibly default) code, even
  some default print/preview functionality and support for command undo/redo.

+

  The framework is highly modular, allowing overriding and replacement of functionality
  and objects to achieve more than the default behaviour.
  The framework is highly modular, allowing overriding and replacement of functionality
  and objects to achieve more than the default behaviour.

- These are the overall steps involved in creating an application based on the document/view framework:
-
-
-  Define your own document and view classes, overriding a minimal set of
- member functions e.g. for input/output, drawing and initialization.
-  Define any subwindows
- (such as a scrolled window) that are needed for the view(s). You may need to route some events
- to views or documents, for example OnPaint needs to be routed to wxView::OnDraw.
-  Decide what style of interface you will use: Microsoft's MDI (multiple
- document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
- for each document), or single-window (one document open at a time, as in Windows Write).
-  Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
- of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
- you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
-  Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
- as many wxDocTemplate instances as necessary to define relationships between documents and
- views. For a simple application, there will be just one wxDocTemplate.

 
 

+ These are the overall steps involved in creating an application based on the 
+ document/view framework:
+
+ @li Define your own document and view classes, overriding a minimal set of
+     member functions e.g. for input/output, drawing and initialization.
+ @li Define any subwindows (such as a scrolled window) that are needed for the view(s).
+     You may need to route some events to views or documents, for example OnPaint needs 
+     to be routed to wxView::OnDraw.
+ @li Decide what style of interface you will use: Microsoft's MDI (multiple
+     document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
+     for each document), or single-window (one document open at a time, as in Windows Write).
+ @li Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
+     of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
+     you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
+ @li Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
+     as many wxDocTemplate instances as necessary to define relationships between documents and
+     views. For a simple application, there will be just one wxDocTemplate.

 
  If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
  and use wxCommandProcessor::Submit instead of directly executing code. The framework will
  take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and
  wxID_REDO menu items are defined in the view menu.
 
  If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
  and use wxCommandProcessor::Submit instead of directly executing code. The framework will
  take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and
  wxID_REDO menu items are defined in the view menu.

+

  Here are a few examples of the tailoring you can do to go beyond the default framework
  behaviour:
 
  Here are a few examples of the tailoring you can do to go beyond the default framework
  behaviour:
 

-
-  Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
- or a command history editor.
-  Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
- class, to provide multi-page document facilities.
-  Override wxDocManager::SelectDocumentPath to provide a different file selector.
-  Limit the maximum number of open documents and the maximum number of undo commands.
-
+ @li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
+     or a command history editor.
+ @li Override wxView::OnCreatePrintout to create an instance of a derived #wxPrintout
+     class, to provide multi-page document facilities.
+ @li Override wxDocManager::SelectDocumentPath to provide a different file selector.
+ @li Limit the maximum number of open documents and the maximum number of undo commands.

 
  Note that to activate framework functionality, you need to use some or all of
  the wxWidgets @ref predefinedids_overview in your menus.
 
  Note that to activate framework functionality, you need to use some or all of
  the wxWidgets @ref predefinedids_overview in your menus.

- @b wxPerl note: The document/view framework is available in wxPerl. To use it,
- you will need the following statements in your application code:
-

 
 

+ @beginWxPerlOnly
+ The document/view framework is available in wxPerl. To use it,
+ you will need the following statements in your application code:

 
  @code
  use Wx::DocView;
  use Wx ':docview';   # import constants (optional)
  @endcode
 
  @code
  use Wx::DocView;
  use Wx ':docview';   # import constants (optional)
  @endcode

+ @endWxPerlOnly

 
 

+ @li @ref overview_docview_wxdoc
+ @li @ref overview_docview_wxview
+ @li @ref overview_docview_wxdoctemplate
+ @li @ref overview_docview_wxdocmanager
+ @li @ref overview_docview_wxcommand
+ @li @ref overview_docview_wxcommandproc
+ @li @ref overview_docview_filehistory
+ @li @ref overview_docview_predefid

 
 

- @ref document_overview
- @ref view_overview
- @ref doctemplate_overview
- @ref docmanager_overview
- @ref command_overview
- @ref commandprocessor_overview
- @ref filehistory_overview
- @ref predefinedids_overview

 
 

+ <hr>

 
 

- @section wxdocumentoverview wxDocument overview

 
 

- @ref docview_overview
+ @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,
  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,
  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.
+ since a range of menu commands -- such as open, save, save as -- are supported
+ automatically.
+

  The programmer just needs to define a minimal set of classes and member functions
  for the framework to call when necessary. Data, and the means to view and edit
  The programmer just needs to define a minimal set of classes and member functions
  for the framework to call when necessary. Data, and the means to view and edit

- the data, are explicitly separated out in this model, and the concept of multiple @e views onto
- the same data is supported.
+ the data, are explicitly separated out in this model, and the concept of multiple
+ @e views onto the same data is supported.
+

  Note that the document/view model will suit many but not all styles of application.
  For example, it would be overkill for a simple file conversion utility, where there
  may be no call for @e views on @e documents or the ability to open, edit and save
  files. But probably the majority of applications are document-based.
  Note that the document/view model will suit many but not all styles of application.
  For example, it would be overkill for a simple file conversion utility, where there
  may be no call for @e views on @e documents or the ability to open, edit and save
  files. But probably the majority of applications are document-based.

+

  See the example application in @c samples/docview.
  To use the abstract wxDocument class, you need to derive a new class and override
  at least the member functions SaveObject and LoadObject. SaveObject and
  LoadObject will be called by the framework when the document needs to be saved
  or loaded.
  See the example application in @c samples/docview.
  To use the abstract wxDocument class, you need to derive a new class and override
  at least the member functions SaveObject and LoadObject. SaveObject and
  LoadObject will be called by the framework when the document needs to be saved
  or loaded.

+

  Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
  to allow the framework to create document objects on demand. When you create
  a #wxDocTemplate object on application initialization, you
  should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
  so that it knows how to create an instance of this class.
  Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
  to allow the framework to create document objects on demand. When you create
  a #wxDocTemplate object on application initialization, you
  should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
  so that it knows how to create an instance of this class.

+

  If you do not wish to use the wxWidgets method of creating document
  objects dynamically, you must override wxDocTemplate::CreateDocument
  to return an instance of the appropriate class.
 
  If you do not wish to use the wxWidgets method of creating document
  objects dynamically, you must override wxDocTemplate::CreateDocument
  to return an instance of the appropriate class.
 

- @section wxviewoverview wxView overview

 
 

- @ref docview_overview
+
+ @section overview_docview_wxview wxView overview
+

  Class: #wxView
  Class: #wxView

+

  The wxView class can be used to model the viewing and editing component of
  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
+ 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.
  and #wxDocManager classes.

+

  See the example application in @c samples/docview.
  See the example application in @c samples/docview.

+

  To use the abstract wxView class, you need to derive a new class and override
  at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
  want to respond to menu commands from the frame containing the view.
  To use the abstract wxView class, you need to derive a new class and override
  at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
  want to respond to menu commands from the frame containing the view.

+

  Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
  to allow the framework to create view objects on demand. When you create
  a #wxDocTemplate object on application initialization, you
  should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
  so that it knows how to create an instance of this class.
  Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
  to allow the framework to create view objects on demand. When you create
  a #wxDocTemplate object on application initialization, you
  should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
  so that it knows how to create an instance of this class.

+

  If you do not wish to use the wxWidgets method of creating view
  objects dynamically, you must override wxDocTemplate::CreateView
  to return an instance of the appropriate class.
 
  If you do not wish to use the wxWidgets method of creating view
  objects dynamically, you must override wxDocTemplate::CreateView
  to return an instance of the appropriate class.
 

- @section wxdoctemplateoverview wxDocTemplate overview

 
 

- @ref docview_overview
+
+ @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
  template object for each document/view pair. The list of document
  The wxDocTemplate class is used to model the relationship between a
  document class and a view class. The application creates a document
  template object for each document/view pair. The list of document


@@ -150,6 +169,7 @@
  documents and views. Each document template knows what file filters
  and default extension are appropriate for a document/view combination,
  and how to create a document or view.
  documents and views. Each document template knows what file filters
  and default extension are appropriate for a document/view combination,
  and how to create a document or view.

+

  For example, you might write a small doodling application that can load
  and save lists of line segments. If you had two views of the data -- graphical,
  and a list of the segments -- then you would create one document class DoodleDocument,
  For example, you might write a small doodling application that can load
  and save lists of line segments. If you had two views of the data -- graphical,
  and a list of the segments -- then you would create one document class DoodleDocument,


@@ -159,94 +179,112 @@
  document templates, but each would be passed a different view class. When
  the user clicks on the Open menu item, the file selector is displayed
  with a list of possible file filters -- one for each wxDocTemplate. Selecting
  document templates, but each would be passed a different view class. When
  the user clicks on the Open menu item, the file selector is displayed
  with a list of possible file filters -- one for each wxDocTemplate. Selecting

- the filter selects the wxDocTemplate, and when
- a file is selected, that template will be used for creating a document
- and view.
+ the filter selects the wxDocTemplate, and when a file is selected, that template 
+ will be used for creating a document and view.
+

  For the case where an application has one document type and one view type,
  a single document template is constructed, and dialogs will be appropriately
  simplified.
  For the case where an application has one document type and one view type,
  a single document template is constructed, and dialogs will be appropriately
  simplified.

+

  wxDocTemplate is part of the document/view framework supported by wxWidgets,
  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.
  See the example application in @c samples/docview.

+

  To use the wxDocTemplate class, you do not need to derive a new class.
  To use the wxDocTemplate class, you do not need to derive a new class.

- Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) and
- CLASSINFO(YourViewClass) to allow dynamic instance creation.
+ Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass) 
+ and CLASSINFO(YourViewClass) to allow dynamic instance creation.
+

  If you do not wish to use the wxWidgets method of creating document
  objects dynamically, you must override wxDocTemplate::CreateDocument
  and wxDocTemplate::CreateView to return instances of the appropriate class.
  If you do not wish to use the wxWidgets method of creating document
  objects dynamically, you must override wxDocTemplate::CreateDocument
  and wxDocTemplate::CreateView to return instances of the appropriate class.

- @e NOTE: the document template has nothing to do with the C++ template construct.

 
 

- @section wxdocmanageroverview wxDocManager overview
+ @note The document template has nothing to do with the C++ template construct.
+
+
+
+ @section overview_docview_wxdocmanager wxDocManager overview

 
 

- @ref docview_overview

  Class: #wxDocManager
  Class: #wxDocManager

+

  The wxDocManager class is part of the document/view framework supported by wxWidgets,
  The wxDocManager class is part of the document/view framework supported by wxWidgets,

- and cooperates with the #wxView, #wxDocument
- and #wxDocTemplate classes.
- A wxDocManager instance coordinates documents, views and document templates. It keeps a list of document
- and template instances, and much functionality is routed through this object, such
- as providing selection and file dialogs. The application can use this class 'as is' or
- derive a class and override some members to extend or change the functionality.
+ and cooperates with the #wxView, #wxDocument and #wxDocTemplate classes.
+
+ A wxDocManager instance coordinates documents, views and document templates. 
+ It keeps a list of document and template instances, and much functionality is routed 
+ through this object, such as providing selection and file dialogs. 
+ The application can use this class 'as is' or derive a class and override some members 
+ to extend or change the functionality.
+

  Create an instance of this class near the beginning of your application initialization,
  before any documents, views or templates are manipulated.
  Create an instance of this class near the beginning of your application initialization,
  before any documents, views or templates are manipulated.

+

  There may be multiple wxDocManager instances in an application.
  See the example application in @c samples/docview.
 
  There may be multiple wxDocManager instances in an application.
  See the example application in @c samples/docview.
 

- @section wxcommandoverview wxCommand overview

 
 

- @ref docview_overview
+
+ @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
  a toolbar button or any other means provided by the application to
  change the data or view.
  wxCommand is a base class for modelling an application command,
  which is an action usually performed by selecting a menu item, pressing
  a toolbar button or any other means provided by the application to
  change the data or view.

+

  Instead of the application functionality being scattered around
  switch statements and functions in a way that may be hard to
  read and maintain, the functionality for a command is explicitly represented
  as an object which can be manipulated by a framework or application.
  Instead of the application functionality being scattered around
  switch statements and functions in a way that may be hard to
  read and maintain, the functionality for a command is explicitly represented
  as an object which can be manipulated by a framework or application.

+

  When a user interface event occurs, the application @e submits a command
  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
  for wxCommand, such as implementing a macro facility that stores, loads
  and replays commands.
  The wxWidgets document/view framework handles Undo and Redo by use of
  wxCommand and wxCommandProcessor objects. You might find further uses
  for wxCommand, such as implementing a macro facility that stores, loads
  and replays commands.

+

  An application can derive a new class for every command, or, more likely, use
  one class parameterized with an integer or string command identifier.
 
  An application can derive a new class for every command, or, more likely, use
  one class parameterized with an integer or string command identifier.
 

- @section wxcommandprocessoroverview wxCommandProcessor overview

 
 

- @ref docview_overview
+
+ @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
  if you want different behaviour.
 
  wxCommandProcessor is a class that maintains a history of wxCommand
  instances, with undo/redo functionality built-in. Derive a new class from this
  if you want different behaviour.
 

- @section wxfilehistoryoverview wxFileHistory overview

 
 

- @ref docview_overview
+
+ @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.
  Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
  to derive from it to allow different behaviour, such as popping up a scrolling
  list of files.
  wxFileHistory encapsulates functionality to record the last few files visited, and
  to allow the user to quickly load these files using the list appended to the File menu.
  Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
  to derive from it to allow different behaviour, such as popping up a scrolling
  list of files.

- By calling wxFileHistory::UseMenu() you can
- associate a file menu with the file history. The menu will then be used for
- appending filenames that are added to the history. 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
+
+ By calling wxFileHistory::UseMenu() you can associate a file menu with the file history. 
+ The menu will then be used for appending filenames that are added to the history.
+
+ Please notice that currently if the history already contained filenames when UseMenu() 
+ is called (e.g. when initializing a second MDI child frame), the menu is not automatically

  initialized with the existing filenames in the history and so you need to call
  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 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.
+ #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.
+

  In order to respond to a file load command from one of these identifiers,
  you need to handle them using an event handler, for example:
 
  In order to respond to a file load command from one of these identifiers,
  you need to handle them using an event handler, for example:
 

-

  @code
  BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
      EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
  @code
  BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
      EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)


@@ -260,7 +298,7 @@
 
  void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
  {
 
  void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
  {

-       wxString f(m_docManager-GetHistoryFile(event.GetId() - wxID_FILE1));
+       wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));

        if (!f.empty())
          (void)m_docManager-CreateDocument(f, wxDOC_SILENT);
  }
        if (!f.empty())
          (void)m_docManager-CreateDocument(f, wxDOC_SILENT);
  }


@@ -268,13 +306,13 @@
 
 
 
 
 
 

- @section predefinedids wxWidgets predefined command identifiers
+ @section overview_docview_predefid wxWidgets predefined command identifiers

 
  To allow communication between the application's menus and the
  document/view framework, several command identifiers are predefined for you
  to use in menus.
 
 
  To allow communication between the application's menus and the
  document/view framework, several command identifiers are predefined for you
  to use in menus.
 

-
+ @verbatim

   wxID_OPEN (5000)
   wxID_CLOSE (5001)
   wxID_NEW (5002)
   wxID_OPEN (5000)
   wxID_CLOSE (5001)
   wxID_NEW (5002)


@@ -288,7 +326,7 @@
   wxID_PRINT (5010)
   wxID_PRINT_SETUP (5011)
   wxID_PREVIEW (5012)
   wxID_PRINT (5010)
   wxID_PRINT_SETUP (5011)
   wxID_PREVIEW (5012)

+ @endverbatim

 
 

- */
-
+*/

 
 

diff --git a/docs/doxygen/overviews/printing.h b/docs/doxygen/overviews/printing.h
index 25b3c6130538fceafa14c1149a0b9a621fc09500..d0b045b58b28d3e7ee005774ca1957394a111b68 100644 (file)
--- a/docs/doxygen/overviews/printing.h
+++ b/docs/doxygen/overviews/printing.h
@@ -8,7 +8,7 @@
 
 /*!
 
 
 /*!
 

- @page printing_overview Printing overview
+ @page overview_printing Printing overview

 
  Classes: #wxPrintout,
  #wxPrinter,
 
  Classes: #wxPrintout,
  #wxPrinter,