home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / mac / UserInterface / Tables / TableClasses.doc < prev   
Encoding:
Text File  |  1998-04-08  |  5.3 KB  |  167 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. This document describes the following classes:
  20.  
  21. LTableHeader            
  22. LTableViewHeader    
  23. LTableRowSelector    
  24. LFlexTableGeometry    
  25.  
  26. There is also a description of how they can all be used together at the end.
  27.  
  28.  
  29. ---- LTableHeader ----
  30.  
  31. This subclass of LView implements a table header with resizable and movable columns.  
  32. Column headers are individual panes within the view.  These panes are always positioned
  33. appropriately to be in line with their columns.  The panes are resized horizontally to
  34. touch the left and right edges of their columns.
  35.  
  36. The class also supports special appearance for the sorted column, chosen by clicking 
  37. on a column header.
  38.  
  39. The header does NOT scroll.  Columns are always resized proportionally, though columns
  40. can be marked as fixed width. The header's image size always matches its frame.
  41.  
  42.  
  43. Ñ Creation
  44.  
  45. The view has custom PPob and also requires a 'Cols' resource.  The data in the PPob
  46. specifies the following information:
  47.  
  48.     header flags:                
  49.         only 1, kHeaderCanHideColumns
  50.     
  51.     2 bevel trait resource ids:
  52.         sorted column header, then unsorted
  53.         
  54.     reverse modifiers:
  55.         an event record modifier mask that denotes a reverse-sort selection
  56.         
  57.     'Cols' resource ID:    
  58.         id of 'Cols' resource, with column initialization data, REQUIRED
  59.             
  60.  
  61. The 'Cols' resource is used to initialize the size and positioning of the header's 
  62. columns.  The header of the resource (SavedHeaderState) is defined in LTableHeader.h.
  63. Following the header is an array of ColumnData (also in LTableHeader.h) records, 1 
  64. for each column.
  65.  
  66. The header of the resource specifies:
  67.     
  68.         # of columns                        (1-based)
  69.         index of rightmost visible column    (1-based)
  70.         index of sorted column                (1-based, 0 if none)
  71.         
  72.         
  73. Each ColumnData record specifies:
  74.  
  75.         Pane ID of column header, 0 if none
  76.         
  77.         Column Width
  78.             In pixels if fixed size, in % of non-fixed space if resizable
  79.             
  80.         Column Position 
  81.             Meaningless in saved state, ignore it.
  82.             
  83.         ColumnFlags
  84.             kColumnDoesNotSort and/or kColumnDoesNotResize
  85.     
  86.     
  87. Ñ Header and Column Size
  88.     
  89.     If a column is fixed-width, it will always have that width. Widths of resizable 
  90.     columns are maintained as percentages of the non-fixed space in the header.
  91.     
  92.     When a column is resized, all columns to its right resize proportionally.  
  93.  
  94.     
  95. Ñ Hiding/Showing Columns    
  96.  
  97.     If the kHeaderCanHideColumns flag is set in the header flags, the view will have
  98.     a widget at the right edge for hiding and showing columns.
  99.     
  100. Ñ Dragging/Resizing Columns
  101.  
  102.     To change the rgn that gets dragged when resizing or moving a column, override
  103.     ComputeResizeDragRect or ComputeColumnDragRect respectively.
  104.     
  105. Ñ Sorting
  106.  
  107.     When the sorted column changes, LTableHeader broadcasts a msg_SortedColumnChanged
  108.     message, with TableHeaderSortChange parameter.
  109.     
  110.     The method GetSortedColumn returns both the index and the header pane ID of the
  111.     sorted column.
  112.     
  113.     
  114.     
  115.     
  116.         
  117.  
  118. ---- LTableViewHeader ----
  119.  
  120. LTableViewHeader is a subclass of LTableHeader that coordinates changes in the header
  121. with an LTableView.  
  122.  
  123. When columns are hidden or shown in the header, this class removes/adds columns from/to 
  124. the table view.  
  125.  
  126. When the image size of the header changes, the image size of the table is adjusted as well. 
  127.  
  128. When columns are redrawn in the header, they are invalidated for refresh in the table view.
  129.  
  130. This class also overrides ComputeResizeDragRect and ComputeColumnDragRect to create more
  131. useful regions when dragging and resizing columns.
  132.  
  133.  
  134.  
  135.  
  136. ---- LTableRowSelector ----
  137.  
  138. This subclass of LTableSelector selects entire rows.  Individual cells cannot be selected.
  139. It allows multiple selection and supports that standard shift and command key selection 
  140. extension semantics.
  141.  
  142.  
  143.  
  144.  
  145. ---- LFlexTableGeometry    ----
  146.  
  147. This subclass of LTableGeometry works in concert with an LTableHeader to compute the position
  148. of cells in a table.  All rows are of uniform height, and column positions and widths
  149. are determined by querying the associated LTableHeader view.
  150.  
  151.  
  152.  
  153. ---- Using them together    ----
  154.  
  155. The Dogbert mail window will use these classes all together.  A subclass of LTableView
  156. (CMessageTableView)  sets its geometry to LFlexTableGeometry, and its selector to
  157. LTableRowSelector.
  158.  
  159. When drawing a cell, CMessageTableView queries its associate LTableViewHeader to find the
  160. pane ID of the column's header.  The pane ID's denote which element of the row is drawn in 
  161. that cell.  For instance, a column with header 'subj' contains the message subject. This
  162. indirection allows the column order to be changed.
  163.  
  164.  
  165.  
  166.  
  167.