Make the CreateTool factories be public so they can be used from application code

[wxWidgets.git] / interface / wx / filepicker.h

diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h
index 5df6c196fdfff53e45ba06d2bd91bce51156cc3c..3053fcefc38c3e32856293d9fb4b768242a16d00 100644 (file)
--- a/interface/wx/filepicker.h
+++ b/interface/wx/filepicker.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxFilePickerCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxFilePickerCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -12,8 +12,7 @@
     This control allows the user to select a file. The generic implementation is
     a button which brings up a wxFileDialog when clicked. Native implementation
     may differ but this is usually a (small) widget which give access to the
     This control allows the user to select a file. The generic implementation is
     a button which brings up a wxFileDialog when clicked. Native implementation
     may differ but this is usually a (small) widget which give access to the

-    file-chooser
-    dialog.
+    file-chooser dialog.

     It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
 
     @beginStyleTable
     It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
 
     @beginStyleTable


@@ -38,11 +37,23 @@
            existing file.
     @style{wxFLP_CHANGE_DIR}
            Change current working directory on each user file selection change.
            existing file.
     @style{wxFLP_CHANGE_DIR}
            Change current working directory on each user file selection change.

+    @style{wxFLP_SMALL}
+           Use smaller version of the control with a small "..." button instead
+           of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.

     @endStyleTable
 
     @endStyleTable
 

+
+    @beginEventEmissionTable{wxFileDirPickerEvent}
+    @event{EVT_FILEPICKER_CHANGED(id, func)}
+        The user changed the file selected in the control either using the
+        button or using text control (see wxFLP_USE_TEXTCTRL; note that in
+        this case the event is fired only if the user's input is valid,
+        e.g. an existing file path if wxFLP_FILE_MUST_EXIST was given).
+    @endEventTable
+

     @library{wxcore}
     @category{pickers}
     @library{wxcore}
     @category{pickers}

-    <!-- @appearance{filepickerctrl.png} -->
+    @appearance{filepickerctrl.png}

 
     @see wxFileDialog, wxFileDirPickerEvent
 */
 
     @see wxFileDialog, wxFileDirPickerEvent
 */


@@ -55,27 +66,29 @@ public:
     */
     wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
                      const wxString& path = wxEmptyString,
     */
     wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
                      const wxString& path = wxEmptyString,

-                     const wxString& message = "Select a file",
-                     const wxString& wildcard = ".",
+                     const wxString& message = wxFileSelectorPromptStr,
+                     const wxString& wildcard = wxFileSelectorDefaultWildcardStr,

                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxFLP_DEFAULT_STYLE,
                      const wxValidator& validator = wxDefaultValidator,
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxFLP_DEFAULT_STYLE,
                      const wxValidator& validator = wxDefaultValidator,

-                     const wxString& name = "filepickerctrl");
+                     const wxString& name = wxFilePickerCtrlNameStr);

 
     /**
 
     /**

+        Creates this widget with the given parameters.
+

         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param path
             The initial file shown in the control. Must be a valid path to a file or
         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param path
             The initial file shown in the control. Must be a valid path to a file or

-        the empty string.
+            the empty string.

         @param message
             The message shown to the user in the wxFileDialog shown by the control.
         @param wildcard
             A wildcard which defines user-selectable files (use the same syntax as for
         @param message
             The message shown to the user in the wxFileDialog shown by the control.
         @param wildcard
             A wildcard which defines user-selectable files (use the same syntax as for

-        wxFileDialog's wildcards).
+            wxFileDialog's wildcards).

         @param pos
             Initial position.
         @param size
         @param pos
             Initial position.
         @param size


@@ -83,26 +96,26 @@ public:
         @param style
             The window style, see wxFLP_* flags.
         @param validator
         @param style
             The window style, see wxFLP_* flags.
         @param validator

-            Validator which can be used for additional date checks.
+            Validator which can be used for additional data checks.

         @param name
             Control name.
 
         @return @true if the control was successfully created or @false if
         @param name
             Control name.
 
         @return @true if the control was successfully created or @false if

-                 creation failed.
+                creation failed.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& path = wxEmptyString,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& path = wxEmptyString,

-                const wxString& message = "Select a file",
-                const wxString& wildcard = ".",
+                const wxString& message = wxFileSelectorPromptStr,
+                const wxString& wildcard = wxFileSelectorDefaultWildcardStr,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxFLP_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxFLP_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "filepickerctrl");
+                const wxString& name = wxFilePickerCtrlNameStr);

 
     /**
 
     /**

-        Similar to GetPath() but returns the path of
-        the currently selected file as a wxFileName object.
+        Similar to GetPath() but returns the path of the currently selected
+        file as a wxFileName object.

     */
     wxFileName GetFileName() const;
 
     */
     wxFileName GetFileName() const;
 


