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.


     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'-'/'-'~'   (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'-'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'
       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.

     *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.

     _The "GtkFileChooserDefault::desktop-folder" signal_

     void user_function (GtkFileChooserDefault *chooser,
                                     gpointer   user_data);

     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.

     _The "GtkFileChooserDefault::quick-bookmark" signal_

     void user_function (GtkFileChooserDefault *chooser,
                                   gint bookmark_index,
                                     gpointer   user_data);

     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:

     '_T_h_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


     '_T_h_e (_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.


     '_T_h_e (_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.


     '_T_h_e (_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.


     '_T_h_e (_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.


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

