path: root/atspi/atspi-table.c

/*
 * AT-SPI - Assistive Technology Service Provider Interface
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001, 2002 Sun Microsystems Inc.,
 * Copyright 2001, 2002 Ximian, Inc.
 * Copyright 2010, 2011 Novell, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

#include "atspi-private.h"
#include <stdlib.h> /* for malloc */

/**
 * AtspiTable:
 *
 * An interface used by containers whose data is arranged in a tabular form.
 *
 * An interface used by containers whose contained data is arranged
 * in a tabular (i.e. row-column) form. Tables may resemble
 * a two-dimensional grid, as in a spreadsheet, or may feature objects
 * which span multiple rows and/or columns, but whose bounds are
 * aligned on a row/column matrix. Objects within tables are children
 * of the table object, and they may be referenced either via a child
 * index or via a row/column pair. Table 'cells' may implement other
 * interfaces, such as Text, Action, Image, and Component, and should do
 * so as appropriate to their onscreen presentation and/or behavior.
 */

/**
 * atspi_table_get_caption:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Gets an accessible representation of the caption for an #AtspiTable.
 *
 * Returns: (transfer full): an #AtspiAccessible object that serves as
 * the table's caption.
 *
 **/
AtspiAccessible *
atspi_table_get_caption (AtspiTable *obj, GError **error)
{
  AtspiAccessible *retval = NULL;

  g_return_val_if_fail (obj != NULL, NULL);

  _atspi_dbus_get_property (obj, atspi_interface_table, "Caption", error, "(so)", &retval);
  return retval;
}

/**
 * atspi_table_get_summary:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Gets an accessible object which summarizes the contents of an #AtspiTable.
 *
 * Returns: (transfer full): an #AtspiAccessible object that serves as the
 *          table's summary (often a reduced #AtspiTable).
 **/
AtspiAccessible *
atspi_table_get_summary (AtspiTable *obj, GError **error)
{
  AtspiAccessible *retval;

  g_return_val_if_fail (obj != NULL, NULL);

  _atspi_dbus_get_property (obj, atspi_interface_table, "Summary", error, "(so)", &retval);

  return retval;
}

/**
 * atspi_table_get_n_rows:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Gets the number of rows in an #AtspiTable,
 *        exclusive of any rows that are programmatically hidden, but inclusive
 *        of rows that may be outside of the current scrolling window or viewport.
 *
 * Returns: a #gint indicating the number of rows in the table.
 **/
gint
atspi_table_get_n_rows (AtspiTable *obj, GError **error)
{
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_get_property (obj, atspi_interface_table, "NRows", error, "i", &retval);

  return retval;
}

/**
 * atspi_table_get_n_columns:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Gets the number of columns in an #AtspiTable,
 *        exclusive of any columns that are programmatically hidden, but inclusive
 *        of columns that may be outside of the current scrolling window or viewport.
 *
 * Returns: a #gint indicating the number of columns in the table.
 **/
gint
atspi_table_get_n_columns (AtspiTable *obj, GError **error)
{
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_get_property (obj, atspi_interface_table, "NColumns", error, "i", &retval);

  return retval;
}

/**
 * atspi_table_get_accessible_at:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 * @column: the specified table column, zero-indexed.
 *
 * Gets the table cell at the specified row and column indices.
 * To get the accessible object at a particular (x, y) screen
 * coordinate, use #atspi_component_get_accessible_at_point.
 *
 * Returns: (transfer full): an #AtspiAccessible object representing the
 *          specified table cell.
 **/
AtspiAccessible *
atspi_table_get_accessible_at (AtspiTable *obj,
                               gint row,
                               gint column,
                               GError **error)
{
  dbus_int32_t d_row = row, d_column = column;
  DBusMessage *reply;

  g_return_val_if_fail (obj != NULL, NULL);

  reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetAccessibleAt", error, "ii", d_row, d_column);

  return _atspi_dbus_return_accessible_from_message (reply);
}

