Gtk.PlacesSidebar

Gtk.PlacesSidebar — Sidebar that displays frequently-used places in the file system

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.ScrolledWindow
                        ╰── Gtk.PlacesSidebar

See also:

Gtk.FileChooser

Functions:

Signals:

  • “drag-action-ask” (sidebar, actions, user_data)
  • “drag-action-requested” (sidebar, context, dest_file, source_file_list, user_data)
  • “drag-perform-drop” (sidebar, dest_file, source_file_list, action, user_data)
  • “open-location” (sidebar, location, open_flags, user_data)
  • “populate-popup” (sidebar, container, selected_item, selected_volume, user_data)
  • “show-connect-to-server” (sidebar, user_data)
  • “show-enter-location” (sidebar, user_data)
  • “show-error-message” (sidebar, primary, secondary, user_data)

Description:

Gtk.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 Gtk.FileChooser and may be used by file managers and similar programs.

This widget is used as a sidebar in Gtk.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 Gtk.PlacesSidebar::add_shortcut().

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

Function Details:

new()

new () -> Gtk.Widget

Creates a new Gtk.PlacesSidebar widget. The application should connect to at least the“open-location” signal to be notifiedwhen the user makes a selection in the sidebar.

  • Returns: a newly created Gtk.PlacesSidebar

  • Since: 3.10

set_open_flags()

set_open_flags (self, flags:Gtk.PlacesOpenFlags)

Sets the way in which the calling application can open new locations fromthe places sidebar. For example, some applications only open locations“directly” into their main view, while others may support opening locationsin a new notebook tab or a new window. This function is used to tell the places sidebar about the ways in which theapplication 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 “open-location” signal is emitted, its flagsargument will be set to one of the flags that was passed inGtk.PlacesSidebar:set_open_flags(). Passing 0 for flags will cause GTK_PLACES_OPEN_NORMAL to always be sentto callbacks for the “open-location” signal.

  • Since: 3.10

get_open_flags()

get_open_flags (self) -> Gtk.PlacesOpenFlags

Gets the open flags.

  • Returns: the Gtk.PlacesOpenFlags of sidebar

  • Since: 3.10

set_location()

set_location (self, location:Gio.File=None)

Sets the location that is being shown in the widgets surrounding thesidebar, for example, in a folder view in a file manager. In turn, thesidebar will highlight that location if it is being shown in the list ofplaces, or it will unhighlight everything if the location is not among theplaces in the list.

  • Since: 3.10

get_location()

get_location (self) -> Gio.File

Gets the currently-selected location in the sidebar. This can be None whennothing is selected, for example, when Gtk.PlacesSidebar:set_location() hasbeen called with a location that is not among the sidebar’s list of places toshow. You can use this function to get the selection in the sidebar. Also, if youconnect to the “populate-popup” signal, you can use thisfunction to get the location that is being referred to during the callbacksfor your menu items.

  • Returns: a GFile with the selected location, or None if nothing is visuallyselected.

  • Since: 3.10

set_show_recent()

set_show_recent (self, show_recent:bool)

Sets whether the sidebar should show an item for recent files.The default value for this option is determined by the desktopenvironment, but this function can be used to override it on aper-application basis.

  • Since: 3.18

get_show_recent()

