qlistbox.cpp

qtopia-phone-2.2.0下公共的控件实现源代码。

/*!
  Returns the height of the pixmap.

  \sa paint(), width()
*/

int QListBoxPixmap::height( const QListBox* lb ) const
{
    int h;
    if ( text().isEmpty() )
	h = pm.height();
    else
	h = QMAX( pm.height(), lb->fontMetrics().lineSpacing() + 2 );
    return QMAX( h, QApplication::globalStrut().height() );
}

/*!
  Returns the width of the pixmap, plus some margin.

  \sa paint(), height()
*/

int QListBoxPixmap::width( const QListBox* lb ) const
{
    if ( text().isEmpty() )
	return QMAX( pm.width() + 6, QApplication::globalStrut().width() );
    return QMAX( pm.width() + lb->fontMetrics().width( text() ) + 6,
	    QApplication::globalStrut().width() );
}


/*!
  \class QListBox qlistbox.h
  \brief The QListBox widget provides a list of selectable, read-only items.

  \ingroup advanced

  This is typically a single-column list where zero or one items
  are selected at once, but can also be used in many other ways.

  QListBox will add scroll bars as necessary, but isn't intended for
  \e really big lists.	If you want more than a few thousand items,
  it's probably better to use a different widget, chiefly because the
  scroll bars won't provide very good navigation, but also because
  QListBox may become slow at larger sizes.

  There is a variety of selection modes, described in the
  QListBox::SelectionMode documentation. The default is
  single-selection, and you can change it using setSelectionMode().
  For compatibility with previous Qt versions there is still the
  setMultiSelection() methode. Calling setMultiSelection( TRUE )
  is equivalent to setSelectionMode( Multi ), and setMultiSelection( FALSE )
  is equivalent to setSelectionMode( Single ). It's suggested not to
  use setMultiSelection() anymore, but to use setSelectionMode()
  instead.

  Since QListBox offers multiple selection it has to display keyboard
  focus and selection state separately.  Therefore there are functions
  both to set the selection state of an item, setSelected(), and to
  select which item displays keyboard focus, setCurrentItem().

  The list box normally arranges its items in a single column with a
  vertical scroll bar if necessary, but it is also possible to have a
  different fixed number of columns (setColumnMode()), or as many
  columns as will fit in the list box' assigned screen space
  (setColumnMode( FitToWidth )), or to have a fixed number of rows
  (setRowMode()), or as many rows as will fit in the list box'
  assigned screen space (setRowMode( FitToHeight )).  In all these
  cases, QListBox will add scroll bars as appropriate in at least one
  direction.

  If multiple rows is used, each row can be as high as necessary (the
  normal setting), or you can request that all items will have the
  same height by calling setVariableHeight( FALSE ).  Of course there
  is a similar setVariableWidth().

  The items discussed are QListBoxItem objects. QListBox provides
  methods to insert new items as a string, as pixmaps, and as
  QListBoxItem * (insertItem() with various arguments), and to replace
  an existing item with a new string, pixmap or QListBoxItem
  (changeItem() with various arguments).  You can also remove items
  (surprise: removeItem()) and clear() the entire list box.  Note that
  if you create a QListBoxItem yourself and insert it, it becomes the
  property of QListBox and you may not delete it.  (QListBox will
  delete it when appropriate.)

  You can also create a QListBoxItem such as QListBoxText or
  QListBoxPixmap with the list box as first parameter. The item will
  then append itself. When you delete an item, it is automatically
  removed from the listbox.

  The list of items can be arbitrarily big; if necessary, QListBox
  adds scroll bars.  It can be single-column (as most list boxes are)
  or multi-column, and offers both single and multiple selection.
  (QListBox does however not support multiple-column items; QListView
  does that job.)
  Also a listbox can display items arranged in a tree. But this is
  quite limited, and if you really want to display and work with
  a tree, you should use a QListView. The tree stuff in the QListBox
  is only supported because it磗 needed in comboboxes.

  The list box items can be accessed both as QListBoxItem objects
  (recommended) and using integer indexes (the original QListBox
  implementation used an array of strings internally, and the API
  still supports this mode of operation).  Everything can be done
  using the new objects; most things can be done using the indexes too
  but unfortunately not everything.

  Each item in a QListBox contains a QListBoxItem.  One of the items
  can be the current item.  The highlighted() signal is emitted when
  a new item gets highlighted, e.g. because the user clicks on it or
  QListBox::setCurrentItem() is called. The selected() signal is emitted
  when the user double-clicks on an item or presses return when an item is
  highlighted.

  If the user does not select anything, no signals are emitted and
  currentItem() returns -1.

  A list box has \c WheelFocus as a default focusPolicy(), i.e. it can
  get keyboard focus both by tabbing, clicking and the mouse wheel.

  New items may be inserted using either insertItem(), insertStrList()
  or insertStringList(). inSort() is obsolete, as this method is quite
  inefficient.  It's preferable to insert the items normally and call
  sort() afterwards, or insert a sorted QStringList().

  By default, vertical and horizontal scroll bars are added and
  removed as necessary. setHScrollBarMode() and setVScrollBarMode()
  can be used to change this policy.

  If you need to insert other types than texts and pixmaps, you must
  define new classes which inherit QListBoxItem.

  \warning The list box assumes ownership of all list box items
  and will delete them when it does not need them any more.

  <img src=qlistbox-m.png> <img src=qlistbox-w.png>

  \sa QListView QComboBox QButtonGroup
  <a href="guibooks.html#fowler">GUI Design Handbook: List Box (two
  sections)</a>
*/

