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.FileChooserT; 26 27 public import gio.FileIF; 28 public import gio.ListModelIF; 29 public import glib.ErrorG; 30 public import glib.GException; 31 public import glib.Str; 32 public import glib.c.functions; 33 public import gobject.ObjectG; 34 public import gtk.FileFilter; 35 public import gtk.c.functions; 36 public import gtk.c.types; 37 38 39 /** 40 * `GtkFileChooser` is an interface that can be implemented by file 41 * selection widgets. 42 * 43 * In GTK, the main objects that implement this interface are 44 * [class@Gtk.FileChooserWidget] and [class@Gtk.FileChooserDialog]. 45 * 46 * You do not need to write an object that implements the `GtkFileChooser` 47 * interface unless you are trying to adapt an existing file selector to 48 * expose a standard programming interface. 49 * 50 * `GtkFileChooser` allows for shortcuts to various places in the filesystem. 51 * In the default implementation these are displayed in the left pane. It 52 * may be a bit confusing at first that these shortcuts come from various 53 * sources and in various flavours, so lets explain the terminology here: 54 * 55 * - Bookmarks: are created by the user, by dragging folders from the 56 * right pane to the left pane, or by using the “Add”. Bookmarks 57 * can be renamed and deleted by the user. 58 * 59 * - Shortcuts: can be provided by the application. For example, a Paint 60 * program may want to add a shortcut for a Clipart folder. Shortcuts 61 * cannot be modified by the user. 62 * 63 * - Volumes: are provided by the underlying filesystem abstraction. They are 64 * the “roots” of the filesystem. 65 * 66 * # File Names and Encodings 67 * 68 * When the user is finished selecting files in a `GtkFileChooser`, your 69 * program can get the selected filenames as `GFile`s. 70 * 71 * # Adding options 72 * 73 * You can add extra widgets to a file chooser to provide options 74 * that are not present in the default design, by using 75 * [method@Gtk.FileChooser.add_choice]. Each choice has an identifier and 76 * a user visible label; additionally, each choice can have multiple 77 * options. If a choice has no option, it will be rendered as a 78 * check button with the given label; if a choice has options, it will 79 * be rendered as a combo box. 80 */ 81 public template FileChooserT(TStruct) 82 { 83 /** Get the main Gtk struct */ 84 public GtkFileChooser* getFileChooserStruct(bool transferOwnership = false) 85 { 86 if (transferOwnership) 87 ownedRef = false; 88 return cast(GtkFileChooser*)getStruct(); 89 } 90 91 92 /** 93 * Adds a 'choice' to the file chooser. 94 * 95 * This is typically implemented as a combobox or, for boolean choices, 96 * as a checkbutton. You can select a value using 97 * [method@Gtk.FileChooser.set_choice] before the dialog is shown, 98 * and you can obtain the user-selected value in the 99 * [signal@Gtk.Dialog::response] signal handler using 100 * [method@Gtk.FileChooser.get_choice]. 101 * 102 * Params: 103 * id = id for the added choice 104 * label = user-visible label for the added choice 105 * options = ids for the options of the choice, or %NULL for a boolean choice 106 * optionLabels = user-visible labels for the options, must be the same length as @options 107 */ 108 public void addChoice(string id, string label, string[] options, string[] optionLabels) 109 { 110 gtk_file_chooser_add_choice(getFileChooserStruct(), Str.toStringz(id), Str.toStringz(label), Str.toStringzArray(options), Str.toStringzArray(optionLabels)); 111 } 112 113 /** 114 * Adds @filter to the list of filters that the user can select between. 115 * 116 * When a filter is selected, only files that are passed by that 117 * filter are displayed. 118 * 119 * Note that the @chooser takes ownership of the filter if it is floating, 120 * so you have to ref and sink it if you want to keep a reference. 121 * 122 * Params: 123 * filter = a `GtkFileFilter` 124 */ 125 public void addFilter(FileFilter filter) 126 { 127 gtk_file_chooser_add_filter(getFileChooserStruct(), (filter is null) ? null : filter.getFileFilterStruct()); 128 } 129 130 /** 131 * Adds a folder to be displayed with the shortcut folders 132 * in a file chooser. 133 * 134 * Params: 135 * folder = a `GFile` for the folder to add 136 * 137 * Returns: %TRUE if the folder could be added successfully, 138 * %FALSE otherwise. 139 * 140 * Throws: GException on failure. 141 */ 142 public bool addShortcutFolder(FileIF folder) 143 { 144 GError* err = null; 145 146 auto __p = gtk_file_chooser_add_shortcut_folder(getFileChooserStruct(), (folder is null) ? null : folder.getFileStruct(), &err) != 0; 147 148 if (err !is null) 149 { 150 throw new GException( new ErrorG(err) ); 151 } 152 153 return __p; 154 } 155 156 /** 157 * Gets the type of operation that the file chooser is performing. 158 * 159 * Returns: the action that the file selector is performing 160 */ 161 public GtkFileChooserAction getAction() 162 { 163 return gtk_file_chooser_get_action(getFileChooserStruct()); 164 } 165 166 /** 167 * Gets the currently selected option in the 'choice' with the given ID. 168 * 169 * Params: 170 * id = the ID of the choice to get 171 * 172 * Returns: the ID of the currently selected option 173 */ 174 public string getChoice(string id) 175 { 176 return Str.toString(gtk_file_chooser_get_choice(getFileChooserStruct(), Str.toStringz(id))); 177 } 178 179 /** 180 * Gets whether file chooser will offer to create new folders. 181 * 182 * Returns: %TRUE if the Create Folder button should be displayed. 183 */ 184 public bool getCreateFolders() 185 { 186 return gtk_file_chooser_get_create_folders(getFileChooserStruct()) != 0; 187 } 188 189 /** 190 * Gets the current folder of @chooser as #GFile. 191 * 192 * Returns: the `GFile` for the current folder. 193 */ 194 public FileIF getCurrentFolder() 195 { 196 auto __p = gtk_file_chooser_get_current_folder(getFileChooserStruct()); 197 198 if(__p is null) 199 { 200 return null; 201 } 202 203 return ObjectG.getDObject!(FileIF)(cast(GFile*) __p, true); 204 } 205 206 /** 207 * Gets the current name in the file selector, as entered by the user. 208 * 209 * This is meant to be used in save dialogs, to get the currently typed 210 * filename when the file itself does not exist yet. 211 * 212 * Returns: The raw text from the file chooser’s “Name” entry. Free with 213 * g_free(). Note that this string is not a full pathname or URI; it is 214 * whatever the contents of the entry are. Note also that this string is 215 * in UTF-8 encoding, which is not necessarily the system’s encoding for 216 * filenames. 217 */ 218 public string getCurrentName() 219 { 220 auto retStr = gtk_file_chooser_get_current_name(getFileChooserStruct()); 221 222 scope(exit) Str.freeString(retStr); 223 return Str.toString(retStr); 224 } 225 226 /** 227 * Gets the `GFile` for the currently selected file in 228 * the file selector. 229 * 230 * If multiple files are selected, one of the files will be 231 * returned at random. 232 * 233 * If the file chooser is in folder mode, this function returns 234 * the selected folder. 235 * 236 * Returns: a selected `GFile`. You own the 237 * returned file; use g_object_unref() to release it. 238 */ 239 public FileIF getFile() 240 { 241 auto __p = gtk_file_chooser_get_file(getFileChooserStruct()); 242 243 if(__p is null) 244 { 245 return null; 246 } 247 248 return ObjectG.getDObject!(FileIF)(cast(GFile*) __p, true); 249 } 250 251 /** 252 * Lists all the selected files and subfolders in the current folder 253 * of @chooser as #GFile. 254 * 255 * Returns: a list model containing a `GFile` for each 256 * selected file and subfolder in the current folder. Free the returned 257 * list with g_object_unref(). 258 */ 259 public ListModelIF getFiles() 260 { 261 auto __p = gtk_file_chooser_get_files(getFileChooserStruct()); 262 263 if(__p is null) 264 { 265 return null; 266 } 267 268 return ObjectG.getDObject!(ListModelIF)(cast(GListModel*) __p, true); 269 } 270 271 /** 272 * Gets the current filter. 273 * 274 * Returns: the current filter, or %NULL 275 */ 276 public FileFilter getFilter() 277 { 278 auto __p = gtk_file_chooser_get_filter(getFileChooserStruct()); 279 280 if(__p is null) 281 { 282 return null; 283 } 284 285 return ObjectG.getDObject!(FileFilter)(cast(GtkFileFilter*) __p); 286 } 287 288 /** 289 * Gets the current set of user-selectable filters, as a list model. 290 * 291 * See [method@Gtk.FileChooser.add_filter] and 292 * [method@Gtk.FileChooser.remove_filter] for changing individual filters. 293 * 294 * You should not modify the returned list model. Future changes to 295 * @chooser may or may not affect the returned model. 296 * 297 * Returns: a `GListModel` containing the current set 298 * of user-selectable filters. 299 */ 300 public ListModelIF getFilters() 301 { 302 auto __p = gtk_file_chooser_get_filters(getFileChooserStruct()); 303 304 if(__p is null) 305 { 306 return null; 307 } 308 309 return ObjectG.getDObject!(ListModelIF)(cast(GListModel*) __p, true); 310 } 311 312 /** 313 * Gets whether multiple files can be selected in the file 314 * chooser. 315 * 316 * Returns: %TRUE if multiple files can be selected. 317 */ 318 public bool getSelectMultiple() 319 { 320 return gtk_file_chooser_get_select_multiple(getFileChooserStruct()) != 0; 321 } 322 323 /** 324 * Queries the list of shortcut folders in the file chooser. 325 * 326 * You should not modify the returned list model. Future changes to 327 * @chooser may or may not affect the returned model. 328 * 329 * Returns: A list model of `GFile`s 330 */ 331 public ListModelIF getShortcutFolders() 332 { 333 auto __p = gtk_file_chooser_get_shortcut_folders(getFileChooserStruct()); 334 335 if(__p is null) 336 { 337 return null; 338 } 339 340 return ObjectG.getDObject!(ListModelIF)(cast(GListModel*) __p, true); 341 } 342 343 /** 344 * Removes a 'choice' that has been added with gtk_file_chooser_add_choice(). 345 * 346 * Params: 347 * id = the ID of the choice to remove 348 */ 349 public void removeChoice(string id) 350 { 351 gtk_file_chooser_remove_choice(getFileChooserStruct(), Str.toStringz(id)); 352 } 353 354 /** 355 * Removes @filter from the list of filters that the user can select between. 356 * 357 * Params: 358 * filter = a `GtkFileFilter` 359 */ 360 public void removeFilter(FileFilter filter) 361 { 362 gtk_file_chooser_remove_filter(getFileChooserStruct(), (filter is null) ? null : filter.getFileFilterStruct()); 363 } 364 365 /** 366 * Removes a folder from the shortcut folders in a file chooser. 367 * 368 * Params: 369 * folder = a `GFile` for the folder to remove 370 * 371 * Returns: %TRUE if the folder could be removed successfully, 372 * %FALSE otherwise. 373 * 374 * Throws: GException on failure. 375 */ 376 public bool removeShortcutFolder(FileIF folder) 377 { 378 GError* err = null; 379 380 auto __p = gtk_file_chooser_remove_shortcut_folder(getFileChooserStruct(), (folder is null) ? null : folder.getFileStruct(), &err) != 0; 381 382 if (err !is null) 383 { 384 throw new GException( new ErrorG(err) ); 385 } 386 387 return __p; 388 } 389 390 /** 391 * Sets the type of operation that the chooser is performing. 392 * 393 * The user interface is adapted to suit the selected action. 394 * 395 * For example, an option to create a new folder might be shown 396 * if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the 397 * action is %GTK_FILE_CHOOSER_ACTION_OPEN. 398 * 399 * Params: 400 * action = the action that the file selector is performing 401 */ 402 public void setAction(GtkFileChooserAction action) 403 { 404 gtk_file_chooser_set_action(getFileChooserStruct(), action); 405 } 406 407 /** 408 * Selects an option in a 'choice' that has been added with 409 * gtk_file_chooser_add_choice(). 410 * 411 * For a boolean choice, the possible options are "true" and "false". 412 * 413 * Params: 414 * id = the ID of the choice to set 415 * option = the ID of the option to select 416 */ 417 public void setChoice(string id, string option) 418 { 419 gtk_file_chooser_set_choice(getFileChooserStruct(), Str.toStringz(id), Str.toStringz(option)); 420 } 421 422 /** 423 * Sets whether file chooser will offer to create new folders. 424 * 425 * This is only relevant if the action is not set to be 426 * %GTK_FILE_CHOOSER_ACTION_OPEN. 427 * 428 * Params: 429 * createFolders = %TRUE if the Create Folder button should be displayed 430 */ 431 public void setCreateFolders(bool createFolders) 432 { 433 gtk_file_chooser_set_create_folders(getFileChooserStruct(), createFolders); 434 } 435 436 /** 437 * Sets the current folder for @chooser from a #GFile. 438 * 439 * Params: 440 * file = the `GFile` for the new folder 441 * 442 * Returns: %TRUE if the folder could be changed successfully, %FALSE 443 * otherwise. 444 * 445 * Throws: GException on failure. 446 */ 447 public bool setCurrentFolder(FileIF file) 448 { 449 GError* err = null; 450 451 auto __p = gtk_file_chooser_set_current_folder(getFileChooserStruct(), (file is null) ? null : file.getFileStruct(), &err) != 0; 452 453 if (err !is null) 454 { 455 throw new GException( new ErrorG(err) ); 456 } 457 458 return __p; 459 } 460 461 /** 462 * Sets the current name in the file selector, as if entered 463 * by the user. 464 * 465 * Note that the name passed in here is a UTF-8 string rather 466 * than a filename. This function is meant for such uses as a 467 * suggested name in a “Save As...” dialog. You can pass 468 * “Untitled.doc” or a similarly suitable suggestion for the @name. 469 * 470 * If you want to preselect a particular existing file, you should 471 * use [method@Gtk.FileChooser.set_file] instead. 472 * 473 * Please see the documentation for those functions for an example 474 * of using [method@Gtk.FileChooser.set_current_name] as well. 475 * 476 * Params: 477 * name = the filename to use, as a UTF-8 string 478 */ 479 public void setCurrentName(string name) 480 { 481 gtk_file_chooser_set_current_name(getFileChooserStruct(), Str.toStringz(name)); 482 } 483 484 /** 485 * Sets @file as the current filename for the file chooser. 486 * 487 * This includes changing to the file’s parent folder and actually selecting 488 * the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, 489 * the file’s base name will also appear in the dialog’s file name entry. 490 * 491 * If the file name isn’t in the current folder of @chooser, then the current 492 * folder of @chooser will be changed to the folder containing @filename. 493 * 494 * Note that the file must exist, or nothing will be done except 495 * for the directory change. 496 * 497 * If you are implementing a save dialog, you should use this function if 498 * you already have a file name to which the user may save; for example, 499 * when the user opens an existing file and then does “Save As…”. If you 500 * don’t have a file name already — for example, if the user just created 501 * a new file and is saving it for the first time, do not call this function. 502 * 503 * Instead, use something similar to this: 504 * 505 * ```c 506 * static void 507 * prepare_file_chooser (GtkFileChooser *chooser, 508 * GFile *existing_file) 509 * { 510 * gboolean document_is_new = (existing_file == NULL); 511 * 512 * if (document_is_new) 513 * { 514 * GFile *default_file_for_saving = g_file_new_for_path ("./out.txt"); 515 * // the user just created a new document 516 * gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL); 517 * gtk_file_chooser_set_current_name (chooser, "Untitled document"); 518 * g_object_unref (default_file_for_saving); 519 * } 520 * else 521 * { 522 * // the user edited an existing document 523 * gtk_file_chooser_set_file (chooser, existing_file, NULL); 524 * } 525 * } 526 * ``` 527 * 528 * Params: 529 * file = the `GFile` to set as current 530 * 531 * Returns: Not useful 532 * 533 * Throws: GException on failure. 534 */ 535 public bool setFile(FileIF file) 536 { 537 GError* err = null; 538 539 auto __p = gtk_file_chooser_set_file(getFileChooserStruct(), (file is null) ? null : file.getFileStruct(), &err) != 0; 540 541 if (err !is null) 542 { 543 throw new GException( new ErrorG(err) ); 544 } 545 546 return __p; 547 } 548 549 /** 550 * Sets the current filter. 551 * 552 * Only the files that pass the filter will be displayed. 553 * If the user-selectable list of filters is non-empty, then 554 * the filter should be one of the filters in that list. 555 * 556 * Setting the current filter when the list of filters is 557 * empty is useful if you want to restrict the displayed 558 * set of files without letting the user change it. 559 * 560 * Params: 561 * filter = a `GtkFileFilter` 562 */ 563 public void setFilter(FileFilter filter) 564 { 565 gtk_file_chooser_set_filter(getFileChooserStruct(), (filter is null) ? null : filter.getFileFilterStruct()); 566 } 567 568 /** 569 * Sets whether multiple files can be selected in the file chooser. 570 * 571 * This is only relevant if the action is set to be 572 * %GTK_FILE_CHOOSER_ACTION_OPEN or 573 * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. 574 * 575 * Params: 576 * selectMultiple = %TRUE if multiple files can be selected. 577 */ 578 public void setSelectMultiple(bool selectMultiple) 579 { 580 gtk_file_chooser_set_select_multiple(getFileChooserStruct(), selectMultiple); 581 } 582 }