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.FileChooserNative;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gtk.FileChooserIF;
31 private import gtk.FileChooserT;
32 private import gtk.NativeDialog;
33 private import gtk.Window;
34 private import gtk.c.functions;
35 public  import gtk.c.types;
36 public  import gtkc.gtktypes;
37 
38 
39 /**
40  * #GtkFileChooserNative is an abstraction of a dialog box suitable
41  * for use with “File/Open” or “File/Save as” commands. By default, this
42  * just uses a #GtkFileChooserDialog to implement the actual dialog.
43  * However, on certain platforms, such as Windows and macOS, the native platform
44  * file chooser is used instead. When the application is running in a
45  * sandboxed environment without direct filesystem access (such as Flatpak),
46  * #GtkFileChooserNative may call the proper APIs (portals) to let the user
47  * choose a file and make it available to the application.
48  * 
49  * While the API of #GtkFileChooserNative closely mirrors #GtkFileChooserDialog, the main
50  * difference is that there is no access to any #GtkWindow or #GtkWidget for the dialog.
51  * This is required, as there may not be one in the case of a platform native dialog.
52  * Showing, hiding and running the dialog is handled by the #GtkNativeDialog functions.
53  * 
54  * ## Typical usage ## {#gtkfilechoosernative-typical-usage}
55  * 
56  * In the simplest of cases, you can the following code to use
57  * #GtkFileChooserDialog to select a file for opening:
58  * 
59  * |[
60  * GtkFileChooserNative *native;
61  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
62  * gint res;
63  * 
64  * native = gtk_file_chooser_native_new ("Open File",
65  * parent_window,
66  * action,
67  * "_Open",
68  * "_Cancel");
69  * 
70  * res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
71  * if (res == GTK_RESPONSE_ACCEPT)
72  * {
73  * char *filename;
74  * GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
75  * filename = gtk_file_chooser_get_filename (chooser);
76  * open_file (filename);
77  * g_free (filename);
78  * }
79  * 
80  * g_object_unref (native);
81  * ]|
82  * 
83  * To use a dialog for saving, you can use this:
84  * 
85  * |[
86  * GtkFileChooserNative *native;
87  * GtkFileChooser *chooser;
88  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
89  * gint res;
90  * 
91  * native = gtk_file_chooser_native_new ("Save File",
92  * parent_window,
93  * action,
94  * "_Save",
95  * "_Cancel");
96  * chooser = GTK_FILE_CHOOSER (native);
97  * 
98  * gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);
99  * 
100  * if (user_edited_a_new_document)
101  * gtk_file_chooser_set_current_name (chooser,
102  * _("Untitled document"));
103  * else
104  * gtk_file_chooser_set_filename (chooser,
105  * existing_filename);
106  * 
107  * res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
108  * if (res == GTK_RESPONSE_ACCEPT)
109  * {
110  * char *filename;
111  * 
112  * filename = gtk_file_chooser_get_filename (chooser);
113  * save_to_file (filename);
114  * g_free (filename);
115  * }
116  * 
117  * g_object_unref (native);
118  * ]|
119  * 
120  * For more information on how to best set up a file dialog, see #GtkFileChooserDialog.
121  * 
122  * ## Response Codes ## {#gtkfilechooserdialognative-responses}
123  * 
124  * #GtkFileChooserNative inherits from #GtkNativeDialog, which means it
125  * will return #GTK_RESPONSE_ACCEPT if the user accepted, and
126  * #GTK_RESPONSE_CANCEL if he pressed cancel. It can also return
127  * #GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed.
128  * 
129  * ## Differences from #GtkFileChooserDialog ##  {#gtkfilechooserdialognative-differences}
130  * 
131  * There are a few things in the GtkFileChooser API that are not
132  * possible to use with #GtkFileChooserNative, as such use would
133  * prohibit the use of a native dialog.
134  * 
135  * There is no support for the signals that are emitted when the user
136  * navigates in the dialog, including:
137  * * #GtkFileChooser::current-folder-changed
138  * * #GtkFileChooser::selection-changed
139  * * #GtkFileChooser::file-activated
140  * * #GtkFileChooser::confirm-overwrite
141  * 
142  * You can also not use the methods that directly control user navigation:
143  * * gtk_file_chooser_unselect_filename()
144  * * gtk_file_chooser_select_all()
145  * * gtk_file_chooser_unselect_all()
146  * 
147  * If you need any of the above you will have to use #GtkFileChooserDialog directly.
148  * 
149  * No operations that change the the dialog work while the dialog is
150  * visible. Set all the properties that are required before showing the dialog.
151  * 
152  * ## Win32 details ## {#gtkfilechooserdialognative-win32}
153  * 
154  * On windows the IFileDialog implementation (added in Windows Vista) is
155  * used. It supports many of the features that #GtkFileChooserDialog
156  * does, but there are some things it does not handle:
157  * 
158  * * Extra widgets added with gtk_file_chooser_set_extra_widget().
159  * 
160  * * Use of custom previews by connecting to #GtkFileChooser::update-preview.
161  * 
162  * * Any #GtkFileFilter added using a mimetype or custom filter.
163  * 
164  * If any of these features are used the regular #GtkFileChooserDialog
165  * will be used in place of the native one.
166  * 
167  * ## Portal details ## {#gtkfilechooserdialognative-portal}
168  * 
169  * When the org.freedesktop.portal.FileChooser portal is available on the
170  * session bus, it is used to bring up an out-of-process file chooser. Depending
171  * on the kind of session the application is running in, this may or may not
172  * be a GTK+ file chooser. In this situation, the following things are not
173  * supported and will be silently ignored:
174  * 
175  * * Extra widgets added with gtk_file_chooser_set_extra_widget().
176  * 
177  * * Use of custom previews by connecting to #GtkFileChooser::update-preview.
178  * 
179  * * Any #GtkFileFilter added with a custom filter.
180  * 
181  * ## macOS details ## {#gtkfilechooserdialognative-macos}
182  * 
183  * On macOS the NSSavePanel and NSOpenPanel classes are used to provide native
184  * file chooser dialogs. Some features provided by #GtkFileChooserDialog are
185  * not supported:
186  * 
187  * * Extra widgets added with gtk_file_chooser_set_extra_widget(), unless the
188  * widget is an instance of GtkLabel, in which case the label text will be used
189  * to set the NSSavePanel message instance property.
190  * 
191  * * Use of custom previews by connecting to #GtkFileChooser::update-preview.
192  * 
193  * * Any #GtkFileFilter added with a custom filter.
194  * 
195  * * Shortcut folders.
196  */
197 public class FileChooserNative : NativeDialog, FileChooserIF
198 {
199 	/** the main Gtk struct */
200 	protected GtkFileChooserNative* gtkFileChooserNative;
201 
202 	/** Get the main Gtk struct */
203 	public GtkFileChooserNative* getFileChooserNativeStruct(bool transferOwnership = false)
204 	{
205 		if (transferOwnership)
206 			ownedRef = false;
207 		return gtkFileChooserNative;
208 	}
209 
210 	/** the main Gtk struct as a void* */
211 	protected override void* getStruct()
212 	{
213 		return cast(void*)gtkFileChooserNative;
214 	}
215 
216 	protected override void setStruct(GObject* obj)
217 	{
218 		gtkFileChooserNative = cast(GtkFileChooserNative*)obj;
219 		super.setStruct(obj);
220 	}
221 
222 	/**
223 	 * Sets our main struct and passes it to the parent class.
224 	 */
225 	public this (GtkFileChooserNative* gtkFileChooserNative, bool ownedRef = false)
226 	{
227 		this.gtkFileChooserNative = gtkFileChooserNative;
228 		super(cast(GtkNativeDialog*)gtkFileChooserNative, ownedRef);
229 	}
230 
231 	// add the FileChooser capabilities
232 	mixin FileChooserT!(GtkFileChooserNative);
233 
234 
235 	/** */
236 	public static GType getType()
237 	{
238 		return gtk_file_chooser_native_get_type();
239 	}
240 
241 	/**
242 	 * Creates a new #GtkFileChooserNative.
243 	 *
244 	 * Params:
245 	 *     title = Title of the native, or %NULL
246 	 *     parent = Transient parent of the native, or %NULL
247 	 *     action = Open or save mode for the dialog
248 	 *     acceptLabel = text to go in the accept button, or %NULL for the default
249 	 *     cancelLabel = text to go in the cancel button, or %NULL for the default
250 	 *
251 	 * Returns: a new #GtkFileChooserNative
252 	 *
253 	 * Since: 3.20
254 	 *
255 	 * Throws: ConstructionException GTK+ fails to create the object.
256 	 */
257 	public this(string title, Window parent, GtkFileChooserAction action, string acceptLabel, string cancelLabel)
258 	{
259 		auto p = gtk_file_chooser_native_new(Str.toStringz(title), (parent is null) ? null : parent.getWindowStruct(), action, Str.toStringz(acceptLabel), Str.toStringz(cancelLabel));
260 
261 		if(p is null)
262 		{
263 			throw new ConstructionException("null returned by new");
264 		}
265 
266 		this(cast(GtkFileChooserNative*) p, true);
267 	}
268 
269 	/**
270 	 * Retrieves the custom label text for the accept button.
271 	 *
272 	 * Returns: The custom label, or %NULL for the default. This string
273 	 *     is owned by GTK+ and should not be modified or freed
274 	 *
275 	 * Since: 3.20
276 	 */
277 	public string getAcceptLabel()
278 	{
279 		return Str.toString(gtk_file_chooser_native_get_accept_label(gtkFileChooserNative));
280 	}
281 
282 	/**
283 	 * Retrieves the custom label text for the cancel button.
284 	 *
285 	 * Returns: The custom label, or %NULL for the default. This string
286 	 *     is owned by GTK+ and should not be modified or freed
287 	 *
288 	 * Since: 3.20
289 	 */
290 	public string getCancelLabel()
291 	{
292 		return Str.toString(gtk_file_chooser_native_get_cancel_label(gtkFileChooserNative));
293 	}
294 
295 	/**
296 	 * Sets the custom label text for the accept button.
297 	 *
298 	 * If characters in @label are preceded by an underscore, they are underlined.
299 	 * If you need a literal underscore character in a label, use “__” (two
300 	 * underscores). The first underlined character represents a keyboard
301 	 * accelerator called a mnemonic.
302 	 * Pressing Alt and that key activates the button.
303 	 *
304 	 * Params:
305 	 *     acceptLabel = custom label or %NULL for the default
306 	 *
307 	 * Since: 3.20
308 	 */
309 	public void setAcceptLabel(string acceptLabel)
310 	{
311 		gtk_file_chooser_native_set_accept_label(gtkFileChooserNative, Str.toStringz(acceptLabel));
312 	}
313 
314 	/**
315 	 * Sets the custom label text for the cancel button.
316 	 *
317 	 * If characters in @label are preceded by an underscore, they are underlined.
318 	 * If you need a literal underscore character in a label, use “__” (two
319 	 * underscores). The first underlined character represents a keyboard
320 	 * accelerator called a mnemonic.
321 	 * Pressing Alt and that key activates the button.
322 	 *
323 	 * Params:
324 	 *     cancelLabel = custom label or %NULL for the default
325 	 *
326 	 * Since: 3.20
327 	 */
328 	public void setCancelLabel(string cancelLabel)
329 	{
330 		gtk_file_chooser_native_set_cancel_label(gtkFileChooserNative, Str.toStringz(cancelLabel));
331 	}
332 }