#[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

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

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.

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.

open_flags

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

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.

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.

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
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

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

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
Sets the property property_name of the object to value value. Read more
Sets the property property_name of the object to value value. Read more
Sets multiple properties of the object at once. Read more
Sets multiple properties of the object at once. Read more
Gets the property property_name of the object and cast it to the type V. Read more
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.
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect a closure to the signal signal_name on this object. Read more
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 invoke_with_values, or invoke when using Rust closures. Read more
Emit signal by signal id. Read more
Same as Self::emit but takes Value for the arguments.
Emit signal by its name. Read more
Emit signal by its name. Read more
Emit signal by its name with details. Read more
Emit signal by its name with details. Read more
Emit signal by signal id with details. Read more
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.
Add a callback to be notified when the Object is disposed.
Add a callback to be notified when the Object is disposed. Read more
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.
Ensures that the type has been registered with the type system.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
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.