X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e029dde795b4ed6aba140b5b476d1788a19a2ef2..a9a04486a2fc7be11a42343070ff8dd859618c46:/wxPython/src/_cmndlgs.i diff --git a/wxPython/src/_cmndlgs.i b/wxPython/src/_cmndlgs.i index 967fb587d1..8f96125982 100644 --- a/wxPython/src/_cmndlgs.i +++ b/wxPython/src/_cmndlgs.i @@ -27,52 +27,60 @@ MAKE_CONST_WXSTRING(MessageBoxCaptionStr); 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(), - "Constructor, sets default values."); - + "Constructor, sets default values.", ""); + ~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(), - "Gets the colour (pre)selected by the dialog."); - + "Gets the colour (pre)selected by the dialog.", ""); + 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), - "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), - "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), - "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, - "This class represents the colour chooser dialog."); + "This class represents the colour chooser dialog.", ""); + +MustHaveApp(wxColourDialog); class wxColourDialog : public wxDialog { public: @@ -80,206 +88,254 @@ public: 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(), - "Returns a reference to the ColourData used by the dialog."); + "Returns a reference to the `wx.ColourData` used by the dialog.", ""); }; +wxColour wxGetColourFromUser(wxWindow *parent = (wxWindow *)NULL, + const wxColour& colInit = wxNullColour, + const wxString& caption = wxPyEmptyString); + + //-------------------------------------------------------------------------------- +enum { + wxDD_NEW_DIR_BUTTON, + wxDD_DEFAULT_STYLE, + wxDD_CHANGE_DIR, +}; 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_DEFAULT_STYLE Equivalent to a combination of + wx.DEFAULT_DIALOG_STYLE, wx.DD_NEW_DIR_BUTTON + and wx.RESIZE_BORDER. + + 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. + + wx.DD_CHANGE_DIR Change the current working directory to the + directory chosen by the user. + ==================== ========================================== +"); -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: %pythonAppend wxDirDialog "self._setOORInfo(self)" - - RefDoc(wxDirDialog, ""); // turn it off for the ctors - + %pythonAppend wxDirDialog() "" + DocCtorStr( wxDirDialog(wxWindow* parent, const wxString& message = wxPyDirSelectorPromptStr, const wxString& defaultPath = wxPyEmptyString, - long style = 0, + long style = wxDD_DEFAULT_STYLE, 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.", ""); + +// %RenameCtor(PreDirDialog, wxDirDialog()); +// bool Create(wxWindow *parent, +// const wxString& title = wxDirSelectorPromptStr, +// const wxString& defaultPath = wxEmptyString, +// long style = wxDD_DEFAULT_STYLE, +// const wxPoint& pos = wxDefaultPosition, +// const wxSize& sz = wxDefaultSize, +// const wxString& name = wxPyDirDialogNameStr); DocDeclStr( wxString , GetPath(), - "Returns the default or user-selected path."); - + "Returns the default or user-selected path.", ""); + DocDeclStr( wxString , GetMessage(), - "Returns the message that will be displayed on the dialog."); - - DocDeclStr( - long , GetStyle(), - "Returns the dialog style."); - + "Returns the message that will be displayed on the dialog.", ""); + 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), - "Sets the default path."); - + "Sets the default path.", ""); + }; //--------------------------------------------------------------------------- +%{ +// for compatibility only +#define wxHIDE_READONLY 0 +%} + +enum { + // These will dissappear in 2.8 + wxOPEN, + wxSAVE, + wxOVERWRITE_PROMPT, + wxFILE_MUST_EXIST, + wxMULTIPLE, + wxCHANGE_DIR, + wxHIDE_READONLY, + + wxFD_OPEN, + wxFD_SAVE, + wxFD_OVERWRITE_PROMPT, + wxFD_FILE_MUST_EXIST, + wxFD_MULTIPLE, + wxFD_CHANGE_DIR, + wxFD_DEFAULT_STYLE, +}; + 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\" - Styles - wx.OPEN This is an open dialog. - wx.SAVE This is a save dialog. +Window Styles +-------------- + ====================== ========================================== + wx.FD_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.FD_SAVE This is a save dialog. - wx.OVERWRITE_PROMPT For save dialog only: prompt for a confirmation if a - file will be overwritten. + wx.FD_OVERWRITE_PROMPT For save dialog only: prompt for a confirmation + if a file will be overwritten. - wx.MULTIPLE For open dialog only: allows selecting multiple files. + wx.FD_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. + wx.FD_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)" - RefDoc(wxFileDialog, ""); // turn it off for the ctors - DocCtorStr( wxFileDialog(wxWindow* parent, const wxString& message = wxPyFileSelectorPromptStr, const wxString& defaultDir = wxPyEmptyString, const wxString& defaultFile = wxPyEmptyString, const wxString& wildcard = wxPyFileSelectorDefaultWildcardStr, - long style = 0, + long style = wxFD_DEFAULT_STYLE, 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), - "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), - "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), - "Sets the default directory."); - + "Sets the default directory.", ""); + DocDeclStr( void , SetFilename(const wxString& name), - "Sets the default filename."); - + "Sets the default filename.", ""); + 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\""); - - DocDeclStr( - void , SetStyle(long style), - "Sets the dialog style."); - + "Sets the wildcard, which can contain multiple file types, for +example:: + + \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\" +", ""); + 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, - "Returns the message that will be displayed on the dialog."); - + "Returns the message that will be displayed on the dialog.", ""); + 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, - "Returns the default directory."); - + "Returns the default directory.", ""); + DocDeclStr( wxString , GetFilename() const, - "Returns the default filename."); - + "Returns the default filename.", ""); + DocDeclStr( wxString , GetWildcard() const, - "Returns the file dialog wildcard."); - - DocDeclStr( - long , GetStyle() const, - "Returns the dialog style."); - + "Returns the file dialog wildcard.", ""); + 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, - "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."); - 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."); - %extend { + DocStr(GetFilenames, + "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.", ""); PyObject* GetFilenames() { wxArrayString arr; self->GetFilenames(arr); return wxArrayString2PyList_helper(arr); } + DocStr(GetPaths, + "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.", ""); + PyObject* GetPaths() { wxArrayString arr; self->GetPaths(arr); @@ -316,7 +372,9 @@ enum { wxCHOICEDLG_STYLE }; DocStr(wxMultiChoiceDialog, - "A simple dialog with a multi selection listbox."); + "A simple dialog with a multi selection listbox.", ""); + +MustHaveApp(wxMultiChoiceDialog); class wxMultiChoiceDialog : public wxDialog { @@ -327,23 +385,37 @@ public: 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), - "__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__(self, Window parent, String message, String caption, + List choices=EmptyList, long style=CHOICEDLG_STYLE, + Point pos=DefaultPosition) -> MultiChoiceDialog", + "Constructor. Use the `ShowModal` method to show the dialog. + + :param parent: The parent window. + :param message: Text to display above the list of selections. + :param caption: Text to use in the title bar of the dialog. + :param choices: A list of strings or unicode objects that the + user is allowed to choose from. + :param style: Styles to apply to the dialog. The default value is + equivallent to wx.DEFAULT_DIALOG_STYLE|wx.RESIZE_BORDER|wx.OK|wx.CANCEL|wx.CENTER. + :param pos: Where to position the dialog (not used on Windows) + +", ""); + - 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. The list should specify the indexes of the items that +should be selected.", ""); 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. +If an item is selected then its index will appear in the list.", ""); %extend { PyObject* GetSelections() { return wxArrayInt2PyList_helper(self->GetSelections()); @@ -355,17 +427,19 @@ public: //--------------------------------------------------------------------------- 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, - "__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=EmptyList, long style=CHOICEDLG_STYLE, + Point pos=DefaultPosition) -> SingleChoiceDialog", + "Constructor. Use ShowModal method to show the dialog.", ""); %extend { // TODO: ignoring clientData for now... FIX THIS @@ -384,22 +458,26 @@ public: DocDeclStr( int , GetSelection(), - "Get the index of teh currently selected item."); - + "Get the index of teh currently selected item.", ""); + 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), - "Set the current selected item to sel"); + "Set the current selected item to sel", ""); }; //--------------------------------------------------------------------------- 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: @@ -410,25 +488,65 @@ public: const wxString& message, const wxString& caption = wxPyGetTextFromUserPromptStr, const wxString& defaultValue = wxPyEmptyString, - long style = wxOK | wxCANCEL | wxCENTRE, + long style = wxTextEntryDialogStyle, const wxPoint& pos = wxDefaultPosition), - "Constructor. Use ShowModal method to show the dialog."); + "Constructor. Use ShowModal method to show the dialog.", ""); 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), - "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( wxNumberEntryDialog, +"A dialog with spin control, ok and cancel buttons.", "") + +MustHaveApp(wxNumberEntryDialog); + +class wxNumberEntryDialog : public wxDialog +{ +public: + %pythonAppend wxNumberEntryDialog "self._setOORInfo(self)" + + DocCtorStr( + wxNumberEntryDialog(wxWindow *parent, + const wxString& message, + const wxString& prompt, + const wxString& caption, + long value, long min, long max, + const wxPoint& pos = wxDefaultPosition), + "Constructor. Use ShowModal method to show the dialog.", ""); + + long GetValue(); }; //--------------------------------------------------------------------------- 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 { @@ -438,132 +556,145 @@ public: 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(), - "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(), - "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(), - "Gets the font chosen by the user."); - + "Gets the font chosen by the user.", ""); + DocDeclStr( bool , GetEnableEffects(), - "Determines whether 'effects' are enabled under Windows."); - + "Determines whether 'effects' are enabled under Windows.", ""); + 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(), - "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), - "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), - "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), - "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), - "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), - "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), - "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, - "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, - "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(), - "Returns a reference to the internal FontData used by the FontDialog."); + "Returns a reference to the internal `wx.FontData` used by the +wx.FontDialog.", ""); }; -//--------------------------------------------------------------------------- - - -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. +wxFont wxGetFontFromUser(wxWindow *parent = NULL, + const wxFont& fontInit = wxNullFont, + const wxString& caption = wxPyEmptyString); - 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). +DocStr(wxMessageDialog, +"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)" - - RefDoc(wxMessageDialog, ""); // turn it off for the ctors - - 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.", ""); }; @@ -571,65 +702,90 @@ public: 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 in the first component of its return + value. + + wx.PD_CAN_SKIP This flag tells the dialog that it should have a + \"Skip\" button which the user may press. If this + happens, the next call to Update() will return + True in the second component of its return value. + + 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: %pythonAppend wxProgressDialog "self._setOORInfo(self)" - RefDoc(wxProgressDialog, ""); // turn it off for the ctors - DocCtorStr( wxProgressDialog(const wxString& title, const wxString& message, 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... + DocDeclAStr( + virtual bool , Update(int value, const wxString& newmsg = wxPyEmptyString, + bool *OUTPUT), + "Update(self, int value, String newmsg) --> (continue, skip)", + "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 a tuple of +boolean values, ``(continue, skip)`` where ``continue`` is ``True`` +unless the Cancel button has been pressed, and ``skip`` is ``False`` +unless the Skip button (if any) has been pressed. + +If the ``continue`` return value is ``false``, the application can either +immediately destroy the dialog or ask the user for confirmation, and if the +abort is not confirmed the dialog may be resumed with `Resume` function. +", ""); - 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."); - 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.", ""); + }; //--------------------------------------------------------------------------- @@ -679,72 +835,76 @@ EVT_FIND_REPLACE_ALL = wx.PyEventBinder( wxEVT_COMMAND_FIND_REPLACE_ALL, 1 ) EVT_FIND_CLOSE = wx.PyEventBinder( wxEVT_COMMAND_FIND_CLOSE, 1 ) %# For backwards compatibility. Should they be removed? -EVT_COMMAND_FIND = EVT_FIND +EVT_COMMAND_FIND = EVT_FIND EVT_COMMAND_FIND_NEXT = EVT_FIND_NEXT EVT_COMMAND_FIND_REPLACE = EVT_FIND_REPLACE EVT_COMMAND_FIND_REPLACE_ALL = EVT_FIND_REPLACE_ALL -EVT_COMMAND_FIND_CLOSE = EVT_FIND_CLOSE +EVT_COMMAND_FIND_CLOSE = EVT_FIND_CLOSE } DocStr(wxFindDialogEvent, - "Events for the FindReplaceDialog"); + "Events for the FindReplaceDialog", ""); class wxFindDialogEvent : public wxCommandEvent { public: wxFindDialogEvent(wxEventType commandType = wxEVT_NULL, int id = 0); - + 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(), - "Return the string to find (never empty)."); - + "Return the string to find (never empty).", ""); + 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(), - "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 , SetFindString(const wxString& str), - ""); - + "", ""); + DocDeclStr( void , SetReplaceString(const wxString& str), - ""); + "", ""); }; -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. +DocStr(wxFindReplaceData, +"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. +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) +Flags +----- + ================ =============================================== + wx.FR_DOWN Downward search/replace selected (otherwise, + upwards) - wxFR_WHOLEWORD: whole word search/replace selected + wx.FR_WHOLEWORD Whole word search/replace selected - wxFR_MATCHCASE: case sensitive search/replace selected (otherwise, - case insensitive) + wx.FR_MATCHCASE Case sensitive search/replace selected + (otherwise, case insensitive) + ================ =============================================== "); @@ -755,97 +915,99 @@ class wxFindReplaceData : public wxObject 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(), - "Get the string to find."); - + "Get the string to find.", ""); + DocDeclStr( const wxString& , GetReplaceString(), - "Get the replacement string."); - + "Get the replacement string.", ""); + DocDeclStr( int , GetFlags(), - "Get the combination of flag values."); - + "Get the combination of flag values.", ""); + 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), - "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), - "Set the replacement string (used as initial value by the dialog)."); - + "Set the replacement string (used as initial value by the dialog).", ""); + }; 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) +Window Styles +------------- - wx.FR_NOUPDOWN: don't allow changing the search direction + ===================== ========================================= + wx.FR_REPLACEDIALOG replace dialog (otherwise find dialog) - wx.FR_NOMATCHCASE: don't allow case sensitive searching + wx.FR_NOUPDOWN don't allow changing the search direction - wx.FR_NOWHOLEWORD: don't allow whole word searching + 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)" %pythonAppend wxFindReplaceDialog() "" - RefDoc(wxFindReplaceDialog, ""); // turn it off for the ctors - DocCtorStr( wxFindReplaceDialog(wxWindow *parent, 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(), - "Precreate a FindReplaceDialog for 2-phase creation", + "Precreate a FindReplaceDialog for 2-phase creation", "", 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(), - "Get the FindReplaceData object used by this dialog."); - + "Get the FindReplaceData object used by this dialog.", ""); + DocDeclStr( void , SetData(wxFindReplaceData *data), - "Set the FindReplaceData object used by this dialog."); - + "Set the FindReplaceData object used by this dialog.", ""); + }; //---------------------------------------------------------------------------