interface/wx/filepicker.h

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