warning fix

[wxWidgets.git] / wxPython / src / _cmndlgs.i

diff --git a/wxPython/src/_cmndlgs.i b/wxPython/src/_cmndlgs.i
index 13cd13edd6c9a952d2e25911e19bb37ca8ab2305..30cefa35bafd5d6115ac56905280e57ec6aeaa4b 100644 (file)
--- a/wxPython/src/_cmndlgs.i
+++ b/wxPython/src/_cmndlgs.i
@@ -27,52 +27,60 @@ MAKE_CONST_WXSTRING(MessageBoxCaptionStr);
 
 
 DocStr(wxColourData,
 
 
 DocStr(wxColourData,

-       "This class holds a variety of information related to colour dialogs.");
+"This class holds a variety of information related to the colour
+chooser dialog, used to transfer settings and results to and from the
+`wx.ColourDialog`.", "");

     
 class wxColourData : public wxObject {
 public:
     DocCtorStr(
         wxColourData(),
     
 class wxColourData : public wxObject {
 public:
     DocCtorStr(
         wxColourData(),

-        "Constructor, sets default values.");
+        "Constructor, sets default values.", "");

     
     ~wxColourData();
 
     
     DocDeclStr(
         bool , GetChooseFull(),
     
     ~wxColourData();
 
     
     DocDeclStr(
         bool , GetChooseFull(),

-        "Under Windows, determines whether the Windows colour dialog will display\n"
-        "the full dialog with custom colour selection controls. Has no meaning\n"
-        "under other platforms.  The default value is true.");
+        "Under Windows, determines whether the Windows colour dialog will
+display the full dialog with custom colour selection controls. Has no
+meaning under other platforms.  The default value is true.", "");

     
     DocDeclStr(
         wxColour , GetColour(),
     
     DocDeclStr(
         wxColour , GetColour(),

-        "Gets the colour (pre)selected by the dialog.");
+        "Gets the colour (pre)selected by the dialog.", "");

     
     DocDeclStr(
         wxColour , GetCustomColour(int i),
     
     DocDeclStr(
         wxColour , GetCustomColour(int i),

-        "Gets the i'th custom colour associated with the colour dialog. i should\n"
-        "be an integer between 0 and 15. The default custom colours are all white.");
+        "Gets the i'th custom colour associated with the colour dialog. i
+should be an integer between 0 and 15. The default custom colours are
+all invalid colours.", "");

     
     DocDeclStr(
         void , SetChooseFull(int flag),
     
     DocDeclStr(
         void , SetChooseFull(int flag),

-        "Under Windows, tells the Windows colour dialog to display the full dialog\n"
-        "with custom colour selection controls. Under other platforms, has no effect.\n"
-        "The default value is true.");
+        "Under Windows, tells the Windows colour dialog to display the full
+dialog with custom colour selection controls. Under other platforms,
+has no effect.  The default value is true.", "");

     
     DocDeclStr(
         void , SetColour(const wxColour& colour),
     
     DocDeclStr(
         void , SetColour(const wxColour& colour),

-        "Sets the default colour for the colour dialog.  The default colour is black.");
+        "Sets the default colour for the colour dialog.  The default colour is
+black.", "");

     
     DocDeclStr(
         void , SetCustomColour(int i, const wxColour& colour),
     
     DocDeclStr(
         void , SetCustomColour(int i, const wxColour& colour),

-        "Sets the i'th custom colour for the colour dialog. i should be an integer\n"
-        "between 0 and 15. The default custom colours are all white.");
+        "Sets the i'th custom colour for the colour dialog. i should be an
+integer between 0 and 15. The default custom colours are all invalid colours.", "");

     
 };
 
 
     
 };
 
 

+
+

 DocStr(wxColourDialog,
 DocStr(wxColourDialog,

-       "This class represents the colour chooser dialog.");
+       "This class represents the colour chooser dialog.", "");
+
+MustHaveApp(wxColourDialog);

 
 class wxColourDialog : public wxDialog {
 public:
 
 class wxColourDialog : public wxDialog {
 public:


@@ -80,12 +88,13 @@ public:
 
    DocCtorStr(
        wxColourDialog(wxWindow* parent, wxColourData* data = NULL),
 
    DocCtorStr(
        wxColourDialog(wxWindow* parent, wxColourData* data = NULL),

-       "Constructor. Pass a parent window, and optionally a ColourData, which\n"
-       "will be copied to the colour dialog's internal ColourData instance.");
+       "Constructor. Pass a parent window, and optionally a `wx.ColourData`,
+which will be copied to the colour dialog's internal ColourData
+instance.", "");

 
     DocDeclStr(
         wxColourData& , GetColourData(),
 
     DocDeclStr(
         wxColourData& , GetColourData(),

-        "Returns a reference to the ColourData used by the dialog.");
+        "Returns a reference to the `wx.ColourData` used by the dialog.", "");

 };
 
 
 };
 
 


@@ -93,14 +102,20 @@ public:
 
 
 DocStr(wxDirDialog,
 
 
 DocStr(wxDirDialog,

-       "This class represents the directory chooser dialog.");
+       "wx.DirDialog allows the user to select a directory by browising the
+file system.", "
+
+Window  Styles
+--------------
+    ====================  ==========================================
+    wx.DD_NEW_DIR_BUTTON  Add 'Create new directory' button and allow
+                          directory names to be editable. On Windows
+                          the new directory button is only available
+                          with recent versions of the common dialogs.
+    ====================  ==========================================
+");

 
 

-RefDoc(wxDirDialog, "
- Styles
-    wxDD_NEW_DIR_BUTTON     Add \"Create new directory\" button and allow
-                            directory names to be editable. On Windows the new
-                            directory button is only available with recent
-                            versions of the common dialogs.");
+MustHaveApp(wxDirDialog);

 
 class wxDirDialog : public wxDialog {
 public:
 
 class wxDirDialog : public wxDialog {
 public:


@@ -114,28 +129,28 @@ public:
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     const wxString& name = wxPyDirDialogNameStr),
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     const wxString& name = wxPyDirDialogNameStr),

-        "Constructor.  Use ShowModal method to show the dialog.");
+        "Constructor.  Use ShowModal method to show the dialog.", "");

 
 
     DocDeclStr(
         wxString , GetPath(),
 
 
     DocDeclStr(
         wxString , GetPath(),

-        "Returns the default or user-selected path.");
+        "Returns the default or user-selected path.", "");

     
     DocDeclStr(
         wxString , GetMessage(),
     
     DocDeclStr(
         wxString , GetMessage(),

-        "Returns the message that will be displayed on the dialog.");
+        "Returns the message that will be displayed on the dialog.", "");

     
     DocDeclStr(
         long , GetStyle(),
     
     DocDeclStr(
         long , GetStyle(),

-        "Returns the dialog style.");
+        "Returns the dialog style.", "");

     
     DocDeclStr(
         void , SetMessage(const wxString& message),
     
     DocDeclStr(
         void , SetMessage(const wxString& message),

-        "Sets the message that will be displayed on the dialog.");
+        "Sets the message that will be displayed on the dialog.", "");

     
     DocDeclStr(
         void , SetPath(const wxString& path),
     
     DocDeclStr(
         void , SetPath(const wxString& path),

-        "Sets the default path.");
+        "Sets the default path.", "");

     
 };
 
     
 };
 


@@ -143,44 +158,52 @@ public:
 //---------------------------------------------------------------------------
 
 DocStr(wxFileDialog,
 //---------------------------------------------------------------------------
 
 DocStr(wxFileDialog,

-       "This class represents the file chooser dialog.");
-
-RefDoc(wxFileDialog, "
-In Windows, 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.
-
-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. The
-wildcard may be a specification for multiple types of file with a description
-for each, such as:
+"wx.FileDialog allows the user to select one or more files from the
+filesystem.", "
+
+In Windows, this is the common file selector dialog. On X based
+platforms a generic alternative is used.  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.
+
+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. The wildcard may be a specification for multiple
+types of file with a description for each, such as::

 
    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
 
 
    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
 

- Styles
-    wx.OPEN              This is an open dialog.

 
 

-    wx.SAVE              This is a save dialog.
+Window  Styles
+--------------
+    ===================   ==========================================
+    wx.OPEN               This is an open dialog.

 
 

-    wx.HIDE_READONLY     For open dialog only: hide the checkbox allowing to
-                         open the file in read-only mode.
+    wx.SAVE               This is a save dialog.

 
 

-    wx.OVERWRITE_PROMPT  For save dialog only: prompt for a confirmation if a
-                         file will be overwritten.
+    wx.HIDE_READONLY      For open dialog only: hide the checkbox
+                          allowing to open the file in read-only mode.

 
 

-    wx.MULTIPLE          For open dialog only: allows selecting multiple files.
+    wx.OVERWRITE_PROMPT   For save dialog only: prompt for a confirmation
+                          if a file will be overwritten.

 
 

-    wx.CHANGE_DIR        Change the current working directory to the directory
-                         where the file(s) chosen by the user are.
+    wx.MULTIPLE           For open dialog only: allows selecting multiple
+                          files.
+
+    wx.CHANGE_DIR         Change the current working directory to the
+                          directory  where the file(s) chosen by the user
+                          are.
+    ===================   ==========================================

 ");
 
 
 
 ");
 
 
 

+MustHaveApp(wxFileDialog);
+

 class wxFileDialog : public wxDialog {
 public:
     %pythonAppend wxFileDialog   "self._setOORInfo(self)"
 class wxFileDialog : public wxDialog {
 public:
     %pythonAppend wxFileDialog   "self._setOORInfo(self)"


@@ -193,81 +216,83 @@ public:
                      const wxString& wildcard = wxPyFileSelectorDefaultWildcardStr,
                      long style = 0,
                      const wxPoint& pos = wxDefaultPosition),
                      const wxString& wildcard = wxPyFileSelectorDefaultWildcardStr,
                      long style = 0,
                      const wxPoint& pos = wxDefaultPosition),

-        "Constructor.  Use ShowModal method to show the dialog.");
+        "Constructor.  Use ShowModal method to show the dialog.", "");

 
 
     DocDeclStr(
         void , SetMessage(const wxString& message),
 
 
     DocDeclStr(
         void , SetMessage(const wxString& message),

-        "Sets the message that will be displayed on the dialog.");
+        "Sets the message that will be displayed on the dialog.", "");

     
     DocDeclStr(
         void , SetPath(const wxString& path),
     
     DocDeclStr(
         void , SetPath(const wxString& path),

-        "Sets the path (the combined directory and filename that will\n"
-        "be returned when the dialog is dismissed).");
+        "Sets the path (the combined directory and filename that will be
+returned when the dialog is dismissed).", "");

     
     DocDeclStr(
         void , SetDirectory(const wxString& dir),
     
     DocDeclStr(
         void , SetDirectory(const wxString& dir),

-        "Sets the default directory.");
+        "Sets the default directory.", "");

     
     DocDeclStr(
         void , SetFilename(const wxString& name),
     
     DocDeclStr(
         void , SetFilename(const wxString& name),

-        "Sets the default filename.");
+        "Sets the default filename.", "");

     
     DocDeclStr(
         void , SetWildcard(const wxString& wildCard),
     
     DocDeclStr(
         void , SetWildcard(const wxString& wildCard),

-        "Sets the wildcard, which can contain multiple file types, for example:\n"
-        "    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"");
+        "Sets the wildcard, which can contain multiple file types, for
+example::
+
+    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
+", "");

     
     DocDeclStr(
         void , SetStyle(long style),
     
     DocDeclStr(
         void , SetStyle(long style),

-        "Sets the dialog style.");
+        "Sets the dialog style.", "");

     
     DocDeclStr(
         void , SetFilterIndex(int filterIndex),
     
     DocDeclStr(
         void , SetFilterIndex(int filterIndex),

-        "Sets the default filter index, starting from zero.");
+        "Sets the default filter index, starting from zero.", "");

     
     

-

     DocDeclStr(
         wxString , GetMessage() const,
     DocDeclStr(
         wxString , GetMessage() const,

-        "Returns the message that will be displayed on the dialog.");
+        "Returns the message that will be displayed on the dialog.", "");

     
     DocDeclStr(
         wxString , GetPath() const,
     
     DocDeclStr(
         wxString , GetPath() const,

-        "Returns the full path (directory and filename) of the selected file.");
+        "Returns the full path (directory and filename) of the selected file.", "");

     
     DocDeclStr(
         wxString , GetDirectory() const,
     
     DocDeclStr(
         wxString , GetDirectory() const,

-        "Returns the default directory.");
+        "Returns the default directory.", "");

     
     DocDeclStr(
         wxString , GetFilename() const,
     
     DocDeclStr(
         wxString , GetFilename() const,

-        "Returns the default filename.");
+        "Returns the default filename.", "");

     
     DocDeclStr(
         wxString , GetWildcard() const,
     
     DocDeclStr(
         wxString , GetWildcard() const,

-        "Returns the file dialog wildcard.");
+        "Returns the file dialog wildcard.", "");

     
     DocDeclStr(
         long , GetStyle() const,
     
     DocDeclStr(
         long , GetStyle() const,

-        "Returns the dialog style.");
+        "Returns the dialog style.", "");

     
     DocDeclStr(
         int , GetFilterIndex() const,
     
     DocDeclStr(
         int , GetFilterIndex() const,

-        "Returns the index into the list of filters supplied, optionally, in\n"
-        "the wildcard parameter. Before the dialog is shown, this is the index\n"
-        "which will be used when the dialog is first displayed. After the dialog\n"
-        "is shown, this is the index selected by the user.");
+        "Returns the index into the list of filters supplied, optionally, in
+the wildcard parameter. Before the dialog is shown, this is the index
+which will be used when the dialog is first displayed. After the
+dialog is shown, this is the index selected by the user.", "");

 
 
     DocStr(GetFilenames,
 
 
     DocStr(GetFilenames,

-        "Returns a list of filenames chosen in the dialog.  This function should\n"
-        "only be used with the dialogs which have wx.MULTIPLE style, use\n"
-        "GetFilename for the others.");
+        "Returns a list of filenames chosen in the dialog.  This function
+should only be used with the dialogs which have wx.MULTIPLE style, use
+GetFilename for the others.", "");

 
     DocStr(GetPaths,
 
     DocStr(GetPaths,

-        "Fills the array paths with the full paths of the files chosen. This\n"
-        "function should only be used with the dialogs which have wx.MULTIPLE style,\n"
-        "use GetPath for the others.");   
+        "Fills the array paths with the full paths of the files chosen. This
+function should only be used with the dialogs which have wx.MULTIPLE
+style, use GetPath for the others.", "");   

     
     %extend {
         PyObject* GetFilenames() {
     
     %extend {
         PyObject* GetFilenames() {


@@ -312,7 +337,9 @@ enum { wxCHOICEDLG_STYLE };
 
 
 DocStr(wxMultiChoiceDialog,
 
 
 DocStr(wxMultiChoiceDialog,

-       "A simple dialog with a multi selection listbox.");
+       "A simple dialog with a multi selection listbox.", "");
+
+MustHaveApp(wxMultiChoiceDialog);

 
 class wxMultiChoiceDialog : public wxDialog
 {
 
 class wxMultiChoiceDialog : public wxDialog
 {


@@ -323,23 +350,24 @@ public:
         wxMultiChoiceDialog(wxWindow *parent,
                             const wxString& message,
                             const wxString& caption,
         wxMultiChoiceDialog(wxWindow *parent,
                             const wxString& message,
                             const wxString& caption,

-                            int choices=0, wxString* choices_array,
+                            int choices=0, wxString* choices_array=NULL,

                             long style = wxCHOICEDLG_STYLE,
                             const wxPoint& pos = wxDefaultPosition),
                             long style = wxCHOICEDLG_STYLE,
                             const wxPoint& pos = wxDefaultPosition),

-        "__init__(Window parent, String message, String caption,\n"
-        "    List choices=[], long style=CHOICEDLG_STYLE,\n"
-        "    Point pos=DefaultPosition) -> MultiChoiceDialog",
-        "Constructor.  Use ShowModal method to show the dialog.");
+        "__init__(Window parent, String message, String caption,
+    List choices=[], long style=CHOICEDLG_STYLE,
+    Point pos=DefaultPosition) -> MultiChoiceDialog",
+        "Constructor.  Use ShowModal method to show the dialog.", "");

 
     
     DocDeclAStr(
         void, SetSelections(const wxArrayInt& selections),
         "SetSelections(List selections)",
 
     
     DocDeclAStr(
         void, SetSelections(const wxArrayInt& selections),
         "SetSelections(List selections)",

-        "Specify the items in the list that shoudl be selected, using a list of integers.");
+        "Specify the items in the list that should be selected, using a list of
+integers.", "");

 
     DocAStr(GetSelections,
             "GetSelections() -> [selections]",
 
     DocAStr(GetSelections,
             "GetSelections() -> [selections]",

-            "Returns a list of integers representing the items that are selected.");
+            "Returns a list of integers representing the items that are selected.", "");

     %extend {
         PyObject* GetSelections() {
             return wxArrayInt2PyList_helper(self->GetSelections());
     %extend {
         PyObject* GetSelections() {
             return wxArrayInt2PyList_helper(self->GetSelections());


@@ -351,17 +379,19 @@ public:
 //---------------------------------------------------------------------------
 
 DocStr(wxSingleChoiceDialog,
 //---------------------------------------------------------------------------
 
 DocStr(wxSingleChoiceDialog,

-       "A simple dialog with a single selection listbox.");
+       "A simple dialog with a single selection listbox.", "");
+
+MustHaveApp(wxSingleChoiceDialog);

 
 class wxSingleChoiceDialog : public wxDialog {
 public:
     %pythonAppend wxSingleChoiceDialog   "self._setOORInfo(self)"
 
     DocAStr(wxSingleChoiceDialog,
 
 class wxSingleChoiceDialog : public wxDialog {
 public:
     %pythonAppend wxSingleChoiceDialog   "self._setOORInfo(self)"
 
     DocAStr(wxSingleChoiceDialog,

-            "__init__(Window parent, String message, String caption,\n"
-            "    List choices=[], long style=CHOICEDLG_STYLE,\n"
-            "    Point pos=DefaultPosition) -> SingleChoiceDialog",
-            "Constructor.  Use ShowModal method to show the dialog.");
+            "__init__(Window parent, String message, String caption,
+    List choices=[], long style=CHOICEDLG_STYLE,
+    Point pos=DefaultPosition) -> SingleChoiceDialog",
+            "Constructor.  Use ShowModal method to show the dialog.", "");

 
     %extend {
         // TODO: ignoring clientData for now...  FIX THIS
 
     %extend {
         // TODO: ignoring clientData for now...  FIX THIS


@@ -380,22 +410,26 @@ public:
 
     DocDeclStr(
         int , GetSelection(),
 
     DocDeclStr(
         int , GetSelection(),

-        "Get the index of teh currently selected item.");
+        "Get the index of teh currently selected item.", "");

     
     DocDeclStr(
         wxString , GetStringSelection(),
     
     DocDeclStr(
         wxString , GetStringSelection(),

-        "Returns the string value of the currently selected item");
+        "Returns the string value of the currently selected item", "");

     
     DocDeclStr(
         void , SetSelection(int sel),
     
     DocDeclStr(
         void , SetSelection(int sel),

-        "Set the current selected item to sel");
+        "Set the current selected item to sel", "");

 };
 
 
 //---------------------------------------------------------------------------
 
 DocStr(wxTextEntryDialog,
 };
 
 
 //---------------------------------------------------------------------------
 
 DocStr(wxTextEntryDialog,

-       "A dialog with text control, [ok] and [cancel] buttons");
+       "A dialog with text control, [ok] and [cancel] buttons", "");
+
+MustHaveApp(wxTextEntryDialog);
+
+enum { wxTextEntryDialogStyle };

 
 class wxTextEntryDialog : public wxDialog {
 public:
 
 class wxTextEntryDialog : public wxDialog {
 public:


@@ -406,25 +440,41 @@ public:
                           const wxString& message,
                           const wxString& caption = wxPyGetTextFromUserPromptStr,
                           const wxString& defaultValue = wxPyEmptyString,
                           const wxString& message,
                           const wxString& caption = wxPyGetTextFromUserPromptStr,
                           const wxString& defaultValue = wxPyEmptyString,

-                          long style = wxOK | wxCANCEL | wxCENTRE,
+                          long style = wxTextEntryDialogStyle,

                           const wxPoint& pos = wxDefaultPosition),
                           const wxPoint& pos = wxDefaultPosition),

-        "Constructor.  Use ShowModal method to show the dialog.");
+        "Constructor.  Use ShowModal method to show the dialog.", "");

 
     DocDeclStr(
         wxString , GetValue(),
 
     DocDeclStr(
         wxString , GetValue(),

-        "Returns the text that the user has entered if the user has pressed OK,\n"
-        "or the original value if the user has pressed Cancel.");
+        "Returns the text that the user has entered if the user has pressed OK,
+or the original value if the user has pressed Cancel.", "");

     
     DocDeclStr(
         void , SetValue(const wxString& value),
     
     DocDeclStr(
         void , SetValue(const wxString& value),

-        "Sets the default text value.");
+        "Sets the default text value.", "");
+};
+
+//---------------------------------------------------------------------------
+
+MAKE_CONST_WXSTRING(GetPasswordFromUserPromptStr);
+
+class wxPasswordEntryDialog : public wxTextEntryDialog
+{
+public:
+    wxPasswordEntryDialog(wxWindow *parent,
+                      const wxString& message,
+                      const wxString& caption = wxPyGetPasswordFromUserPromptStr,
+                      const wxString& value = wxPyEmptyString,
+                      long style = wxTextEntryDialogStyle,
+                      const wxPoint& pos = wxDefaultPosition);

 };
 
 //---------------------------------------------------------------------------
 
 
 DocStr(wxFontData,
 };
 
 //---------------------------------------------------------------------------
 
 
 DocStr(wxFontData,

-       "This class holds a variety of information related to font dialogs.");
+       "This class holds a variety of information related to font dialogs and
+is used to transfer settings to and results from a `wx.FontDialog`.", "");

 
 
 class wxFontData : public wxObject {
 
 
 class wxFontData : public wxObject {


@@ -434,85 +484,96 @@ public:
 
     DocDeclStr(
         void , EnableEffects(bool enable),
 
     DocDeclStr(
         void , EnableEffects(bool enable),

-        "Enables or disables 'effects' under MS Windows only. This refers\n"
-        "to the controls for manipulating colour, strikeout and underline\n"
-        "properties.  The default value is true.");
+        "Enables or disables 'effects' under MS Windows only. This refers to
+the controls for manipulating colour, strikeout and underline
+properties.  The default value is true.", "");

     
     DocDeclStr(
         bool , GetAllowSymbols(),
     
     DocDeclStr(
         bool , GetAllowSymbols(),

-        "Under MS Windows, returns a flag determining whether symbol fonts can be\n"
-        "selected. Has no effect on other platforms. The default value is true.");
+        "Under MS Windows, returns a flag determining whether symbol fonts can
+be selected. Has no effect on other platforms. The default value is
+true.", "");

     
     DocDeclStr(
         wxColour , GetColour(),
     
     DocDeclStr(
         wxColour , GetColour(),

-        "Gets the colour associated with the font dialog. The default value is black.");
+        "Gets the colour associated with the font dialog. The default value is
+black.", "");

     
     DocDeclStr(
         wxFont , GetChosenFont(),
     
     DocDeclStr(
         wxFont , GetChosenFont(),

-        "Gets the font chosen by the user.");
+        "Gets the font chosen by the user.", "");

     
     DocDeclStr(
         bool , GetEnableEffects(),
     
     DocDeclStr(
         bool , GetEnableEffects(),

-        "Determines whether 'effects' are enabled under Windows.");
+        "Determines whether 'effects' are enabled under Windows.", "");

     
     DocDeclStr(
         wxFont , GetInitialFont(),
     
     DocDeclStr(
         wxFont , GetInitialFont(),

-        "Gets the font that will be initially used by the font dialog. This should have\n"
-        "previously been set by the application.");
+        "Gets the font that will be initially used by the font dialog. This
+should have previously been set by the application.", "");

     
     DocDeclStr(
         bool , GetShowHelp(),
     
     DocDeclStr(
         bool , GetShowHelp(),

-        "Returns true if the Help button will be shown (Windows only).  The default\n"
-        "value is false.");
+        "Returns true if the Help button will be shown (Windows only).  The
+default value is false.", "");

     
     DocDeclStr(
         void , SetAllowSymbols(bool allowSymbols),
     
     DocDeclStr(
         void , SetAllowSymbols(bool allowSymbols),

-        "Under MS Windows, determines whether symbol fonts can be selected. Has no\n"
-        "effect on other platforms.  The default value is true.");
+        "Under MS Windows, determines whether symbol fonts can be selected. Has
+no effect on other platforms.  The default value is true.", "");

     
     DocDeclStr(
         void , SetChosenFont(const wxFont& font),
     
     DocDeclStr(
         void , SetChosenFont(const wxFont& font),

-        "Sets the font that will be returned to the user (for internal use only).");
+        "Sets the font that will be returned to the user (normally for internal
+use only).", "");

     
     DocDeclStr(
         void , SetColour(const wxColour& colour),
     
     DocDeclStr(
         void , SetColour(const wxColour& colour),

-        "Sets the colour that will be used for the font foreground colour.  The default\n"
-        "colour is black.");
+        "Sets the colour that will be used for the font foreground colour.  The
+default colour is black.", "");

     
     DocDeclStr(
         void , SetInitialFont(const wxFont& font),
     
     DocDeclStr(
         void , SetInitialFont(const wxFont& font),

-        "Sets the font that will be initially used by the font dialog.");
+        "Sets the font that will be initially used by the font dialog.", "");

     
     DocDeclStr(
         void , SetRange(int min, int max),
     
     DocDeclStr(
         void , SetRange(int min, int max),

-        "Sets the valid range for the font point size (Windows only).  The default is\n"
-        "0, 0 (unrestricted range).");
+        "Sets the valid range for the font point size (Windows only).  The
+default is 0, 0 (unrestricted range).", "");

     
     DocDeclStr(
         void , SetShowHelp(bool showHelp),
     
     DocDeclStr(
         void , SetShowHelp(bool showHelp),

-        "Determines whether the Help button will be displayed in the font dialog\n"
-        "(Windows only).  The default value is false.");
+        "Determines whether the Help button will be displayed in the font
+dialog (Windows only).  The default value is false.", "");

 };
 
 
 
 
 DocStr(wxFontDialog,
 };
 
 
 
 
 DocStr(wxFontDialog,

-       "This class represents the font chooser dialog.");
+       "wx.FontDialog allows the user to select a system font and its attributes.
+
+:see: `wx.FontData`
+", "");
+
+MustHaveApp(wxFontDialog);

 
 class wxFontDialog : public wxDialog {
 public:
     %pythonAppend wxFontDialog   "self._setOORInfo(self)"
 
     DocStr(wxFontDialog,
 
 class wxFontDialog : public wxDialog {
 public:
     %pythonAppend wxFontDialog   "self._setOORInfo(self)"
 
     DocStr(wxFontDialog,

-           "Constructor. Pass a parent window and the FontData object to be\n"
-           "used to initialize the dialog controls.");
+           "Constructor. Pass a parent window and the `wx.FontData` object to be
+used to initialize the dialog controls.  Call `ShowModal` to display
+the dialog.  If ShowModal returns ``wx.ID_OK`` then you can fetch the
+results with via the `wx.FontData` returned by `GetFontData`.", "");

     wxFontDialog(wxWindow* parent, const wxFontData& data);
 
     
     DocDeclStr(
         wxFontData& , GetFontData(),
     wxFontDialog(wxWindow* parent, const wxFontData& data);
 
     
     DocDeclStr(
         wxFontData& , GetFontData(),

-        "Returns a reference to the internal FontData used by the FontDialog.");    
+        "Returns a reference to the internal `wx.FontData` used by the
+wx.FontDialog.", "");    

 };
 
 
 };
 
 


@@ -520,44 +581,43 @@ public:
 
 
 DocStr(wxMessageDialog,
 
 
 DocStr(wxMessageDialog,

-       "This class provides a dialog that shows a single or multi-line message, with\n"
-       "a choice of OK, Yes, No and Cancel buttons.");
-
-RefDoc(wxMessageDialog, "
-  Styles
-    wx.OK:                Show an OK button.
-
-    wx.CANCEL:            Show a Cancel button.
-
-    wx.YES_NO:            Show Yes and No buttons.
-
-    wx.YES_DEFAULT:       Used with wxYES_NO, makes Yes button the default - which is the default behaviour.
-
-    wx.NO_DEFAULT:        Used with wxYES_NO, makes No button the default.
-
-    wx.ICON_EXCLAMATION:  Shows an exclamation mark icon.
-
-    wx.ICON_HAND:         Shows an error icon.
-
-    wx.ICON_ERROR:        Shows an error icon - the same as wxICON_HAND.
-
-    wx.ICON_QUESTION:     Shows a question mark icon.
-
-    wx.ICON_INFORMATION:  Shows an information (i) icon.
-
-    wx.STAY_ON_TOP:       The message box stays on top of all other window, even those of the other applications (Windows only).
+"This class provides a simple dialog that shows a single or multi-line
+message, with a choice of OK, Yes, No and/or Cancel buttons.", "
+
+Window Styles
+--------------
+    ===================    =============================================
+    wx.OK                  Show an OK button.
+    wx.CANCEL              Show a Cancel button.
+    wx.YES_NO              Show Yes and No buttons.
+    wx.YES_DEFAULT         Used with wxYES_NO, makes Yes button the
+                           default - which is the default behaviour.
+    wx.NO_DEFAULT          Used with wxYES_NO, makes No button the default.
+    wx.ICON_EXCLAMATION    Shows an exclamation mark icon.
+    wx.ICON_HAND           Shows an error icon.
+    wx.ICON_ERROR          Shows an error icon - the same as wxICON_HAND.
+    wx.ICON_QUESTION       Shows a question mark icon.
+    wx.ICON_INFORMATION    Shows an information (i) icon.
+    wx.STAY_ON_TOP         The message box stays on top of all other
+                           window, even those of the other applications
+                           (Windows only).
+    ===================    =============================================

 ");
 
 
 ");
 
 

+MustHaveApp(wxMessageDialog);
+

 class wxMessageDialog : public wxDialog {
 public:
     %pythonAppend wxMessageDialog   "self._setOORInfo(self)"
     
 class wxMessageDialog : public wxDialog {
 public:
     %pythonAppend wxMessageDialog   "self._setOORInfo(self)"
     

-    wxMessageDialog(wxWindow* parent,
-                    const wxString& message,
-                    const wxString& caption = wxPyMessageBoxCaptionStr,
-                    long style = wxOK | wxCANCEL | wxCENTRE,
-                    const wxPoint& pos = wxDefaultPosition);
+    DocCtorStr(
+        wxMessageDialog(wxWindow* parent,
+                        const wxString& message,
+                        const wxString& caption = wxPyMessageBoxCaptionStr,
+                        long style = wxOK | wxCANCEL | wxCENTRE,
+                        const wxPoint& pos = wxDefaultPosition),
+        "Constructor, use `ShowModal` to display the dialog.", "");

 
 };
 
 
 };
 


@@ -565,36 +625,44 @@ public:
 
 
 DocStr(wxProgressDialog,
 
 
 DocStr(wxProgressDialog,

-       "A dialog that shows a short message and a progress bar. Optionally, it can\n"
-       "display an ABORT button.");
-
-RefDoc(wxProgressDialog, "
-  Styles
-
-    wx.PD_APP_MODAL:            Make the progress dialog modal. If this flag is
-                                not given, it is only \"locally\" modal - that is
-                                the input to the parent window is disabled,
-                                but not to the other ones.
-
-    wx.PD_AUTO_HIDE:            Causes the progress dialog to disappear from screen 
-                                as soon as the maximum value of the progress
-                                meter has been reached.
-
-    wx.PD_CAN_ABORT:            This flag tells the dialog that it should have
-                                a \"Cancel\" button which the user may press. If
-                                this happens, the next call to Update() will
-                                return false.
-
-    wx.PD_ELAPSED_TIME:         This flag tells the dialog that it should show
-                                elapsed time (since creating the dialog).
+"A dialog that shows a short message and a progress bar. Optionally, it
+can display an ABORT button.", "
+
+Window Styles
+--------------
+    ====================     =============================================
+    wx.PD_APP_MODAL          Make the progress dialog modal. If this flag is
+                             not given, it is only \"locally\" modal -
+                             that is the input to the parent window is
+                             disabled, but not to the other ones.
+
+    wx.PD_AUTO_HIDE          Causes the progress dialog to disappear from
+                             screen as soon as the maximum value of the
+                             progress meter has been reached.
+
+    wx.PD_CAN_ABORT          This flag tells the dialog that it should have
+                             a \"Cancel\" button which the user may press. If
+                             this happens, the next call to Update() will
+                             return false.
+
+    wx.PD_ELAPSED_TIME       This flag tells the dialog that it should show
+                             elapsed time (since creating the dialog).
+
+    wx.PD_ESTIMATED_TIME     This flag tells the dialog that it should show
+                             estimated time.
+
+    wx.PD_REMAINING_TIME     This flag tells the dialog that it should show
+                             remaining time.
+
+    wx.PD_SMOOTH             Uses the wx.GA_SMOOTH style on the embedded
+                             wx.Gauge widget.
+    ====================     =============================================
+");

 
 

-    wx.PD_ESTIMATED_TIME:      This flag tells the dialog that it should show
-                                estimated time.

 
 

-    wx.PD_REMAINING_TIME:      This flag tells the dialog that it should show
-                                remaining time.
-");
+// TODO: wxPD_CAN_SKIP

 
 

+MustHaveApp(wxProgressDialog);

 
 class wxProgressDialog : public wxFrame {
 public:
 
 class wxProgressDialog : public wxFrame {
 public:


@@ -606,21 +674,29 @@ public:
                          int maximum = 100,
                          wxWindow* parent = NULL,
                          int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL ),
                          int maximum = 100,
                          wxWindow* parent = NULL,
                          int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL ),

-        "Constructor. Creates the dialog, displays it and disables user input for other\n"
-        "windows, or, if wxPD_APP_MODAL flag is not given, for its parent window only.");
+        "Constructor. Creates the dialog, displays it and disables user input
+for other windows, or, if wx.PD_APP_MODAL flag is not given, for its
+parent window only.", "");

 
 

+    // TODO: support getting the skipped value back in the return value, but
+    // only if style is set.  This is so the API doesn't change for existing
+    // users...

     DocDeclStr(
     DocDeclStr(

-        bool , Update(int value, const wxString& newmsg = wxPyEmptyString),
-        "Updates the dialog, setting the progress bar to the new value and, if given\n"
-        "changes the message above it. Returns true unless the Cancel button has been\n"
-        "pressed.\n\n"
-        "If false is returned, the application can either immediately destroy the\n"
-        "dialog or ask the user for the confirmation and if the abort is not confirmed\n"
-        "the dialog may be resumed with Resume function.");
+        virtual bool , Update(int value, const wxString& newmsg = wxPyEmptyString),
+        "Updates the dialog, setting the progress bar to the new value and, if
+given changes the message above it. The value given should be less
+than or equal to the maximum value given to the constructor and the
+dialog is closed if it is equal to the maximum.  Returns True unless
+the Cancel button has been pressed.
+
+If false is returned, the application can either immediately destroy
+the dialog or ask the user for the confirmation and if the abort is
+not confirmed the dialog may be resumed with Resume function.", "");

     
     DocDeclStr(
         void , Resume(),
     
     DocDeclStr(
         void , Resume(),

-        "Can be used to continue with the dialog, after the user had chosen to abort.");
+        "Can be used to continue with the dialog, after the user had chosen to
+abort.", "");

     
 };
 
     
 };
 


@@ -680,7 +756,7 @@ EVT_COMMAND_FIND_CLOSE       = EVT_FIND_CLOSE
 
 
 DocStr(wxFindDialogEvent,
 
 
 DocStr(wxFindDialogEvent,

-       "Events for the FindReplaceDialog");
+       "Events for the FindReplaceDialog", "");

 
 class wxFindDialogEvent : public wxCommandEvent
 {
 
 class wxFindDialogEvent : public wxCommandEvent
 {


@@ -689,54 +765,58 @@ public:
     
     DocDeclStr(
         int , GetFlags(),
     
     DocDeclStr(
         int , GetFlags(),

-        "Get the currently selected flags: this is the combination of\n"
-        "wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags.");
+        "Get the currently selected flags: this is the combination of
+wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags.", "");

     
     DocDeclStr(
         const wxString& , GetFindString(),
     
     DocDeclStr(
         const wxString& , GetFindString(),

-        "Return the string to find (never empty).");
+        "Return the string to find (never empty).", "");

     
     DocDeclStr(
         const wxString& , GetReplaceString(),
     
     DocDeclStr(
         const wxString& , GetReplaceString(),

-        "Return the string to replace the search string with (only\n"
-        "for replace and replace all events).");
+        "Return the string to replace the search string with (only for replace
+and replace all events).", "");

     
     DocDeclStr(
         wxFindReplaceDialog *, GetDialog(),
     
     DocDeclStr(
         wxFindReplaceDialog *, GetDialog(),

-        "Return the pointer to the dialog which generated this event.");
+        "Return the pointer to the dialog which generated this event.", "");

     
     DocDeclStr(
         void , SetFlags(int flags),
     
     DocDeclStr(
         void , SetFlags(int flags),

-        "");
+        "", "");

     
     DocDeclStr(
         void , SetFindString(const wxString& str),
     
     DocDeclStr(
         void , SetFindString(const wxString& str),

-        "");
+        "", "");

     
     DocDeclStr(
         void , SetReplaceString(const wxString& str),
     
     DocDeclStr(
         void , SetReplaceString(const wxString& str),

-        "");
+        "", "");

 };
 
 
 
 DocStr(wxFindReplaceData, 
 };
 
 
 
 DocStr(wxFindReplaceData, 

-"FindReplaceData holds the data for FindReplaceDialog. It is used to initialize
-the dialog with the default values and will keep the last values from the
-dialog when it is closed. It is also updated each time a wxFindDialogEvent is
-generated so instead of using the wxFindDialogEvent methods you can also
-directly query this object.
-
-Note that all SetXXX() methods may only be called before showing the dialog
-and calling them has no effect later.
-
- Flags
-    wxFR_DOWN:          downward search/replace selected (otherwise, upwards)
-
-    wxFR_WHOLEWORD:     whole word search/replace selected
-
-    wxFR_MATCHCASE:     case sensitive search/replace selected (otherwise,
-                        case insensitive)
+"wx.FindReplaceData holds the data for wx.FindReplaceDialog. It is used
+to initialize the dialog with the default values and will keep the
+last values from the dialog when it is closed. It is also updated each
+time a `wx.FindDialogEvent` is generated so instead of using the
+`wx.FindDialogEvent` methods you can also directly query this object.
+
+Note that all SetXXX() methods may only be called before showing the
+dialog and calling them has no effect later.", "
+
+Flags
+-----
+    ================   ===============================================  
+    wx.FR_DOWN         Downward search/replace selected (otherwise,
+                       upwards)
+
+    wx.FR_WHOLEWORD    Whole word search/replace selected
+
+    wx.FR_MATCHCASE    Case sensitive search/replace selected
+                       (otherwise, case insensitive)
+    ================   ===============================================  

 ");
 
 
 ");
 
 


@@ -747,34 +827,34 @@ class wxFindReplaceData : public wxObject
 public:
     DocCtorStr(
         wxFindReplaceData(int flags=0),
 public:
     DocCtorStr(
         wxFindReplaceData(int flags=0),

-        "Constuctor initializes the flags to default value (0).");
+        "Constuctor initializes the flags to default value (0).", "");

     
     ~wxFindReplaceData();
     
 
     DocDeclStr(
         const wxString& , GetFindString(),
     
     ~wxFindReplaceData();
     
 
     DocDeclStr(
         const wxString& , GetFindString(),

-        "Get the string to find.");
+        "Get the string to find.", "");

     
     DocDeclStr(
         const wxString& , GetReplaceString(),
     
     DocDeclStr(
         const wxString& , GetReplaceString(),

-        "Get the replacement string.");
+        "Get the replacement string.", "");

     
     DocDeclStr(
         int , GetFlags(),
     
     DocDeclStr(
         int , GetFlags(),

-        "Get the combination of flag values.");
+        "Get the combination of flag values.", "");

     
     DocDeclStr(
         void , SetFlags(int flags),
     
     DocDeclStr(
         void , SetFlags(int flags),

-        "Set the flags to use to initialize the controls of the dialog.");
+        "Set the flags to use to initialize the controls of the dialog.", "");

     
     DocDeclStr(
         void , SetFindString(const wxString& str),
     
     DocDeclStr(
         void , SetFindString(const wxString& str),

-        "Set the string to find (used as initial value by the dialog).");
+        "Set the string to find (used as initial value by the dialog).", "");

     
     DocDeclStr(
         void , SetReplaceString(const wxString& str),
     
     DocDeclStr(
         void , SetReplaceString(const wxString& str),

-        "Set the replacement string (used as initial value by the dialog).");
+        "Set the replacement string (used as initial value by the dialog).", "");

     
 };
 
     
 };
 


@@ -782,25 +862,31 @@ public:
 
 
 DocStr(wxFindReplaceDialog,
 
 
 DocStr(wxFindReplaceDialog,

-"FindReplaceDialog is a standard modeless dialog which is used to allow the
-user to search for some text (and possibly replace it with something
-else). The actual searching is supposed to be done in the owner window which
-is the parent of this dialog. Note that it means that unlike for the other
-standard dialogs this one must have a parent window. Also note that there is
-no way to use this dialog in a modal way; it is always, by design and
-implementation, modeless.");
+"wx.FindReplaceDialog is a standard modeless dialog which is used to
+allow the user to search for some text (and possibly replace it with
+something else). The actual searching is supposed to be done in the
+owner window which is the parent of this dialog. Note that it means
+that unlike for the other standard dialogs this one must have a parent
+window. Also note that there is no way to use this dialog in a modal
+way; it is always, by design and implementation, modeless.", "

 
 

-RefDoc(wxFindReplaceDialog, "
- Styles
-    wx.FR_REPLACEDIALOG:        replace dialog (otherwise find dialog)

 
 

-    wx.FR_NOUPDOWN:             don't allow changing the search direction
+Window Styles
+-------------

 
 

-    wx.FR_NOMATCHCASE:          don't allow case sensitive searching
+    =====================  =========================================
+    wx.FR_REPLACEDIALOG    replace dialog (otherwise find dialog)

 
 

-    wx.FR_NOWHOLEWORD:          don't allow whole word searching
+    wx.FR_NOUPDOWN         don't allow changing the search direction
+
+    wx.FR_NOMATCHCASE      don't allow case sensitive searching
+
+    wx.FR_NOWHOLEWORD      don't allow whole word searching
+    =====================  =========================================

 ");
 
 ");
 

+MustHaveApp(wxFindReplaceDialog);
+

 class wxFindReplaceDialog : public wxDialog {
 public:
     %pythonAppend wxFindReplaceDialog     "self._setOORInfo(self)"
 class wxFindReplaceDialog : public wxDialog {
 public:
     %pythonAppend wxFindReplaceDialog     "self._setOORInfo(self)"


@@ -811,30 +897,28 @@ public:
                             wxFindReplaceData *data,
                             const wxString &title,
                             int style = 0),
                             wxFindReplaceData *data,
                             const wxString &title,
                             int style = 0),

-        "Create a FindReplaceDialog.  The parent and data parameters must be\n"
-        "non-None.  Use Show to display the dialog.");
+        "Create a FindReplaceDialog.  The parent and data parameters must be
+non-None.  Use Show to display the dialog.", "");

 
     DocCtorStrName(
         wxFindReplaceDialog(),
 
     DocCtorStrName(
         wxFindReplaceDialog(),

-        "Precreate a FindReplaceDialog for 2-phase creation",
+        "Precreate a FindReplaceDialog for 2-phase creation", "",

         PreFindReplaceDialog);
 
     
     DocDeclStr(
         PreFindReplaceDialog);
 
     
     DocDeclStr(

-        bool , Create(wxWindow *parent,
-                      wxFindReplaceData *data,
-                      const wxString &title,
-                      int style = 0),
-        "Create the dialog, for 2-phase create.");
+        bool , Create(wxWindow *parent, wxFindReplaceData *data,
+                      const wxString &title, int style = 0),
+        "Create the dialog, for 2-phase create.", "");

     
 
     DocDeclStr(
         const wxFindReplaceData *, GetData(),
     
 
     DocDeclStr(
         const wxFindReplaceData *, GetData(),

-        "Get the FindReplaceData object used by this dialog.");
+        "Get the FindReplaceData object used by this dialog.", "");

     
     DocDeclStr(
         void , SetData(wxFindReplaceData *data),
     
     DocDeclStr(
         void , SetData(wxFindReplaceData *data),

-        "Set the FindReplaceData object used by this dialog.");
+        "Set the FindReplaceData object used by this dialog.", "");

     
 };
 
     
 };