1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gtk.PlacesSidebar;
26 
27 private import gdk.DragContext;
28 private import gio.FileIF;
29 private import gio.MountOperation;
30 private import gio.VolumeIF;
31 private import glib.ConstructionException;
32 private import glib.ListG;
33 private import glib.ListSG;
34 private import glib.Str;
35 private import gobject.ObjectG;
36 private import gobject.Signals;
37 private import gtk.ScrolledWindow;
38 private import gtk.Widget;
39 private import gtk.c.functions;
40 public  import gtk.c.types;
41 public  import gtkc.gtktypes;
42 private import std.algorithm;
43 
44 
45 /**
46  * #GtkPlacesSidebar is a widget that displays a list of frequently-used places in the
47  * file system:  the user’s home directory, the user’s bookmarks, and volumes and drives.
48  * This widget is used as a sidebar in #GtkFileChooser and may be used by file managers
49  * and similar programs.
50  * 
51  * The places sidebar displays drives and volumes, and will automatically mount
52  * or unmount them when the user selects them.
53  * 
54  * Applications can hook to various signals in the places sidebar to customize
55  * its behavior.  For example, they can add extra commands to the context menu
56  * of the sidebar.
57  * 
58  * While bookmarks are completely in control of the user, the places sidebar also
59  * allows individual applications to provide extra shortcut folders that are unique
60  * to each application.  For example, a Paint program may want to add a shortcut
61  * for a Clipart folder.  You can do this with gtk_places_sidebar_add_shortcut().
62  * 
63  * To make use of the places sidebar, an application at least needs to connect
64  * to the #GtkPlacesSidebar::open-location signal.  This is emitted when the
65  * user selects in the sidebar a location to open.  The application should also
66  * call gtk_places_sidebar_set_location() when it changes the currently-viewed
67  * location.
68  * 
69  * # CSS nodes
70  * 
71  * GtkPlacesSidebar uses a single CSS node with name placessidebar and style
72  * class .sidebar.
73  * 
74  * Among the children of the places sidebar, the following style classes can
75  * be used:
76  * - .sidebar-new-bookmark-row for the 'Add new bookmark' row
77  * - .sidebar-placeholder-row for a row that is a placeholder
78  * - .has-open-popup when a popup is open for a row
79  */
80 public class PlacesSidebar : ScrolledWindow
81 {
82 	/** the main Gtk struct */
83 	protected GtkPlacesSidebar* gtkPlacesSidebar;
84 
85 	/** Get the main Gtk struct */
86 	public GtkPlacesSidebar* getPlacesSidebarStruct(bool transferOwnership = false)
87 	{
88 		if (transferOwnership)
89 			ownedRef = false;
90 		return gtkPlacesSidebar;
91 	}
92 
93 	/** the main Gtk struct as a void* */
94 	protected override void* getStruct()
95 	{
96 		return cast(void*)gtkPlacesSidebar;
97 	}
98 
99 	/**
100 	 * Sets our main struct and passes it to the parent class.
101 	 */
102 	public this (GtkPlacesSidebar* gtkPlacesSidebar, bool ownedRef = false)
103 	{
104 		this.gtkPlacesSidebar = gtkPlacesSidebar;
105 		super(cast(GtkScrolledWindow*)gtkPlacesSidebar, ownedRef);
106 	}
107 
108 
109 	/** */
110 	public static GType getType()
111 	{
112 		return gtk_places_sidebar_get_type();
113 	}
114 
115 	/**
116 	 * Creates a new #GtkPlacesSidebar widget.
117 	 *
118 	 * The application should connect to at least the
119 	 * #GtkPlacesSidebar::open-location signal to be notified
120 	 * when the user makes a selection in the sidebar.
121 	 *
122 	 * Returns: a newly created #GtkPlacesSidebar
123 	 *
124 	 * Since: 3.10
125 	 *
126 	 * Throws: ConstructionException GTK+ fails to create the object.
127 	 */
128 	public this()
129 	{
130 		auto p = gtk_places_sidebar_new();
131 
132 		if(p is null)
133 		{
134 			throw new ConstructionException("null returned by new");
135 		}
136 
137 		this(cast(GtkPlacesSidebar*) p);
138 	}
139 
140 	/**
141 	 * Applications may want to present some folders in the places sidebar if
142 	 * they could be immediately useful to users.  For example, a drawing
143 	 * program could add a “/usr/share/clipart” location when the sidebar is
144 	 * being used in an “Insert Clipart” dialog box.
145 	 *
146 	 * This function adds the specified @location to a special place for immutable
147 	 * shortcuts.  The shortcuts are application-specific; they are not shared
148 	 * across applications, and they are not persistent.  If this function
149 	 * is called multiple times with different locations, then they are added
150 	 * to the sidebar’s list in the same order as the function is called.
151 	 *
152 	 * Params:
153 	 *     location = location to add as an application-specific shortcut
154 	 *
155 	 * Since: 3.10
156 	 */
157 	public void addShortcut(FileIF location)
158 	{
159 		gtk_places_sidebar_add_shortcut(gtkPlacesSidebar, (location is null) ? null : location.getFileStruct());
160 	}
161 
162 	/**
163 	 * Returns the value previously set with gtk_places_sidebar_set_local_only().
164 	 *
165 	 * Returns: %TRUE if the sidebar will only show local files.
166 	 *
167 	 * Since: 3.12
168 	 */
169 	public bool getLocalOnly()
170 	{
171 		return gtk_places_sidebar_get_local_only(gtkPlacesSidebar) != 0;
172 	}
173 
174 	/**
175 	 * Gets the currently selected location in the @sidebar. This can be %NULL when
176 	 * nothing is selected, for example, when gtk_places_sidebar_set_location() has
177 	 * been called with a location that is not among the sidebar’s list of places to
178 	 * show.
179 	 *
180 	 * You can use this function to get the selection in the @sidebar.  Also, if you
181 	 * connect to the #GtkPlacesSidebar::populate-popup signal, you can use this
182 	 * function to get the location that is being referred to during the callbacks
183 	 * for your menu items.
184 	 *
185 	 * Returns: a #GFile with the selected location, or
186 	 *     %NULL if nothing is visually selected.
187 	 *
188 	 * Since: 3.10
189 	 */
190 	public FileIF getLocation()
191 	{
192 		auto p = gtk_places_sidebar_get_location(gtkPlacesSidebar);
193 
194 		if(p is null)
195 		{
196 			return null;
197 		}
198 
199 		return ObjectG.getDObject!(FileIF)(cast(GFile*) p, true);
200 	}
201 
202 	/**
203 	 * This function queries the bookmarks added by the user to the places sidebar,
204 	 * and returns one of them.  This function is used by #GtkFileChooser to implement
205 	 * the “Alt-1”, “Alt-2”, etc. shortcuts, which activate the cooresponding bookmark.
206 	 *
207 	 * Params:
208 	 *     n = index of the bookmark to query
209 	 *
210 	 * Returns: The bookmark specified by the index @n, or
211 	 *     %NULL if no such index exist.  Note that the indices start at 0, even though
212 	 *     the file chooser starts them with the keyboard shortcut "Alt-1".
213 	 *
214 	 * Since: 3.10
215 	 */
216 	public FileIF getNthBookmark(int n)
217 	{
218 		auto p = gtk_places_sidebar_get_nth_bookmark(gtkPlacesSidebar, n);
219 
220 		if(p is null)
221 		{
222 			return null;
223 		}
224 
225 		return ObjectG.getDObject!(FileIF)(cast(GFile*) p, true);
226 	}
227 
228 	/**
229 	 * Gets the open flags.
230 	 *
231 	 * Returns: the #GtkPlacesOpenFlags of @sidebar
232 	 *
233 	 * Since: 3.10
234 	 */
235 	public GtkPlacesOpenFlags getOpenFlags()
236 	{
237 		return gtk_places_sidebar_get_open_flags(gtkPlacesSidebar);
238 	}
239 
240 	/**
241 	 * Returns the value previously set with gtk_places_sidebar_set_show_connect_to_server()
242 	 *
243 	 * Deprecated: It is recommended to group this functionality with the drives
244 	 * and network location under the new 'Other Location' item
245 	 *
246 	 * Returns: %TRUE if the sidebar will display a “Connect to Server” item.
247 	 */
248 	public bool getShowConnectToServer()
249 	{
250 		return gtk_places_sidebar_get_show_connect_to_server(gtkPlacesSidebar) != 0;
251 	}
252 
253 	/**
254 	 * Returns the value previously set with gtk_places_sidebar_set_show_desktop()
255 	 *
256 	 * Returns: %TRUE if the sidebar will display a builtin shortcut to the desktop folder.
257 	 *
258 	 * Since: 3.10
259 	 */
260 	public bool getShowDesktop()
261 	{
262 		return gtk_places_sidebar_get_show_desktop(gtkPlacesSidebar) != 0;
263 	}
264 
265 	/**
266 	 * Returns the value previously set with gtk_places_sidebar_set_show_enter_location()
267 	 *
268 	 * Returns: %TRUE if the sidebar will display an “Enter Location” item.
269 	 *
270 	 * Since: 3.14
271 	 */
272 	public bool getShowEnterLocation()
273 	{
274 		return gtk_places_sidebar_get_show_enter_location(gtkPlacesSidebar) != 0;
275 	}
276 
277 	/**
278 	 * Returns the value previously set with gtk_places_sidebar_set_show_other_locations()
279 	 *
280 	 * Returns: %TRUE if the sidebar will display an “Other Locations” item.
281 	 *
282 	 * Since: 3.18
283 	 */
284 	public bool getShowOtherLocations()
285 	{
286 		return gtk_places_sidebar_get_show_other_locations(gtkPlacesSidebar) != 0;
287 	}
288 
289 	/**
290 	 * Returns the value previously set with gtk_places_sidebar_set_show_recent()
291 	 *
292 	 * Returns: %TRUE if the sidebar will display a builtin shortcut for recent files
293 	 *
294 	 * Since: 3.18
295 	 */
296 	public bool getShowRecent()
297 	{
298 		return gtk_places_sidebar_get_show_recent(gtkPlacesSidebar) != 0;
299 	}
300 
301 	/**
302 	 * Returns the value previously set with gtk_places_sidebar_set_show_starred_location()
303 	 *
304 	 * Returns: %TRUE if the sidebar will display a Starred item.
305 	 *
306 	 * Since: 3.22.26
307 	 */
308 	public bool getShowStarredLocation()
309 	{
310 		return gtk_places_sidebar_get_show_starred_location(gtkPlacesSidebar) != 0;
311 	}
312 
313 	/**
314 	 * Returns the value previously set with gtk_places_sidebar_set_show_trash()
315 	 *
316 	 * Returns: %TRUE if the sidebar will display a “Trash” item.
317 	 *
318 	 * Since: 3.18
319 	 */
320 	public bool getShowTrash()
321 	{
322 		return gtk_places_sidebar_get_show_trash(gtkPlacesSidebar) != 0;
323 	}
324 
325 	/**
326 	 * Gets the list of shortcuts.
327 	 *
328 	 * Returns: A #GSList of #GFile of the locations that have been added as
329 	 *     application-specific shortcuts with gtk_places_sidebar_add_shortcut().
330 	 *     To free this list, you can use
331 	 *     |[<!-- language="C" -->
332 	 *     g_slist_free_full (list, (GDestroyNotify) g_object_unref);
333 	 *     ]|
334 	 *
335 	 * Since: 3.10
336 	 */
337 	public ListSG listShortcuts()
338 	{
339 		auto p = gtk_places_sidebar_list_shortcuts(gtkPlacesSidebar);
340 
341 		if(p is null)
342 		{
343 			return null;
344 		}
345 
346 		return new ListSG(cast(GSList*) p, true);
347 	}
348 
349 	/**
350 	 * Removes an application-specific shortcut that has been previously been
351 	 * inserted with gtk_places_sidebar_add_shortcut().  If the @location is not a
352 	 * shortcut in the sidebar, then nothing is done.
353 	 *
354 	 * Params:
355 	 *     location = location to remove
356 	 *
357 	 * Since: 3.10
358 	 */
359 	public void removeShortcut(FileIF location)
360 	{
361 		gtk_places_sidebar_remove_shortcut(gtkPlacesSidebar, (location is null) ? null : location.getFileStruct());
362 	}
363 
364 	/**
365 	 * Make the GtkPlacesSidebar show drop targets, so it can show the available
366 	 * drop targets and a "new bookmark" row. This improves the Drag-and-Drop
367 	 * experience of the user and allows applications to show all available
368 	 * drop targets at once.
369 	 *
370 	 * This needs to be called when the application is aware of an ongoing drag
371 	 * that might target the sidebar. The drop-targets-visible state will be unset
372 	 * automatically if the drag finishes in the GtkPlacesSidebar. You only need
373 	 * to unset the state when the drag ends on some other widget on your application.
374 	 *
375 	 * Params:
376 	 *     visible = whether to show the valid targets or not.
377 	 *     context = drag context used to ask the source about the action that wants to
378 	 *         perform, so hints are more accurate.
379 	 *
380 	 * Since: 3.18
381 	 */
382 	public void setDropTargetsVisible(bool visible, DragContext context)
383 	{
384 		gtk_places_sidebar_set_drop_targets_visible(gtkPlacesSidebar, visible, (context is null) ? null : context.getDragContextStruct());
385 	}
386 
387 	/**
388 	 * Sets whether the @sidebar should only show local files.
389 	 *
390 	 * Params:
391 	 *     localOnly = whether to show only local files
392 	 *
393 	 * Since: 3.12
394 	 */
395 	public void setLocalOnly(bool localOnly)
396 	{
397 		gtk_places_sidebar_set_local_only(gtkPlacesSidebar, localOnly);
398 	}
399 
400 	/**
401 	 * Sets the location that is being shown in the widgets surrounding the
402 	 * @sidebar, for example, in a folder view in a file manager.  In turn, the
403 	 * @sidebar will highlight that location if it is being shown in the list of
404 	 * places, or it will unhighlight everything if the @location is not among the
405 	 * places in the list.
406 	 *
407 	 * Params:
408 	 *     location = location to select, or %NULL for no current path
409 	 *
410 	 * Since: 3.10
411 	 */
412 	public void setLocation(FileIF location)
413 	{
414 		gtk_places_sidebar_set_location(gtkPlacesSidebar, (location is null) ? null : location.getFileStruct());
415 	}
416 
417 	/**
418 	 * Sets the way in which the calling application can open new locations from
419 	 * the places sidebar.  For example, some applications only open locations
420 	 * “directly” into their main view, while others may support opening locations
421 	 * in a new notebook tab or a new window.
422 	 *
423 	 * This function is used to tell the places @sidebar about the ways in which the
424 	 * application can open new locations, so that the sidebar can display (or not)
425 	 * the “Open in new tab” and “Open in new window” menu items as appropriate.
426 	 *
427 	 * When the #GtkPlacesSidebar::open-location signal is emitted, its flags
428 	 * argument will be set to one of the @flags that was passed in
429 	 * gtk_places_sidebar_set_open_flags().
430 	 *
431 	 * Passing 0 for @flags will cause #GTK_PLACES_OPEN_NORMAL to always be sent
432 	 * to callbacks for the “open-location” signal.
433 	 *
434 	 * Params:
435 	 *     flags = Bitmask of modes in which the calling application can open locations
436 	 *
437 	 * Since: 3.10
438 	 */
439 	public void setOpenFlags(GtkPlacesOpenFlags flags)
440 	{
441 		gtk_places_sidebar_set_open_flags(gtkPlacesSidebar, flags);
442 	}
443 
444 	/**
445 	 * Sets whether the @sidebar should show an item for connecting to a network server;
446 	 * this is off by default. An application may want to turn this on if it implements
447 	 * a way for the user to connect to network servers directly.
448 	 *
449 	 * If you enable this, you should connect to the
450 	 * #GtkPlacesSidebar::show-connect-to-server signal.
451 	 *
452 	 * Deprecated: It is recommended to group this functionality with the drives
453 	 * and network location under the new 'Other Location' item
454 	 *
455 	 * Params:
456 	 *     showConnectToServer = whether to show an item for the Connect to Server command
457 	 *
458 	 * Since: 3.10
459 	 */
460 	public void setShowConnectToServer(bool showConnectToServer)
461 	{
462 		gtk_places_sidebar_set_show_connect_to_server(gtkPlacesSidebar, showConnectToServer);
463 	}
464 
465 	/**
466 	 * Sets whether the @sidebar should show an item for the Desktop folder.
467 	 * The default value for this option is determined by the desktop
468 	 * environment and the user’s configuration, but this function can be
469 	 * used to override it on a per-application basis.
470 	 *
471 	 * Params:
472 	 *     showDesktop = whether to show an item for the Desktop folder
473 	 *
474 	 * Since: 3.10
475 	 */
476 	public void setShowDesktop(bool showDesktop)
477 	{
478 		gtk_places_sidebar_set_show_desktop(gtkPlacesSidebar, showDesktop);
479 	}
480 
481 	/**
482 	 * Sets whether the @sidebar should show an item for entering a location;
483 	 * this is off by default. An application may want to turn this on if manually
484 	 * entering URLs is an expected user action.
485 	 *
486 	 * If you enable this, you should connect to the
487 	 * #GtkPlacesSidebar::show-enter-location signal.
488 	 *
489 	 * Params:
490 	 *     showEnterLocation = whether to show an item to enter a location
491 	 *
492 	 * Since: 3.14
493 	 */
494 	public void setShowEnterLocation(bool showEnterLocation)
495 	{
496 		gtk_places_sidebar_set_show_enter_location(gtkPlacesSidebar, showEnterLocation);
497 	}
498 
499 	/**
500 	 * Sets whether the @sidebar should show an item for the application to show
501 	 * an Other Locations view; this is off by default. When set to %TRUE, persistent
502 	 * devices such as hard drives are hidden, otherwise they are shown in the sidebar.
503 	 * An application may want to turn this on if it implements a way for the user to
504 	 * see and interact with drives and network servers directly.
505 	 *
506 	 * If you enable this, you should connect to the
507 	 * #GtkPlacesSidebar::show-other-locations signal.
508 	 *
509 	 * Params:
510 	 *     showOtherLocations = whether to show an item for the Other Locations view
511 	 *
512 	 * Since: 3.18
513 	 */
514 	public void setShowOtherLocations(bool showOtherLocations)
515 	{
516 		gtk_places_sidebar_set_show_other_locations(gtkPlacesSidebar, showOtherLocations);
517 	}
518 
519 	/**
520 	 * Sets whether the @sidebar should show an item for recent files.
521 	 * The default value for this option is determined by the desktop
522 	 * environment, but this function can be used to override it on a
523 	 * per-application basis.
524 	 *
525 	 * Params:
526 	 *     showRecent = whether to show an item for recent files
527 	 *
528 	 * Since: 3.18
529 	 */
530 	public void setShowRecent(bool showRecent)
531 	{
532 		gtk_places_sidebar_set_show_recent(gtkPlacesSidebar, showRecent);
533 	}
534 
535 	/**
536 	 * If you enable this, you should connect to the
537 	 * #GtkPlacesSidebar::show-starred-location signal.
538 	 *
539 	 * Params:
540 	 *     showStarredLocation = whether to show an item for Starred files
541 	 *
542 	 * Since: 3.22.26
543 	 */
544 	public void setShowStarredLocation(bool showStarredLocation)
545 	{
546 		gtk_places_sidebar_set_show_starred_location(gtkPlacesSidebar, showStarredLocation);
547 	}
548 
549 	/**
550 	 * Sets whether the @sidebar should show an item for the Trash location.
551 	 *
552 	 * Params:
553 	 *     showTrash = whether to show an item for the Trash location
554 	 *
555 	 * Since: 3.18
556 	 */
557 	public void setShowTrash(bool showTrash)
558 	{
559 		gtk_places_sidebar_set_show_trash(gtkPlacesSidebar, showTrash);
560 	}
561 
562 	/**
563 	 * The places sidebar emits this signal when it needs to ask the application
564 	 * to pop up a menu to ask the user for which drag action to perform.
565 	 *
566 	 * Params:
567 	 *     actions = Possible drag actions that need to be asked for.
568 	 *
569 	 * Returns: the final drag action that the sidebar should pass to the drag side
570 	 *     of the drag-and-drop operation.
571 	 *
572 	 * Since: 3.10
573 	 */
574 	gulong addOnDragActionAsk(int delegate(int, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
575 	{
576 		return Signals.connect(this, "drag-action-ask", dlg, connectFlags ^ ConnectFlags.SWAPPED);
577 	}
578 
579 	/**
580 	 * When the user starts a drag-and-drop operation and the sidebar needs
581 	 * to ask the application for which drag action to perform, then the
582 	 * sidebar will emit this signal.
583 	 *
584 	 * The application can evaluate the @context for customary actions, or
585 	 * it can check the type of the files indicated by @source_file_list against the
586 	 * possible actions for the destination @dest_file.
587 	 *
588 	 * The drag action to use must be the return value of the signal handler.
589 	 *
590 	 * Params:
591 	 *     context = #GdkDragContext with information about the drag operation
592 	 *     destFile = #GFile with the tentative location that is being hovered for a drop
593 	 *     sourceFileList = List of #GFile that are being dragged
594 	 *
595 	 * Returns: The drag action to use, for example, #GDK_ACTION_COPY
596 	 *     or #GDK_ACTION_MOVE, or 0 if no action is allowed here (i.e. drops
597 	 *     are not allowed in the specified @dest_file).
598 	 *
599 	 * Since: 3.10
600 	 */
601 	gulong addOnDragActionRequested(int delegate(DragContext, FileIF, ListG, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
602 	{
603 		return Signals.connect(this, "drag-action-requested", dlg, connectFlags ^ ConnectFlags.SWAPPED);
604 	}
605 
606 	/**
607 	 * The places sidebar emits this signal when the user completes a
608 	 * drag-and-drop operation and one of the sidebar's items is the
609 	 * destination.  This item is in the @dest_file, and the
610 	 * @source_file_list has the list of files that are dropped into it and
611 	 * which should be copied/moved/etc. based on the specified @action.
612 	 *
613 	 * Params:
614 	 *     destFile = Destination #GFile.
615 	 *     sourceFileList = #GList of #GFile that got dropped.
616 	 *     action = Drop action to perform.
617 	 *
618 	 * Since: 3.10
619 	 */
620 	gulong addOnDragPerformDrop(void delegate(FileIF, ListG, int, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
621 	{
622 		return Signals.connect(this, "drag-perform-drop", dlg, connectFlags ^ ConnectFlags.SWAPPED);
623 	}
624 
625 	/**
626 	 * The places sidebar emits this signal when it starts a new operation
627 	 * because the user clicked on some location that needs mounting.
628 	 * In this way the application using the #GtkPlacesSidebar can track the
629 	 * progress of the operation and, for example, show a notification.
630 	 *
631 	 * Params:
632 	 *     mountOperation = the #GMountOperation that is going to start.
633 	 *
634 	 * Since: 3.20
635 	 */
636 	gulong addOnMount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
637 	{
638 		return Signals.connect(this, "mount", dlg, connectFlags ^ ConnectFlags.SWAPPED);
639 	}
640 
641 	/**
642 	 * The places sidebar emits this signal when the user selects a location
643 	 * in it.  The calling application should display the contents of that
644 	 * location; for example, a file manager should show a list of files in
645 	 * the specified location.
646 	 *
647 	 * Params:
648 	 *     location = #GFile to which the caller should switch.
649 	 *     openFlags = a single value from #GtkPlacesOpenFlags specifying how the @location should be opened.
650 	 *
651 	 * Since: 3.10
652 	 */
653 	gulong addOnOpenLocation(void delegate(FileIF, GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
654 	{
655 		return Signals.connect(this, "open-location", dlg, connectFlags ^ ConnectFlags.SWAPPED);
656 	}
657 
658 	/**
659 	 * The places sidebar emits this signal when the user invokes a contextual
660 	 * popup on one of its items. In the signal handler, the application may
661 	 * add extra items to the menu as appropriate. For example, a file manager
662 	 * may want to add a "Properties" command to the menu.
663 	 *
664 	 * It is not necessary to store the @selected_item for each menu item;
665 	 * during their callbacks, the application can use gtk_places_sidebar_get_location()
666 	 * to get the file to which the item refers.
667 	 *
668 	 * The @selected_item argument may be %NULL in case the selection refers to
669 	 * a volume. In this case, @selected_volume will be non-%NULL. In this case,
670 	 * the calling application will have to g_object_ref() the @selected_volume and
671 	 * keep it around to use it in the callback.
672 	 *
673 	 * The @container and all its contents are destroyed after the user
674 	 * dismisses the popup. The popup is re-created (and thus, this signal is
675 	 * emitted) every time the user activates the contextual menu.
676 	 *
677 	 * Before 3.18, the @container always was a #GtkMenu, and you were expected
678 	 * to add your items as #GtkMenuItems. Since 3.18, the popup may be implemented
679 	 * as a #GtkPopover, in which case @container will be something else, e.g. a
680 	 * #GtkBox, to which you may add #GtkModelButtons or other widgets, such as
681 	 * #GtkEntries, #GtkSpinButtons, etc. If your application can deal with this
682 	 * situation, you can set #GtkPlacesSidebar::populate-all to %TRUE to request
683 	 * that this signal is emitted for populating popovers as well.
684 	 *
685 	 * Params:
686 	 *     container = a #GtkMenu or another #GtkContainer
687 	 *     selectedItem = #GFile with the item to which
688 	 *         the popup should refer, or %NULL in the case of a @selected_volume.
689 	 *     selectedVolume = #GVolume if the selected
690 	 *         item is a volume, or %NULL if it is a file.
691 	 *
692 	 * Since: 3.10
693 	 */
694 	gulong addOnPopulatePopup(void delegate(Widget, FileIF, VolumeIF, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
695 	{
696 		return Signals.connect(this, "populate-popup", dlg, connectFlags ^ ConnectFlags.SWAPPED);
697 	}
698 
699 	/**
700 	 * The places sidebar emits this signal when it needs the calling
701 	 * application to present an way to connect directly to a network server.
702 	 * For example, the application may bring up a dialog box asking for
703 	 * a URL like "sftp://ftp.example.com".  It is up to the application to create
704 	 * the corresponding mount by using, for example, g_file_mount_enclosing_volume().
705 	 *
706 	 * Deprecated: use the #GtkPlacesSidebar::show-other-locations signal
707 	 * to connect to network servers.
708 	 */
709 	gulong addOnShowConnectToServer(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
710 	{
711 		return Signals.connect(this, "show-connect-to-server", dlg, connectFlags ^ ConnectFlags.SWAPPED);
712 	}
713 
714 	/**
715 	 * The places sidebar emits this signal when it needs the calling
716 	 * application to present an way to directly enter a location.
717 	 * For example, the application may bring up a dialog box asking for
718 	 * a URL like "http://http.example.com".
719 	 *
720 	 * Since: 3.14
721 	 */
722 	gulong addOnShowEnterLocation(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
723 	{
724 		return Signals.connect(this, "show-enter-location", dlg, connectFlags ^ ConnectFlags.SWAPPED);
725 	}
726 
727 	/**
728 	 * The places sidebar emits this signal when it needs the calling
729 	 * application to present an error message.  Most of these messages
730 	 * refer to mounting or unmounting media, for example, when a drive
731 	 * cannot be started for some reason.
732 	 *
733 	 * Params:
734 	 *     primary = primary message with a summary of the error to show.
735 	 *     secondary = secondary message with details of the error to show.
736 	 *
737 	 * Since: 3.10
738 	 */
739 	gulong addOnShowErrorMessage(void delegate(string, string, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
740 	{
741 		return Signals.connect(this, "show-error-message", dlg, connectFlags ^ ConnectFlags.SWAPPED);
742 	}
743 
744 	/**
745 	 * The places sidebar emits this signal when it needs the calling
746 	 * application to present a way to show other locations e.g. drives
747 	 * and network access points.
748 	 * For example, the application may bring up a page showing persistent
749 	 * volumes and discovered network addresses.
750 	 *
751 	 * Deprecated: use the #GtkPlacesSidebar::show-other-locations-with-flags
752 	 * which includes the open flags in order to allow the user to specify to open
753 	 * in a new tab or window, in a similar way than #GtkPlacesSidebar::open-location
754 	 *
755 	 * Since: 3.18
756 	 */
757 	gulong addOnShowOtherLocations(void delegate(PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
758 	{
759 		return Signals.connect(this, "show-other-locations", dlg, connectFlags ^ ConnectFlags.SWAPPED);
760 	}
761 
762 	/**
763 	 * The places sidebar emits this signal when it needs the calling
764 	 * application to present a way to show other locations e.g. drives
765 	 * and network access points.
766 	 * For example, the application may bring up a page showing persistent
767 	 * volumes and discovered network addresses.
768 	 *
769 	 * Params:
770 	 *     openFlags = a single value from #GtkPlacesOpenFlags specifying how it should be opened.
771 	 *
772 	 * Since: 3.20
773 	 */
774 	gulong addOnShowOtherLocationsWithFlags(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
775 	{
776 		return Signals.connect(this, "show-other-locations-with-flags", dlg, connectFlags ^ ConnectFlags.SWAPPED);
777 	}
778 
779 	/**
780 	 * The places sidebar emits this signal when it needs the calling
781 	 * application to present a way to show the starred files. In GNOME,
782 	 * starred files are implemented by setting the nao:predefined-tag-favorite
783 	 * tag in the tracker database.
784 	 *
785 	 * Since: 3.22.26
786 	 */
787 	gulong addOnShowStarredLocation(void delegate(GtkPlacesOpenFlags, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
788 	{
789 		return Signals.connect(this, "show-starred-location", dlg, connectFlags ^ ConnectFlags.SWAPPED);
790 	}
791 
792 	/**
793 	 * The places sidebar emits this signal when it starts a new operation
794 	 * because the user for example ejected some drive or unmounted a mount.
795 	 * In this way the application using the #GtkPlacesSidebar can track the
796 	 * progress of the operation and, for example, show a notification.
797 	 *
798 	 * Params:
799 	 *     mountOperation = the #GMountOperation that is going to start.
800 	 *
801 	 * Since: 3.20
802 	 */
803 	gulong addOnUnmount(void delegate(MountOperation, PlacesSidebar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
804 	{
805 		return Signals.connect(this, "unmount", dlg, connectFlags ^ ConnectFlags.SWAPPED);
806 	}
807 }