| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: vscroll.h |
| 3 | // Purpose: interface of wxVarHScrollHelper |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxVarScrollHelperBase |
| 11 | |
| 12 | This class provides all common base functionality for scroll calculations |
| 13 | shared among all variable scrolled window implementations as well as |
| 14 | automatic scrollbar functionality, saved scroll positions, controlling |
| 15 | target windows to be scrolled, as well as defining all required virtual |
| 16 | functions that need to be implemented for any orientation specific work. |
| 17 | |
| 18 | Documentation of this class is provided specifically for referencing use |
| 19 | of the functions provided by this class for use with the variable scrolled |
| 20 | windows that derive from here. You will likely want to derive your window |
| 21 | from one of the already implemented variable scrolled windows rather than |
| 22 | from wxVarScrollHelperBase directly. |
| 23 | |
| 24 | @library{wxcore} |
| 25 | @category{miscwnd} |
| 26 | |
| 27 | @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow |
| 28 | */ |
| 29 | class wxVarScrollHelperBase |
| 30 | { |
| 31 | public: |
| 32 | /** |
| 33 | Constructor taking the target window to be scrolled by this helper |
| 34 | class. This will attach scroll event handlers to the target window to |
| 35 | catch and handle scroll events appropriately. |
| 36 | */ |
| 37 | wxVarScrollHelperBase(wxWindow* winToScroll); |
| 38 | |
| 39 | /** |
| 40 | Virtual destructor for detaching scroll event handlers attached with |
| 41 | this helper class. |
| 42 | */ |
| 43 | virtual ~wxVarScrollHelperBase(); |
| 44 | |
| 45 | /** |
| 46 | Translates the logical coordinate given to the current device |
| 47 | coordinate. For example, if the window is scrolled 10 units and each |
| 48 | scroll unit represents 10 device units (which may not be the case since |
| 49 | this class allows for variable scroll unit sizes), a call to this |
| 50 | function with a coordinate of 15 will return -85. |
| 51 | |
| 52 | @see CalcUnscrolledPosition() |
| 53 | */ |
| 54 | int CalcScrolledPosition(int coord) const; |
| 55 | |
| 56 | /** |
| 57 | Translates the device coordinate given to the corresponding logical |
| 58 | coordinate. For example, if the window is scrolled 10 units and each |
| 59 | scroll unit represents 10 device units (which may not be the case since |
| 60 | this class allows for variable scroll unit sizes), a call to this |
| 61 | function with a coordinate of 15 will return 115. |
| 62 | |
| 63 | @see CalcScrolledPosition() |
| 64 | */ |
| 65 | int CalcUnscrolledPosition(int coord) const; |
| 66 | |
| 67 | /** |
| 68 | With physical scrolling on (when this is @true), the device origin is |
| 69 | changed properly when a wxPaintDC is prepared, children are actually |
| 70 | moved and laid out properly, and the contents of the window (pixels) |
| 71 | are actually moved. When this is @false, you are responsible for |
| 72 | repainting any invalidated areas of the window yourself to account for |
| 73 | the new scroll position. |
| 74 | */ |
| 75 | void EnablePhysicalScrolling(bool scrolling = true); |
| 76 | |
| 77 | /** |
| 78 | This function needs to be overridden in the in the derived class to |
| 79 | return the window size with respect to the opposing orientation. If |
| 80 | this is a vertical scrolled window, it should return the height. |
| 81 | |
| 82 | @see GetOrientationTargetSize() |
| 83 | */ |
| 84 | virtual int GetNonOrientationTargetSize() const = 0; |
| 85 | |
| 86 | /** |
| 87 | This function need to be overridden to return the orientation that this |
| 88 | helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL. |
| 89 | */ |
| 90 | virtual wxOrientation GetOrientation() const = 0; |
| 91 | |
| 92 | /** |
| 93 | This function needs to be overridden in the in the derived class to |
| 94 | return the window size with respect to the orientation this helper is |
| 95 | working with. If this is a vertical scrolled window, it should return |
| 96 | the width. |
| 97 | |
| 98 | @see GetNonOrientationTargetSize() |
| 99 | */ |
| 100 | virtual int GetOrientationTargetSize() const = 0; |
| 101 | |
| 102 | /** |
| 103 | This function will return the target window this helper class is |
| 104 | currently scrolling. |
| 105 | |
| 106 | @see SetTargetWindow() |
| 107 | */ |
| 108 | virtual wxWindow* GetTargetWindow() const; |
| 109 | |
| 110 | /** |
| 111 | Returns the index of the first visible unit based on the scroll |
| 112 | position. |
| 113 | */ |
| 114 | size_t GetVisibleBegin() const; |
| 115 | |
| 116 | /** |
| 117 | Returns the index of the last visible unit based on the scroll |
| 118 | position. This includes the last unit even if it is only partially |
| 119 | visible. |
| 120 | */ |
| 121 | size_t GetVisibleEnd() const; |
| 122 | |
| 123 | /** |
| 124 | Returns @true if the given scroll unit is currently visible (even if |
| 125 | only partially visible) or @false otherwise. |
| 126 | */ |
| 127 | bool IsVisible(size_t unit) const; |
| 128 | |
| 129 | /** |
| 130 | Recalculate all parameters and repaint all units. |
| 131 | */ |
| 132 | virtual void RefreshAll(); |
| 133 | |
| 134 | /** |
| 135 | Normally the window will scroll itself, but in some rare occasions you |
| 136 | might want it to scroll (part of) another window (e.g. a child of it in |
| 137 | order to scroll only a portion the area between the scrollbars like a |
| 138 | spreadsheet where only the cell area will move). |
| 139 | |
| 140 | @see GetTargetWindow() |
| 141 | */ |
| 142 | virtual void SetTargetWindow(wxWindow* target); |
| 143 | |
| 144 | /** |
| 145 | Update the thumb size shown by the scrollbar. |
| 146 | */ |
| 147 | virtual void UpdateScrollbar(); |
| 148 | |
| 149 | /** |
| 150 | Returns the virtual scroll unit under the device unit given accounting |
| 151 | for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the |
| 152 | last item). |
| 153 | */ |
| 154 | int VirtualHitTest(wxCoord coord) const; |
| 155 | |
| 156 | |
| 157 | protected: |
| 158 | |
| 159 | /** |
| 160 | This function doesn't have to be overridden but it may be useful to do |
| 161 | so if calculating the units' sizes is a relatively expensive operation |
| 162 | as it gives your code a chance to calculate several of them at once and |
| 163 | cache the result if necessary. |
| 164 | |
| 165 | OnGetUnitsSizeHint() is normally called just before OnGetUnitSize() but |
| 166 | you shouldn't rely on the latter being called for all units in the |
| 167 | interval specified here. It is also possible that OnGetUnitSize() will |
| 168 | be called for units outside of this interval, so this is really just a |
| 169 | hint, not a promise. |
| 170 | |
| 171 | Finally, note that @a unitMin is inclusive, while @a unitMax is |
| 172 | exclusive. |
| 173 | */ |
| 174 | virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const; |
| 175 | |
| 176 | /** |
| 177 | When the number of scroll units change, we try to estimate the total |
| 178 | size of all units when the full window size is needed (i.e. to |
| 179 | calculate the scrollbar thumb size). This is a rather expensive |
| 180 | operation in terms of unit access, so if the user code may estimate the |
| 181 | average size better or faster than we do, it should override this |
| 182 | function to implement its own logic. This function should return the |
| 183 | best guess for the total virtual window size. |
| 184 | |
| 185 | @note Although returning a totally wrong value would still work, it |
| 186 | risks resulting in very strange scrollbar behaviour so this |
| 187 | function should really try to make the best guess possible. |
| 188 | */ |
| 189 | virtual wxCoord EstimateTotalSize() const; |
| 190 | |
| 191 | /** |
| 192 | This function must be overridden in the derived class, and should |
| 193 | return the size of the given unit in pixels. |
| 194 | */ |
| 195 | virtual wxCoord OnGetUnitSize(size_t unit) const = 0; |
| 196 | }; |
| 197 | |
| 198 | |
| 199 | |
| 200 | /** |
| 201 | @class wxVarVScrollHelper |
| 202 | |
| 203 | This class provides functions wrapping the wxVarScrollHelperBase class, |
| 204 | targeted for vertical-specific scrolling. |
| 205 | |
| 206 | Like wxVarScrollHelperBase, this class is mostly only useful to those |
| 207 | classes built into wxWidgets deriving from here, and this documentation is |
| 208 | mostly only provided for referencing the functions provided by this class. |
| 209 | You will likely want to derive your window from wxVScrolledWindow rather |
| 210 | than from here directly. |
| 211 | |
| 212 | @library{wxcore} |
| 213 | @category{miscwnd} |
| 214 | |
| 215 | @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow |
| 216 | */ |
| 217 | class wxVarVScrollHelper : public wxVarScrollHelperBase |
| 218 | { |
| 219 | public: |
| 220 | /** |
| 221 | Constructor taking the target window to be scrolled by this helper |
| 222 | class. This will attach scroll event handlers to the target window to |
| 223 | catch and handle scroll events appropriately. |
| 224 | */ |
| 225 | wxVarVScrollHelper(wxWindow* winToScroll); |
| 226 | |
| 227 | /** |
| 228 | Returns the number of rows the target window contains. |
| 229 | |
| 230 | @see SetRowCount() |
| 231 | */ |
| 232 | size_t GetRowCount() const; |
| 233 | |
| 234 | /** |
| 235 | Returns the index of the first visible row based on the scroll |
| 236 | position. |
| 237 | */ |
| 238 | size_t GetVisibleRowsBegin() const; |
| 239 | |
| 240 | /** |
| 241 | Returns the index of the last visible row based on the scroll position. |
| 242 | This includes the last row even if it is only partially visible. |
| 243 | */ |
| 244 | size_t GetVisibleRowsEnd() const; |
| 245 | |
| 246 | /** |
| 247 | Returns @true if the given row is currently visible (even if only |
| 248 | partially visible) or @false otherwise. |
| 249 | */ |
| 250 | bool IsRowVisible(size_t row) const; |
| 251 | |
| 252 | /** |
| 253 | Triggers a refresh for just the given row's area of the window if it's |
| 254 | visible. |
| 255 | */ |
| 256 | virtual void RefreshRow(size_t row); |
| 257 | |
| 258 | /** |
| 259 | Triggers a refresh for the area between the specified range of rows |
| 260 | given (inclusively). |
| 261 | */ |
| 262 | virtual void RefreshRows(size_t from, size_t to); |
| 263 | |
| 264 | /** |
| 265 | Scroll by the specified number of pages which may be positive (to |
| 266 | scroll down) or negative (to scroll up). |
| 267 | */ |
| 268 | virtual bool ScrollRowPages(int pages); |
| 269 | |
| 270 | /** |
| 271 | Scroll by the specified number of rows which may be positive (to scroll |
| 272 | down) or negative (to scroll up). |
| 273 | |
| 274 | @return @true if the window was scrolled, @false otherwise (for |
| 275 | example, if we're trying to scroll down but we are already |
| 276 | showing the last row). |
| 277 | */ |
| 278 | virtual bool ScrollRows(int rows); |
| 279 | |
| 280 | /** |
| 281 | Scroll to the specified row. It will become the first visible row in |
| 282 | the window. |
| 283 | |
| 284 | @return @true if we scrolled the window, @false if nothing was done. |
| 285 | */ |
| 286 | bool ScrollToRow(size_t row); |
| 287 | |
| 288 | /** |
| 289 | Set the number of rows the window contains. The derived class must |
| 290 | provide the heights for all rows with indices up to the one given here |
| 291 | in it's OnGetRowHeight() implementation. |
| 292 | |
| 293 | @see GetRowCount() |
| 294 | */ |
| 295 | void SetRowCount(size_t rowCount); |
| 296 | |
| 297 | protected: |
| 298 | |
| 299 | /** |
| 300 | This function doesn't have to be overridden but it may be useful to do |
| 301 | so if calculating the rows' sizes is a relatively expensive operation |
| 302 | as it gives your code a chance to calculate several of them at once and |
| 303 | cache the result if necessary. |
| 304 | |
| 305 | OnGetRowsHeightHint() is normally called just before OnGetRowHeight() |
| 306 | but you shouldn't rely on the latter being called for all rows in the |
| 307 | interval specified here. It is also possible that OnGetRowHeight() will |
| 308 | be called for units outside of this interval, so this is really just a |
| 309 | hint, not a promise. |
| 310 | |
| 311 | Finally, note that @a rowMin is inclusive, while @a rowMax is |
| 312 | exclusive. |
| 313 | */ |
| 314 | virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const; |
| 315 | |
| 316 | /** |
| 317 | This class forwards calls from EstimateTotalSize() to this function so |
| 318 | derived classes can override either just the height or the width |
| 319 | estimation, or just estimate both differently if desired in any |
| 320 | wxHVScrolledWindow derived class. |
| 321 | |
| 322 | @note This function will not be called if EstimateTotalSize() is |
| 323 | overridden in your derived class. |
| 324 | */ |
| 325 | virtual wxCoord EstimateTotalHeight() const; |
| 326 | |
| 327 | /** |
| 328 | This function must be overridden in the derived class, and should |
| 329 | return the height of the given row in pixels. |
| 330 | */ |
| 331 | virtual wxCoord OnGetRowHeight(size_t row) const = 0; |
| 332 | }; |
| 333 | |
| 334 | |
| 335 | |
| 336 | /** |
| 337 | @class wxVarHScrollHelper |
| 338 | |
| 339 | This class provides functions wrapping the wxVarScrollHelperBase class, |
| 340 | targeted for horizontal-specific scrolling. |
| 341 | |
| 342 | Like wxVarScrollHelperBase, this class is mostly only useful to those |
| 343 | classes built into wxWidgets deriving from here, and this documentation is |
| 344 | mostly only provided for referencing the functions provided by this class. |
| 345 | You will likely want to derive your window from wxHScrolledWindow rather |
| 346 | than from here directly. |
| 347 | |
| 348 | @library{wxcore} |
| 349 | @category{miscwnd} |
| 350 | |
| 351 | @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow |
| 352 | */ |
| 353 | class wxVarHScrollHelper : public wxVarScrollHelperBase |
| 354 | { |
| 355 | public: |
| 356 | /** |
| 357 | Constructor taking the target window to be scrolled by this helper |
| 358 | class. This will attach scroll event handlers to the target window to |
| 359 | catch and handle scroll events appropriately. |
| 360 | */ |
| 361 | wxVarHScrollHelper(wxWindow* winToScroll); |
| 362 | |
| 363 | /** |
| 364 | Returns the number of columns the target window contains. |
| 365 | |
| 366 | @see SetColumnCount() |
| 367 | */ |
| 368 | size_t GetColumnCount() const; |
| 369 | |
| 370 | /** |
| 371 | Returns the index of the first visible column based on the scroll |
| 372 | position. |
| 373 | */ |
| 374 | size_t GetVisibleColumnsBegin() const; |
| 375 | |
| 376 | /** |
| 377 | Returns the index of the last visible column based on the scroll |
| 378 | position. This includes the last column even if it is only partially |
| 379 | visible. |
| 380 | */ |
| 381 | size_t GetVisibleColumnsEnd() const; |
| 382 | |
| 383 | /** |
| 384 | Returns @true if the given column is currently visible (even if only |
| 385 | partially visible) or @false otherwise. |
| 386 | */ |
| 387 | bool IsColumnVisible(size_t column) const; |
| 388 | |
| 389 | /** |
| 390 | Triggers a refresh for just the given column's area of the window if |
| 391 | it's visible. |
| 392 | */ |
| 393 | virtual void RefreshColumn(size_t column); |
| 394 | |
| 395 | /** |
| 396 | Triggers a refresh for the area between the specified range of columns |
| 397 | given (inclusively). |
| 398 | */ |
| 399 | virtual void RefreshColumns(size_t from, size_t to); |
| 400 | |
| 401 | /** |
| 402 | Scroll by the specified number of pages which may be positive (to |
| 403 | scroll right) or negative (to scroll left). |
| 404 | */ |
| 405 | virtual bool ScrollColumnPages(int pages); |
| 406 | |
| 407 | /** |
| 408 | Scroll by the specified number of columns which may be positive (to |
| 409 | scroll right) or negative (to scroll left). |
| 410 | |
| 411 | @return @true if the window was scrolled, @false otherwise (for |
| 412 | example, if we're trying to scroll right but we are already |
| 413 | showing the last column). |
| 414 | */ |
| 415 | virtual bool ScrollColumns(int columns); |
| 416 | |
| 417 | /** |
| 418 | Scroll to the specified column. It will become the first visible column |
| 419 | in the window. |
| 420 | |
| 421 | @return @true if we scrolled the window, @false if nothing was done. |
| 422 | */ |
| 423 | bool ScrollToColumn(size_t column); |
| 424 | |
| 425 | /** |
| 426 | Set the number of columns the window contains. The derived class must |
| 427 | provide the widths for all columns with indices up to the one given |
| 428 | here in it's OnGetColumnWidth() implementation. |
| 429 | |
| 430 | @see GetColumnCount() |
| 431 | */ |
| 432 | void SetColumnCount(size_t columnCount); |
| 433 | |
| 434 | protected: |
| 435 | |
| 436 | /** |
| 437 | This class forwards calls from EstimateTotalSize() to this function so |
| 438 | derived classes can override either just the height or the width |
| 439 | estimation, or just estimate both differently if desired in any |
| 440 | wxHVScrolledWindow derived class. |
| 441 | |
| 442 | @note This function will not be called if EstimateTotalSize() is |
| 443 | overridden in your derived class. |
| 444 | */ |
| 445 | virtual wxCoord EstimateTotalWidth() const; |
| 446 | |
| 447 | /** |
| 448 | This function doesn't have to be overridden but it may be useful to do |
| 449 | so if calculating the columns' sizes is a relatively expensive |
| 450 | operation as it gives your code a chance to calculate several of them |
| 451 | at once and cache the result if necessary. |
| 452 | |
| 453 | OnGetColumnsWidthHint() is normally called just before |
| 454 | OnGetColumnWidth() but you shouldn't rely on the latter being called |
| 455 | for all columns in the interval specified here. It is also possible |
| 456 | that OnGetColumnWidth() will be called for units outside of this |
| 457 | interval, so this is really just a hint, not a promise. |
| 458 | |
| 459 | Finally, note that @a columnMin is inclusive, while @a columnMax is |
| 460 | exclusive. |
| 461 | */ |
| 462 | virtual void OnGetColumnsWidthHint(size_t columnMin, |
| 463 | size_t columnMax) const; |
| 464 | |
| 465 | /** |
| 466 | This function must be overridden in the derived class, and should |
| 467 | return the width of the given column in pixels. |
| 468 | */ |
| 469 | virtual wxCoord OnGetColumnWidth(size_t column) const = 0; |
| 470 | }; |
| 471 | |
| 472 | |
| 473 | |
| 474 | /** |
| 475 | @class wxVarHVScrollHelper |
| 476 | |
| 477 | This class provides functions wrapping the wxVarHScrollHelper and |
| 478 | wxVarVScrollHelper classes, targeted for scrolling a window in both axis. |
| 479 | Since this class is also the join class of the horizontal and vertical |
| 480 | scrolling functionality, it also addresses some wrappers that help avoid |
| 481 | the need to specify class scope in your wxHVScrolledWindow derived class |
| 482 | when using wxVarScrollHelperBase functionality. |
| 483 | |
| 484 | Like all three of it's scroll helper base classes, this class is mostly |
| 485 | only useful to those classes built into wxWidgets deriving from here, and |
| 486 | this documentation is mostly only provided for referencing the functions |
| 487 | provided by this class. You will likely want to derive your window from |
| 488 | wxHVScrolledWindow rather than from here directly. |
| 489 | |
| 490 | @library{wxcore} |
| 491 | @category{miscwnd} |
| 492 | |
| 493 | @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow |
| 494 | */ |
| 495 | class wxVarHVScrollHelper : public wxVarVScrollHelper, |
| 496 | public wxVarHScrollHelper |
| 497 | { |
| 498 | public: |
| 499 | /** |
| 500 | Constructor taking the target window to be scrolled by this helper |
| 501 | class. This will attach scroll event handlers to the target window to |
| 502 | catch and handle scroll events appropriately. |
| 503 | */ |
| 504 | wxVarHVScrollHelper(wxWindow* winToScroll); |
| 505 | |
| 506 | /** |
| 507 | With physical scrolling on (when this is @true), the device origin is |
| 508 | changed properly when a wxPaintDC is prepared, children are actually |
| 509 | moved and laid out properly, and the contents of the window (pixels) |
| 510 | are actually moved. When this is @false, you are responsible for |
| 511 | repainting any invalidated areas of the window yourself to account for |
| 512 | the new scroll position. |
| 513 | |
| 514 | @param vscrolling |
| 515 | Specifies if physical scrolling should be turned on when scrolling |
| 516 | vertically. |
| 517 | @param hscrolling |
| 518 | Specifies if physical scrolling should be turned on when scrolling |
| 519 | horizontally. |
| 520 | */ |
| 521 | void EnablePhysicalScrolling(bool vscrolling = true, |
| 522 | bool hscrolling = true); |
| 523 | |
| 524 | /** |
| 525 | Returns the number of columns and rows the target window contains. |
| 526 | |
| 527 | @see SetRowColumnCount() |
| 528 | */ |
| 529 | wxSize GetRowColumnCount() const; |
| 530 | |
| 531 | /** |
| 532 | Returns the index of the first visible column and row based on the |
| 533 | current scroll position. |
| 534 | */ |
| 535 | wxPosition GetVisibleBegin() const; |
| 536 | |
| 537 | /** |
| 538 | Returns the index of the last visible column and row based on the |
| 539 | scroll position. This includes any partially visible columns or rows. |
| 540 | */ |
| 541 | wxPosition GetVisibleEnd() const; |
| 542 | |
| 543 | //@{ |
| 544 | /** |
| 545 | Returns @true if both the given row and column are currently visible |
| 546 | (even if only partially visible) or @false otherwise. |
| 547 | */ |
| 548 | bool IsVisible(size_t row, size_t column) const; |
| 549 | bool IsVisible(const wxPosition& pos) const; |
| 550 | //@} |
| 551 | |
| 552 | //@{ |
| 553 | /** |
| 554 | Triggers a refresh for just the area shared between the given row and |
| 555 | column of the window if it is visible. |
| 556 | */ |
| 557 | virtual void RefreshRowColumn(size_t row, size_t column); |
| 558 | virtual void RefreshRowColumn(const wxPosition& pos); |
| 559 | //@} |
| 560 | |
| 561 | //@{ |
| 562 | /** |
| 563 | Triggers a refresh for the visible area shared between all given rows |
| 564 | and columns (inclusive) of the window. If the target window for both |
| 565 | orientations is the same, the rectangle of cells is refreshed; if the |
| 566 | target windows differ, the entire client size opposite the orientation |
| 567 | direction is refreshed between the specified limits. |
| 568 | */ |
| 569 | virtual void RefreshRowsColumns(size_t fromRow, size_t toRow, |
| 570 | size_t fromColumn, size_t toColumn); |
| 571 | virtual void RefreshRowsColumns(const wxPosition& from, |
| 572 | const wxPosition& to); |
| 573 | //@} |
| 574 | |
| 575 | //@{ |
| 576 | /** |
| 577 | Scroll to the specified row and column. It will become the first |
| 578 | visible row and column in the window. Returns @true if we scrolled the |
| 579 | window, @false if nothing was done. |
| 580 | */ |
| 581 | bool ScrollToRowColumn(size_t row, size_t column); |
| 582 | bool ScrollToRowColumn(const wxPosition& pos); |
| 583 | //@} |
| 584 | |
| 585 | /** |
| 586 | Set the number of rows and columns the target window will contain. The |
| 587 | derived class must provide the sizes for all rows and columns with |
| 588 | indices up to the ones given here in it's OnGetRowHeight() and |
| 589 | OnGetColumnWidth() implementations, respectively. |
| 590 | |
| 591 | @see GetRowColumnCount() |
| 592 | */ |
| 593 | void SetRowColumnCount(size_t rowCount, size_t columnCount); |
| 594 | |
| 595 | //@{ |
| 596 | /** |
| 597 | Returns the virtual scroll unit under the device unit given accounting |
| 598 | for scroll position or @c wxNOT_FOUND (for the row, column, or possibly |
| 599 | both values) if none. |
| 600 | */ |
| 601 | wxPosition VirtualHitTest(wxCoord x, wxCoord y) const; |
| 602 | wxPosition VirtualHitTest(const wxPoint& pos) const; |
| 603 | //@} |
| 604 | }; |
| 605 | |
| 606 | |
| 607 | |
| 608 | /** |
| 609 | @class wxVScrolledWindow |
| 610 | |
| 611 | In the name of this class, "V" may stand for "variable" because it can be |
| 612 | used for scrolling rows of variable heights; "virtual", because it is not |
| 613 | necessary to know the heights of all rows in advance -- only those which |
| 614 | are shown on the screen need to be measured; or even "vertical", because |
| 615 | this class only supports scrolling vertically. |
| 616 | |
| 617 | In any case, this is a generalization of wxScrolled which can be only used |
| 618 | when all rows have the same heights. It lacks some other wxScrolled |
| 619 | features however, notably it can't scroll specific pixel sizes of the |
| 620 | window or its exact client area size. |
| 621 | |
| 622 | To use this class, you need to derive from it and implement the |
| 623 | OnGetRowHeight() pure virtual method. You also must call SetRowCount() to |
| 624 | let the base class know how many rows it should display, but from that |
| 625 | moment on the scrolling is handled entirely by wxVScrolledWindow. You only |
| 626 | need to draw the visible part of contents in your @c OnPaint() method as |
| 627 | usual. You should use GetVisibleRowsBegin() and GetVisibleRowsEnd() to |
| 628 | select the lines to display. Note that the device context origin is not |
| 629 | shifted so the first visible row always appears at the point (0, 0) in |
| 630 | physical as well as logical coordinates. |
| 631 | |
| 632 | @section vscrolledwindow_compat wxWidgets 2.8 Compatibility Functions |
| 633 | |
| 634 | The following functions provide backwards compatibility for applications |
| 635 | originally built using wxVScrolledWindow in 2.6 or 2.8. Originally, |
| 636 | wxVScrolledWindow referred to scrolling "lines". We now use "units" in |
| 637 | wxVarScrollHelperBase to avoid implying any orientation (since the |
| 638 | functions are used for both horizontal and vertical scrolling in derived |
| 639 | classes). And in the new wxVScrolledWindow and wxHScrolledWindow classes, |
| 640 | we refer to them as "rows" and "columns", respectively. This is to help |
| 641 | clear some confusion in not only those classes, but also in |
| 642 | wxHVScrolledWindow where functions are inherited from both. |
| 643 | |
| 644 | You are encouraged to update any existing code using these function to use |
| 645 | the new replacements mentioned below, and avoid using these functions for |
| 646 | any new code as they are deprecated. |
| 647 | |
| 648 | @beginTable |
| 649 | @row2col{ <tt>size_t %GetFirstVisibleLine() const</tt>, |
| 650 | Deprecated for GetVisibleRowsBegin(). } |
| 651 | @row2col{ <tt>size_t %GetLastVisibleLine() const</tt>, |
| 652 | Deprecated for GetVisibleRowsEnd(). This function originally had a |
| 653 | slight design flaw in that it was possible to return |
| 654 | <tt>(size_t)-1</tt> (ie: a large positive number) if the scroll |
| 655 | position was 0 and the first line wasn't completely visible. } |
| 656 | @row2col{ <tt>size_t %GetLineCount() const</tt>, |
| 657 | Deprecated for GetRowCount(). } |
| 658 | @row2col{ <tt>int %HitTest(wxCoord x\, wxCoord y) const |
| 659 | @n int %HitTest(const wxPoint& pt) const</tt>, |
| 660 | Deprecated for VirtualHitTest(). } |
| 661 | @row2col{ <tt>virtual wxCoord %OnGetLineHeight(size_t line) const</tt>, |
| 662 | Deprecated for OnGetRowHeight(). } |
| 663 | @row2col{ <tt>virtual void %OnGetLinesHint(size_t lineMin\, size_t lineMax) const</tt>, |
| 664 | Deprecated for OnGetRowsHeightHint(). } |
| 665 | @row2col{ <tt>virtual void %RefreshLine(size_t line)</tt>, |
| 666 | Deprecated for RefreshRow(). } |
| 667 | @row2col{ <tt>virtual void %RefreshLines(size_t from\, size_t to)</tt>, |
| 668 | Deprecated for RefreshRows(). } |
| 669 | @row2col{ <tt>virtual bool %ScrollLines(int lines)</tt>, |
| 670 | Deprecated for ScrollRows(). } |
| 671 | @row2col{ <tt>virtual bool %ScrollPages(int pages)</tt>, |
| 672 | Deprecated for ScrollRowPages(). } |
| 673 | @row2col{ <tt>bool %ScrollToLine(size_t line)</tt>, |
| 674 | Deprecated for ScrollToRow(). } |
| 675 | @row2col{ <tt>void %SetLineCount(size_t count)</tt>, |
| 676 | Deprecated for SetRowCount(). } |
| 677 | @endTable |
| 678 | |
| 679 | @library{wxcore} |
| 680 | @category{miscwnd} |
| 681 | |
| 682 | @see wxHScrolledWindow, wxHVScrolledWindow |
| 683 | */ |
| 684 | class wxVScrolledWindow : public wxPanel, public wxVarVScrollHelper |
| 685 | { |
| 686 | public: |
| 687 | /** |
| 688 | Default constructor, you must call Create() later. |
| 689 | */ |
| 690 | wxVScrolledWindow(); |
| 691 | /** |
| 692 | This is the normal constructor, no need to call Create() after using |
| 693 | this constructor. |
| 694 | |
| 695 | @note @c wxVSCROLL is always automatically added to the style, there is |
| 696 | no need to specify it explicitly. |
| 697 | |
| 698 | @param parent |
| 699 | The parent window, must not be @NULL. |
| 700 | @param id |
| 701 | The identifier of this window, wxID_ANY by default. |
| 702 | @param pos |
| 703 | The initial window position. |
| 704 | @param size |
| 705 | The initial window size. |
| 706 | @param style |
| 707 | The window style. There are no special style bits defined for this |
| 708 | class. |
| 709 | @param name |
| 710 | The name for this window; usually not used. |
| 711 | */ |
| 712 | wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 713 | const wxPoint& pos = wxDefaultPosition, |
| 714 | const wxSize& size = wxDefaultSize, long style = 0, |
| 715 | const wxString& name = wxPanelNameStr); |
| 716 | |
| 717 | /** |
| 718 | Same as the non-default constructor, but returns a status code: @true if |
| 719 | ok, @false if the window couldn't be created. |
| 720 | |
| 721 | Just as with the constructor, the @c wxVSCROLL style is always used, |
| 722 | there is no need to specify it explicitly. |
| 723 | */ |
| 724 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 725 | const wxPoint& pos = wxDefaultPosition, |
| 726 | const wxSize& size = wxDefaultSize, long style = 0, |
| 727 | const wxString& name = wxPanelNameStr); |
| 728 | }; |
| 729 | |
| 730 | |
| 731 | |
| 732 | /** |
| 733 | @class wxHScrolledWindow |
| 734 | |
| 735 | In the name of this class, "H" stands for "horizontal" because it can be |
| 736 | used for scrolling columns of variable widths. It is not necessary to know |
| 737 | the widths of all columns in advance -- only those which are shown on the |
| 738 | screen need to be measured. |
| 739 | |
| 740 | In any case, this is a generalization of wxScrolled which can be only used |
| 741 | when all columns have the same widths. It lacks some other wxScrolled |
| 742 | features however, notably it can't scroll specific pixel sizes of the |
| 743 | window or its exact client area size. |
| 744 | |
| 745 | To use this class, you need to derive from it and implement the |
| 746 | OnGetColumnWidth() pure virtual method. You also must call SetColumnCount() |
| 747 | to let the base class know how many columns it should display, but from |
| 748 | that moment on the scrolling is handled entirely by wxHScrolledWindow. You |
| 749 | only need to draw the visible part of contents in your @c OnPaint() method |
| 750 | as usual. You should use GetVisibleColumnsBegin() and |
| 751 | GetVisibleColumnsEnd() to select the lines to display. Note that the device |
| 752 | context origin is not shifted so the first visible column always appears at |
| 753 | the point (0, 0) in physical as well as logical coordinates. |
| 754 | |
| 755 | @library{wxcore} |
| 756 | @category{miscwnd} |
| 757 | |
| 758 | @see wxHVScrolledWindow, wxVScrolledWindow |
| 759 | */ |
| 760 | class wxHScrolledWindow : public wxPanel, public wxVarHScrollHelper |
| 761 | { |
| 762 | public: |
| 763 | /** |
| 764 | Default constructor, you must call Create() later. |
| 765 | */ |
| 766 | wxHScrolledWindow(); |
| 767 | /** |
| 768 | This is the normal constructor, no need to call Create() after using |
| 769 | this constructor. |
| 770 | |
| 771 | @note @c wxHSCROLL is always automatically added to the style, there is |
| 772 | no need to specify it explicitly. |
| 773 | |
| 774 | @param parent |
| 775 | The parent window, must not be @NULL. |
| 776 | @param id |
| 777 | The identifier of this window, wxID_ANY by default. |
| 778 | @param pos |
| 779 | The initial window position. |
| 780 | @param size |
| 781 | The initial window size. |
| 782 | @param style |
| 783 | The window style. There are no special style bits defined for this |
| 784 | class. |
| 785 | @param name |
| 786 | The name for this window; usually not used. |
| 787 | */ |
| 788 | wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 789 | const wxPoint& pos = wxDefaultPosition, |
| 790 | const wxSize& size = wxDefaultSize, long style = 0, |
| 791 | const wxString& name = wxPanelNameStr); |
| 792 | |
| 793 | /** |
| 794 | Same as the non-default constructor, but returns a status code: @true if |
| 795 | ok, @false if the window couldn't be created. |
| 796 | |
| 797 | Just as with the constructor, the @c wxHSCROLL style is always used, |
| 798 | there is no need to specify it explicitly. |
| 799 | */ |
| 800 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 801 | const wxPoint& pos = wxDefaultPosition, |
| 802 | const wxSize& size = wxDefaultSize, long style = 0, |
| 803 | const wxString& name = wxPanelNameStr); |
| 804 | }; |
| 805 | |
| 806 | |
| 807 | |
| 808 | /** |
| 809 | @class wxHVScrolledWindow |
| 810 | |
| 811 | This window inherits all functionality of both vertical and horizontal, |
| 812 | variable scrolled windows. It automatically handles everything needed to |
| 813 | scroll both axis simultaneously with both variable row heights and variable |
| 814 | column widths. |
| 815 | |
| 816 | In any case, this is a generalization of wxScrolled which can be only used |
| 817 | when all rows and columns are the same size. It lacks some other wxScrolled |
| 818 | features however, notably it can't scroll specific pixel sizes of the |
| 819 | window or its exact client area size. |
| 820 | |
| 821 | To use this class, you must derive from it and implement both the |
| 822 | OnGetRowHeight() and OnGetColumnWidth() pure virtual methods to let the |
| 823 | base class know how many rows and columns it should display. You also need |
| 824 | to set the total rows and columns the window contains, but from that moment |
| 825 | on the scrolling is handled entirely by wxHVScrolledWindow. You only need |
| 826 | to draw the visible part of contents in your @c OnPaint() method as usual. |
| 827 | You should use GetVisibleBegin() and GetVisibleEnd() to select the lines to |
| 828 | display. Note that the device context origin is not shifted so the first |
| 829 | visible row and column always appear at the point (0, 0) in physical as |
| 830 | well as logical coordinates. |
| 831 | |
| 832 | @library{wxcore} |
| 833 | @category{miscwnd} |
| 834 | |
| 835 | @see wxHScrolledWindow, wxVScrolledWindow |
| 836 | */ |
| 837 | class wxHVScrolledWindow : public wxPanel, public wxVarHVScrollHelper |
| 838 | { |
| 839 | public: |
| 840 | /** |
| 841 | Default constructor, you must call Create() later. |
| 842 | */ |
| 843 | wxHVScrolledWindow(); |
| 844 | /** |
| 845 | This is the normal constructor, no need to call Create() after using |
| 846 | this constructor. |
| 847 | |
| 848 | @note @c wxHSCROLL and @c wxVSCROLL are always automatically added to |
| 849 | the style, there is no need to specify it explicitly. |
| 850 | |
| 851 | @param parent |
| 852 | The parent window, must not be @NULL. |
| 853 | @param id |
| 854 | The identifier of this window, wxID_ANY by default. |
| 855 | @param pos |
| 856 | The initial window position. |
| 857 | @param size |
| 858 | The initial window size. |
| 859 | @param style |
| 860 | The window style. There are no special style bits defined for this |
| 861 | class. |
| 862 | @param name |
| 863 | The name for this window; usually not used. |
| 864 | */ |
| 865 | wxHVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 866 | const wxPoint& pos = wxDefaultPosition, |
| 867 | const wxSize& size = wxDefaultSize, long style = 0, |
| 868 | const wxString& name = wxPanelNameStr); |
| 869 | |
| 870 | /** |
| 871 | Same as the non-default constructor, but returns a status code: @true if |
| 872 | ok, @false if the window couldn't be created. |
| 873 | |
| 874 | Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles |
| 875 | are always used, there is no need to specify them explicitly. |
| 876 | */ |
| 877 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, |
| 878 | const wxPoint& pos = wxDefaultPosition, |
| 879 | const wxSize& size = wxDefaultSize, long style = 0, |
| 880 | const wxString& name = wxPanelNameStr); |
| 881 | }; |
| 882 | |