@@ -112,15 +125,28 @@ public:
     wxString GetPath() const;
 
     /**
     wxString GetPath() const;
 
     /**

-        This method does the same thing as SetPath() but
-        takes a wxFileName object instead of a string.
+        This method does the same thing as SetPath() but takes a wxFileName
+        object instead of a string.

     */
     void SetFileName(const wxFileName& filename);
 
     /**
     */
     void SetFileName(const wxFileName& filename);
 
     /**

-        Sets the absolute path of the currently selected file. This must be a valid
-        file if
-        the @c wxFLP_FILE_MUST_EXIST style was given.
+        Set the directory to show when starting to browse for files.
+
+        This function is mostly useful for the file picker controls which have
+        no selection initially to configure the directory that should be shown
+        if the user starts browsing for files as otherwise the directory of
+        initially selected file is used, which is usually the desired
+        behaviour and so the directory specified by this function is ignored in
+        this case.
+
+        @since 2.9.4
+     */
+    void SetInitialDirectory(const wxString& dir);
+
+    /**
+        Sets the absolute path of the currently selected file.
+        This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given.

     */
     void SetPath(const wxString& filename);
 };
     */
     void SetPath(const wxString& filename);
 };


@@ -131,11 +157,9 @@ public:
     @class wxDirPickerCtrl
 
     This control allows the user to select a directory. The generic implementation
     @class wxDirPickerCtrl
 
     This control allows the user to select a directory. The generic implementation

-    is
-    a button which brings up a wxDirDialog when clicked. Native implementation
+    is a button which brings up a wxDirDialog when clicked. Native implementation

     may differ but this is usually a (small) widget which give access to the
     may differ but this is usually a (small) widget which give access to the

-    dir-chooser
-    dialog.
+    dir-chooser dialog.

     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 
     @beginStyleTable
     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 
     @beginStyleTable


@@ -153,13 +177,24 @@ public:
            wxGTK control always adds this flag internally as it does not
            support its absence.
     @style{wxDIRP_CHANGE_DIR}
            wxGTK control always adds this flag internally as it does not
            support its absence.
     @style{wxDIRP_CHANGE_DIR}

-           Change current working directory on each user directory selection
-           change.
+           Change current working directory on each user directory selection change.
+    @style{wxDIRP_SMALL}
+           Use smaller version of the control with a small "..." button instead
+           of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.

     @endStyleTable
 
     @endStyleTable
 

+    @beginEventEmissionTable{wxFileDirPickerEvent}
+    @event{EVT_DIRPICKER_CHANGED(id, func)}
+        The user changed the directory selected in the control either using the
+        button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this
+        case the event is fired only if the user's input is valid, e.g. an
+        existing directory path).
+    @endEventTable
+
+

     @library{wxcore}
     @category{pickers}
     @library{wxcore}
     @category{pickers}

-    <!-- @appearance{dirpickerctrl.png} -->
+    @appearance{dirpickerctrl.png}

 
     @see wxDirDialog, wxFileDirPickerEvent
 */
 
     @see wxDirDialog, wxFileDirPickerEvent
 */


@@ -172,21 +207,23 @@ public:
     */
     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
                     const wxString& path = wxEmptyString,
     */
     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
                     const wxString& path = wxEmptyString,

-                    const wxString& message = "Select a folder",
+                    const wxString& message = wxDirSelectorPromptStr,

                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDIRP_DEFAULT_STYLE,
                     const wxValidator& validator = wxDefaultValidator,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDIRP_DEFAULT_STYLE,
                     const wxValidator& validator = wxDefaultValidator,

