Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkfilechooserbutton.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkFileChooserButton
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A button to launch a file selection dialog
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkFileChooserButton is a widget that lets the user select a
  10 file.  It implements the #GtkFileChooser interface.  Visually, it is a
  11 file name with a button to bring up a #GtkFileChooserDialog.
  12 The user can then use that dialog to change the file associated with
  13 that button.  This widget does not support setting the "select-multiple"
  14 property to %TRUE.
  15 </para>
  16
  17 <example>
  18 <title>Create a button to let the user select a file in /etc</title>
  19 <programlisting>
  20 {
  21   GtkWidget *button;
  22
  23   button = gtk_file_chooser_button_new (_("Select a file"));
  24   gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button),
  25                                        "/etc");
  26 }
  27 </programlisting>
  28 </example>
  29
  30 <para>
  31 The #GtkFileChooserButton supports all four #GtkFileChooserAction<!--
  32 -->s that the #GtkFileChooser supports.  Two of the actions,
  33 %GTK_FILE_CHOOSER_ACTION_SAVE and
  34 %GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER, give the button the appearance
  35 of an entry next to a button.  The user can type the name of a file in
  36 this entry, and it will complete as it types.  The other two actions,
  37 %GTK_FILE_CHOOSER_ACTION_OPEN and
  38 %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER, make the #GtkFileChooserAction
  39 look like a #GtkButton.
  40 </para>
  41
  42 <example>
  43 <title>Using GtkFileChooserButton in save mode</title>
  44 <programlisting>
  45 {
  46   GtkWidget *button;
  47
  48   button = gtk_file_chooser_button_new (_("Save as..."));
  49   gtk_file_chooser_set_action (GTK_FILE_CHOOSER (button),
  50                                GTK_FILE_CHOOSER_ACTION_SAVE);
  51   gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER_BUTTON (button),
  52                                        DEFAULT_SAVE_DIRECTORY);
  53 }
  54 </programlisting>
  55 </example>
  56
  57 <important>
  58 <para>
  59 The #GtkFileChooserButton will ellipsize the label while in Open mode,
  60 and thus will thus request little horizontal space.  To give the button
  61 more space, you should call gtk_widget_size_request(),
  62 gtk_file_chooser_button_set_width_chars (), or pack the button in
  63 such a way that other interface elements give space to the widget.
  64 </para>
  65 </important>
  66
  67 <!-- ##### SECTION See_Also ##### -->
  68 <para>
  69 #GtkFileChooserDialog
  70 </para>
  71
  72 <!-- ##### STRUCT GtkFileChooserButton ##### -->
  73 <para>
  74 This should not be accessed directly.  Use the accessor functions below.
  75 </para>
  76
  77
  78 <!-- ##### ARG GtkFileChooserButton:active ##### -->
  79 <para>
  80 %TRUE, if the #GtkFileChooserDialog associated with the button has been
  81 made visible.  This can also be set by the application, though it is
  82 rarely useful to do so.
  83 </para>
  84
  85 <!-- ##### ARG GtkFileChooserButton:dialog ##### -->
  86 <para>
  87 Instance of the #GtkFileChooserDialog associated with the button.
  88 </para>
  89
  90 <!-- ##### ARG GtkFileChooserButton:title ##### -->
  91 <para>
  92 Title to put on the #GtkFileChooserDialog associated with the button.
  93 </para>
  94
  95 <!-- ##### ARG GtkFileChooserButton:width-chars ##### -->
  96 <para>
  97 The width of the entry and label inside the button, in characters.
  98 </para>
  99
 100 <!-- ##### FUNCTION gtk_file_chooser_button_new ##### -->
 101 <para>
 102
 103 </para>
 104
 105 @title:
 106 @Returns:
 107
 108
 109 <!-- ##### FUNCTION gtk_file_chooser_button_new_with_backend ##### -->
 110 <para>
 111
 112 </para>
 113
 114 @title:
 115 @backend:
 116 @Returns:
 117
 118
 119 <!-- ##### FUNCTION gtk_file_chooser_button_new_with_dialog ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @dialog:
 125 @Returns:
 126
 127
 128 <!-- ##### FUNCTION gtk_file_chooser_button_get_title ##### -->
 129 <para>
 130
 131 </para>
 132
 133 @button:
 134 @Returns:
 135
 136
 137 <!-- ##### FUNCTION gtk_file_chooser_button_set_title ##### -->
 138 <para>
 139
 140 </para>
 141
 142 @button:
 143 @title:
 144
 145
 146 <!-- ##### FUNCTION gtk_file_chooser_button_get_active ##### -->
 147 <para>
 148
 149 </para>
 150
 151 @button:
 152 @Returns:
 153
 154
 155 <!-- ##### FUNCTION gtk_file_chooser_button_set_active ##### -->
 156 <para>
 157
 158 </para>
 159
 160 @button:
 161 @is_active:
 162
 163
 164 <!-- ##### FUNCTION gtk_file_chooser_button_get_width_chars ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @button:
 170 @Returns:
 171
 172
 173 <!-- ##### FUNCTION gtk_file_chooser_button_set_width_chars ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @button:
 179 @n_chars:
 180
 181