X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..fb3b60978febbf86a71324a22dbf55d9717fd32a:/interface/wx/filepicker.h diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h index 2cb91adc97..3053fcefc3 100644 --- a/interface/wx/filepicker.h +++ b/interface/wx/filepicker.h @@ -3,18 +3,16 @@ // Purpose: interface of wxFilePickerCtrl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @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 @@ -39,11 +37,23 @@ existing file. @style{wxFLP_CHANGE_DIR} Change current working directory on each user file selection change. + @style{wxFLP_SMALL} + Use smaller version of the control with a small "..." button instead + of the normal "Browse" one. This flag is new since wxWidgets 2.9.3. @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 +66,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 +96,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 +125,28 @@ 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. + Set the directory to show when starting to browse for files. + + This function is mostly useful for the file picker controls which have + no selection initially to configure the directory that should be shown + if the user starts browsing for files as otherwise the directory of + initially selected file is used, which is usually the desired + behaviour and so the directory specified by this function is ignored in + this case. + + @since 2.9.4 + */ + void SetInitialDirectory(const wxString& dir); + + /** + 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 +155,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 +177,24 @@ 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. + @style{wxDIRP_SMALL} + Use smaller version of the control with a small "..." button instead + of the normal "Browse" one. This flag is new since wxWidgets 2.9.3. @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 +207,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 +238,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 +262,28 @@ 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); + /** + Set the directory to show when starting to browse for directories. + + This function is mostly useful for the directory picker controls which + have no selection initially to configure the directory that should be + shown if the user starts browsing for directories as otherwise the + initially selected directory is used, which is usually the desired + behaviour and so the directory specified by this function is ignored in + this case. + + @since 2.9.4 + */ + void SetInitialDirectory(const wxString& dir); + /** 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 +292,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 +316,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.