-                    const wxString& name = "dirpickerctrl");
+                    const wxString& name = wxDirPickerCtrlNameStr);

 
     /**
 
     /**

+        Creates the widgets with the given parameters.
+

         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param path
             The initial directory shown in the control. Must be a valid path to a
         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param path
             The initial directory shown in the control. Must be a valid path to a

-        directory or the empty string.
+            directory or the empty string.

         @param message
             The message shown to the user in the wxDirDialog shown by the control.
         @param pos
         @param message
             The message shown to the user in the wxDirDialog shown by the control.
         @param pos


@@ -201,21 +238,21 @@ public:
             Control name.
 
         @return @true if the control was successfully created or @false if
             Control name.
 
         @return @true if the control was successfully created or @false if

-                 creation failed.
+                creation failed.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& path = wxEmptyString,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& path = wxEmptyString,

-                const wxString& message = "Select a folder",
+                const wxString& message = wxDirSelectorPromptStr,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxDIRP_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxDIRP_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "dirpickerctrl");
+                const wxString& name = wxDirPickerCtrlNameStr);

 
     /**
 
     /**

-        Returns the absolute path of the currently selected directory as a wxFileName
-        object.
-        This function is equivalent to GetPath()
+        Returns the absolute path of the currently selected directory as a
+        wxFileName object.
+        This function is equivalent to GetPath().

     */
     wxFileName GetDirName() const;
 
     */
     wxFileName GetDirName() const;
 


@@ -225,15 +262,28 @@ public:
     wxString GetPath() const;
 
     /**
     wxString GetPath() const;
 
     /**

-        Just like SetPath() but this function takes a
-        wxFileName object.
+        Just like SetPath() but this function takes a wxFileName object.

     */
     void SetDirName(const wxFileName& dirname);
 
     */
     void SetDirName(const wxFileName& dirname);
 

+    /**
+        Set the directory to show when starting to browse for directories.
+
+        This function is mostly useful for the directory picker controls which
+        have no selection initially to configure the directory that should be
+        shown if the user starts browsing for directories as otherwise the
+        initially selected directory is used, which is usually the desired
+        behaviour and so the directory specified by this function is ignored in
+        this case.
+
+        @since 2.9.4
+     */
+    void SetInitialDirectory(const wxString& dir);
+

     /**
         Sets the absolute path of  (the default converter uses current locale's
     /**
         Sets the absolute path of  (the default converter uses current locale's

-        charset)the currently selected directory. This must be a valid directory if
-        @c wxDIRP_DIR_MUST_EXIST style was given.
+        charset)the currently selected directory.
+        This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given.

     */
     void SetPath(const wxString& dirname);
 };
     */
     void SetPath(const wxString& dirname);
 };


@@ -246,10 +296,17 @@ public:
     This event class is used for the events generated by
     wxFilePickerCtrl and by wxDirPickerCtrl.
 
     This event class is used for the events generated by
     wxFilePickerCtrl and by wxDirPickerCtrl.
 

+    @beginEventTable{wxFileDirPickerEvent}
+    @event{EVT_FILEPICKER_CHANGED(id, func)}
+        Generated whenever the selected file changes.
+    @event{EVT_DIRPICKER_CHANGED(id, func)}
+        Generated whenever the selected directory changes.
+    @endEventTable
+

     @library{wxcore}
     @library{wxcore}

-    @category{FIXME}
+    @category{events}

 
 

-    @see wxfilepickerctrl()
+    @see wxFilePickerCtrl, wxDirPickerCtrl

 */
 class wxFileDirPickerEvent : public wxCommandEvent
 {
 */
 class wxFileDirPickerEvent : public wxCommandEvent
 {


@@ -259,7 +316,7 @@ public:
     */
     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
                          int id,
     */
     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
                          int id,

-                         const wxString path);
+                         const wxString& path);

 
     /**
         Retrieve the absolute path of the file/directory the user has just selected.
 
     /**
         Retrieve the absolute path of the file/directory the user has just selected.