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

None

The gtk:places-sidebar widget 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.

Figure: GtkPlacesSidebar

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 gtk:places-sidebar-add-shortcut function.

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

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 source)    :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 against the possible actions for the destination dest. 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 object with information about the drag operation.

dest

A g:file object with the tentative location that is being hovered for a drop.

source

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.

The "drag-perform-drop" signal

lambda (sidebar dest source 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, and the source has the list of files that are dropped into it and which should be copied/moved/ etc. based on the specified action.

sidebar

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

dest

Destination g:file object.

source

List of g:file objects that got dropped.

action

An integer with the drop action to perform.

The "mount" signal

lambda (sidebar mount)    :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 widget can track the progress of the operation and, for example, show a notification.

sidebar

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

mount

The g:mount-operation object that is going to start.

The "open-location" signal

lambda (sidebar location 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 object to which the caller should switch.

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 item 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 item for each menu item; during their callbacks, the application can use the gtk:places-sidebar-location function to get the file to which the item refers.

The item argument may be nil in case the selection refers to a volume. In this case, volume will be non-nil. In this case, the calling application will have to the g:object-ref function the 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 widget, 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 widget, in which case container will be something else, e.g. a gtk:box widget, 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 widget or another gtk:container widget.

item

A g:file object with the item to which the popup should refer, or nil in the case of a volume.

volume

A g:volume object 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.

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 flags)    :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.

sidebar

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

flags

A single gtk:places-open-flags value specifying how it should be opened.

The "show-starred-location" signal

lambda (sidebar 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.

sidebar

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

flags

A single gtk:places-open-flags value specifying how the starred file should be opened.

The "unmount" signal

lambda (sidebar mount)    :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 widget can track the progress of the operation and, for example, show a notification.

sidebar

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

mount

The GMountOperation that is going to start.