*
* Creates a new #CallyActor for the given @actor
*
- * Return value: the newly created #CallyActor
+ * Return value: the newly created #AtkObject
*
* Since: 1.4
*/
/**
* CallyActorClass:
- * @notify_clutter: FIXME
- * @focus_clutter: FIXME
- * @add_actor: FIXME
- * @remove_actor: FIXME
+ * @notify_clutter: Signal handler for notify signal on Clutter actor
+ * @focus_clutter: Signal handler for key-focus-in and key-focus-out signal on Clutter actor
+ * @add_actor: Signal handler for actor-added signal on ClutterContainer interface
+ * @remove_actor: Signal handler for actor-added signal on ClutterContainer interface
*
* The <structname>CallyActorClass</structname> structure contains only
* private data
/* nothing to do yet */
}
+/**
+ * cally_clone_new:
+ * @actor: a #ClutterActor
+ *
+ * Creates a new #CallyClone for the given @actor. @actor must be a
+ * #ClutterClone.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_clone_new (ClutterActor *actor)
{
#include <glib-object.h>
#include <atk/atkobject.h>
+/**
+ * CALLY_ACCESSIBLE_FACTORY:
+ * @type: GType of the accessible which is created by the factory
+ * @type_as_function: prefix of the accessible object methods
+ * @opt_create_accessible: method to instantiate the accessibility object
+ *
+ * Defines a new #AtkObjectFactory factory to create accessible
+ * objects of a specific GType. It defines the factory GType and also
+ * overrides the proper #AtkObjectFactory methods.
+ *
+ * It assumes that the accessibility object provides a
+ * @opt_create_accessible method in order to create the accessibility
+ * object. It returns a @type GType object.
+ *
+ * Since: 1.4
+ */
#define CALLY_ACCESSIBLE_FACTORY(type, type_as_function, opt_create_accessible) \
\
static GType \
return t; \
}
+/**
+ * CALLY_ACTOR_SET_FACTORY:
+ * @widget_type: GType of the clutter actor
+ * @type_as_function: prefix of the accessible object methods
+ *
+ * Sets the #AtkObjectFactory to be used in order to instantiate
+ * accessibility objects for the actor which GType is @widget_type.
+ *
+ * Since: 1.4
+ */
#define CALLY_ACTOR_SET_FACTORY(widget_type, type_as_function) \
atk_registry_set_factory_type (atk_get_default_registry (), \
widget_type, \
/* nothing to do yet */
}
+/**
+ * cally_rectangle_new:
+ * @actor: a #ClutterActor
+ *
+ * Creates a new #CallyRectangle for the given @actor. @actor must be
+ * a #ClutterRectangle.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_rectangle_new (ClutterActor *actor)
{
/**
* SECTION:cally-root
- * @short_description: Root object for the CALLY toolkit
+ * @short_description: Root object for the Cally toolkit
* @see_also: #ClutterStage
*
* #CallyRoot is the root object of the accessibility tree-like
root->priv->stage_removed_id = 0;
}
+/**
+ * cally_root_new:
+ *
+ * Creates a new #CallyRoot object.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_root_new (void)
{
*
* #CallyStage implements the required ATK interfaces for #ClutterStage
*
+ * Some implementation details: at this moment #CallyStage is used as
+ * the most similar Window object in this toolkit (ie: emitting window
+ * related signals), although the real purpose of #ClutterStage is
+ * being a canvas. Anyway, this is required for applications using
+ * just clutter, or directly #ClutterStage
*/
#include "cally-stage.h"
g_type_class_add_private (gobject_class, sizeof (CallyStagePrivate));
+ /**
+ * CallyStage::activate:
+ * @cally_actor: the object which received the signal
+ *
+ * The ::activate signal is emitted when the stage receives the key
+ * focus from the underlying window system.
+ *
+ * Toolkit implementation note: it is used when anyone adds a global
+ * event listener to "window:activate"
+ *
+ * Since: 1.4
+ */
cally_stage_signals [ACTIVATE] =
g_signal_new ("activate",
G_TYPE_FROM_CLASS (klass),
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+
+ /**
+ * CallyStage::create:
+ * @cally_actor: the object which received the signal
+ *
+ * The ::create signal is emitted when the stage is created.
+ *
+ * Toolkit implementation note: it is used when anyone adds a global
+ * event listener to "window:create"
+ *
+ * Since: 1.4
+ */
cally_stage_signals [CREATE] =
g_signal_new ("create",
G_TYPE_FROM_CLASS (klass),
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+
+ /**
+ * CallyStage::deactivate:
+ * @cally_actor: the object which received the signal
+ *
+ * The ::deactivate signal is emitted when the stage loses key focus
+ * from the underlying window system.
+ *
+ * Toolkit implementation note: it is used when anyone adds a global
+ * event listener to "window:deactivate"
+ *
+ * Since: 1.4
+ */
cally_stage_signals [DEACTIVATE] =
g_signal_new ("deactivate",
G_TYPE_FROM_CLASS (klass),
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+
+ /**
+ * CallyStage::destroy:
+ * @cally_actor: the object which received the signal
+ *
+ * The ::destroy signal is emitted when the stage is destroyed.
+ *
+ * Toolkit implementation note: it is used when anyone adds a global
+ * event listener to "window:destroy"
+ *
+ * Since: 1.4
+ */
cally_stage_signals [DESTROY] =
g_signal_new ("destroy",
G_TYPE_FROM_CLASS (klass),
priv->active = FALSE;
}
+/**
+ * cally_stage_new:
+ * @actor: a #ClutterActor
+ *
+ * Creates a new #CallyStage for the given @actor. @actor should be a
+ * #ClutterStage.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_stage_new (ClutterActor *actor)
{
G_OBJECT_CLASS (cally_text_parent_class)->finalize (obj);
}
+/**
+ * cally_text_new:
+ * @actor: a #ClutterActor
+ *
+ * Creates a new #CallyText for the given @actor. @actor must be a
+ * #ClutterText.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_text_new (ClutterActor *actor)
{
/* nothing to do yet */
}
+/**
+ * cally_texture_new:
+ * @actor: a #ClutterActor
+ *
+ * Creates a new #CallyTexture for the given @actor. @actor must be
+ * a #ClutterTexture.
+ *
+ * Return value: the newly created #AtkObject
+ *
+ * Since: 1.4
+ */
AtkObject*
cally_texture_new (ClutterActor *actor)
{
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:cally
+ * @Title: Cally
+ * @short_description: Cally initialization methods.
+ *
+ * Cally initialization methods.
+ *
+ */
+
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
CALLY_ACCESSIBLE_FACTORY (CALLY_TYPE_CLONE, cally_clone, cally_clone_new)
/**
- * cally_acccessibility_init:
+ * cally_accessibility_init:
*
* Initializes the accessibility support.
*
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=
+content_files= \
+ cally-overview.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
-expand_content_files=
+expand_content_files= \
+ cally-overview.xml
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
<releaseinfo>for Clutter &version;</releaseinfo>
<copyright>
+ <year>2008</year>
+ <year>2009</year>
<year>2010</year>
- <holder>Intel Corporation</holder>
+ <holder>Igalia S.L.</holder>
</copyright>
<legalnotice>
</legalnotice>
</bookinfo>
+ <xi:include href="xml/cally-overview.xml"/>
+
<part id="callybase">
<title>Cally Reference</title>
<title>Base Classes</title>
<xi:include href="xml/cally-actor.xml"/>
+ <xi:include href="xml/cally-group.xml"/>
<xi:include href="xml/cally-stage.xml"/>
<xi:include href="xml/cally-texture.xml"/>
<xi:include href="xml/cally-rectangle.xml"/>
--- /dev/null
+<part id="clutter-overview">
+ <partinfo>
+ <author>
+ <firstname>Alejandro</firstname>
+ <surname>Piñeiro Iglesias</surname>
+ <affiliation>
+ <address>
+ <email>apinheiro@igalia.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </partinfo>
+
+ <title>Overview</title>
+
+ <partintro>
+
+ <para>Cally (Clutter Accessibility Implementation Library) is the
+ Clutter implementation of the ATK interfaces. You can see as the
+ Clutter equivalent of GAIL, which provides accessibility support
+ for GTK+ and other GNOME related libraries.</para>
+
+ <para>This implementation expose Clutter actors to accessibility
+ tools like Orca. This allows not only writing accessible user
+ interfaces, but also allows testing and verification frameworks
+ based on accessibility technologies to inspect and test a Clutter
+ scene graph.</para>
+
+ <para>This reference manual defines the different APIs defined in
+ Cally. Anyway take into account that the most common use of case
+ Cally is transparent to the user, as the different accessibility
+ tools are intended to use the abstract ATK interfaces, and *not
+ directly* Cally, so this tools can communicate with applications
+ using different toolkits, like GTK+, Java, Clutter, etc. </para>
+
+ <para>The purpose of this reference is allow to extend Cally
+ functionality in any Clutter-based widget toolkit. Clutter is more
+ low-level that other toolkits like GTK+, and some toolkits have
+ started to appear based on Clutter: MX, Shell Toolkit, Candies,
+ Glitter, etc. This means that it is really likely that these
+ libraries will require extra accessibility support.</para>
+
+ <para>GAIL used a different approach, being a almost-pure-opaque
+ implementation of the ATK interfaces. So you can't extend it
+ directly. You need to use GObject and ATK mechanisms, like
+ run-time anonymous inheritance, to extend it. Although valid to
+ some custom cases, it showed to be really problematic and hacky in
+ wider approaches, like HAIL(Hildon Accessibility Implementation
+ Library). As explained, Clutter is more likely to be extended, so
+ these issues would arise sooner.</para>
+
+ <para>Part of the accessibility support is implemented on Clutter,
+ like the initialization code, and the method to obtain the
+ accessibility object for each Clutter object. In the same way, to
+ make it easier, and to allow access to Clutter object private
+ data, it would be really likely that the accessibility support
+ would be implemented directly on some Clutter objects</para>
+
+ <para>Check the next clutter methods for more information:</para>
+ <variablelist>
+ <varlistentry>
+ <term>clutter_actor_get_accessible()</term>
+ <listitem>Virtual method to obtain the accessibility object of a
+ clutter actor</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>clutter_get_accessibility_enabled()</term>
+ <listitem>Method to check if accessibility is enabled.</listitem>
+ </varlistentry>
+ </variablelist>
+
+ </partintro>
+
+</part>
<listitem><para>Unsets FLAGS from the COGL debugging
flags.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>--clutter-enable-accessibility</term>
+ <listitem><para>Enables accessibility support.</para></listitem>
+ </varlistentry>
</variablelist>
<para>The X11 backends also have the following command line