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

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

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

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.

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

Returns the value previously set with set_local_only().

Returns

true if the sidebar will only show local files.

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.

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

Gets the open flags.

Returns

the PlacesOpenFlags of self

Returns the value previously set with set_show_desktop()

Returns

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

Returns the value previously set with set_show_enter_location()

Returns

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

Returns the value previously set with set_show_other_locations()

Returns

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

Returns the value previously set with set_show_recent()

Returns

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

This is supported 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.

Returns the value previously set with set_show_trash()

Returns

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

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);

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

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.

Sets whether the self should only show local files.

local_only

whether to show only local files

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

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

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

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

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

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

This is supported 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

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

show_trash

whether to show an item for the Trash location

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

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

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.

This is supported 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.

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.

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

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.

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

This is supported 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.

This is supported 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.

This is supported 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.

This is supported on crate feature v3_22_26 only.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

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

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

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

Returns the type identifier of Self.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Upcasts an object to a superclass or interface T. Read more

Upcasts an object to a reference of its superclass or interface T. Read more

Tries to downcast to a subclass or interface implementor T. Read more

Tries to downcast to a reference of its subclass or interface implementor T. Read more

Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Casts to T unconditionally. Read more

Casts to &T unconditionally. Read more

Performs the conversion.

Performs the conversion.

Returns true if the object is an instance of (can be cast to) T.

Returns the type of the object.

Returns the ObjectClass of the object. Read more

Returns the class of the object.

Returns the class of the object in the given type T. Read more

Returns the interface T of the object. Read more

Similar to Self::set_property but fails instead of panicking.

Sets the property property_name of the object to value value. Read more

Similar to Self::set_property but fails instead of panicking.

Sets the property property_name of the object to value value. Read more

Similar to Self::set_properties but fails instead of panicking.

Sets multiple properties of the object at once. Read more

Similar to Self::set_properties_from_value but fails instead of panicking.

Sets multiple properties of the object at once. Read more

Similar to Self::property but fails instead of panicking.

Gets the property property_name of the object and cast it to the type V. Read more

Similar to Self::property_value but fails instead of panicking.

Gets the property property_name of the object. Read more

Check if the object has a property property_name of the given type_. Read more

Get the type of the property property_name of this object. Read more

Get the ParamSpec of the property property_name of this object.

Return all ParamSpec of the properties of this object.

Freeze all property notifications until the return guard object is dropped. Read more

Set arbitrary data on this object with the given key. Read more

Return previously set arbitrary data of this object with the given key. Read more

Retrieve previously set arbitrary data of this object with the given key. Read more

Set arbitrary data on this object with the given key. Read more

Return previously set arbitrary data of this object with the given key. Read more

Retrieve previously set arbitrary data of this object with the given key. Read more

Block a given signal handler. Read more

Unblock a given signal handler.

Stop emission of the currently emitted signal.

Stop emission of the currently emitted signal by the (possibly detailed) signal name.

Similar to Self::connect but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_id but fails instead of panicking.

Connect to the signal signal_id on this object. Read more

Similar to Self::connect_local but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_local_id but fails instead of panicking.

Connect to the signal signal_id on this object. Read more

Similar to Self::connect_unsafe but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_unsafe_id but fails instead of panicking.

Similar to Self::connect_closure but fails instead of panicking.

Connect a closure to the signal signal_name on this object. Read more

Similar to Self::connect_closure_id but fails instead of panicking.

Connect a closure to the signal signal_id on this object. Read more

Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to Closure::invoke. Read more

Connect to the signal signal_id on this object. Read more

Similar to Self::emit but fails instead of panicking.

Emit signal by signal id. Read more

Similar to Self::emit_with_values but fails instead of panicking.

Same as Self::emit but takes Value for the arguments.

Similar to Self::emit_by_name but fails instead of panicking.

Emit signal by its name. Read more

Similar to Self::emit_by_name_with_values but fails instead of panicking.

Emit signal by its name. Read more

Similar to Self::emit_with_details but fails instead of panicking.

Emit signal by signal id with details. Read more

Similar to Self::emit_with_details_and_values but fails instead of panicking.

Emit signal by signal id with details. Read more

Disconnect a previously connected signal handler.

Connect to the notify signal of the object. Read more

Connect to the notify signal of the object. Read more

Connect to the notify signal of the object. Read more

Notify that the given property has changed its value. Read more

Notify that the given property has changed its value. Read more

Downgrade this object to a weak reference.

Bind property source_property on this object to the target_property on the target object. Read more

Returns the strong reference count of this object.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

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

Uses borrowed data to replace owned data, usually by cloning. Read more

Returns a SendValue clone of self.

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.