/**
 * atspi_table_get_index_at:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 * @column: the specified table column, zero-indexed.
 *
 * Gets the 1-D child index corresponding to the specified 2-D row and
 * column indices. To get the accessible object at a particular (x, y) screen
 * coordinate, use #atspi_component_get_accessible_at_point.
 *
 * @see #atspi_table_get_row_at_index, #atspi_table_get_column_at_index
 *
 * Returns: a #gint which serves as the index of a specified cell in the
 *          table, in a form usable by #atspi_get_child_at_index.
 **/
gint
atspi_table_get_index_at (AtspiTable *obj,
                          gint row,
                          gint column,
                          GError **error)
{
  dbus_int32_t d_row = row, d_column = column;
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_call (obj, atspi_interface_table, "GetIndexAt", error, "ii=>i", d_row, d_column, &retval);

  return retval;
}

/**
 * atspi_table_get_row_at_index:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @index: the specified child index, zero-indexed.
 *
 * Gets the table row index occupied by the child at a particular 1-D
 * child index.
 *
 * @see #atspi_table_get_index_at, #atspi_table_get_column_at_index
 *
 * Returns: a #gint indicating the first row spanned by the child of a
 *          table, at the specified 1-D (zero-offset) @index.
 **/
gint
atspi_table_get_row_at_index (AtspiTable *obj,
                              gint index,
                              GError **error)
{
  dbus_int32_t d_index = index;
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_call (obj, atspi_interface_table, "GetRowAtIndex", error, "i=>i", d_index, &retval);

  return retval;
}

/**
 * atspi_table_get_column_at_index:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @index: the specified child index, zero-indexed.
 *
 * Gets the table column index occupied by the child at a particular 1-D
 * child index.
 *
 * @see #atspi_table_get_index_at, #atspi_table_get_row_at_index
 *
 * Returns: a #gint indicating the first column spanned by the child of a
 *          table, at the specified 1-D (zero-offset) @index.
 **/
gint
atspi_table_get_column_at_index (AtspiTable *obj,
                                 gint index,
                                 GError **error)
{
  dbus_int32_t d_index = index;
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_call (obj, atspi_interface_table, "GetColumnAtIndex", error, "i=>i", d_index, &retval);

  return retval;
}

/**
 * atspi_table_get_row_description:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 *
 * Gets a text description of a particular table row.  This differs from
 * #atspi_table_get_row_header, which returns an #AtspiAccessible.
 *
 * Returns: a UTF-8 string describing the specified table row, if available.
 **/
gchar *
atspi_table_get_row_description (AtspiTable *obj,
                                 gint row,
                                 GError **error)
{
  dbus_int32_t d_row = row;
  char *retval = NULL;

  g_return_val_if_fail (obj != NULL, NULL);

  _atspi_dbus_call (obj, atspi_interface_table, "GetRowDescription", error, "i=>s", d_row, &retval);

  return retval;
}

/**
 * atspi_table_get_column_description:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @column: the specified table column, zero-indexed.
 *
 * Gets a text description of a particular table column.  This differs from
 * #atspi_table_get_column_header, which returns an #Accessible.
 *
 * Returns: a UTF-8 string describing the specified table column, if available.
 **/
gchar *
atspi_table_get_column_description (AtspiTable *obj,
                                    gint column,
                                    GError **error)
{
  dbus_int32_t d_column = column;
  char *retval = NULL;

  g_return_val_if_fail (obj != NULL, NULL);

  _atspi_dbus_call (obj, atspi_interface_table, "GetColumnDescription", error, "i=>s", d_column, &retval);

  return retval;
}

/**
 * atspi_table_get_row_extent_at:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 * @column: the specified table column, zero-indexed.
 *
 * Gets the number of rows spanned by the table cell at the specific row
 * and column. (some tables can have cells which span multiple rows
 * and/or columns).
 * The returned values are meaningful only if the Table has both
 * STATE_VISIBLE and STATE_SHOWING.
 *
 * Returns: a #gint indicating the number of rows spanned by the specified cell.
 **/
