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 glib.Str;
30 private import gtkc.gdk;
31 public  import gtkc.gdktypes;
32 
33 
34 /**
35  * An opaque type representing a string as an index into a table
36  * of strings on the X server.
37  */
38 /**
39  */
40 
41 /**
42  * Determines the string corresponding to an atom.
43  *
44  * Return: a newly-allocated string containing the string
45  *     corresponding to @atom. When you are done with the
46  *     return value, you should free it using g_free().
47  */
48 public string name(GdkAtom atom)
49 {
50 	return Str.toString(gdk_atom_name(atom));
51 }
52 
53 /**
54  * Finds or creates an atom corresponding to a given string.
55  *
56  * Params:
57  *     atomName = a string.
58  *     onlyIfExists = if %TRUE, GDK is allowed to not create a new atom, but
59  *         just return %GDK_NONE if the requested atom doesn’t already
60  *         exists. Currently, the flag is ignored, since checking the
61  *         existance of an atom is as expensive as creating it.
62  *
63  * Return: the atom corresponding to @atom_name.
64  */
65 public GdkAtom intern(string atomName, bool onlyIfExists)
66 {
67 	return gdk_atom_intern(Str.toStringz(atomName), onlyIfExists);
68 }
69 
70 /**
71  * Finds or creates an atom corresponding to a given string.
72  *
73  * Note that this function is identical to gdk_atom_intern() except
74  * that if a new #GdkAtom is created the string itself is used rather
75  * than a copy. This saves memory, but can only be used if the string
76  * will always exist. It can be used with statically
77  * allocated strings in the main program, but not with statically
78  * allocated memory in dynamically loaded modules, if you expect to
79  * ever unload the module again (e.g. do not use this function in
80  * GTK+ theme engines).
81  *
82  * Params:
83  *     atomName = a static string
84  *
85  * Return: the atom corresponding to @atom_name
86  *
87  * Since: 2.10
88  */
89 public GdkAtom internStaticString(string atomName)
90 {
91 	return gdk_atom_intern_static_string(Str.toStringz(atomName));
92 }
93 
94 /**
95  * Changes the contents of a property on a window.
96  *
97  * Params:
98  *     window = a #GdkWindow
99  *     property = the property to change
100  *     type = the new type for the property. If @mode is
101  *         %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
102  *         must match the existing type or an error will occur.
103  *     format = the new format for the property. If @mode is
104  *         %GDK_PROP_MODE_PREPEND or %GDK_PROP_MODE_APPEND, then this
105  *         must match the existing format or an error will occur.
106  *     mode = a value describing how the new data is to be combined
107  *         with the current data.
108  *     data = the data (a `guchar *`
109  *         `gushort *`, or `gulong *`,
110  *         depending on @format), cast to a `guchar *`.
111  *     nelements = the number of elements of size determined by the format,
112  *         contained in @data.
113  */
114 public void propertyChange(Window window, GdkAtom property, GdkAtom type, int format, GdkPropMode mode, string data, int nelements)
115 {
116 	gdk_property_change((window is null) ? null : window.getWindowStruct(), property, type, format, mode, Str.toStringz(data), nelements);
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  *     actualLength = location to store the length of the retrieved data, in
167  *         bytes.  Data returned in the 32 bit format is stored
168  *         in a long variable, so the actual number of 32 bit
169  *         elements should be be calculated via
170  *         @actual_length / sizeof(glong) to ensure portability to
171  *         64 bit systems.
172  *     data = location
173  *         to store a pointer to the data. The retrieved data should be
174  *         freed with g_free() when you are finished using it.
175  *
176  * Return: %TRUE if data was successfully received and stored
177  *     in @data, otherwise %FALSE.
178  */
179 public bool propertyGet(Window window, GdkAtom property, GdkAtom type, gulong offset, gulong length, int pdelete, out GdkAtom actualPropertyType, out int actualFormat, out string data)
180 {
181 	int actualLength;
182 	char* outdata = null;
183 	
184 	auto p = gdk_property_get((window is null) ? null : window.getWindowStruct(), property, type, offset, length, pdelete, &actualPropertyType, &actualFormat, &actualLength, &outdata) != 0;
185 	
186 	data = Str.toString(outdata, actualLength);
187 	
188 	return p;
189 }
190 
191 /**
192  * Converts a text property in the given encoding to
193  * a list of UTF-8 strings.
194  *
195  * Params:
196  *     display = a #GdkDisplay
197  *     encoding = an atom representing the encoding of the text
198  *     format = the format of the property
199  *     text = the text to convert
200  *     length = the length of @text, in bytes
201  *     list = location to store the list
202  *         of strings or %NULL. The list should be freed with
203  *         g_strfreev().
204  *
205  * Return: the number of strings in the resulting list
206  *
207  * Since: 2.2
208  */
209 public int textPropertyToUtf8ListForDisplay(Display display, GdkAtom encoding, int format, string text, out string[] list)
210 {
211 	char** outlist = null;
212 	
213 	auto p = gdk_text_property_to_utf8_list_for_display((display is null) ? null : display.getDisplayStruct(), encoding, format, Str.toStringz(text), cast(int)text.length, &outlist);
214 	
215 	list = Str.toStringArray(outlist);
216 	
217 	return p;
218 }
219 
220 /**
221  * Converts an UTF-8 string into the best possible representation
222  * as a STRING. The representation of characters not in STRING
223  * is not specified; it may be as pseudo-escape sequences
224  * \x{ABCD}, or it may be in some other form of approximation.
225  *
226  * Params:
227  *     str = a UTF-8 string
228  *
229  * Return: the newly-allocated string, or %NULL if the
230  *     conversion failed. (It should not fail for any properly
231  *     formed UTF-8 string unless system limits like memory or
232  *     file descriptors are exceeded.)
233  */
234 public string utf8ToStringTarget(string str)
235 {
236 	return Str.toString(gdk_utf8_to_string_target(Str.toStringz(str)));
237 }