dali/devel-api/atspi-interfaces/table.h

   1 #ifndef DALI_ADAPTOR_ATSPI_TABLE_H
   2 #define DALI_ADAPTOR_ATSPI_TABLE_H
   3
   4 /*
   5  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 // EXTERNAL INCLUDES
  21 #include <string>
  22 #include <vector>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/devel-api/atspi-interfaces/accessible.h>
  26
  27 namespace Dali::Accessibility
  28 {
  29 class TableCell;
  30
  31 /**
  32  * @brief Interface representing a table.
  33  *
  34  * The selection methods extend the Selection interface,
  35  * so both should be implemented by table and grid controls.
  36  *
  37  * @see Dali::Accessibility::Selection
  38  * @see Dali::Accessibility::TableCell
  39  */
  40 class DALI_ADAPTOR_API Table : public virtual Accessible
  41 {
  42 public:
  43   /**
  44    * @brief Cell information type.
  45    *
  46    * @see Table:GetRowColumnSpan()
  47    */
  48   struct RowColumnSpanType
  49   {
  50     int row;         ///< Row index
  51     int column;      ///< Column index
  52     int rowSpan;     ///< Row span
  53     int columnSpan;  ///< Column span
  54     bool isSelected; ///< Whether the cell is selected
  55     bool success;    ///< Whether other fields are meaningful
  56   };
  57
  58   /**
  59    * @brief Gets the number of rows.
  60    *
  61    * @return Number of rows
  62    */
  63   virtual int GetRowCount() const = 0;
  64
  65   /**
  66    * @brief Gets the number of columns.
  67    *
  68    * @return Number of columns
  69    */
  70   virtual int GetColumnCount() const = 0;
  71
  72   /**
  73    * @brief Gets the number of selected rows.
  74    *
  75    * @return Number of selected rows
  76    *
  77    * @see Table::GetSelectedRows()
  78    */
  79   virtual int GetSelectedRowCount() const = 0;
  80
  81   /**
  82    * @brief Gets the number of selected columns.
  83    *
  84    * @return Number of selected columns
  85    *
  86    * @see Table::GetSelectedColumns()
  87    */
  88   virtual int GetSelectedColumnCount() const = 0;
  89
  90   /**
  91    * @brief Gets the table's caption.
  92    *
  93    * @return The caption or null
  94    */
  95   virtual Accessible* GetCaption() const = 0;
  96
  97   /**
  98    * @brief Gets the table's summary.
  99    *
 100    * @return The summary or null
 101    */
 102   virtual Accessible* GetSummary() const = 0;
 103
 104   /**
 105    * @brief Gets the cell at the specified position
 106    *
 107    * @param[in] row Row number
 108    * @param[in] column Column number
 109    *
 110    * @return The cell or null
 111    */
 112   virtual TableCell* GetCell(int row, int column) const = 0;
 113
 114   /**
 115    * @brief Gets the one-dimensional index of a cell
 116    *
 117    * The returned index should be such that:
 118    * @code GetChildAtIndex(GetChildIndex(row, column)) == GetCell(row, column) @endcode
 119    *
 120    * @param[in] row Row number
 121    * @param[in] column Column number
 122    *
 123    * @return The one-dimensional index
 124    *
 125    * @see Dali::Accessibility::Accessible::GetChildAtIndex()
 126    * @see Table::GetCell()
 127    */
 128   virtual std::size_t GetChildIndex(int row, int column) const = 0;
 129
 130   /**
 131    * @brief Gets the row number of a cell
 132    *
 133    * @param[in] childIndex One-dimensional index of the cell
 134    *
 135    * @return The row number of the cell
 136    *
 137    * @see Table::GetChildIndex()
 138    */
 139   virtual int GetRowByChildIndex(std::size_t childIndex) const = 0;
 140
 141   /**
 142    * @brief Gets the column number of a cell
 143    *
 144    * @param[in] childIndex One-dimensional index of the cell
 145    *
 146    * @return The column number of the cell
 147    *
 148    * @see Table::GetChildIndex()
 149    */
 150   virtual int GetColumnByChildIndex(std::size_t childIndex) const = 0;
 151
 152   /**
 153    * @brief Gets the description of a row.
 154    *
 155    * @param[in] row Row number
 156    *
 157    * @return The description of the row
 158    */
 159   virtual std::string GetRowDescription(int row) const = 0;
 160
 161   /**
 162    * @brief Gets the description of a column.
 163    *
 164    * @param[in] column Column number
 165    *
 166    * @return The description of the column
 167    */
 168   virtual std::string GetColumnDescription(int column) const = 0;
 169
 170   /**
 171    * @brief Gets the row span of a cell
 172    *
 173    * The return value should be such that:
 174    * @code GetRowSpan(row, column) == GetCell(row, column)->GetCellRowSpan() @endcode
 175    *
 176    * @param[in] row Row number
 177    * @param[in] column Column number
 178    *
 179    * @return The row span of the cell
 180    *
 181    * @see Table::GetCell()
 182    * @see Dali::Accessibility::TableCell::GetCellRowSpan()
 183    */
 184   virtual int GetRowSpan(int row, int column) const = 0;
 185
 186   /**
 187    * @brief Gets the column span of a cell
 188    *
 189    * The return value should be such that:
 190    * @code GetColumnSpan(row, column) == GetCell(row, column)->GetCellColumnSpan() @endcode
 191    *
 192    * @param[in] row Row number
 193    * @param[in] column Column number
 194    *
 195    * @return The column span of the cell
 196    *
 197    * @see Table::GetCell()
 198    * @see Dali::Accessibility::TableCell::GetCellColumnSpan()
 199    */
 200   virtual int GetColumnSpan(int row, int column) const = 0;
 201
 202   /**
 203    * @brief Gets the header of a row.
 204    *
 205    * @param[in] row Row number
 206    *
 207    * @return The row header or null
 208    */
 209   virtual Accessible* GetRowHeader(int row) const = 0;
 210
 211   /**
 212    * @brief Gets the header of a column.
 213    *
 214    * @param[in] column Column number
 215    *
 216    * @return The column header or null
 217    */
 218   virtual Accessible* GetColumnHeader(int column) const = 0;
 219
 220   /**
 221    * @brief Gets all selected rows' numbers.
 222    *
 223    * @return Selected rows' numbers
 224    *
 225    * @see Table::GetSelectedRowCount()
 226    */
 227   virtual std::vector<int> GetSelectedRows() const = 0;
 228
 229   /**
 230    * @brief Gets all selected columns' numbers.
 231    *
 232    * @return Selected columns' numbers
 233    *
 234    * @see Table::GetSelectedColumnCount()
 235    */
 236   virtual std::vector<int> GetSelectedColumns() const = 0;
 237
 238   /**
 239    * @brief Checks if a row is selected.
 240    *
 241    * @param[in] row Row number
 242    *
 243    * @return True if the row is selected, false otherwise
 244    */
 245   virtual bool IsRowSelected(int row) const = 0;
 246
 247   /**
 248    * @brief Checks if a column is selected.
 249    *
 250    * @param[in] column Column number
 251    *
 252    * @return True if the column is selected, false otherwise
 253    */
 254   virtual bool IsColumnSelected(int column) const = 0;
 255
 256   /**
 257    * @brief Checks if a cell is selected.
 258    *
 259    * @param[in] row Row number of the cell
 260    * @param[in] column Column number of the cell
 261    *
 262    * @return True if the cell is selected, false otherwise
 263    */
 264   virtual bool IsCellSelected(int row, int column) const = 0;
 265
 266   /**
 267    * @brief Selects a row.
 268    *
 269    * @param[in] row Row number
 270    *
 271    * @return True on success, false otherwise
 272    */
 273   virtual bool AddRowSelection(int row) = 0;
 274
 275   /**
 276    * @brief Selects a column.
 277    *
 278    * @param[in] column Column number
 279    *
 280    * @return True on success, false otherwise
 281    */
 282   virtual bool AddColumnSelection(int column) = 0;
 283
 284   /**
 285    * @brief Unselects a row.
 286    *
 287    * @param[in] row Row number
 288    *
 289    * @return True on success, false otherwise
 290    */
 291   virtual bool RemoveRowSelection(int row) = 0;
 292
 293   /**
 294    * @brief Unselects a column.
 295    *
 296    * @param[in] column Column number
 297    *
 298    * @return True on success, false otherwise
 299    */
 300   virtual bool RemoveColumnSelection(int column) = 0;
 301
 302   /**
 303    * @brief Returns position and span information about a cell.
 304    *
 305    * @param[in] childIndex One-dimensional index of the cell
 306    *
 307    * @return The 'status' field of the returned structure is true on success, false otherwise
 308    *
 309    * @see Table::RowColumnSpanType
 310    */
 311   virtual RowColumnSpanType GetRowColumnSpan(std::size_t childIndex) const = 0;
 312
 313   /**
 314    * @brief Downcasts an Accessible to a Table.
 315    *
 316    * @param obj The Accessible
 317    * @return A Table or null
 318    *
 319    * @see Dali::Accessibility::Accessible::DownCast()
 320    */
 321   static inline Table* DownCast(Accessible* obj);
 322 };
 323
 324 namespace Internal
 325 {
 326 template<>
 327 struct AtspiInterfaceTypeHelper<AtspiInterface::TABLE>
 328 {
 329   using Type = Table;
 330 };
 331 } // namespace Internal
 332
 333 inline Table* Table::DownCast(Accessible* obj)
 334 {
 335   return Accessible::DownCast<AtspiInterface::TABLE>(obj);
 336 }
 337
 338 } // namespace Dali::Accessibility
 339
 340 #endif // DALI_ADAPTOR_ATSPI_TABLE_H