Struct gtk::PlacesSidebar

#[repr(transparent)]
pub struct PlacesSidebar { /* private fields */ }

PlacesSidebar 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 FileChooser 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 add_shortcut().

To make use of the places sidebar, an application at least needs to connect to the signal::PlacesSidebar::open-location signal. This is emitted when the user selects in the sidebar a location to open. The application should also call 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

Implements

ScrolledWindowExt, BinExt, ContainerExt, WidgetExt, glib::ObjectExt, BuildableExt, ContainerExtManual, WidgetExtManual, BuildableExtManual

Implementations

impl PlacesSidebar

pub fn new() -> PlacesSidebar

Creates a new PlacesSidebar widget.

The application should connect to at least the signal::PlacesSidebar::open-location signal to be notified when the user makes a selection in the sidebar.

Returns

a newly created PlacesSidebar

pub fn builder() -> PlacesSidebarBuilder

Creates a new builder-pattern struct instance to construct PlacesSidebar objects.

This method returns an instance of PlacesSidebarBuilder which can be used to create PlacesSidebar objects.

pub fn add_shortcut(&self, location: &impl IsA<File>)

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.

location

location to add as an application-specific shortcut

pub fn is_local_only(&self) -> bool

Returns the value previously set with set_local_only().

Returns

true if the sidebar will only show local files.

pub fn location(&self) -> Option<File>

Gets the currently selected location in the self. This can be None when nothing is selected, for example, when 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 self. Also, if you connect to the signal::PlacesSidebar::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 gio::File with the selected location, or None if nothing is visually selected.

pub fn nth_bookmark(&self, n: i32) -> Option<File>

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

n

index of the bookmark to query

Returns

The bookmark specified by the index n, or None 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”.

pub fn open_flags(&self) -> PlacesOpenFlags

Gets the open flags.

Returns

the PlacesOpenFlags of self

pub fn shows_desktop(&self) -> bool

Returns the value previously set with set_show_desktop()

Returns

true if the sidebar will display a builtin shortcut to the desktop folder.

pub fn shows_enter_location(&self) -> bool

Returns the value previously set with set_show_enter_location()

Returns

true if the sidebar will display an “Enter Location” item.

pub fn shows_other_locations(&self) -> bool

Returns the value previously set with set_show_other_locations()

Returns

true if the sidebar will display an “Other Locations” item.

pub fn shows_recent(&self) -> bool

Returns the value previously set with set_show_recent()

Returns

true if the sidebar will display a builtin shortcut for recent files

pub fn shows_starred_location(&self) -> bool

Available on crate feature v3_22_26 only.

Returns the value previously set with set_show_starred_location()

Returns

true if the sidebar will display a Starred item.

pub fn shows_trash(&self) -> bool

Returns the value previously set with set_show_trash()

Returns

true if the sidebar will display a “Trash” item.

pub fn list_shortcuts(&self) -> Vec<File>

Gets the list of shortcuts.

Returns

A GSList of gio::File of the locations that have been added as application-specific shortcuts with add_shortcut(). To free this list, you can use

⚠️ The following code is in C ⚠️

g_slist_free_full (list, (GDestroyNotify) g_object_unref);

pub fn remove_shortcut(&self, location: &impl IsA<File>)

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

location

location to remove

pub fn set_drop_targets_visible(&self, visible: bool, context: &DragContext)

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.

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.

pub fn set_local_only(&self, local_only: bool)

Sets whether the self should only show local files.

local_only

whether to show only local files

pub fn set_location(&self, location: Option<&impl IsA<File>>)

Sets the location that is being shown in the widgets surrounding the self, for example, in a folder view in a file manager. In turn, the self 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.

location

location to select, or None for no current path

pub fn set_open_flags(&self, flags: PlacesOpenFlags)

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 self 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 signal::PlacesSidebar::open-location signal is emitted, its flags argument will be set to one of the flags that was passed in set_open_flags().

Passing 0 for flags will cause PlacesOpenFlags::NORMAL to always be sent to callbacks for the “open-location” signal.

flags

Bitmask of modes in which the calling application can open locations

pub fn set_show_desktop(&self, show_desktop: bool)

