Struct gtk::PlacesSidebar

pub struct PlacesSidebar(_, _);

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 PlacesSidebar::add_shortcut.

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

CSS nodes

PlacesSidebar 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::object::ObjectExt, BuildableExt, WidgetExtManual, BuildableExtManual

Implementations

impl PlacesSidebar

pub fn new() -> PlacesSidebar

Creates a new PlacesSidebar widget.

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

Returns

a newly created PlacesSidebar

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

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 get_local_only(&self) -> bool

Returns the value previously set with PlacesSidebar::set_local_only.

Returns

true if the sidebar will only show local files.

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

Gets the currently selected location in the self. This can be None when nothing is selected, for example, when PlacesSidebar::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 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 get_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 get_open_flags(&self) -> PlacesOpenFlags

Gets the open flags.

Returns

the PlacesOpenFlags of self

pub fn get_show_connect_to_server(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_connect_to_server

Deprecated since 3.18

It is recommended to group this functionality with the drives and network location under the new 'Other Location' item

Returns

true if the sidebar will display a “Connect to Server” item.

pub fn get_show_desktop(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_desktop

Returns

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

pub fn get_show_enter_location(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_enter_location

Returns

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

pub fn get_show_other_locations(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_other_locations

Feature: v3_18

Returns

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

pub fn get_show_recent(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_recent

Feature: v3_18

Returns

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

pub fn get_show_starred_location(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_starred_location

Feature: v3_22_26

Returns

true if the sidebar will display a Starred item.

pub fn get_show_trash(&self) -> bool

Returns the value previously set with PlacesSidebar::set_show_trash

Feature: v3_18

Returns

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

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

Gets the list of shortcuts.

Returns

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

g_slist_free_full (list, (GDestroyNotify) g_object_unref);

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

Removes an application-specific shortcut that has been previously been inserted with PlacesSidebar::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 PlacesSidebar 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 PlacesSidebar. You only need to unset the state when the drag ends on some other widget on your application.

Feature: v3_18

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<P: IsA<File>>(&self, location: Option<&P>)

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

Sets whether the self 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 PlacesSidebar::show-connect-to-server signal.

Deprecated since 3.18

It is recommended to group this functionality with the drives and network location under the new 'Other Location' item

show_connect_to_server

whether to show an item for the Connect to Server command

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 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 PlacesSidebar::show-other-locations signal.

Feature: v3_18

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.

Feature: v3_18

show_recent

whether to show an item for recent files

pub fn set_show_starred_location(&self, show_starred_location: bool)

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

Feature: v3_22_26

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.

Feature: v3_18

show_trash

whether to show an item for the Trash location

pub fn get_property_populate_all(&self) -> bool

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

Feature: v3_18

pub fn set_property_populate_all(&self, populate_all: bool)

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

Feature: v3_18

pub fn get_property_show_other_locations(&self) -> bool

pub fn set_property_show_other_locations(&self, show_other_locations: bool)

pub fn get_property_show_recent(&self) -> bool

pub fn set_property_show_recent(&self, show_recent: bool)

pub fn get_property_show_trash(&self) -> bool

pub fn set_property_show_trash(&self, show_trash: bool)

pub fn connect_drag_action_ask<F: Fn(&PlacesSidebar, 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(&PlacesSidebar, &MountOperation) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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.

Feature: v3_20

mount_operation

the gio::MountOperation that is going to start.

pub fn connect_open_location<F: Fn(&PlacesSidebar, &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_connect_to_server<F: Fn(&PlacesSidebar) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

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, gio::File::mount_enclosing_volume.

Deprecated since 3.18

use the PlacesSidebar::show-other-locations signal to connect to network servers.

pub fn connect_show_enter_location<F: Fn(&PlacesSidebar) + '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(&PlacesSidebar, &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(&PlacesSidebar) + '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.

Feature: v3_18

Deprecated since 3.20

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

pub fn connect_show_other_locations_with_flags<F: Fn(&PlacesSidebar, PlacesOpenFlags) + '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.

Feature: v3_20

open_flags

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

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

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.

Feature: v3_22_26

open_flags

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

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

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.

Feature: v3_20

mount_operation

the gio::MountOperation that is going to start.

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

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

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

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

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

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

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

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

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

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

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

Trait Implementations

impl Clone for PlacesSidebar

fn clone(&self) -> PlacesSidebar

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 Eq for PlacesSidebar

impl Hash for PlacesSidebar

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

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 IsA<Bin> for PlacesSidebar

impl IsA<Buildable> for PlacesSidebar

impl IsA<Container> for PlacesSidebar

impl IsA<ScrolledWindow> for PlacesSidebar

impl IsA<Widget> for PlacesSidebar

impl Ord for PlacesSidebar

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

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

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

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

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

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

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

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

#[must_use]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.