IP电话/视频会议

开发平台：
Visual C++

listview.h：源码内容
							/*
 * listview.h
 *
 * List View control classes.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: listview.h,v $
 * Revision 1.5  1999/03/10 03:49:52  robertj
 * More documentation adjustments.
 *
 * Revision 1.4  1999/03/09 08:01:48  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.3  1998/09/23 06:24:07  robertj
 * Added open source copyright license.
 *
 * Revision 1.2  1998/09/22 15:07:20  robertj
 * Added OnDraw functions.
 *
 * Revision 1.1  1998/09/21 13:58:48  robertj
 * Initial revision
 *
 */
#define _PLISTVIEW
#ifdef __GNUC__
#pragma interface
#endif
class PListViewControl;
/**This class is the ancestor for all elements added to the PListViewControl
   class.
 */
class PListViewItem : public PObject
{
  PCLASSINFO(PListViewItem, PObject);
  public:
   /**Get the string representation of the list view element column.
       @return
       String for column.
     */
    virtual PString GetColumn(
      PINDEX column
    ) const = 0;
};
/**A scrollable list view control for selection of a one or more of items. The
   items are PListViewItem descendents.
 */
class PListViewControl : public PControl
{
  PCLASSINFO(PListViewControl, PControl);
  public:
    /** Options on creation of the list view control. */
    enum Styles {
      /// Show headings at the top of each column.
      ShowHeadings    = 0x01,
      /// Allow the heading to be a "button" which sorts by that column when clicked.
      CanHeadingSort  = 0x02,
      /// Only allow one item to be selected at a time.
      SingleSelection = 0x04
    };
    /** Create a list view control. */
    PListViewControl(
      PInteractor * parent,     /// Interactor into which the control is placed.
      unsigned styles = ShowHeadings, /// Bits from the Styles enum.
      PINDEX columnCount = 1,         /// Number of columns in view.
      const char * const * headings = NULL /// Strings for column headings
    );
  /**@name PNotifier codes */
   /**Notification codes passed to the PNotifier function when the specified
       notification events occur.
     */
    enum {
      /// A new entry was selected or deselected.
      NewSelection = NotifyChange, 
      /// An entry was double clicked.
      DoubleClick,                 
      /// A right button click was made on an item
      RightClick                   
    };
    /**@name Overrides from class PInteractor */
   /**Set the default foreground or text colour of the interactor.
     */
    virtual void SetForegroundColour(
      const PColour & newColour  /// New background colour for interactor.
    );
   /**Set the background colour of the interactor.
     */
    virtual void SetBackgroundColour(
      const PColour & newColour  /// New background colour for interactor.
    );
    /**@name Overrides from class PControl */
   /**This function transfers the value of the control to or from the variable
       pointed to by the value pointer member variable.
     */
    virtual void TransferValue(
      int option 
     /**Transfer value option. When this is -1 when the function transfers
         the value from the value pointer into the control. This is called in
         Ref{PDialog::OnInit()} function. When option is zero then the
         function transfers the value from the control to the value pointer
         variable. This is called just before the callback function every time
         the list view value changes.
       */
    );
    /**@name New functions for class */
    /** Set flag to delete entry objects using delete operator. */
    void AllowDeleteObjects(
      BOOL yes = TRUE   /// New flag for deleting entries in list view.
    );
   /**Reset flag to delete entry objects using delete operator. This is
       equivalent to #AllowDeleteObjects(FALSE)#.
     */
    void DisallowDeleteObjects() { AllowDeleteObjects(FALSE); }
   /**Add a new entry to the end of the list view.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if a large number of entries are
       to be added to the list view in one go. The user would add the entries
       and then call the Ref{PInteractor::Invalidate()} function on the list
       view to force a redraw. This is much faster and tidier in appearance.
       @return
       the index that the entry was placed.
     */
    PINDEX AddEntry(
      PListViewItem * obj, /// New object to add to list view.
      BOOL update = TRUE   /// Flag to indicate screen should be updated.
    );
   /**Add a collection of new entries to the list view. Each element of the
       collection is added in order using the Ref{AddEntry()} function.
     */
    void AddEntries(
      const PCollection & objects, /// New objects to add to list view.
      BOOL update = TRUE          /// Flag to indicate screen should be updated.
    );
   /**Insert an entry at the specified location, ie before that entry.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if a large number of entries are
       to be added to the list view in one go. The user would add the entries
       and then call the Ref{PInteractor::Invalidate()} function on the list
       view to force a redraw. This is much faster and tidier in appearance.
     */
    void InsertEntry(
      PListViewItem * obj, /// New object to add to list view.
      PINDEX index,        /// Index position in list view to insert entry.
      BOOL update = TRUE   /// Flag to indicate screen should be updated.
    );
   /**Delete the entry from the list view. If the delete objects option was
       selected then the object added to the list view is deleted as well.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if a large number of entries are
       to be deleted to the list view in one go. The user would delete the
       entries and then call the Ref{PInteractor::Invalidate()} function on
       the list view to force a redraw. This is much faster and tidier in
       appearance.
     */
    void DeleteEntry(
      PINDEX index,       /// Index position in list view to delete entry.
      BOOL update = TRUE  /// Flag to indicate screen should be updated.
    );
   /**Delete all of the entries in the list view. If the delete objects option
       was selected then all the objects added to the list view are deleted as
       well.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if entries are to be added to the
       list view immediately after deleting then. This is much faster and tidier
       in appearance.
     */
    void DeleteAllEntries(
      BOOL update = TRUE  /// Flag to indicate screen should be updated.
    );
   /**Find the entry in the list view starting at the entry after the specified
       index. If the #index# parameter is #P_MAX_INDEX#
       then searches the whole list from the beginning.
       This uses the objects Ref{PObject::Compare()} function to test for
       equality on the objects in the list.
     */
    PINDEX FindEntry(
      const PListViewItem & obj,        /// Object value to search for.
      PINDEX startIndex = P_MAX_INDEX   /// Starting index for the search.
    ) const;
   /**Update the entry on in the list view. This is used when the
       PListViewItem descendent is changed and the internal cache of the
       column strings needs to be updated.
     */
    void UpdateEntry(
      PINDEX index,         /// Index position in list view to set entry.
      BOOL update = TRUE    /// Flag to indicate screen should be updated.
    );
   /**Set the entry at the index position. If the index is beyond the end
       of the list then simply adds the entry to the end of the list.
       
       If there was an existing entry at the index position then that entry
       is removed and if the delet objects option selected it is also deleted
       using the delete operator.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if a large number of entries are
       to be changed in the list view in one go. The user would change the
       entries and then call the Ref{PInteractor::Invalidate()} function on
       the list view to force a redraw. This is much faster and tidier in
       appearance.
     */
    void SetEntry(
      PListViewItem * obj,  /// New object to add to list view.
      PINDEX index,         /// Index position in list view to set entry.
      BOOL update = TRUE    /// Flag to indicate screen should be updated.
    );
   /**Get the entry at the index. If the index is beyond the end of the
       list then returns NULL.
       @return
       pointer to the object placed in the list view at the index.
     */
    PListViewItem * GetEntry(
      PINDEX index    /// Index into the list for the entry to retrieve.
    ) const;
   /**Get the count of the number of items in the list of entries in the
       list view.
       @return
       number of entries.
     */
    PINDEX GetCount() const;
   /**Get the index of the list view entry that is currently visible at the
       top of the list.
       @return
       index position of the list views top entry.
     */
    PINDEX GetTopIndex() const;
   /**Add a new column to the list view. The current entries of the list view
       are scanned and the column populated from the entries. If the
       #before# parameter is P_MAX_INDEX then the column is added
       to the right of all current columns.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward.
     */
    void InsertColumn(
      const PString & heading,      /// Heading text for the column
      PINDEX before = P_MAX_INDEX,  /// Index of column to insert before
      BOOL update = TRUE      /// Flag to indicate screen should be updated.
    );
   /**Delete an existing column. Note you cannot delete column zero. This
       function will assert if an attempt to do so is made. Deleting columns
       beyond the last column is silently ignored.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward.
     */
    void DeleteColumn(
      PINDEX column,      /// Index of column to delete
      BOOL update = TRUE  /// Flag to indicate screen should be updated.
    );
   /**Get the number of columns that are in the list view.
       @return
       number of columns.
     */
    PINDEX GetColumnCount();
   /**Set the heading string for the column.
     */
    void SetColumnHeading(
      PINDEX column,        /// Index of column to change
      const PString & str   /// New heading for column
    );
   /**Get the width of the column in the list view. If the column is not
       present then zero is returned.
       @return
       dimension of the column.
     */
    PDIMENSION GetColumnWidth(
      PINDEX column           /// Which column to get width
    );
   /**Set the new width of column in the list view. The first form will scan
       all entries in the column and assure the column is as wide as the
       widest string in the column. The second form set the width to the
       specified value.
    
       If the #newWidth# parameter is zero, then the column is set
       to the minimium width required to contain the longest string in the
       column.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward.
     */
    void SetColumnWidth(
      PINDEX column,           /// Which column to adjust
      PDIMENSION newWidth = 0, /// New width for the columns in the list view.
      BOOL update = TRUE       /// Flag to indicate screen should be updated.
    );
   /**Get the width of the string as used in the list view. The result may be
       used in the SetColumnWidth() function.
       @return
       dimension of the string.
     */
    PDIMENSION GetStringWidth(
      const PString & str   /// String to get the width of
    );
   /**Set the current selection to the entry specified by the index.
    
       If the multiple selection option is used then this will deselect all
       other items and only have the specified entry selected.
       If the #index# parameter is beyond the end of the list view
       then all entries are deselected.
     */
    void SetSelection(
      PINDEX index  /// Index of entry to become the single selection.
    );
   /**Get the current selection index. If the list view has the multi-select
       option this only indicates the item that has the focus.
       @return
       currently selected item or P_MAX_INDEX if nothing selected.
     */
    PINDEX GetSelection() const;
   /**Set the selection state of the list view item. If the list view is not a
       multi-select then deselects all others before selecting or deselecting
       the item specified.
       If the #update# parameter is FALSE then it is the users
       responsibility to redraw the list view, ie call
       Ref{PInteractor::Invalidate()} or Ref{PInteractor::Update()} some
       time afterward. This is typically used if a large number of entries are
       to be changed in the list view in one go. The user would change the
       entries and then call the Ref{PInteractor::Invalidate()} function on
       the list view to force a redraw. This is much faster and tidier in
       appearance.
     */
    void Select(
      PINDEX index,       /// Index position in list view to select.
      BOOL update = TRUE, /// Flag to indicate screen should be updated.
      BOOL sel = TRUE     /// State in which to set the entries selection.
    );
   /**Reset the selection state of the list view item. This is equivalent to
       #Select(index, FALSE, update)#.
       If the list view was not multi select then all entries a deselected.
     */
    void Deselect(
      PINDEX index,       /// Index position in list view to select.
      BOOL update = TRUE  /// Flag to indicate screen should be updated.
      ) { Select(index, update, FALSE); }
      /** Get the selection state of the list view item. */
    BOOL IsSelected(
      PINDEX index    /// Index of entry to check for being selected.
    ) const;
   /**Get the number of list view items that are selected. This would only be
       one or zero is the single selection option is used.
       @return
       total items selected in list view.
     */
    PINDEX GetSelCount() const;
   /**Get the current value pointer associated with the control. The variable
       pointed to by this is autamatically updated with the current value of
       the list view.
       @return
       value pointer associated with the control.
     */
    PINDEX * GetValuePointer() const { return (PINDEX *)PControl::GetValuePointer(); }
   /**Set the current value pointer associated with the control. The variable
       pointed to by this is autamatically updated with the current value of
       the list view.
     */
    void SetValuePointer(
      PINDEX * ptr  /// New value pointer to associate with the control.
      ) { PControl::SetValuePointer(ptr); }
   /**This callback is executed whenever the user clicks on a column heading.
       The default behaviour is to sort the entries by that column, provided
       that the CanHeadingSort style was used in the creation of the list view.
     */
    virtual void OnColumnClick(
      PINDEX column       /// Column that was clicked.
    );
   /**This callback is executed whenever the user clicks the right mouse
       button on an item. This allows a conext menu, for example, to be
       displayed.
       The default behaviour does nothing.
     */
    virtual void OnRightClick(
      PINDEX index         /// Index of item that was clicked.
    );
   /**This callback is executed whenever the user starts to drag an item in
       list view.
       The default behaviour does nothing.
     */
    virtual void OnBeginDrag(
      BOOL rightButton,     /// The drag was begun using the right button.
      PINDEX index         /// Index of item that was dragged.
    );
   /**Thus callback is executed before draw operation on the contents of the
       list view. If the #completed# flag is FALSE then you have
       the opportunity to alter the canvas before the control is cleared. When
       this flag is TRUE, the drawing has completed and you have the chance to
       draw things over the top of already drawn items.
       Note that the return value is only examined on the first call, when the
       #completed# flag is FALSE. Also no furter calls to
       OnDrawControl() or OnDrawEntry() are made if FALSE is returned.
       The default behaviour simply returns FALSE.
       @return
       TRUE if custom drawing of each entry is required.
     */
    virtual BOOL OnDrawControl(
      PCanvas & canvas,   /// Canvas in which to draw the object entry.
      BOOL completed      /// Indication that the drawing has completed.
    );
   /**The system calls this whenever an object in the list needs to be
       redrawn. The redraw is optional depending on the return value. The
       function may simply alter the drawing characteristics of the canvas,
       e.g. font, and return FALSE.
       If the #column# field is P_MAX_INDEX, then the function is
       being called before the draw of any of the columns.
       The default behaviour simply returns FALSE.
       @return
       TRUE if drawn locally, FALSE is control is to continue drawing entry.
     */
    virtual BOOL OnDrawEntry(
      PINDEX index,       /// Index of entry to draw in the list view.
      PINDEX column,      /// Index of column to draw in the list view.
      PListViewItem & obj,// Object to draw for this entry in the list view.
      PCanvas & canvas,   /// Canvas in which to draw the object entry.
      unsigned flags      /// Flags indicating is selected or has focus, etc.
    );
  protected:
    /** Values from the Styles enum for the creation of the list view. */
    unsigned defaultStyles;
    /** Number of columns in list view. */
    PINDEX numColumns;
    /** Flag to indicate objects placed in list should be deleted when removed. */
    BOOL deleteObjects;
  private:
    // New functions for class
    void Construct();
      // Common constructor code
#ifdef DOC_PLUS_PLUS
};
#endif
// Class declaration continued in platform specific header file ///////////////

						