include/svtools/table/tablemodel.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SVTOOLS_TABLE_TABLEMODEL_HXX
  21 #define INCLUDED_SVTOOLS_TABLE_TABLEMODEL_HXX
  22
  23 #include <svtools/svtdllapi.h>
  24 #include <svtools/table/tabletypes.hxx>
  25 #include <svtools/table/tablerenderer.hxx>
  26 #include <svtools/table/tableinputhandler.hxx>
  27
  28 #include <com/sun/star/style/VerticalAlignment.hpp>
  29 #include <com/sun/star/style/HorizontalAlignment.hpp>
  30
  31 #include <sal/types.h>
  32
  33 #include <boost/optional.hpp>
  34 #include <memory>
  35 #include <o3tl/typed_flags_set.hxx>
  36
  37 namespace svt { namespace table { class ITableDataSort; } }
  38
  39 class Color;
  40
  41 enum class ColumnAttributeGroup
  42 {
  43     NONE          = 0x00,
  44     /// denotes column attributes related to the width of the column
  45     WIDTH         = 0x01,
  46     /// denotes column attributes related to the appearance of the column, i.e. those relevant for rendering
  47     APPEARANCE    = 0x02,
  48     /// denotes the entirety of column attributes
  49     ALL           = 0x03,
  50 };
  51 namespace o3tl
  52 {
  53     template<> struct typed_flags<ColumnAttributeGroup> : is_typed_flags<ColumnAttributeGroup, 0x03> {};
  54 }
  55
  56
  57 namespace svt { namespace table
  58 {
  59     //= ScrollbarVisibility
  60     enum ScrollbarVisibility
  61     {
  62         /** enumeration value denoting that a scrollbar should never be visible, even
  63             if needed normally
  64         */
  65         ScrollbarShowNever,
  66         /** enumeration value denoting that a scrollbar should be visible when needed only
  67         */
  68         ScrollbarShowSmart,
  69         /** enumeration value denoting that a scrollbar should always be visible, even
  70             if not needed normally
  71         */
  72         ScrollbarShowAlways
  73     };
  74
  75
  76     //= ITableModelListener
  77
  78     /** declares an interface to be implemented by components interested in
  79         changes in an ->ITableModel
  80     */
  81     class SAL_NO_VTABLE ITableModelListener : public std::enable_shared_from_this< ITableModelListener >
  82     {
  83     public:
  84         /** notifies the listener that one or more rows have been inserted into
  85             the table
  86
  87             @param first
  88                 the index of the first newly inserted row
  89             @param last
  90                 the index of the last newly inserted row. Must not be smaller
  91                 than ->first
  92         */
  93         virtual void    rowsInserted( RowPos first, RowPos last ) = 0;
  94
  95         /** notifies the listener that one or more rows have been removed from
  96             the table
  97
  98             @param first
  99                 the old index of the first removed row. If this is <code>-1</code>, then all
 100                 rows have been removed from the model.
 101             @param last
 102                 the old index of the last removed row. Must not be smaller
 103                 than ->first
 104         */
 105         virtual void    rowsRemoved( RowPos first, RowPos last ) = 0;
 106
 107         /** notifies the listener that one or more columns have been inserted into
 108             the table
 109         */
 110         virtual void    columnInserted() = 0;
 111
 112         /** notifies the listener that one or more columns have been removed from
 113             the table
 114         */
 115         virtual void    columnRemoved() = 0;
 116
 117         /** notifies the listener that all columns have been removed form the model
 118         */
 119         virtual void    allColumnsRemoved() = 0;
 120
 121         /** notifies the listener that a rectangular cell range in the table
 122             has been updated
 123
 124             Listeners are required to discard any possibly cached information
 125             they have about the cells in question, in particular any possibly
 126             cached cell values.
 127         */
 128         virtual void    cellsUpdated( RowPos const i_firstRow, RowPos const i_lastRow ) = 0;
 129
 130         /** notifies the listener that attributes of a given column changed
 131
 132             @param i_column
 133                 the position of the column whose attributes changed
 134             @param i_attributeGroup
 135                 a combination of one or more <code>COL_ATTRS_*</code> flags, denoting the attribute group(s)
 136                 in which changes occurred.
 137         */
 138         virtual void    columnChanged( ColPos const i_column, ColumnAttributeGroup const i_attributeGroup ) = 0;
 139
 140         /** notifies the listener that the metrics of the table changed.
 141
 142             Metrics here include the column header height, the row header width, the row height, and the presence
 143             of both the row and column header.
 144         */
 145         virtual void    tableMetricsChanged() = 0;
 146
 147         /// deletes the listener instance
 148         virtual ~ITableModelListener(){};
 149     };
 150     typedef std::shared_ptr< ITableModelListener > PTableModelListener;
 151
 152
 153     //= IColumnModel
 154
 155     /** interface to be implemented by table column models
 156     */
 157     class SAL_NO_VTABLE IColumnModel
 158     {
 159     public:
 160         /** returns the name of the column
 161
 162             Column names should be human-readable, but not necessarily unique
 163             within a given table.
 164
 165             @see setName
 166         */
 167         virtual OUString      getName() const = 0;
 168
 169         /** retrieves the help text to be displayed for the column.
 170         */
 171         virtual OUString      getHelpText() const = 0;
 172
 173         /** determines whether the column can be interactively resized
 174
 175             @see getMinWidth
 176             @see getMaxWidth
 177             @see getWidth
 178         */
 179         virtual bool        isResizable() const = 0;
 180
 181         /** denotes the relative flexibility of the column
 182
 183             This flexibility is taken into account when a table control auto-resizes its columns, because the available
 184             space changed. In this case, the columns grow or shrink according to their flexibility.
 185
 186             A value of 0 means the column is not auto-resized at all.
 187         */
 188         virtual sal_Int32   getFlexibility() const = 0;
 189
 190         /** returns the width of the column, in app-font units
 191
 192             The returned value must be a positive ->TableMetrics value.
 193
 194             @see setWidth
 195             @see getMinWidth
 196             @see getMaxWidth
 197         */
 198         virtual TableMetrics    getWidth() const = 0;
 199
 200         /** sets a new width for the column
 201
 202             @param _nWidth
 203                 the new width, app-font units
 204
 205             @see getWidth
 206         */
 207         virtual void            setWidth( TableMetrics _nWidth ) = 0;
 208
 209         /** returns the minimum width of the column, in app-font units, or 0 if the column
 210             does not have a minimal width
 211
 212             @see setMinWidth
 213             @see getMaxWidth
 214             @see getWidth
 215         */
 216         virtual TableMetrics    getMinWidth() const = 0;
 217
 218         /** returns the maximum width of the column, in app-font units, or 0 if the column
 219             does not have a minimal width
 220
 221             @see setMaxWidth
 222             @see getMinWidth
 223             @see getWidth
 224         */
 225         virtual TableMetrics    getMaxWidth() const = 0;
 226
 227         /** retrieves the horizontal alignment to be used for content in this cell
 228         */
 229         virtual css::style::HorizontalAlignment getHorizontalAlign() = 0;
 230
 231         /// deletes the column model instance
 232         virtual ~IColumnModel() { }
 233     };
 234     typedef std::shared_ptr< IColumnModel > PColumnModel;
 235
 236
 237     //= ITableModel
 238
 239     /** declares the interface to implement by an abstract table model
 240     */
 241     class SAL_NO_VTABLE SVT_DLLPUBLIC ITableModel
 242     {
 243     public:
 244         /** returns the number of columns in the table
 245         */
 246         virtual TableSize   getColumnCount() const = 0;
 247
 248         /** returns the number of rows in the table
 249         */
 250         virtual TableSize   getRowCount() const = 0;
 251
 252         /** determines whether the table has column headers
 253
 254             If this method returns <TRUE/>, the renderer returned by
 255             ->getRenderer must be able to render column headers.
 256
 257             @see IColumnRenderer
 258         */
 259         virtual bool        hasColumnHeaders() const = 0;
 260
 261         /** determines whether the table has row headers
 262
 263             If this method returns <TRUE/>, the renderer returned by
 264             ->getRenderer must be able to render row headers.
 265
 266             @see IColumnRenderer
 267         */
 268         virtual bool        hasRowHeaders() const = 0;
 269
 270         /** returns a model for a certain column
 271
 272             @param column
 273                 the index of the column in question. Must be greater than or
 274                 equal 0, and smaller than the return value of ->getColumnCount()
 275
 276             @return
 277                 the model of the column in question. Must not be <NULL/>
 278         */
 279         virtual PColumnModel    getColumnModel( ColPos column ) = 0;
 280
 281         /** returns a renderer which is able to paint the table represented
 282             by this table model
 283
 284             @return the renderer to use. Must not be <NULL/>
 285         */
 286         virtual PTableRenderer  getRenderer() const = 0;
 287
 288         /** returns the component handling input in a view associated with the model
 289         */
 290         virtual PTableInputHandler  getInputHandler() const = 0;
 291
 292         /** determines the height of rows in the table.
 293
 294             @return
 295                 the logical height of rows in the table, in app-font units. The height must be
 296                 greater 0.
 297         */
 298         virtual TableMetrics    getRowHeight() const = 0;
 299
 300         /** determines the height of the column header row
 301
 302             This method is not to be called if ->hasColumnHeaders()
 303             returned <FALSE/>.
 304
 305             @return
 306                 the logical height of the column header row, in app-font units.
 307                 Must be greater than 0.
 308         */
 309         virtual TableMetrics    getColumnHeaderHeight() const = 0;
 310
 311         /** determines the width of the row header column
 312
 313             This method is not to be called if ->hasRowHeaders()
 314             returned <FALSE/>.
 315
 316             @return
 317                 the logical width of the row header column, in app-font units.
 318                 Must be greater than 0.
 319         */
 320         virtual TableMetrics    getRowHeaderWidth() const = 0;
 321
 322         /** returns the visibilit mode of the vertical scrollbar
 323         */
 324         virtual ScrollbarVisibility getVerticalScrollbarVisibility() const = 0;
 325
 326         /** returns the visibilit mode of the horizontal scrollbar
 327         */
 328         virtual ScrollbarVisibility getHorizontalScrollbarVisibility() const = 0;
 329
 330         /** adds a listener to be notified of changes in the table model
 331         */
 332         virtual void addTableModelListener( const PTableModelListener& i_listener ) = 0;
 333
 334         /** remove a listener to be notified of changes in the table model
 335         */
 336         virtual void removeTableModelListener( const PTableModelListener& i_listener ) = 0;
 337
 338         /** retrieves the content of the given cell
 339         */
 340         virtual void getCellContent( ColPos const i_col, RowPos const i_row, css::uno::Any& o_cellContent ) = 0;
 341
 342         /** returns an object which should be displayed as tooltip for the given cell
 343
 344             At the moment, only string-convertible values are supported here. In the future, one might imagine displaying
 345             scaled-down versions of a graphic in a cell, and a larger version of that very graphic as tooltip.
 346
 347             If no tooltip object is provided, then the cell content is used, and displayed as tooltip for the cell
 348             if and only if it doesn't fit into the cell's space itself.
 349
 350             @param i_col
 351                 The column index of the cell in question. COL_ROW_HEADERS is a valid argument here.
 352             @param i_row
 353                 The row index of the cell in question.
 354             @param o_cellToolTip
 355                 takes the tooltip object upon return.
 356         */
 357         virtual void getCellToolTip( ColPos const i_col, RowPos const i_row, css::uno::Any & o_cellToolTip ) = 0;
 358
 359         /** retrieves title of a given row
 360         */
 361         virtual css::uno::Any      getRowHeading( RowPos const i_rowPos ) const = 0;
 362
 363         /** returns the color to be used for rendering the grid lines.
 364
 365             If this value is not set, a default color from the style settings will be used.
 366         */
 367         virtual ::boost::optional< ::Color >    getLineColor() const = 0;
 368
 369         /** returns the color to be used for rendering the header background.
 370
 371             If this value is not set, a default color from the style settings will be used.
 372         */
 373         virtual ::boost::optional< ::Color >    getHeaderBackgroundColor() const = 0;
 374
 375         /** returns the color to be used for rendering the header text.
 376
 377             If this value is not set, a default color from the style settings will be used.
 378         */
 379         virtual ::boost::optional< ::Color >    getHeaderTextColor() const = 0;
 380
 381         /** returns the color to be used for the background of selected cells, when the control has the focus
 382
 383             If this value is not set, a default color from the style settings will be used.
 384         */
 385         virtual ::boost::optional< ::Color >    getActiveSelectionBackColor() const = 0;
 386
 387         /** returns the color to be used for the background of selected cells, when the control does not have the focus
 388
 389             If this value is not set, a default color from the style settings will be used.
 390         */
 391         virtual ::boost::optional< ::Color >    getInactiveSelectionBackColor() const = 0;
 392
 393         /** returns the color to be used for the text of selected cells, when the control has the focus
 394
 395             If this value is not set, a default color from the style settings will be used.
 396         */
 397         virtual ::boost::optional< ::Color >    getActiveSelectionTextColor() const = 0;
 398
 399         /** returns the color to be used for the text of selected cells, when the control does not have the focus
 400
 401             If this value is not set, a default color from the style settings will be used.
 402         */
 403         virtual ::boost::optional< ::Color >    getInactiveSelectionTextColor() const = 0;
 404
 405         /** returns the color to be used for rendering cell texts.
 406
 407             If this value is not set, a default color from the style settings will be used.
 408         */
 409         virtual ::boost::optional< ::Color >    getTextColor() const = 0;
 410
 411         /** returns the color to be used for text lines (underline, strikethrough) when rendering cell text.
 412
 413             If this value is not set, a default color from the style settings will be used.
 414         */
 415         virtual ::boost::optional< ::Color >    getTextLineColor() const = 0;
 416
 417         /** returns the colors to be used for the row backgrounds.
 418
 419             If this value is not set, every second row will have a background color derived from the style settings's
 420             selection color, the other rows will not have a special background at all.
 421
 422             If this value is an empty sequence, the rows will not have a special background at all, instead the
 423             normal background of the complete control will be used.
 424
 425             If value is a non-empty sequence, then rows will have the background colors as specified in the sequence,
 426             in alternating order.
 427         */
 428         virtual ::boost::optional< ::std::vector< ::Color > >
 429                                                 getRowBackgroundColors() const = 0;
 430
 431         /** determines the vertical alignment of content within a cell
 432         */
 433         virtual css::style::VerticalAlignment getVerticalAlign() const = 0;
 434
 435         /** returns an adapter to the sorting functionality of the model
 436
 437             It is legitimate to return <NULL/> here, in this case, the table model does not support sorting.
 438         */
 439         virtual ITableDataSort* getSortAdapter() = 0;
 440
 441         /** returns enabled state.
 442         */
 443         virtual bool isEnabled() const = 0;
 444
 445         /// destroys the table model instance
 446         virtual ~ITableModel() { }
 447     };
 448     typedef std::shared_ptr< ITableModel > PTableModel;
 449
 450
 451 } } // namespace svt::table
 452
 453
 454 #endif // INCLUDED_SVTOOLS_TABLE_TABLEMODEL_HXX
 455
 456 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */