X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/filepicker.h diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h index 5df6c196fd..de2f816fa3 100644 --- a/interface/wx/filepicker.h +++ b/interface/wx/filepicker.h @@ -3,17 +3,35 @@ // Purpose: interface of wxFilePickerCtrl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +#define wxFLP_OPEN 0x0400 +#define wxFLP_SAVE 0x0800 +#define wxFLP_OVERWRITE_PROMPT 0x1000 +#define wxFLP_FILE_MUST_EXIST 0x2000 +#define wxFLP_CHANGE_DIR 0x4000 +#define wxFLP_SMALL wxPB_SMALL +#define wxFLP_USE_TEXTCTRL (wxPB_USE_TEXTCTRL) +#define wxFLP_DEFAULT_STYLE (wxFLP_OPEN|wxFLP_FILE_MUST_EXIST) + +#define wxDIRP_DIR_MUST_EXIST 0x0008 +#define wxDIRP_CHANGE_DIR 0x0010 +#define wxDIRP_SMALL wxPB_SMALL +#define wxDIRP_USE_TEXTCTRL (wxPB_USE_TEXTCTRL) +#define wxDIRP_DEFAULT_STYLE (wxDIRP_DIR_MUST_EXIST) + +wxEventType wxEVT_FILEPICKER_CHANGED; +wxEventType wxEVT_DIRPICKER_CHANGED; + + /** @class wxFilePickerCtrl 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 @@ -38,44 +56,60 @@ 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} @see wxFileDialog, wxFileDirPickerEvent */ class wxFilePickerCtrl : public wxPickerBase { public: + wxFilePickerCtrl(); + /** Initializes the object and calls Create() with all the parameters. */ 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 @@ -83,26 +117,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; @@ -112,15 +146,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); }; @@ -131,11 +178,9 @@ public: @class wxDirPickerCtrl 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 @@ -153,40 +198,55 @@ 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} @see wxDirDialog, wxFileDirPickerEvent */ class wxDirPickerCtrl : public wxPickerBase { public: + wxDirPickerCtrl(); + /** Initializes the object and calls Create() with all the parameters. */ 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 @@ -201,21 +261,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; @@ -225,15 +285,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); /** - 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. + 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 currently selected directory (the default converter uses current locale's + charset). + This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given. */ void SetPath(const wxString& dirname); }; @@ -246,20 +319,29 @@ public: 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 { public: + wxFileDirPickerEvent(); + /** The constructor is not normally used by the user code. */ 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.