# CEGUIMultiColumnList.h

    00001 /************************************************************************
    00002         filename:       CEGUIMultiColumnList.h
    00003         created:        13/4/2004
    00004         author:         Paul D Turner
    00005
    00006         purpose:        Interface to base class for MultiColumnList widget
    00007 *************************************************************************/
    00008 /*************************************************************************
    00009     Crazy Eddie's GUI System (http://www.cegui.org.uk)
    00010     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
    00011
    00012     This library is free software; you can redistribute it and/or
    00013     modify it under the terms of the GNU Lesser General Public
    00014     License as published by the Free Software Foundation; either
    00015     version 2.1 of the License, or (at your option) any later version.
    00016
    00017     This library is distributed in the hope that it will be useful,
    00018     but WITHOUT ANY WARRANTY; without even the implied warranty of
    00019     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00020     Lesser General Public License for more details.
    00021
    00022     You should have received a copy of the GNU Lesser General Public
    00023     License along with this library; if not, write to the Free Software
    00024     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    00025 *************************************************************************/
    00026 #ifndef _CEGUIMultiColumnList_h_
    00027 #define _CEGUIMultiColumnList_h_
    00028
    00029 #include "CEGUIBase.h"
    00030 #include "CEGUIWindow.h"
    00031 #include "CEGUIListHeader.h"
    00032 #include "elements/CEGUIMultiColumnListProperties.h"
    00033
    00034
    00035 #if defined(_MSC_VER)
    00036 #       pragma warning(push)
    00037 #       pragma warning(disable : 4251)
    00038 #endif
    00039
    00040
    00041 // Start of CEGUI namespace section
    00042 namespace CEGUI
    00043 {
    00044
    00049 struct CEGUIEXPORT MCLGridRef
    00050 {
    00051         MCLGridRef(uint r, uint c) : row(r), column(c) {}
    00052
    00053         uint    row;
    00054         uint    column;
    00055
    00056         // operators
    00057         MCLGridRef& operator=(const MCLGridRef& rhs);
    00058         bool operator<(const MCLGridRef& rhs) const;
    00059         bool operator<=(const MCLGridRef& rhs) const;
    00060         bool operator>(const MCLGridRef& rhs) const;
    00061         bool operator>=(const MCLGridRef& rhs) const;
    00062         bool operator==(const MCLGridRef& rhs) const;
    00063         bool operator!=(const MCLGridRef& rhs) const;
    00064 };
    00065
    00066
    00071 class CEGUIEXPORT MultiColumnList : public Window
    00072 {
    00073 public:
    00074         static const String EventNamespace;
    00075
    00076
    00077         /*************************************************************************
    00078                 Constants
    00079         *************************************************************************/
    00080         // Event names
    00081         static const String EventSelectionModeChanged;
    00082         static const String EventNominatedSelectColumnChanged;
    00083         static const String EventNominatedSelectRowChanged;
    00084         static const String EventVertScrollbarModeChanged;
    00085         static const String EventHorzScrollbarModeChanged;
    00086         static const String EventSelectionChanged;
    00087         static const String EventListContentsChanged;
    00088         static const String EventSortColumnChanged;
    00089         static const String EventSortDirectionChanged;
    00090         static const String EventListColumnSized;
    00091         static const String EventListColumnMoved;
    00092
    00093
    00094         /*************************************************************************
    00095                 Enumerations
    00096         *************************************************************************/
    00101         enum SelectionMode
    00102         {
    00103                 RowSingle,                                      // Any single row may be selected.  All items in the row are selected.
    00104                 RowMultiple,                            // Multiple rows may be selected.  All items in the row are selected.
    00105                 CellSingle,                                     // Any single cell may be selected.
    00106                 CellMultiple,                           // Multiple cells bay be selected.
    00107                 NominatedColumnSingle,          // Any single item in a nominated column may be selected.
    00108                 NominatedColumnMultiple,        // Multiple items in a nominated column may be selected.
    00109                 ColumnSingle,                           // Any single column may be selected.  All items in the column are selected.
    00110                 ColumnMultiple,                         // Multiple columns may be selected.  All items in the column are selected.
    00111                 NominatedRowSingle,                     // Any single item in a nominated row may be selected.
    00112                 NominatedRowMultiple            // Multiple items in a nominated row may be selected.
    00113         };
    00114
    00115
    00116         /*************************************************************************
    00117                 Accessor Methods
    00118         *************************************************************************/
    00127         bool    isUserSortControlEnabled(void) const;
    00128
    00129
    00137         bool    isUserColumnSizingEnabled(void) const;
    00138
    00139
    00147         bool    isUserColumnDraggingEnabled(void) const;
    00148
    00149
    00157         uint    getColumnCount(void) const;
    00158
    00159
    00167         uint    getRowCount(void) const;
    00168
    00169
    00180         uint    getSortColumn(void) const;
    00181
    00182
    00195         uint    getColumnWithID(uint col_id) const;
    00196
    00197
    00210         uint    getColumnWithHeaderText(const String& text) const;
    00211
    00212
    00220         float   getTotalColumnHeadersWidth(void) const;
    00221
    00222
    00235         float   getColumnHeaderWidth(uint col_idx) const;
    00236
    00237
    00245         ListHeaderSegment::SortDirection        getSortDirection(void) const;
    00246
    00247
    00260         ListHeaderSegment&      getHeaderSegmentForColumn(uint col_idx) const;
    00261
    00262
    00275         uint    getItemRowIndex(const ListboxItem* item) const;
    00276
    00277
    00290         uint    getItemColumnIndex(const ListboxItem* item) const;
    00291
    00292
    00305         MCLGridRef      getItemGridReference(const ListboxItem* item) const;
    00306
    00307
    00320         ListboxItem*    getItemAtGridReference(const MCLGridRef& grid_ref) const;
    00321
    00322
    00339         bool    isListboxItemInColumn(const ListboxItem* item, uint col_idx) const;
    00340
    00341
    00358         bool    isListboxItemInRow(const ListboxItem* item, uint row_idx) const;
    00359
    00360
    00372         bool    isListboxItemInList(const ListboxItem* item) const;
    00373
    00374
    00393         ListboxItem*    findColumnItemWithText(const String& text, uint col_idx, const ListboxItem* start_item) const;
    00394
    00395
    00414         ListboxItem*    findRowItemWithText(const String& text, uint row_idx, const ListboxItem* start_item) const;
    00415
    00416
    00435         ListboxItem*    findListItemWithText(const String& text, const ListboxItem* start_item) const;
    00436
    00437
    00448         ListboxItem*    getFirstSelectedItem(void) const;
    00449
    00450
    00466         ListboxItem*    getNextSelected(const ListboxItem* start_item) const;
    00467
    00468
    00476         uint    getSelectedCount(void) const;
    00477
    00478
    00492         bool    isItemSelected(const MCLGridRef& grid_ref) const;
    00493
    00494
    00506         uint    getNominatedSelectionColumnID(void) const;
    00507
    00508
    00517         uint    getNominatedSelectionColumn(void) const;
    00518
    00519
    00528         uint    getNominatedSelectionRow(void) const;
    00529
    00530
    00538         MultiColumnList::SelectionMode  getSelectionMode(void) const;
    00539
    00540
    00549         bool    isVertScrollbarAlwaysShown(void) const;
    00550
    00551
    00560         bool    isHorzScrollbarAlwaysShown(void) const;
    00561
    00562
    00575         uint    getColumnID(uint col_idx) const;
    00576
    00577
    00590         uint    getRowID(uint row_idx) const;
    00591
    00592
    00605         uint    getRowWithID(uint row_id) const;
    00606
    00607
    00608         /*************************************************************************
    00609                 Manipulator Methods
    00610         *************************************************************************/
    00621         virtual void    initialise(void);
    00622
    00623
    00630         void    resetList(void);
    00631
    00632
    00649         void    addColumn(const String& text, uint col_id, float width);
    00650
    00651
    00672         void    insertColumn(const String& text, uint col_id, float width, uint position);
    00673
    00674
    00687         void    removeColumn(uint col_idx);
    00688
    00689
    00702         void    removeColumnWithID(uint col_id);
    00703
    00704
    00720         void    moveColumn(uint col_idx, uint position);
    00721
    00722
    00738         void    moveColumnWithID(uint col_id, uint position);
    00739
    00740
    00755         uint    addRow(uint row_id = 0);
    00756
    00757
    00780         uint    addRow(ListboxItem* item, uint col_id, uint row_id = 0);
    00781
    00782
    00801         uint    insertRow(uint row_idx, uint row_id = 0);
    00802
    00803
    00830         uint    insertRow(ListboxItem* item, uint col_id, uint row_idx, uint row_id = 0);
    00831
    00832
    00845         void    removeRow(uint row_idx);
    00846
    00847
    00863         void    setItem(ListboxItem* item, const MCLGridRef& position);
    00864
    00865
    00884         void    setItem(ListboxItem* item, uint col_id, uint row_idx);
    00885
    00886
    00899         void    setSelectionMode(MultiColumnList::SelectionMode sel_mode);
    00900
    00901
    00914         void    setNominatedSelectionColumnID(uint col_id);
    00915
    00916
    00929         void    setNominatedSelectionColumn(uint col_idx);
    00930
    00931
    00944         void    setNominatedSelectionRow(uint row_idx);
    00945
    00946
    00957         void    setSortDirection(ListHeaderSegment::SortDirection direction);
    00958
    00959
    00972         void    setSortColumn(uint col_idx);
    00973
    00974
    00987         void    setSortColumnByID(uint col_id);
    00988
    00989
    01001         void    setShowVertScrollbar(bool setting);
    01002
    01003
    01015         void    setShowHorzScrollbar(bool setting);
    01016
    01017
    01025         void    clearAllSelections(void);
    01026
    01027
    01048         void    setItemSelectState(ListboxItem* item, bool state);
    01049
    01050
    01071         void    setItemSelectState(const MCLGridRef& grid_ref, bool state);
    01072
    01073
    01082         void    handleUpdatedItemData(void);
    01083
    01084
    01100         void    setColumnHeaderWidth(uint col_idx, float width);
    01101
    01102
    01114         void    setUserSortControlEnabled(bool setting);
    01115
    01116
    01128         void    setUserColumnSizingEnabled(bool setting);
    01129
    01130
    01139         void    setUserColumnDraggingEnabled(bool setting);
    01140
    01141
    01155         void    autoSizeColumnHeader(uint col_idx);
    01156
    01157
    01173         void    setRowID(uint row_idx, uint row_id);
    01174
    01175
    01176         /*************************************************************************
    01177                 Construction and Destruction
    01178         *************************************************************************/
    01183         MultiColumnList(const String& type, const String& name);
    01184
    01185
    01190         virtual ~MultiColumnList(void);
    01191
    01192
    01193 protected:
    01194         /*************************************************************************
    01195                 Implementation Functions (abstract interface)
    01196         *************************************************************************/
    01206         virtual Rect    getListRenderArea(void) const           = 0;
    01207
    01208
    01219         virtual ListHeader*     createListHeader(const String& name) const              = 0;
    01220
    01221
    01232         virtual Scrollbar*      createVertScrollbar(const String& name) const           = 0;
    01233
    01234
    01245         virtual Scrollbar*      createHorzScrollbar(const String& name) const           = 0;
    01246
    01247
    01258         virtual void    cacheListboxBaseImagery()               = 0;
    01259
    01260
    01261         /*************************************************************************
    01262                 Implementation Functions
    01263         *************************************************************************/
    01268         void    addMultiColumnListboxEvents(void);
    01269
    01270     // overridden from base class.
    01271         virtual void populateRenderCache();
    01272
    01273
    01278         void    configureScrollbars(void);
    01279
    01280
    01285         bool    selectRange(const MCLGridRef& start, const MCLGridRef& end);
    01286
    01287
    01292         float   getTotalRowsHeight(void) const;
    01293
    01294
    01299         float   getWidestColumnItemWidth(uint col_idx) const;
    01300
    01301
    01306         float   getHighestRowItemHeight(uint row_idx) const;
    01307
    01308
    01316         bool    clearAllSelections_impl(void);
    01317
    01318
    01327         ListboxItem*    getItemAtPoint(const Point& pt) const;
    01328
    01329
    01336         bool    setItemSelectState_impl(const MCLGridRef grid_ref, bool state);
    01337
    01338
    01343         void    setSelectForItemsInRow(uint row_idx, bool state);
    01344
    01345
    01350         void    setSelectForItemsInColumn(uint col_idx, bool state);
    01351
    01352
    01360         void    moveColumn_impl(uint col_idx, uint position);
    01361
    01362
    01374         bool    resetList_impl(void);
    01375
    01376
    01387         virtual bool    testClassName_impl(const String& class_name) const
    01388         {
    01389                 if (class_name==(const utf8*)"MultiColumnList") return true;
    01390                 return Window::testClassName_impl(class_name);
    01391         }
    01392
    01393     // overrides function in base class.
    01394     int writePropertiesXML(OutStream& out_stream) const;
    01395
    01396         /*************************************************************************
    01397                 New event handlers for multi column list
    01398         *************************************************************************/
    01403         virtual void    onSelectionModeChanged(WindowEventArgs& e);
    01404
    01405
    01410         virtual void    onNominatedSelectColumnChanged(WindowEventArgs& e);
    01411
    01412
    01417         virtual void    onNominatedSelectRowChanged(WindowEventArgs& e);
    01418
    01419
    01424         virtual void    onVertScrollbarModeChanged(WindowEventArgs& e);
    01425
    01426
    01431         virtual void    onHorzScrollbarModeChanged(WindowEventArgs& e);
    01432
    01433
    01438         virtual void    onSelectionChanged(WindowEventArgs& e);
    01439
    01440
    01445         virtual void    onListContentsChanged(WindowEventArgs& e);
    01446
    01447
    01452         virtual void    onSortColumnChanged(WindowEventArgs& e);
    01453
    01454
    01459         virtual void    onSortDirectionChanged(WindowEventArgs& e);
    01460
    01461
    01466         virtual void    onListColumnSized(WindowEventArgs& e);
    01467
    01468
    01473         virtual void    onListColumnMoved(WindowEventArgs& e);
    01474
    01475
    01476         /*************************************************************************
    01477                 Overridden Event handlers
    01478         *************************************************************************/
    01479         virtual void    onSized(WindowEventArgs& e);
    01480         virtual void    onMouseButtonDown(MouseEventArgs& e);
    01481         virtual void    onMouseWheel(MouseEventArgs& e);
    01482
    01483
    01484         /*************************************************************************
    01485                 Handlers for subscribed events
    01486         *************************************************************************/
    01487         bool    handleHeaderScroll(const EventArgs& e);
    01488         bool    handleHeaderSegMove(const EventArgs& e);
    01489         bool    handleColumnSizeChange(const EventArgs& e);
    01490         bool    handleHorzScrollbar(const EventArgs& e);
    01491         bool    handleVertScrollbar(const EventArgs& e);
    01492         bool    handleSortColumnChange(const EventArgs& e);
    01493         bool    handleSortDirectionChange(const EventArgs& e);
    01494         bool    handleHeaderSegDblClick(const EventArgs& e);
    01495
    01501         struct ListRow
    01502         {
    01503                 typedef std::vector<ListboxItem*>       RowItems;
    01504                 RowItems        d_items;
    01505                 uint            d_sortColumn;
    01506                 uint            d_rowID;
    01507
    01508                 // operators
    01509                 ListboxItem* const& operator[](uint idx) const  {return d_items[idx];}
    01510                 ListboxItem*&   operator[](uint idx) {return d_items[idx];}
    01511                 bool    operator<(const ListRow& rhs) const;
    01512                 bool    operator>(const ListRow& rhs) const;
    01513         };
    01514
    01515
    01520         static bool pred_descend(const ListRow& a, const ListRow& b);
    01521
    01522
    01523         /*************************************************************************
    01524                 Implementation Data
    01525         *************************************************************************/
    01526         // component widgets and settings.
    01527         Scrollbar*      d_vertScrollbar;
    01528         Scrollbar*      d_horzScrollbar;
    01529         ListHeader*     d_header;
    01530         bool    d_forceVertScroll;
    01531         bool    d_forceHorzScroll;
    01532
    01533         // selection abilities.
    01534         SelectionMode   d_selectMode;
    01535         uint    d_nominatedSelectCol;
    01536         uint    d_nominatedSelectRow;
    01537         bool    d_multiSelect;
    01538         bool    d_fullRowSelect;
    01539         bool    d_fullColSelect;
    01540         bool    d_useNominatedRow;
    01541         bool    d_useNominatedCol;
    01542         ListboxItem*    d_lastSelected;
    01543
    01544         // storage of items in the list box.
    01545         typedef std::vector<ListRow>            ListItemGrid;
    01546         ListItemGrid    d_grid;
    01547
    01548
    01549 private:
    01550         /*************************************************************************
    01551                 Static Properties for this class
    01552         *************************************************************************/
    01553         static MultiColumnListProperties::ColumnsMovable                                d_columnsMovableProperty;
    01554         static MultiColumnListProperties::ColumnsSizable                                d_columnsSizableProperty;
    01555         static MultiColumnListProperties::ForceHorzScrollbar                    d_forceHorzScrollProperty;
    01556         static MultiColumnListProperties::ForceVertScrollbar                    d_forceVertScrollProperty;
    01557         static MultiColumnListProperties::NominatedSelectionColumnID    d_nominatedSelectColProperty;
    01558         static MultiColumnListProperties::NominatedSelectionRow                 d_nominatedSelectRowProperty;
    01559         static MultiColumnListProperties::SelectionMode                                 d_selectModeProperty;
    01560         static MultiColumnListProperties::SortColumnID                                  d_sortColumnIDProperty;
    01561         static MultiColumnListProperties::SortDirection                                 d_sortDirectionProperty;
    01562         static MultiColumnListProperties::SortSettingEnabled                    d_sortSettingProperty;
    01563         static MultiColumnListProperties::ColumnHeader                                  d_columnHeaderProperty;
    01564         static MultiColumnListProperties::RowCount                                              d_rowCountProperty;
    01565
    01566
    01567         /*************************************************************************
    01568                 Private methods
    01569         *************************************************************************/
    01570         void    addMultiColumnListProperties(void);
    01571 };
    01572
    01573 } // End of  CEGUI namespace section
    01574
    01575 #if defined(_MSC_VER)
    01576 #       pragma warning(pop)
    01577 #endif
    01578
    01579 #endif  // end of guard _CEGUIMultiColumnList_h_