Top | ![]() |
![]() |
![]() |
![]() |
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.
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
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
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
GtkPlacesOpenFlags
gtk_places_sidebar_get_open_flags (GtkPlacesSidebar *sidebar
);
Gets the open flags.
Since: 3.10
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
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.
a GFile with the selected location, or
NULL
if nothing is visually selected.
[nullable][transfer full]
Since: 3.10
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
gboolean
gtk_places_sidebar_get_show_recent (GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_show_recent()
Since: 3.18
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
gboolean
gtk_places_sidebar_get_show_desktop (GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_show_desktop()
Since: 3.10
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
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
GSList *
gtk_places_sidebar_list_shortcuts (GtkPlacesSidebar *sidebar
);
Gets the list of shortcuts.
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
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.
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
gboolean
gtk_places_sidebar_get_local_only (GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_local_only()
.
Since: 3.12
void gtk_places_sidebar_set_local_only (GtkPlacesSidebar *sidebar
,gboolean local_only
);
Sets whether the sidebar
should only show local files.
Since: 3.12
gboolean
gtk_places_sidebar_get_show_enter_location
(GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_show_enter_location()
Since: 3.14
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
gboolean
gtk_places_sidebar_get_show_trash (GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_show_trash()
Since: 3.18
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
gboolean
gtk_places_sidebar_get_show_other_locations
(GtkPlacesSidebar *sidebar
);
Returns the value previously set with gtk_places_sidebar_set_show_other_locations()
Since: 3.18
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-with-flags” signal.
sidebar |
a places sidebar |
|
show_other_locations |
whether to show an item for the Other Locations view |
Since: 3.18
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.
sidebar |
a places sidebar. |
|
visible |
whether to show the valid targets or not. |
|
context |
drag context used to ask the source about the action that wants to perform, so hints are more accurate. |
Since: 3.18
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.
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. |
||
When passed to |
||
Similar to |