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 gdk.Atom;
26 
27 private import gdk.Display;
28 private import gdk.Window;
29 private import gdk.c.functions;
30 public  import gdk.c.types;
31 private import glib.Str;
32 public  import gtkc.gdktypes;
33 
34 
35 /**
36  * An opaque type representing a string as an index into a table
37  * of strings on the X server.
38  */
39 
40 /**
41  * Determines the string corresponding to an atom.
42  *
43  * Returns: a newly-allocated string containing the string
44  *     corresponding to @atom. When you are done with the
45  *     return value, you should free it using g_free().
46  */
47 public string name(GdkAtom atom)
48 {
49 	auto retStr = gdk_atom_name(atom);
50 
51 	scope(exit) Str.freeString(retStr);
52 	return Str.toString(retStr);
53 }
54 
55 /**
56  * Finds or creates an atom corresponding to a given string.
57  *
58  * Params:
59  *     atomName = a string.
60  *     onlyIfExists = if %TRUE, GDK is allowed to not create a new atom, but
61  *         just return %GDK_NONE if the requested atom doesn’t already
62  *         exists. Currently, the flag is ignored, since checking the
63  *         existance of an atom is as expensive as creating it.
64  *
65  * Returns: the atom corresponding to @atom_name.
66  */
67 public GdkAtom intern(string atomName, bool onlyIfExists)
68 {
69 	return gdk_atom_intern(Str.toStringz(atomName), onlyIfExists);
70 }
71 
72 /**
73  * Finds or creates an atom corresponding to a given string.
74  *
75  * Note that this function is identical to gdk_atom_intern() except
76  * that if a new #GdkAtom is created the string itself is used rather
77  * than a copy. This saves memory, but can only be used if the string
78  * will always exist. It can be used with statically
79  * allocated strings in the main program, but not with statically
80  * allocated memory in dynamically loaded modules, if you expect to
81  * ever unload the module again (e.g. do not use this function in
82  * GTK+ theme engines).
83  *
84  * Params:
85  *     atomName = a static string
86  *
87  * Returns: the atom corresponding to @atom_name
88  *
89  * Since: 2.10
90  */
91 public GdkAtom internStaticString(string atomName)
92 {
93 	return gdk_atom_intern_static_string(Str.toStringz(atomName));
94 }
95 
96 /**
97  * Changes the contents of a property on a window.
98  *
99  * Params:
100  *     window = a #GdkWindow
101  *     property = the property to change
102  *     type = the new type for the property. If @mode is
103  *         %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
104  *         must match the existing type or an error will occur.
105  *     format = the new format for the property. If @mode is
106  *         %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
107  *         must match the existing format or an error will occur.
108  *     mode = a value describing how the new data is to be combined
109  *         with the current data.
110  *     data = the data (a `guchar *`
111  *         `gushort *`, or `gulong *`,
112  *         depending on @format), cast to a `guchar *`.
113  */
114 public void propertyChange(Window window, GdkAtom property, GdkAtom type, int format, GdkPropMode mode, char[] data)
115 {
116 	gdk_property_change((window is null) ? null : window.getWindowStruct(), property, type, format, mode, data.ptr, cast(int)data.length);
117 }
118 
119 /**
120  * Deletes a property from a window.
121  *
122  * Params:
123  *     window = a #GdkWindow
124  *     property = the property to delete
125  */
126 public void propertyDelete(Window window, GdkAtom property)
127 {
128 	gdk_property_delete((window is null) ? null : window.getWindowStruct(), property);
129 }
130 
131 /**
132  * Retrieves a portion of the contents of a property. If the
133  * property does not exist, then the function returns %FALSE,
134  * and %GDK_NONE will be stored in @actual_property_type.
135  *
136  * The XGetWindowProperty() function that gdk_property_get()
137  * uses has a very confusing and complicated set of semantics.
138  * Unfortunately, gdk_property_get() makes the situation
139  * worse instead of better (the semantics should be considered
140  * undefined), and also prints warnings to stderr in cases where it
141  * should return a useful error to the program. You are advised to use
142  * XGetWindowProperty() directly until a replacement function for
143  * gdk_property_get() is provided.
144  *
145  * Params:
146  *     window = a #GdkWindow
147  *     property = the property to retrieve
148  *     type = the desired property type, or %GDK_NONE, if any type of data
149  *         is acceptable. If this does not match the actual
150  *         type, then @actual_format and @actual_length will
151  *         be filled in, a warning will be printed to stderr
152  *         and no data will be returned.
153  *     offset = the offset into the property at which to begin
154  *         retrieving data, in 4 byte units.
155  *     length = the length of the data to retrieve in bytes.  Data is
156  *         considered to be retrieved in 4 byte chunks, so @length
157  *         will be rounded up to the next highest 4 byte boundary
158  *         (so be careful not to pass a value that might overflow
159  *         when rounded up).
160  *     pdelete = if %TRUE, delete the property after retrieving the
161  *         data.
162  *     actualPropertyType = location to store the
163  *         actual type of the property.
164  *     actualFormat = location to store the actual return format of the
165  *         data; either 8, 16 or 32 bits.
166  *     data = location
167  *         to store a pointer to the data. The retrieved data should be
168  *         freed with g_free() when you are finished using it.
169  *
170  * Returns: %TRUE if data was successfully received and stored
171  *     in @data, otherwise %FALSE.
172  */
173 public bool propertyGet(Window window, GdkAtom property, GdkAtom type, gulong offset, gulong length, int pdelete, out GdkAtom actualPropertyType, out int actualFormat, out char[] data)
174 {
175 	int actualLength;
176 	char* outdata = null;
177 
178 	auto p = gdk_property_get((window is null) ? null : window.getWindowStruct(), property, type, offset, length, pdelete, &actualPropertyType, &actualFormat, &actualLength, &outdata) != 0;
179 
180 	data = outdata[0 .. actualLength];
181 
182 	return p;
183 }
184 
185 /**
186  * Converts a text property in the given encoding to
187  * a list of UTF-8 strings.
188  *
189  * Params:
190  *     display = a #GdkDisplay
191  *     encoding = an atom representing the encoding of the text
192  *     format = the format of the property
193  *     text = the text to convert
194  *     list = location to store the list
195  *         of strings or %NULL. The list should be freed with
196  *         g_strfreev().
197  *
198  * Returns: the number of strings in the resulting list
199  *
200  * Since: 2.2
201  */
202 public int textPropertyToUtf8ListForDisplay(Display display, GdkAtom encoding, int format, char[] text, out string[] list)
203 {
204 	char** outlist = null;
205 
206 	auto p = gdk_text_property_to_utf8_list_for_display((display is null) ? null : display.getDisplayStruct(), encoding, format, text.ptr, cast(int)text.length, &outlist);
207 
208 	list = Str.toStringArray(outlist);
209 
210 	return p;
211 }
212 
213 /**
214  * Converts an UTF-8 string into the best possible representation
215  * as a STRING. The representation of characters not in STRING
216  * is not specified; it may be as pseudo-escape sequences
217  * \x{ABCD}, or it may be in some other form of approximation.
218  *
219  * Params:
220  *     str = a UTF-8 string
221  *
222  * Returns: the newly-allocated string, or %NULL if the
223  *     conversion failed. (It should not fail for any properly
224  *     formed UTF-8 string unless system limits like memory or
225  *     file descriptors are exceeded.)
226  */
227 public string utf8ToStringTarget(string str)
228 {
229 	auto retStr = gdk_utf8_to_string_target(Str.toStringz(str));
230 
231 	scope(exit) Str.freeString(retStr);
232 	return Str.toString(retStr);
233 }