qtooltip.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QToolTip 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QToolTip \- Tool tips (balloon help) for any widget or rectangular part of a widget
.SH SYNOPSIS
\fC#include <qtooltip.h>\fR
.PP
Inherits Qt.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQToolTip\fR ( QWidget * widget, QToolTipGroup * group = 0 )"
.br
.ti -1c
.BI "QWidget * \fBparentWidget\fR () const"
.br
.ti -1c
.BI "QToolTipGroup * \fBgroup\fR () const"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "void \fBadd\fR ( QWidget * widget, const QString & text )"
.br
.ti -1c
.BI "void \fBadd\fR ( QWidget * widget, const QString & text, QToolTipGroup * group, const QString & longText )"
.br
.ti -1c
.BI "void \fBremove\fR ( QWidget * widget )"
.br
.ti -1c
.BI "void \fBadd\fR ( QWidget * widget, const QRect & rect, const QString & text )"
.br
.ti -1c
.BI "void \fBadd\fR ( QWidget * widget, const QRect & rect, const QString & text, QToolTipGroup * group, const QString & groupText )"
.br
.ti -1c
.BI "void \fBremove\fR ( QWidget * widget, const QRect & rect )"
.br
.ti -1c
.BI "QString \fBtextFor\fR ( QWidget * widget, const QPoint & pos = QPoint ( ) )"
.br
.ti -1c
.BI "void \fBhide\fR ()"
.br
.ti -1c
.BI "QFont \fBfont\fR ()"
.br
.ti -1c
.BI "void \fBsetFont\fR ( const QFont & font )"
.br
.ti -1c
.BI "QPalette \fBpalette\fR ()"
.br
.ti -1c
.BI "void \fBsetPalette\fR ( const QPalette & palette )"
.br
.ti -1c
.BI "void setEnabled ( bool enable )  \fI(obsolete)\fR"
.br
.ti -1c
.BI "bool enabled ()  \fI(obsolete)\fR"
.br
.ti -1c
.BI "void \fBsetGloballyEnabled\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBisGloballyEnabled\fR ()"
.br
.ti -1c
.BI "void \fBsetWakeUpDelay\fR ( int i )"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBmaybeTip\fR ( const QPoint & p ) = 0"
.br
.ti -1c
.BI "void \fBtip\fR ( const QRect & rect, const QString & text )"
.br
.ti -1c
.BI "void \fBtip\fR ( const QRect & rect, const QString & text, const QString & groupText )"
.br
.ti -1c
.BI "void \fBtip\fR ( const QRect & rect, const QString & text, const QRect & geometry )"
.br
.ti -1c
.BI "void \fBtip\fR ( const QRect & rect, const QString & text, const QString & groupText, const QRect & geometry )"
.br
.ti -1c
.BI "void \fBclear\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QToolTip class provides tool tips (balloon help) for any widget or rectangular part of a widget.
.PP
The tip is a short, single line of text reminding the user of the widget's or rectangle's function. It is drawn immediately below the region in a distinctive black-on-yellow combination.
.PP
QToolTipGroup provides a way for tool tips to display another text elsewhere (most often in a status bar).
.PP
At any point in time, QToolTip is either dormant or active. In dormant mode the tips are not shown and in active mode they are. The mode is global, not particular to any one widget.
.PP
QToolTip switches from dormant to active mode when the user hovers the mouse on a tip-equipped region for a second or so and remains active until the user either clicks a mouse button, presses a key, lets the mouse hover for five seconds or moves the mouse outside \fIall\fR tip-equipped regions for at least a second.
.PP
The QToolTip class can be used in three different ways: <ol type=1>
.IP 1
Adding a tip to an entire widget.
.IP 2
Adding a tip to a fixed rectangle within a widget.
.IP 3
Adding a tip to a dynamic rectangle within a widget.
.PP
To add a tip to a widget, call the \fIstatic\fR function QToolTip::add() with the widget and tip as arguments:
.PP
.nf
.br
        QToolTip::add( quitButton, "Leave the application" );
.br
.fi
.PP
This is the simplest and most common use of QToolTip. The tip will be deleted automatically when \fIquitButton\fR is deleted, but you can remove it yourself, too:
.PP
.nf
.br
        QToolTip::remove( quitButton );
.br
.fi
.PP
You can also display another text (typically in a status bar), courtesy of QToolTipGroup. This example assumes that \fIgrp\fR is a \fCQToolTipGroup *\fR and is already connected to the appropriate status bar:
.PP
.nf
.br
        QToolTip::add( quitButton, "Leave the application", grp,
.br
                       "Leave the application, prompting to save if necessary" );
.br
        QToolTip::add( closeButton, "Close this window", grp,
.br
                       "Close this window, prompting to save if necessary" );
.br
.fi
.PP
To add a tip to a fixed rectangle within a widget, call the static function QToolTip::add() with the widget, rectangle and tip as arguments. (See the tooltip/tooltip.cpp example.) Again, you can supply a \fCQToolTipGroup *\fR and another text if you want.
.PP
Both of these are one-liners and cover the majority of cases. The third and most general way to use QToolTip requires you to reimplement a pure virtual function to decide whether to pop up a tool tip. The tooltip/tooltip.cpp example demonstrates this too. This mode can be used to implement tips for text that can move as the user scrolls, for example.
.PP
To use QToolTip like this, you must subclass QToolTip and reimplement maybeTip(). QToolTip calls maybeTip() when a tip should pop up, and maybeTip() decides whether to show a tip.
.PP
Tool tips can be globally disabled using QToolTip::setGloballyEnabled() or disabled in groups with QToolTipGroup::setEnabled().
.PP
You can retrieve the text of a tooltip for a given position within a widget using textFor().
.PP
The global tooltip font and palette can be set with the static setFont() and setPalette() functions respectively.
.PP
See also QStatusBar, QWhatsThis, QToolTipGroup, GUI Design Handbook: Tool Tip, and Help System.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QToolTip::QToolTip ( QWidget * widget, QToolTipGroup * group = 0 )"
Constructs a tool tip object. This is only necessary if you need tool tips on regions that can move within the widget (most often because the widget's contents can scroll).
.PP
\fIwidget\fR is the widget you want to add dynamic tool tips to and \fIgroup\fR (optional) is the tool tip group they should belong to.