GtkFileChooserButton: GTK+ 2 Reference Manual

## GtkFileChooserButton GtkFileChooserButton — A button to launch a file selection dialog |

## Functions

GtkWidget * | gtk_file_chooser_button_new ()
GtkWidget * | gtk_file_chooser_button_new_with_backend ()
GtkWidget * | gtk_file_chooser_button_new_with_dialog ()
const gchar * | gtk_file_chooser_button_get_title ()
void | gtk_file_chooser_button_set_title ()
gint | gtk_file_chooser_button_get_width_chars ()
void | gtk_file_chooser_button_set_width_chars ()
gboolean | gtk_file_chooser_button_get_focus_on_click ()
void | gtk_file_chooser_button_set_focus_on_click ()

## Properties

GtkFileChooser * | dialog | Write / Construct Only
gboolean | focus-on-click | Read / Write
gchar * | title | Read / Write
gint | width-chars | Read / Write

## Signals

void | file-set | Run First

## Types and Values

struct | GtkFileChooserButton

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkBox
                            ╰── GtkHBox
                                ╰── GtkFileChooserButton

## Implemented Interfaces

GtkFileChooserButton implements AtkImplementorIface, GtkBuildable, GtkOrientable and GtkFileChooser.

## Includes

    #include <gtk/gtk.h>

## Description

The GtkFileChooserButton is a widget that lets the user select a file. It implements the GtkFileChooser interface. Visually, it is a file name with a button to bring up a GtkFileChooserDialog. The user can then use that dialog to change the file associated with that button. This widget does not support setting the "select-multiple" property to `TRUE`.

Example 33. Create a button to let the user select a file in /etc

    1
    2
    3
    4
    5
    6
    7
    {
      GtkWidget *button;
      button = gtk_file_chooser_button_new (_("Select a file"),
                                            GTK_FILE_CHOOSER_ACTION_OPEN);
      gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button),
                                           "/etc");
    }

The GtkFileChooserButton supports the GtkFileChooserActions `GTK_FILE_CHOOSER_ACTION_OPEN` and `GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER`.

The GtkFileChooserButton will ellipsize the label, and thus will thus request little horizontal space. To give the button more space, you should call `gtk_widget_size_request()`, `gtk_file_chooser_button_set_width_chars()`, or pack the button in such a way that other interface elements give space to the widget.

## Functions

### gtk_file_chooser_button_new ()

    GtkWidget *
    gtk_file_chooser_button_new (const gchar *title,
                                 GtkFileChooserAction action);

Creates a new file-selecting button widget.

#### Parameters

title | the title of the browse dialog. |
action | the open mode for the widget. |

#### Returns

a new button widget.

Since: 2.6

### gtk_file_chooser_button_new_with_backend ()

    GtkWidget *
    gtk_file_chooser_button_new_with_backend
                                   (const gchar *title,
                                    GtkFileChooserAction action,
                                    const gchar *backend);

`gtk_file_chooser_button_new_with_backend` has been deprecated since version 2.14 and should not be used in newly-written code.

Use `gtk_file_chooser_button_new()` instead.

Creates a new file-selecting button widget using `backend` .

#### Parameters

title | the title of the browse dialog. |
action | the open mode for the widget. |
backend | the name of the GtkFileSystem backend to use. |

#### Returns

a new button widget.

Since: 2.6

### gtk_file_chooser_button_new_with_dialog ()

    GtkWidget *
    gtk_file_chooser_button_new_with_dialog
                                   (GtkWidget *dialog);

`gtk_file_chooser_button_new_with_dialog` is deprecated and should not be used in newly-written code.

Creates a GtkFileChooserButton widget which uses `dialog` as its file-picking window.

Note that `dialog` must be a GtkDialog (or subclass) which implements the GtkFileChooser interface and must not have `GTK_DIALOG_DESTROY_WITH_PARENT` set.

Also note that the dialog needs to have its confirmative button added with response `GTK_RESPONSE_ACCEPT` or `GTK_RESPONSE_OK` in order for the button to take over the file selected in the dialog.

#### Parameters

dialog | the widget to use as dialog |

#### Returns

a new button widget.

Since: 2.6

### gtk_file_chooser_button_get_title ()

    const gchar *
    gtk_file_chooser_button_get_title (GtkFileChooserButton *button);

Retrieves the title of the browse dialog used by `button` . The returned value should not be modified or freed.

#### Parameters

button | the button widget to examine. |

#### Returns

a pointer to the browse dialog's title.

Since: 2.6

### gtk_file_chooser_button_set_title ()

    void
    gtk_file_chooser_button_set_title (GtkFileChooserButton *button,
                                       const gchar *title);

Modifies the `title` of the browse dialog used by `button` .

#### Parameters

button | the button widget to modify. |
title | the new browse dialog title. |

Since: 2.6

### gtk_file_chooser_button_get_width_chars ()

    gint
    gtk_file_chooser_button_get_width_chars
                                   (GtkFileChooserButton *button);

Retrieves the width in characters of the `button` widget's entry and/or label.

#### Parameters

button | the button widget to examine. |

#### Returns

an integer width (in characters) that the button will use to size itself.

Since: 2.6

### gtk_file_chooser_button_set_width_chars ()

    void
    gtk_file_chooser_button_set_width_chars
                                   (GtkFileChooserButton *button,
                                    gint n_chars);

Sets the width (in characters) that `button` will use to `n_chars` .

#### Parameters

button | the button widget to examine. |
n_chars | the new width, in characters. |

Since: 2.6

### gtk_file_chooser_button_get_focus_on_click ()

    gboolean
    gtk_file_chooser_button_get_focus_on_click
                                   (GtkFileChooserButton *button);

Returns whether the button grabs focus when it is clicked with the mouse. See `gtk_file_chooser_button_set_focus_on_click()`.

#### Parameters

button | a GtkFileChooserButton |

#### Returns

`TRUE` if the button grabs focus when it is clicked with the mouse.

Since: 2.10

### gtk_file_chooser_button_set_focus_on_click ()

    void
    gtk_file_chooser_button_set_focus_on_click
                                   (GtkFileChooserButton *button,
                                    gboolean focus_on_click);

Sets whether the button will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don't want the keyboard focus removed from the main area of the application.

#### Parameters

button | a GtkFileChooserButton |
focus_on_click | whether the button grabs focus when clicked with the mouse |

Since: 2.10

## Types and Values

### struct GtkFileChooserButton

    struct GtkFileChooserButton;

This should not be accessed directly. Use the accessor functions below.

## Property Details

### The `“dialog”` property

      “dialog”                   GtkFileChooser *

Instance of the GtkFileChooserDialog associated with the button.

Flags: Write / Construct Only

Since: 2.6

### The `“focus-on-click”` property

      “focus-on-click”           gboolean

Whether the GtkFileChooserButton button grabs focus when it is clicked with the mouse.

Flags: Read / Write

Default value: TRUE

Since: 2.10

### The `“title”` property

      “title”                    gchar *

Title to put on the GtkFileChooserDialog associated with the button.

Flags: Read / Write

Default value: "Select a File"

Since: 2.6

### The `“width-chars”` property

      “width-chars”              gint

The width of the entry and label inside the button, in characters.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 2.6

## Signal Details

### The `“file-set”` signal

    void
    user_function (GtkFileChooserButton *widget,
                   gpointer              user_data)

The ::file-set signal is emitted when the user selects a file.

Note that this signal is only emitted when the user changes the file.

#### Parameters

widget | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 2.12

## See Also

GtkFileChooserDialog