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_add_shortcut().

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_set_location() 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 {}

Constructors

this
this(GtkPlacesSidebar* gtkPlacesSidebar, bool ownedRef)

Sets our main struct and passes it to the parent class.

this
this()

Creates a new #GtkPlacesSidebar 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 #GtkPlacesSidebar 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 #GtkPlacesSidebar 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 gtk_places_sidebar_set_local_only().

getLocation
FileIF getLocation()

Gets the currently selected location in the @sidebar. This can be %NULL when nothing is selected, for example, when gtk_places_sidebar_set_location() 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 gtk_places_sidebar_set_show_connect_to_server()

getShowDesktop
bool getShowDesktop()

Returns the value previously set with gtk_places_sidebar_set_show_desktop()

getShowEnterLocation
bool getShowEnterLocation()

Returns the value previously set with gtk_places_sidebar_set_show_enter_location()

getShowOtherLocations
bool getShowOtherLocations()

Returns the value previously set with gtk_places_sidebar_set_show_other_locations()

getShowRecent
bool getShowRecent()

Returns the value previously set with gtk_places_sidebar_set_show_recent()

getShowStarredLocation
bool getShowStarredLocation()

Returns the value previously set with gtk_places_sidebar_set_show_starred_location()

getShowTrash
bool getShowTrash()

Returns the value previously set with gtk_places_sidebar_set_show_trash()

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 gtk_places_sidebar_add_shortcut(). 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 #GtkPlacesSidebar::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 gtk_container_add() instead of this function.

getCaptureButtonPress
bool getCaptureButtonPress()

Return whether button presses are captured during kinetic scrolling. See gtk_scrolled_window_set_capture_button_press().

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 gtk_scrolled_window_set_placement().

getPolicy
void getPolicy(GtkPolicyType hscrollbarPolicy, GtkPolicyType vscrollbarPolicy)

Retrieves the current policy values for the horizontal and vertical scrollbars. See gtk_scrolled_window_set_policy().

getPropagateNaturalHeight
bool getPropagateNaturalHeight()

Reports whether the natural height of the child will be calculated and propagated through the scrolled windows requested natural height.

getPropagateNaturalWidth
bool getPropagateNaturalWidth()

Reports whether the natural width of the child will be calculated and propagated through the scrolled windows requested natural width.

getShadowType
GtkShadowType getShadowType()

Gets the shadow type of the scrolled window. See gtk_scrolled_window_set_shadow_type().

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 #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_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 windows requested natural height.

setPropagateNaturalWidth
void setPropagateNaturalWidth(bool propagate)

Sets whether the natural width of the child should be calculated and propagated through the scrolled windows 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 #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_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 scrolledwindow firmly surpass (ie. 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 scrolledwindow exactly reaches 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 #GtkWidget::move-focus signal is emitted with @direction_type on this scrolled windows toplevel parent in the container hierarchy. The default bindings for this signal are Tab + Ctrl and Tab + Ctrl + Shift.

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 windows child may listen to and scroll itself.

Meta