gint
atspi_table_get_row_extent_at (AtspiTable *obj,
                               gint row,
                               gint column,
                               GError **error)
{
  dbus_int32_t d_row = row, d_column = column;
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_call (obj, atspi_interface_table, "GetRowExtentAt", error, "ii=>i", d_row, d_column, &retval);

  return retval;
}

/**
 * atspi_table_get_column_extent_at:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 * @column: the specified table column, zero-indexed.
 *
 * Gets the number of columns spanned by the table cell at the specific
 * row and column (some tables can have cells which span multiple
 * rows and/or columns).
 * The returned values are meaningful only if the Table has both
 * STATE_VISIBLE and STATE_SHOWING.
 *
 * Returns: a #gint indicating the number of columns spanned by the specified cell.
 **/
gint
atspi_table_get_column_extent_at (AtspiTable *obj,
                                  gint row,
                                  gint column,
                                  GError **error)
{
  dbus_int32_t d_row = row, d_column = column;
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_call (obj, atspi_interface_table, "GetColumnExtentAt", error, "ii=>i", d_row, d_column, &retval);

  return retval;
}

/**
 * atspi_table_get_row_header:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the specified table row, zero-indexed.
 *
 * Gets the header associated with a table row, if available. This differs from
 * #atspi_table_get_row_description, which returns a string.
 *
 * Returns: (transfer full): an #AtspiAccessible representation of the specified
 *          table row, if available.
 **/
AtspiAccessible *
atspi_table_get_row_header (AtspiTable *obj,
                            gint row,
                            GError **error)
{
  dbus_int32_t d_row = row;
  DBusMessage *reply;

  g_return_val_if_fail (obj != NULL, NULL);

  reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetRowHeader", error, "i", d_row);

  return _atspi_dbus_return_accessible_from_message (reply);
}

/**
 * atspi_table_get_column_header:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @column: the specified table column, zero-indexed.
 *
 * Gets the header associated with a table column, if available.
 * This differs from #atspi_table_get_column_description, which
 * returns a string.
 *
 * Returns: (transfer full): an #AtspiAccessible representation of the
 *          specified table column, if available.
 **/
AtspiAccessible *
atspi_table_get_column_header (AtspiTable *obj,
                               gint column,
                               GError **error)
{
  dbus_int32_t d_column = column;
  DBusMessage *reply;

  g_return_val_if_fail (obj != NULL, NULL);

  reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetColumnHeader", error, "i", d_column);

  return _atspi_dbus_return_accessible_from_message (reply);
}

/**
 * atspi_table_get_n_selected_rows:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Query a table to find out how many rows are currently selected.
 * Not all tables support row selection.
 *
 * Returns: a #gint indicating the number of rows currently selected.
 **/
gint
atspi_table_get_n_selected_rows (AtspiTable *obj, GError **error)
{
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_get_property (obj, atspi_interface_table, "NSelectedRows", error, "i", &retval);

  return retval;
}

/**
 * atspi_table_get_selected_rows:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Queries a table for a list of indices of rows which are currently selected.
 *
 * Returns: (element-type gint) (transfer full): an array of #gint values,
 *          specifying which rows are currently selected.
 **/
GArray *
atspi_table_get_selected_rows (AtspiTable *obj,
                               GError **error)
{
  GArray *rows = NULL;

  g_return_val_if_fail (obj != NULL, 0);

  _atspi_dbus_call (obj, atspi_interface_table, "GetSelectedRows", error, "=>ai", &rows);

  return rows;
}

/**
 * atspi_table_get_selected_columns:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Queries a table for a list of indices of columns which are currently
 * selected.
 *
 * Returns: (element-type gint) (transfer full): an array of #gint values,
 *          specifying which columns are currently selected.
 **/
