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 gio.Resource; 26 27 private import gio.InputStream; 28 private import gio.c.functions; 29 public import gio.c.types; 30 private import glib.Bytes; 31 private import glib.ConstructionException; 32 private import glib.ErrorG; 33 private import glib.GException; 34 private import glib.Str; 35 private import gobject.ObjectG; 36 public import gtkc.giotypes; 37 private import gtkd.Loader; 38 39 40 /** 41 * Applications and libraries often contain binary or textual data that is 42 * really part of the application, rather than user data. For instance 43 * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, 44 * icons, etc. These are often shipped as files in `$datadir/appname`, or 45 * manually included as literal strings in the code. 46 * 47 * The #GResource API and the [glib-compile-resources][glib-compile-resources] program 48 * provide a convenient and efficient alternative to this which has some nice properties. You 49 * maintain the files as normal files, so its easy to edit them, but during the build the files 50 * are combined into a binary bundle that is linked into the executable. This means that loading 51 * the resource files are efficient (as they are already in memory, shared with other instances) and 52 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It 53 * also makes it easier to create relocatable applications. 54 * 55 * Resource files can also be marked as compressed. Such files will be included in the resource bundle 56 * in a compressed form, but will be automatically uncompressed when the resource is used. This 57 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. 58 * 59 * Resource files can also be marked to be preprocessed, by setting the value of the 60 * `preprocess` attribute to a comma-separated list of preprocessing options. 61 * The only options currently supported are: 62 * 63 * `xml-stripblanks` which will use the xmllint command 64 * to strip ignorable whitespace from the XML file. For this to work, 65 * the `XMLLINT` environment variable must be set to the full path to 66 * the xmllint executable, or xmllint must be in the `PATH`; otherwise 67 * the preprocessing step is skipped. 68 * 69 * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert 70 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside 71 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata 72 * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be 73 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will 74 * abort. 75 * 76 * Resource files will be exported in the GResource namespace using the 77 * combination of the given `prefix` and the filename from the `file` element. 78 * The `alias` attribute can be used to alter the filename to expose them at a 79 * different location in the resource namespace. Typically, this is used to 80 * include files from a different source directory without exposing the source 81 * directory in the resource namespace, as in the example below. 82 * 83 * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program 84 * which takes an XML file that describes the bundle, and a set of files that the XML references. These 85 * are combined into a binary resource bundle. 86 * 87 * An example resource description: 88 * |[ 89 * <?xml version="1.0" encoding="UTF-8"?> 90 * <gresources> 91 * <gresource prefix="/org/gtk/Example"> 92 * <file>data/splashscreen.png</file> 93 * <file compressed="true">dialog.ui</file> 94 * <file preprocess="xml-stripblanks">menumarkup.xml</file> 95 * <file alias="example.css">data/example.css</file> 96 * </gresource> 97 * </gresources> 98 * ]| 99 * 100 * This will create a resource bundle with the following files: 101 * |[ 102 * /org/gtk/Example/data/splashscreen.png 103 * /org/gtk/Example/dialog.ui 104 * /org/gtk/Example/menumarkup.xml 105 * /org/gtk/Example/example.css 106 * ]| 107 * 108 * Note that all resources in the process share the same namespace, so use Java-style 109 * path prefixes (like in the above example) to avoid conflicts. 110 * 111 * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a 112 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and 113 * --generate-header arguments to create a source file and header to link directly into your application. 114 * This will generate `get_resource()`, `register_resource()` and 115 * `unregister_resource()` functions, prefixed by the `--c-name` argument passed 116 * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns 117 * the generated #GResource object. The register and unregister functions 118 * register the resource so its files can be accessed using 119 * g_resources_lookup_data(). 120 * 121 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by 122 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer 123 * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access 124 * the resource data. 125 * 126 * Some higher-level APIs, such as #GtkApplication, will automatically load 127 * resources from certain well-known paths in the resource namespace as a 128 * convenience. See the documentation for those APIs for details. 129 * 130 * There are two forms of the generated source, the default version uses the compiler support for constructor 131 * and destructor functions (where available) to automatically create and register the #GResource on startup 132 * or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created 133 * instead. This requires an explicit initialization call in your application/library, but it works on all platforms, 134 * even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) 135 * 136 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries 137 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away 138 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses 139 * are for your own resources, and resource data is often used once, during parsing, and then released. 140 * 141 * When debugging a program or testing a change to an installed version, it is often useful to be able to 142 * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing 143 * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay 144 * resources with replacements from the filesystem. It is a colon-separated list of substitutions to perform 145 * during resource lookups. 146 * 147 * A substitution has the form 148 * 149 * |[ 150 * /org/gtk/libgtk=/home/desrt/gtk-overlay 151 * ]| 152 * 153 * The part before the `=` is the resource subpath for which the overlay applies. The part after is a 154 * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the 155 * equivalent names. 156 * 157 * In the example above, if an application tried to load a resource with the resource path 158 * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path 159 * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an 160 * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in 161 * version will be used instead. Whiteouts are not currently supported. 162 * 163 * Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after 164 * the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the 165 * location of a single resource with an individual file. 166 * 167 * Since: 2.32 168 */ 169 public class Resource 170 { 171 /** the main Gtk struct */ 172 protected GResource* gResource; 173 protected bool ownedRef; 174 175 /** Get the main Gtk struct */ 176 public GResource* getResourceStruct(bool transferOwnership = false) 177 { 178 if (transferOwnership) 179 ownedRef = false; 180 return gResource; 181 } 182 183 /** the main Gtk struct as a void* */ 184 protected void* getStruct() 185 { 186 return cast(void*)gResource; 187 } 188 189 /** 190 * Sets our main struct and passes it to the parent class. 191 */ 192 public this (GResource* gResource, bool ownedRef = false) 193 { 194 this.gResource = gResource; 195 this.ownedRef = ownedRef; 196 } 197 198 ~this () 199 { 200 if ( Linker.isLoaded(LIBRARY_GIO) && ownedRef ) 201 g_resource_unref(gResource); 202 } 203 204 205 /** */ 206 public static GType getType() 207 { 208 return g_resource_get_type(); 209 } 210 211 /** 212 * Creates a GResource from a reference to the binary resource bundle. 213 * This will keep a reference to @data while the resource lives, so 214 * the data should not be modified or freed. 215 * 216 * If you want to use this resource in the global resource namespace you need 217 * to register it with g_resources_register(). 218 * 219 * Note: @data must be backed by memory that is at least pointer aligned. 220 * Otherwise this function will internally create a copy of the memory since 221 * GLib 2.56, or in older versions fail and exit the process. 222 * 223 * Params: 224 * data = A #GBytes 225 * 226 * Returns: a new #GResource, or %NULL on error 227 * 228 * Since: 2.32 229 * 230 * Throws: GException on failure. 231 * Throws: ConstructionException GTK+ fails to create the object. 232 */ 233 public this(Bytes data) 234 { 235 GError* err = null; 236 237 auto p = g_resource_new_from_data((data is null) ? null : data.getBytesStruct(), &err); 238 239 if (err !is null) 240 { 241 throw new GException( new ErrorG(err) ); 242 } 243 244 if(p is null) 245 { 246 throw new ConstructionException("null returned by new_from_data"); 247 } 248 249 this(cast(GResource*) p); 250 } 251 252 /** 253 * Registers the resource with the process-global set of resources. 254 * Once a resource is registered the files in it can be accessed 255 * with the global resource lookup functions like g_resources_lookup_data(). 256 * 257 * Params: 258 * resource = A #GResource 259 * 260 * Since: 2.32 261 */ 262 public static void register(Resource resource) 263 { 264 g_resources_register((resource is null) ? null : resource.getResourceStruct()); 265 } 266 267 /** 268 * Unregisters the resource from the process-global set of resources. 269 * 270 * Params: 271 * resource = A #GResource 272 * 273 * Since: 2.32 274 */ 275 public static void unregister(Resource resource) 276 { 277 g_resources_unregister((resource is null) ? null : resource.getResourceStruct()); 278 } 279 280 /** 281 * Returns all the names of children at the specified @path in the resource. 282 * The return result is a %NULL terminated list of strings which should 283 * be released with g_strfreev(). 284 * 285 * If @path is invalid or does not exist in the #GResource, 286 * %G_RESOURCE_ERROR_NOT_FOUND will be returned. 287 * 288 * @lookup_flags controls the behaviour of the lookup. 289 * 290 * Params: 291 * path = A pathname inside the resource 292 * lookupFlags = A #GResourceLookupFlags 293 * 294 * Returns: an array of constant strings 295 * 296 * Since: 2.32 297 * 298 * Throws: GException on failure. 299 */ 300 public string[] enumerateChildren(string path, GResourceLookupFlags lookupFlags) 301 { 302 GError* err = null; 303 304 auto retStr = g_resource_enumerate_children(gResource, Str.toStringz(path), lookupFlags, &err); 305 306 if (err !is null) 307 { 308 throw new GException( new ErrorG(err) ); 309 } 310 311 scope(exit) Str.freeStringArray(retStr); 312 return Str.toStringArray(retStr); 313 } 314 315 /** 316 * Looks for a file at the specified @path in the resource and 317 * if found returns information about it. 318 * 319 * @lookup_flags controls the behaviour of the lookup. 320 * 321 * Params: 322 * path = A pathname inside the resource 323 * lookupFlags = A #GResourceLookupFlags 324 * size = a location to place the length of the contents of the file, 325 * or %NULL if the length is not needed 326 * flags = a location to place the flags about the file, 327 * or %NULL if the length is not needed 328 * 329 * Returns: %TRUE if the file was found. %FALSE if there were errors 330 * 331 * Since: 2.32 332 * 333 * Throws: GException on failure. 334 */ 335 public bool getInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags) 336 { 337 GError* err = null; 338 339 auto p = g_resource_get_info(gResource, Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0; 340 341 if (err !is null) 342 { 343 throw new GException( new ErrorG(err) ); 344 } 345 346 return p; 347 } 348 349 /** 350 * Looks for a file at the specified @path in the resource and 351 * returns a #GBytes that lets you directly access the data in 352 * memory. 353 * 354 * The data is always followed by a zero byte, so you 355 * can safely use the data as a C string. However, that byte 356 * is not included in the size of the GBytes. 357 * 358 * For uncompressed resource files this is a pointer directly into 359 * the resource bundle, which is typically in some readonly data section 360 * in the program binary. For compressed files we allocate memory on 361 * the heap and automatically uncompress the data. 362 * 363 * @lookup_flags controls the behaviour of the lookup. 364 * 365 * Params: 366 * path = A pathname inside the resource 367 * lookupFlags = A #GResourceLookupFlags 368 * 369 * Returns: #GBytes or %NULL on error. 370 * Free the returned object with g_bytes_unref() 371 * 372 * Since: 2.32 373 * 374 * Throws: GException on failure. 375 */ 376 public Bytes lookupData(string path, GResourceLookupFlags lookupFlags) 377 { 378 GError* err = null; 379 380 auto p = g_resource_lookup_data(gResource, Str.toStringz(path), lookupFlags, &err); 381 382 if (err !is null) 383 { 384 throw new GException( new ErrorG(err) ); 385 } 386 387 if(p is null) 388 { 389 return null; 390 } 391 392 return new Bytes(cast(GBytes*) p, true); 393 } 394 395 /** 396 * Looks for a file at the specified @path in the resource and 397 * returns a #GInputStream that lets you read the data. 398 * 399 * @lookup_flags controls the behaviour of the lookup. 400 * 401 * Params: 402 * path = A pathname inside the resource 403 * lookupFlags = A #GResourceLookupFlags 404 * 405 * Returns: #GInputStream or %NULL on error. 406 * Free the returned object with g_object_unref() 407 * 408 * Since: 2.32 409 * 410 * Throws: GException on failure. 411 */ 412 public InputStream openStream(string path, GResourceLookupFlags lookupFlags) 413 { 414 GError* err = null; 415 416 auto p = g_resource_open_stream(gResource, Str.toStringz(path), lookupFlags, &err); 417 418 if (err !is null) 419 { 420 throw new GException( new ErrorG(err) ); 421 } 422 423 if(p is null) 424 { 425 return null; 426 } 427 428 return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true); 429 } 430 431 alias doref = ref_; 432 /** 433 * Atomically increments the reference count of @resource by one. This 434 * function is MT-safe and may be called from any thread. 435 * 436 * Returns: The passed in #GResource 437 * 438 * Since: 2.32 439 */ 440 public Resource ref_() 441 { 442 auto p = g_resource_ref(gResource); 443 444 if(p is null) 445 { 446 return null; 447 } 448 449 return ObjectG.getDObject!(Resource)(cast(GResource*) p, true); 450 } 451 452 /** 453 * Atomically decrements the reference count of @resource by one. If the 454 * reference count drops to 0, all memory allocated by the resource is 455 * released. This function is MT-safe and may be called from any 456 * thread. 457 * 458 * Since: 2.32 459 */ 460 public void unref() 461 { 462 g_resource_unref(gResource); 463 } 464 465 /** 466 * Loads a binary resource bundle and creates a #GResource representation of it, allowing 467 * you to query it for data. 468 * 469 * If you want to use this resource in the global resource namespace you need 470 * to register it with g_resources_register(). 471 * 472 * Params: 473 * filename = the path of a filename to load, in the GLib filename encoding 474 * 475 * Returns: a new #GResource, or %NULL on error 476 * 477 * Since: 2.32 478 * 479 * Throws: GException on failure. 480 */ 481 public static Resource load(string filename) 482 { 483 GError* err = null; 484 485 auto p = g_resource_load(Str.toStringz(filename), &err); 486 487 if (err !is null) 488 { 489 throw new GException( new ErrorG(err) ); 490 } 491 492 if(p is null) 493 { 494 return null; 495 } 496 497 return ObjectG.getDObject!(Resource)(cast(GResource*) p, true); 498 } 499 500 /** 501 * Returns all the names of children at the specified @path in the set of 502 * globally registered resources. 503 * The return result is a %NULL terminated list of strings which should 504 * be released with g_strfreev(). 505 * 506 * @lookup_flags controls the behaviour of the lookup. 507 * 508 * Params: 509 * path = A pathname inside the resource 510 * lookupFlags = A #GResourceLookupFlags 511 * 512 * Returns: an array of constant strings 513 * 514 * Since: 2.32 515 * 516 * Throws: GException on failure. 517 */ 518 public static string[] resourcesEnumerateChildren(string path, GResourceLookupFlags lookupFlags) 519 { 520 GError* err = null; 521 522 auto retStr = g_resources_enumerate_children(Str.toStringz(path), lookupFlags, &err); 523 524 if (err !is null) 525 { 526 throw new GException( new ErrorG(err) ); 527 } 528 529 scope(exit) Str.freeStringArray(retStr); 530 return Str.toStringArray(retStr); 531 } 532 533 /** 534 * Looks for a file at the specified @path in the set of 535 * globally registered resources and if found returns information about it. 536 * 537 * @lookup_flags controls the behaviour of the lookup. 538 * 539 * Params: 540 * path = A pathname inside the resource 541 * lookupFlags = A #GResourceLookupFlags 542 * size = a location to place the length of the contents of the file, 543 * or %NULL if the length is not needed 544 * flags = a location to place the #GResourceFlags about the file, 545 * or %NULL if the flags are not needed 546 * 547 * Returns: %TRUE if the file was found. %FALSE if there were errors 548 * 549 * Since: 2.32 550 * 551 * Throws: GException on failure. 552 */ 553 public static bool resourcesGetInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags) 554 { 555 GError* err = null; 556 557 auto p = g_resources_get_info(Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0; 558 559 if (err !is null) 560 { 561 throw new GException( new ErrorG(err) ); 562 } 563 564 return p; 565 } 566 567 /** 568 * Looks for a file at the specified @path in the set of 569 * globally registered resources and returns a #GBytes that 570 * lets you directly access the data in memory. 571 * 572 * The data is always followed by a zero byte, so you 573 * can safely use the data as a C string. However, that byte 574 * is not included in the size of the GBytes. 575 * 576 * For uncompressed resource files this is a pointer directly into 577 * the resource bundle, which is typically in some readonly data section 578 * in the program binary. For compressed files we allocate memory on 579 * the heap and automatically uncompress the data. 580 * 581 * @lookup_flags controls the behaviour of the lookup. 582 * 583 * Params: 584 * path = A pathname inside the resource 585 * lookupFlags = A #GResourceLookupFlags 586 * 587 * Returns: #GBytes or %NULL on error. 588 * Free the returned object with g_bytes_unref() 589 * 590 * Since: 2.32 591 * 592 * Throws: GException on failure. 593 */ 594 public static Bytes resourcesLookupData(string path, GResourceLookupFlags lookupFlags) 595 { 596 GError* err = null; 597 598 auto p = g_resources_lookup_data(Str.toStringz(path), lookupFlags, &err); 599 600 if (err !is null) 601 { 602 throw new GException( new ErrorG(err) ); 603 } 604 605 if(p is null) 606 { 607 return null; 608 } 609 610 return new Bytes(cast(GBytes*) p, true); 611 } 612 613 /** 614 * Looks for a file at the specified @path in the set of 615 * globally registered resources and returns a #GInputStream 616 * that lets you read the data. 617 * 618 * @lookup_flags controls the behaviour of the lookup. 619 * 620 * Params: 621 * path = A pathname inside the resource 622 * lookupFlags = A #GResourceLookupFlags 623 * 624 * Returns: #GInputStream or %NULL on error. 625 * Free the returned object with g_object_unref() 626 * 627 * Since: 2.32 628 * 629 * Throws: GException on failure. 630 */ 631 public static InputStream resourcesOpenStream(string path, GResourceLookupFlags lookupFlags) 632 { 633 GError* err = null; 634 635 auto p = g_resources_open_stream(Str.toStringz(path), lookupFlags, &err); 636 637 if (err !is null) 638 { 639 throw new GException( new ErrorG(err) ); 640 } 641 642 if(p is null) 643 { 644 return null; 645 } 646 647 return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true); 648 } 649 }