wxPython/wx/lib/mixins/listctrl.py

   1 #----------------------------------------------------------------------------
   2 # Name:        wxPython.lib.mixins.listctrl
   3 # Purpose:     Helpful mix-in classes for wxListCtrl
   4 #
   5 # Author:      Robin Dunn
   6 #
   7 # Created:     15-May-2001
   8 # RCS-ID:      $Id$
   9 # Copyright:   (c) 2001 by Total Control Software
  10 # Licence:     wxWindows license
  11 #----------------------------------------------------------------------------
  12 # 12/14/2003 - Jeff Grimmett (grimmtooth@softhome.net)
  13 #
  14 # o 2.5 compatability update.
  15 # o ListCtrlSelectionManagerMix untested.
  16 #
  17 # 12/21/2003 - Jeff Grimmett (grimmtooth@softhome.net)
  18 #
  19 # o wxColumnSorterMixin -> ColumnSorterMixin
  20 # o wxListCtrlAutoWidthMixin -> ListCtrlAutoWidthMixin
  21 # ...
  22 # 13/10/2004 - Pim Van Heuven (pim@think-wize.com)
  23 # o wxTextEditMixin: Support Horizontal scrolling when TAB is pressed on long
  24 #       ListCtrls, support for WXK_DOWN, WXK_UP, performance improvements on
  25 #       very long ListCtrls, Support for virtual ListCtrls
  26 #
  27 # 15-Oct-2004 - Robin Dunn
  28 # o wxTextEditMixin: Added Shift-TAB support
  29 #
  30
  31 import  locale
  32 import  wx
  33
  34 #----------------------------------------------------------------------------
  35
  36 class ColumnSorterMixin:
  37     """
  38     A mixin class that handles sorting of a wx.ListCtrl in REPORT mode when
  39     the column header is clicked on.
  40
  41     There are a few requirments needed in order for this to work genericly:
  42
  43       1. The combined class must have a GetListCtrl method that
  44          returns the wx.ListCtrl to be sorted, and the list control
  45          must exist at the time the wx.ColumnSorterMixin.__init__
  46          method is called because it uses GetListCtrl.
  47
  48       2. Items in the list control must have a unique data value set
  49          with list.SetItemData.
  50
  51       3. The combined class must have an attribute named itemDataMap
  52          that is a dictionary mapping the data values to a sequence of
  53          objects representing the values in each column.  These values
  54          are compared in the column sorter to determine sort order.
  55
  56     Interesting methods to override are GetColumnSorter,
  57     GetSecondarySortValues, and GetSortImages.  See below for details.
  58     """
  59
  60     def __init__(self, numColumns):
  61         self.SetColumnCount(numColumns)
  62         list = self.GetListCtrl()
  63         if not list:
  64             raise ValueError, "No wx.ListCtrl available"
  65         self.Bind(wx.EVT_LIST_COL_CLICK, self.__OnColClick, list)
  66
  67
  68     def SetColumnCount(self, newNumColumns):
  69         self._colSortFlag = [0] * newNumColumns
  70         self._col = -1
  71
  72
  73     def SortListItems(self, col=-1, ascending=1):
  74         """Sort the list on demand.  Can also be used to set the sort column and order."""
  75         oldCol = self._col
  76         if col != -1:
  77             self._col = col
  78             self._colSortFlag[col] = ascending
  79         self.GetListCtrl().SortItems(self.GetColumnSorter())
  80         self.__updateImages(oldCol)
  81
  82
  83     def GetColumnWidths(self):
  84         """
  85         Returns a list of column widths.  Can be used to help restore the current
  86         view later.
  87         """
  88         list = self.GetListCtrl()
  89         rv = []
  90         for x in range(len(self._colSortFlag)):
  91             rv.append(list.GetColumnWidth(x))
  92         return rv
  93
  94
  95     def GetSortImages(self):
  96         """
  97         Returns a tuple of image list indexesthe indexes in the image list for an image to be put on the column
  98         header when sorting in descending order.
  99         """
 100         return (-1, -1)  # (decending, ascending) image IDs
 101
 102
 103     def GetColumnSorter(self):
 104         """Returns a callable object to be used for comparing column values when sorting."""
 105         return self.__ColumnSorter
 106
 107
 108     def GetSecondarySortValues(self, col, key1, key2):
 109         """Returns a tuple of 2 values to use for secondary sort values when the
 110            items in the selected column match equal.  The default just returns the
 111            item data values."""
 112         return (key1, key2)
 113
 114
 115     def __OnColClick(self, evt):
 116         oldCol = self._col
 117         self._col = col = evt.GetColumn()
 118         self._colSortFlag[col] = not self._colSortFlag[col]
 119         self.GetListCtrl().SortItems(self.GetColumnSorter())
 120         self.__updateImages(oldCol)
 121         evt.Skip()
 122
 123
 124     def __ColumnSorter(self, key1, key2):
 125         col = self._col
 126         ascending = self._colSortFlag[col]
 127         item1 = self.itemDataMap[key1][col]
 128         item2 = self.itemDataMap[key2][col]
 129
 130         #--- Internationalization of string sorting with locale module
 131         if type(item1) == type('') or type(item2) == type(''):
 132             cmpVal = locale.strcoll(str(item1), str(item2))
 133         else:
 134             cmpVal = cmp(item1, item2)
 135         #---
 136
 137         # If the items are equal then pick something else to make the sort value unique
 138         if cmpVal == 0:
 139             cmpVal = apply(cmp, self.GetSecondarySortValues(col, key1, key2))
 140
 141         if ascending:
 142             return cmpVal
 143         else:
 144             return -cmpVal
 145
 146
 147     def __updateImages(self, oldCol):
 148         sortImages = self.GetSortImages()
 149         if self._col != -1 and sortImages[0] != -1:
 150             img = sortImages[self._colSortFlag[self._col]]
 151             list = self.GetListCtrl()
 152             if oldCol != -1:
 153                 list.ClearColumnImage(oldCol)
 154             list.SetColumnImage(self._col, img)
 155
 156
 157 #----------------------------------------------------------------------------
 158 #----------------------------------------------------------------------------
 159
 160 class ListCtrlAutoWidthMixin:
 161     """ A mix-in class that automatically resizes the last column to take up
 162         the remaining width of the wx.ListCtrl.
 163
 164         This causes the wx.ListCtrl to automatically take up the full width of
 165         the list, without either a horizontal scroll bar (unless absolutely
 166         necessary) or empty space to the right of the last column.
 167
 168         NOTE:    This only works for report-style lists.
 169
 170         WARNING: If you override the EVT_SIZE event in your wx.ListCtrl, make
 171                  sure you call event.Skip() to ensure that the mixin's
 172                  _OnResize method is called.
 173
 174         This mix-in class was written by Erik Westra <ewestra@wave.co.nz>
 175     """
 176     def __init__(self):
 177         """ Standard initialiser.
 178         """
 179         self._resizeColMinWidth = None
 180         self._resizeColStyle = "LAST"
 181         self._resizeCol = 0
 182         self.Bind(wx.EVT_SIZE, self._onResize)
 183         self.Bind(wx.EVT_LIST_COL_END_DRAG, self._onResize, self)
 184
 185
 186     def setResizeColumn(self, col):
 187         """
 188         Specify which column that should be autosized.  Pass either
 189         'LAST' or the column number.  Default is 'LAST'.
 190         """
 191         if col == "LAST":
 192             self._resizeColStyle = "LAST"
 193         else:
 194             self._resizeColStyle = "COL"
 195             self._resizeCol = col
 196
 197
 198     def resizeLastColumn(self, minWidth):
 199         """ Resize the last column appropriately.
 200
 201             If the list's columns are too wide to fit within the window, we use
 202             a horizontal scrollbar.  Otherwise, we expand the right-most column
 203             to take up the remaining free space in the list.
 204
 205             This method is called automatically when the wx.ListCtrl is resized;
 206             you can also call it yourself whenever you want the last column to
 207             be resized appropriately (eg, when adding, removing or resizing
 208             columns).
 209
 210             'minWidth' is the preferred minimum width for the last column.
 211         """
 212         self.resizeColumn(self, minWidth)
 213
 214
 215     def resizeColumn(self, minWidth):
 216         self._resizeColMinWidth = minWidth
 217         self._doResize()
 218
 219
 220     # =====================
 221     # == Private Methods ==
 222     # =====================
 223
 224     def _onResize(self, event):
 225         """ Respond to the wx.ListCtrl being resized.
 226
 227             We automatically resize the last column in the list.
 228         """
 229         wx.CallAfter(self._doResize)
 230         event.Skip()
 231
 232
 233     def _doResize(self):
 234         """ Resize the last column as appropriate.
 235
 236             If the list's columns are too wide to fit within the window, we use
 237             a horizontal scrollbar.  Otherwise, we expand the right-most column
 238             to take up the remaining free space in the list.
 239
 240             We remember the current size of the last column, before resizing,
 241             as the preferred minimum width if we haven't previously been given
 242             or calculated a minimum width.  This ensure that repeated calls to
 243             _doResize() don't cause the last column to size itself too large.
 244         """
 245
 246         if not self:  # avoid a PyDeadObject error
 247             return
 248
 249         numCols = self.GetColumnCount()
 250         if numCols == 0: return # Nothing to resize.
 251
 252         if(self._resizeColStyle == "LAST"):
 253             resizeCol = self.GetColumnCount()
 254         else:
 255             resizeCol = self._resizeCol
 256
 257         if self._resizeColMinWidth == None:
 258             self._resizeColMinWidth = self.GetColumnWidth(resizeCol - 1)
 259
 260         # We're showing the vertical scrollbar -> allow for scrollbar width
 261         # NOTE: on GTK, the scrollbar is included in the client size, but on
 262         # Windows it is not included
 263         listWidth = self.GetClientSize().width
 264         if wx.Platform != '__WXMSW__':
 265             if self.GetItemCount() > self.GetCountPerPage():
 266                 scrollWidth = wx.SystemSettings_GetMetric(wx.SYS_VSCROLL_X)
 267                 listWidth = listWidth - scrollWidth
 268
 269         totColWidth = 0 # Width of all columns except last one.
 270         for col in range(numCols):
 271             if col != (resizeCol-1):
 272                 totColWidth = totColWidth + self.GetColumnWidth(col)
 273
 274         resizeColWidth = self.GetColumnWidth(resizeCol - 1)
 275
 276         if totColWidth + self._resizeColMinWidth > listWidth:
 277             # We haven't got the width to show the last column at its minimum
 278             # width -> set it to its minimum width and allow the horizontal
 279             # scrollbar to show.
 280             self.SetColumnWidth(resizeCol-1, self._resizeColMinWidth)
 281             return
 282
 283         # Resize the last column to take up the remaining available space.
 284
 285         self.SetColumnWidth(resizeCol-1, listWidth - totColWidth)
 286
 287
 288
 289
 290 #----------------------------------------------------------------------------
 291
 292 SEL_FOC = wx.LIST_STATE_SELECTED | wx.LIST_STATE_FOCUSED
 293 def selectBeforePopup(event):
 294     """Ensures the item the mouse is pointing at is selected before a popup.
 295
 296     Works with both single-select and multi-select lists."""
 297     ctrl = event.GetEventObject()
 298     if isinstance(ctrl, wx.ListCtrl):
 299         n, flags = ctrl.HitTest(event.GetPosition())
 300         if n >= 0:
 301             if not ctrl.GetItemState(n, wx.LIST_STATE_SELECTED):
 302                 for i in range(ctrl.GetItemCount()):
 303                     ctrl.SetItemState(i, 0, SEL_FOC)
 304                 #for i in getListCtrlSelection(ctrl, SEL_FOC):
 305                 #    ctrl.SetItemState(i, 0, SEL_FOC)
 306                 ctrl.SetItemState(n, SEL_FOC, SEL_FOC)
 307
 308
 309 def getListCtrlSelection(listctrl, state=wx.LIST_STATE_SELECTED):
 310     """ Returns list of item indexes of given state (selected by defaults) """
 311     res = []
 312     idx = -1
 313     while 1:
 314         idx = listctrl.GetNextItem(idx, wx.LIST_NEXT_ALL, state)
 315         if idx == -1:
 316             break
 317         res.append(idx)
 318     return res
 319
 320 wxEVT_DOPOPUPMENU = wx.NewEventType()
 321 EVT_DOPOPUPMENU = wx.PyEventBinder(wxEVT_DOPOPUPMENU, 0)
 322
 323
 324 class ListCtrlSelectionManagerMix:
 325     """Mixin that defines a platform independent selection policy
 326
 327     As selection single and multi-select list return the item index or a
 328     list of item indexes respectively.
 329     """
 330     _menu = None
 331
 332     def __init__(self):
 333         self.Bind(wx.EVT_RIGHT_DOWN, self.OnLCSMRightDown)
 334         self.Bind(EVT_DOPOPUPMENU, self.OnLCSMDoPopup)
 335 #        self.Connect(-1, -1, self.wxEVT_DOPOPUPMENU, self.OnLCSMDoPopup)
 336
 337
 338     def getPopupMenu(self):
 339         """ Override to implement dynamic menus (create) """
 340         return self._menu
 341
 342
 343     def setPopupMenu(self, menu):
 344         """ Must be set for default behaviour """
 345         self._menu = menu
 346
 347
 348     def afterPopupMenu(self, menu):
 349         """ Override to implement dynamic menus (destroy) """
 350         pass
 351
 352
 353     def getSelection(self):
 354         res = getListCtrlSelection(self)
 355         if self.GetWindowStyleFlag() & wx.LC_SINGLE_SEL:
 356             if res:
 357                 return res[0]
 358             else:
 359                 return -1
 360         else:
 361             return res
 362
 363
 364     def OnLCSMRightDown(self, event):
 365         selectBeforePopup(event)
 366         event.Skip()
 367         menu = self.getPopupMenu()
 368         if menu:
 369             evt = wx.PyEvent()
 370             evt.SetEventType(wxEVT_DOPOPUPMENU)
 371             evt.menu = menu
 372             evt.pos = event.GetPosition()
 373             wx.PostEvent(self, evt)
 374
 375
 376     def OnLCSMDoPopup(self, event):
 377         self.PopupMenu(event.menu, event.pos)
 378         self.afterPopupMenu(event.menu)
 379
 380
 381 #----------------------------------------------------------------------------
 382 from bisect import bisect
 383
 384
 385 class TextEditMixin:
 386     """
 387     A mixin class that enables any text in any column of a
 388     multi-column listctrl to be edited by clicking on the given row
 389     and column.  You close the text editor by hitting the ENTER key or
 390     clicking somewhere else on the listctrl. You switch to the next
 391     column by hiting TAB.
 392
 393     To use the mixin you have to include it in the class definition
 394     and call the __init__ function::
 395
 396         class TestListCtrl(wx.ListCtrl, TextEditMixin):
 397             def __init__(self, parent, ID, pos=wx.DefaultPosition,
 398                          size=wx.DefaultSize, style=0):
 399                 wx.ListCtrl.__init__(self, parent, ID, pos, size, style)
 400                 TextEditMixin.__init__(self)
 401
 402
 403     Authors:     Steve Zatz, Pim Van Heuven (pim@think-wize.com)
 404     """
 405
 406     editorBgColour = wx.Colour(255,255,175) # Yellow
 407     editorFgColour = wx.Colour(0,0,0)       # black
 408
 409     def __init__(self):
 410         #editor = wx.TextCtrl(self, -1, pos=(-1,-1), size=(-1,-1),
 411         #                     style=wx.TE_PROCESS_ENTER|wx.TE_PROCESS_TAB \
 412         #                     |wx.TE_RICH2)
 413
 414         self.make_editor()
 415         self.Bind(wx.EVT_TEXT_ENTER, self.CloseEditor)
 416         self.Bind(wx.EVT_LEFT_DOWN, self.OnLeftDown)
 417         self.Bind(wx.EVT_LEFT_DCLICK, self.OnLeftDown)
 418         self.Bind(wx.EVT_LIST_ITEM_SELECTED, self.OnItemSelected)
 419
 420
 421     def make_editor(self, col_style=wx.LIST_FORMAT_LEFT):
 422         editor = wx.PreTextCtrl()
 423
 424         style =wx.TE_PROCESS_ENTER|wx.TE_PROCESS_TAB|wx.TE_RICH2
 425         style |= {wx.LIST_FORMAT_LEFT: wx.TE_LEFT,
 426                   wx.LIST_FORMAT_RIGHT: wx.TE_RIGHT,
 427                   wx.LIST_FORMAT_CENTRE : wx.TE_CENTRE
 428                   }[col_style]
 429
 430         editor.Create(self, -1, style=style)
 431         editor.SetBackgroundColour(self.editorBgColour)
 432         editor.SetForegroundColour(self.editorFgColour)
 433         font = self.GetFont()
 434         editor.SetFont(font)
 435
 436         self.curRow = 0
 437         self.curCol = 0
 438
 439         editor.Hide()
 440         self.editor = editor
 441
 442         self.col_style = col_style
 443         self.editor.Bind(wx.EVT_CHAR, self.OnChar)
 444         self.editor.Bind(wx.EVT_KILL_FOCUS, self.CloseEditor)
 445
 446
 447     def OnItemSelected(self, evt):
 448         self.curRow = evt.GetIndex()
 449         evt.Skip()
 450
 451
 452     def OnChar(self, event):
 453         ''' Catch the TAB, Shift-TAB, cursor DOWN/UP key code
 454             so we can open the editor at the next column (if any).'''
 455
 456         keycode = event.GetKeyCode()
 457         if keycode == wx.WXK_TAB and event.ShiftDown():
 458             self.CloseEditor()
 459             if self.curCol-1 >= 0:
 460                 self.OpenEditor(self.curCol-1, self.curRow)
 461
 462         elif keycode == wx.WXK_TAB:
 463             self.CloseEditor()
 464             if self.curCol+1 < self.GetColumnCount():
 465                 self.OpenEditor(self.curCol+1, self.curRow)
 466
 467         elif keycode == wx.WXK_ESCAPE:
 468             self.CloseEditor()
 469
 470         elif keycode == wx.WXK_DOWN:
 471             self.CloseEditor()
 472             if self.curRow+1 < self.GetItemCount():
 473                 self._SelectIndex(self.curRow+1)
 474                 self.OpenEditor(self.curCol, self.curRow)
 475
 476         elif keycode == wx.WXK_UP:
 477             self.CloseEditor()
 478             if self.curRow > 0:
 479                 self._SelectIndex(self.curRow-1)
 480                 self.OpenEditor(self.curCol, self.curRow)
 481
 482         else:
 483             event.Skip()
 484
 485
 486     def OnLeftDown(self, evt=None):
 487         ''' Examine the click and double
 488         click events to see if a row has been click on twice. If so,
 489         determine the current row and columnn and open the editor.'''
 490
 491         if self.editor.IsShown():
 492             self.CloseEditor()
 493
 494         x,y = evt.GetPosition()
 495         row,flags = self.HitTest((x,y))
 496
 497         if row != self.curRow: # self.curRow keeps track of the current row
 498             evt.Skip()
 499             return
 500
 501         # the following should really be done in the mixin's init but
 502         # the wx.ListCtrl demo creates the columns after creating the
 503         # ListCtrl (generally not a good idea) on the other hand,
 504         # doing this here handles adjustable column widths
 505
 506         self.col_locs = [0]
 507         loc = 0
 508         for n in range(self.GetColumnCount()):
 509             loc = loc + self.GetColumnWidth(n)
 510             self.col_locs.append(loc)
 511
 512
 513         col = bisect(self.col_locs, x+self.GetScrollPos(wx.HORIZONTAL)) - 1
 514         self.OpenEditor(col, row)
 515
 516
 517     def OpenEditor(self, col, row):
 518         ''' Opens an editor at the current position. '''
 519
 520         if self.GetColumn(col).m_format != self.col_style:
 521             self.make_editor(self.GetColumn(col).m_format)
 522
 523         x0 = self.col_locs[col]
 524         x1 = self.col_locs[col+1] - x0
 525
 526         scrolloffset = self.GetScrollPos(wx.HORIZONTAL)
 527
 528         # scroll forward
 529         if x0+x1-scrolloffset > self.GetSize()[0]:
 530             if wx.Platform == "__WXMSW__":
 531                 # don't start scrolling unless we really need to
 532                 offset = x0+x1-self.GetSize()[0]-scrolloffset
 533                 # scroll a bit more than what is minimum required
 534                 # so we don't have to scroll everytime the user presses TAB
 535                 # which is very tireing to the eye
 536                 addoffset = self.GetSize()[0]/4
 537                 # but be careful at the end of the list
 538                 if addoffset + scrolloffset < self.GetSize()[0]:
 539                     offset += addoffset
 540
 541                 self.ScrollList(offset, 0)
 542                 scrolloffset = self.GetScrollPos(wx.HORIZONTAL)
 543             else:
 544                 # Since we can not programmatically scroll the ListCtrl
 545                 # close the editor so the user can scroll and open the editor
 546                 # again
 547                 self.editor.SetValue(self.GetItem(row, col).GetText())
 548                 self.curRow = row
 549                 self.curCol = col
 550                 self.CloseEditor()
 551                 return
 552
 553         y0 = self.GetItemRect(row)[1]
 554
 555         editor = self.editor
 556         editor.SetDimensions(x0-scrolloffset,y0, x1,-1)
 557
 558         editor.SetValue(self.GetItem(row, col).GetText())
 559         editor.Show()
 560         editor.Raise()
 561         editor.SetSelection(-1,-1)
 562         editor.SetFocus()
 563
 564         self.curRow = row
 565         self.curCol = col
 566
 567
 568     # FIXME: this function is usually called twice - second time because
 569     # it is binded to wx.EVT_KILL_FOCUS. Can it be avoided? (MW)
 570     def CloseEditor(self, evt=None):
 571         ''' Close the editor and save the new value to the ListCtrl. '''
 572         text = self.editor.GetValue()
 573         self.editor.Hide()
 574         self.SetFocus()
 575
 576         # post wxEVT_COMMAND_LIST_END_LABEL_EDIT
 577         # Event can be vetoed. It doesn't has SetEditCanceled(), what would
 578         # require passing extra argument to CloseEditor()
 579         evt = wx.ListEvent(wx.wxEVT_COMMAND_LIST_END_LABEL_EDIT, self.GetId())
 580         evt.m_itemIndex = self.curRow
 581         evt.m_col = self.curCol
 582         item = self.GetItem(self.curRow, self.curCol)
 583         evt.m_item.SetId(item.GetId())
 584         evt.m_item.SetColumn(item.GetColumn())
 585         evt.m_item.SetData(item.GetData())
 586         evt.m_item.SetText(text) #should be empty string if editor was canceled
 587         ret = self.GetEventHandler().ProcessEvent(evt)
 588         if not ret or evt.IsAllowed():
 589             if self.IsVirtual():
 590                 # replace by whather you use to populate the virtual ListCtrl
 591                 # data source
 592                 self.SetVirtualData(self.curRow, self.curCol, text)
 593             else:
 594                 self.SetStringItem(self.curRow, self.curCol, text)
 595         self.RefreshItem(self.curRow)
 596
 597     def _SelectIndex(self, row):
 598         listlen = self.GetItemCount()
 599         if row < 0 and not listlen:
 600             return
 601         if row > (listlen-1):
 602             row = listlen -1
 603
 604         self.SetItemState(self.curRow, ~wx.LIST_STATE_SELECTED,
 605                           wx.LIST_STATE_SELECTED)
 606         self.EnsureVisible(row)
 607         self.SetItemState(row, wx.LIST_STATE_SELECTED,
 608                           wx.LIST_STATE_SELECTED)
 609
 610
 611
 612 #----------------------------------------------------------------------------