PlacesSidebar

#GtkPlacesSidebar 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 #GtkFileChooser 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.places_sidebar.PlacesSidebar.addShortcut.

To make use of the places sidebar, an application at least needs to connect to the #GtkPlacesSidebar::open-location signal. This is emitted when the user selects in the sidebar a location to open. The application should also call gtk.places_sidebar.PlacesSidebar.setLocation 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

class PlacesSidebar : ScrolledWindow {

this(void* ptr, Flag!"Take" take);

static GType _getGType();

GType _gType [@property getter];

PlacesSidebar self();

static PlacesSidebarGidBuilder builder();

bool localOnly [@property getter];

bool localOnly [@property setter];

gio.file.File location [@property getter];

gio.file.File location [@property setter];

gtk.types.PlacesOpenFlags openFlags [@property getter];

gtk.types.PlacesOpenFlags openFlags [@property setter];

bool populateAll [@property getter];

bool populateAll [@property setter];

bool showConnectToServer [@property getter];

bool showConnectToServer [@property setter];

bool showDesktop [@property getter];

bool showDesktop [@property setter];

bool showEnterLocation [@property getter];

bool showEnterLocation [@property setter];

bool showOtherLocations [@property getter];

bool showOtherLocations [@property setter];

bool showRecent [@property getter];

bool showRecent [@property setter];

bool showStarredLocation [@property getter];

bool showStarredLocation [@property setter];

bool showTrash [@property getter];

bool showTrash [@property setter];

void addShortcut(gio.file.File location);

bool getLocalOnly();

gio.file.File getLocation();

gio.file.File getNthBookmark(int n);

gtk.types.PlacesOpenFlags getOpenFlags();

bool getShowConnectToServer();

bool getShowDesktop();

bool getShowEnterLocation();

bool getShowOtherLocations();

bool getShowRecent();

bool getShowStarredLocation();

bool getShowTrash();

gio.file.File[] listShortcuts();

void removeShortcut(gio.file.File location);

void setDropTargetsVisible(bool visible, gdk.drag_context.DragContext context);

void setLocalOnly(bool localOnly);

void setLocation(gio.file.File location);

void setOpenFlags(gtk.types.PlacesOpenFlags flags);

void setShowConnectToServer(bool showConnectToServer);

void setShowDesktop(bool showDesktop);

void setShowEnterLocation(bool showEnterLocation);

void setShowOtherLocations(bool showOtherLocations);

void setShowRecent(bool showRecent);

void setShowStarredLocation(bool showStarredLocation);

void setShowTrash(bool showTrash);

gulong connectDragActionAsk(T callback, Flag!"After" after);

gulong connectDragActionRequested(T callback, Flag!"After" after);

gulong connectDragPerformDrop(T callback, Flag!"After" after);

gulong connectMount(T callback, Flag!"After" after);

gulong connectOpenLocation(T callback, Flag!"After" after);

gulong connectPopulatePopup(T callback, Flag!"After" after);

gulong connectShowConnectToServer(T callback, Flag!"After" after);

gulong connectShowEnterLocation(T callback, Flag!"After" after);

gulong connectShowErrorMessage(T callback, Flag!"After" after);

gulong connectShowOtherLocations(T callback, Flag!"After" after);

gulong connectShowOtherLocationsWithFlags(T callback, Flag!"After" after);

gulong connectShowStarredLocation(T callback, Flag!"After" after);

gulong connectUnmount(T callback, Flag!"After" after);

}

Constructors

this this(void* ptr, Flag!"Take" take)
this this(): Creates a new #GtkPlacesSidebar widget.

Members

Functions

addShortcut void addShortcut(gio.file.File location): 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.
connectDragActionAsk gulong connectDragActionAsk(T callback, Flag!"After" after): Connect to DragActionAsk signal.
connectDragActionRequested gulong connectDragActionRequested(T callback, Flag!"After" after): Connect to DragActionRequested signal.
connectDragPerformDrop gulong connectDragPerformDrop(T callback, Flag!"After" after): Connect to DragPerformDrop signal.
connectMount gulong connectMount(T callback, Flag!"After" after): Connect to Mount signal.
connectOpenLocation gulong connectOpenLocation(T callback, Flag!"After" after): Connect to OpenLocation signal.
connectPopulatePopup gulong connectPopulatePopup(T callback, Flag!"After" after): Connect to PopulatePopup signal.
connectShowConnectToServer gulong connectShowConnectToServer(T callback, Flag!"After" after): Connect to ShowConnectToServer signal.
connectShowEnterLocation gulong connectShowEnterLocation(T callback, Flag!"After" after): Connect to ShowEnterLocation signal.
connectShowErrorMessage gulong connectShowErrorMessage(T callback, Flag!"After" after): Connect to ShowErrorMessage signal.
connectShowOtherLocations gulong connectShowOtherLocations(T callback, Flag!"After" after): Connect to ShowOtherLocations signal.
connectShowOtherLocationsWithFlags gulong connectShowOtherLocationsWithFlags(T callback, Flag!"After" after): Connect to ShowOtherLocationsWithFlags signal.
connectShowStarredLocation gulong connectShowStarredLocation(T callback, Flag!"After" after): Connect to ShowStarredLocation signal.
connectUnmount gulong connectUnmount(T callback, Flag!"After" after): Connect to Unmount signal.
getLocalOnly bool getLocalOnly(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setLocalOnly.
getLocation gio.file.File getLocation(): Gets the currently selected location in the sidebar. This can be null when nothing is selected, for example, when gtk.places_sidebar.PlacesSidebar.setLocation has been called with a location that is not among the sidebar’s list of places to show.
getNthBookmark gio.file.File getNthBookmark(int n): This function queries the bookmarks added by the user to the places sidebar, and returns one of them. This function is used by #GtkFileChooser to implement the “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark.
getOpenFlags gtk.types.PlacesOpenFlags getOpenFlags(): Gets the open flags.
getShowConnectToServer bool getShowConnectToServer(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowConnectToServer
getShowDesktop bool getShowDesktop(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowDesktop
getShowEnterLocation bool getShowEnterLocation(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowEnterLocation
getShowOtherLocations bool getShowOtherLocations(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowOtherLocations
getShowRecent bool getShowRecent(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowRecent
getShowStarredLocation bool getShowStarredLocation(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowStarredLocation
getShowTrash bool getShowTrash(): Returns the value previously set with gtk.places_sidebar.PlacesSidebar.setShowTrash
listShortcuts gio.file.File[] listShortcuts(): Gets the list of shortcuts.
removeShortcut void removeShortcut(gio.file.File location): Removes an application-specific shortcut that has been previously been inserted with gtk.places_sidebar.PlacesSidebar.addShortcut. If the location is not a shortcut in the sidebar, then nothing is done.
self PlacesSidebar self(): Returns this, for use in with statements.
setDropTargetsVisible void setDropTargetsVisible(bool visible, gdk.drag_context.DragContext context): 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.
setLocalOnly void setLocalOnly(bool localOnly): Sets whether the sidebar should only show local files.
setLocation void setLocation(gio.file.File location): 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.
setOpenFlags void setOpenFlags(gtk.types.PlacesOpenFlags flags): 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.
setShowConnectToServer void setShowConnectToServer(bool showConnectToServer): 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.
setShowDesktop void setShowDesktop(bool showDesktop): 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.
setShowEnterLocation void setShowEnterLocation(bool showEnterLocation): 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.
setShowOtherLocations void setShowOtherLocations(bool showOtherLocations): 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.
setShowRecent void setShowRecent(bool showRecent): 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.
setShowStarredLocation void setShowStarredLocation(bool showStarredLocation): If you enable this, you should connect to the #GtkPlacesSidebar::show-starred-location signal.
setShowTrash void setShowTrash(bool showTrash): Sets whether the sidebar should show an item for the Trash location.

Properties

_gType GType _gType [@property getter]
localOnly bool localOnly [@property getter]
localOnly bool localOnly [@property setter]
location gio.file.File location [@property getter]
location gio.file.File location [@property setter]
openFlags gtk.types.PlacesOpenFlags openFlags [@property getter]
openFlags gtk.types.PlacesOpenFlags openFlags [@property setter]
populateAll bool populateAll [@property getter]: Get populateAll property.
populateAll bool populateAll [@property setter]: Set populateAll property.
showConnectToServer bool showConnectToServer [@property getter]
showConnectToServer bool showConnectToServer [@property setter]
showDesktop bool showDesktop [@property getter]
showDesktop bool showDesktop [@property setter]
showEnterLocation bool showEnterLocation [@property getter]
showEnterLocation bool showEnterLocation [@property setter]
showOtherLocations bool showOtherLocations [@property getter]
showOtherLocations bool showOtherLocations [@property setter]
showRecent bool showRecent [@property getter]
showRecent bool showRecent [@property setter]
showStarredLocation bool showStarredLocation [@property getter]
showStarredLocation bool showStarredLocation [@property setter]
showTrash bool showTrash [@property getter]
showTrash bool showTrash [@property setter]

Static functions

_getGType GType _getGType()
builder PlacesSidebarGidBuilder builder(): Get builder for gtk.places_sidebar.PlacesSidebar

Inherited Members

From ScrolledWindow

_getGType GType _getGType()
_gType GType _gType [@property getter]
self ScrolledWindow self(): Returns this, for use in with statements.
builder ScrolledWindowGidBuilder builder(): Get builder for gtk.scrolled_window.ScrolledWindow
hadjustment gtk.adjustment.Adjustment hadjustment [@property getter]
hadjustment gtk.adjustment.Adjustment hadjustment [@property setter]
hscrollbarPolicy gtk.types.PolicyType hscrollbarPolicy [@property getter]
hscrollbarPolicy gtk.types.PolicyType hscrollbarPolicy [@property setter]
kineticScrolling bool kineticScrolling [@property getter]: Get kineticScrolling property.
kineticScrolling bool kineticScrolling [@property setter]: Set kineticScrolling property.
maxContentHeight int maxContentHeight [@property getter]: Get maxContentHeight property.
maxContentHeight int maxContentHeight [@property setter]: Set maxContentHeight property.
maxContentWidth int maxContentWidth [@property getter]: Get maxContentWidth property.
maxContentWidth int maxContentWidth [@property setter]: Set maxContentWidth property.
minContentHeight int minContentHeight [@property getter]: Get minContentHeight property.
minContentHeight int minContentHeight [@property setter]: Set minContentHeight property.
minContentWidth int minContentWidth [@property getter]: Get minContentWidth property.
minContentWidth int minContentWidth [@property setter]: Set minContentWidth property.
overlayScrolling bool overlayScrolling [@property getter]: Get overlayScrolling property.
overlayScrolling bool overlayScrolling [@property setter]: Set overlayScrolling property.
propagateNaturalHeight bool propagateNaturalHeight [@property getter]: Get propagateNaturalHeight property.
propagateNaturalHeight bool propagateNaturalHeight [@property setter]: Set propagateNaturalHeight property.
propagateNaturalWidth bool propagateNaturalWidth [@property getter]: Get propagateNaturalWidth property.
propagateNaturalWidth bool propagateNaturalWidth [@property setter]: Set propagateNaturalWidth property.
shadowType gtk.types.ShadowType shadowType [@property getter]
shadowType gtk.types.ShadowType shadowType [@property setter]
vadjustment gtk.adjustment.Adjustment vadjustment [@property getter]
vadjustment gtk.adjustment.Adjustment vadjustment [@property setter]
vscrollbarPolicy gtk.types.PolicyType vscrollbarPolicy [@property getter]
vscrollbarPolicy gtk.types.PolicyType vscrollbarPolicy [@property setter]
windowPlacement gtk.types.CornerType windowPlacement [@property getter]
windowPlacement gtk.types.CornerType windowPlacement [@property setter]
windowPlacementSet bool windowPlacementSet [@property getter]: Get windowPlacementSet property.
windowPlacementSet bool windowPlacementSet [@property setter]: Set windowPlacementSet property.
addWithViewport void addWithViewport(gtk.widget.Widget child): Used to add children without native scrolling capabilities. This is simply a convenience function; it is equivalent to adding the unscrollable child to a viewport, then adding the viewport to the scrolled window. If a child has native scrolling, use gtk.container.Container.add instead of this function.
getCaptureButtonPress bool getCaptureButtonPress(): Return whether button presses are captured during kinetic scrolling. See gtk.scrolled_window.ScrolledWindow.setCaptureButtonPress.
getHadjustment gtk.adjustment.Adjustment getHadjustment(): Returns the horizontal scrollbar’s adjustment, used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality.
getHscrollbar gtk.widget.Widget getHscrollbar(): Returns the horizontal scrollbar of scrolled_window.
getKineticScrolling bool getKineticScrolling(): Returns the specified kinetic scrolling behavior.
getMaxContentHeight int getMaxContentHeight(): Returns the maximum content height set.
getMaxContentWidth int getMaxContentWidth(): Returns the maximum content width set.
getMinContentHeight int getMinContentHeight(): Gets the minimal content height of scrolled_window, or -1 if not set.
getMinContentWidth int getMinContentWidth(): Gets the minimum content width of scrolled_window, or -1 if not set.
getOverlayScrolling bool getOverlayScrolling(): Returns whether overlay scrolling is enabled for this scrolled window.
getPlacement gtk.types.CornerType getPlacement(): Gets the placement of the contents with respect to the scrollbars for the scrolled window. See gtk.scrolled_window.ScrolledWindow.setPlacement.
getPolicy void getPolicy(gtk.types.PolicyType hscrollbarPolicy, gtk.types.PolicyType vscrollbarPolicy): Retrieves the current policy values for the horizontal and vertical scrollbars. See gtk.scrolled_window.ScrolledWindow.setPolicy.
getPropagateNaturalHeight bool getPropagateNaturalHeight(): Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height.
getPropagateNaturalWidth bool getPropagateNaturalWidth(): Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width.
getShadowType gtk.types.ShadowType getShadowType(): Gets the shadow type of the scrolled window. See gtk.scrolled_window.ScrolledWindow.setShadowType.
getVadjustment gtk.adjustment.Adjustment getVadjustment(): Returns the vertical scrollbar’s adjustment, used to connect the vertical scrollbar to the child widget’s vertical scroll functionality.
getVscrollbar gtk.widget.Widget getVscrollbar(): Returns the vertical scrollbar of scrolled_window.
setCaptureButtonPress void setCaptureButtonPress(bool captureButtonPress): Changes the behaviour of scrolled_window with regard to the initial event that possibly starts kinetic scrolling. When capture_button_press is set to true, the event is captured by the scrolled window, and then later replayed if it is meant to go to the child widget.
setHadjustment void setHadjustment(gtk.adjustment.Adjustment hadjustment): Sets the #GtkAdjustment for the horizontal scrollbar.
setKineticScrolling void setKineticScrolling(bool kineticScrolling): Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source gdk.types.InputSource.Touchscreen.
setMaxContentHeight void setMaxContentHeight(int height): Sets the maximum height that scrolled_window should keep visible. The scrolled_window will grow up to this height before it starts scrolling the content.
setMaxContentWidth void setMaxContentWidth(int width): Sets the maximum width that scrolled_window should keep visible. The scrolled_window will grow up to this width before it starts scrolling the content.
setMinContentHeight void setMinContentHeight(int height): Sets the minimum height that scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content.
setMinContentWidth void setMinContentWidth(int width): Sets the minimum width that scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content.
setOverlayScrolling void setOverlayScrolling(bool overlayScrolling): Enables or disables overlay scrolling for this scrolled window.
setPlacement void setPlacement(gtk.types.CornerType windowPlacement): Sets the placement of the contents with respect to the scrollbars for the scrolled window.
setPolicy void setPolicy(gtk.types.PolicyType hscrollbarPolicy, gtk.types.PolicyType vscrollbarPolicy): Sets the scrollbar policy for the horizontal and vertical scrollbars.
setPropagateNaturalHeight void setPropagateNaturalHeight(bool propagate): Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height.
setPropagateNaturalWidth void setPropagateNaturalWidth(bool propagate): Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width.
setShadowType void setShadowType(gtk.types.ShadowType type): Changes the type of shadow drawn around the contents of scrolled_window.
setVadjustment void setVadjustment(gtk.adjustment.Adjustment vadjustment): Sets the #GtkAdjustment for the vertical scrollbar.
unsetPlacement void unsetPlacement(): Unsets the placement of the contents with respect to the scrollbars for the scrolled window. If no window placement is set for a scrolled window, it defaults to gtk.types.CornerType.TopLeft.
connectEdgeOvershot gulong connectEdgeOvershot(T callback, Flag!"After" after): Connect to EdgeOvershot signal.
connectEdgeReached gulong connectEdgeReached(T callback, Flag!"After" after): Connect to EdgeReached signal.
connectMoveFocusOut gulong connectMoveFocusOut(T callback, Flag!"After" after): Connect to MoveFocusOut signal.
connectScrollChild gulong connectScrollChild(T callback, Flag!"After" after): Connect to ScrollChild signal.

gtk places_sidebar classes