GtkPlacesSidebar

## GtkPlacesSidebar GtkPlacesSidebar — Sidebar that displays frequently-used places in the file system |

## Synopsis

    #include <gtk/gtk.h>

                        GtkPlacesSidebar;
    enum                GtkPlacesOpenFlags;
    GtkWidget *         gtk_places_sidebar_new              (void);
    void                gtk_places_sidebar_set_open_flags   (GtkPlacesSidebar *sidebar,
                                                             GtkPlacesOpenFlags flags);
    void                gtk_places_sidebar_set_location     (GtkPlacesSidebar *sidebar,
                                                             GFile *location);
    GFile *             gtk_places_sidebar_get_location     (GtkPlacesSidebar *sidebar);
    void                gtk_places_sidebar_set_show_desktop (GtkPlacesSidebar *sidebar,
                                                             gboolean show_desktop);
    void                gtk_places_sidebar_add_shortcut     (GtkPlacesSidebar *sidebar,
                                                             GFile *location);
    void                gtk_places_sidebar_remove_shortcut  (GtkPlacesSidebar *sidebar,
                                                             GFile *location);
    GSList *            gtk_places_sidebar_list_shortcuts   (GtkPlacesSidebar *sidebar);
    GFile *             gtk_places_sidebar_get_nth_bookmark (GtkPlacesSidebar *sidebar,
                                                             gint n);
    GtkPlacesOpenFlags  gtk_places_sidebar_get_open_flags   (GtkPlacesSidebar *sidebar);
    gboolean            gtk_places_sidebar_get_show_connect_to_server
                                                            (GtkPlacesSidebar *sidebar);
    gboolean            gtk_places_sidebar_get_show_desktop (GtkPlacesSidebar *sidebar);
    void                gtk_places_sidebar_set_show_connect_to_server
                                                            (GtkPlacesSidebar *sidebar,
                                                             gboolean show_connect_to_server);

## Description

GtkPlacesSidebar is a widget that displays a list of frequently-used places in the file system: the user's home directory, the user's bookmarks, and volumes and drives. This widget is used as a sidebar in GtkFileChooser and may be used by file managers and similar programs.

The places sidebar displays drives and volumes, and will automatically mount or unmount them when the user selects them.

Applications can hook to various signals in the places sidebar to customize its behavior. For example, they can add extra commands to the context menu of the sidebar.

While bookmarks are completely in control of the user, the places sidebar also allows individual applications to provide extra shortcut folders that are unique to each application. For example, a Paint program may want to add a shortcut for a Clipart folder. You can do this with `gtk_places_sidebar_add_shortcut()`.

To make use of the places sidebar, an application at least needs to connect to the "open-location" signal. This is emitted when the user selects in the sidebar a location to open. The application should also call `gtk_places_sidebar_set_location()` when it changes the currently-viewed location.

## Details

### GtkPlacesSidebar

    typedef struct _GtkPlacesSidebar GtkPlacesSidebar;

### enum GtkPlacesOpenFlags

    typedef enum {
      GTK_PLACES_OPEN_NORMAL     = 1 << 0,
      GTK_PLACES_OPEN_NEW_TAB    = 1 << 1,
      GTK_PLACES_OPEN_NEW_WINDOW = 1 << 2
    } GtkPlacesOpenFlags;

These flags serve two purposes. First, the application can call `gtk_places_sidebar_set_open_flags()` using these flags as a bitmask. This tells the sidebar that the application is able to open folders selected from the sidebar in various ways, for example, in new tabs or in new windows in addition to the normal mode.

Second, when one of these values gets passed back to the application in the "open-location" signal, it means that the application should open the selected location in the normal way, in a new tab, or in a new window. The sidebar takes care of determining the desired way to open the location, based on the modifier keys that the user is pressing at the time the selection is made.

If the application never calls `gtk_places_sidebar_set_open_flags()`, then the sidebar will only use GTK_PLACES_OPEN_NORMAL in the "open-location" signal. This is the default mode of operation.

`GTK_PLACES_OPEN_NORMAL` | This is the default mode that GtkPlacesSidebar uses if no other flags are specified. It indicates that the calling application should open the selected location in the normal way, for example, in the folder view beside the sidebar.
`GTK_PLACES_OPEN_NEW_TAB` | When passed to `gtk_places_sidebar_set_open_flags()`, this indicates that the application can open folders selected from the sidebar in new tabs. This value will be passed to the "open-location" signal when the user selects that a location be opened in a new tab instead of in the standard fashion.
`GTK_PLACES_OPEN_NEW_WINDOW` | Similar to `GTK_PLACES_OPEN_NEW_TAB`, but indicates that the application can open folders in new windows.

### gtk_places_sidebar_new ()

    GtkWidget *         gtk_places_sidebar_new              (void);

Creates a new GtkPlacesSidebar widget. The application should connect to at least the "open-location" signal to be notified when the user makes a selection in the sidebar.

### gtk_places_sidebar_set_open_flags ()

    void                gtk_places_sidebar_set_open_flags   (GtkPlacesSidebar *sidebar,
                                                             GtkPlacesOpenFlags flags);

Sets the way in which the calling application can open new locations from the places sidebar. For example, some applications only open locations "directly" into their main view, while others may support opening locations in a new notebook tab or a new window.

This function is used to tell the places `sidebar` about the ways in which the application can open new locations, so that the sidebar can display (or not) the "Open in new tab" and "Open in new window" menu items as appropriate.

When the "open-location" signal is emitted, its flags argument will be set to one of the `flags` that was passed in `gtk_places_sidebar_set_open_flags()`.

Passing 0 for `flags` will cause GTK_PLACES_OPEN_NORMAL to always be sent to callbacks for the "open-location" signal.

