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