include/svtools/table/tablerenderer.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_TABLERENDERER_HXX
  21 #define INCLUDED_SVTOOLS_TABLE_TABLERENDERER_HXX
  22
  23 #include <svtools/table/tabletypes.hxx>
  24
  25 #include <vcl/outdev.hxx>
  26
  27 #include <memory>
  28
  29 class StyleSettings;
  30
  31
  32 namespace svt { namespace table
  33 {
  34
  35
  36
  37     //= ITableRenderer
  38
  39     /** interface to implement by components rendering a ->TableControl
  40     */
  41     class SAL_NO_VTABLE ITableRenderer
  42     {
  43         public:
  44
  45         /** paints a (part of) header area
  46
  47             There are two header areas in a table control:
  48             <ul><li>The row containing all column headers, i.e. <em>above</em> all rows containing the data</li>
  49                 <li>The column containing all row headers. i.e. <em>left of</em> all columns containing the data</li>
  50             </ul>
  51
  52             A header area is more than the union of the single column/row headers.
  53
  54             First, there might be less columns than fit into the view - in this case, right
  55             beside the right-most column, there's still room which belongs to the column header
  56             area, but is not occupied by any particular column header.<br/>
  57             An equivalent statement holds for the row header area, if there are less rows than
  58             fit into the view.
  59
  60             Second, if the table control has both a row header and a column header,
  61             the intersection between those both belongs to both the column header area and the
  62             row header area, but not to any particular column or row header.
  63
  64             There are two flags specifying whether the to-be-painted area is part of the column
  65             and/or row header area.
  66             <ul><li>If both are <TRUE/>, the intersection of both areas is to be painted.</li>
  67                 <li>If ->_bIsColHeaderArea is <TRUE/> and ->_bIsRowHeaderArea is <FALSE/>,
  68                     then ->_rArea denotes the column header area <em>excluding</em> the
  69                     intersection between row and column header area.</li>
  70                 <li>Equivalently for ->_bIsColHeaderArea being <FALSE/> and ->_bIsRowHeaderArea
  71                     being <TRUE/></li>
  72             </ul>
  73             Note that it's not possible for both ->_bIsColHeaderArea and ->_bIsRowHeaderArea
  74             to be <FALSE/> at the same time.
  75
  76             @param _rDevice
  77                 the device to paint onto
  78             @param _rArea
  79                 the area to paint into
  80             @param _bIsColHeaderArea
  81                 <TRUE/> if and only if ->_rArea is part of the column header area.
  82             @param _bIsRowHeaderArea
  83                 <TRUE/> if and only if ->_rArea is part of the row header area.
  84             @param _rStyle
  85                 the style to be used for drawing
  86         */
  87         virtual void    PaintHeaderArea(
  88                             OutputDevice& _rDevice, const Rectangle& _rArea,
  89                             bool _bIsColHeaderArea, bool _bIsRowHeaderArea,
  90                             const StyleSettings& _rStyle ) = 0;
  91
  92         /** paints the header for a given column
  93
  94             @param _nCol
  95                 the index of the column to paint
  96             @param _bActive
  97                 <TRUE/> if and only if the column whose column is to be painted
  98                 contains the active cell.
  99             @param _bSelected
 100                 <TRUE/> if and only if the column whose column is to be painted
 101                 is selected currently.
 102             @param _rDevice
 103                 denotes the device to paint onto
 104             @param _rArea
 105                 the are into which the column header should be painted
 106             @param _rStyle
 107                 the style to be used for drawing
 108         */
 109         virtual void    PaintColumnHeader( ColPos _nCol, bool _bActive, bool _bSelected,
 110                             OutputDevice& _rDevice, const Rectangle& _rArea,
 111                             const StyleSettings& _rStyle ) = 0;
 112
 113         /** prepares a row for painting
 114
 115             Painting a table means painting rows as necessary, in an increasing
 116             order. The assumption is that retrieving data for two different rows
 117             is (potentially) more expensive than retrieving data for two different
 118             columns. Thus, the renderer will get the chance to "seek" to a certain
 119             row, and then has to render all cells in this row, before another
 120             row is going to be painted.
 121
 122             @param _nRow
 123                 the row which is going to be painted. The renderer should
 124                 at least remember this row, since subsequent calls to
 125                 ->PaintRowHeader(), ->PaintCell(), and ->FinishRow() will
 126                 not pass this parameter again.
 127
 128                 However, the renderer is also allowed to render any
 129                 cell-independent content of this row.
 130
 131             @param i_hasControlFocus
 132                 <TRUE/> if and only if the table control currently has the focus
 133             @param _bSelected
 134                 <TRUE/> if and only if the row to be prepared is
 135                 selected currently.
 136             @param _rDevice
 137                 denotes the device to paint onto
 138             @param _rRowArea
 139                 the are into which the row should be painted. This excludes
 140                 the row header area, if applicable.
 141             @param _rStyle
 142                 the style to be used for drawing
 143         */
 144         virtual void    PrepareRow( RowPos _nRow, bool i_hasControlFocus, bool _bSelected,
 145                             OutputDevice& _rDevice, const Rectangle& _rRowArea,
 146                             const StyleSettings& _rStyle ) = 0;
 147
 148         /** paints the header of a row
 149
 150             The row to be painted is denoted by the most recent call to
 151             ->PrepareRow.
 152
 153             @param i_hasControlFocus
 154                 <TRUE/> if and only if the table control currently has the focus
 155                 <br/>
 156                 Note that this flag is equal to the respective flag in the
 157                 previous ->PrepareRow call, it's passed here for convinience
 158                 only.
 159             @param _bSelected
 160                 <TRUE/> if and only if the row whose header cell is to be
 161                 painted is selected currently.
 162                 <br/>
 163                 Note that this flag is equal to the respective flag in the
 164                 previous ->PrepareRow call, it's passed here for convinience
 165                 only.
 166             @param _rDevice
 167                 denotes the device to paint onto
 168             @param _rArea
 169                 the are into which the row header should be painted
 170             @param _rStyle
 171                 the style to be used for drawing
 172         */
 173         virtual void    PaintRowHeader( bool i_hasControlFocus, bool _bSelected,
 174                             OutputDevice& _rDevice, Rectangle const & _rArea,
 175                             StyleSettings const & _rStyle ) = 0;
 176
 177         /** paints a certain cell
 178
 179             The row to be painted is denoted by the most recent call to
 180             ->PrepareRow.
 181
 182             @param _bSelected
 183                 <TRUE/> if and only if the cell to be painted is
 184                 selected currently. This is the case if either
 185                 the row or the column of the cell is currently selected.
 186                 <br/>
 187                 Note that this flag is equal to the respective flag in the
 188                 previous ->PrepareRow call, it's passed here for convinience
 189                 only.
 190             @param i_hasControlFocus
 191                 <TRUE/> if and only if the table control currently has the focus
 192                 <br/>
 193                 Note that this flag is equal to the respective flag in the
 194                 previous ->PrepareRow call, it's passed here for convinience
 195                 only.
 196             @param _rDevice
 197                 denotes the device to paint onto
 198             @param _rArea
 199                 the are into which the cell should be painted
 200             @param _rStyle
 201                 the style to be used for drawing
 202         */
 203         virtual void    PaintCell( ColPos const i_col,
 204                             bool i_hasControlFocus, bool _bSelected,
 205                             OutputDevice& _rDevice, const Rectangle& _rArea,
 206                             const StyleSettings& _rStyle ) = 0;
 207
 208         /** draws a cell cursor in the given rectangle
 209
 210             The cell cursor is used to indicate the active/current cell
 211             of a table control.
 212         */
 213         virtual void    ShowCellCursor( vcl::Window& _rView, const Rectangle& _rCursorRect) = 0;
 214
 215         /** hides the cell cursor previously drawn into the given rectangle
 216
 217             The cell cursor is used to indicate the active/current cell
 218             of a table control.
 219         */
 220         virtual void    HideCellCursor( vcl::Window& _rView, const Rectangle& _rCursorRect) = 0;
 221
 222         /** checks whether a given cell content fits into a given target area on a given device.
 223
 224             @param i_colPos
 225                 denotes the column which the cell content would be painted into. Your renderer implementation
 226                 would only need this parameter if rendering is done differently for different columns.
 227
 228             @param i_rowPos
 229                 denotes the row which the cell content would be painted into. Your renderer implementation
 230                 would only need this parameter if rendering is done differently for different rows.
 231
 232             @param i_active
 233                 is <TRUE/> if and only if the renderer should assume the cell content would be painted for the active
 234                 cell.
 235
 236             @param i_selected
 237                 is <TRUE/> if and only if the renderer should assume the cell content would be painted for a selected
 238                 cell.
 239
 240             @param i_targetDevice
 241                 denotes the target device for the assumed rendering operation
 242
 243             @param i_targetArea
 244                 denotes the area within the target device for the assumed rendering operation.
 245
 246             @return
 247                 <TRUE/> if and only if the given cell content could be rendered into the given device and the
 248                 given area.
 249         */
 250         virtual bool    FitsIntoCell(
 251                             ::com::sun::star::uno::Any const & i_cellContent,
 252                             ColPos const i_colPos, RowPos const i_rowPos,
 253                             bool const i_active, bool const i_selected,
 254                             OutputDevice& i_targetDevice, Rectangle const & i_targetArea
 255                         ) const = 0;
 256
 257         /** attempts to format the content of the given cell as string
 258
 259             @param i_cellValue
 260                 the value for which an attempt for a string conversion should be made
 261             @param  i_colPos
 262                 the column position of the cell in question
 263             @param  i_rowPos
 264                 the row position of the cell in question
 265             @param  o_cellString
 266                 the cell content, formatted as string
 267             @return
 268                 <TRUE/> if and only if the content could be formatted as string
 269         */
 270         virtual bool    GetFormattedCellString(
 271                             ::com::sun::star::uno::Any const & i_cellValue,
 272                             ColPos const i_colPos, RowPos const i_rowPos,
 273                             OUString & o_cellString
 274                         ) const = 0;
 275
 276         /// deletes the renderer instance
 277         virtual ~ITableRenderer() { }
 278     };
 279     typedef std::shared_ptr< ITableRenderer > PTableRenderer;
 280
 281
 282 } } // namespace svt::table
 283
 284
 285 #endif // INCLUDED_SVTOOLS_TABLE_TABLERENDERER_HXX
 286
 287 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */