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 atk.ObjectAtk;
26 
27 private import atk.RelationSet;
28 private import atk.StateSet;
29 private import atk.c.functions;
30 public  import atk.c.types;
31 private import glib.Str;
32 private import gobject.ObjectG;
33 private import gobject.Signals;
34 public  import gtkc.atktypes;
35 private import std.algorithm;
36 
37 
38 /**
39  * This class is the primary class for accessibility support via the
40  * Accessibility ToolKit (ATK).  Objects which are instances of
41  * #AtkObject (or instances of AtkObject-derived types) are queried
42  * for properties which relate basic (and generic) properties of a UI
43  * component such as name and description.  Instances of #AtkObject
44  * may also be queried as to whether they implement other ATK
45  * interfaces (e.g. #AtkAction, #AtkComponent, etc.), as appropriate
46  * to the role which a given UI component plays in a user interface.
47  * 
48  * All UI components in an application which provide useful
49  * information or services to the user must provide corresponding
50  * #AtkObject instances on request (in GTK+, for instance, usually on
51  * a call to #gtk_widget_get_accessible ()), either via ATK support
52  * built into the toolkit for the widget class or ancestor class, or
53  * in the case of custom widgets, if the inherited #AtkObject
54  * implementation is insufficient, via instances of a new #AtkObject
55  * subclass.
56  * 
57  * See also: #AtkObjectFactory, #AtkRegistry.  (GTK+ users see also
58  * #GtkAccessible).
59  */
60 public class ObjectAtk : ObjectG
61 {
62 	/** the main Gtk struct */
63 	protected AtkObject* atkObject;
64 
65 	/** Get the main Gtk struct */
66 	public AtkObject* getObjectAtkStruct(bool transferOwnership = false)
67 	{
68 		if (transferOwnership)
69 			ownedRef = false;
70 		return atkObject;
71 	}
72 
73 	/** the main Gtk struct as a void* */
74 	protected override void* getStruct()
75 	{
76 		return cast(void*)atkObject;
77 	}
78 
79 	/**
80 	 * Sets our main struct and passes it to the parent class.
81 	 */
82 	public this (AtkObject* atkObject, bool ownedRef = false)
83 	{
84 		this.atkObject = atkObject;
85 		super(cast(GObject*)atkObject, ownedRef);
86 	}
87 
88 
89 	/** */
90 	public static GType getType()
91 	{
92 		return atk_object_get_type();
93 	}
94 
95 	/**
96 	 * Adds a relationship of the specified type with the specified target.
97 	 *
98 	 * Params:
99 	 *     relationship = The #AtkRelationType of the relation
100 	 *     target = The #AtkObject which is to be the target of the relation.
101 	 *
102 	 * Returns: TRUE if the relationship is added.
103 	 */
104 	public bool addRelationship(AtkRelationType relationship, ObjectAtk target)
105 	{
106 		return atk_object_add_relationship(atkObject, relationship, (target is null) ? null : target.getObjectAtkStruct()) != 0;
107 	}
108 
109 	/**
110 	 *
111 	 *
112 	 * Deprecated: Since 2.12. Connect directly to property-change or
113 	 * notify signals.
114 	 *
115 	 * Params:
116 	 *     handler = a function to be called when a property changes its value
117 	 *
118 	 * Returns: a #guint which is the handler id used in
119 	 *     atk_object_remove_property_change_handler()
120 	 */
121 	public uint connectPropertyChangeHandler(AtkPropertyChangeHandler* handler)
122 	{
123 		return atk_object_connect_property_change_handler(atkObject, handler);
124 	}
125 
126 	/**
127 	 * Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of
128 	 * name-value pairs. As such these attributes may be considered weakly-typed properties or annotations,
129 	 * as distinct from strongly-typed object data available via other get/set methods.
130 	 * Not all objects have explicit "name-value pair" #AtkAttributeSet properties.
131 	 *
132 	 * Returns: an #AtkAttributeSet consisting of all
133 	 *     explicit properties/annotations applied to the object, or an empty
134 	 *     set if the object has no name-value pair attributes assigned to
135 	 *     it. This #atkattributeset should be freed by a call to
136 	 *     atk_attribute_set_free().
137 	 *
138 	 * Since: 1.12
139 	 */
140 	public AtkAttributeSet* getAttributes()
141 	{
142 		return atk_object_get_attributes(atkObject);
143 	}
144 
145 	/**
146 	 * Gets the accessible description of the accessible.
147 	 *
148 	 * Returns: a character string representing the accessible description
149 	 *     of the accessible.
150 	 */
151 	public string getDescription()
152 	{
153 		return Str.toString(atk_object_get_description(atkObject));
154 	}
155 
156 	/**
157 	 * Gets the 0-based index of this accessible in its parent; returns -1 if the
158 	 * accessible does not have an accessible parent.
159 	 *
160 	 * Returns: an integer which is the index of the accessible in its parent
161 	 */
162 	public int getIndexInParent()
163 	{
164 		return atk_object_get_index_in_parent(atkObject);
165 	}
166 
167 	/**
168 	 * Gets the layer of the accessible.
169 	 *
170 	 * Deprecated: Use atk_component_get_layer instead.
171 	 *
172 	 * Returns: an #AtkLayer which is the layer of the accessible
173 	 */
174 	public AtkLayer getLayer()
175 	{
176 		return atk_object_get_layer(atkObject);
177 	}
178 
179 	/**
180 	 * Gets the zorder of the accessible. The value G_MININT will be returned
181 	 * if the layer of the accessible is not ATK_LAYER_MDI.
182 	 *
183 	 * Deprecated: Use atk_component_get_mdi_zorder instead.
184 	 *
185 	 * Returns: a gint which is the zorder of the accessible, i.e. the depth at
186 	 *     which the component is shown in relation to other components in the same
187 	 *     container.
188 	 */
189 	public int getMdiZorder()
190 	{
191 		return atk_object_get_mdi_zorder(atkObject);
192 	}
193 
194 	/**
195 	 * Gets the number of accessible children of the accessible.
196 	 *
197 	 * Returns: an integer representing the number of accessible children
198 	 *     of the accessible.
199 	 */
200 	public int getNAccessibleChildren()
201 	{
202 		return atk_object_get_n_accessible_children(atkObject);
203 	}
204 
205 	/**
206 	 * Gets the accessible name of the accessible.
207 	 *
208 	 * Returns: a character string representing the accessible name of the object.
209 	 */
210 	public string getName()
211 	{
212 		return Str.toString(atk_object_get_name(atkObject));
213 	}
214 
215 	/**
216 	 * Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale
217 	 * of @accessible.
218 	 *
219 	 * Returns: a UTF-8 string indicating the POSIX-style LC_MESSAGES
220 	 *     locale of @accessible.
221 	 *
222 	 * Since: 2.8
223 	 */
224 	public string getObjectLocale()
225 	{
226 		return Str.toString(atk_object_get_object_locale(atkObject));
227 	}
228 
229 	/**
230 	 * Gets the accessible parent of the accessible. By default this is
231 	 * the one assigned with atk_object_set_parent(), but it is assumed
232 	 * that ATK implementors have ways to get the parent of the object
233 	 * without the need of assigning it manually with
234 	 * atk_object_set_parent(), and will return it with this method.
235 	 *
236 	 * If you are only interested on the parent assigned with
237 	 * atk_object_set_parent(), use atk_object_peek_parent().
238 	 *
239 	 * Returns: an #AtkObject representing the accessible
240 	 *     parent of the accessible
241 	 */
242 	public ObjectAtk getParent()
243 	{
244 		auto p = atk_object_get_parent(atkObject);
245 
246 		if(p is null)
247 		{
248 			return null;
249 		}
250 
251 		return ObjectG.getDObject!(ObjectAtk)(cast(AtkObject*) p);
252 	}
253 
254 	/**
255 	 * Gets the role of the accessible.
256 	 *
257 	 * Returns: an #AtkRole which is the role of the accessible
258 	 */
259 	public AtkRole getRole()
260 	{
261 		return atk_object_get_role(atkObject);
262 	}
263 
264 	/**
265 	 * This function is called when implementing subclasses of #AtkObject.
266 	 * It does initialization required for the new object. It is intended
267 	 * that this function should called only in the ..._new() functions used
268 	 * to create an instance of a subclass of #AtkObject
269 	 *
270 	 * Params:
271 	 *     data = a #gpointer which identifies the object for which the AtkObject was created.
272 	 */
273 	public void initialize(void* data)
274 	{
275 		atk_object_initialize(atkObject, data);
276 	}
277 
278 	/**
279 	 * Emits a state-change signal for the specified state.
280 	 *
281 	 * Note that as a general rule when the state of an existing object changes,
282 	 * emitting a notification is expected.
283 	 *
284 	 * Params:
285 	 *     state = an #AtkState whose state is changed
286 	 *     value = a gboolean which indicates whether the state is being set on or off
287 	 */
288 	public void notifyStateChange(AtkState state, bool value)
289 	{
290 		atk_object_notify_state_change(atkObject, state, value);
291 	}
292 
293 	/**
294 	 * Gets the accessible parent of the accessible, if it has been
295 	 * manually assigned with atk_object_set_parent. Otherwise, this
296 	 * function returns %NULL.
297 	 *
298 	 * This method is intended as an utility for ATK implementors, and not
299 	 * to be exposed to accessible tools. See atk_object_get_parent() for
300 	 * further reference.
301 	 *
302 	 * Returns: an #AtkObject representing the accessible
303 	 *     parent of the accessible if assigned
304 	 */
305 	public ObjectAtk peekParent()
306 	{
307 		auto p = atk_object_peek_parent(atkObject);
308 
309 		if(p is null)
310 		{
311 			return null;
312 		}
313 
314 		return ObjectG.getDObject!(ObjectAtk)(cast(AtkObject*) p);
315 	}
316 
317 	/**
318 	 * Gets a reference to the specified accessible child of the object.
319 	 * The accessible children are 0-based so the first accessible child is
320 	 * at index 0, the second at index 1 and so on.
321 	 *
322 	 * Params:
323 	 *     i = a gint representing the position of the child, starting from 0
324 	 *
325 	 * Returns: an #AtkObject representing the specified
326 	 *     accessible child of the accessible.
327 	 */
328 	public ObjectAtk refAccessibleChild(int i)
329 	{
330 		auto p = atk_object_ref_accessible_child(atkObject, i);
331 
332 		if(p is null)
333 		{
334 			return null;
335 		}
336 
337 		return ObjectG.getDObject!(ObjectAtk)(cast(AtkObject*) p, true);
338 	}
339 
340 	/**
341 	 * Gets the #AtkRelationSet associated with the object.
342 	 *
343 	 * Returns: an #AtkRelationSet representing the relation set
344 	 *     of the object.
345 	 */
346 	public RelationSet refRelationSet()
347 	{
348 		auto p = atk_object_ref_relation_set(atkObject);
349 
350 		if(p is null)
351 		{
352 			return null;
353 		}
354 
355 		return ObjectG.getDObject!(RelationSet)(cast(AtkRelationSet*) p, true);
356 	}
357 
358 	/**
359 	 * Gets a reference to the state set of the accessible; the caller must
360 	 * unreference it when it is no longer needed.
361 	 *
362 	 * Returns: a reference to an #AtkStateSet which is the state
363 	 *     set of the accessible
364 	 */
365 	public StateSet refStateSet()
366 	{
367 		auto p = atk_object_ref_state_set(atkObject);
368 
369 		if(p is null)
370 		{
371 			return null;
372 		}
373 
374 		return ObjectG.getDObject!(StateSet)(cast(AtkStateSet*) p, true);
375 	}
376 
377 	/**
378 	 *
379 	 *
380 	 * Deprecated: Since 2.12.
381 	 *
382 	 * Removes a property change handler.
383 	 *
384 	 * Params:
385 	 *     handlerId = a guint which identifies the handler to be removed.
386 	 */
387 	public void removePropertyChangeHandler(uint handlerId)
388 	{
389 		atk_object_remove_property_change_handler(atkObject, handlerId);
390 	}
391 
392 	/**
393 	 * Removes a relationship of the specified type with the specified target.
394 	 *
395 	 * Params:
396 	 *     relationship = The #AtkRelationType of the relation
397 	 *     target = The #AtkObject which is the target of the relation to be removed.
398 	 *
399 	 * Returns: TRUE if the relationship is removed.
400 	 */
401 	public bool removeRelationship(AtkRelationType relationship, ObjectAtk target)
402 	{
403 		return atk_object_remove_relationship(atkObject, relationship, (target is null) ? null : target.getObjectAtkStruct()) != 0;
404 	}
405 
406 	/**
407 	 * Sets the accessible description of the accessible. You can't set
408 	 * the description to NULL. This is reserved for the initial value. In
409 	 * this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set
410 	 * the name to a empty value you can use "".
411 	 *
412 	 * Params:
413 	 *     description = a character string to be set as the accessible description
414 	 */
415 	public void setDescription(string description)
416 	{
417 		atk_object_set_description(atkObject, Str.toStringz(description));
418 	}
419 
420 	/**
421 	 * Sets the accessible name of the accessible. You can't set the name
422 	 * to NULL. This is reserved for the initial value. In this aspect
423 	 * NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to
424 	 * a empty value you can use "".
425 	 *
426 	 * Params:
427 	 *     name = a character string to be set as the accessible name
428 	 */
429 	public void setName(string name)
430 	{
431 		atk_object_set_name(atkObject, Str.toStringz(name));
432 	}
433 
434 	/**
435 	 * Sets the accessible parent of the accessible. @parent can be NULL.
436 	 *
437 	 * Params:
438 	 *     parent = an #AtkObject to be set as the accessible parent
439 	 */
440 	public void setParent(ObjectAtk parent)
441 	{
442 		atk_object_set_parent(atkObject, (parent is null) ? null : parent.getObjectAtkStruct());
443 	}
444 
445 	/**
446 	 * Sets the role of the accessible.
447 	 *
448 	 * Params:
449 	 *     role = an #AtkRole to be set as the role
450 	 */
451 	public void setRole(AtkRole role)
452 	{
453 		atk_object_set_role(atkObject, role);
454 	}
455 
456 	/**
457 	 * The "active-descendant-changed" signal is emitted by an object
458 	 * which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus
459 	 * object in the object changes. For instance, a table will emit the
460 	 * signal when the cell in the table which has focus changes.
461 	 *
462 	 * Params:
463 	 *     arg1 = the newly focused object.
464 	 */
465 	gulong addOnActiveDescendantChanged(void delegate(void*, ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
466 	{
467 		return Signals.connect(this, "active-descendant-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
468 	}
469 
470 	/**
471 	 * The signal "children-changed" is emitted when a child is added or
472 	 * removed form an object. It supports two details: "add" and
473 	 * "remove"
474 	 *
475 	 * Params:
476 	 *     arg1 = The index of the added or removed child. The value can be
477 	 *         -1. This is used if the value is not known by the implementor
478 	 *         when the child is added/removed or irrelevant.
479 	 *     arg2 = A gpointer to the child AtkObject which was added or
480 	 *         removed. If the child was removed, it is possible that it is not
481 	 *         available for the implementor. In that case this pointer can be
482 	 *         NULL.
483 	 */
484 	gulong addOnChildrenChanged(void delegate(uint, void*, ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
485 	{
486 		return Signals.connect(this, "children-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
487 	}
488 
489 	/**
490 	 * The signal "focus-event" is emitted when an object gained or lost
491 	 * focus.
492 	 *
493 	 * Deprecated: Use the #AtkObject::state-change signal instead.
494 	 *
495 	 * Params:
496 	 *     arg1 = a boolean value which indicates whether the object gained
497 	 *         or lost focus.
498 	 */
499 	gulong addOnFocus(void delegate(bool, ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
500 	{
501 		return Signals.connect(this, "focus-event", dlg, connectFlags ^ ConnectFlags.SWAPPED);
502 	}
503 
504 	/**
505 	 * The signal "property-change" is emitted when an object's property
506 	 * value changes. @arg1 contains an #AtkPropertyValues with the name
507 	 * and the new value of the property whose value has changed. Note
508 	 * that, as with GObject notify, getting this signal does not
509 	 * guarantee that the value of the property has actually changed; it
510 	 * may also be emitted when the setter of the property is called to
511 	 * reinstate the previous value.
512 	 *
513 	 * Toolkit implementor note: ATK implementors should use
514 	 * g_object_notify() to emit property-changed
515 	 * notifications. #AtkObject::property-changed is needed by the
516 	 * implementation of atk_add_global_event_listener() because GObject
517 	 * notify doesn't support emission hooks.
518 	 *
519 	 * Params:
520 	 *     arg1 = an #AtkPropertyValues containing the new value of the
521 	 *         property which changed.
522 	 */
523 	gulong addOnPropertyChange(void delegate(void*, ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
524 	{
525 		return Signals.connect(this, "property-change", dlg, connectFlags ^ ConnectFlags.SWAPPED);
526 	}
527 
528 	/**
529 	 * The "state-change" signal is emitted when an object's state
530 	 * changes.  The detail value identifies the state type which has
531 	 * changed.
532 	 *
533 	 * Params:
534 	 *     arg1 = The name of the state which has changed
535 	 *     arg2 = A boolean which indicates whether the state has been set or unset.
536 	 */
537 	gulong addOnStateChange(void delegate(string, bool, ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
538 	{
539 		return Signals.connect(this, "state-change", dlg, connectFlags ^ ConnectFlags.SWAPPED);
540 	}
541 
542 	/**
543 	 * The "visible-data-changed" signal is emitted when the visual
544 	 * appearance of the object changed.
545 	 */
546 	gulong addOnVisibleDataChanged(void delegate(ObjectAtk) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
547 	{
548 		return Signals.connect(this, "visible-data-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
549 	}
550 
551 	/**
552 	 * Get the #AtkRole type corresponding to a rolew name.
553 	 *
554 	 * Params:
555 	 *     name = a string which is the (non-localized) name of an ATK role.
556 	 *
557 	 * Returns: the #AtkRole enumerated type corresponding to the specified name,
558 	 *     or #ATK_ROLE_INVALID if no matching role is found.
559 	 */
560 	public static AtkRole roleForName(string name)
561 	{
562 		return atk_role_for_name(Str.toStringz(name));
563 	}
564 
565 	/**
566 	 * Gets the localized description string describing the #AtkRole @role.
567 	 *
568 	 * Params:
569 	 *     role = The #AtkRole whose localized name is required
570 	 *
571 	 * Returns: the localized string describing the AtkRole
572 	 */
573 	public static string roleGetLocalizedName(AtkRole role)
574 	{
575 		return Str.toString(atk_role_get_localized_name(role));
576 	}
577 
578 	/**
579 	 * Gets the description string describing the #AtkRole @role.
580 	 *
581 	 * Params:
582 	 *     role = The #AtkRole whose name is required
583 	 *
584 	 * Returns: the string describing the AtkRole
585 	 */
586 	public static string roleGetName(AtkRole role)
587 	{
588 		return Str.toString(atk_role_get_name(role));
589 	}
590 
591 	/**
592 	 * Registers the role specified by @name. @name must be a meaningful
593 	 * name. So it should not be empty, or consisting on whitespaces.
594 	 *
595 	 * Deprecated: Since 2.12. If your application/toolkit doesn't find a
596 	 * suitable role for a specific object defined at #AtkRole, please
597 	 * submit a bug in order to add a new role to the specification.
598 	 *
599 	 * Params:
600 	 *     name = a character string describing the new role.
601 	 *
602 	 * Returns: an #AtkRole for the new role if added
603 	 *     properly. ATK_ROLE_INVALID in case of error.
604 	 */
605 	public static AtkRole roleRegister(string name)
606 	{
607 		return atk_role_register(Str.toStringz(name));
608 	}
609 }