/*! \enum QListBox::SelectionMode

  This enumerated type is used by QListBox to indicate how it reacts
  to selection by the user.  It has four values: <ul>

  <li> \c Single - When the user selects an item, any already-selected
  item becomes unselected, and the user cannot unselect the selected
  item. This means that the user can never clear the selection, even
  though the selection may be cleared by the application programmer
  using QListBox::clearSelection().

  <li> \c Multi - When the user selects an item in the most ordinary
  way, the selection status of that item is toggled and the other
  items are left alone.

  <li> \c Extended - When the user selects an item in the most
  ordinary way, the selection is cleared and the new item selected.
  However, if the user presses the CTRL key when clicking on an item,
  the clicked item gets toggled and all other items are left untouched. And
  if the user presses the SHIFT key while clicking on an item, all items
  between the current item and the clicked item get selected or unselected
  depending on the state of the clicked item.
  Also multiple items can be selected by dragging the mouse while the
  left mouse button stayes pressed.

  <li> \c NoSelection - Items cannot be selected.

  </ul>

  In other words, \c Single is a real single-selection list box, \c
  Multi a real multi-selection list box, and \c Extended list box
  where users can select multiple items but usually want to select
  either just one or a range of contiguous items, and \c NoSelection
  is for a list box where the user can look but not touch.
*/


/*! \enum QListBox::LayoutMode

  This enum type decides how QListBox lays out its rows and columns.
  The two modes interact, of course.

  The possible values for each mode are: <ul>

  <li> \c FixedNumber - there is a fixed number of rows (or columns).

  <li> \c FitToHeight - there are as many rows as will fit on-screen.
  (Ditto with \c FitToWidth and columns.)

  <li> \c Variable - there are as many rows as are required by the
  column mode.  (Or as many columns as required by the row mode.)

  </ul>

  Example: When you call setRowMode( FitToHeight ), columnMode()
  automatically becomes \c Variable to accomodate the row mode you've
  set.
*/

/*! \fn void  QListBox::onItem( QListBoxItem *i )
  This signal is emitted, when the user moves the mouse cursor onto an item.
  It磗 only emitted once per item.
*/

/*! \fn void  QListBox::onViewport()
  This signal is emitted, when the user moves the mouse cursor, which was
  on an item away from the item onto the viewport.
*/


/*!
  Constructs a new empty list box, with \a parent as a parent and \a name
  as object name.

  Performance is boosted by modifying the widget flags \a f so that only
  part of the QListBoxItem children is redrawn.  This may be unsuitable
  for custom QListBoxItem classes, in which case \c WNorthWestGravity and
  \c WRepaintNoErase should be cleared.

  \sa QWidget::clearWFlags() Qt::WidgetFlags
*/

QListBox::QListBox( QWidget *parent, const char *name, WFlags f )
    : QScrollView( parent, name, f | WNorthWestGravity | WRepaintNoErase )
{
    d = new QListBoxPrivate( this );
    d->updateTimer = new QTimer( this, "listbox update timer" );
    d->visibleTimer = new QTimer( this, "listbox visible timer" );
    d->inputTimer = new QTimer( this, "listbox input timer" );
    d->resizeTimer = new QTimer( this, "listbox resize timer" );
    d->clearing = FALSE;
    d->pressedItem = 0;
    d->selectAnchor = 0;
    d->select = FALSE;
    d->rubber = 0;
    d->selectable.setAutoDelete( TRUE );

    setMouseTracking( TRUE );
    viewport()->setMouseTracking( TRUE );

    connect( d->updateTimer, SIGNAL(timeout()),
	     this, SLOT(refreshSlot()) );
    connect( d->visibleTimer, SIGNAL(timeout()),
	     this, SLOT(ensureCurrentVisible()) );
    connect( d->inputTimer, SIGNAL( timeout() ),
	     this, SLOT( clearInputString() ) );
    connect( d->resizeTimer, SIGNAL( timeout() ),
	     this, SLOT( adjustItems() ) );
    viewport()->setBackgroundMode( PaletteBase );
    viewport()->setFocusProxy( this );
    viewport()->setFocusPolicy( WheelFocus );
}


QListBox * QListBox::changedListBox = 0;

/*!
  Destroys the list box.  Deletes all list box items.
*/

QListBox::~QListBox()
{
    if ( changedListBox == this )
	changedListBox = 0;
    clear();
    delete d;
    d = 0;
}

/*! \fn void QListBox::pressed( QListBoxItem *item )

  This signal is emitted whenever the user presses the mouse button
  on a listbox.
  \a item is the pointer to the listbox item onto which the user pressed the
  mouse button or NULL, if the user didn't press the mouse on an item.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*! \fn void QListBox::pressed( QListBoxItem *item, const QPoint &pnt )

  This signal is emitted whenever the user presses the mouse button
  on a listbox.
  \a item is the pointer to the listbox item onto which the user pressed the
  mouse button or NULL, if the user didn't press the mouse on an item.
  \a pnt is the position of the mouse cursor where the mouse cursor was
  when the user pressed the mouse button.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*! \fn void QListBox::clicked( QListBoxItem *item )

  This signal is emitted whenever the user clicks (mouse pressed + mouse released)
  into the listbox.
  \a item is the pointer to the clicked listbox item or NULL, if the user didn't click on an item.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*! \fn void QListBox::clicked( QListBoxItem *item, const QPoint &pnt )

  This signal is emitted whenever the user clicks (mouse pressed + mouse released)
  into the listbox.
  \a item is the pointer to the clicked listbox item or NULL, if the user didn't click on an item.
  \a pnt is the position where the user has clicked.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*!
  \fn void QListBox::mouseButtonClicked (int button, QListBoxItem * item, const QPoint & pos)

  This signal is emitted whenever the user clicks (mouse pressed + mouse released)
  into the listbox.
  \a button is the mouse button, which the user pressed.
  \a item is the pointer to the clicked listbox item or NULL, if the user didn't click on an item.
  \a pos is the position where the user has clicked.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*!
  \fn void QListBox::mouseButtonPressed (int button, QListBoxItem * item, const QPoint & pos)

  This signal is emitted whenever the user presses the mouse button
  on a listbox.
  \a button is the mouse button, which the user pressed.
  \a item is the pointer to the listbox item onto which the user pressed the
  mouse button or NULL, if the user didn't press the mouse on an item.
  \a pos is the position of the mouse cursor where the mouse cursor was
  when the user pressed the mouse button.

  Note that you may not delete any QListBoxItem objects in slots
  connected to this signal.
*/

/*! \fn void QListBox::doubleClicked( QListBoxItem *item )

  This signal is emitted whenever an item is double-clicked.  It's
  emitted on the second button press, not the second button release.
  \a item is the listbox item onto which the user did the double click.
*/


/*! \fn void QListBox::returnPressed( QListBoxItem * )

  This signal is emitted when enter or return is pressed.  The
  argument is currentItem().
*/

