<page xmlns="http://projectmallard.org/1.0/" type="topic" id="event_monitor_plugin">
  <info>
    <link type="guide" xref="index#examining_a11y" />
    <title type="sort">4. Event Monitor Plugin</title>
    <link type="next" xref="quick_select_plugin" />
    <desc>
      Monitoring accessible events as they occur
    </desc>
    <credit type="author">
      <name>Eitan Isaacson</name>
      <email>eitan@ascender.com</email>
    </credit>
    <credit type="author">
      <name>Peter Parente</name>
      <email>pparent@us.ibm.com</email>
    </credit>
    <credit type="author">
      <name>Aline Bessa</name>
      <email>alibezz@gmail.com</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title> Event Monitor Plugin</title>
  <p>
    The Event Monitor Plugin allows you to view 
    <link href="http://accessibility.linuxfoundation.org/a11yspecs/atspi/adoc/atspi-events.html">AT-SPI events</link>
    as they occur on the applications exposed in <app>Accerciser</app>'s
    <link xref="desktop_tree_view">Application Tree View</link>. The plugin is useful to explore the dynamics of an 
    application's interface and verify which accessible widgets are related to which AT-SPI events.
  </p>

  <figure>
    <title>Event Monitor Plugin</title>
    <desc>
      The Event Monitor Plugin allows you to view AT-SPI events and match them
      with accessible widgets. 
    </desc>
    <media type="image" mime="image/png" width="700" height="500" src="figures/event_monitor_plugin.png">
      <p>
       The Event Monitor Plugin allows you to view AT-SPI events and match them
       with accessible widgets.
      </p>
    </media>
  </figure>

  <section id="running_event_monitor_plugin">
    <title>Running the Event Monitor Plugin</title>
    <p>
      When you open the Event Monitor Plugin, you see a list of checkboxes
      representing all the different AT-SPI event classes covered by the
      plugin:
    </p>

    <list>
      <item>
        <p>
          document
        </p>
      </item>
      <item>
        <p>
          focus
        </p>
      </item>
      <item>
        <p>
          mouse
        </p>
      </item>
      <item>
        <p>
          object
        </p>
      </item>
      <item>
        <p>
          terminal
        </p>
      </item>
      <item>
        <p>
          window
        </p>
      </item>
    </list>

    <p>
      If you check a class,
      all of its event types will be monitored by the plugin. The classes
      are exposed as tree structures; therefore, you can refine your selection
      by expanding them and checking only the event types you really care about.
    </p>
    <p>  
      If you want to monitor all possible types of AT-SPI events, press the <cmd>Select All</cmd>
      button. Similarly, if you want to clear all currently selected event types,
      press the <cmd>Clear Selection</cmd> button.
    </p>

    <note style="tip">
      <p>
        Selecting only a few event types per monitoring gives you a clearer output. 
      </p>
    </note>

    <p>  
      Another way to refine event monitoring is by the event source. By default, the Source option <cmd>Everything</cmd>
      is selected, indicating that AT-SPI events of all applications will be monitored.
      If you want to investigate a single application, select it
      in the Application Tree View and click the Source radio button <cmd>Selected application</cmd>. Likewise,
      if you want to monitor a single accessible widget and its corresponding descendants,
      select it in the Application Tree View and click the Source radio button <cmd>Selected accessible</cmd>.
    </p>

    <p>
      After selecting event types and specifying a Source option, the Event Monitor Plugin starts
      monitoring AT-SPI events automatically, because the <cmd>Monitor Events</cmd> button is
      pressed by default. Whenever you want to stop monitoring, click the <cmd>Monitor Events</cmd>
      button. To restart monitoring, press this button again.
    </p>
    
    <p>
      For each incoming event, the Event Monitor Plugin indicates the source and the application. Activating the
      link for either of these items will cause it to become selected in the Application Tree View.
    </p>

    <p>
      If you want to save the output generated by the Event Monitor Plugin,
      just press the <cmd>Save</cmd> button. To clear the output screen, you just need to
      click the <cmd>Clear</cmd> button.
    </p>
  </section>
</page>
