svtools/inc/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 #pragma once
  21
  22 #include <table/tabletypes.hxx>
  23
  24 #include <rtl/ustring.hxx>
  25
  26 #include <memory>
  27
  28 namespace com :: sun :: star :: uno { class Any; }
  29 namespace tools { class Rectangle; }
  30 namespace vcl { class Window; }
  31
  32 class OutputDevice;
  33 class StyleSettings;
  34 namespace vcl {
  35     typedef OutputDevice RenderContext;
  36 };
  37
  38
  39 namespace svt::table
  40 {
  41
  42
  43     //= ITableRenderer
  44
  45     /** interface to implement by components rendering a ->TableControl
  46     */
  47     class SAL_NO_VTABLE ITableRenderer
  48     {
  49         public:
  50
  51         /** paints a (part of) header area
  52
  53             There are two header areas in a table control:
  54             <ul><li>The row containing all column headers, i.e. <em>above</em> all rows containing the data</li>
  55                 <li>The column containing all row headers. i.e. <em>left of</em> all columns containing the data</li>
  56             </ul>
  57
  58             A header area is more than the union of the single column/row headers.
  59
  60             First, there might be less columns than fit into the view - in this case, right
  61             beside the right-most column, there's still room which belongs to the column header
  62             area, but is not occupied by any particular column header.<br/>
  63             An equivalent statement holds for the row header area, if there are fewer rows than
  64             fit into the view.
  65
  66             Second, if the table control has both a row header and a column header,
  67             the intersection between those both belongs to both the column header area and the
  68             row header area, but not to any particular column or row header.
  69
  70             There are two flags specifying whether the to-be-painted area is part of the column
  71             and/or row header area.
  72             <ul><li>If both are <TRUE/>, the intersection of both areas is to be painted.</li>
  73                 <li>If ->_bIsColHeaderArea is <TRUE/> and ->_bIsRowHeaderArea is <FALSE/>,
  74                     then ->_rArea denotes the column header area <em>excluding</em> the
  75                     intersection between row and column header area.</li>
  76                 <li>Equivalently for ->_bIsColHeaderArea being <FALSE/> and ->_bIsRowHeaderArea
  77                     being <TRUE/></li>
  78             </ul>
  79             Note that it's not possible for both ->_bIsColHeaderArea and ->_bIsRowHeaderArea
  80             to be <FALSE/> at the same time.
  81
  82             @param _rDevice
  83                 the device to paint onto
  84             @param _rArea
  85                 the area to paint into
  86             @param _bIsColHeaderArea
  87                 <TRUE/> if and only if ->_rArea is part of the column header area.
  88             @param _bIsRowHeaderArea
  89                 <TRUE/> if and only if ->_rArea is part of the row header area.
  90             @param _rStyle
  91                 the style to be used for drawing
  92         */
  93         virtual void    PaintHeaderArea(
  94                             vcl::RenderContext& _rDevice, const tools::Rectangle& _rArea,
  95                             bool _bIsColHeaderArea, bool _bIsRowHeaderArea,
  96                             const StyleSettings& _rStyle ) = 0;
  97
  98         /** paints the header for a given column
  99
 100             @param _nCol
 101                 the index of the column to paint
 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,
 110                             vcl::RenderContext& _rDevice, const tools::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                             vcl::RenderContext& _rDevice, const tools::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 _rDevice
 154                 denotes the device to paint onto
 155             @param _rArea
 156                 the are into which the row header should be painted
 157             @param _rStyle
 158                 the style to be used for drawing
 159         */
 160         virtual void    PaintRowHeader(
 161                             vcl::RenderContext& _rDevice, tools::Rectangle const & _rArea,
 162                             StyleSettings const & _rStyle ) = 0;
 163
 164         /** paints a certain cell
 165
 166             The row to be painted is denoted by the most recent call to
 167             ->PrepareRow.
 168
 169             @param _bSelected
 170                 <TRUE/> if and only if the cell to be painted is
 171                 selected currently. This is the case if either
 172                 the row or the column of the cell is currently selected.
 173                 <br/>
 174                 Note that this flag is equal to the respective flag in the
 175                 previous ->PrepareRow call, it's passed here for convenience
 176                 only.
 177             @param i_hasControlFocus
 178                 <TRUE/> if and only if the table control currently has the focus
 179                 <br/>
 180                 Note that this flag is equal to the respective flag in the
 181                 previous ->PrepareRow call, it's passed here for convenience
 182                 only.
 183             @param _rDevice
 184                 denotes the device to paint onto
 185             @param _rArea
 186                 the are into which the cell should be painted
 187             @param _rStyle
 188                 the style to be used for drawing
 189         */
 190         virtual void    PaintCell( ColPos const i_col,
 191                             bool i_hasControlFocus, bool _bSelected,
 192                             vcl::RenderContext& _rDevice, const tools::Rectangle& _rArea,
 193                             const StyleSettings& _rStyle ) = 0;
 194
 195         /** draws a cell cursor in the given rectangle
 196
 197             The cell cursor is used to indicate the active/current cell
 198             of a table control.
 199         */
 200         virtual void    ShowCellCursor( vcl::Window& _rView, const tools::Rectangle& _rCursorRect) = 0;
 201
 202         /** hides the cell cursor previously drawn into the given rectangle
 203
 204             The cell cursor is used to indicate the active/current cell
 205             of a table control.
 206         */
 207         virtual void    HideCellCursor( vcl::Window& _rView ) = 0;
 208
 209         /** checks whether a given cell content fits into a given target area on a given device.
 210
 211             @param i_targetDevice
 212                 denotes the target device for the assumed rendering operation
 213
 214             @param i_targetArea
 215                 denotes the area within the target device for the assumed rendering operation.
 216
 217             @return
 218                 <TRUE/> if and only if the given cell content could be rendered into the given device and the
 219                 given area.
 220         */
 221         virtual bool    FitsIntoCell(
 222                             css::uno::Any const & i_cellContent,
 223                             OutputDevice& i_targetDevice, tools::Rectangle const & i_targetArea
 224                         ) const = 0;
 225
 226         /** attempts to format the content of the given cell as string
 227
 228             @param i_cellValue
 229                 the value for which an attempt for a string conversion should be made
 230             @param  o_cellString
 231                 the cell content, formatted as string
 232             @return
 233                 <TRUE/> if and only if the content could be formatted as string
 234         */
 235         virtual bool    GetFormattedCellString(
 236                             css::uno::Any const & i_cellValue,
 237                             OUString & o_cellString
 238                         ) const = 0;
 239
 240         /// deletes the renderer instance
 241         virtual ~ITableRenderer() { }
 242     };
 243     typedef std::shared_ptr< ITableRenderer > PTableRenderer;
 244
 245
 246 } // namespace svt::table
 247
 248
 249 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */