GtkFileChooser             package:RGtk2             R Documentation

_G_t_k_F_i_l_e_C_h_o_o_s_e_r

_D_e_s_c_r_i_p_t_i_o_n:

     File chooser interface used by GtkFileChooserWidget and
     GtkFileChooserDialog

_M_e_t_h_o_d_s _a_n_d _F_u_n_c_t_i_o_n_s:

     'gtkFileChooserSetAction(object, action)'
      'gtkFileChooserGetAction(object)'
      'gtkFileChooserSetLocalOnly(object, local.only)'
      'gtkFileChooserGetLocalOnly(object)'
      'gtkFileChooserSetSelectMultiple(object, select.multiple)'
      'gtkFileChooserGetSelectMultiple(object)'
      'gtkFileChooserSetShowHidden(object, show.hidden)'
      'gtkFileChooserGetShowHidden(object)'
      'gtkFileChooserSetDoOverwriteConfirmation(object,
     do.overwrite.confirmation)'
      'gtkFileChooserGetDoOverwriteConfirmation(object)'
      'gtkFileChooserSetCurrentName(object, name)'
      'gtkFileChooserGetFilename(object)'
      'gtkFileChooserSetFilename(object, filename)'
      'gtkFileChooserSelectFilename(object, filename)'
      'gtkFileChooserUnselectFilename(object, filename)'
      'gtkFileChooserSelectAll(object)'
      'gtkFileChooserUnselectAll(object)'
      'gtkFileChooserGetFilenames(object)'
      'gtkFileChooserSetCurrentFolder(object, filename)'
      'gtkFileChooserGetCurrentFolder(object)'
      'gtkFileChooserGetUri(object)'
      'gtkFileChooserSetUri(object, uri)'
      'gtkFileChooserSelectUri(object, uri)'
      'gtkFileChooserUnselectUri(object, uri)'
      'gtkFileChooserGetUris(object)'
      'gtkFileChooserSetCurrentFolderUri(object, uri)'
      'gtkFileChooserGetCurrentFolderUri(object)'
      'gtkFileChooserSetPreviewWidget(object, preview.widget)'
      'gtkFileChooserGetPreviewWidget(object)'
      'gtkFileChooserSetPreviewWidgetActive(object, active)'
      'gtkFileChooserGetPreviewWidgetActive(object)'
      'gtkFileChooserSetUsePreviewLabel(object, use.label)'
      'gtkFileChooserGetUsePreviewLabel(object)'
      'gtkFileChooserGetPreviewFilename(object)'
      'gtkFileChooserGetPreviewUri(object)'
      'gtkFileChooserSetExtraWidget(object, extra.widget)'
      'gtkFileChooserGetExtraWidget(object)'
      'gtkFileChooserAddFilter(object, filter)'
      'gtkFileChooserRemoveFilter(object, filter)'
      'gtkFileChooserListFilters(object)'
      'gtkFileChooserSetFilter(object, filter)'
      'gtkFileChooserGetFilter(object)'
      'gtkFileChooserAddShortcutFolder(object, folder, .errwarn =
     TRUE)'
      'gtkFileChooserRemoveShortcutFolder(object, folder, .errwarn =
     TRUE)'
      'gtkFileChooserListShortcutFolders(object)'
      'gtkFileChooserAddShortcutFolderUri(object, uri, .errwarn =
     TRUE)'
      'gtkFileChooserRemoveShortcutFolderUri(object, uri, .errwarn =
     TRUE)'
      'gtkFileChooserListShortcutFolderUris(object)'

_H_i_e_r_a_r_c_h_y:

     GInterface
        +----GtkFileChooser 

_I_m_p_l_e_m_e_n_t_a_t_i_o_n_s:

     GtkFileChooser is implemented by 'GtkFileChooserButton', 
     'GtkFileChooserWidget' and  'GtkFileChooserDialog'.

_D_e_t_a_i_l_e_d _D_e_s_c_r_i_p_t_i_o_n:

     'GtkFileChooser' is an interface that can be implemented by file
     selection widgets.  In GTK+, the main objects that implement this
     interface are 'GtkFileChooserWidget', 'GtkFileChooserDialog', and
     'GtkFileChooserButton'.  You do not need to write an object that
     implements the 'GtkFileChooser' interface unless you are trying to
     adapt an existing file selector to expose a standard programming
     interface. 'GtkFileChooser' allows for shortcuts to various places
     in the filesystem. In the default implementation these are
     displayed in the left pane. It may be a bit confusing at first
     taht these shortcuts come from various  sources and in various
     flavours, so lets explain the terminology here:

     _B_o_o_k_m_a_r_k_s are created by the user, by dragging folders from the 
          right pane to the left pane, or by using the "Add". Bookmarks
          can be renamed and deleted by the user.

     _S_h_o_r_t_c_u_t_s can be provided by the application or by the underlying
          filesystem abstraction (e.g. both the gnome-vfs and the
          Windows filesystems  provide "Desktop" shortcuts). Shortcuts
          cannot be modified by the  user.

     _V_o_l_u_m_e_s are provided by the underlying filesystem abstraction.
          They are the "roots" of the filesystem. 


_F_i_l_e _N_a_m_e_s _a_n_d _E_n_c_o_d_i_n_g_s:

     When the user is finished selecting files in a 'GtkFileChooser',
     your program can get the selected names either as filenames or as
     URIs.  For URIs, the normal escaping rules are applied if the URI
     contains non-ASCII characters. However, filenames are _always_
     returned in the character set specified by the
     'G_FILENAME_ENCODING' environment variable. Please see the Glib
     documentation for more details about this variable. *PLEASE NOTE:*
         This means that while you can pass the result of
     'gtkFileChooserGetFilename' to 'open(2)' or 'fopen(3)', you may
     not be able to directly set it as the text of a 'GtkLabel' widget
     unless you convert it first to UTF-8, which all GTK+ widgets
     expect. You should use 'gFilenameToUtf8()' to convert filenames
     into strings that can be passed to GTK+ widgets.

_A_d_d_i_n_g _a _P_r_e_v_i_e_w _W_i_d_g_e_t:

     You can add a custom preview widget to a file chooser and then get
     notification about when the preview needs to be updated. To
     install a preview widget, use 'gtkFileChooserSetPreviewWidget'. 
     Then, connect to the '"update-preview"' signal to get notified
     when you need to update the contents of the preview.

     Your callback should use 'gtkFileChooserGetPreviewFilename' to see
     what needs previewing.  Once you have generated the preview for
     the corresponding file, you must call
     'gtkFileChooserSetPreviewWidgetActive' with a boolean flag that
     indicates whether your callback could successfully generate a
     preview.

     _Sample Usage_


     update_preview_cb <- function(file_chooser, preview)
     {
       filename <- file_chooser$getPreviewFilename()

       pixbuf <- gdkPixbuf(file=filename, w=128, h=128)[[1]]
       have_preview <- !is.null(pixbuf)

       preview$setFromPixbuf(pixbuf)

       file_chooser$setPreviewWidgetActive(have_preview)
     }

     preview <- gtkImage()
     my_file_chooser$setPreviewWidget(preview)
     gSignalConnect(my_file_chooser, "update-preview",
     update_preview_cb, preview)


_A_d_d_i_n_g _E_x_t_r_a _W_i_d_g_e_t_s:

     You can add extra widgets to a file chooser to provide options
     that are not present in the default design.  For example, you can
     add a toggle button to give the user the option to open a file in
     read-only mode.  You can use 'gtkFileChooserSetExtraWidget' to
     insert additional widgets in a file chooser.

     _Sample Usage_


     toggle <- gtkCheckButton("Open file read-only")
     my_file_chooser$setExtraWidget(toggle)
      *PLEASE NOTE:*          If you want to set more than one extra
     widget in the file chooser, you can a container such as a GtkVBox
     or a GtkTable and include your widgets in it.  Then, set the
     container as the whole extra widget.

_K_e_y _B_i_n_d_i_n_g_s:

     Internally, GTK+ implements a file chooser's graphical user
     interface with the private 'GtkFileChooserDefaultClass'.  This
     widget has several key bindings and their associated signals. 
     This section describes the available key binding signals.

     _GtkFileChooser key binding example_ The default keys that
     activate the key-binding signals in 'GtkFileChooserDefaultClass'
     are as follows:

       Signal name     Default key combinations
       location-popup  'Control'-'L'   (empty path); '/'   (path of "/")  *PLEASE NOTE:*                    Both the individual '/' key and the numeric keypad's "divide" key are supported. ; '~'   (path of "~")
       up-folder       'Alt'-'Up'  *PLEASE NOTE:*                      Both the individual Up key and the numeric keypad's Up key are supported.  ; 'Backspace'
       down-folder     'Alt'-'Down'
       home-folder     'Alt'-'Home'
       desktop-folder  'Alt'-'D'
       quick-bookmark  'Alt'-'1'   through   'Alt'-'0'

     You can change these defaults to something else.  For example, to
     add a 'Shift' modifier to a few of the default bindings, you can
     include the following fragment in your '.gtkrc-2.0' file:

     binding "my-own-gtkfilechooser-bindings" {
             bind "<Alt><Shift>Up" {
                     "up-folder" ()
             }
             bind "<Alt><Shift>Down" {
                     "down-folder" ()
             }
             bind "<Alt><Shift>Home" {
                     "home-folder" ()
             }
     }

     class "GtkFileChooserDefault" binding
     "my-own-gtkfilechooser-bindings"

      _The "GtkFileChooserDefault::location-popup" signal_ void
     user_function (GtkFileChooserDefault *chooser,
                                   const char            *path,
                                     gpointer   user_data);

     This is used to make the file chooser show a "Location" dialog
     which the user can use to manually type the name of the file he
     wishes to select.  The 'path' argument is a string that gets put
     in the text entry for the file name.  By default this is bound to
     'Control'-'L' with a 'path' string of "" (the empty string).  It
     is also bound to '/' with a 'path' string of "'/'" (a slash): 
     this lets you type '/' and immediately type a path name.  On Unix
     systems, this is bound to '~' (tilde) with a 'path' string of "~"
     itself for access to home directories.

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_p_a_t_h' : default contents for the text entry for the file name

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


     binding "misc-shortcut" {
             bind "<Alt>M" {
                     "location-popup" ("/home/username/misc")
             }
     }

     class "GtkFileChooserDefault" binding "misc-shortcut"

      _The "GtkFileChooserDefault::up-folder" signal_ void
     user_function (GtkFileChooserDefault *chooser,
                                     gpointer   user_data);

     This is used to make the file chooser go to the parent of the
     current folder in the file hierarchy.  By default this is bound to
     'Backspace' and 'Alt'-'Up' (the Up key in the numeric keypad also
     works).

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


     This is used to make the file chooser go to a child of the current
     folder in the file hierarchy.  The subfolder that will be used is
     displayed in the path bar widget of the file chooser.  For
     example, if the path bar is showing "/foo/_bar/_baz", then this
     will cause the file chooser to switch to the "baz" subfolder.  By
     default this is bound to 'Alt'-'Down' (the Down key in the numeric
     keypad also works).

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


     This is used to make the file chooser show the user's home folder
     in the file list.  By default this is bound to 'Alt'-'Home' (the
     Home key in the numeric keypad also works).

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


     This is used to make the file chooser show the user's Desktop
     folder in the file list.  By default this is bound to 'Alt'-'D'.

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


     This is used to make the file chooser switch to the bookmark
     specified in the 'bookmark.index' parameter. For example, if you
     have three bookmarks, you can pass 0, 1, 2 to this signal to
     switch to each of them, respectively.  By default this is bound to
     'Alt'-'1', 'Alt'-'2',  etc. until 'Alt'-'0'.  Note that in the
     default binding, that 'Alt'-'1' is actually defined to switch to
     the bookmark at index 0, and so on successively; 'Alt'-'0' is
     defined to switch to the bookmark at index 10.

     '_c_h_o_o_s_e_r' : the object which received the signal.

     '_b_o_o_k_m_a_r_k._i_n_d_e_s' : index of the bookmark to switch to; the indices
          start at 0.

     '_u_s_e_r._d_a_t_a' : user data set when the signal handler was connected.


_S_t_r_u_c_t_u_r_e_s:


     '_G_t_k_F_i_l_e_C_h_o_o_s_e_r' _undocumented _


_E_n_u_m_s _a_n_d _F_l_a_g_s:


     '_G_t_k_F_i_l_e_C_h_o_o_s_e_r_A_c_t_i_o_n' Describes whether a 'GtkFileChooser' is
          being used to open existing files or to save to a possibly
          new file.

          '_o_p_e_n' Indicates open mode.  The file chooser will only let
               the user pick an existing file.

          '_s_a_v_e' Indicates save mode.  The file chooser will let the
               user pick an existing file, or type in a new filename.

          '_s_e_l_e_c_t-_f_o_l_d_e_r' Indicates an Open mode for selecting folders.
                The file chooser will let the user pick an existing
               folder.

          '_c_r_e_a_t_e-_f_o_l_d_e_r' Indicates a mode for creating a new folder. 
               The file chooser will let the user name an existing or
               new folder.


     '_G_t_k_F_i_l_e_C_h_o_o_s_e_r_C_o_n_f_i_r_m_a_t_i_o_n' Used as a return value of handlers
          for the confirm-overwrite signal of a 'GtkFileChooser'.  This
          value determines whether the file chooser will present the
          stock confirmation dialog, accept the user's choice of a
          filename, or let the user choose another filename.

          '_c_o_n_f_i_r_m' The file chooser will present its stock dialog to
               confirm about overwriting an existing file.

          '_a_c_c_e_p_t-_f_i_l_e_n_a_m_e' The file chooser will terminate and accept
               the user's choice of a file name.

          '_s_e_l_e_c_t-_a_g_a_i_n' The file chooser will continue running, so as
               to let the user select another file name.

               Since 2.8


     '_G_t_k_F_i_l_e_C_h_o_o_s_e_r_E_r_r_o_r' These identify the various errors that can
          occur while calling 'GtkFileChooser' functions.

          '_n_o_n_e_x_i_s_t_e_n_t' Indicates that a file does not exist.

          '_b_a_d-_f_i_l_e_n_a_m_e' Indicates a malformed filename.