GArray *
atspi_table_get_selected_columns (AtspiTable *obj,
                                  GError **error)
{
  GArray *columns = NULL;

  g_return_val_if_fail (obj != NULL, 0);

  _atspi_dbus_call (obj, atspi_interface_table, "GetSelectedColumns", error, "=>ai", &columns);

  return columns;
}

/**
 * atspi_table_get_n_selected_columns:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 *
 * Queries a table to find out how many columns are currently selected.
 * Not all tables support column selection.
 *
 * Returns: a #gint indicating the number of columns currently selected.
 **/
gint
atspi_table_get_n_selected_columns (AtspiTable *obj, GError **error)
{
  dbus_int32_t retval = -1;

  g_return_val_if_fail (obj != NULL, -1);

  _atspi_dbus_get_property (obj, atspi_interface_table, "NSelectedColumns", error, "i", &retval);

  return retval;
}

/**
 * atspi_table_is_row_selected:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the zero-indexed row number of the row being queried.
 *
 * Determines whether a table row is selected.  Not all tables support
 * row selection.
 *
 * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
 **/
gboolean
atspi_table_is_row_selected (AtspiTable *obj,
                             gint row,
                             GError **error)
{
  dbus_int32_t d_row = row;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "IsRowSelected", error, "i=>b", d_row, &retval);

  return retval;
}

/**
 * atspi_table_is_column_selected:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @column: the zero-indexed column number of the column being queried.
 *
 * Determines whether specified table column is selected.
 * Not all tables support column selection.
 *
 * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
 **/
gboolean
atspi_table_is_column_selected (AtspiTable *obj,
                                gint column,
                                GError **error)
{
  dbus_int32_t d_column = column;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "IsColumnSelected", error, "i=>b", d_column, &retval);

  return retval;
}

/**
 * atspi_table_add_row_selection:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the zero-indexed row number of the row being selected.
 *
 * Selects the specified row, adding it to the current row selection.
 * Not all tables support row selection.
 *
 * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
 **/
gboolean
atspi_table_add_row_selection (AtspiTable *obj,
                               gint row,
                               GError **error)
{
  dbus_int32_t d_row = row;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "AddRowSelection", error, "i=>b", d_row, &retval);

  return retval;
}

/**
 * atspi_table_add_column_selection:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @column: the zero-indexed column number of the column being selected.
 *
 * Selects the specified column, adding it to the current column selection.
 * Not all tables support column selection.
 *
 * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
 **/
gboolean
atspi_table_add_column_selection (AtspiTable *obj,
                                  gint column,
                                  GError **error)
{
  dbus_int32_t d_column = column;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "AddColumnSelection", error, "i=>b", d_column, &retval);

  return retval;
}

/**
 * atspi_table_remove_row_selection:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the zero-indexed number of the row being de-selected.
 *
 * De-selects the specified row, removing it from the current row selection.
 * Not all tables support row selection.
 *
 * Returns: #TRUE if the specified row was successfully de-selected,
 * #FALSE if not.
 **/
gboolean
atspi_table_remove_row_selection (AtspiTable *obj,
                                  gint row,
                                  GError **error)
{
  dbus_int32_t d_row = row;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "RemoveRowSelection", error, "i=>b", d_row, &retval);

  return retval;
}

/**
 * atspi_table_remove_column_selection:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @column: the zero-indexed column number of the column being de-selected.
 *
 * De-selects the specified column, removing it from the current column
 * selection.
 * Not all tables support column selection.
 *
 * Returns: #TRUE if the specified column was successfully de-selected,
 * #FALSE if not.
 **/
gboolean
atspi_table_remove_column_selection (AtspiTable *obj,
                                     gint column,
                                     GError **error)
{
  dbus_int32_t d_column = column;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "RemoveColumnSelection", error, "i=>b", d_column, &retval);

  return retval;
}

