gi-gtk-3.0.11: Gtk bindings

CopyrightWill Thompson, Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.PlacesSidebar

Contents

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

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

CSS nodes

GtkPlacesSidebar uses a single CSS node with name placesidebar 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

Synopsis

Exported types

Methods

addShortcut

placesSidebarAddShortcut Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a, IsFile b) 
=> a

sidebar: a places sidebar

-> b

location: location to add as an application-specific shortcut

-> m () 

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.

Since: 3.10

getLocalOnly

placesSidebarGetLocalOnly Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetLocalOnly.

Since: 3.12

getLocation

placesSidebarGetLocation Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m (Maybe File)

Returns: a GFile with the selected location, or Nothing if nothing is visually selected.

Gets the currently-selected location in the sidebar. This can be NULL when nothing is selected, for example, when placesSidebarSetLocation 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 sidebar. Also, if you connect to the 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.

Since: 3.10

getNthBookmark

placesSidebarGetNthBookmark Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Int32

n: index of the bookmark to query

-> m (Maybe File)

Returns: The bookmark specified by the index n, or Nothing 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".

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.

Since: 3.10

getOpenFlags

placesSidebarGetOpenFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a PlacesSidebar

-> m [PlacesOpenFlags]

Returns: the PlacesOpenFlags of sidebar

Gets the open flags.

Since: 3.10

getShowConnectToServer

placesSidebarGetShowConnectToServer Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Deprecated: (Since version 3.18)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 placesSidebarSetShowConnectToServer

getShowDesktop

placesSidebarGetShowDesktop Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetShowDesktop

Since: 3.10

getShowEnterLocation

placesSidebarGetShowEnterLocation Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetShowEnterLocation

Since: 3.14

getShowOtherLocations

placesSidebarGetShowOtherLocations Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetShowOtherLocations

Since: 3.18

getShowRecent

placesSidebarGetShowRecent Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetShowRecent

Since: 3.18

getShowTrash

placesSidebarGetShowTrash Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m Bool

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

Returns the value previously set with placesSidebarSetShowTrash

Since: 3.18

listShortcuts

placesSidebarListShortcuts Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> m [File]

Returns: A SList of File of the locations that have been added as application-specific shortcuts with placesSidebarAddShortcut. To free this list, you can use

C code

g_slist_free_full (list, (GDestroyNotify) g_object_unref);

Gets the list of shortcuts.

Since: 3.10

new

placesSidebarNew Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m PlacesSidebar

Returns: a newly created PlacesSidebar

Creates a new PlacesSidebar widget.

The application should connect to at least the PlacesSidebar::open-location signal to be notified when the user makes a selection in the sidebar.

Since: 3.10

removeShortcut

placesSidebarRemoveShortcut Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a, IsFile b) 
=> a

sidebar: a places sidebar

-> b

location: location to remove

-> m () 

Removes an application-specific shortcut that has been previously been inserted with placesSidebarAddShortcut. If the location is not a shortcut in the sidebar, then nothing is done.

Since: 3.10

setDropTargetsVisible

placesSidebarSetDropTargetsVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a, IsDragContext b) 
=> a

sidebar: a places sidebar.

-> Bool

visible: whether to show the valid targets or not.

-> b

context: drag context used to ask the source about the action that wants to perform, so hints are more accurate.

-> m () 

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.

Since: 3.18

setLocalOnly

placesSidebarSetLocalOnly Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

localOnly: whether to show only local files

-> m () 

Sets whether the sidebar should only show local files.

Since: 3.12

setLocation

placesSidebarSetLocation Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a, IsFile b) 
=> a

sidebar: a places sidebar

-> Maybe b

location: location to select, or NULL for no current path

-> m () 

Sets the location that is being shown in the widgets surrounding the sidebar, for example, in a folder view in a file manager. In turn, the sidebar 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.

Since: 3.10

setOpenFlags

placesSidebarSetOpenFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> [PlacesOpenFlags]

flags: Bitmask of modes in which the calling application can open locations

-> m () 

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 sidebar 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 PlacesSidebar::open-location signal is emitted, its flags argument will be set to one of the flags that was passed in placesSidebarSetOpenFlags.

Passing 0 for flags will cause GTK_PLACES_OPEN_NORMAL to always be sent to callbacks for the “open-location” signal.

Since: 3.10

setShowConnectToServer

placesSidebarSetShowConnectToServer Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showConnectToServer: whether to show an item for the Connect to Server command

-> m () 

Deprecated: (Since version 3.18)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 implements a way for the user to connect to network servers directly.

If you enable this, you should connect to the PlacesSidebar::show-connect-to-server signal.

Since: 3.10

setShowDesktop