_S_i_g_n_a_l_s:


     '_c_o_n_f_i_r_m-_o_v_e_r_w_r_i_t_e(_f_i_l_e_c_h_o_o_s_e_r, _u_s_e_r._d_a_t_a)' This signal gets
          emitted whenever it is appropriate to present a confirmation
          dialog when the user has selected a file name that already
          exists.  The signal only gets emitted when the file chooser
          is in 'GTK_FILE_CHOOSER_ACTION_SAVE' mode.

          Most applications just need to turn on the
          do-overwrite-confirmation property (or call the
          'gtkFileChooserSetDoOverwriteConfirmation' function), and
          they will automatically get a stock confirmation dialog.
          Applications which need to customize this behavior should do
          that, and also connect to the 'confirm-overwrite' signal.

          A signal handler for this signal must return a
          'GtkFileChooserConfirmation' value, which indicates the
          action to take.  If the handler determines that the user
          wants to select a different filename, it should return
          'GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN'.  If it
          determines that the user is satisfied with his choice of file
          name, it should return
          'GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME'. On the other
          hand, if it determines that the stock confirmation dialog
          should be used, it should return
          'GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM'.  The following
          example illustrates this.

          '_f_i_l_e_c_h_o_o_s_e_r' ['GtkFileChooser'] the object which received
               the signal.

          '_u_s_e_r._d_a_t_a' [R object] user data set when the signal handler
               was connected.

          _Returns:_ ['GtkFileChooserConfirmation']
          'GtkFileChooserConfirmation' value that indicates which
          action to take after emitting the signal.

          Since 2.8


     '_c_u_r_r_e_n_t-_f_o_l_d_e_r-_c_h_a_n_g_e_d(_c_h_o_o_s_e_r, _u_s_e_r._d_a_t_a)' This signal is
          emitted when the current folder in a 'GtkFileChooser'
          changes.  This can happen due to the user performing some
          action that changes folders, such as selecting a bookmark or
          visiting a folder on the file list.  It can also happen as a
          result of calling a function to explicitly change the current
          folder in a file chooser.

          Normally you do not need to connect to this signal, unless
          you need to keep track of which folder a file chooser is
          showing.

          See also:  'gtkFileChooserSetCurrentFolder',
          'gtkFileChooserGetCurrentFolder',
          'gtkFileChooserSetCurrentFolderUri',
          'gtkFileChooserGetCurrentFolderUri'.  

          '_c_h_o_o_s_e_r' ['GtkFileChooser']  the object which received the
               signal.

          '_u_s_e_r._d_a_t_a' [R object] user data set when the signal handler
               was connected.


     '_f_i_l_e-_a_c_t_i_v_a_t_e_d(_c_h_o_o_s_e_r, _u_s_e_r._d_a_t_a)' This signal is emitted when
          the user "activates" a file in the file chooser.  This can
          happen by double-clicking on a file in the file list, or by
          pressing 'Enter'.

          Normally you do not need to connect to this signal.  It is
          used internally by 'GtkFileChooserDialog' to know when to
          activate the default button in the dialog.

          See also: 'gtkFileChooserGetFilename',
          'gtkFileChooserGetFilenames', 'gtkFileChooserGetUri',
          'gtkFileChooserGetUris'.  

          '_c_h_o_o_s_e_r' ['GtkFileChooser']  the object which received the
               signal.

          '_u_s_e_r._d_a_t_a' [R object] user data set when the signal handler
               was connected.


     '_s_e_l_e_c_t_i_o_n-_c_h_a_n_g_e_d(_c_h_o_o_s_e_r, _u_s_e_r._d_a_t_a)' This signal is emitted
          when there is a change in the set of selected files in a
          'GtkFileChooser'.  This can happen when the user modifies the
          selection with the mouse or the keyboard, or when explicitly
          calling functions to change the selection.

          Normally you do not need to connect to this signal, as it is
          easier to wait for the file chooser to finish running, and
          then to get the list of selected files using the functions
          mentioned below.

          See also: 'gtkFileChooserSelectFilename',
          'gtkFileChooserUnselectFilename',
          'gtkFileChooserGetFilename', 'gtkFileChooserGetFilenames',
          'gtkFileChooserSelectUri', 'gtkFileChooserUnselectUri',
          'gtkFileChooserGetUri', 'gtkFileChooserGetUris'.  

          '_c_h_o_o_s_e_r' ['GtkFileChooser']  the object which received the
               signal.

          '_u_s_e_r._d_a_t_a' [R object] user data set when the signal handler
               was connected.


     '_u_p_d_a_t_e-_p_r_e_v_i_e_w(_c_h_o_o_s_e_r, _u_s_e_r._d_a_t_a)' This signal is emitted when
          the preview in a file chooser should be regenerated.  For
          example, this can happen when the currently selected file
          changes.  You should use this signal if you want your file
          chooser to have a preview widget.

          Once you have installed a preview widget with
          'gtkFileChooserSetPreviewWidget', you should update it when
          this signal is emitted.  You can use the functions
          'gtkFileChooserGetPreviewFilename' or
          'gtkFileChooserGetPreviewUri' to get the name of the file to
          preview. Your widget may not be able to preview all kinds of
          files; your callback must call
          'gtkFileChooserSetPreviewWidgetActive' to inform the file
          chooser about whether the preview was generated successfully
          or not.

          Please see the example code in .

          See also: 'gtkFileChooserSetPreviewWidget',
          'gtkFileChooserSetPreviewWidgetActive',
          'gtkFileChooserSetUsePreviewLabel',
          'gtkFileChooserGetPreviewFilename',
          'gtkFileChooserGetPreviewUri'.  

          '_c_h_o_o_s_e_r' ['GtkFileChooser']  the object which received the
               signal.

          '_u_s_e_r._d_a_t_a' [R object] user data set when the signal handler
               was connected.


