src/MuleListCtrl.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2003-2008 aMule Team ( admin@amule.org / http://www.amule.org )
   5 // Copyright (c) 2002 Merkur ( devs@emule-project.net / http://www.emule-project.net )
   6 //
   7 // Any parts of this program derived from the xMule, lMule or eMule project,
   8 // or contributed by third-party developers are copyrighted by their
   9 // respective authors.
  10 //
  11 // This program is free software; you can redistribute it and/or modify
  12 // it under the terms of the GNU General Public License as published by
  13 // the Free Software Foundation; either version 2 of the License, or
  14 // (at your option) any later version.
  15 //
  16 // This program is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 // GNU General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License
  22 // along with this program; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  24 //
  25
  26 #ifndef MULELISTCTRL_H
  27 #define MULELISTCTRL_H
  28
  29 #ifdef WIN32
  30 #include <wx/msw/winundef.h>
  31 #endif
  32
  33 #include <wx/defs.h> // Do_not_auto_remove (Mac, Win32, and just good practice)
  34 #include "extern/wxWidgets/listctrl.h"
  35
  36 #include <vector>
  37 #include <list>
  38
  39
  40 /**
  41  * Enhanced wxListCtrl provided custom-drawing among other things.
  42  *
  43  * This class provides these features which the original wxListCtrl lacks:
  44  *  - Automatic sort arrows upon clicks on the column headers
  45  *  - Custom drawing of items.
  46  *  - Hiding of columns through auto-generated popup-menu.
  47  *  - Helper function for inserting items pre-sorted.
  48  *  - Loading and saving of column properties.
  49  *  - Selection of items by typing an initial part of the text (TTS).
  50  */
  51 class CMuleListCtrl : public MuleExtern::wxGenericListCtrl
  52 {
  53 public:
  54         /**
  55          * The various ways in which a column can be sorted.
  56          *
  57          * If SORT_DES is not set, sorting is taken to be
  58          * ascending. If SORT_ALT is not set, sorting is
  59          * taken to be normal.
  60          */
  61         enum MLOrder
  62         {
  63                 //! If set, sorting is to be in descending order.
  64                 SORT_DES        = 0x1000,
  65
  66                 //! If sorting should use alternate method.
  67                 //! Is specified in with or without DEC.
  68                 SORT_ALT        = 0x2000
  69         };
  70
  71         //! Mask which covers the column part of the sort-data.
  72         static const unsigned COLUMN_MASK = 0xfff;
  73
  74         //! Mask which covers the sorting part of the sort-data.
  75         static const unsigned SORTING_MASK = 0x3000;
  76
  77         /**
  78          * Constructor.
  79          *
  80          * @see wxGenericListCtrl::wxGenericListCtrl for documentation of parameters.
  81          */
  82          CMuleListCtrl(
  83                     wxWindow *parent,
  84                 wxWindowID winid = -1,
  85                 const wxPoint &pos = wxDefaultPosition,
  86                 const wxSize &size = wxDefaultSize,
  87                 long style = wxLC_ICON,
  88                 const wxValidator& validator = wxDefaultValidator,
  89                 const wxString &name = wxT("mulelistctrl") );
  90
  91         /**
  92          * Destructor.
  93          *
  94          * If a name for the table has been specified with SetTableName, then
  95          * column settings will be saved automatically.
  96          */
  97         virtual ~CMuleListCtrl();
  98
  99
 100         /**
 101          * Saves column settings.
 102          *
 103          * Currently saves the width of all columns, hidden columns, the column
 104          * to sort by and in which direction to sort.
 105          */
 106         virtual void SaveSettings();
 107
 108         /**
 109          * Loads column settings.
 110          *
 111          * Currently loads the width of all columns, hidden columns, the column
 112          * to sort by and in which direction to sort. This function also ensures
 113          * that the items are sorted after the settings have been read.
 114          */
 115         virtual void LoadSettings();
 116
 117
 118         /**
 119          * This function tries to locate the best place to insert an item.
 120          *
 121          * @param The userdata of the new item.
 122          *
 123          * This function does a binary type search to locate the best place to
 124          * insert the new item with the specified userdata. It then returns the
 125          * item after this position. To do this, the sorter-function must be set
 126          * though the SetSortFunc function, otherwise it will just return the
 127          * position after the last item.
 128          */
 129         long GetInsertPos( wxUIntPtr data );
 130
 131
 132         /**
 133          * Sorts the list.
 134          *
 135          * Before you can use this function, you will need to specify a sorter
 136          * function using SetSortFunc. wxListCtrl needs such a function to
 137          * perform the sort.
 138          */
 139         virtual void SortList();
 140
 141
 142         //! The type of the list of item specific data
 143         typedef std::vector<wxUIntPtr> ItemDataList;
 144
 145         /**
 146          * Returns a list the user-data of all selected items.
 147          *
 148          * @return A list of data assosiated with the selected items.
 149          *
 150          * This function will return the user-data for each selected item in a
 151          * vector, which can then be manipulated with regards to changes made
 152          * in the current order of the listctrl items.
 153          */
 154         ItemDataList GetSelectedItems() const;
 155
 156
 157         /**
 158          * Sets the sorter function.
 159          *
 160          * @param func
 161          *
 162          * See the documentation on wxListCtrl::SortItems for more information
 163          * about the expected function type.
 164          */
 165         void SetSortFunc(MuleListCtrlCompare func);
 166
 167
 168         /**
 169          * Deselects all selected items, but does not change focus.
 170          */
 171         void ClearSelection();
 172
 173 protected:
 174
 175         /**
 176          * Must be overwritten to enable alternate sorting.
 177          *
 178          * @param The column being sorted.
 179          *
 180          * Subclasses of CMuleListCtrl can allow alternative sorting
 181          * of columns. This is done by overriding this function and
 182          * returning true for the columns where alternative sorting
 183          * is desired.
 184          */
 185         virtual bool AltSortAllowed(unsigned column) const;
 186
 187         /**
 188          * Returns the string used when selecting rows via Type-To-Select.
 189          *
 190          * @param item The index of the item being examined.
 191          *
 192          * By default, this function simply returns the text in the first
 193          * column for the given item. However, when owner-drawing is
 194          * enabled, this function _must_ be overriden.
 195          */
 196         virtual wxString GetTTSText(unsigned item) const;
 197
 198
 199         /**
 200          * Sets the internally used table-name.
 201          *
 202          * @param name The new name or an empty string to disable.
 203          *
 204          * You need to call this function with a unique name before you can
 205          * make use of the LoadSettings/SaveSettings functions. CMuleListCtrl
 206          * uses the name specified in this command to create unique keynames.
 207          */
 208         void SetTableName(const wxString& name);
 209
 210         /**
 211          * Returns the column which is currently used to sort the list.
 212          */
 213         unsigned GetSortColumn() const;
 214
 215         /**
 216          * Returns the current sorting order, a combination of the DES and ALT flags.
 217          */
 218         unsigned GetSortOrder() const;
 219
 220         /**
 221          * Set the sort column
 222          *
 223          * @param column The column with which the list should be sorted.
 224          * @param order The order in which to sort the column.
 225          *
 226          * Note that attempting to sort a column in an unsupported order
 227          * is an illegal operation.
 228          */
 229         void SetSorting(unsigned column, unsigned order);
 230
 231         /**
 232          * Returns true if the item is sorted compared to its neighbohrs.
 233          */
 234         bool IsItemSorted(long item);
 235
 236
 237
 238         /**
 239          * Check and fix selection state.
 240          *
 241          * @param event The event which triggered the selection.
 242          * @return The index of the item selected or -1 if none.
 243          *
 244          * This function checks if the clicked item is selected.
 245          * If not, then the item is selected and all other items
 246          * are deselected.
 247          */
 248         //@{
 249         long CheckSelection(wxListEvent& event);
 250         long CheckSelection(wxMouseEvent& event);
 251         //@}
 252
 253
 254         /**
 255          * Event handler for right-clicks on the column headers.
 256          */
 257         void OnColumnRClick(wxListEvent& evt);
 258         /**
 259          * Event handler for left-clicks on the column headers.
 260          */
 261         void OnColumnLClick(wxListEvent& evt);
 262         /**
 263          * Event handler for the hide/show menu items.
 264          */
 265         void OnMenuSelected(wxCommandEvent& evt);
 266         /**
 267          * Event handler for the mouse wheel.
 268          */
 269         void OnMouseWheel(wxMouseEvent &event);
 270         /**
 271          * Event handler for key-presses, needed by TTS.
 272          */
 273         void OnChar(wxKeyEvent& evt);
 274         /**
 275          * Event handler for item selection/deletion, needed by TTS.
 276          */
 277         void OnItemSelected(wxListEvent& evt);
 278         void OnItemDeleted(wxListEvent& evt);
 279         void OnAllItemsDeleted(wxListEvent& evt);
 280
 281
 282 private:
 283         /**
 284          * Resets the current TTS session.
 285          */
 286         void ResetTTS();
 287
 288         /**
 289          * Sets the image of a specific column.
 290          *
 291          * @param col The column to change.
 292          * @param order The sorting order to represent. Zero unsets the image.
 293          */
 294         void SetColumnImage(unsigned col, int image);
 295
 296
 297         //! The name of the table. Used to load/save settings.
 298         wxString                        m_name;
 299         //! The sorter function needed by wxListCtrl.
 300         MuleListCtrlCompare     m_sort_func;
 301
 302         //! Contains the current search string.
 303         wxString                        m_tts_text;
 304         //! Timestamp for the last TTS event.
 305         unsigned                        m_tts_time;
 306         //! The index of the last item selected via TTS.
 307         int                                     m_tts_item;
 308
 309
 310         /**
 311          * Wrapper around the user-provided sorter function.
 312          *
 313          * This function ensures that items are sorted in the order
 314          * specified by clicking on column-headers, and also enforces
 315          * that different entries are never considered equal. This is
 316          * required for lists that make use of child-items, since
 317          * otherwise, parents may not end up properly located in
 318          * relation to child-items.
 319          */
 320         static int wxCALLBACK SortProc(wxUIntPtr item1, wxUIntPtr item2, long sortData);
 321
 322         /** Compares two items in the list, using the current sort sequence. */
 323         int CompareItems(wxUIntPtr item1, wxUIntPtr item2);
 324
 325
 326         //! This pair contains a column number and its sorting order.
 327         typedef std::pair<unsigned, unsigned> CColPair;
 328         typedef std::list<CColPair> CSortingList;
 329
 330         //! This list contains in order the columns sequence to sort by.
 331         CSortingList m_sort_orders;
 332
 333
 334         DECLARE_EVENT_TABLE()
 335 };
 336
 337
 338 #endif // MULELISTCTRL_H
 339 // File_checked_for_headers