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.InitableT;
26 
27 public  import gio.Cancellable;
28 public  import gio.c.functions;
29 public  import gio.c.types;
30 public  import glib.ConstructionException;
31 public  import glib.ErrorG;
32 public  import glib.GException;
33 public  import glib.Str;
34 public  import gobject.ObjectG;
35 public  import gtkc.giotypes;
36 
37 
38 /**
39  * #GInitable is implemented by objects that can fail during
40  * initialization. If an object implements this interface then
41  * it must be initialized as the first thing after construction,
42  * either via g_initable_init() or g_async_initable_init_async()
43  * (the latter is only available if it also implements #GAsyncInitable).
44  * 
45  * If the object is not initialized, or initialization returns with an
46  * error, then all operations on the object except g_object_ref() and
47  * g_object_unref() are considered to be invalid, and have undefined
48  * behaviour. They will often fail with g_critical() or g_warning(), but
49  * this must not be relied on.
50  * 
51  * Users of objects implementing this are not intended to use
52  * the interface method directly, instead it will be used automatically
53  * in various ways. For C applications you generally just call
54  * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
55  * This will call g_initable_init() under the cover, returning %NULL and
56  * setting a #GError on failure (at which point the instance is
57  * unreferenced).
58  * 
59  * For bindings in languages where the native constructor supports
60  * exceptions the binding could check for objects implemention %GInitable
61  * during normal construction and automatically initialize them, throwing
62  * an exception on failure.
63  *
64  * Since: 2.22
65  */
66 public template InitableT(TStruct)
67 {
68 	/** Get the main Gtk struct */
69 	public GInitable* getInitableStruct(bool transferOwnership = false)
70 	{
71 		if (transferOwnership)
72 			ownedRef = false;
73 		return cast(GInitable*)getStruct();
74 	}
75 
76 
77 	/**
78 	 * Initializes the object implementing the interface.
79 	 *
80 	 * This method is intended for language bindings. If writing in C,
81 	 * g_initable_new() should typically be used instead.
82 	 *
83 	 * The object must be initialized before any real use after initial
84 	 * construction, either with this function or g_async_initable_init_async().
85 	 *
86 	 * Implementations may also support cancellation. If @cancellable is not %NULL,
87 	 * then initialization can be cancelled by triggering the cancellable object
88 	 * from another thread. If the operation was cancelled, the error
89 	 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
90 	 * the object doesn't support cancellable initialization the error
91 	 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
92 	 *
93 	 * If the object is not initialized, or initialization returns with an
94 	 * error, then all operations on the object except g_object_ref() and
95 	 * g_object_unref() are considered to be invalid, and have undefined
96 	 * behaviour. See the [introduction][ginitable] for more details.
97 	 *
98 	 * Callers should not assume that a class which implements #GInitable can be
99 	 * initialized multiple times, unless the class explicitly documents itself as
100 	 * supporting this. Generally, a class’ implementation of init() can assume
101 	 * (and assert) that it will only be called once. Previously, this documentation
102 	 * recommended all #GInitable implementations should be idempotent; that
103 	 * recommendation was relaxed in GLib 2.54.
104 	 *
105 	 * If a class explicitly supports being initialized multiple times, it is
106 	 * recommended that the method is idempotent: multiple calls with the same
107 	 * arguments should return the same results. Only the first call initializes
108 	 * the object; further calls return the result of the first call.
109 	 *
110 	 * One reason why a class might need to support idempotent initialization is if
111 	 * it is designed to be used via the singleton pattern, with a
112 	 * #GObjectClass.constructor that sometimes returns an existing instance.
113 	 * In this pattern, a caller would expect to be able to call g_initable_init()
114 	 * on the result of g_object_new(), regardless of whether it is in fact a new
115 	 * instance.
116 	 *
117 	 * Params:
118 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
119 	 *
120 	 * Returns: %TRUE if successful. If an error has occurred, this function will
121 	 *     return %FALSE and set @error appropriately if present.
122 	 *
123 	 * Since: 2.22
124 	 *
125 	 * Throws: GException on failure.
126 	 */
127 	public bool init(Cancellable cancellable)
128 	{
129 		GError* err = null;
130 
131 		auto p = g_initable_init(getInitableStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
132 
133 		if (err !is null)
134 		{
135 			throw new GException( new ErrorG(err) );
136 		}
137 
138 		return p;
139 	}
140 }