Sets whether the self 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.

show_desktop

whether to show an item for the Desktop folder

pub fn set_show_enter_location(&self, show_enter_location: bool)

Sets whether the self 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 signal::PlacesSidebar::show-enter-location signal.

show_enter_location

whether to show an item to enter a location

pub fn set_show_other_locations(&self, show_other_locations: bool)

Sets whether the self 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 signal::PlacesSidebar::show-other-locations signal.

show_other_locations

whether to show an item for the Other Locations view

pub fn set_show_recent(&self, show_recent: bool)

Sets whether the self 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.

show_recent

whether to show an item for recent files

pub fn set_show_starred_location(&self, show_starred_location: bool)

Available on crate feature v3_22_26 only.

If you enable this, you should connect to the signal::PlacesSidebar::show-starred-location signal.

show_starred_location

whether to show an item for Starred files

pub fn set_show_trash(&self, show_trash: bool)

Sets whether the self should show an item for the Trash location.

show_trash

whether to show an item for the Trash location

pub fn populates_all(&self) -> bool

If :populate-all is true, the signal::PlacesSidebar::populate-popup signal is also emitted for popovers.

pub fn set_populate_all(&self, populate_all: bool)

If :populate-all is true, the signal::PlacesSidebar::populate-popup signal is also emitted for popovers.

pub fn shows_connect_to_server(&self) -> bool

pub fn set_show_connect_to_server(&self, show_connect_to_server: bool)

pub fn connect_drag_action_ask<F: Fn(&Self, i32) -> i32 + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

actions

Possible drag actions that need to be asked for.

Returns

the final drag action that the sidebar should pass to the drag side of the drag-and-drop operation.

pub fn connect_mount<F: Fn(&Self, &MountOperation) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_20 only.

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 PlacesSidebar can track the progress of the operation and, for example, show a notification.

mount_operation

the gio::MountOperation that is going to start.

pub fn connect_open_location<F: Fn(&Self, &File, PlacesOpenFlags) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

location

gio::File to which the caller should switch.

open_flags

a single value from PlacesOpenFlags specifying how the location should be opened.

pub fn connect_show_enter_location<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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”.

pub fn connect_show_error_message<F: Fn(&Self, &str, &str) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

primary

primary message with a summary of the error to show.

secondary

secondary message with details of the error to show.

pub fn connect_show_other_locations<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

Deprecated since 3.20

use the signal::PlacesSidebar::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 signal::PlacesSidebar::open-location

pub fn connect_show_other_locations_with_flags<F: Fn(&Self, PlacesOpenFlags) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_20 only.

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.

open_flags

a single value from PlacesOpenFlags specifying how it should be opened.

pub fn connect_show_starred_location<F: Fn(&Self, PlacesOpenFlags) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_22_26 only.

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.

open_flags

a single value from PlacesOpenFlags specifying how the starred file should be opened.

pub fn connect_unmount<F: Fn(&Self, &MountOperation) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_20 only.

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 PlacesSidebar can track the progress of the operation and, for example, show a notification.

mount_operation

the gio::MountOperation that is going to start.

pub fn connect_local_only_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_location_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_open_flags_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_populate_all_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_connect_to_server_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_desktop_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_enter_location_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_other_locations_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_recent_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_show_starred_location_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Available on crate feature v3_22_26 only.

pub fn connect_show_trash_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Trait Implementations

impl Clone for PlacesSidebar

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PlacesSidebar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PlacesSidebar

fn default() -> Self

Returns the “default value” for a type.

impl Display for PlacesSidebar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for PlacesSidebar

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for PlacesSidebar

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl ParentClassIs for PlacesSidebar

type Parent = ScrolledWindow

impl<OT: ObjectType> PartialEq<OT> for PlacesSidebar

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<OT: ObjectType> PartialOrd<OT> for PlacesSidebar

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for PlacesSidebar

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for PlacesSidebar

impl IsA<Bin> for PlacesSidebar

impl IsA<Buildable> for PlacesSidebar

impl IsA<Container> for PlacesSidebar

impl IsA<ScrolledWindow> for PlacesSidebar

impl IsA<Widget> for PlacesSidebar