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