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 }