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