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.
CSS nodes
GtkPlacesSidebar uses a single CSS node with name placessidebar and style
class .sidebar.
Among the children of the places sidebar, the following style classes can
be used:
.sidebar-new-bookmark-row for the 'Add new bookmark' row
.sidebar-placeholder-row for a row that is a placeholder
.has-open-popup when a popup is open for a row
Functions
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.
Since: 3.10
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.
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.
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 “populate-popup” signal, you can use this
function to get the location that is being referred to during the callbacks
for your menu items.
Returns
a GFile with the selected location, or
NULL if nothing is visually selected.
[nullable][transfer full]
Since: 3.10
gtk_places_sidebar_set_show_recent ()
void
gtk_places_sidebar_set_show_recent (GtkPlacesSidebar *sidebar,
gboolean show_recent);
Sets whether the sidebar
should show an item for recent files.
The default value for this option is determined by the desktop
environment, but this function can be used to override it on a
per-application basis.
Since: 3.18
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.
The default value for this option is determined by the desktop
environment and the user’s configuration, but this function can be
used to override it on a per-application basis.
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.
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.
Since: 3.10
gtk_places_sidebar_list_shortcuts ()
GSList *
gtk_places_sidebar_list_shortcuts (GtkPlacesSidebar *sidebar);
Gets the list of shortcuts.
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.
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".
[nullable][transfer full]
Since: 3.10
gtk_places_sidebar_get_show_connect_to_server ()
gboolean
gtk_places_sidebar_get_show_connect_to_server
(GtkPlacesSidebar *sidebar);
gtk_places_sidebar_get_show_connect_to_server has been deprecated since version 3.18 and should not be used in newly-written code.
It is recommended to group this functionality with the drives
and network location under the new 'Other Location' item
Returns the value previously set with gtk_places_sidebar_set_show_connect_to_server()
Returns
TRUE if the sidebar will display a “Connect to Server” item.
gtk_places_sidebar_set_show_connect_to_server ()
void
gtk_places_sidebar_set_show_connect_to_server
(GtkPlacesSidebar *sidebar,
gboolean show_connect_to_server);
gtk_places_sidebar_set_show_connect_to_server has been deprecated since version 3.18 and should not be used in newly-written code.
It is recommended to group this functionality with the drives
and network location under the new 'Other Location' item
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.
If you enable this, you should connect to the
“show-connect-to-server” signal.
Since: 3.10
gtk_places_sidebar_set_local_only ()
void
gtk_places_sidebar_set_local_only (GtkPlacesSidebar *sidebar,
gboolean local_only);
Sets whether the sidebar
should only show local files.
Since: 3.12
gtk_places_sidebar_set_show_enter_location ()
void
gtk_places_sidebar_set_show_enter_location
(GtkPlacesSidebar *sidebar,
gboolean show_enter_location);
Sets whether the sidebar
should show an item for entering a location;
this is off by default. An application may want to turn this on if manually
entering URLs is an expected user action.
If you enable this, you should connect to the
“show-enter-location” signal.
Since: 3.14
gtk_places_sidebar_set_show_trash ()
void
gtk_places_sidebar_set_show_trash (GtkPlacesSidebar *sidebar,
gboolean show_trash);
Sets whether the sidebar
should show an item for the Trash location.
Since: 3.18
gtk_places_sidebar_set_show_other_locations ()
void
gtk_places_sidebar_set_show_other_locations
(GtkPlacesSidebar *sidebar,
gboolean show_other_locations);
Sets whether the sidebar
should show an item for the application to show
an Other Locations view; this is off by default. When set to TRUE, persistent
devices such as hard drives are hidden, otherwise they are shown in the sidebar.
An application may want to turn this on if it implements a way for the user to
see and interact with drives and network servers directly.
If you enable this, you should connect to the
“show-other-locations” signal.
Since: 3.18
gtk_places_sidebar_set_drop_targets_visible ()
void
gtk_places_sidebar_set_drop_targets_visible
(GtkPlacesSidebar *sidebar,
gboolean visible,
GdkDragContext *context);
Make the GtkPlacesSidebar show drop targets, so it can show the available
drop targets and a "new bookmark" row. This improves the Drag-and-Drop
experience of the user and allows applications to show all available
drop targets at once.
This needs to be called when the application is aware of an ongoing drag
that might target the sidebar. The drop-targets-visible state will be unset
automatically if the drag finishes in the GtkPlacesSidebar. You only need
to unset the state when the drag ends on some other widget on your application.
Since: 3.18
Property Details
The “local-only” property
“local-only” gboolean
Whether the sidebar only includes local files.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
The “location” property
“location” GFile *
The location to highlight in the sidebar.
Owner: GtkPlacesSidebar
Flags: Read / Write
The “open-flags” property
“open-flags” GtkPlacesOpenFlags
Modes in which the calling application can open locations selected in the sidebar.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: GTK_PLACES_OPEN_NORMAL
The “populate-all” property
“populate-all” gboolean
If :populate-all is TRUE, the “populate-popup” signal
is also emitted for popovers.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
Since: 3.18
The “show-connect-to-server” property
“show-connect-to-server” gboolean
Whether the sidebar includes a builtin shortcut to a 'Connect to server' dialog.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
The “show-desktop” property
“show-desktop” gboolean
Whether the sidebar includes a builtin shortcut to the Desktop folder.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: TRUE
The “show-enter-location” property
“show-enter-location” gboolean
Whether the sidebar includes a builtin shortcut to manually enter a location.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
The “show-other-locations” property
“show-other-locations” gboolean
Whether the sidebar includes an item to show external locations.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
The “show-recent” property
“show-recent” gboolean
Whether the sidebar includes a builtin shortcut for recent files.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: TRUE
The “show-starred-location” property
“show-starred-location” gboolean
Whether the sidebar includes an item to show starred files.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: FALSE
The “show-trash” property
“show-trash” gboolean
Whether the sidebar includes a builtin shortcut to the Trash location.
Owner: GtkPlacesSidebar
Flags: Read / Write
Default value: TRUE
Signal Details
The “drag-action-ask” signal
gint
user_function (GtkPlacesSidebar *sidebar,
gint actions,
gpointer user_data)
The places sidebar emits this signal when it needs to ask the application
to pop up a menu to ask the user for which drag action to perform.
Returns
the final drag action that the sidebar should pass to the drag side
of the drag-and-drop operation.
Flags: Run Last
Since: 3.10
The “drag-action-requested” signal
gint
user_function (GtkPlacesSidebar *sidebar,
GdkDragContext *context,
GObject *dest_file,
gpointer source_file_list,
gpointer user_data)
When the user starts a drag-and-drop operation and the sidebar needs
to ask the application for which drag action to perform, then the
sidebar will emit this signal.
The application can evaluate the context
for customary actions, or
it can check the type of the files indicated by source_file_list
against the
possible actions for the destination dest_file
.
The drag action to use must be the return value of the signal handler.
Returns
The drag action to use, for example, GDK_ACTION_COPY
or GDK_ACTION_MOVE, or 0 if no action is allowed here (i.e. drops
are not allowed in the specified dest_file
).
Flags: Run Last
Since: 3.10
The “drag-perform-drop” signal
void
user_function (GtkPlacesSidebar *sidebar,
GObject *dest_file,
gpointer source_file_list,
gint action,
gpointer user_data)
The places sidebar emits this signal when the user completes a
drag-and-drop operation and one of the sidebar's items is the
destination. This item is in the dest_file
, and the
source_file_list
has the list of files that are dropped into it and
which should be copied/moved/etc. based on the specified action
.
Flags: Run First
Since: 3.10
The “mount” signal
void
user_function (GtkPlacesSidebar *sidebar,
GMountOperation *mount_operation,
gpointer user_data)
The places sidebar emits this signal when it starts a new operation
because the user clicked on some location that needs mounting.
In this way the application using the GtkPlacesSidebar can track the
progress of the operation and, for example, show a notification.
Flags: Run First
Since: 3.20
The “open-location” signal
void
user_function (GtkPlacesSidebar *sidebar,
GObject *location,
GtkPlacesOpenFlags open_flags,
gpointer user_data)
The places sidebar emits this signal when the user selects a location
in it. The calling application should display the contents of that
location; for example, a file manager should show a list of files in
the specified location.
Flags: Run First
Since: 3.10
The “populate-popup” signal
void
user_function (GtkPlacesSidebar *sidebar,
GtkWidget *container,
GFile *selected_item,
GVolume *selected_volume,
gpointer user_data)
The places sidebar emits this signal when the user invokes a contextual
popup on one of its items. In the signal handler, the application may
add extra items to the menu as appropriate. For example, a file manager
may want to add a "Properties" command to the menu.
It is not necessary to store the selected_item
for each menu item;
during their callbacks, the application can use gtk_places_sidebar_get_location()
to get the file to which the item refers.
The selected_item
argument may be NULL in case the selection refers to
a volume. In this case, selected_volume
will be non-NULL. In this case,
the calling application will have to g_object_ref() the selected_volume
and
keep it around to use it in the callback.
The container
and all its contents are destroyed after the user
dismisses the popup. The popup is re-created (and thus, this signal is
emitted) every time the user activates the contextual menu.
Before 3.18, the container
always was a GtkMenu, and you were expected
to add your items as GtkMenuItems. Since 3.18, the popup may be implemented
as a GtkPopover, in which case container
will be something else, e.g. a
GtkBox, to which you may add GtkModelButtons or other widgets, such as
GtkEntries, GtkSpinButtons, etc. If your application can deal with this
situation, you can set “populate-all” to TRUE to request
that this signal is emitted for populating popovers as well.
Flags: Run First
Since: 3.10
The “show-connect-to-server” signal
void
user_function (GtkPlacesSidebar *sidebar,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present an way to connect directly to a network server.
For example, the application may bring up a dialog box asking for
a URL like "sftp://ftp.example.com". It is up to the application to create
the corresponding mount by using, for example, g_file_mount_enclosing_volume().
GtkPlacesSidebar::show-connect-to-server has been deprecated since version 3.18 and should not be used in newly-written code.
use the “show-other-locations” signal
to connect to network servers.
Flags: Run First
The “show-enter-location” signal
void
user_function (GtkPlacesSidebar *sidebar,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present an way to directly enter a location.
For example, the application may bring up a dialog box asking for
a URL like "http://http.example.com".
Flags: Run First
Since: 3.14
The “show-error-message” signal
void
user_function (GtkPlacesSidebar *sidebar,
gchar *primary,
gchar *secondary,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present an error message. Most of these messages
refer to mounting or unmounting media, for example, when a drive
cannot be started for some reason.
Flags: Run First
Since: 3.10
The “show-other-locations” signal
void
user_function (GtkPlacesSidebar *sidebar,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present a way to show other locations e.g. drives
and network access points.
For example, the application may bring up a page showing persistent
volumes and discovered network addresses.
GtkPlacesSidebar::show-other-locations has been deprecated since version 3.20 and should not be used in newly-written code.
use the “show-other-locations-with-flags”
which includes the open flags in order to allow the user to specify to open
in a new tab or window, in a similar way than “open-location”
Flags: Run First
Since: 3.18
The “show-other-locations-with-flags” signal
void
user_function (GtkPlacesSidebar *sidebar,
GtkPlacesOpenFlags open_flags,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present a way to show other locations e.g. drives
and network access points.
For example, the application may bring up a page showing persistent
volumes and discovered network addresses.
Flags: Run First
Since: 3.20
The “show-starred-location” signal
void
user_function (GtkPlacesSidebar *sidebar,
GtkPlacesOpenFlags open_flags,
gpointer user_data)
The places sidebar emits this signal when it needs the calling
application to present a way to show the starred files. In GNOME,
starred files are implemented by setting the nao:predefined-tag-favorite
tag in the tracker database.
Flags: Run First
Since: 3.22.26
The “unmount” signal
void
user_function (GtkPlacesSidebar *sidebar,
GMountOperation *mount_operation,
gpointer user_data)
The places sidebar emits this signal when it starts a new operation
because the user for example ejected some drive or unmounted a mount.
In this way the application using the GtkPlacesSidebar can track the
progress of the operation and, for example, show a notification.
Flags: Run First
Since: 3.20