_P_r_o_p_e_r_t_i_e_s:


     '_a_c_t_i_o_n' ['_G_t_k_F_i_l_e_C_h_o_o_s_e_r_A_c_t_i_o_n' : _R_e_a_d / _W_r_i_t_e] The type of
          operation that the file selector is performing.  Default
          value: GTK_FILE_CHOOSER_ACTION_OPEN


     '_d_o-_o_v_e_r_w_r_i_t_e-_c_o_n_f_i_r_m_a_t_i_o_n' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether a
          file chooser in 'GTK_FILE_CHOOSER_ACTION_SAVE' mode will
          present an overwrite confirmation dialog if the user selects
          a file name that already exists.  

          Default value: FALSE  Since  2.8


     '_e_x_t_r_a-_w_i_d_g_e_t' ['_G_t_k_W_i_d_g_e_t' : _R_e_a_d / _W_r_i_t_e] Application supplied
          widget for extra options.


     '_f_i_l_e-_s_y_s_t_e_m-_b_a_c_k_e_n_d' [_c_h_a_r_a_c_t_e_r : _W_r_i_t_e / _C_o_n_s_t_r_u_c_t _O_n_l_y] Name of
          file system backend to use.  Default value: NULL


     '_f_i_l_t_e_r' ['_G_t_k_F_i_l_e_F_i_l_t_e_r' : _R_e_a_d / _W_r_i_t_e] The current filter for
          selecting which files are displayed.


     '_l_o_c_a_l-_o_n_l_y' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether the selected file(s)
          should be limited to local file: URLs.  Default value: TRUE


     '_p_r_e_v_i_e_w-_w_i_d_g_e_t' ['_G_t_k_W_i_d_g_e_t' : _R_e_a_d / _W_r_i_t_e] Application supplied
          widget for custom previews.


     '_p_r_e_v_i_e_w-_w_i_d_g_e_t-_a_c_t_i_v_e' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether the
          application supplied widget for custom previews should be
          shown.  Default value: TRUE


     '_s_e_l_e_c_t-_m_u_l_t_i_p_l_e' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether to allow
          multiple files to be selected.  Default value: FALSE


     '_s_h_o_w-_h_i_d_d_e_n' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether the hidden files
          and folders should be displayed.  Default value: FALSE


     '_u_s_e-_p_r_e_v_i_e_w-_l_a_b_e_l' [_l_o_g_i_c_a_l : _R_e_a_d / _W_r_i_t_e] Whether to display a
          stock label with the name of the previewed file.  Default
          value: TRUE


_A_u_t_h_o_r(_s):

     Derived by RGtkGen from GTK+ documentation

_R_e_f_e_r_e_n_c_e_s:

     <URL:
     http://developer.gnome.org/doc/API/2.0/gtk/GtkFileChooser.html>

_S_e_e _A_l_s_o:

     'GtkFileChooserDialog' 'GtkFileChooserWidget'
     'GtkFileChooserButton'

