interface/filepicker.h

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