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 licence
   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 dialog.
  16     It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
  17
  18     @beginStyleTable
  19     @style{wxFLP_DEFAULT_STYLE}
  20            The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and,
  21            under wxMSW only, wxFLP_USE_TEXTCTRL.
  22     @style{wxFLP_USE_TEXTCTRL}
  23            Creates a text control to the left of the picker button which is
  24            completely managed by the wxFilePickerCtrl and which can be used by
  25            the user to specify a path (see SetPath). The text control is
  26            automatically synchronized with button's value. Use functions
  27            defined in wxPickerBase to modify the text control.
  28     @style{wxFLP_OPEN}
  29            Creates a picker which allows the user to select a file to open.
  30     @style{wxFLP_SAVE}
  31            Creates a picker which allows the user to select a file to save.
  32     @style{wxFLP_OVERWRITE_PROMPT}
  33            Can be combined with wxFLP_SAVE only: ask confirmation to the user
  34            before selecting a file.
  35     @style{wxFLP_FILE_MUST_EXIST}
  36            Can be combined with wxFLP_OPEN only: the selected file must be an
  37            existing file.
  38     @style{wxFLP_CHANGE_DIR}
  39            Change current working directory on each user file selection change.
  40     @style{wxFLP_SMALL}
  41            Use smaller version of the control with a small "..." button instead
  42            of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.
  43     @endStyleTable
  44
  45
  46     @beginEventEmissionTable{wxFileDirPickerEvent}
  47     @event{EVT_FILEPICKER_CHANGED(id, func)}
  48         The user changed the file selected in the control either using the
  49         button or using text control (see wxFLP_USE_TEXTCTRL; note that in
  50         this case the event is fired only if the user's input is valid,
  51         e.g. an existing file path if wxFLP_FILE_MUST_EXIST was given).
  52     @endEventTable
  53
  54     @library{wxcore}
  55     @category{pickers}
  56     @appearance{filepickerctrl.png}
  57
  58     @see wxFileDialog, wxFileDirPickerEvent
  59 */
  60 class wxFilePickerCtrl : public wxPickerBase
  61 {
  62 public:
  63     /**
  64         Initializes the object and calls Create() with
  65         all the parameters.
  66     */
  67     wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
  68                      const wxString& path = wxEmptyString,
  69                      const wxString& message = wxFileSelectorPromptStr,
  70                      const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
  71                      const wxPoint& pos = wxDefaultPosition,
  72                      const wxSize& size = wxDefaultSize,
  73                      long style = wxFLP_DEFAULT_STYLE,
  74                      const wxValidator& validator = wxDefaultValidator,
  75                      const wxString& name = wxFilePickerCtrlNameStr);
  76
  77     /**
  78         Creates this widget with the given parameters.
  79
  80         @param parent
  81             Parent window, must not be non-@NULL.
  82         @param id
  83             The identifier for the control.
  84         @param path
  85             The initial file shown in the control. Must be a valid path to a file or
  86             the empty string.
  87         @param message
  88             The message shown to the user in the wxFileDialog shown by the control.
  89         @param wildcard
  90             A wildcard which defines user-selectable files (use the same syntax as for
  91             wxFileDialog's wildcards).
  92         @param pos
  93             Initial position.
  94         @param size
  95             Initial size.
  96         @param style
  97             The window style, see wxFLP_* flags.
  98         @param validator
  99             Validator which can be used for additional data checks.
 100         @param name
 101             Control name.
 102
 103         @return @true if the control was successfully created or @false if
 104                 creation failed.
 105     */
 106     bool Create(wxWindow* parent, wxWindowID id,
 107                 const wxString& path = wxEmptyString,
 108                 const wxString& message = wxFileSelectorPromptStr,
 109                 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 110                 const wxPoint& pos = wxDefaultPosition,
 111                 const wxSize& size = wxDefaultSize,
 112                 long style = wxFLP_DEFAULT_STYLE,
 113                 const wxValidator& validator = wxDefaultValidator,
 114                 const wxString& name = wxFilePickerCtrlNameStr);
 115
 116     /**
 117         Similar to GetPath() but returns the path of the currently selected
 118         file as a wxFileName object.
 119     */
 120     wxFileName GetFileName() const;
 121
 122     /**
 123         Returns the absolute path of the currently selected file.
 124     */
 125     wxString GetPath() const;
 126
 127     /**
 128         This method does the same thing as SetPath() but takes a wxFileName
 129         object instead of a string.
 130     */
 131     void SetFileName(const wxFileName& filename);
 132
 133     /**
 134         Set the directory to show when starting to browse for files.
 135
 136         This function is mostly useful for the file picker controls which have
 137         no selection initially to configure the directory that should be shown
 138         if the user starts browsing for files as otherwise the directory of
 139         initially selected file is used, which is usually the desired
 140         behaviour and so the directory specified by this function is ignored in
 141         this case.
 142
 143         @since 2.9.4
 144      */
 145     void SetInitialDirectory(const wxString& dir);
 146
 147     /**
 148         Sets the absolute path of the currently selected file.
 149         This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given.
 150     */
 151     void SetPath(const wxString& filename);
 152 };
 153
 154
 155
 156 /**
 157     @class wxDirPickerCtrl
 158
 159     This control allows the user to select a directory. The generic implementation
 160     is a button which brings up a wxDirDialog when clicked. Native implementation
 161     may differ but this is usually a (small) widget which give access to the
 162     dir-chooser dialog.
 163     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 164
 165     @beginStyleTable
 166     @style{wxDIRP_DEFAULT_STYLE}
 167            The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW
 168            only, wxDIRP_USE_TEXTCTRL.
 169     @style{wxDIRP_USE_TEXTCTRL}
 170            Creates a text control to the left of the picker button which is
 171            completely managed by the wxDirPickerCtrl and which can be used by
 172            the user to specify a path (see SetPath). The text control is
 173            automatically synchronized with button's value. Use functions
 174            defined in wxPickerBase to modify the text control.
 175     @style{wxDIRP_DIR_MUST_EXIST}
 176            Creates a picker which allows to select only existing directories.
 177            wxGTK control always adds this flag internally as it does not
 178            support its absence.
 179     @style{wxDIRP_CHANGE_DIR}
 180            Change current working directory on each user directory selection change.
 181     @style{wxDIRP_SMALL}
 182            Use smaller version of the control with a small "..." button instead
 183            of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.
 184     @endStyleTable
 185
 186     @beginEventEmissionTable{wxFileDirPickerEvent}
 187     @event{EVT_DIRPICKER_CHANGED(id, func)}
 188         The user changed the directory selected in the control either using the
 189         button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this
 190         case the event is fired only if the user's input is valid, e.g. an
 191         existing directory path).
 192     @endEventTable
 193
 194
 195     @library{wxcore}
 196     @category{pickers}
 197     @appearance{dirpickerctrl.png}
 198
 199     @see wxDirDialog, wxFileDirPickerEvent
 200 */
 201 class wxDirPickerCtrl : public wxPickerBase
 202 {
 203 public:
 204     /**
 205         Initializes the object and calls Create() with
 206         all the parameters.
 207     */
 208     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
 209                     const wxString& path = wxEmptyString,
 210                     const wxString& message = wxDirSelectorPromptStr,
 211                     const wxPoint& pos = wxDefaultPosition,
 212                     const wxSize& size = wxDefaultSize,
 213                     long style = wxDIRP_DEFAULT_STYLE,
 214                     const wxValidator& validator = wxDefaultValidator,
 215                     const wxString& name = wxDirPickerCtrlNameStr);
 216
 217     /**
 218         Creates the widgets with the given parameters.
 219
 220         @param parent
 221             Parent window, must not be non-@NULL.
 222         @param id
 223             The identifier for the control.
 224         @param path
 225             The initial directory shown in the control. Must be a valid path to a
 226             directory or the empty string.
 227         @param message
 228             The message shown to the user in the wxDirDialog shown by the control.
 229         @param pos
 230             Initial position.
 231         @param size
 232             Initial size.
 233         @param style
 234             The window style, see wxDIRP_* flags.
 235         @param validator
 236             Validator which can be used for additional date checks.
 237         @param name
 238             Control name.
 239
 240         @return @true if the control was successfully created or @false if
 241                 creation failed.
 242     */
 243     bool Create(wxWindow* parent, wxWindowID id,
 244                 const wxString& path = wxEmptyString,
 245                 const wxString& message = wxDirSelectorPromptStr,
 246                 const wxPoint& pos = wxDefaultPosition,
 247                 const wxSize& size = wxDefaultSize,
 248                 long style = wxDIRP_DEFAULT_STYLE,
 249                 const wxValidator& validator = wxDefaultValidator,
 250                 const wxString& name = wxDirPickerCtrlNameStr);
 251
 252     /**
 253         Returns the absolute path of the currently selected directory as a
 254         wxFileName object.
 255         This function is equivalent to GetPath().
 256     */
 257     wxFileName GetDirName() const;
 258
 259     /**
 260         Returns the absolute path of the currently selected directory.
 261     */
 262     wxString GetPath() const;
 263
 264     /**
 265         Just like SetPath() but this function takes a wxFileName object.
 266     */
 267     void SetDirName(const wxFileName& dirname);
 268
 269     /**
 270         Set the directory to show when starting to browse for directories.
 271
 272         This function is mostly useful for the directory picker controls which
 273         have no selection initially to configure the directory that should be
 274         shown if the user starts browsing for directories as otherwise the
 275         initially selected directory is used, which is usually the desired
 276         behaviour and so the directory specified by this function is ignored in
 277         this case.
 278
 279         @since 2.9.4
 280      */
 281     void SetInitialDirectory(const wxString& dir);
 282
 283     /**
 284         Sets the absolute path of  (the default converter uses current locale's
 285         charset)the currently selected directory.
 286         This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given.
 287     */
 288     void SetPath(const wxString& dirname);
 289 };
 290
 291
 292
 293 /**
 294     @class wxFileDirPickerEvent
 295
 296     This event class is used for the events generated by
 297     wxFilePickerCtrl and by wxDirPickerCtrl.
 298
 299     @beginEventTable{wxFileDirPickerEvent}
 300     @event{EVT_FILEPICKER_CHANGED(id, func)}
 301         Generated whenever the selected file changes.
 302     @event{EVT_DIRPICKER_CHANGED(id, func)}
 303         Generated whenever the selected directory changes.
 304     @endEventTable
 305
 306     @library{wxcore}
 307     @category{events}
 308
 309     @see wxFilePickerCtrl, wxDirPickerCtrl
 310 */
 311 class wxFileDirPickerEvent : public wxCommandEvent
 312 {
 313 public:
 314     /**
 315         The constructor is not normally used by the user code.
 316     */
 317     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
 318                          int id,
 319                          const wxString& path);
 320
 321     /**
 322         Retrieve the absolute path of the file/directory the user has just selected.
 323     */
 324     wxString GetPath() const;
 325
 326     /**
 327         Set the absolute path of the file/directory associated with the event.
 328     */
 329     void SetPath(const wxString& path);
 330 };
 331