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:

     'gtkFileChooserErrorQuark()'
      '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 'GtkFileChooserWidget', 
     'GtkFileChooserButton' 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 'g\Filename\To\Utf8()' 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 'GtkFileChooser'::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.


     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.


     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'-'/'  ; '/'
       up-folder       'Alt'-'Up'-'Backspace'  *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'

     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.

     '_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.

     *PLEASE NOTE:*        You can create your own bindings for the
     'location-popup' signal with custom 'path' strings, and have a
     crude form of easily-to-type bookmarks.  For example, say you
     access the path '/home/username/misc' very frequently.  You could
     then create an 'Alt'-'M' shortcut by including the following in
     your '.gtkrc-2.0':

     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.

     _The "GtkFileChooserDefault::down-folder" signal_

     void user_function (GtkFileChooserDefault *chooser,
                                     gpointer   user_data);

     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.

     _The "GtkFileChooserDefault::home-folder" signal_

     void user_function (GtkFileChooserDefault *chooser,
                                     gpointer   user_data);

     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.

_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 _ .in -5 

_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.


     '_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
          'gtk\File\Chooser\Set\Preview\Wiget\Active()' 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 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'

