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 #include <svtools/table/tablesort.hxx>
  28
  29 #include <com/sun/star/util/Color.hpp>
  30 #include <com/sun/star/style/VerticalAlignment.hpp>
  31 #include <com/sun/star/style/HorizontalAlignment.hpp>
  32
  33 #include <rtl/ref.hxx>
  34 #include <sal/types.h>
  35
  36 #include <boost/optional.hpp>
  37 #include <memory>
  38 #include <o3tl/typed_flags_set.hxx>
  39
  40 enum class ColumnAttributeGroup
  41 {
  42     NONE          = 0x00,
  43     /// denotes column attributes related to the width of the column
  44     WIDTH         = 0x01,
  45     /// denotes column attributes related to the appearance of the column, i.e. those relevant for rendering
  46     APPEARANCE    = 0x02,
  47     /// denotes the entirety of column attributes
  48     ALL           = 0x03,
  49 };
  50 namespace o3tl
  51 {
  52     template<> struct typed_flags<ColumnAttributeGroup> : is_typed_flags<ColumnAttributeGroup, 0x03> {};
  53 }
  54
  55
  56 namespace svt { namespace table
  57 {
  58     //= ScrollbarVisibility
  59     enum ScrollbarVisibility
  60     {
  61         /** enumeration value denoting that a scrollbar should never be visible, even
  62             if needed normally
  63         */
  64         ScrollbarShowNever,
  65         /** enumeration value denoting that a scrollbar should be visible when needed only
  66         */
  67         ScrollbarShowSmart,
  68         /** enumeration value denoting that a scrollbar should always be visible, even
  69             if not needed normally
  70         */
  71         ScrollbarShowAlways
  72     };
  73
  74
  75     //= ITableModelListener
  76
  77     /** declares an interface to be implemented by components interested in
  78         changes in an ->ITableModel
  79     */
  80     class SAL_NO_VTABLE ITableModelListener : public std::enable_shared_from_this< ITableModelListener >
  81     {
  82     public:
  83         /** notifies the listener that one or more rows have been inserted into
  84             the table
  85
  86             @param first
  87                 the index of the first newly inserted row
  88             @param last
  89                 the index of the last newly inserted row. Must not be smaller
  90                 than ->first
  91         */
  92         virtual void    rowsInserted( RowPos first, RowPos last ) = 0;
  93
  94         /** notifies the listener that one or more rows have been removed from
  95             the table
  96
  97             @param first
  98                 the old index of the first removed row. If this is <code>-1</code>, then all
  99                 rows have been removed from the model.
 100             @param last
 101                 the old index of the last removed row. Must not be smaller
 102                 than ->first
 103         */
 104         virtual void    rowsRemoved( RowPos first, RowPos last ) = 0;
 105
 106         /** notifies the listener that one or more columns have been inserted into
 107             the table
 108
 109             @param first
 110                 the index of the first newly inserted row
 111             @param last
 112                 the index of the last newly inserted row. Must not be smaller
 113                 than ->first
 114         */
 115         virtual void    columnInserted( ColPos const i_colIndex ) = 0;
 116
 117         /** notifies the listener that one or more columns have been removed from
 118             the table
 119
 120             @param i_colIndex
 121                 the old index of the removed column
 122         */
 123         virtual void    columnRemoved( ColPos const i_colIndex ) = 0;
 124
 125         /** notifies the listener that all columns have been removed form the model
 126         */
 127         virtual void    allColumnsRemoved() = 0;
 128
 129         /** notifies the listener that a rectangular cell range in the table
 130             has been updated
 131
 132             Listeners are required to discard any possibly cached information
 133             they have about the cells in question, in particular any possibly
 134             cached cell values.
 135         */
 136         virtual void    cellsUpdated( ColPos const i_firstCol, ColPos i_lastCol, RowPos const i_firstRow, RowPos const i_lastRow ) = 0;
 137
 138         /** notifies the listener that attributes of a given column changed
 139
 140             @param i_column
 141                 the position of the column whose attributes changed
 142             @param i_attributeGroup
 143                 a combination of one or more <code>COL_ATTRS_*</code> flags, denoting the attribute group(s)
 144                 in which changes occurred.
 145         */
 146         virtual void    columnChanged( ColPos const i_column, ColumnAttributeGroup const i_attributeGroup ) = 0;
 147
 148         /** notifies the listener that the metrics of the table changed.
 149
 150             Metrics here include the column header height, the row header width, the row height, and the presence
 151             of both the row and column header.
 152         */
 153         virtual void    tableMetricsChanged() = 0;
 154
 155         /// deletes the listener instance
 156         virtual ~ITableModelListener(){};
 157     };
 158     typedef std::shared_ptr< ITableModelListener > PTableModelListener;
 159
 160
 161     //= IColumnModel
 162
 163     /** interface to be implemented by table column models
 164     */
 165     class SAL_NO_VTABLE IColumnModel
 166     {
 167     public:
 168         /** retrieves the ID of the column
 169
 170             The semantics of a column id is not defined. It's up to the
 171             implementor of the ->IColumnModel, respectively the ->ITableModel
 172             which provides the column models, to define such a semantics.
 173
 174             @return
 175                 the ID of the column. May be 0 if the table which the column
 176                 belongs to does not need and support column ids.
 177
 178             @see setID
 179         */
 180         virtual ::com::sun::star::uno::Any
 181                             getID() const = 0;
 182
 183         /** sets a new column ID
 184
 185             @return
 186                 <TRUE/> if setting the new ID was successful. A possible error
 187                 conditions is if you try to set an ID which is already used
 188                 by another column within the same table.
 189
 190             @see getID
 191         */
 192         virtual void        setID( const ::com::sun::star::uno::Any& _nID ) = 0;
 193
 194         /** returns the name of the column
 195
 196             Column names should be human-readable, but not necessarily unique
 197             within a given table.
 198
 199             @see setName
 200         */
 201         virtual OUString      getName() const = 0;
 202
 203         /** sets a new name for the column
 204
 205             @see getName
 206         */
 207         virtual void        setName( const OUString& _rName ) = 0;
 208
 209         /** retrieves the help text to be displayed for the column.
 210         */
 211         virtual OUString      getHelpText() const = 0;
 212
 213         /** sets a new the help text to be displayed for the column.
 214         */
 215         virtual void        setHelpText( const OUString& i_helpText ) = 0;
 216
 217         /** determines whether the column can be interactively resized
 218
 219             @see getMinWidth
 220             @see getMaxWidth
 221             @see getWidth
 222         */
 223         virtual bool        isResizable() const = 0;
 224
 225         /** declares the column as resizable or fixed in width
 226
 227             @see getMinWidth
 228             @see getMaxWidth
 229             @see getWidth
 230         */
 231         virtual void        setResizable( bool _bResizable ) = 0;
 232
 233         /** denotes the relative flexibility of the column
 234
 235             This flexibility is taken into account when a table control auto-resizes its columns, because the available
 236             space changed. In this case, the columns grow or shrink according to their flexibility.
 237
 238             A value of 0 means the column is not auto-resized at all.
 239         */
 240         virtual sal_Int32   getFlexibility() const = 0;
 241
 242         /** sets a new flexibility value for the column
 243
 244             @see getFlexibility
 245         */
 246         virtual void        setFlexibility( sal_Int32 const i_flexibility ) = 0;
 247
 248         /** returns the width of the column, in app-font unitss
 249
 250             The returned value must be a positive ->TableMetrics value.
 251
 252             @see setWidth
 253             @see getMinWidth
 254             @see getMaxWidth
 255         */
 256         virtual TableMetrics    getWidth() const = 0;
 257
 258         /** sets a new width for the column
 259
 260             @param _nWidth
 261                 the new width, app-font units
 262
 263             @see getWidth
 264         */
 265         virtual void            setWidth( TableMetrics _nWidth ) = 0;
 266
 267         /** returns the minimum width of the column, in app-font units, or 0 if the column
 268             does not have a minimal width
 269
 270             @see setMinWidth
 271             @see getMaxWidth
 272             @see getWidth
 273         */
 274         virtual TableMetrics    getMinWidth() const = 0;
 275
 276         /** sets the minimum width of the column, in app-font units
 277
 278             @see getMinWidth
 279             @see setMaxWidth
 280             @see setWidth
 281         */
 282         virtual void            setMinWidth( TableMetrics _nMinWidth ) = 0;
 283
 284         /** returns the maximum width of the column, in app-font units, or 0 if the column
 285             does not have a minimal width
 286
 287             @see setMaxWidth
 288             @see getMinWidth
 289             @see getWidth
 290         */
 291         virtual TableMetrics    getMaxWidth() const = 0;
 292
 293         /** sets the maximum width of the column, in app-font units
 294
 295             @see getMaxWidth
 296             @see setMinWidth
 297             @see setWidth
 298         */
 299         virtual void            setMaxWidth( TableMetrics _nMaxWidth ) = 0;
 300
 301         /** retrieves the horizontal alignment to be used for content in this cell
 302         */
 303         virtual ::com::sun::star::style::HorizontalAlignment getHorizontalAlign() = 0;
 304
 305         /** sets a new the horizontal alignment to be used for content in this cell
 306         */
 307         virtual void setHorizontalAlign(::com::sun::star::style::HorizontalAlignment _xAlign) = 0;
 308
 309         /// deletes the column model instance
 310         virtual ~IColumnModel() { }
 311     };
 312     typedef std::shared_ptr< IColumnModel > PColumnModel;
 313
 314
 315     //= ITableModel
 316
 317     /** declares the interface to implement by an abtract table model
 318     */
 319     class SAL_NO_VTABLE SVT_DLLPUBLIC ITableModel
 320     {
 321     public:
 322         /** returns the number of columns in the table
 323         */
 324         virtual TableSize   getColumnCount() const = 0;
 325
 326         /** returns the number of rows in the table
 327         */
 328         virtual TableSize   getRowCount() const = 0;
 329
 330         /** determines whether the table has column headers
 331
 332             If this method returns <TRUE/>, the renderer returned by
 333             ->getRenderer must be able to render column headers.
 334
 335             @see IColumnRenderer
 336         */
 337         virtual bool        hasColumnHeaders() const = 0;
 338
 339         /** determines whether the table has row headers
 340
 341             If this method returns <TRUE/>, the renderer returned by
 342             ->getRenderer must be able to render row headers.
 343
 344             @see IColumnRenderer
 345         */
 346         virtual bool        hasRowHeaders() const = 0;
 347
 348         /** determines whether the given cell is editable
 349
 350             @see ICellEditor
 351             @todo
 352         */
 353         virtual bool        isCellEditable( ColPos col, RowPos row ) const = 0;
 354
 355         /** returns a model for a certain column
 356
 357             @param column
 358                 the index of the column in question. Must be greater than or
 359                 equal 0, and smaller than the return value of ->getColumnCount()
 360
 361             @return
 362                 the model of the column in question. Must not be <NULL/>
 363         */
 364         virtual PColumnModel    getColumnModel( ColPos column ) = 0;
 365
 366         /** returns a renderer which is able to paint the table represented
 367             by this table model
 368
 369             @return the renderer to use. Must not be <NULL/>
 370         */
 371         virtual PTableRenderer  getRenderer() const = 0;
 372
 373         /** returns the component handling input in a view associated with the model
 374         */
 375         virtual PTableInputHandler  getInputHandler() const = 0;
 376
 377         /** determines the height of rows in the table.
 378
 379             @return
 380                 the logical height of rows in the table, in app-font units. The height must be
 381                 greater 0.
 382         */
 383         virtual TableMetrics    getRowHeight() const = 0;
 384
 385         /** determines the height of the column header row
 386
 387             This method is not to be called if ->hasColumnHeaders()
 388             returned <FALSE/>.
 389
 390             @return
 391                 the logical height of the column header row, in app-font units.
 392                 Must be greater than 0.
 393         */
 394         virtual TableMetrics    getColumnHeaderHeight() const = 0;
 395
 396         /** determines the width of the row header column
 397
 398             This method is not to be called if ->hasRowHeaders()
 399             returned <FALSE/>.
 400
 401             @return
 402                 the logical width of the row header column, in app-font units.
 403                 Must be greater than 0.
 404         */
 405         virtual TableMetrics    getRowHeaderWidth() const = 0;
 406
 407         /** returns the visibilit mode of the vertical scrollbar
 408         */
 409         virtual ScrollbarVisibility getVerticalScrollbarVisibility() const = 0;
 410
 411         /** returns the visibilit mode of the horizontal scrollbar
 412         */
 413         virtual ScrollbarVisibility getHorizontalScrollbarVisibility() const = 0;
 414
 415         /** adds a listener to be notified of changes in the table model
 416         */
 417         virtual void addTableModelListener( const PTableModelListener& i_listener ) = 0;
 418
 419         /** remove a listener to be notified of changes in the table model
 420         */
 421         virtual void removeTableModelListener( const PTableModelListener& i_listener ) = 0;
 422
 423         /** retrieves the content of the given cell
 424         */
 425         virtual void getCellContent( ColPos const i_col, RowPos const i_row, ::com::sun::star::uno::Any& o_cellContent ) = 0;
 426
 427         /** returns an object which should be displayed as tooltip for the given cell
 428
 429             At the moment, only string-convertible values are supported here. In the future, one might imagine displaying
 430             scaled-down versions of a graphic in a cell, and a larger version of that very graphic as tooltip.
 431
 432             If no tooltip object is provided, then the cell content is used, and displayed as tooltip for the cell
 433             if and only if it doesn't fit into the cell's space itself.
 434
 435             @param i_col
 436                 The column index of the cell in question. COL_ROW_HEADERS is a valid argument here.
 437             @param i_row
 438                 The row index of the cell in question.
 439             @param o_cellToolTip
 440                 takes the tooltip object upon return.
 441         */
 442         virtual void getCellToolTip( ColPos const i_col, RowPos const i_row, ::com::sun::star::uno::Any & o_cellToolTip ) = 0;
 443
 444         /** retrieves title of a given row
 445         */
 446         virtual ::com::sun::star::uno::Any      getRowHeading( RowPos const i_rowPos ) const = 0;
 447
 448         /** returns the color to be used for rendering the grid lines.
 449
 450             If this value is not set, a default color from the style settings will be used.
 451         */
 452         virtual ::boost::optional< ::Color >    getLineColor() const = 0;
 453
 454         /** returns the color to be used for rendering the header background.
 455
 456             If this value is not set, a default color from the style settings will be used.
 457         */
 458         virtual ::boost::optional< ::Color >    getHeaderBackgroundColor() const = 0;
 459
 460         /** returns the color to be used for rendering the header text.
 461
 462             If this value is not set, a default color from the style settings will be used.
 463         */
 464         virtual ::boost::optional< ::Color >    getHeaderTextColor() const = 0;
 465
 466         /** returns the color to be used for the background of selected cells, when the control has the focus
 467
 468             If this value is not set, a default color from the style settings will be used.
 469         */
 470         virtual ::boost::optional< ::Color >    getActiveSelectionBackColor() const = 0;
 471
 472         /** returns the color to be used for the background of selected cells, when the control does not have the focus
 473
 474             If this value is not set, a default color from the style settings will be used.
 475         */
 476         virtual ::boost::optional< ::Color >    getInactiveSelectionBackColor() const = 0;
 477
 478         /** returns the color to be used for the text of selected cells, when the control has the focus
 479
 480             If this value is not set, a default color from the style settings will be used.
 481         */
 482         virtual ::boost::optional< ::Color >    getActiveSelectionTextColor() const = 0;
 483
 484         /** returns the color to be used for the text of selected cells, when the control does not have the focus
 485
 486             If this value is not set, a default color from the style settings will be used.
 487         */
 488         virtual ::boost::optional< ::Color >    getInactiveSelectionTextColor() const = 0;
 489
 490         /** returns the color to be used for rendering cell texts.
 491
 492             If this value is not set, a default color from the style settings will be used.
 493         */
 494         virtual ::boost::optional< ::Color >    getTextColor() const = 0;
 495
 496         /** returns the color to be used for text lines (underline, strikethrough) when rendering cell text.
 497
 498             If this value is not set, a default color from the style settings will be used.
 499         */
 500         virtual ::boost::optional< ::Color >    getTextLineColor() const = 0;
 501
 502         /** returns the colors to be used for the row backgrounds.
 503
 504             If this value is not set, every second row will have a background color derived from the style settings's
 505             selection color, the other rows will not have a special background at all.
 506
 507             If this value is an empty sequence, the rows will not have a special background at all, instead the
 508             normal background of the complete control will be used.
 509
 510             If value is a non-empty sequence, then rows will have the background colors as specified in the sequence,
 511             in alternating order.
 512         */
 513         virtual ::boost::optional< ::std::vector< ::Color > >
 514                                                 getRowBackgroundColors() const = 0;
 515
 516         /** determines the vertical alignment of content within a cell
 517         */
 518         virtual ::com::sun::star::style::VerticalAlignment getVerticalAlign() const = 0;
 519
 520         /** returns an adapter to the sorting functionality of the model
 521
 522             It is legitimate to return <NULL/> here, in this case, the table model does not support sorting.
 523         */
 524         virtual ITableDataSort* getSortAdapter() = 0;
 525
 526         /** returns enabled state.
 527         */
 528         virtual bool isEnabled() const = 0;
 529
 530         /// destroys the table model instance
 531         virtual ~ITableModel() { }
 532     };
 533     typedef std::shared_ptr< ITableModel > PTableModel;
 534
 535
 536 } } // namespace svt::table
 537
 538
 539 #endif // INCLUDED_SVTOOLS_TABLE_TABLEMODEL_HXX
 540
 541 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */