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