/*! \fn void QListBox::rightButtonClicked( QListBoxItem *, const QPoint& )

  This signal is emitted when the right button is clicked (ie. when
  it's released).  The arguments are the relevant QListBoxItem (may
  be 0) and the point in global coordinates.
*/


/*! \fn void QListBox::rightButtonPressed (QListBoxItem *, const QPoint & )

  This signal is emitted when the right button is pressed.  Then
  arguments are the relevant QListBoxItem (may be 0) and the point in
  global coordinates.
*/

/*!
  \fn void QListBox::selectionChanged()

  This signal is emitted when the selection set of a
  listbox changes. This signal is emitted in each selection mode
  If the user selects five items by drag-selecting,
  QListBox tries to emit just one selectionChanged() signal, so the
  signal can be connected to computationally expensive slots.

  \sa selected() currentItem()
*/

/*!
  \fn void QListBox::selectionChanged( QListBoxItem *item )

  This signal is emitted when the selection in a single-selection
  listbox changes. \a item is the new selected listbox item.

  \sa selected() currentItem()
*/

/*! \fn void QListBox::currentChanged( QListBoxItem *item )

  This signal is emitted when the user highlights a new current item.
  The argument is the index of the new item, which is already current.

  \sa setCurrentItem() currentItem()
*/

/*! \fn void QListBox::highlighted( int index )

  This signal is emitted when the user highlights a new current item.
  The argument is the index of the new item, which is already current.

  \sa selected() currentItem() selectionChanged()
*/

/*! \fn void QListBox::highlighted( QListBoxItem * )

  This signal is emitted when the user highlights a new current item.
  The argument is a pointer to the new current item.

  \sa selected() currentItem() selectionChanged()
*/

/*! \fn void QListBox::highlighted( const QString &)

  This signal is emitted when the user highlights a new current item
  and the new item is a string.	 The argument is the text of the
  new current item.

  \sa selected() currentItem() selectionChanged()
*/

/*! \fn void QListBox::selected( int index )

  This signal is emitted when the user double-clicks on an item or
  presses return when an item is highlighted.  The argument is the
  index of the selected item.

  \sa highlighted() selectionChanged()
*/

/*! \fn void QListBox::selected( QListBoxItem * )

  This signal is emitted when the user double-clicks on an item or
  presses return when an item is highlighted.  The argument is a
  pointer to the new selected item.

  \sa highlighted() selectionChanged()
*/

/*! \fn void QListBox::selected( const QString &)

  This signal is emitted when the user double-clicks on an item or
  presses return while an item is highlighted, and the selected item
  is (or has) a string.	 The argument is the text of the selected
  item.

  \sa highlighted() selectionChanged()
*/

/*! \reimp */

void QListBox::setFont( const QFont &font )
{
    d->sizeHint = QSize();  // Invalidate Size Hint
    QScrollView::setFont( font );
    triggerUpdate( TRUE );
}


/*! Returns the number of items in the list box. */

uint QListBox::count() const
{
    return d->count;
}


/*!
  Inserts the string list \a list into the list at item \a index.

  If \a index is negative, \a list is inserted at the end of the list.	If
  \a index is too large, the operation is ignored.

  \warning This function uses <code>const char *</code> rather than
  QString, so we recommend against using it.  It is provided so that
  legacy code will continue to work, and so that programs that
  certainly will not need to handle code outside a single 8-bit locale
  can use it.  See insertStringList() - it uses real QStrings.

  \warning This function is never significantly faster than a loop
  around insertItem().

  \sa insertItem(), insertStringList()
*/

void QListBox::insertStrList( const QStrList *list, int index )
{
    if ( !list ) {
#if defined(CHECK_NULL)
	ASSERT( list != 0 );
#endif
	return;
    }
    insertStrList( *list, index );
}



/*!
  Inserts the string list \a list into the list at item \a index.

  If \a index is negative, \a list is inserted at the end of the list.	If
  \a index is too large, the operation is ignored.

  \warning This function is never significantly faster than a loop
  around insertItem().

  \sa insertItem(), insertStrList()
*/

void QListBox::insertStringList( const QStringList & list, int index )
{
    if ( index < 0 )
	index = count();