`sidebar` : | a places sidebar
`flags` : | Bitmask of modes in which the calling application can open locations

Since 3.10

### gtk_places_sidebar_set_location ()

    void                gtk_places_sidebar_set_location     (GtkPlacesSidebar *sidebar,
                                                             GFile *location);

Sets the location that is being shown in the widgets surrounding the `sidebar`, for example, in a folder view in a file manager. In turn, the `sidebar` will highlight that location if it is being shown in the list of places, or it will unhighlight everything if the `location` is not among the places in the list.

`sidebar` : | a places sidebar
`location` : | location to select, or NULL for no current path. [allow-none]

Since 3.10

### gtk_places_sidebar_get_location ()

    GFile *             gtk_places_sidebar_get_location     (GtkPlacesSidebar *sidebar);

Gets the currently-selected location in the `sidebar`. This can be NULL when nothing is selected, for example, when `gtk_places_sidebar_set_location()` has been called with a location that is not among the sidebar's list of places to show.

You can use this function to get the selection in the `sidebar`. Also, if you connect to the "popup-menu" signal, you can use this function to get the location that is being referred to during the callbacks for your menu items.

`sidebar` : | a places sidebar
Returns : | a GFile with the selected location, or NULL if nothing is visually selected. [transfer full]

Since 3.10

### gtk_places_sidebar_set_show_desktop ()

    void                gtk_places_sidebar_set_show_desktop (GtkPlacesSidebar *sidebar,
                                                             gboolean show_desktop);

Sets whether the `sidebar` should show an item for the Desktop folder; this is off by default. An application may want to turn this on if the desktop environment actually supports the notion of a desktop.

`sidebar` : | a places sidebar
`show_desktop` : | whether to show an item for the Desktop folder

Since 3.10

### gtk_places_sidebar_add_shortcut ()

    void                gtk_places_sidebar_add_shortcut     (GtkPlacesSidebar *sidebar,
                                                             GFile *location);

Applications may want to present some folders in the places sidebar if they could be immediately useful to users. For example, a drawing program could add a "/usr/share/clipart" location when the sidebar is being used in an "Insert Clipart" dialog box.

This function adds the specified `location` to a special place for immutable shortcuts. The shortcuts are application-specific; they are not shared across applications, and they are not persistent. If this function is called multiple times with different locations, then they are added to the sidebar's list in the same order as the function is called.

`sidebar` : | a places sidebar
`location` : | location to add as an application-specific shortcut

Since 3.10

### gtk_places_sidebar_remove_shortcut ()

    void                gtk_places_sidebar_remove_shortcut  (GtkPlacesSidebar *sidebar,
                                                             GFile *location);

Removes an application-specific shortcut that has been previously been inserted with `gtk_places_sidebar_add_shortcut()`. If the `location` is not a shortcut in the sidebar, then nothing is done.

`sidebar` : | a places sidebar
`location` : | location to remove

Since 3.10

### gtk_places_sidebar_list_shortcuts ()

    GSList *            gtk_places_sidebar_list_shortcuts   (GtkPlacesSidebar *sidebar);

`sidebar` : | a places sidebar
Returns : | A GSList of GFile of the locations that have been added as application-specific shortcuts with `gtk_places_sidebar_add_shortcut()`. To free this list, you can use
    1
    g_slist_free_full (list, (GDestroyNotify) g_object_unref);
. [element-type GFile][transfer full]

Since 3.10

### gtk_places_sidebar_get_nth_bookmark ()

    GFile *             gtk_places_sidebar_get_nth_bookmark (GtkPlacesSidebar *sidebar,
                                                             gint n);

This function queries the bookmarks added by the user to the places sidebar, and returns one of them. This function is used by GtkFileChooser to implement the "Alt-1", "Alt-2", etc. shortcuts, which activate the cooresponding bookmark.

`sidebar` : | a places sidebar
`n` : | index of the bookmark to query
Returns : | The bookmark specified by the index `n`, or NULL if no such index exist. Note that the indices start at 0, even though the file chooser starts them with the keyboard shortcut "Alt-1". [transfer full]

Since 3.10

### gtk_places_sidebar_get_open_flags ()

    GtkPlacesOpenFlags  gtk_places_sidebar_get_open_flags   (GtkPlacesSidebar *sidebar);

### gtk_places_sidebar_get_show_connect_to_server ()

    gboolean            gtk_places_sidebar_get_show_connect_to_server
                                                            (GtkPlacesSidebar *sidebar);

Returns the value previously set with `gtk_places_sidebar_set_show_connect_to_server()`

`sidebar` : | a places sidebar
Returns : | `TRUE` if the sidebar will display a "Connect to Server" item.

Since 3.10

### gtk_places_sidebar_get_show_desktop ()

    gboolean            gtk_places_sidebar_get_show_desktop (GtkPlacesSidebar *sidebar);

Returns the value previously set with `gtk_places_sidebar_set_show_desktop()`

`sidebar` : | a places sidebar
Returns : | `TRUE` if the sidebar will display a builtin shortcut to the desktop folder.

Since 3.10

### gtk_places_sidebar_set_show_connect_to_server ()

    void                gtk_places_sidebar_set_show_connect_to_server
                                                            (GtkPlacesSidebar *sidebar,
                                                             gboolean show_connect_to_server);

Sets whether the `sidebar` should show an item for connecting to a network server; this is off by default. An application may want to turn this on if it implements a way for the user to connect to network servers directly.

`sidebar` : | a places sidebar
`show_connect_to_server` : | whether to show an item for the Connect to Server command

Since 3.10

## See Also

GtkFileChooser