X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..89a7e1ff98e58687eef2bf8ec94bf7190208167f:/interface/wx/filepicker.h diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h index 2cb91adc97..2e83658293 100644 --- a/interface/wx/filepicker.h +++ b/interface/wx/filepicker.h @@ -8,13 +8,11 @@ /** @class wxFilePickerCtrl - @wxheader{filepicker.h} This control allows the user to select a file. The generic implementation is a button which brings up a wxFileDialog when clicked. Native implementation may differ but this is usually a (small) widget which give access to the - file-chooser - dialog. + file-chooser dialog. It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default). @beginStyleTable @@ -41,9 +39,18 @@ Change current working directory on each user file selection change. @endStyleTable + + @beginEventEmissionTable{wxFileDirPickerEvent} + @event{EVT_FILEPICKER_CHANGED(id, func)} + The user changed the file selected in the control either using the + button or using text control (see wxFLP_USE_TEXTCTRL; note that in + this case the event is fired only if the user's input is valid, + e.g. an existing file path if wxFLP_FILE_MUST_EXIST was given). + @endEventTable + @library{wxcore} @category{pickers} - + @appearance{filepickerctrl.png} @see wxFileDialog, wxFileDirPickerEvent */ @@ -56,27 +63,29 @@ public: */ wxFilePickerCtrl(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, - const wxString& message = "Select a file", - const wxString& wildcard = ".", + const wxString& message = wxFileSelectorPromptStr, + const wxString& wildcard = wxFileSelectorDefaultWildcardStr, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxFLP_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, - const wxString& name = "filepickerctrl"); + const wxString& name = wxFilePickerCtrlNameStr); /** + Creates this widget with the given parameters. + @param parent Parent window, must not be non-@NULL. @param id The identifier for the control. @param path The initial file shown in the control. Must be a valid path to a file or - the empty string. + the empty string. @param message The message shown to the user in the wxFileDialog shown by the control. @param wildcard A wildcard which defines user-selectable files (use the same syntax as for - wxFileDialog's wildcards). + wxFileDialog's wildcards). @param pos Initial position. @param size @@ -84,26 +93,26 @@ public: @param style The window style, see wxFLP_* flags. @param validator - Validator which can be used for additional date checks. + Validator which can be used for additional data checks. @param name Control name. @return @true if the control was successfully created or @false if - creation failed. + creation failed. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, - const wxString& message = "Select a file", - const wxString& wildcard = ".", + const wxString& message = wxFileSelectorPromptStr, + const wxString& wildcard = wxFileSelectorDefaultWildcardStr, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxFLP_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, - const wxString& name = "filepickerctrl"); + const wxString& name = wxFilePickerCtrlNameStr); /** - Similar to GetPath() but returns the path of - the currently selected file as a wxFileName object. + Similar to GetPath() but returns the path of the currently selected + file as a wxFileName object. */ wxFileName GetFileName() const; @@ -113,15 +122,14 @@ public: wxString GetPath() const; /** - This method does the same thing as SetPath() but - takes a wxFileName object instead of a string. + This method does the same thing as SetPath() but takes a wxFileName + object instead of a string. */ void SetFileName(const wxFileName& filename); /** - Sets the absolute path of the currently selected file. This must be a valid - file if - the @c wxFLP_FILE_MUST_EXIST style was given. + Sets the absolute path of the currently selected file. + This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given. */ void SetPath(const wxString& filename); }; @@ -130,14 +138,11 @@ public: /** @class wxDirPickerCtrl - @wxheader{filepicker.h} This control allows the user to select a directory. The generic implementation - is - a button which brings up a wxDirDialog when clicked. Native implementation + is a button which brings up a wxDirDialog when clicked. Native implementation may differ but this is usually a (small) widget which give access to the - dir-chooser - dialog. + dir-chooser dialog. It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default). @beginStyleTable @@ -155,13 +160,21 @@ public: wxGTK control always adds this flag internally as it does not support its absence. @style{wxDIRP_CHANGE_DIR} - Change current working directory on each user directory selection - change. + Change current working directory on each user directory selection change. @endStyleTable + @beginEventEmissionTable{wxFileDirPickerEvent} + @event{EVT_DIRPICKER_CHANGED(id, func)} + The user changed the directory selected in the control either using the + button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this + case the event is fired only if the user's input is valid, e.g. an + existing directory path). + @endEventTable + + @library{wxcore} @category{pickers} - + @appearance{dirpickerctrl.png} @see wxDirDialog, wxFileDirPickerEvent */ @@ -174,21 +187,23 @@ public: */ wxDirPickerCtrl(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, - const wxString& message = "Select a folder", + const wxString& message = wxDirSelectorPromptStr, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDIRP_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, - const wxString& name = "dirpickerctrl"); + const wxString& name = wxDirPickerCtrlNameStr); /** + Creates the widgets with the given parameters. + @param parent Parent window, must not be non-@NULL. @param id The identifier for the control. @param path The initial directory shown in the control. Must be a valid path to a - directory or the empty string. + directory or the empty string. @param message The message shown to the user in the wxDirDialog shown by the control. @param pos @@ -203,21 +218,21 @@ public: Control name. @return @true if the control was successfully created or @false if - creation failed. + creation failed. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& path = wxEmptyString, - const wxString& message = "Select a folder", + const wxString& message = wxDirSelectorPromptStr, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDIRP_DEFAULT_STYLE, const wxValidator& validator = wxDefaultValidator, - const wxString& name = "dirpickerctrl"); + const wxString& name = wxDirPickerCtrlNameStr); /** - Returns the absolute path of the currently selected directory as a wxFileName - object. - This function is equivalent to GetPath() + Returns the absolute path of the currently selected directory as a + wxFileName object. + This function is equivalent to GetPath(). */ wxFileName GetDirName() const; @@ -227,15 +242,14 @@ public: wxString GetPath() const; /** - Just like SetPath() but this function takes a - wxFileName object. + Just like SetPath() but this function takes a wxFileName object. */ void SetDirName(const wxFileName& dirname); /** Sets the absolute path of (the default converter uses current locale's - charset)the currently selected directory. This must be a valid directory if - @c wxDIRP_DIR_MUST_EXIST style was given. + charset)the currently selected directory. + This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given. */ void SetPath(const wxString& dirname); }; @@ -244,15 +258,21 @@ public: /** @class wxFileDirPickerEvent - @wxheader{filepicker.h} This event class is used for the events generated by wxFilePickerCtrl and by wxDirPickerCtrl. + @beginEventTable{wxFileDirPickerEvent} + @event{EVT_FILEPICKER_CHANGED(id, func)} + Generated whenever the selected file changes. + @event{EVT_DIRPICKER_CHANGED(id, func)} + Generated whenever the selected directory changes. + @endEventTable + @library{wxcore} - @category{FIXME} + @category{events} - @see wxfilepickerctrl() + @see wxFilePickerCtrl, wxDirPickerCtrl */ class wxFileDirPickerEvent : public wxCommandEvent { @@ -262,7 +282,7 @@ public: */ wxFileDirPickerEvent(wxEventType type, wxObject* generator, int id, - const wxString path); + const wxString& path); /** Retrieve the absolute path of the file/directory the user has just selected.