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 * Params: 220 * data = A #GBytes 221 * 222 * Returns: a new #GResource, or %NULL on error 223 * 224 * Since: 2.32 225 * 226 * Throws: GException on failure. 227 * Throws: ConstructionException GTK+ fails to create the object. 228 */ 229 public this(Bytes data) 230 { 231 GError* err = null; 232 233 auto p = g_resource_new_from_data((data is null) ? null : data.getBytesStruct(), &err); 234 235 if (err !is null) 236 { 237 throw new GException( new ErrorG(err) ); 238 } 239 240 if(p is null) 241 { 242 throw new ConstructionException("null returned by new_from_data"); 243 } 244 245 this(cast(GResource*) p); 246 } 247 248 /** 249 * Registers the resource with the process-global set of resources. 250 * Once a resource is registered the files in it can be accessed 251 * with the global resource lookup functions like g_resources_lookup_data(). 252 * 253 * Params: 254 * resource = A #GResource 255 * 256 * Since: 2.32 257 */ 258 public static void register(Resource resource) 259 { 260 g_resources_register((resource is null) ? null : resource.getResourceStruct()); 261 } 262 263 /** 264 * Unregisters the resource from the process-global set of resources. 265 * 266 * Params: 267 * resource = A #GResource 268 * 269 * Since: 2.32 270 */ 271 public static void unregister(Resource resource) 272 { 273 g_resources_unregister((resource is null) ? null : resource.getResourceStruct()); 274 } 275 276 /** 277 * Returns all the names of children at the specified @path in the resource. 278 * The return result is a %NULL terminated list of strings which should 279 * be released with g_strfreev(). 280 * 281 * If @path is invalid or does not exist in the #GResource, 282 * %G_RESOURCE_ERROR_NOT_FOUND will be returned. 283 * 284 * @lookup_flags controls the behaviour of the lookup. 285 * 286 * Params: 287 * path = A pathname inside the resource 288 * lookupFlags = A #GResourceLookupFlags 289 * 290 * Returns: an array of constant strings 291 * 292 * Since: 2.32 293 * 294 * Throws: GException on failure. 295 */ 296 public string[] enumerateChildren(string path, GResourceLookupFlags lookupFlags) 297 { 298 GError* err = null; 299 300 auto retStr = g_resource_enumerate_children(gResource, Str.toStringz(path), lookupFlags, &err); 301 302 if (err !is null) 303 { 304 throw new GException( new ErrorG(err) ); 305 } 306 307 scope(exit) Str.freeStringArray(retStr); 308 return Str.toStringArray(retStr); 309 } 310 311 /** 312 * Looks for a file at the specified @path in the resource and 313 * if found returns information about it. 314 * 315 * @lookup_flags controls the behaviour of the lookup. 316 * 317 * Params: 318 * path = A pathname inside the resource 319 * lookupFlags = A #GResourceLookupFlags 320 * size = a location to place the length of the contents of the file, 321 * or %NULL if the length is not needed 322 * flags = a location to place the flags about the file, 323 * or %NULL if the length is not needed 324 * 325 * Returns: %TRUE if the file was found. %FALSE if there were errors 326 * 327 * Since: 2.32 328 * 329 * Throws: GException on failure. 330 */ 331 public bool getInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags) 332 { 333 GError* err = null; 334 335 auto p = g_resource_get_info(gResource, Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0; 336 337 if (err !is null) 338 { 339 throw new GException( new ErrorG(err) ); 340 } 341 342 return p; 343 } 344 345 /** 346 * Looks for a file at the specified @path in the resource and 347 * returns a #GBytes that lets you directly access the data in 348 * memory. 349 * 350 * The data is always followed by a zero byte, so you 351 * can safely use the data as a C string. However, that byte 352 * is not included in the size of the GBytes. 353 * 354 * For uncompressed resource files this is a pointer directly into 355 * the resource bundle, which is typically in some readonly data section 356 * in the program binary. For compressed files we allocate memory on 357 * the heap and automatically uncompress the data. 358 * 359 * @lookup_flags controls the behaviour of the lookup. 360 * 361 * Params: 362 * path = A pathname inside the resource 363 * lookupFlags = A #GResourceLookupFlags 364 * 365 * Returns: #GBytes or %NULL on error. 366 * Free the returned object with g_bytes_unref() 367 * 368 * Since: 2.32 369 * 370 * Throws: GException on failure. 371 */ 372 public Bytes lookupData(string path, GResourceLookupFlags lookupFlags) 373 { 374 GError* err = null; 375 376 auto p = g_resource_lookup_data(gResource, Str.toStringz(path), lookupFlags, &err); 377 378 if (err !is null) 379 { 380 throw new GException( new ErrorG(err) ); 381 } 382 383 if(p is null) 384 { 385 return null; 386 } 387 388 return new Bytes(cast(GBytes*) p, true); 389 } 390 391 /** 392 * Looks for a file at the specified @path in the resource and 393 * returns a #GInputStream that lets you read the data. 394 * 395 * @lookup_flags controls the behaviour of the lookup. 396 * 397 * Params: 398 * path = A pathname inside the resource 399 * lookupFlags = A #GResourceLookupFlags 400 * 401 * Returns: #GInputStream or %NULL on error. 402 * Free the returned object with g_object_unref() 403 * 404 * Since: 2.32 405 * 406 * Throws: GException on failure. 407 */ 408 public InputStream openStream(string path, GResourceLookupFlags lookupFlags) 409 { 410 GError* err = null; 411 412 auto p = g_resource_open_stream(gResource, Str.toStringz(path), lookupFlags, &err); 413 414 if (err !is null) 415 { 416 throw new GException( new ErrorG(err) ); 417 } 418 419 if(p is null) 420 { 421 return null; 422 } 423 424 return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true); 425 } 426 427 /** 428 * Atomically increments the reference count of @resource by one. This 429 * function is MT-safe and may be called from any thread. 430 * 431 * Returns: The passed in #GResource 432 * 433 * Since: 2.32 434 */ 435 public Resource doref() 436 { 437 auto p = g_resource_ref(gResource); 438 439 if(p is null) 440 { 441 return null; 442 } 443 444 return ObjectG.getDObject!(Resource)(cast(GResource*) p, true); 445 } 446 447 /** 448 * Atomically decrements the reference count of @resource by one. If the 449 * reference count drops to 0, all memory allocated by the resource is 450 * released. This function is MT-safe and may be called from any 451 * thread. 452 * 453 * Since: 2.32 454 */ 455 public void unref() 456 { 457 g_resource_unref(gResource); 458 } 459 460 /** 461 * Loads a binary resource bundle and creates a #GResource representation of it, allowing 462 * you to query it for data. 463 * 464 * If you want to use this resource in the global resource namespace you need 465 * to register it with g_resources_register(). 466 * 467 * Params: 468 * filename = the path of a filename to load, in the GLib filename encoding 469 * 470 * Returns: a new #GResource, or %NULL on error 471 * 472 * Since: 2.32 473 * 474 * Throws: GException on failure. 475 */ 476 public static Resource load(string filename) 477 { 478 GError* err = null; 479 480 auto p = g_resource_load(Str.toStringz(filename), &err); 481 482 if (err !is null) 483 { 484 throw new GException( new ErrorG(err) ); 485 } 486 487 if(p is null) 488 { 489 return null; 490 } 491 492 return ObjectG.getDObject!(Resource)(cast(GResource*) p, true); 493 } 494 495 /** 496 * Returns all the names of children at the specified @path in the set of 497 * globally registered resources. 498 * The return result is a %NULL terminated list of strings which should 499 * be released with g_strfreev(). 500 * 501 * @lookup_flags controls the behaviour of the lookup. 502 * 503 * Params: 504 * path = A pathname inside the resource 505 * lookupFlags = A #GResourceLookupFlags 506 * 507 * Returns: an array of constant strings 508 * 509 * Since: 2.32 510 * 511 * Throws: GException on failure. 512 */ 513 public static string[] resourcesEnumerateChildren(string path, GResourceLookupFlags lookupFlags) 514 { 515 GError* err = null; 516 517 auto retStr = g_resources_enumerate_children(Str.toStringz(path), lookupFlags, &err); 518 519 if (err !is null) 520 { 521 throw new GException( new ErrorG(err) ); 522 } 523 524 scope(exit) Str.freeStringArray(retStr); 525 return Str.toStringArray(retStr); 526 } 527 528 /** 529 * Looks for a file at the specified @path in the set of 530 * globally registered resources and if found returns information about it. 531 * 532 * @lookup_flags controls the behaviour of the lookup. 533 * 534 * Params: 535 * path = A pathname inside the resource 536 * lookupFlags = A #GResourceLookupFlags 537 * size = a location to place the length of the contents of the file, 538 * or %NULL if the length is not needed 539 * flags = a location to place the #GResourceFlags about the file, 540 * or %NULL if the flags are not needed 541 * 542 * Returns: %TRUE if the file was found. %FALSE if there were errors 543 * 544 * Since: 2.32 545 * 546 * Throws: GException on failure. 547 */ 548 public static bool resourcesGetInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags) 549 { 550 GError* err = null; 551 552 auto p = g_resources_get_info(Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0; 553 554 if (err !is null) 555 { 556 throw new GException( new ErrorG(err) ); 557 } 558 559 return p; 560 } 561 562 /** 563 * Looks for a file at the specified @path in the set of 564 * globally registered resources and returns a #GBytes that 565 * lets you directly access the data in memory. 566 * 567 * The data is always followed by a zero byte, so you 568 * can safely use the data as a C string. However, that byte 569 * is not included in the size of the GBytes. 570 * 571 * For uncompressed resource files this is a pointer directly into 572 * the resource bundle, which is typically in some readonly data section 573 * in the program binary. For compressed files we allocate memory on 574 * the heap and automatically uncompress the data. 575 * 576 * @lookup_flags controls the behaviour of the lookup. 577 * 578 * Params: 579 * path = A pathname inside the resource 580 * lookupFlags = A #GResourceLookupFlags 581 * 582 * Returns: #GBytes or %NULL on error. 583 * Free the returned object with g_bytes_unref() 584 * 585 * Since: 2.32 586 * 587 * Throws: GException on failure. 588 */ 589 public static Bytes resourcesLookupData(string path, GResourceLookupFlags lookupFlags) 590 { 591 GError* err = null; 592 593 auto p = g_resources_lookup_data(Str.toStringz(path), lookupFlags, &err); 594 595 if (err !is null) 596 { 597 throw new GException( new ErrorG(err) ); 598 } 599 600 if(p is null) 601 { 602 return null; 603 } 604 605 return new Bytes(cast(GBytes*) p, true); 606 } 607 608 /** 609 * Looks for a file at the specified @path in the set of 610 * globally registered resources and returns a #GInputStream 611 * that lets you read the data. 612 * 613 * @lookup_flags controls the behaviour of the lookup. 614 * 615 * Params: 616 * path = A pathname inside the resource 617 * lookupFlags = A #GResourceLookupFlags 618 * 619 * Returns: #GInputStream or %NULL on error. 620 * Free the returned object with g_object_unref() 621 * 622 * Since: 2.32 623 * 624 * Throws: GException on failure. 625 */ 626 public static InputStream resourcesOpenStream(string path, GResourceLookupFlags lookupFlags) 627 { 628 GError* err = null; 629 630 auto p = g_resources_open_stream(Str.toStringz(path), lookupFlags, &err); 631 632 if (err !is null) 633 { 634 throw new GException( new ErrorG(err) ); 635 } 636 637 if(p is null) 638 { 639 return null; 640 } 641 642 return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true); 643 } 644 }