1 | /************************************************************************
|
---|
2 | filename: CEGUIMultiColumnList.h
|
---|
3 | created: 13/4/2004
|
---|
4 | author: Paul D Turner
|
---|
5 |
|
---|
6 | purpose: Interface to base class for MultiColumnList widget
|
---|
7 | *************************************************************************/
|
---|
8 | /*************************************************************************
|
---|
9 | Crazy Eddie's GUI System (http://www.cegui.org.uk)
|
---|
10 | Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
|
---|
11 |
|
---|
12 | This library is free software; you can redistribute it and/or
|
---|
13 | modify it under the terms of the GNU Lesser General Public
|
---|
14 | License as published by the Free Software Foundation; either
|
---|
15 | version 2.1 of the License, or (at your option) any later version.
|
---|
16 |
|
---|
17 | This library is distributed in the hope that it will be useful,
|
---|
18 | but WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
19 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
20 | Lesser General Public License for more details.
|
---|
21 |
|
---|
22 | You should have received a copy of the GNU Lesser General Public
|
---|
23 | License along with this library; if not, write to the Free Software
|
---|
24 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
---|
25 | *************************************************************************/
|
---|
26 | #ifndef _CEGUIMultiColumnList_h_
|
---|
27 | #define _CEGUIMultiColumnList_h_
|
---|
28 |
|
---|
29 | #include "CEGUIBase.h"
|
---|
30 | #include "CEGUIWindow.h"
|
---|
31 | #include "CEGUIListHeader.h"
|
---|
32 | #include "elements/CEGUIMultiColumnListProperties.h"
|
---|
33 |
|
---|
34 |
|
---|
35 | #if defined(_MSC_VER)
|
---|
36 | # pragma warning(push)
|
---|
37 | # pragma warning(disable : 4251)
|
---|
38 | #endif
|
---|
39 |
|
---|
40 |
|
---|
41 | // Start of CEGUI namespace section
|
---|
42 | namespace CEGUI
|
---|
43 | {
|
---|
44 |
|
---|
45 | /*!
|
---|
46 | \brief
|
---|
47 | Simple grid index structure.
|
---|
48 | */
|
---|
49 | struct CEGUIEXPORT MCLGridRef
|
---|
50 | {
|
---|
51 | MCLGridRef(uint r, uint c) : row(r), column(c) {}
|
---|
52 |
|
---|
53 | uint row; //!< Zero based row index.
|
---|
54 | uint column; //!< Zero based column index.
|
---|
55 |
|
---|
56 | // operators
|
---|
57 | MCLGridRef& operator=(const MCLGridRef& rhs);
|
---|
58 | bool operator<(const MCLGridRef& rhs) const;
|
---|
59 | bool operator<=(const MCLGridRef& rhs) const;
|
---|
60 | bool operator>(const MCLGridRef& rhs) const;
|
---|
61 | bool operator>=(const MCLGridRef& rhs) const;
|
---|
62 | bool operator==(const MCLGridRef& rhs) const;
|
---|
63 | bool operator!=(const MCLGridRef& rhs) const;
|
---|
64 | };
|
---|
65 |
|
---|
66 |
|
---|
67 | /*!
|
---|
68 | \brief
|
---|
69 | Base class for the multi column list widget.
|
---|
70 | */
|
---|
71 | class CEGUIEXPORT MultiColumnList : public Window
|
---|
72 | {
|
---|
73 | public:
|
---|
74 | static const String EventNamespace; //!< Namespace for global events
|
---|
75 |
|
---|
76 |
|
---|
77 | /*************************************************************************
|
---|
78 | Constants
|
---|
79 | *************************************************************************/
|
---|
80 | // Event names
|
---|
81 | static const String EventSelectionModeChanged; //!< Event fired when the selection mode for the list box changes.
|
---|
82 | static const String EventNominatedSelectColumnChanged;//!< Event fired when the nominated select column changes.
|
---|
83 | static const String EventNominatedSelectRowChanged; //!< Event fired when the nominated select row changes.
|
---|
84 | static const String EventVertScrollbarModeChanged; //!< Event fired when the vertical scroll bar 'force' setting changes.
|
---|
85 | static const String EventHorzScrollbarModeChanged; //!< Event fired when the horizontal scroll bar 'force' setting changes.
|
---|
86 | static const String EventSelectionChanged; //!< Event fired when the current selection(s) within the list box changes.
|
---|
87 | static const String EventListContentsChanged; //!< Event fired when the contents of the list box changes.
|
---|
88 | static const String EventSortColumnChanged; //!< Event fired when the sort column changes.
|
---|
89 | static const String EventSortDirectionChanged; //!< Event fired when the sort direction changes.
|
---|
90 | static const String EventListColumnSized; //!< Event fired when the width of a column in the list changes.
|
---|
91 | static const String EventListColumnMoved; //!< Event fired when the column order changes.
|
---|
92 |
|
---|
93 |
|
---|
94 | /*************************************************************************
|
---|
95 | Enumerations
|
---|
96 | *************************************************************************/
|
---|
97 | /*!
|
---|
98 | \brief
|
---|
99 | Enumerated values for the selection modes possible with a Multi-column list
|
---|
100 | */
|
---|
101 | enum SelectionMode
|
---|
102 | {
|
---|
103 | RowSingle, // Any single row may be selected. All items in the row are selected.
|
---|
104 | RowMultiple, // Multiple rows may be selected. All items in the row are selected.
|
---|
105 | CellSingle, // Any single cell may be selected.
|
---|
106 | CellMultiple, // Multiple cells bay be selected.
|
---|
107 | NominatedColumnSingle, // Any single item in a nominated column may be selected.
|
---|
108 | NominatedColumnMultiple, // Multiple items in a nominated column may be selected.
|
---|
109 | ColumnSingle, // Any single column may be selected. All items in the column are selected.
|
---|
110 | ColumnMultiple, // Multiple columns may be selected. All items in the column are selected.
|
---|
111 | NominatedRowSingle, // Any single item in a nominated row may be selected.
|
---|
112 | NominatedRowMultiple // Multiple items in a nominated row may be selected.
|
---|
113 | };
|
---|
114 |
|
---|
115 |
|
---|
116 | /*************************************************************************
|
---|
117 | Accessor Methods
|
---|
118 | *************************************************************************/
|
---|
119 | /*!
|
---|
120 | \brief
|
---|
121 | Return whether user manipulation of the sort column and direction are enabled.
|
---|
122 |
|
---|
123 | \return
|
---|
124 | true if the user may interactively modify the sort column and direction. false if the user may not
|
---|
125 | modify the sort column and direction (these can still be set programmatically).
|
---|
126 | */
|
---|
127 | bool isUserSortControlEnabled(void) const;
|
---|
128 |
|
---|
129 |
|
---|
130 | /*!
|
---|
131 | \brief
|
---|
132 | Return whether the user may size column segments.
|
---|
133 |
|
---|
134 | \return
|
---|
135 | true if the user may interactively modify the width of columns, false if they may not.
|
---|
136 | */
|
---|
137 | bool isUserColumnSizingEnabled(void) const;
|
---|
138 |
|
---|
139 |
|
---|
140 | /*!
|
---|
141 | \brief
|
---|
142 | Return whether the user may modify the order of the columns.
|
---|
143 |
|
---|
144 | \return
|
---|
145 | true if the user may interactively modify the order of the columns, false if they may not.
|
---|
146 | */
|
---|
147 | bool isUserColumnDraggingEnabled(void) const;
|
---|
148 |
|
---|
149 |
|
---|
150 | /*!
|
---|
151 | \brief
|
---|
152 | Return the number of columns in the multi-column list
|
---|
153 |
|
---|
154 | \return
|
---|
155 | uint value equal to the number of columns in the list.
|
---|
156 | */
|
---|
157 | uint getColumnCount(void) const;
|
---|
158 |
|
---|
159 |
|
---|
160 | /*!
|
---|
161 | \brief
|
---|
162 | Return the number of rows in the multi-column list.
|
---|
163 |
|
---|
164 | \return
|
---|
165 | uint value equal to the number of rows currently in the list.
|
---|
166 | */
|
---|
167 | uint getRowCount(void) const;
|
---|
168 |
|
---|
169 |
|
---|
170 | /*!
|
---|
171 | \brief
|
---|
172 | Return the zero based index of the current sort column. There must be at least one column to successfully call this
|
---|
173 | method.
|
---|
174 |
|
---|
175 | \return
|
---|
176 | Zero based column index that is the current sort column.
|
---|
177 |
|
---|
178 | \exception InvalidRequestException thrown if there are no columns in this multi column list.
|
---|
179 | */
|
---|
180 | uint getSortColumn(void) const;
|
---|
181 |
|
---|
182 |
|
---|
183 | /*!
|
---|
184 | \brief
|
---|
185 | Return the zero based column index of the column with the specified ID.
|
---|
186 |
|
---|
187 | \param col_id
|
---|
188 | ID code of the column whos index is to be returned.
|
---|
189 |
|
---|
190 | \return
|
---|
191 | Zero based column index of the first column whos ID matches \a col_id.
|
---|
192 |
|
---|
193 | \exception InvalidRequestException thrown if no attached column has the requested ID.
|
---|
194 | */
|
---|
195 | uint getColumnWithID(uint col_id) const;
|
---|
196 |
|
---|
197 |
|
---|
198 | /*!
|
---|
199 | \brief
|
---|
200 | Return the zero based index of the column whos header text matches the specified text.
|
---|
201 |
|
---|
202 | \param text
|
---|
203 | String object containing the text to be searched for.
|
---|
204 |
|
---|
205 | \return
|
---|
206 | Zero based column index of the column whos header has the specified text.
|
---|
207 |
|
---|
208 | \exception InvalidRequestException thrown if no columns header has the requested text.
|
---|
209 | */
|
---|
210 | uint getColumnWithHeaderText(const String& text) const;
|
---|
211 |
|
---|
212 |
|
---|
213 | /*!
|
---|
214 | \brief
|
---|
215 | Return the total width of all column headers.
|
---|
216 |
|
---|
217 | \return
|
---|
218 | Sum total of all the column header widths in whichever metrics system is active.
|
---|
219 | */
|
---|
220 | float getTotalColumnHeadersWidth(void) const;
|
---|
221 |
|
---|
222 |
|
---|
223 | /*!
|
---|
224 | \brief
|
---|
225 | Return the width of the specified column header (and therefore the column itself).
|
---|
226 |
|
---|
227 | \param col_idx
|
---|
228 | Zero based column index of the column whos width is to be returned.
|
---|
229 |
|
---|
230 | \return
|
---|
231 | Width of the column header at the zero based column index specified by \a col_idx, in whichever is the active metrics system.
|
---|
232 |
|
---|
233 | \exception InvalidRequestException thrown if \a column is out of range.
|
---|
234 | */
|
---|
235 | float getColumnHeaderWidth(uint col_idx) const;
|
---|
236 |
|
---|
237 |
|
---|
238 | /*!
|
---|
239 | \brief
|
---|
240 | Return the currently set sort direction.
|
---|
241 |
|
---|
242 | \return
|
---|
243 | One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.
|
---|
244 | */
|
---|
245 | ListHeaderSegment::SortDirection getSortDirection(void) const;
|
---|
246 |
|
---|
247 |
|
---|
248 | /*!
|
---|
249 | \brief
|
---|
250 | Return the ListHeaderSegment object for the specified column
|
---|
251 |
|
---|
252 | \param col_idx
|
---|
253 | zero based index of the column whos ListHeaderSegment is to be returned.
|
---|
254 |
|
---|
255 | \return
|
---|
256 | ListHeaderSegment object for the column at the requested index.
|
---|
257 |
|
---|
258 | \exception InvalidRequestException thrown if \a col_idx is out of range.
|
---|
259 | */
|
---|
260 | ListHeaderSegment& getHeaderSegmentForColumn(uint col_idx) const;
|
---|
261 |
|
---|
262 |
|
---|
263 | /*!
|
---|
264 | \brief
|
---|
265 | Return the zero based index of the Row that contains \a item.
|
---|
266 |
|
---|
267 | \param item
|
---|
268 | Pointer to the ListboxItem that the row index is to returned for.
|
---|
269 |
|
---|
270 | \return
|
---|
271 | Zero based index of the row that contains ListboxItem \a item.
|
---|
272 |
|
---|
273 | \exception InvalidRequestException thrown if \a item is not attached to the list box.
|
---|
274 | */
|
---|
275 | uint getItemRowIndex(const ListboxItem* item) const;
|
---|
276 |
|
---|
277 |
|
---|
278 | /*!
|
---|
279 | \brief
|
---|
280 | Return the current zero based index of the column that contains \a item.
|
---|
281 |
|
---|
282 | \param item
|
---|
283 | Pointer to the ListboxItem that the column index is to returned for.
|
---|
284 |
|
---|
285 | \return
|
---|
286 | Zero based index of the column that contains ListboxItem \a item.
|
---|
287 |
|
---|
288 | \exception InvalidRequestException thrown if \a item is not attached to the list box.
|
---|
289 | */
|
---|
290 | uint getItemColumnIndex(const ListboxItem* item) const;
|
---|
291 |
|
---|
292 |
|
---|
293 | /*!
|
---|
294 | \brief
|
---|
295 | Return the grid reference for \a item.
|
---|
296 |
|
---|
297 | \param item
|
---|
298 | Pointer to the ListboxItem whos current grid reference is to be returned.
|
---|
299 |
|
---|
300 | \return
|
---|
301 | MCLGridRef object describing the current grid reference of ListboxItem \a item.
|
---|
302 |
|
---|
303 | \exception InvalidRequestException thrown if \a item is not attached to the list box.
|
---|
304 | */
|
---|
305 | MCLGridRef getItemGridReference(const ListboxItem* item) const;
|
---|
306 |
|
---|
307 |
|
---|
308 | /*!
|
---|
309 | \brief
|
---|
310 | Return a pointer to the ListboxItem at the specified grid reference.
|
---|
311 |
|
---|
312 | \param grid_ref
|
---|
313 | MCLGridRef object that describes the position of the ListboxItem to be returned.
|
---|
314 |
|
---|
315 | \return
|
---|
316 | Pointer to the ListboxItem at grid reference \a grid_ref.
|
---|
317 |
|
---|
318 | \exception InvalidRequestException thrown if \a grid_ref is invalid for this list box.
|
---|
319 | */
|
---|
320 | ListboxItem* getItemAtGridReference(const MCLGridRef& grid_ref) const;
|
---|
321 |
|
---|
322 |
|
---|
323 | /*!
|
---|
324 | \brief
|
---|
325 | return whether ListboxItem \a item is attached to the column at index \a col_idx.
|
---|
326 |
|
---|
327 | \param item
|
---|
328 | Pointer to the ListboxItem to look for.
|
---|
329 |
|
---|
330 | \param col_idx
|
---|
331 | Zero based index of the column that is to be searched.
|
---|
332 |
|
---|
333 | \return
|
---|
334 | - true if \a item is attached to list box column \a col_idx.
|
---|
335 | - false if \a item is not attached to list box column \a col_idx.
|
---|
336 |
|
---|
337 | \exception InvalidRequestException thrown if \a col_idx is out of range.
|
---|
338 | */
|
---|
339 | bool isListboxItemInColumn(const ListboxItem* item, uint col_idx) const;
|
---|
340 |
|
---|
341 |
|
---|
342 | /*!
|
---|
343 | \brief
|
---|
344 | return whether ListboxItem \a item is attached to the row at index \a row_idx.
|
---|
345 |
|
---|
346 | \param item
|
---|
347 | Pointer to the ListboxItem to look for.
|
---|
348 |
|
---|
349 | \param row_idx
|
---|
350 | Zero based index of the row that is to be searched.
|
---|
351 |
|
---|
352 | \return
|
---|
353 | - true if \a item is attached to list box row \a row_idx.
|
---|
354 | - false if \a item is not attached to list box row \a row_idx.
|
---|
355 |
|
---|
356 | \exception InvalidRequestException thrown if \a row_idx is out of range.
|
---|
357 | */
|
---|
358 | bool isListboxItemInRow(const ListboxItem* item, uint row_idx) const;
|
---|
359 |
|
---|
360 |
|
---|
361 | /*!
|
---|
362 | \brief
|
---|
363 | return whether ListboxItem \a item is attached to the list box.
|
---|
364 |
|
---|
365 | \param item
|
---|
366 | Pointer to the ListboxItem to look for.
|
---|
367 |
|
---|
368 | \return
|
---|
369 | - true if \a item is attached to list box.
|
---|
370 | - false if \a item is not attached to list box.
|
---|
371 | */
|
---|
372 | bool isListboxItemInList(const ListboxItem* item) const;
|
---|
373 |
|
---|
374 |
|
---|
375 | /*!
|
---|
376 | \brief
|
---|
377 | Return the ListboxItem in column \a col_idx that has the text string \a text.
|
---|
378 |
|
---|
379 | \param text
|
---|
380 | String object containing the text to be searched for.
|
---|
381 |
|
---|
382 | \param col_idx
|
---|
383 | Zero based index of the column to be searched.
|
---|
384 |
|
---|
385 | \param start_item
|
---|
386 | Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the top of the column.
|
---|
387 |
|
---|
388 | \return
|
---|
389 | Pointer to the first ListboxItem in column \a col_idx, after \a start_item, that has the string \a text.
|
---|
390 |
|
---|
391 | \exception InvalidRequestException thrown if \a start_item is not attached to the list box, or if \a col_idx is out of range.
|
---|
392 | */
|
---|
393 | ListboxItem* findColumnItemWithText(const String& text, uint col_idx, const ListboxItem* start_item) const;
|
---|
394 |
|
---|
395 |
|
---|
396 | /*!
|
---|
397 | \brief
|
---|
398 | Return the ListboxItem in row \a row_idx that has the text string \a text.
|
---|
399 |
|
---|
400 | \param text
|
---|
401 | String object containing the text to be searched for.
|
---|
402 |
|
---|
403 | \param row_idx
|
---|
404 | Zero based index of the row to be searched.
|
---|
405 |
|
---|
406 | \param start_item
|
---|
407 | Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the start of the row.
|
---|
408 |
|
---|
409 | \return
|
---|
410 | Pointer to the first ListboxItem in row \a row_idx, after \a start_item, that has the string \a text.
|
---|
411 |
|
---|
412 | \exception InvalidRequestException thrown if \a start_item is not attached to the list box, or if \a row_idx is out of range.
|
---|
413 | */
|
---|
414 | ListboxItem* findRowItemWithText(const String& text, uint row_idx, const ListboxItem* start_item) const;
|
---|
415 |
|
---|
416 |
|
---|
417 | /*!
|
---|
418 | \brief
|
---|
419 | Return the ListboxItem that has the text string \a text.
|
---|
420 |
|
---|
421 | \note
|
---|
422 | List box searching progresses across the columns in each row.
|
---|
423 |
|
---|
424 | \param text
|
---|
425 | String object containing the text to be searched for.
|
---|
426 |
|
---|
427 | \param start_item
|
---|
428 | Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.
|
---|
429 |
|
---|
430 | \return
|
---|
431 | Pointer to the first ListboxItem, after \a start_item, that has the string \a text.
|
---|
432 |
|
---|
433 | \exception InvalidRequestException thrown if \a start_item is not attached to the list box.
|
---|
434 | */
|
---|
435 | ListboxItem* findListItemWithText(const String& text, const ListboxItem* start_item) const;
|
---|
436 |
|
---|
437 |
|
---|
438 | /*!
|
---|
439 | \brief
|
---|
440 | Return a pointer to the first selected ListboxItem attached to this list box.
|
---|
441 |
|
---|
442 | \note
|
---|
443 | List box searching progresses across the columns in each row.
|
---|
444 |
|
---|
445 | \return
|
---|
446 | Pointer to the first ListboxItem attached to this list box that is selected, or NULL if no item is selected.
|
---|
447 | */
|
---|
448 | ListboxItem* getFirstSelectedItem(void) const;
|
---|
449 |
|
---|
450 |
|
---|
451 | /*!
|
---|
452 | \brief
|
---|
453 | Return a pointer to the next selected ListboxItem after \a start_item.
|
---|
454 |
|
---|
455 | \note
|
---|
456 | List box searching progresses across the columns in each row.
|
---|
457 |
|
---|
458 | \param start_item
|
---|
459 | Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.
|
---|
460 |
|
---|
461 | \return
|
---|
462 | Pointer to the first selected ListboxItem attached to this list box, after \a start_item, or NULL if no item is selected.
|
---|
463 |
|
---|
464 | \exception InvalidRequestException thrown if \a start_item is not attached to the list box.
|
---|
465 | */
|
---|
466 | ListboxItem* getNextSelected(const ListboxItem* start_item) const;
|
---|
467 |
|
---|
468 |
|
---|
469 | /*!
|
---|
470 | \brief
|
---|
471 | Return the number of selected ListboxItems attached to this list box.
|
---|
472 |
|
---|
473 | return
|
---|
474 | uint value equal to the number of ListboxItems attached to this list box that are currently selected.
|
---|
475 | */
|
---|
476 | uint getSelectedCount(void) const;
|
---|
477 |
|
---|
478 |
|
---|
479 | /*!
|
---|
480 | \brief
|
---|
481 | Return whether the ListboxItem at \a grid_ref is selected.
|
---|
482 |
|
---|
483 | \param grid_ref
|
---|
484 | MCLGridRef object describing the grid reference that is to be examined.
|
---|
485 |
|
---|
486 | \return
|
---|
487 | - true if there is a ListboxItem at \a grid_ref and it is selected.
|
---|
488 | - false if there is no ListboxItem at \a grid_ref, or if the item is not selected.
|
---|
489 |
|
---|
490 | \exception InvalidRequestException thrown if \a grid_ref contains an invalid grid position.
|
---|
491 | */
|
---|
492 | bool isItemSelected(const MCLGridRef& grid_ref) const;
|
---|
493 |
|
---|
494 |
|
---|
495 | /*!
|
---|
496 | \brief
|
---|
497 | Return the ID of the currently set nominated selection column to be used when in one of the NominatedColumn*
|
---|
498 | selection modes.
|
---|
499 |
|
---|
500 | \note
|
---|
501 | You should only ever call this when getColumnCount() returns > 0.
|
---|
502 |
|
---|
503 | \return
|
---|
504 | ID code of the nominated selection column.
|
---|
505 | */
|
---|
506 | uint getNominatedSelectionColumnID(void) const;
|
---|
507 |
|
---|
508 |
|
---|
509 | /*!
|
---|
510 | \brief
|
---|
511 | Return the index of the currently set nominated selection column to be used when in one of the NominatedColumn*
|
---|
512 | selection modes.
|
---|
513 |
|
---|
514 | \return
|
---|
515 | Zero based index of the nominated selection column.
|
---|
516 | */
|
---|
517 | uint getNominatedSelectionColumn(void) const;
|
---|
518 |
|
---|
519 |
|
---|
520 | /*!
|
---|
521 | \brief
|
---|
522 | Return the index of the currently set nominated selection row to be used when in one of the NominatedRow*
|
---|
523 | selection modes.
|
---|
524 |
|
---|
525 | \return
|
---|
526 | Zero based index of the nominated selection column.
|
---|
527 | */
|
---|
528 | uint getNominatedSelectionRow(void) const;
|
---|
529 |
|
---|
530 |
|
---|
531 | /*!
|
---|
532 | \brief
|
---|
533 | Return the currently set selection mode.
|
---|
534 |
|
---|
535 | \return
|
---|
536 | One of the MultiColumnList::SelectionMode enumerated values specifying the current selection mode.
|
---|
537 | */
|
---|
538 | MultiColumnList::SelectionMode getSelectionMode(void) const;
|
---|
539 |
|
---|
540 |
|
---|
541 | /*!
|
---|
542 | \brief
|
---|
543 | Return whether the vertical scroll bar is always shown.
|
---|
544 |
|
---|
545 | \return
|
---|
546 | - true if the scroll bar will always be shown even if it is not required.
|
---|
547 | - false if the scroll bar will only be shown when it is required.
|
---|
548 | */
|
---|
549 | bool isVertScrollbarAlwaysShown(void) const;
|
---|
550 |
|
---|
551 |
|
---|
552 | /*!
|
---|
553 | \brief
|
---|
554 | Return whether the horizontal scroll bar is always shown.
|
---|
555 |
|
---|
556 | \return
|
---|
557 | - true if the scroll bar will always be shown even if it is not required.
|
---|
558 | - false if the scroll bar will only be shown when it is required.
|
---|
559 | */
|
---|
560 | bool isHorzScrollbarAlwaysShown(void) const;
|
---|
561 |
|
---|
562 |
|
---|
563 | /*!
|
---|
564 | \brief
|
---|
565 | Return the ID code assigned to the requested column.
|
---|
566 |
|
---|
567 | \param col_idx
|
---|
568 | Zero based index of the column whos ID code is to be returned.
|
---|
569 |
|
---|
570 | \return
|
---|
571 | Current ID code assigned to the column at the requested index.
|
---|
572 |
|
---|
573 | \exception InvalidRequestException thrown if \a col_idx is out of range
|
---|
574 | */
|
---|
575 | uint getColumnID(uint col_idx) const;
|
---|
576 |
|
---|
577 |
|
---|
578 | /*!
|
---|
579 | \brief
|
---|
580 | Return the ID code assigned to the requested row.
|
---|
581 |
|
---|
582 | \param row_idx
|
---|
583 | Zero based index of the row who's ID code is to be returned.
|
---|
584 |
|
---|
585 | \return
|
---|
586 | Current ID code assigned to the row at the requested index.
|
---|
587 |
|
---|
588 | \exception InvalidRequestException thrown if \a row_idx is out of range
|
---|
589 | */
|
---|
590 | uint getRowID(uint row_idx) const;
|
---|
591 |
|
---|
592 |
|
---|
593 | /*!
|
---|
594 | \brief
|
---|
595 | Return the zero based row index of the row with the specified ID.
|
---|
596 |
|
---|
597 | \param row_id
|
---|
598 | ID code of the row who's index is to be returned.
|
---|
599 |
|
---|
600 | \return
|
---|
601 | Zero based row index of the first row who's ID matches \a row_id.
|
---|
602 |
|
---|
603 | \exception InvalidRequestException thrown if no row has the requested ID.
|
---|
604 | */
|
---|
605 | uint getRowWithID(uint row_id) const;
|
---|
606 |
|
---|
607 |
|
---|
608 | /*************************************************************************
|
---|
609 | Manipulator Methods
|
---|
610 | *************************************************************************/
|
---|
611 | /*!
|
---|
612 | \brief
|
---|
613 | Initialise the Window based object ready for use.
|
---|
614 |
|
---|
615 | \note
|
---|
616 | This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.
|
---|
617 |
|
---|
618 | \return
|
---|
619 | Nothing
|
---|
620 | */
|
---|
621 | virtual void initialise(void);
|
---|
622 |
|
---|
623 |
|
---|
624 | /*!
|
---|
625 | \brief
|
---|
626 | Remove all items from the list.
|
---|
627 |
|
---|
628 | Note that this will cause 'AutoDelete' items to be deleted.
|
---|
629 | */
|
---|
630 | void resetList(void);
|
---|
631 |
|
---|
632 |
|
---|
633 | /*!
|
---|
634 | \brief
|
---|
635 | Add a column to the list box.
|
---|
636 |
|
---|
637 | \param text
|
---|
638 | String object containing the text label for the column header.
|
---|
639 |
|
---|
640 | \param col_id
|
---|
641 | ID code to be assigned to the column header.
|
---|
642 |
|
---|
643 | \param width
|
---|
644 | Initial width to be set for the column using the active metrics mode for this window.
|
---|
645 |
|
---|
646 | \return
|
---|
647 | Nothing.
|
---|
648 | */
|
---|
649 | void addColumn(const String& text, uint col_id, float width);
|
---|
650 |
|
---|
651 |
|
---|
652 | /*!
|
---|
653 | \brief
|
---|
654 | Insert a new column in the list.
|
---|
655 |
|
---|
656 | \param text
|
---|
657 | String object containing the text label for the column header.
|
---|
658 |
|
---|
659 | \param col_id
|
---|
660 | ID code to be assigned to the column header.
|
---|
661 |
|
---|
662 | \param width
|
---|
663 | Initial width to be set for the column using the active metrics mode for this window.
|
---|
664 |
|
---|
665 | \param position
|
---|
666 | Zero based index where the column is to be inserted. If this is greater than the current
|
---|
667 | number of columns, the new column is inserted at the end.
|
---|
668 |
|
---|
669 | \return
|
---|
670 | Nothing.
|
---|
671 | */
|
---|
672 | void insertColumn(const String& text, uint col_id, float width, uint position);
|
---|
673 |
|
---|
674 |
|
---|
675 | /*!
|
---|
676 | \brief
|
---|
677 | Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
|
---|
678 |
|
---|
679 | \param col_idx
|
---|
680 | Zero based index of the column to be removed.
|
---|
681 |
|
---|
682 | \return
|
---|
683 | Nothing.
|
---|
684 |
|
---|
685 | \exception InvalidRequestException thrown if \a col_idx is invalid.
|
---|
686 | */
|
---|
687 | void removeColumn(uint col_idx);
|
---|
688 |
|
---|
689 |
|
---|
690 | /*!
|
---|
691 | \brief
|
---|
692 | Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
|
---|
693 |
|
---|
694 | \param col_id
|
---|
695 | ID code of the column to be deleted.
|
---|
696 |
|
---|
697 | \return
|
---|
698 | Nothing.
|
---|
699 |
|
---|
700 | \exception InvalidRequestException thrown if no column with \a col_id is available on this list box.
|
---|
701 | */
|
---|
702 | void removeColumnWithID(uint col_id);
|
---|
703 |
|
---|
704 |
|
---|
705 | /*!
|
---|
706 | \brief
|
---|
707 | Move the column at index \a col_idx so it is at index \a position.
|
---|
708 |
|
---|
709 | \param col_idx
|
---|
710 | Zero based index of the column to be moved.
|
---|
711 |
|
---|
712 | \param position
|
---|
713 | Zero based index of the new position for the column.
|
---|
714 |
|
---|
715 | \return
|
---|
716 | Nothing.
|
---|
717 |
|
---|
718 | \exception InvalidRequestException thrown if \a col_idx is invalid.
|
---|
719 | */
|
---|
720 | void moveColumn(uint col_idx, uint position);
|
---|
721 |
|
---|
722 |
|
---|
723 | /*!
|
---|
724 | \brief
|
---|
725 | Move the column with ID \a col_id so it is at index \a position.
|
---|
726 |
|
---|
727 | \param col_id
|
---|
728 | ID code of the column to be moved.
|
---|
729 |
|
---|
730 | \param position
|
---|
731 | Zero based index of the new position for the column.
|
---|
732 |
|
---|
733 | \return
|
---|
734 | Nothing.
|
---|
735 |
|
---|
736 | \exception InvalidRequestException thrown if no column with \a col_id is available on this list box.
|
---|
737 | */
|
---|
738 | void moveColumnWithID(uint col_id, uint position);
|
---|
739 |
|
---|
740 |
|
---|
741 | /*!
|
---|
742 | \brief
|
---|
743 | Add an empty row to the list box.
|
---|
744 |
|
---|
745 | \param row_id
|
---|
746 | ID code to be assigned to the new row.
|
---|
747 |
|
---|
748 | \note
|
---|
749 | If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
|
---|
750 | applied. If no sorting is being done, the new row will appear at the bottom of the list.
|
---|
751 |
|
---|
752 | \return
|
---|
753 | Initial zero based index of the new row.
|
---|
754 | */
|
---|
755 | uint addRow(uint row_id = 0);
|
---|
756 |
|
---|
757 |
|
---|
758 | /*!
|
---|
759 | \brief
|
---|
760 | Add a row to the list box, and set the item in the column with ID \a col_id to \a item.
|
---|
761 |
|
---|
762 | \note
|
---|
763 | If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
|
---|
764 | applied. If no sorting is being done, the new row will appear at the bottom of the list.
|
---|
765 |
|
---|
766 | \param item
|
---|
767 | Pointer to a ListboxItem to be used as the initial contents for the column with ID \a col_id.
|
---|
768 |
|
---|
769 | \param col_id
|
---|
770 | ID code of the column whos initial item is to be set to \a item.
|
---|
771 |
|
---|
772 | \param row_id
|
---|
773 | ID code to be assigned to the new row.
|
---|
774 |
|
---|
775 | \return
|
---|
776 | Initial zero based index of the new row.
|
---|
777 |
|
---|
778 | \exception InvalidRequestException thrown if no column with the specified ID is attached to the list box.
|
---|
779 | */
|
---|
780 | uint addRow(ListboxItem* item, uint col_id, uint row_id = 0);
|
---|
781 |
|
---|
782 |
|
---|
783 | /*!
|
---|
784 | \brief
|
---|
785 | Insert an empty row into the list box.
|
---|
786 |
|
---|
787 | \note
|
---|
788 | If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
|
---|
789 | applied. If no sorting is being done, the new row will appear at the specified index.
|
---|
790 |
|
---|
791 | \param row_idx
|
---|
792 | Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is
|
---|
793 | appended to the list.
|
---|
794 |
|
---|
795 | \param row_id
|
---|
796 | ID code to be assigned to the new row.
|
---|
797 |
|
---|
798 | \return
|
---|
799 | Zero based index where the row was actually inserted.
|
---|
800 | */
|
---|
801 | uint insertRow(uint row_idx, uint row_id = 0);
|
---|
802 |
|
---|
803 |
|
---|
804 | /*!
|
---|
805 | \brief
|
---|
806 | Insert a row into the list box, and set the item in the column with ID \a col_id to \a item.
|
---|
807 |
|
---|
808 | \note
|
---|
809 | If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
|
---|
810 | applied. If no sorting is being done, the new row will appear at the specified index.
|
---|
811 |
|
---|
812 | \param item
|
---|
813 | Pointer to a ListboxItem to be used as the initial contents for the column with ID \a col_id.
|
---|
814 |
|
---|
815 | \param col_id
|
---|
816 | ID code of the column whos initial item is to be set to \a item.
|
---|
817 |
|
---|
818 | \param row_idx
|
---|
819 | Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is
|
---|
820 | appended to the list.
|
---|
821 |
|
---|
822 | \param row_id
|
---|
823 | ID code to be assigned to the new row.
|
---|
824 |
|
---|
825 | \return
|
---|
826 | Zero based index where the row was actually inserted.
|
---|
827 |
|
---|
828 | \exception InvalidRequestException thrown if no column with the specified ID is attached to the list box.
|
---|
829 | */
|
---|
830 | uint insertRow(ListboxItem* item, uint col_id, uint row_idx, uint row_id = 0);
|
---|
831 |
|
---|
832 |
|
---|
833 | /*!
|
---|
834 | \brief
|
---|
835 | Remove the list box row with index \a row_idx. Any ListboxItem in row \a row_idx using autoDelete mode will be deleted.
|
---|
836 |
|
---|
837 | \param row_idx
|
---|
838 | Zero based index of the row to be removed.
|
---|
839 |
|
---|
840 | \return
|
---|
841 | Nothing.
|
---|
842 |
|
---|
843 | \exception InvalidRequestException thrown if \a row_idx is invalid.
|
---|
844 | */
|
---|
845 | void removeRow(uint row_idx);
|
---|
846 |
|
---|
847 |
|
---|
848 | /*!
|
---|
849 | \brief
|
---|
850 | Set the ListboxItem for grid reference \a position.
|
---|
851 |
|
---|
852 | \param item
|
---|
853 | Pointer to the ListboxItem to be set at \a position.
|
---|
854 |
|
---|
855 | \param position
|
---|
856 | MCLGridRef describing the grid reference of the item to be set.
|
---|
857 |
|
---|
858 | \return
|
---|
859 | Nothing.
|
---|
860 |
|
---|
861 | \exception InvalidRequestException thrown if \a position contains an invalid grid reference.
|
---|
862 | */
|
---|
863 | void setItem(ListboxItem* item, const MCLGridRef& position);
|
---|
864 |
|
---|
865 |
|
---|
866 | /*!
|
---|
867 | \brief
|
---|
868 | Set the ListboxItem for the column with ID \a col_id in row \a row_idx.
|
---|
869 |
|
---|
870 | \param item
|
---|
871 | Pointer to the ListboxItem to be set into the list.
|
---|
872 |
|
---|
873 | \param col_id
|
---|
874 | ID code of the column to receive \a item.
|
---|
875 |
|
---|
876 | \param row_idx
|
---|
877 | Zero based index of the row to receive \a item.
|
---|
878 |
|
---|
879 | \return
|
---|
880 | Nothing.
|
---|
881 |
|
---|
882 | \exception InvalidRequestException thrown if no column with ID \a col_id exists, or of \a row_idx is out of range.
|
---|
883 | */
|
---|
884 | void setItem(ListboxItem* item, uint col_id, uint row_idx);
|
---|
885 |
|
---|
886 |
|
---|
887 | /*!
|
---|
888 | \brief
|
---|
889 | Set the selection mode for the list box.
|
---|
890 |
|
---|
891 | \param sel_mode
|
---|
892 | One of the MultiColumnList::SelectionMode enumerated values specifying the selection mode to be used.
|
---|
893 |
|
---|
894 | \return
|
---|
895 | Nothing.
|
---|
896 |
|
---|
897 | \exception InvalidRequestException thrown if the value specified for \a sel_mode is invalid.
|
---|
898 | */
|
---|
899 | void setSelectionMode(MultiColumnList::SelectionMode sel_mode);
|
---|
900 |
|
---|
901 |
|
---|
902 | /*!
|
---|
903 | \brief
|
---|
904 | Set the column to be used for the NominatedColumn* selection modes.
|
---|
905 |
|
---|
906 | \param col_id
|
---|
907 | ID code of the column to be used in NominatedColumn* selection modes.
|
---|
908 |
|
---|
909 | \return
|
---|
910 | Nothing.
|
---|
911 |
|
---|
912 | \exception InvalidRequestException thrown if no column has ID code \a col_id.
|
---|
913 | */
|
---|
914 | void setNominatedSelectionColumnID(uint col_id);
|
---|
915 |
|
---|
916 |
|
---|
917 | /*!
|
---|
918 | \brief
|
---|
919 | Set the column to be used for the NominatedColumn* selection modes.
|
---|
920 |
|
---|
921 | \param col_idx
|
---|
922 | zero based index of the column to be used in NominatedColumn* selection modes.
|
---|
923 |
|
---|
924 | \return
|
---|
925 | Nothing.
|
---|
926 |
|
---|
927 | \exception InvalidRequestException thrown if \a col_idx is out of range.
|
---|
928 | */
|
---|
929 | void setNominatedSelectionColumn(uint col_idx);
|
---|
930 |
|
---|
931 |
|
---|
932 | /*!
|
---|
933 | \brief
|
---|
934 | Set the row to be used for the NominatedRow* selection modes.
|
---|
935 |
|
---|
936 | \param row_idx
|
---|
937 | zero based index of the row to be used in NominatedRow* selection modes.
|
---|
938 |
|
---|
939 | \return
|
---|
940 | Nothing.
|
---|
941 |
|
---|
942 | \exception InvalidRequestException thrown if \a row_idx is out of range.
|
---|
943 | */
|
---|
944 | void setNominatedSelectionRow(uint row_idx);
|
---|
945 |
|
---|
946 |
|
---|
947 | /*!
|
---|
948 | \brief
|
---|
949 | Set the sort direction to be used.
|
---|
950 |
|
---|
951 | \param direction
|
---|
952 | One of the ListHeaderSegment::SortDirection enumerated values specifying the sort direction to be used.
|
---|
953 |
|
---|
954 | \return
|
---|
955 | Nothing.
|
---|
956 | */
|
---|
957 | void setSortDirection(ListHeaderSegment::SortDirection direction);
|
---|
958 |
|
---|
959 |
|
---|
960 | /*!
|
---|
961 | \brief
|
---|
962 | Set the column to be used as the sort key.
|
---|
963 |
|
---|
964 | \param col_idx
|
---|
965 | Zero based index of the column to use as the key when sorting the list items.
|
---|
966 |
|
---|
967 | \return
|
---|
968 | Nothing.
|
---|
969 |
|
---|
970 | \exception InvalidRequestException thrown if col_idx is out of range.
|
---|
971 | */
|
---|
972 | void setSortColumn(uint col_idx);
|
---|
973 |
|
---|
974 |
|
---|
975 | /*!
|
---|
976 | \brief
|
---|
977 | Set the column to be used as the sort key.
|
---|
978 |
|
---|
979 | \param col_id
|
---|
980 | ID code of the column to use as the key when sorting the list items.
|
---|
981 |
|
---|
982 | \return
|
---|
983 | Nothing.
|
---|
984 |
|
---|
985 | \exception InvalidRequestException thrown if col_id is invalid for this list box.
|
---|
986 | */
|
---|
987 | void setSortColumnByID(uint col_id);
|
---|
988 |
|
---|
989 |
|
---|
990 | /*!
|
---|
991 | \brief
|
---|
992 | Set whether the vertical scroll bar should always be shown, or just when needed.
|
---|
993 |
|
---|
994 | \param setting
|
---|
995 | - true to have the vertical scroll bar shown at all times.
|
---|
996 | - false to have the vertical scroll bar appear only when needed.
|
---|
997 |
|
---|
998 | \return
|
---|
999 | Nothing.
|
---|
1000 | */
|
---|
1001 | void setShowVertScrollbar(bool setting);
|
---|
1002 |
|
---|
1003 |
|
---|
1004 | /*!
|
---|
1005 | \brief
|
---|
1006 | Set whether the horizontal scroll bar should always be shown, or just when needed.
|
---|
1007 |
|
---|
1008 | \param setting
|
---|
1009 | - true to have the horizontal scroll bar shown at all times.
|
---|
1010 | - false to have the horizontal scroll bar appear only when needed.
|
---|
1011 |
|
---|
1012 | \return
|
---|
1013 | Nothing.
|
---|
1014 | */
|
---|
1015 | void setShowHorzScrollbar(bool setting);
|
---|
1016 |
|
---|
1017 |
|
---|
1018 | /*!
|
---|
1019 | \brief
|
---|
1020 | Removed the selected state from any currently selected ListboxItem attached to the list.
|
---|
1021 |
|
---|
1022 | \return
|
---|
1023 | Nothing.
|
---|
1024 | */
|
---|
1025 | void clearAllSelections(void);
|
---|
1026 |
|
---|
1027 |
|
---|
1028 | /*!
|
---|
1029 | \brief
|
---|
1030 | Sets or clears the selected state of the given ListboxItem which must be attached to the list.
|
---|
1031 |
|
---|
1032 | \note
|
---|
1033 | Depending upon the current selection mode, this may cause other items to be selected, other
|
---|
1034 | items to be deselected, or for nothing to actually happen at all.
|
---|
1035 |
|
---|
1036 | \param item
|
---|
1037 | Pointer to the attached ListboxItem to be affected.
|
---|
1038 |
|
---|
1039 | \param state
|
---|
1040 | - true to put the ListboxItem into the selected state.
|
---|
1041 | - false to put the ListboxItem into the de-selected state.
|
---|
1042 |
|
---|
1043 | \return
|
---|
1044 | Nothing.
|
---|
1045 |
|
---|
1046 | \exception InvalidRequestException thrown if \a item is not attached to the list box.
|
---|
1047 | */
|
---|
1048 | void setItemSelectState(ListboxItem* item, bool state);
|
---|
1049 |
|
---|
1050 |
|
---|
1051 | /*!
|
---|
1052 | \brief
|
---|
1053 | Sets or clears the selected state of the ListboxItem at the given grid reference.
|
---|
1054 |
|
---|
1055 | \note
|
---|
1056 | Depending upon the current selection mode, this may cause other items to be selected, other
|
---|
1057 | items to be deselected, or for nothing to actually happen at all.
|
---|
1058 |
|
---|
1059 | \param grid_ref
|
---|
1060 | MCLGridRef object describing the position of the item to be affected.
|
---|
1061 |
|
---|
1062 | \param state
|
---|
1063 | - true to put the ListboxItem into the selected state.
|
---|
1064 | - false to put the ListboxItem into the de-selected state.
|
---|
1065 |
|
---|
1066 | \return
|
---|
1067 | Nothing.
|
---|
1068 |
|
---|
1069 | \exception InvalidRequestException thrown if \a grid_ref is invalid for this list box.
|
---|
1070 | */
|
---|
1071 | void setItemSelectState(const MCLGridRef& grid_ref, bool state);
|
---|
1072 |
|
---|
1073 |
|
---|
1074 | /*!
|
---|
1075 | \brief
|
---|
1076 | Inform the list box that one or more attached ListboxItems have been externally modified, and
|
---|
1077 | the list should re-sync its internal state and refresh the display as needed.
|
---|
1078 |
|
---|
1079 | \return
|
---|
1080 | Nothing.
|
---|
1081 | */
|
---|
1082 | void handleUpdatedItemData(void);
|
---|
1083 |
|
---|
1084 |
|
---|
1085 | /*!
|
---|
1086 | \brief
|
---|
1087 | Set the width of the specified column header (and therefore the column itself).
|
---|
1088 |
|
---|
1089 | \param col_idx
|
---|
1090 | Zero based column index of the column whos width is to be set.
|
---|
1091 |
|
---|
1092 | \param width
|
---|
1093 | float value specifying the new width for the column using the active metrics system.
|
---|
1094 |
|
---|
1095 | \return
|
---|
1096 | Nothing.
|
---|
1097 |
|
---|
1098 | \exception InvalidRequestException thrown if \a column is out of range.
|
---|
1099 | */
|
---|
1100 | void setColumnHeaderWidth(uint col_idx, float width);
|
---|
1101 |
|
---|
1102 |
|
---|
1103 | /*!
|
---|
1104 | \brief
|
---|
1105 | Set whether user manipulation of the sort column and direction are enabled.
|
---|
1106 |
|
---|
1107 | \param setting
|
---|
1108 | - true if the user may interactively modify the sort column and direction.
|
---|
1109 | - false if the user may not modify the sort column and direction (these can still be set programmatically).
|
---|
1110 |
|
---|
1111 | \return
|
---|
1112 | Nothing.
|
---|
1113 | */
|
---|
1114 | void setUserSortControlEnabled(bool setting);
|
---|
1115 |
|
---|
1116 |
|
---|
1117 | /*!
|
---|
1118 | \brief
|
---|
1119 | Set whether the user may size column segments.
|
---|
1120 |
|
---|
1121 | \param setting
|
---|
1122 | - true if the user may interactively modify the width of columns.
|
---|
1123 | - false if the user may not change the width of the columns.
|
---|
1124 |
|
---|
1125 | \return
|
---|
1126 | Nothing.
|
---|
1127 | */
|
---|
1128 | void setUserColumnSizingEnabled(bool setting);
|
---|
1129 |
|
---|
1130 |
|
---|
1131 | /*!
|
---|
1132 | \brief
|
---|
1133 | Set whether the user may modify the order of the columns.
|
---|
1134 |
|
---|
1135 | \param setting
|
---|
1136 | - true if the user may interactively modify the order of the columns.
|
---|
1137 | - false if the user may not modify the order of the columns.
|
---|
1138 | */
|
---|
1139 | void setUserColumnDraggingEnabled(bool setting);
|
---|
1140 |
|
---|
1141 |
|
---|
1142 | /*!
|
---|
1143 | \brief
|
---|
1144 | Automatically determines the "best fit" size for the specified column and sets
|
---|
1145 | the column width to the same.
|
---|
1146 |
|
---|
1147 | \param col_idx
|
---|
1148 | Zero based index of the column to be sized.
|
---|
1149 |
|
---|
1150 | \return
|
---|
1151 | Nothing.
|
---|
1152 |
|
---|
1153 | \exception InvalidRequestException thrown if \a col_idx is out of range.
|
---|
1154 | */
|
---|
1155 | void autoSizeColumnHeader(uint col_idx);
|
---|
1156 |
|
---|
1157 |
|
---|
1158 | /*!
|
---|
1159 | \brief
|
---|
1160 | Set the ID code assigned to a given row.
|
---|
1161 |
|
---|
1162 | \param row_idx
|
---|
1163 | Zero based index of the row who's ID code is to be set.
|
---|
1164 |
|
---|
1165 | \param row_id
|
---|
1166 | ID code to be assigned to the row at the requested index.
|
---|
1167 |
|
---|
1168 | \return
|
---|
1169 | Nothing.
|
---|
1170 |
|
---|
1171 | \exception InvalidRequestException thrown if \a row_idx is out of range
|
---|
1172 | */
|
---|
1173 | void setRowID(uint row_idx, uint row_id);
|
---|
1174 |
|
---|
1175 |
|
---|
1176 | /*************************************************************************
|
---|
1177 | Construction and Destruction
|
---|
1178 | *************************************************************************/
|
---|
1179 | /*!
|
---|
1180 | \brief
|
---|
1181 | Constructor for the Multi-column list base class
|
---|
1182 | */
|
---|
1183 | MultiColumnList(const String& type, const String& name);
|
---|
1184 |
|
---|
1185 |
|
---|
1186 | /*!
|
---|
1187 | \brief
|
---|
1188 | Destructor for the multi-column list base class.
|
---|
1189 | */
|
---|
1190 | virtual ~MultiColumnList(void);
|
---|
1191 |
|
---|
1192 |
|
---|
1193 | protected:
|
---|
1194 | /*************************************************************************
|
---|
1195 | Implementation Functions (abstract interface)
|
---|
1196 | *************************************************************************/
|
---|
1197 | /*!
|
---|
1198 | \brief
|
---|
1199 | Return a Rect object describing, in un-clipped pixels, the window relative area
|
---|
1200 | that is to be used for rendering list items.
|
---|
1201 |
|
---|
1202 | \return
|
---|
1203 | Rect object describing the area of the Window to be used for rendering
|
---|
1204 | list box items.
|
---|
1205 | */
|
---|
1206 | virtual Rect getListRenderArea(void) const = 0;
|
---|
1207 |
|
---|
1208 |
|
---|
1209 | /*!
|
---|
1210 | \brief
|
---|
1211 | create and return a pointer to a ListHeaer widget for use as the column headers.
|
---|
1212 |
|
---|
1213 | \param name
|
---|
1214 | String holding the name to be assigned to the created component.
|
---|
1215 |
|
---|
1216 | \return
|
---|
1217 | Pointer to a ListHeader based object.
|
---|
1218 | */
|
---|
1219 | virtual ListHeader* createListHeader(const String& name) const = 0;
|
---|
1220 |
|
---|
1221 |
|
---|
1222 | /*!
|
---|
1223 | \brief
|
---|
1224 | create and return a pointer to a Scrollbar widget for use as vertical scroll bar
|
---|
1225 |
|
---|
1226 | \param name
|
---|
1227 | String holding the name to be assigned to the created component.
|
---|
1228 |
|
---|
1229 | \return
|
---|
1230 | Pointer to a Scrollbar to be used for scrolling the list vertically.
|
---|
1231 | */
|
---|
1232 | virtual Scrollbar* createVertScrollbar(const String& name) const = 0;
|
---|
1233 |
|
---|
1234 |
|
---|
1235 | /*!
|
---|
1236 | \brief
|
---|
1237 | create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
|
---|
1238 |
|
---|
1239 | \param name
|
---|
1240 | String holding the name to be assigned to the created component.
|
---|
1241 |
|
---|
1242 | \return
|
---|
1243 | Pointer to a Scrollbar to be used for scrolling the list horizontally.
|
---|
1244 | */
|
---|
1245 | virtual Scrollbar* createHorzScrollbar(const String& name) const = 0;
|
---|
1246 |
|
---|
1247 |
|
---|
1248 | /*!
|
---|
1249 | \brief
|
---|
1250 | Perform rendering of the widget control frame and other 'static' areas. This
|
---|
1251 | method should not render the actual items. Note that the items are typically
|
---|
1252 | rendered to layer 3, other layers can be used for rendering imagery behind and
|
---|
1253 | infront of the items.
|
---|
1254 |
|
---|
1255 | \return
|
---|
1256 | Nothing.
|
---|
1257 | */
|
---|
1258 | virtual void cacheListboxBaseImagery() = 0;
|
---|
1259 |
|
---|
1260 |
|
---|
1261 | /*************************************************************************
|
---|
1262 | Implementation Functions
|
---|
1263 | *************************************************************************/
|
---|
1264 | /*!
|
---|
1265 | \brief
|
---|
1266 | Add multi column list box specific events
|
---|
1267 | */
|
---|
1268 | void addMultiColumnListboxEvents(void);
|
---|
1269 |
|
---|
1270 | // overridden from base class.
|
---|
1271 | virtual void populateRenderCache();
|
---|
1272 |
|
---|
1273 |
|
---|
1274 | /*!
|
---|
1275 | \brief
|
---|
1276 | display required integrated scroll bars according to current state of the list box and update their values.
|
---|
1277 | */
|
---|
1278 | void configureScrollbars(void);
|
---|
1279 |
|
---|
1280 |
|
---|
1281 | /*!
|
---|
1282 | \brief
|
---|
1283 | select all strings between positions \a start and \a end. (inclusive). Returns true if something was modified.
|
---|
1284 | */
|
---|
1285 | bool selectRange(const MCLGridRef& start, const MCLGridRef& end);
|
---|
1286 |
|
---|
1287 |
|
---|
1288 | /*!
|
---|
1289 | \brief
|
---|
1290 | Return the sum of all row heights
|
---|
1291 | */
|
---|
1292 | float getTotalRowsHeight(void) const;
|
---|
1293 |
|
---|
1294 |
|
---|
1295 | /*!
|
---|
1296 | \brief
|
---|
1297 | Return the width of the widest item in the given column
|
---|
1298 | */
|
---|
1299 | float getWidestColumnItemWidth(uint col_idx) const;
|
---|
1300 |
|
---|
1301 |
|
---|
1302 | /*!
|
---|
1303 | \brief
|
---|
1304 | Return the height of the highest item in the given row.
|
---|
1305 | */
|
---|
1306 | float getHighestRowItemHeight(uint row_idx) const;
|
---|
1307 |
|
---|
1308 |
|
---|
1309 | /*!
|
---|
1310 | \brief
|
---|
1311 | Clear the selected state for all items (implementation)
|
---|
1312 |
|
---|
1313 | \return
|
---|
1314 | true if some selections were cleared, false nothing was changed.
|
---|
1315 | */
|
---|
1316 | bool clearAllSelections_impl(void);
|
---|
1317 |
|
---|
1318 |
|
---|
1319 | /*!
|
---|
1320 | \brief
|
---|
1321 | Return the ListboxItem under the given window local pixel co-ordinate.
|
---|
1322 |
|
---|
1323 | \return
|
---|
1324 | ListboxItem that is under window pixel co-ordinate \a pt, or NULL if no
|
---|
1325 | item is under that position.
|
---|
1326 | */
|
---|
1327 | ListboxItem* getItemAtPoint(const Point& pt) const;
|
---|
1328 |
|
---|
1329 |
|
---|
1330 | /*!
|
---|
1331 | \brief
|
---|
1332 | Set select state for the given item. This appropriately selects other
|
---|
1333 | items depending upon the select mode. Returns true if something is
|
---|
1334 | changed, else false.
|
---|
1335 | */
|
---|
1336 | bool setItemSelectState_impl(const MCLGridRef grid_ref, bool state);
|
---|
1337 |
|
---|
1338 |
|
---|
1339 | /*!
|
---|
1340 | \brief
|
---|
1341 | Set select state for all items in the given row
|
---|
1342 | */
|
---|
1343 | void setSelectForItemsInRow(uint row_idx, bool state);
|
---|
1344 |
|
---|
1345 |
|
---|
1346 | /*!
|
---|
1347 | \brief
|
---|
1348 | Set select state for all items in the given column
|
---|
1349 | */
|
---|
1350 | void setSelectForItemsInColumn(uint col_idx, bool state);
|
---|
1351 |
|
---|
1352 |
|
---|
1353 | /*!
|
---|
1354 | \brief
|
---|
1355 | Move the column at index \a col_idx so it is at index \a position. Implementation version which does not move the
|
---|
1356 | header segment (since that may have already happened).
|
---|
1357 |
|
---|
1358 | \exception InvalidRequestException thrown if \a col_idx is invalid.
|
---|
1359 | */
|
---|
1360 | void moveColumn_impl(uint col_idx, uint position);
|
---|
1361 |
|
---|
1362 |
|
---|
1363 | /*!
|
---|
1364 | \brief
|
---|
1365 | Remove all items from the list.
|
---|
1366 |
|
---|
1367 | \note
|
---|
1368 | Note that this will cause 'AutoDelete' items to be deleted.
|
---|
1369 |
|
---|
1370 | \return
|
---|
1371 | - true if the list contents were changed.
|
---|
1372 | - false if the list contents were not changed (list already empty).
|
---|
1373 | */
|
---|
1374 | bool resetList_impl(void);
|
---|
1375 |
|
---|
1376 |
|
---|
1377 | /*!
|
---|
1378 | \brief
|
---|
1379 | Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
|
---|
1380 |
|
---|
1381 | \param class_name
|
---|
1382 | The class name that is to be checked.
|
---|
1383 |
|
---|
1384 | \return
|
---|
1385 | true if this window was inherited from \a class_name. false if not.
|
---|
1386 | */
|
---|
1387 | virtual bool testClassName_impl(const String& class_name) const
|
---|
1388 | {
|
---|
1389 | if (class_name==(const utf8*)"MultiColumnList") return true;
|
---|
1390 | return Window::testClassName_impl(class_name);
|
---|
1391 | }
|
---|
1392 |
|
---|
1393 | // overrides function in base class.
|
---|
1394 | int writePropertiesXML(OutStream& out_stream) const;
|
---|
1395 |
|
---|
1396 | /*************************************************************************
|
---|
1397 | New event handlers for multi column list
|
---|
1398 | *************************************************************************/
|
---|
1399 | /*!
|
---|
1400 | \brief
|
---|
1401 | Handler called when the selection mode of the list box changes
|
---|
1402 | */
|
---|
1403 | virtual void onSelectionModeChanged(WindowEventArgs& e);
|
---|
1404 |
|
---|
1405 |
|
---|
1406 | /*!
|
---|
1407 | \brief
|
---|
1408 | Handler called when the nominated selection column changes
|
---|
1409 | */
|
---|
1410 | virtual void onNominatedSelectColumnChanged(WindowEventArgs& e);
|
---|
1411 |
|
---|
1412 |
|
---|
1413 | /*!
|
---|
1414 | \brief
|
---|
1415 | Handler called when the nominated selection row changes.
|
---|
1416 | */
|
---|
1417 | virtual void onNominatedSelectRowChanged(WindowEventArgs& e);
|
---|
1418 |
|
---|
1419 |
|
---|
1420 | /*!
|
---|
1421 | \brief
|
---|
1422 | Handler called when the vertical scroll bar 'force' mode is changed.
|
---|
1423 | */
|
---|
1424 | virtual void onVertScrollbarModeChanged(WindowEventArgs& e);
|
---|
1425 |
|
---|
1426 |
|
---|
1427 | /*!
|
---|
1428 | \brief
|
---|
1429 | Handler called when the horizontal scroll bar 'force' mode is changed.
|
---|
1430 | */
|
---|
1431 | virtual void onHorzScrollbarModeChanged(WindowEventArgs& e);
|
---|
1432 |
|
---|
1433 |
|
---|
1434 | /*!
|
---|
1435 | \brief
|
---|
1436 | Handler called when the current selection changes.
|
---|
1437 | */
|
---|
1438 | virtual void onSelectionChanged(WindowEventArgs& e);
|
---|
1439 |
|
---|
1440 |
|
---|
1441 | /*!
|
---|
1442 | \brief
|
---|
1443 | Handler called when the list contents is changed.
|
---|
1444 | */
|
---|
1445 | virtual void onListContentsChanged(WindowEventArgs& e);
|
---|
1446 |
|
---|
1447 |
|
---|
1448 | /*!
|
---|
1449 | \brief
|
---|
1450 | Handler called when the sort column changes.
|
---|
1451 | */
|
---|
1452 | virtual void onSortColumnChanged(WindowEventArgs& e);
|
---|
1453 |
|
---|
1454 |
|
---|
1455 | /*!
|
---|
1456 | \brief
|
---|
1457 | Handler called when the sort direction changes.
|
---|
1458 | */
|
---|
1459 | virtual void onSortDirectionChanged(WindowEventArgs& e);
|
---|
1460 |
|
---|
1461 |
|
---|
1462 | /*!
|
---|
1463 | \brief
|
---|
1464 | Handler called when a column is sized.
|
---|
1465 | */
|
---|
1466 | virtual void onListColumnSized(WindowEventArgs& e);
|
---|
1467 |
|
---|
1468 |
|
---|
1469 | /*!
|
---|
1470 | \brief
|
---|
1471 | Handler called when the column order is changed.
|
---|
1472 | */
|
---|
1473 | virtual void onListColumnMoved(WindowEventArgs& e);
|
---|
1474 |
|
---|
1475 |
|
---|
1476 | /*************************************************************************
|
---|
1477 | Overridden Event handlers
|
---|
1478 | *************************************************************************/
|
---|
1479 | virtual void onSized(WindowEventArgs& e);
|
---|
1480 | virtual void onMouseButtonDown(MouseEventArgs& e);
|
---|
1481 | virtual void onMouseWheel(MouseEventArgs& e);
|
---|
1482 |
|
---|
1483 |
|
---|
1484 | /*************************************************************************
|
---|
1485 | Handlers for subscribed events
|
---|
1486 | *************************************************************************/
|
---|
1487 | bool handleHeaderScroll(const EventArgs& e);
|
---|
1488 | bool handleHeaderSegMove(const EventArgs& e);
|
---|
1489 | bool handleColumnSizeChange(const EventArgs& e);
|
---|
1490 | bool handleHorzScrollbar(const EventArgs& e);
|
---|
1491 | bool handleVertScrollbar(const EventArgs& e);
|
---|
1492 | bool handleSortColumnChange(const EventArgs& e);
|
---|
1493 | bool handleSortDirectionChange(const EventArgs& e);
|
---|
1494 | bool handleHeaderSegDblClick(const EventArgs& e);
|
---|
1495 |
|
---|
1496 | /*!
|
---|
1497 | \brief
|
---|
1498 | Struct used internally to represent a row in the list and also to ease
|
---|
1499 | sorting of the rows.
|
---|
1500 | */
|
---|
1501 | struct ListRow
|
---|
1502 | {
|
---|
1503 | typedef std::vector<ListboxItem*> RowItems;
|
---|
1504 | RowItems d_items;
|
---|
1505 | uint d_sortColumn;
|
---|
1506 | uint d_rowID;
|
---|
1507 |
|
---|
1508 | // operators
|
---|
1509 | ListboxItem* const& operator[](uint idx) const {return d_items[idx];}
|
---|
1510 | ListboxItem*& operator[](uint idx) {return d_items[idx];}
|
---|
1511 | bool operator<(const ListRow& rhs) const;
|
---|
1512 | bool operator>(const ListRow& rhs) const;
|
---|
1513 | };
|
---|
1514 |
|
---|
1515 |
|
---|
1516 | /*!
|
---|
1517 | \brief
|
---|
1518 | std algorithm predicate used for sorting in descending order
|
---|
1519 | */
|
---|
1520 | static bool pred_descend(const ListRow& a, const ListRow& b);
|
---|
1521 |
|
---|
1522 |
|
---|
1523 | /*************************************************************************
|
---|
1524 | Implementation Data
|
---|
1525 | *************************************************************************/
|
---|
1526 | // component widgets and settings.
|
---|
1527 | Scrollbar* d_vertScrollbar; //!< vertical scroll-bar widget
|
---|
1528 | Scrollbar* d_horzScrollbar; //!< horizontal scroll-bar widget
|
---|
1529 | ListHeader* d_header; //!< The ListHeader attached to this multi-column list.
|
---|
1530 | bool d_forceVertScroll; //!< true if vertical scrollbar should always be displayed
|
---|
1531 | bool d_forceHorzScroll; //!< true if horizontal scrollbar should always be displayed
|
---|
1532 |
|
---|
1533 | // selection abilities.
|
---|
1534 | SelectionMode d_selectMode; //!< Holds selection mode (represented by settings below).
|
---|
1535 | uint d_nominatedSelectCol; //!< Nominated column for single column selection.
|
---|
1536 | uint d_nominatedSelectRow; //!< Nominated row for single row selection.
|
---|
1537 | bool d_multiSelect; //!< Allow multiple selections.
|
---|
1538 | bool d_fullRowSelect; //!< All items in a row are selected.
|
---|
1539 | bool d_fullColSelect; //!< All items in a column are selected.
|
---|
1540 | bool d_useNominatedRow; //!< true if we use a nominated row to select.
|
---|
1541 | bool d_useNominatedCol; //!< true if we use a nominated col to select.
|
---|
1542 | ListboxItem* d_lastSelected; //!< holds pointer to the last selected item (used in range selections)
|
---|
1543 |
|
---|
1544 | // storage of items in the list box.
|
---|
1545 | typedef std::vector<ListRow> ListItemGrid;
|
---|
1546 | ListItemGrid d_grid; //!< Holds the list box data.
|
---|
1547 |
|
---|
1548 |
|
---|
1549 | private:
|
---|
1550 | /*************************************************************************
|
---|
1551 | Static Properties for this class
|
---|
1552 | *************************************************************************/
|
---|
1553 | static MultiColumnListProperties::ColumnsMovable d_columnsMovableProperty;
|
---|
1554 | static MultiColumnListProperties::ColumnsSizable d_columnsSizableProperty;
|
---|
1555 | static MultiColumnListProperties::ForceHorzScrollbar d_forceHorzScrollProperty;
|
---|
1556 | static MultiColumnListProperties::ForceVertScrollbar d_forceVertScrollProperty;
|
---|
1557 | static MultiColumnListProperties::NominatedSelectionColumnID d_nominatedSelectColProperty;
|
---|
1558 | static MultiColumnListProperties::NominatedSelectionRow d_nominatedSelectRowProperty;
|
---|
1559 | static MultiColumnListProperties::SelectionMode d_selectModeProperty;
|
---|
1560 | static MultiColumnListProperties::SortColumnID d_sortColumnIDProperty;
|
---|
1561 | static MultiColumnListProperties::SortDirection d_sortDirectionProperty;
|
---|
1562 | static MultiColumnListProperties::SortSettingEnabled d_sortSettingProperty;
|
---|
1563 | static MultiColumnListProperties::ColumnHeader d_columnHeaderProperty;
|
---|
1564 | static MultiColumnListProperties::RowCount d_rowCountProperty;
|
---|
1565 |
|
---|
1566 |
|
---|
1567 | /*************************************************************************
|
---|
1568 | Private methods
|
---|
1569 | *************************************************************************/
|
---|
1570 | void addMultiColumnListProperties(void);
|
---|
1571 | };
|
---|
1572 |
|
---|
1573 | } // End of CEGUI namespace section
|
---|
1574 |
|
---|
1575 | #if defined(_MSC_VER)
|
---|
1576 | # pragma warning(pop)
|
---|
1577 | #endif
|
---|
1578 |
|
---|
1579 | #endif // end of guard _CEGUIMultiColumnList_h_
|
---|