PlacesSidebar

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 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 PlacesSidebar.addShortcut.

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 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 {

GtkPlacesSidebar* gtkPlacesSidebar;

GtkPlacesSidebar* getPlacesSidebarStruct(bool transferOwnership);

void* getStruct();

this(GtkPlacesSidebar* gtkPlacesSidebar, bool ownedRef);

static GType getType();

void addShortcut(FileIF location);

bool getLocalOnly();

FileIF getLocation();

FileIF getNthBookmark(int n);

GtkPlacesOpenFlags getOpenFlags();

bool getShowConnectToServer();

bool getShowDesktop();

bool getShowEnterLocation();

bool getShowOtherLocations();

bool getShowRecent();

bool getShowStarredLocation();

bool getShowTrash();

ListSG listShortcuts();

void removeShortcut(FileIF location);

void setDropTargetsVisible(bool visible, DragContext context);

void setLocalOnly(bool localOnly);

void setLocation(FileIF location);

void setOpenFlags(GtkPlacesOpenFlags 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 addOnDragActionAsk(int delegate(int, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnDragActionRequested(int delegate(DragContext, FileIF, ListG, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnDragPerformDrop(void delegate(FileIF, ListG, int, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnMount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnOpenLocation(void delegate(FileIF, GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnPopulatePopup(void delegate(Widget, FileIF, VolumeIF, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowConnectToServer(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowEnterLocation(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowErrorMessage(void delegate(string, string, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowOtherLocations(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowOtherLocationsWithFlags(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnShowStarredLocation(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags);

gulong addOnUnmount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags);

}

Constructors

this this(GtkPlacesSidebar* gtkPlacesSidebar, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(): Creates a new gtk.PlacesSidebar widget.

Members

Functions

addOnDragActionAsk gulong addOnDragActionAsk(int delegate(int, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnDragActionRequested gulong addOnDragActionRequested(int delegate(DragContext, FileIF, ListG, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnDragPerformDrop gulong addOnDragPerformDrop(void delegate(FileIF, ListG, int, PlacesSidebar) dlg, ConnectFlags connectFlags): 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 copied/moved/etc. based on the specified action.
addOnMount gulong addOnMount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.PlacesSidebar can track the progress of the operation and, for example, show a notification.
addOnOpenLocation gulong addOnOpenLocation(void delegate(FileIF, GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnPopulatePopup gulong addOnPopulatePopup(void delegate(Widget, FileIF, VolumeIF, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnShowConnectToServer gulong addOnShowConnectToServer(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags): 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().
addOnShowEnterLocation gulong addOnShowEnterLocation(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags): 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".
addOnShowErrorMessage gulong addOnShowErrorMessage(void delegate(string, string, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnShowOtherLocations gulong addOnShowOtherLocations(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnShowOtherLocationsWithFlags gulong addOnShowOtherLocationsWithFlags(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnShowStarredLocation gulong addOnShowStarredLocation(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.
addOnUnmount gulong addOnUnmount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags): 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.PlacesSidebar can track the progress of the operation and, for example, show a notification.
addShortcut void addShortcut(FileIF 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.
getLocalOnly bool getLocalOnly(): Returns the value previously set with PlacesSidebar.setLocalOnly.
getLocation FileIF getLocation(): Gets the currently selected location in the sidebar. This can be NULL when nothing is selected, for example, when PlacesSidebar.setLocation has been called with a location that is not among the sidebar’s list of places to show.
getNthBookmark FileIF 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 GtkPlacesOpenFlags getOpenFlags(): Gets the open flags.
getPlacesSidebarStruct GtkPlacesSidebar* getPlacesSidebarStruct(bool transferOwnership): Get the main Gtk struct
getShowConnectToServer bool getShowConnectToServer(): Returns the value previously set with PlacesSidebar.setShowConnectToServer
getShowDesktop bool getShowDesktop(): Returns the value previously set with PlacesSidebar.setShowDesktop
getShowEnterLocation bool getShowEnterLocation(): Returns the value previously set with PlacesSidebar.setShowEnterLocation
getShowOtherLocations bool getShowOtherLocations(): Returns the value previously set with PlacesSidebar.setShowOtherLocations
getShowRecent bool getShowRecent(): Returns the value previously set with PlacesSidebar.setShowRecent
getShowStarredLocation bool getShowStarredLocation(): Returns the value previously set with PlacesSidebar.setShowStarredLocation
getShowTrash bool getShowTrash(): Returns the value previously set with PlacesSidebar.setShowTrash
getStruct void* getStruct(): the main Gtk struct as a void*
listShortcuts ListSG listShortcuts(): Gets the list of shortcuts.
removeShortcut void removeShortcut(FileIF location): Removes an application-specific shortcut that has been previously been inserted with PlacesSidebar.addShortcut. If the location is not a shortcut in the sidebar, then nothing is done.
setDropTargetsVisible void setDropTargetsVisible(bool visible, 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(FileIF 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(GtkPlacesOpenFlags 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 show-starred-location signal.
setShowTrash void setShowTrash(bool showTrash): Sets whether the sidebar should show an item for the Trash location.

Static functions

getType GType getType()

Variables

gtkPlacesSidebar GtkPlacesSidebar* gtkPlacesSidebar;: the main Gtk struct

Inherited Members

From ScrolledWindow

gtkScrolledWindow GtkScrolledWindow* gtkScrolledWindow;: the main Gtk struct
getScrolledWindowStruct GtkScrolledWindow* getScrolledWindowStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
getType GType getType()
addWithViewport void addWithViewport(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 Container.add instead of this function.
getCaptureButtonPress bool getCaptureButtonPress(): Return whether button presses are captured during kinetic scrolling. See ScrolledWindow.setCaptureButtonPress.
getHadjustment Adjustment getHadjustment(): Returns the horizontal scrollbar’s adjustment, used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality.
getHscrollbar 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 GtkCornerType getPlacement(): Gets the placement of the contents with respect to the scrollbars for the scrolled window. See ScrolledWindow.setPlacement.
getPolicy void getPolicy(GtkPolicyType hscrollbarPolicy, GtkPolicyType vscrollbarPolicy): Retrieves the current policy values for the horizontal and vertical scrollbars. See 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 GtkShadowType getShadowType(): Gets the shadow type of the scrolled window. See ScrolledWindow.setShadowType.
getVadjustment Adjustment getVadjustment(): Returns the vertical scrollbar’s adjustment, used to connect the vertical scrollbar to the child widget’s vertical scroll functionality.
getVscrollbar 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(Adjustment hadjustment): Sets the gtk.Adjustment for the horizontal scrollbar.
setKineticScrolling void setKineticScrolling(bool kineticScrolling): Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source GDK_SOURCE_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(GtkCornerType windowPlacement): Sets the placement of the contents with respect to the scrollbars for the scrolled window.
setPolicy void setPolicy(GtkPolicyType hscrollbarPolicy, GtkPolicyType 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(GtkShadowType type): Changes the type of shadow drawn around the contents of scrolled_window.
setVadjustment void setVadjustment(Adjustment vadjustment): Sets the gtk.Adjustment 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_CORNER_TOP_LEFT.
addOnEdgeOvershot gulong addOnEdgeOvershot(void delegate(GtkPositionType, ScrolledWindow) dlg, ConnectFlags connectFlags): The ::edge-overshot signal is emitted whenever user initiated scrolling makes the scrolled window firmly surpass (i.e. with some edge resistance) the lower or upper limits defined by the adjustment in that orientation.
addOnEdgeReached gulong addOnEdgeReached(void delegate(GtkPositionType, ScrolledWindow) dlg, ConnectFlags connectFlags): The ::edge-reached signal is emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation.
addOnMoveFocusOut gulong addOnMoveFocusOut(void delegate(GtkDirectionType, ScrolledWindow) dlg, ConnectFlags connectFlags): The ::move-focus-out signal is a [keybinding signal]GtkBindingSignal which gets emitted when focus is moved away from the scrolled window by a keybinding. The move-focus signal is emitted with direction_type on this scrolled window’s toplevel parent in the container hierarchy. The default bindings for this signal are Ctrl + Tab to move forward and Ctrl + Shift + Tab to move backward.
addOnScrollChild gulong addOnScrollChild(bool delegate(GtkScrollType, bool, ScrolledWindow) dlg, ConnectFlags connectFlags): The ::scroll-child signal is a [keybinding signal]GtkBindingSignal which gets emitted when a keybinding that scrolls is pressed. The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself.

gtk PlacesSidebar classes

PlacesSidebar