placesSidebarSetShowDesktop Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showDesktop: whether to show an item for the Desktop folder

-> m () 

Sets whether the sidebar 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.

Since: 3.10

setShowEnterLocation

placesSidebarSetShowEnterLocation Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showEnterLocation: whether to show an item to enter a location

-> m () 

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 manually entering URLs is an expected user action.

If you enable this, you should connect to the PlacesSidebar::show-enter-location signal.

Since: 3.14

setShowOtherLocations

placesSidebarSetShowOtherLocations Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showOtherLocations: whether to show an item for the Other Locations view

-> m () 

Sets whether the sidebar 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 PlacesSidebar::show-other-locations signal.

Since: 3.18

setShowRecent

placesSidebarSetShowRecent Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showRecent: whether to show an item for recent files

-> m () 

Sets whether the sidebar 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.

Since: 3.18

setShowTrash

placesSidebarSetShowTrash Source #

Arguments

:: (HasCallStack, MonadIO m, IsPlacesSidebar a) 
=> a

sidebar: a places sidebar

-> Bool

showTrash: whether to show an item for the Trash location

-> m () 

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

Since: 3.18

Properties

localOnly

data PlacesSidebarLocalOnlyPropertyInfo Source #

Instances

AttrInfo PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrOrigin PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrLabel PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrGetType PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarLocalOnlyPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarLocalOnlyPropertyInfo Source # 

location

data PlacesSidebarLocationPropertyInfo Source #

Instances

AttrInfo PlacesSidebarLocationPropertyInfo Source # 
type AttrOrigin PlacesSidebarLocationPropertyInfo Source # 
type AttrLabel PlacesSidebarLocationPropertyInfo Source # 
type AttrGetType PlacesSidebarLocationPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarLocationPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarLocationPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarLocationPropertyInfo Source # 

openFlags

data PlacesSidebarOpenFlagsPropertyInfo Source #

Instances

AttrInfo PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrOrigin PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrLabel PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrGetType PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarOpenFlagsPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarOpenFlagsPropertyInfo Source # 

populateAll

data PlacesSidebarPopulateAllPropertyInfo Source #

Instances

AttrInfo PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrOrigin PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrLabel PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrGetType PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarPopulateAllPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarPopulateAllPropertyInfo Source # 

showConnectToServer

data PlacesSidebarShowConnectToServerPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrLabel PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrGetType PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowConnectToServerPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowConnectToServerPropertyInfo Source # 

showDesktop

data PlacesSidebarShowDesktopPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrLabel PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrGetType PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowDesktopPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowDesktopPropertyInfo Source # 

showEnterLocation

data PlacesSidebarShowEnterLocationPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrLabel PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrGetType PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowEnterLocationPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowEnterLocationPropertyInfo Source # 

showOtherLocations

data PlacesSidebarShowOtherLocationsPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrLabel PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrGetType PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowOtherLocationsPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowOtherLocationsPropertyInfo Source # 

showRecent

data PlacesSidebarShowRecentPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowRecentPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowRecentPropertyInfo Source # 
type AttrLabel PlacesSidebarShowRecentPropertyInfo Source # 
type AttrGetType PlacesSidebarShowRecentPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowRecentPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowRecentPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowRecentPropertyInfo Source # 

showTrash

data PlacesSidebarShowTrashPropertyInfo Source #

Instances

AttrInfo PlacesSidebarShowTrashPropertyInfo Source # 
type AttrOrigin PlacesSidebarShowTrashPropertyInfo Source # 
type AttrLabel PlacesSidebarShowTrashPropertyInfo Source # 
type AttrGetType PlacesSidebarShowTrashPropertyInfo Source # 
type AttrBaseTypeConstraint PlacesSidebarShowTrashPropertyInfo Source # 
type AttrSetTypeConstraint PlacesSidebarShowTrashPropertyInfo Source # 
type AttrAllowedOps PlacesSidebarShowTrashPropertyInfo Source # 

Signals

dragActionAsk

dragActionRequested

dragPerformDrop

mount

openLocation

populatePopup

showConnectToServer

type PlacesSidebarShowConnectToServerCallback = IO () Source #

Deprecated: (Since version 3.18)use the PlacesSidebar::show-other-locations signal to connect to network servers.

showEnterLocation

showErrorMessage

showOtherLocations

type PlacesSidebarShowOtherLocationsCallback = IO () Source #

Deprecated: (Since version 3.20)use the PlacesSidebar::show-other-locations-with-flagswhich includes the open flags in order to allow the user to specify to openin a new tab or window, in a similar way than PlacesSidebar::open-location

showOtherLocationsWithFlags

unmount