/**
 * atspi_table_get_row_column_extents_at_index:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @index: the index of the #AtspiTable child whose row/column
 * extents are requested.
 * @row: (out): back-filled with the first table row associated with
 * the cell with child index.
 * @col: (out): back-filled with the first table column associated
 * with the cell with child index.
 * @row_extents: (out): back-filled with the number of table rows
 * across which child i extends.
 * @col_extents: (out): back-filled with the number of table columns
 * across which child i extends.
 * @is_selected: (out): a boolean which is back-filled with #TRUE
 * if the child at index i corresponds to a selected table cell,
 * #FALSE otherwise.
 *
 * Given a child index, determines the row and column indices and
 * extents, and whether the cell is currently selected.  If
 * the child at index is not a cell (for instance, if it is
 * a summary, caption, etc.), #FALSE is returned.
 * The returned values are meaningful only if the Table has both
 * STATE_VISIBLE and STATE_SHOWING.
 *
 * Example:
 * If the #AtspiTable child at index '6' extends across columns 5 and 6 of
 * row 2 of an #AtspiTable instance, and is currently selected, then
 *
 * retval = atspi_table_get_row_column_extents_at_index (table, 6,
 *                                             row, col,
 *                                             row_extents,
 *                                             col_extents,
 *                                             is_selected);
 *
 * will return #TRUE, and after the call
 * row, col, row_extents, col_extents,
 * and is_selected will contain 2, 5, 1, 2, and
 * #TRUE, respectively.
 *
 * Returns: #TRUE if the index is associated with a valid table
 * cell, #FALSE if the index does not correspond to a cell.  If
 * #FALSE is returned, the values of the out parameters are
 * undefined.
 **/
gboolean
atspi_table_get_row_column_extents_at_index (AtspiTable *obj,
                                             gint index,
                                             gint *row,
                                             gint *col,
                                             gint *row_extents,
                                             gint *col_extents,
                                             gboolean *is_selected,
                                             GError **error)
{
  dbus_int32_t d_index = index;
  dbus_bool_t retval = FALSE;
  dbus_int32_t d_row = 0, d_col = 0, d_row_extents = 0, d_col_extents = 0;
  dbus_bool_t d_is_selected = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "GetRowColumnExtentsAtIndex",
                    error, "i=>biiiib", d_index, &retval, &d_row, &d_col,
                    &d_row_extents, &d_col_extents, &d_is_selected);

  *row = d_row;
  *col = d_col;
  *row_extents = d_row_extents;
  ;
  *col_extents = d_col_extents;
  *is_selected = d_is_selected;
  ;

  return retval;
}

/**
 * atspi_table_is_selected:
 * @obj: a pointer to the #AtspiTable implementor on which to operate.
 * @row: the zero-indexed row of the cell being queried.
 * @column: the zero-indexed column of the cell being queried.
 *
 * Determines whether the cell at a specific row and column is selected.
 *
 * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
 **/
gboolean
atspi_table_is_selected (AtspiTable *obj,
                         gint row,
                         gint column,
                         GError **error)
{
  dbus_int32_t d_row = row, d_column = column;
  dbus_bool_t retval = FALSE;

  g_return_val_if_fail (obj != NULL, FALSE);

  _atspi_dbus_call (obj, atspi_interface_table, "IsSelected", error, "ii=>b", d_row, d_column, &retval);

  return retval;
}

static void
atspi_table_base_init (AtspiTable *klass)
{
}

GType
atspi_table_get_type (void)
{
  static GType type = 0;

  if (!type)
    {
      static const GTypeInfo tinfo = {
        sizeof (AtspiTable),
        (GBaseInitFunc) atspi_table_base_init,
        (GBaseFinalizeFunc) NULL,
      };

      type = g_type_register_static (G_TYPE_INTERFACE, "AtspiTable", &tinfo, 0);
    }
  return type;
}