Class gtk-places-sidebar

Package: gtk

Superclasses

gtk-scrolled-window, gtk-bin, gtk-container, gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

The local-only property of type :boolean (Read / Write)
Whether the sidebar only includes local files.
Default value: false

The location property of type g-file (Read / Write)
The location to highlight in the sidebar.

The open-flags property of type gtk-places-open-flags (Read / Write)
Modes in which the calling application can open locations selected in the sidebar.
Default value: :normal

The populate-all property of type :boolean (Read / Write)
If populate-all is true, the "populate-popup" signal is also emitted for popovers. Since 3.18
Default value: false

The show-connect-to-server property of type :boolean (Read / Write)
Whether the sidebar includes a builtin shortcut to a 'Connect to server' dialog.
Default value: false

The show-desktop property of type :boolean (Read / Write)
Whether the sidebar includes a builtin shortcut to the Desktop folder.
Default value: true

The show-enter-location property of type :boolean (Read / Write)
Whether the sidebar includes a builtin shortcut to manually enter a location.
Default value: false

The show-other-locations property of type :boolean (Read / Write)
Whether the sidebar includes an item to show external locations. Since 3.18
Default value: false

The show-recent property of type :boolean (Read / Write)
Whether the sidebar includes a builtin shortcut for recent files. Since 3.18
Default value: true

The show-starred-location property of type :boolean (Read / Write)
Whether the sidebar includes an item to show starred files. Since 3.24
Default value: false

The show-trash property of type :boolean (Read / Write)
Whether the sidebar includes a builtin shortcut to the Trash location. Since 3.18
Default value: true

Details

The gtk-places-sidebar 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 the gtk-file-chooser interface 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 the function 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 the function gtk-places-sidebar-location when it changes the currently-viewed location.

CSS nodes

The gtk-places-sidebar implementation uses a single CSS node with name placessidebar and .sidebar style class.

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

Signal Details

The "drag-action-ask" signal

 lambda (sidebar actions)    : Run Last

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.

sidebar: The gtk-places-sidebar widget which received the signal.
actions: An integer with the possible drag actions that need to be asked for.
Returns: An integer with the final drag action that the sidebar should pass to the drag side of the drag and drop operation.

The "drag-action-requested" signal

 lambda (sidebar context dest-file source-file-list)    : Run Last

When the user starts a drag and drop operation and the sidebar needs to ask the application for which drag action to perform, then the sidebar will emit this signal.

The application can evaluate the context for customary actions, or it can check the type of the files indicated by source-file-list against the possible actions for the destination dest-file.

The drag action to use must be the return value of the signal handler.

sidebar: The gtk-places-sidebar widget which received the signal.
context: The gdk-drag-context with information about the drag operation.
dest-file: A g-file with the tentative location that is being hovered for a drop.
source-file-list: List of g-file objects that are being dragged.
Returns: An integer with the drag action to use, for example, GDK_ACTION_COPY or GDK_ACTION_MOVE, or 0 if no action is allowed here, i.e. drops are not allowed in the specified dest-file.

The "drag-perform-drop" signal

 lambda (sidebar dest-file source-file-list action)    : Run First

The places sidebar emits this signal when the user completes a drag and drop operation and one of the sidebar's items is the destination. This item is in the dest-file, and the source-file-list has the list of files that are dropped into it and which should be

sidebar: The gtk-places-sidebar widget which received the signal.
dest-file: Destination g-file.
source-file-list: List of g-file that got dropped.
action: An integer with the drop action to perform.

The "mount" signal

 lambda (sidebar mount-operation)    : Run First

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 gtk-places-sidebar can track the progress of the operation and, for example, show a notification. Since 3.20

sidebar: The gtk-places-sidebar widget which received the signal.
mount-operation: The g-mount-operation that is going to start.

The "open-location" signal

 lambda (sidebar location open-flags)    : Run First

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.

sidebar: The gtk-places-sidebar widget which received the signal.
location: The g-file to which the caller should switch.
open-flags: A single value from the gtk-places-open-flags flags specifying how the location should be opened.

The "populate-popup" signal

 lambda (sidebar container selected-item selected-volume)    : Run First

The places sidebar emits this signal when the user invokes a contextual popup on one of its items. In the signal handler, the application may add extra items to the menu as appropriate. For example, a file manager may want to add a "Properties" command to the menu.

It is not necessary to store the selected-item for each menu item; during their callbacks, the application can use the function gtk-places-sidebar-location to get the file to which the item refers.

The selected-item argument may be nil in case the selection refers to a volume. In this case, selected-volume will be non-nil. In this case, the calling application will have to the function g-object-ref the selected-volume and keep it around to use it in the callback.

The container and all its contents are destroyed after the user dismisses the popup. The popup is re-created, and thus, this signal is emitted, every time the user activates the contextual menu.

Before 3.18, the container always was a gtk-menu, and you were expected to add your items as gtk-menu-item objects. Since 3.18, the popup may be implemented as a gtk-popover, in which case container will be something else, e.g. a gtk-box, to which you may add gtk-model-button widgets or other widgets, such as gtk-entry, gtk-spin-button widgets, etc. If your application can deal with this situation, you can set populate-all to true to request that this signal is emitted for populating popovers as well.

sidebar: The gtk-places-sidebar widget which received the signal.
container: A gtk-menu or another gtk-container.
selected-item: A g-file with the item to which the popup should refer, or nil in the case of a selected-volume.
selected-volume: A g-volume if the selected item is a volume, or nil if it is a file.

The "show-connect-to-server" signal

 lambda (sidebar)    : Run First

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, g_file_mount_enclosing_volume().

Warning: The "show-connect-to-server" signal has been deprecated since version 3.18 and should not be used in newly written code. Use the "show-other-locations" signal to connect to network servers.

sidebar: The gtk-places-sidebar widget which received the signal.

The "show-enter-location" signal

 lambda (sidebar)    : Run First

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

sidebar: The gtk-places-sidebar widget which received the signal.

The "show-error-message" signal

 lambda (sidebar primary secondary)    : Run First

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.

sidebar: The gtk-places-sidebar widget which received the signal.
primary: A string with the primary message with a summary of the error to show.
secondary: A string with the secondary message with details of the error to show.

The "show-other-locations" signal

 lambda (sidebar)    : Run First

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. Since 3.18

Warning: The "show-other-locations" signal has been deprecated since version 3.20 and should not be used in newly written code. Use the "show-other-locations-with-flags" signal 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 the "open-location" signal.

sidebar: The gtk-places-sidebar widget which received the signal.

The "show-other-locations-with-flags" signal

 lambda (sidebar open-flags)    : Run First

sidebar: The gtk-places-sidebar widget which received the signal.
open-flags: A single value from gtk-places-open-flags specifying how it should be opened.

The "show-starred-location" signal

 lambda (sidebar open-flags)    : Run First

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. Since 3.22

sidebar: The gtk-places-sidebar widget which received the signal.
open-flags: A single value from gtk-places-open-flags specifying how the starred file should be opened.

The "unmount" signal

 lambda (sidebar mount-operation)    : Run First

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 gtk-places-sidebar can track the progress of the operation and, for example, show a notification. Since 3.20

sidebar: The gtk-places-sidebar widget which received the signal.
mount-operation: The GMountOperation that is going to start.