get_show_recent (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_show_recent()

  • Returns: True if the sidebar will display a builtin shortcut for recent files

  • Since: 3.18

set_show_desktop()

set_show_desktop (self, show_desktop:bool)

Sets whether the sidebar should show an item for the Desktop folder.The default value for this option is determined by the desktopenvironment and the user’s configuration, but this function can beused to override it on a per-application basis.

  • Since: 3.10

get_show_desktop()

get_show_desktop (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_show_desktop()

  • Returns: True if the sidebar will display a builtin shortcut to the desktop folder.

  • Since: 3.10

add_shortcut()

add_shortcut (self, location:Gio.File)

Applications may want to present some folders in the places sidebar ifthey could be immediately useful to users. For example, a drawingprogram could add a “/usr/share/clipart” location when the sidebar isbeing used in an “Insert Clipart” dialog box. This function adds the specified location to a special place for immutableshortcuts. The shortcuts are application-specific; they are not sharedacross applications, and they are not persistent. If this functionis called multiple times with different locations, then they are addedto the sidebar’s list in the same order as the function is called.

  • Since: 3.10

remove_shortcut()

remove_shortcut (self, location:Gio.File)

Removes an application-specific shortcut that has been previously beeninserted with Gtk.PlacesSidebar:add_shortcut(). If the location is not ashortcut in the sidebar, then nothing is done.

  • Since: 3.10

list_shortcuts()

list_shortcuts (self) -> list

Gets the list of shortcuts.

  • Returns: A GSList of GFile of the locations that have been added asapplication-specific shortcuts with Gtk.PlacesSidebar:add_shortcut().To free this list, you can use

  • Since: 3.10

get_nth_bookmark()

get_nth_bookmark (self, n:int) -> Gio.File

This function queries the bookmarks added by the user to the places sidebar,and returns one of them. This function is used by Gtk.FileChooser to implementthe “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark.

  • Returns: The bookmark specified by the index n, orNone if no such index exist. Note that the indices start at 0, even thoughthe file chooser starts them with the keyboard shortcut “Alt-1”.

  • Since: 3.10

get_show_connect_to_server()

get_show_connect_to_server (self) -> bool

Gtk.PlacesSidebar:get_show_connect_to_server has been deprecated since version 3.18 and should not be used in newly-written code. It is recommended to group this functionality with the drives and network location under the new 'Other Location' item Returns the value previously set with Gtk.PlacesSidebar:set_show_connect_to_server()

  • Returns: True if the sidebar will display a “Connect to Server” item.

set_show_connect_to_server()

set_show_connect_to_server (self, show_connect_to_server:bool)

Gtk.PlacesSidebar:set_show_connect_to_server has been deprecated since version 3.18 and should not be used in newly-written code. It is recommended to group this functionality with the drives and network location under the new 'Other Location' item Sets whether the sidebar 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 implementsa way for the user to connect to network servers directly. If you enable this, you should connect to the“show-connect-to-server” signal.

  • Since: 3.10

get_local_only()

get_local_only (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_local_only().

  • Returns: True if the sidebar will only show local files.

  • Since: 3.12

set_local_only()

set_local_only (self, local_only:bool)

Sets whether the sidebar should only show local files.

  • Since: 3.12

get_show_enter_location()

get_show_enter_location (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_show_enter_location()

  • Returns: True if the sidebar will display an “Enter Location” item.

  • Since: 3.14

set_show_enter_location()

set_show_enter_location (self, show_enter_location:bool)

Sets whether the sidebar should show an item for entering a location;this is off by default. An application may want to turn this on if manuallyentering URLs is an expected user action. If you enable this, you should connect to the“show-enter-location” signal.

  • Since: 3.14

get_show_trash()

get_show_trash (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_show_trash()

  • Returns: True if the sidebar will display a “Trash” item.

  • Since: 3.18

set_show_trash()

set_show_trash (self, show_trash:bool)

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

  • Since: 3.18

get_show_other_locations()

get_show_other_locations (self) -> bool

Returns the value previously set with Gtk.PlacesSidebar:set_show_other_locations()

  • Returns: True if the sidebar will display an “Other Locations” item.

  • Since: 3.18

set_show_other_locations()

set_show_other_locations (self, show_other_locations:bool)

Sets whether the sidebar should show an item for the application to showan Other Locations view; this is off by default. When set to True, persistentdevices 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 tosee and interact with drives and network servers directly. If you enable this, you should connect to the“show-other-locations” signal.

  • Since: 3.18

set_drop_targets_visible()

set_drop_targets_visible (self, visible:bool, context:Gdk.DragContext)

Make the Gtk.PlacesSidebar show drop targets, so it can show the availabledrop targets and a "new bookmark" row. This improves the Drag-and-Dropexperience of the user and allows applications to show all availabledrop targets at once. This needs to be called when the application is aware of an ongoing dragthat might target the sidebar. The drop-targets-visible state will be unsetautomatically if the drag finishes in the Gtk.PlacesSidebar. You only needto unset the state when the drag ends on some other widget on your application.

  • Since: 3.18

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
from gi.repository import Gio

class PlacesSidebar(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.connect("destroy", Gtk.main_quit)

        placessidebar = Gtk.PlacesSidebar()
        placessidebar.connect("open-location", self.on_open_location)
        self.add(placessidebar)

    def on_open_location(self, placessidebar, location, flags):
        location = placessidebar.get_location()

        print("Opened URI: %s" % (GLocalFile.get_uri(location)))

window = PlacesSidebar()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""