cthulhu/help/C/howto_tables.page

<page xmlns="http://projectmallard.org/1.0/" type="topic" id="howto_tables">
  <info>
    <link type="guide" xref="index#reading"/>
    <link type="next" xref="howto_forms" />
    <title type="sort">4. Tables</title>
    <desc>
      Navigating and setting dynamic headers
    </desc>
    <credit type="author">
      <name>Joanmarie Diggs</name>
      <email>joanied@gnome.org</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title>Tables</title>
  <p>
    <app>Cthulhu</app> provides several features specifically designed to improve
    access to tables found in web pages and other documents: configurable cell
    versus row reading, <link xref="howto_structural_navigation">Structural
    Navigation</link> and Dynamic Headers.
  </p>
  <section id="cell_row">
    <title>Cell Versus Row Reading</title>
    <p>
      Consider the process of examining the list of messages in your Inbox.
      In order to have Cthulhu announce the sender, subject, date, and presence
      of attachments you would need <app>Cthulhu</app> to speak the row. On the
      other hand, when navigating amongst rows in a spreadsheet, hearing the
      full row may not be desired if for no other reason than the sheer number
      of cells in each row. Thus in that case, you would want <app>Cthulhu</app>
      to only speak the cell with focus. Similar situations occur in document
      tables.
    </p>
    <p>
      <app>Cthulhu</app> allows you to customize whether only the cell should be
      read, or if the full row should be, for GUI tables, document tables,
      and spreadsheets. Because these settings are independent of one another,
      you do not have to choose one table reading mode to fit multiple types of
      tables.
    </p>
    <p>
      You can set each of <app>Cthulhu</app>'s table reading preferences <app>Cthulhu</app>
      wide as well as on an application-by-application basis. How to do each is
      described in the guide on <link xref="preferences"><app>Cthulhu</app>'s preferences
      dialogs</link>. The settings can be found on the <link xref="preferences_speech">
      <gui>Speech</gui> page</link>.
    </p>
    <p>
      Lastly, there is also an <app>Cthulhu</app> command which allows you to toggle
      cell versus row reading on the fly for the currently-active table:
      <keyseq><key>Cthulhu Modifier</key><key>F11</key></keyseq>.
    </p>
  </section>
  <section id="structural_navigation">
    <title>Structural Navigation</title>
    <p>
      <app>Cthulhu</app>'s <link xref="commands_structural_navigation#tables">table
      Structural Navigation commands</link> make it possible for you to quickly
      locate tables, jump immediately to a table's first or last cell, and
      move to the next cell in any direction.
    </p>
    <p>
      As you navigate amongst and within tables using Structural Navigation,
      <app>Cthulhu</app> will announce additional details to help you understand
      your position, such as the dimensions of the table you just entered and
      the fact that you have reached the edge of the table in the direction you
      are moving.
    </p>
    <p>
      In addition, <app>Cthulhu</app> provides configurable
      <link xref="preferences_table_navigation">presentation options</link>
      which work in conjunction with Structural Navigation and allow you to
      control whether or not cell coordinates are presented, multiple cell spans
      are indicated, and cell headers are announced.
    </p>
    <note style="tip">
      <title>Don't Forget To Toggle Structural Navigation On!</title>
      <p>
        Depending on where you are, it may be necessary for you to explicitly
        toggle Structural Navigation on before you can use it. To learn more, read
        <link xref="howto_structural_navigation#toggling_required">
        when toggling Structural Navigation on is required.</link>
      </p>
    </note>
  </section>
  <section id="dynamic_headers">
    <title>Dynamic Headers</title>
    <p>
      Many of the tables you will encounter while reading have cells which serve
      as the header for a row or a column. Whether or not the creator of that
      table correctly marked those cells as headers is hard to say. In many
      cases, the text was simply formatted to be larger and/or bold. And even if
      the table is correctly marked up, that is no guarantee that the application
      or toolkit exposes that text as header information to assistive technologies.
      <app>Cthulhu</app>'s Dynamic Header support makes it possible to overcome these
      challenges.
    </p>
    <steps>
      <title>Setting Column Headers</title>
      <item>
        <p>
          Move to the row which contains all of the column headers.
        </p>
      </item>
      <item>
        <p>
          Press <keyseq><key>Cthulhu Modifier</key><key>R</key></keyseq> to tell
          <app>Cthulhu</app> that the current row is the one with the headers.
        </p>
      </item>
    </steps>
    <steps>
      <title>Setting Row Headers</title>
      <item>
        <p>
          Move to the column which contains all of the row headers.
        </p>
      </item>
      <item>
        <p>
          Press <keyseq><key>Cthulhu Modifier</key><key>C</key></keyseq> to tell
          <app>Cthulhu</app> that the current column is the one with the headers.
        </p>
      </item>
    </steps>
    <p>
      Having set either the column headers or the row headers, you should find
      that as you navigate amongst the cells, <app>Cthulhu</app> will present each
      header that has changed. Or to put it another way, <app>Cthulhu</app> will
      not present the column header over and over again as you move up or down
      within the current column. Likewise, it will not present the row header
      over and over again as you move left or right within the current row.
      However, if you change rows and there are row headers, the header
      associated with the new row will be presented. And if you change columns
      and there are column headers, the header associated with the new column
      will be presented.
    </p>
    <p>
      To clear headers, simply double-click the command you used to set them.
      Thus double-clicking <keyseq><key>Cthulhu Modifier</key><key>R</key></keyseq>
      tells <app>Cthulhu</app> there are no column headers. Double-clicking 
      <keyseq><key>Cthulhu Modifier</key><key>C</key></keyseq> tells <app>Cthulhu</app>
      there are no row headers.
    </p>
  </section>
</page>