interface/wx/filepicker.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filepicker.h
   3 // Purpose:     interface of wxFilePickerCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFilePickerCtrl
  11
  12     This control allows the user to select a file. The generic implementation is
  13     a button which brings up a wxFileDialog when clicked. Native implementation
  14     may differ but this is usually a (small) widget which give access to the
  15     file-chooser
  16     dialog.
  17     It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
  18
  19     @beginStyleTable
  20     @style{wxFLP_DEFAULT_STYLE}
  21            The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and,
  22            under wxMSW only, wxFLP_USE_TEXTCTRL.
  23     @style{wxFLP_USE_TEXTCTRL}
  24            Creates a text control to the left of the picker button which is
  25            completely managed by the wxFilePickerCtrl and which can be used by
  26            the user to specify a path (see SetPath). The text control is
  27            automatically synchronized with button's value. Use functions
  28            defined in wxPickerBase to modify the text control.
  29     @style{wxFLP_OPEN}
  30            Creates a picker which allows the user to select a file to open.
  31     @style{wxFLP_SAVE}
  32            Creates a picker which allows the user to select a file to save.
  33     @style{wxFLP_OVERWRITE_PROMPT}
  34            Can be combined with wxFLP_SAVE only: ask confirmation to the user
  35            before selecting a file.
  36     @style{wxFLP_FILE_MUST_EXIST}
  37            Can be combined with wxFLP_OPEN only: the selected file must be an
  38            existing file.
  39     @style{wxFLP_CHANGE_DIR}
  40            Change current working directory on each user file selection change.
  41     @endStyleTable
  42
  43     @library{wxcore}
  44     @category{pickers}
  45     <!-- @appearance{filepickerctrl.png} -->
  46
  47     @see wxFileDialog, wxFileDirPickerEvent
  48 */
  49 class wxFilePickerCtrl : public wxPickerBase
  50 {
  51 public:
  52     /**
  53         Initializes the object and calls Create() with
  54         all the parameters.
  55     */
  56     wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
  57                      const wxString& path = wxEmptyString,
  58                      const wxString& message = "Select a file",
  59                      const wxString& wildcard = ".",
  60                      const wxPoint& pos = wxDefaultPosition,
  61                      const wxSize& size = wxDefaultSize,
  62                      long style = wxFLP_DEFAULT_STYLE,
  63                      const wxValidator& validator = wxDefaultValidator,
  64                      const wxString& name = "filepickerctrl");
  65
  66     /**
  67         @param parent
  68             Parent window, must not be non-@NULL.
  69         @param id
  70             The identifier for the control.
  71         @param path
  72             The initial file shown in the control. Must be a valid path to a file or
  73         the empty string.
  74         @param message
  75             The message shown to the user in the wxFileDialog shown by the control.
  76         @param wildcard
  77             A wildcard which defines user-selectable files (use the same syntax as for
  78         wxFileDialog's wildcards).
  79         @param pos
  80             Initial position.
  81         @param size
  82             Initial size.
  83         @param style
  84             The window style, see wxFLP_* flags.
  85         @param validator
  86             Validator which can be used for additional date checks.
  87         @param name
  88             Control name.
  89
  90         @return @true if the control was successfully created or @false if
  91                  creation failed.
  92     */
  93     bool Create(wxWindow* parent, wxWindowID id,
  94                 const wxString& path = wxEmptyString,
  95                 const wxString& message = "Select a file",
  96                 const wxString& wildcard = ".",
  97                 const wxPoint& pos = wxDefaultPosition,
  98                 const wxSize& size = wxDefaultSize,
  99                 long style = wxFLP_DEFAULT_STYLE,
 100                 const wxValidator& validator = wxDefaultValidator,
 101                 const wxString& name = "filepickerctrl");
 102
 103     /**
 104         Similar to GetPath() but returns the path of
 105         the currently selected file as a wxFileName object.
 106     */
 107     wxFileName GetFileName() const;
 108
 109     /**
 110         Returns the absolute path of the currently selected file.
 111     */
 112     wxString GetPath() const;
 113
 114     /**
 115         This method does the same thing as SetPath() but
 116         takes a wxFileName object instead of a string.
 117     */
 118     void SetFileName(const wxFileName& filename);
 119
 120     /**
 121         Sets the absolute path of the currently selected file. This must be a valid
 122         file if
 123         the @c wxFLP_FILE_MUST_EXIST style was given.
 124     */
 125     void SetPath(const wxString& filename);
 126 };
 127
 128
 129
 130 /**
 131     @class wxDirPickerCtrl
 132
 133     This control allows the user to select a directory. The generic implementation
 134     is
 135     a button which brings up a wxDirDialog when clicked. Native implementation
 136     may differ but this is usually a (small) widget which give access to the
 137     dir-chooser
 138     dialog.
 139     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 140
 141     @beginStyleTable
 142     @style{wxDIRP_DEFAULT_STYLE}
 143            The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW
 144            only, wxDIRP_USE_TEXTCTRL.
 145     @style{wxDIRP_USE_TEXTCTRL}
 146            Creates a text control to the left of the picker button which is
 147            completely managed by the wxDirPickerCtrl and which can be used by
 148            the user to specify a path (see SetPath). The text control is
 149            automatically synchronized with button's value. Use functions
 150            defined in wxPickerBase to modify the text control.
 151     @style{wxDIRP_DIR_MUST_EXIST}
 152            Creates a picker which allows to select only existing directories.
 153            wxGTK control always adds this flag internally as it does not
 154            support its absence.
 155     @style{wxDIRP_CHANGE_DIR}
 156            Change current working directory on each user directory selection
 157            change.
 158     @endStyleTable
 159
 160     @library{wxcore}
 161     @category{pickers}
 162     <!-- @appearance{dirpickerctrl.png} -->
 163
 164     @see wxDirDialog, wxFileDirPickerEvent
 165 */
 166 class wxDirPickerCtrl : public wxPickerBase
 167 {
 168 public:
 169     /**
 170         Initializes the object and calls Create() with
 171         all the parameters.
 172     */
 173     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
 174                     const wxString& path = wxEmptyString,
 175                     const wxString& message = "Select a folder",
 176                     const wxPoint& pos = wxDefaultPosition,
 177                     const wxSize& size = wxDefaultSize,
 178                     long style = wxDIRP_DEFAULT_STYLE,
 179                     const wxValidator& validator = wxDefaultValidator,
 180                     const wxString& name = "dirpickerctrl");
 181
 182     /**
 183         @param parent
 184             Parent window, must not be non-@NULL.
 185         @param id
 186             The identifier for the control.
 187         @param path
 188             The initial directory shown in the control. Must be a valid path to a
 189         directory or the empty string.
 190         @param message
 191             The message shown to the user in the wxDirDialog shown by the control.
 192         @param pos
 193             Initial position.
 194         @param size
 195             Initial size.
 196         @param style
 197             The window style, see wxDIRP_* flags.
 198         @param validator
 199             Validator which can be used for additional date checks.
 200         @param name
 201             Control name.
 202
 203         @return @true if the control was successfully created or @false if
 204                  creation failed.
 205     */
 206     bool Create(wxWindow* parent, wxWindowID id,
 207                 const wxString& path = wxEmptyString,
 208                 const wxString& message = "Select a folder",
 209                 const wxPoint& pos = wxDefaultPosition,
 210                 const wxSize& size = wxDefaultSize,
 211                 long style = wxDIRP_DEFAULT_STYLE,
 212                 const wxValidator& validator = wxDefaultValidator,
 213                 const wxString& name = "dirpickerctrl");
 214
 215     /**
 216         Returns the absolute path of the currently selected directory as a wxFileName
 217         object.
 218         This function is equivalent to GetPath()
 219     */
 220     wxFileName GetDirName() const;
 221
 222     /**
 223         Returns the absolute path of the currently selected directory.
 224     */
 225     wxString GetPath() const;
 226
 227     /**
 228         Just like SetPath() but this function takes a
 229         wxFileName object.
 230     */
 231     void SetDirName(const wxFileName& dirname);
 232
 233     /**
 234         Sets the absolute path of  (the default converter uses current locale's
 235         charset)the currently selected directory. This must be a valid directory if
 236         @c wxDIRP_DIR_MUST_EXIST style was given.
 237     */
 238     void SetPath(const wxString& dirname);
 239 };
 240
 241
 242
 243 /**
 244     @class wxFileDirPickerEvent
 245
 246     This event class is used for the events generated by
 247     wxFilePickerCtrl and by wxDirPickerCtrl.
 248
 249     @library{wxcore}
 250     @category{FIXME}
 251
 252     @see wxfilepickerctrl()
 253 */
 254 class wxFileDirPickerEvent : public wxCommandEvent
 255 {
 256 public:
 257     /**
 258         The constructor is not normally used by the user code.
 259     */
 260     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
 261                          int id,
 262                          const wxString path);
 263
 264     /**
 265         Retrieve the absolute path of the file/directory the user has just selected.
 266     */
 267     wxString GetPath() const;
 268
 269     /**
 270         Set the absolute path of the file/directory associated with the event.
 271     */
 272     void SetPath(const wxString& path);
 273 };
 274