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.FileChooserDialog;
26 
27 private import glib.ConstructionException;
28 private import gtk.Dialog;
29 private import gtk.FileChooserIF;
30 private import gtk.FileChooserT;
31 private import gtk.Window;
32 private import gtk.c.functions;
33 public  import gtk.c.types;
34 public  import gtkc.gtktypes;
35 
36 
37 /**
38  * #GtkFileChooserDialog is a dialog box suitable for use with
39  * “File/Open” or “File/Save as” commands.  This widget works by
40  * putting a #GtkFileChooserWidget inside a #GtkDialog.  It exposes
41  * the #GtkFileChooser interface, so you can use all of the
42  * #GtkFileChooser functions on the file chooser dialog as well as
43  * those for #GtkDialog.
44  * 
45  * Note that #GtkFileChooserDialog does not have any methods of its
46  * own.  Instead, you should use the functions that work on a
47  * #GtkFileChooser.
48  * 
49  * If you want to integrate well with the platform you should use the
50  * #GtkFileChooserNative API, which will use a platform-specific
51  * dialog if available and fall back to GtkFileChooserDialog
52  * otherwise.
53  * 
54  * ## Typical usage ## {#gtkfilechooser-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  * GtkWidget *dialog;
61  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
62  * gint res;
63  * 
64  * dialog = gtk_file_chooser_dialog_new ("Open File",
65  * parent_window,
66  * action,
67  * _("_Cancel"),
68  * GTK_RESPONSE_CANCEL,
69  * _("_Open"),
70  * GTK_RESPONSE_ACCEPT,
71  * NULL);
72  * 
73  * res = gtk_dialog_run (GTK_DIALOG (dialog));
74  * if (res == GTK_RESPONSE_ACCEPT)
75  * {
76  * char *filename;
77  * GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
78  * filename = gtk_file_chooser_get_filename (chooser);
79  * open_file (filename);
80  * g_free (filename);
81  * }
82  * 
83  * gtk_widget_destroy (dialog);
84  * ]|
85  * 
86  * To use a dialog for saving, you can use this:
87  * 
88  * |[
89  * GtkWidget *dialog;
90  * GtkFileChooser *chooser;
91  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
92  * gint res;
93  * 
94  * dialog = gtk_file_chooser_dialog_new ("Save File",
95  * parent_window,
96  * action,
97  * _("_Cancel"),
98  * GTK_RESPONSE_CANCEL,
99  * _("_Save"),
100  * GTK_RESPONSE_ACCEPT,
101  * NULL);
102  * chooser = GTK_FILE_CHOOSER (dialog);
103  * 
104  * gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);
105  * 
106  * if (user_edited_a_new_document)
107  * gtk_file_chooser_set_current_name (chooser,
108  * _("Untitled document"));
109  * else
110  * gtk_file_chooser_set_filename (chooser,
111  * existing_filename);
112  * 
113  * res = gtk_dialog_run (GTK_DIALOG (dialog));
114  * if (res == GTK_RESPONSE_ACCEPT)
115  * {
116  * char *filename;
117  * 
118  * filename = gtk_file_chooser_get_filename (chooser);
119  * save_to_file (filename);
120  * g_free (filename);
121  * }
122  * 
123  * gtk_widget_destroy (dialog);
124  * ]|
125  * 
126  * ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up}
127  * 
128  * There are various cases in which you may need to use a #GtkFileChooserDialog:
129  * 
130  * - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
131  * 
132  * - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
133  * and suggest a name such as “Untitled” with gtk_file_chooser_set_current_name().
134  * 
135  * - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
136  * and set the existing filename with gtk_file_chooser_set_filename().
137  * 
138  * - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
139  * 
140  * Note that old versions of the file chooser’s documentation suggested
141  * using gtk_file_chooser_set_current_folder() in various
142  * situations, with the intention of letting the application
143  * suggest a reasonable default folder.  This is no longer
144  * considered to be a good policy, as now the file chooser is
145  * able to make good suggestions on its own.  In general, you
146  * should only cause the file chooser to show a specific folder
147  * when it is appropriate to use gtk_file_chooser_set_filename(),
148  * i.e. when you are doing a Save As command and you already
149  * have a file saved somewhere.
150  * 
151  * ## Response Codes ## {#gtkfilechooserdialog-responses}
152  * 
153  * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
154  * go in its action area have response codes such as
155  * #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL.  For example, you
156  * could call gtk_file_chooser_dialog_new() as follows:
157  * 
158  * |[
159  * GtkWidget *dialog;
160  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
161  * 
162  * dialog = gtk_file_chooser_dialog_new ("Open File",
163  * parent_window,
164  * action,
165  * _("_Cancel"),
166  * GTK_RESPONSE_CANCEL,
167  * _("_Open"),
168  * GTK_RESPONSE_ACCEPT,
169  * NULL);
170  * ]|
171  * 
172  * This will create buttons for “Cancel” and “Open” that use stock
173  * response identifiers from #GtkResponseType.  For most dialog
174  * boxes you can use your own custom response codes rather than the
175  * ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
176  * its “accept”-type action, e.g. an “Open” or “Save” button,
177  * will have one of the following response codes:
178  * 
179  * - #GTK_RESPONSE_ACCEPT
180  * - #GTK_RESPONSE_OK
181  * - #GTK_RESPONSE_YES
182  * - #GTK_RESPONSE_APPLY
183  * 
184  * This is because #GtkFileChooserDialog must intercept responses
185  * and switch to folders if appropriate, rather than letting the
186  * dialog terminate — the implementation uses these known
187  * response codes to know which responses can be blocked if
188  * appropriate.
189  * 
190  * To summarize, make sure you use a
191  * [stock response code][gtkfilechooserdialog-responses]
192  * when you use #GtkFileChooserDialog to ensure proper operation.
193  */
194 public class FileChooserDialog : Dialog, FileChooserIF
195 {
196 	/** the main Gtk struct */
197 	protected GtkFileChooserDialog* gtkFileChooserDialog;
198 
199 	/** Get the main Gtk struct */
200 	public GtkFileChooserDialog* getFileChooserDialogStruct(bool transferOwnership = false)
201 	{
202 		if (transferOwnership)
203 			ownedRef = false;
204 		return gtkFileChooserDialog;
205 	}
206 
207 	/** the main Gtk struct as a void* */
208 	protected override void* getStruct()
209 	{
210 		return cast(void*)gtkFileChooserDialog;
211 	}
212 
213 	protected override void setStruct(GObject* obj)
214 	{
215 		gtkFileChooserDialog = cast(GtkFileChooserDialog*)obj;
216 		super.setStruct(obj);
217 	}
218 
219 	/**
220 	 * Sets our main struct and passes it to the parent class.
221 	 */
222 	public this (GtkFileChooserDialog* gtkFileChooserDialog, bool ownedRef = false)
223 	{
224 		this.gtkFileChooserDialog = gtkFileChooserDialog;
225 		super(cast(GtkDialog*)gtkFileChooserDialog, ownedRef);
226 	}
227 
228 	// add the FileChooser capabilities
229 	mixin FileChooserT!(GtkFileChooserDialog);
230 
231 	/**
232 	 * Creates a new FileChooserDialog. This function is analogous to
233 	 * gtk_dialog_new_with_buttons().
234 	 * Since: 2.4
235 	 * Params:
236 	 *  title = Title of the dialog, or NULL
237 	 *  parent = Transient parent of the dialog, or NULL
238 	 *  action = Open or save mode for the dialog
239 	 *  buttonsText = text to go in the buttons
240 	 *  responses = response ID's for the buttons
241 	 * Throws: ConstructionException GTK+ fails to create the object.
242 	 */
243 	this(string title, Window parent, FileChooserAction action,  string[] buttonsText=null, ResponseType[] responses=null)
244 	{
245 		if ( buttonsText  is  null )
246 		{
247 			buttonsText ~= "OK";
248 			buttonsText ~= "Cancel";
249 		}
250 		if ( responses  is  null )
251 		{
252 			responses ~= ResponseType.OK;
253 			responses ~= ResponseType.CANCEL;
254 		}
255 
256 		auto p = gtk_file_chooser_dialog_new(
257 			Str.toStringz(title),
258 			(parent is null) ? null : parent.getWindowStruct(),
259 			action,
260 			null,
261 			0);
262 
263 		if(p is null)
264 		{
265 			throw new ConstructionException("null returned by gtk_file_chooser_dialog_new");
266 		}
267 
268 		this(cast(GtkFileChooserDialog*) p);
269 
270 		addButtons(buttonsText, responses);
271 	}
272 
273 	/**
274 	 */
275 
276 	/** */
277 	public static GType getType()
278 	{
279 		return gtk_file_chooser_dialog_get_type();
280 	}
281 }