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         Sets the absolute path of the currently selected file.
 135         This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given.
 136     */
 137     void SetPath(const wxString& filename);
 138 };
 139
 140
 141
 142 /**
 143     @class wxDirPickerCtrl
 144
 145     This control allows the user to select a directory. The generic implementation
 146     is a button which brings up a wxDirDialog when clicked. Native implementation
 147     may differ but this is usually a (small) widget which give access to the
 148     dir-chooser dialog.
 149     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 150
 151     @beginStyleTable
 152     @style{wxDIRP_DEFAULT_STYLE}
 153            The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW
 154            only, wxDIRP_USE_TEXTCTRL.
 155     @style{wxDIRP_USE_TEXTCTRL}
 156            Creates a text control to the left of the picker button which is
 157            completely managed by the wxDirPickerCtrl and which can be used by
 158            the user to specify a path (see SetPath). The text control is
 159            automatically synchronized with button's value. Use functions
 160            defined in wxPickerBase to modify the text control.
 161     @style{wxDIRP_DIR_MUST_EXIST}
 162            Creates a picker which allows to select only existing directories.
 163            wxGTK control always adds this flag internally as it does not
 164            support its absence.
 165     @style{wxDIRP_CHANGE_DIR}
 166            Change current working directory on each user directory selection change.
 167     @style{wxDIRP_SMALL}
 168            Use smaller version of the control with a small "..." button instead
 169            of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.
 170     @endStyleTable
 171
 172     @beginEventEmissionTable{wxFileDirPickerEvent}
 173     @event{EVT_DIRPICKER_CHANGED(id, func)}
 174         The user changed the directory selected in the control either using the
 175         button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this
 176         case the event is fired only if the user's input is valid, e.g. an
 177         existing directory path).
 178     @endEventTable
 179
 180
 181     @library{wxcore}
 182     @category{pickers}
 183     @appearance{dirpickerctrl.png}
 184
 185     @see wxDirDialog, wxFileDirPickerEvent
 186 */
 187 class wxDirPickerCtrl : public wxPickerBase
 188 {
 189 public:
 190     /**
 191         Initializes the object and calls Create() with
 192         all the parameters.
 193     */
 194     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
 195                     const wxString& path = wxEmptyString,
 196                     const wxString& message = wxDirSelectorPromptStr,
 197                     const wxPoint& pos = wxDefaultPosition,
 198                     const wxSize& size = wxDefaultSize,
 199                     long style = wxDIRP_DEFAULT_STYLE,
 200                     const wxValidator& validator = wxDefaultValidator,
 201                     const wxString& name = wxDirPickerCtrlNameStr);
 202
 203     /**
 204         Creates the widgets with the given parameters.
 205
 206         @param parent
 207             Parent window, must not be non-@NULL.
 208         @param id
 209             The identifier for the control.
 210         @param path
 211             The initial directory shown in the control. Must be a valid path to a
 212             directory or the empty string.
 213         @param message
 214             The message shown to the user in the wxDirDialog shown by the control.
 215         @param pos
 216             Initial position.
 217         @param size
 218             Initial size.
 219         @param style
 220             The window style, see wxDIRP_* flags.
 221         @param validator
 222             Validator which can be used for additional date checks.
 223         @param name
 224             Control name.
 225
 226         @return @true if the control was successfully created or @false if
 227                 creation failed.
 228     */
 229     bool Create(wxWindow* parent, wxWindowID id,
 230                 const wxString& path = wxEmptyString,
 231                 const wxString& message = wxDirSelectorPromptStr,
 232                 const wxPoint& pos = wxDefaultPosition,
 233                 const wxSize& size = wxDefaultSize,
 234                 long style = wxDIRP_DEFAULT_STYLE,
 235                 const wxValidator& validator = wxDefaultValidator,
 236                 const wxString& name = wxDirPickerCtrlNameStr);
 237
 238     /**
 239         Returns the absolute path of the currently selected directory as a
 240         wxFileName object.
 241         This function is equivalent to GetPath().
 242     */
 243     wxFileName GetDirName() const;
 244
 245     /**
 246         Returns the absolute path of the currently selected directory.
 247     */
 248     wxString GetPath() const;
 249
 250     /**
 251         Just like SetPath() but this function takes a wxFileName object.
 252     */
 253     void SetDirName(const wxFileName& dirname);
 254
 255     /**
 256         Sets the absolute path of  (the default converter uses current locale's
 257         charset)the currently selected directory.
 258         This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given.
 259     */
 260     void SetPath(const wxString& dirname);
 261 };
 262
 263
 264
 265 /**
 266     @class wxFileDirPickerEvent
 267
 268     This event class is used for the events generated by
 269     wxFilePickerCtrl and by wxDirPickerCtrl.
 270
 271     @beginEventTable{wxFileDirPickerEvent}
 272     @event{EVT_FILEPICKER_CHANGED(id, func)}
 273         Generated whenever the selected file changes.
 274     @event{EVT_DIRPICKER_CHANGED(id, func)}
 275         Generated whenever the selected directory changes.
 276     @endEventTable
 277
 278     @library{wxcore}
 279     @category{events}
 280
 281     @see wxFilePickerCtrl, wxDirPickerCtrl
 282 */
 283 class wxFileDirPickerEvent : public wxCommandEvent
 284 {
 285 public:
 286     /**
 287         The constructor is not normally used by the user code.
 288     */
 289     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
 290                          int id,
 291                          const wxString& path);
 292
 293     /**
 294         Retrieve the absolute path of the file/directory the user has just selected.
 295     */
 296     wxString GetPath() const;
 297
 298     /**
 299         Set the absolute path of the file/directory associated with the event.
 300     */
 301     void SetPath(const wxString& path);
 302 };
 303