eail/eail.h

   1 /*
   2  * Copyright (c) 2013 Samsung Electronics Co., Ltd.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library; see the file COPYING.LIB.  If not, write to
  16  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 /**
  21  * @file eail.h
  22  *
  23  * @brief Header for Eail initialization part
  24  */
  25
  26 /**
  27  * @mainpage Manual SDK
  28  *
  29  * @section Description
  30  * EAIL (Enlightenment Accessibility Implementation Library) is an implementation
  31  * of ATK (Accessibility Toolkit) - it allows to receive accessible content
  32  * representation for Elementary widgets.
  33  * EAIL is meant to be a bridge between Elementary and ATK, thus various ATs can query for
  34  * accessible information using AT-SPI2.
  35  * ATK is an accessibility toolkit conforming to the Section 508 Standards.
  36  * EAIL is developed as an Elementary module and loaded whenever Elementary
  37  * ELM_MODULES environmental variable is set  ("eail>eail/api" is appended).
  38  *
  39  * @section Setup
  40  * <p>In order to load properly, EAIL has to be installed in directory that is
  41  * used to store the rest of Elementary modules (directory path is architecture
  42  * dependent). Passing correct directory name is available via ./configure
  43  * option '--with-elementary-module'.</p>
  44  * <p>Below is sample configuration for x86_64
  45  * architecture:
  46  * @code
  47  * ./configure --with-elementary-modules=/usr/local/lib/elementary/modules/eail/linux-gnu-x86_64-1.7.99/
  48  * @endcode
  49  * </p>
  50  * <p>When EAIL module is installed, Elementary library has to be notified
  51  * about the new module - it needs to load EAIL module during startup.
  52  * This can be done using 'ELM_MODULES' environmental variable.</p>
  53  * <p>Below is a code snippet that shows how to set EAIL module load for the current
  54  * session:
  55  * @code
  56  * export ELM_MODULES="eail>eail/api"
  57  * @endcode
  58  *
  59  * NOTE: ELM_MODULES can also be set for every session using elementary configuration
  60  * files. Details on how to do that can be found in the Elementary documentation.
  61  *
  62  * <p>This is all configuration needed - now an elementary application can be
  63  * launched and accessible content for target application should be visible
  64  * when using accessibility clients (eg. ORCA, TADEK, accerciser...).</p>
  65  * </p>
  66  *
  67  * @section Architecture
  68  * <p>EAIL is implemented as a module of Enlightenment (it is located in Elementary
  69  * modules directory). When an elementary application is being
  70  * launched and ELM_MODULES is set correctly, then EAIL module is also loaded.
  71  * EAIL module registers itself to ATK bridge, so accessibility client
  72  * application (eg. ORCA, TADEK) can obtain information (in form of an accessible
  73  * ATK object) about every visible element in application UI.</p>
  74  * <p>
  75  * See the diagram of architecture below:
  76  * @image html eail_component_diagram.png
  77  * </p>
  78  *
  79  * @section Dataflow Data Flow
  80  * <p>When an accessibility client wants to get the accessible content of an application
  81  * it needs to get the 'root' ATK object for application. To do that, the client has to
  82  * call atk_get_root() on ATK/AT-SPI brigde. Request is propagated to EAIL which
  83  * creates a new instance of EailApp which is the ATK representation of the elementary
  84  * application.</p>
  85  * <p>
  86  * Below is a diagram that shows what is happening during that operation:
  87  * @image html eail_get_root_flow.png
  88  * </p>
  89  *
  90  * <p>When an accessibility client holds reference to the ATK root object (EailApp), it
  91  * can use an AtkObject interface to use the object's accessible functionality (eg.
  92  * get name, set/get description or, the most important one, get reference to
  93  * children)). To get widget's children, client has to call
  94  * <b>atk_object_ref_accessible_child.</b>
  95  * </p>
  96  * <p>
  97  * Below is a diagram that shows how an app child (EailWindow) is being created. For
  98  * other kinds of object data flow is very similar:
  99  * @image html eail_ref_window_child_flow.png
 100  * </p>
 101  *
 102  * @section Events
 103  * Following ATK event types are supported:
 104  * -# "focus"
 105  * -# "state-change"
 106  * -# "visible-data-changed"
 107  * -# "property-change"
 108  * <p>
 109  * NOTE: To receive events from EAIL widget, ATK-client application needs to
 110  * hold reference to the target widget (it can be achieved by eg. listing the whole
 111  * widget hierarchy tree). Without that event listener for widget won't be
 112  * registered and ATK events won't be propagated.
 113  * \n
 114  * To be sure that client always
 115  * has the correct widget tree, it needs to refresh the widget's descendants every time
 116  * it receives "visible-data-changed" event from ATK.
 117  * </p>
 118  * Below is an example on how to register for events using python pyatspi binding (
 119  * as mentioned above, all objects that we're interested in have to be listed at
 120  * first; below is a code snippet only for event registration for pyatspi part):
 121  * @code
 122  * pyatspi.Registry.registerEventListener(test_cb, "focus")
 123  * pyatspi.Registry.registerEventListener(test_cb, "object:state-changed")
 124  * pyatspi.Registry.registerEventListener(test_cb, "object:visible-data-changed")
 125  * pyatspi.Registry.registerEventListener(test_cb, "object:property-changed")
 126  *
 127  * pyatspi.Registry.start()
 128  *
 129  * @endcode
 130  *
 131  * @section Examples
 132  * <p>Below are some examples on how to use C API for ATK with EAIL.
 133  * </p>
 134  * <p>
 135  * How to get the root ATK object for the current application:
 136  * @code
 137  * AtkObject *atk_obj = atk_get_root();
 138  * @endcode
 139  * </p>
 140  *
 141  * <p>
 142  * How to get the children count for given ATK object:
 143  * @code
 144  * gint n = atk_object_get_n_accessible_children(atk_obj);
 145  * @endcode
 146  * </p>
 147  *
 148  * <p>
 149  * How to obtain a reference to the first child of ATK object:
 150  * @code
 151  * AtkObject *atk_obj = atk_object_ref_accessible_child(atk_obj, 0);
 152  * @endcode
 153  * </p>
 154  *
 155  * <p>
 156  * How to launch the first action of the given ATK object that supports ATK_ACTION
 157  * interface:
 158  * @code
 159  * gboolean success = atk_action_do_action(ATK_ACTION(atk_obj), 0);
 160  * @endcode
 161  * </p>
 162  *
 163  * <p>
 164  * How to get the name of an action with the given index ('1'):
 165  * @code
 166  * const gchar *action_name = atk_action_get_name(ATK_ACTION(atk_obj), 1);
 167  * @endcode
 168  * </p>
 169  *
 170  * Many more ready-to-go examples can be found in EAIL test code which can
 171  * be found in <b>tests/</b> directory.
 172  */
 173 #ifndef EAIL_H
 174 #define EAIL_H
 175
 176 #include "Elementary.h"
 177
 178 #ifdef __cplusplus
 179 extern "C" {
 180 #endif
 181
 182 EAPI int elm_modapi_init(void *m);
 183
 184 EAPI int elm_modapi_shutdown(void *m);
 185
 186 #ifdef __cplusplus
 187 }
 188 #endif
 189
 190 #endif