You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
355 lines
16 KiB
355 lines
16 KiB
'\" t
|
|
.TH TQToolTip 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
|
|
.\" Copyright 1992-2007 Trolltech ASA. All rights reserved. See the
|
|
.\" license file included in the distribution for a complete license
|
|
.\" statement.
|
|
.\"
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
TQToolTip \- Tool tips (balloon help) for any widget or rectangular part of a widget
|
|
.SH SYNOPSIS
|
|
\fC#include <tqtooltip.h>\fR
|
|
.PP
|
|
Inherits Qt.
|
|
.PP
|
|
.SS "Public Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "\fBTQToolTip\fR ( TQWidget * widget, TQToolTipGroup * group = 0 )"
|
|
.br
|
|
.ti -1c
|
|
.BI "TQWidget * \fBparentWidget\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "TQToolTipGroup * \fBgroup\fR () const"
|
|
.br
|
|
.in -1c
|
|
.SS "Static Public Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "void \fBadd\fR ( TQWidget * widget, const TQString & text )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBadd\fR ( TQWidget * widget, const TQString & text, TQToolTipGroup * group, const TQString & longText )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBremove\fR ( TQWidget * widget )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBadd\fR ( TQWidget * widget, const TQRect & rect, const TQString & text )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBadd\fR ( TQWidget * widget, const TQRect & rect, const TQString & text, TQToolTipGroup * group, const TQString & groupText )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBremove\fR ( TQWidget * widget, const TQRect & rect )"
|
|
.br
|
|
.ti -1c
|
|
.BI "TQString \fBtextFor\fR ( TQWidget * widget, const TQPoint & pos = TQPoint ( ) )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBhide\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "TQFont \fBfont\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBsetFont\fR ( const TQFont & font )"
|
|
.br
|
|
.ti -1c
|
|
.BI "TQPalette \fBpalette\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBsetPalette\fR ( const TQPalette & 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 TQPoint & p ) = 0"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBtip\fR ( const TQRect & rect, const TQString & text )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBtip\fR ( const TQRect & rect, const TQString & text, const TQString & groupText )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBtip\fR ( const TQRect & rect, const TQString & text, const TQRect & geometry )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBtip\fR ( const TQRect & rect, const TQString & text, const TQString & groupText, const TQRect & geometry )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBclear\fR ()"
|
|
.br
|
|
.in -1c
|
|
.SH DESCRIPTION
|
|
The TQToolTip 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
|
|
The tip can be any Rich-Text formatted string.
|
|
.PP
|
|
TQToolTipGroup provides a way for tool tips to display another text elsewhere (most often in a status bar).
|
|
.PP
|
|
At any point in time, TQToolTip 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
|
|
TQToolTip 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 TQToolTip 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 TQToolTip::add() with the widget and tip as arguments:
|
|
.PP
|
|
.nf
|
|
.br
|
|
TQToolTip::add( quitButton, "Leave the application" );
|
|
.br
|
|
.fi
|
|
.PP
|
|
This is the simplest and most common use of TQToolTip. The tip will be deleted automatically when \fIquitButton\fR is deleted, but you can remove it yourself, too:
|
|
.PP
|
|
.nf
|
|
.br
|
|
TQToolTip::remove( quitButton );
|
|
.br
|
|
.fi
|
|
.PP
|
|
You can also display another text (typically in a status bar), courtesy of TQToolTipGroup. This example assumes that \fIgrp\fR is a \fCTQToolTipGroup *\fR and is already connected to the appropriate status bar:
|
|
.PP
|
|
.nf
|
|
.br
|
|
TQToolTip::add( quitButton, "Leave the application", grp,
|
|
.br
|
|
"Leave the application, prompting to save if necessary" );
|
|
.br
|
|
TQToolTip::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 TQToolTip::add() with the widget, rectangle and tip as arguments. (See the tooltip/tooltip.cpp example.) Again, you can supply a \fCTQToolTipGroup *\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 TQToolTip 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 TQToolTip like this, you must subclass TQToolTip and reimplement maybeTip(). TQToolTip calls maybeTip() when a tip should pop up, and maybeTip() decides whether to show a tip.
|
|
.PP
|
|
Tool tips can be globally disabled using TQToolTip::setGloballyEnabled() or disabled in groups with TQToolTipGroup::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 TQStatusBar, TQWhatsThis, TQToolTipGroup, GUI Design Handbook: Tool Tip, and Help System.
|
|
.SH MEMBER FUNCTION DOCUMENTATION
|
|
.SH "TQToolTip::TQToolTip ( TQWidget * widget, TQToolTipGroup * 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.
|
|
.PP
|
|
\fBWarning:\fR TQToolTip is not a subclass of TQObject, so the instance of TQToolTip is not deleted when \fIwidget\fR is deleted.
|
|
.PP
|
|
\fBWarning:\fR If you delete the tool tip before you have deleted \fIwidget\fR then you need to make sure you call remove() yourself from \fIwidget\fR in your reimplemented TQToolTip destructor.
|
|
.PP
|
|
.nf
|
|
.br
|
|
MyToolTip::~MyToolTip()
|
|
.br
|
|
{
|
|
.br
|
|
remove( widget );
|
|
.br
|
|
}
|
|
.br
|
|
.fi
|
|
.PP
|
|
See also maybeTip().
|
|
.SH "void TQToolTip::add ( TQWidget * widget, const TQString & text )\fC [static]\fR"
|
|
Adds a tool tip to \fIwidget\fR. \fItext\fR is the text to be shown in the tool tip.
|
|
.PP
|
|
This is the most common entry point to the TQToolTip class; it is suitable for adding tool tips to buttons, checkboxes, comboboxes and so on.
|
|
.PP
|
|
Examples:
|
|
.)l helpsystem/mainwindow.cpp, tqdir/tqdir.cpp, scribble/scribble.cpp, and tooltip/tooltip.cpp.
|
|
.SH "void TQToolTip::add ( TQWidget * widget, const TQString & text, TQToolTipGroup * group, const TQString & longText )\fC [static]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Adds a tool tip to \fIwidget\fR and to tool tip group \fIgroup\fR.
|
|
.PP
|
|
\fItext\fR is the text shown in the tool tip and \fIlongText\fR is the text emitted from \fIgroup\fR.
|
|
.PP
|
|
Normally, \fIlongText\fR is shown in a status bar or similar.
|
|
.SH "void TQToolTip::add ( TQWidget * widget, const TQRect & rect, const TQString & text )\fC [static]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Adds a tool tip to a fixed rectangle, \fIrect\fR, within \fIwidget\fR. \fItext\fR is the text shown in the tool tip.
|
|
.SH "void TQToolTip::add ( TQWidget * widget, const TQRect & rect, const TQString & text, TQToolTipGroup * group, const TQString & groupText )\fC [static]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Adds a tool tip to an entire \fIwidget\fR and to tool tip group \fIgroup\fR. The tooltip will disappear when the mouse leaves the \fIrect\fR.
|
|
.PP
|
|
\fItext\fR is the text shown in the tool tip and \fIgroupText\fR is the text emitted from \fIgroup\fR.
|
|
.PP
|
|
Normally, \fIgroupText\fR is shown in a status bar or similar.
|
|
.SH "void TQToolTip::clear ()\fC [protected]\fR"
|
|
Immediately removes all tool tips for this tooltip's parent widget.
|
|
.SH "bool TQToolTip::enabled ()\fC [static]\fR"
|
|
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
|
|
.SH "TQFont TQToolTip::font ()\fC [static]\fR"
|
|
Returns the font common to all tool tips.
|
|
.PP
|
|
See also setFont().
|
|
.SH "TQToolTipGroup * TQToolTip::group () const"
|
|
Returns the tool tip group this TQToolTip is a member of or 0 if it isn't a member of any group.
|
|
.PP
|
|
The tool tip group is the object responsible for maintaining contact between tool tips and a status bar or something else which can show the longer help text.
|
|
.PP
|
|
See also parentWidget() and TQToolTipGroup.
|
|
.SH "void TQToolTip::hide ()\fC [static]\fR"
|
|
Hides any tip that is currently being shown.
|
|
.PP
|
|
Normally, there is no need to call this function; TQToolTip takes care of showing and hiding the tips as the user moves the mouse.
|
|
.SH "bool TQToolTip::isGloballyEnabled ()\fC [static]\fR"
|
|
Returns whether tool tips are enabled globally.
|
|
.PP
|
|
See also setGloballyEnabled().
|
|
.SH "void TQToolTip::maybeTip ( const TQPoint & p )\fC [pure virtual protected]\fR"
|
|
This pure virtual function is half of the most versatile interface TQToolTip offers.
|
|
.PP
|
|
It is called when there is a possibility that a tool tip should be shown and must decide whether there is a tool tip for the point \fIp\fR in the widget that this TQToolTip object relates to. If so, maybeTip() must call tip() with the rectangle the tip applies to, the tip's text and optionally the TQToolTipGroup details and the geometry in screen coordinates.
|
|
.PP
|
|
\fIp\fR is given in that widget's local coordinates. Most maybeTip() implementations will be of the form:
|
|
.PP
|
|
.nf
|
|
.br
|
|
if ( <something> ) {
|
|
.br
|
|
tip( <something>, <something> );
|
|
.br
|
|
}
|
|
.br
|
|
.fi
|
|
.PP
|
|
The first argument to tip() (a rectangle) must encompass \fIp\fR, i.e. the tip must apply to the current mouse position; otherwise TQToolTip's operation is undefined.
|
|
.PP
|
|
Note that the tip will disappear once the mouse moves outside the rectangle you give to tip(), and will not reappear if the mouse moves back in: maybeTip() is called again instead.
|
|
.PP
|
|
See also tip().
|
|
.PP
|
|
Examples:
|
|
.)l helpsystem/tooltip.cpp and tooltip/tooltip.cpp.
|
|
.SH "TQPalette TQToolTip::palette ()\fC [static]\fR"
|
|
Returns the palette common to all tool tips.
|
|
.PP
|
|
See also setPalette().
|
|
.SH "TQWidget * TQToolTip::parentWidget () const"
|
|
Returns the widget this TQToolTip applies to.
|
|
.PP
|
|
The tool tip is destroyed automatically when the parent widget is destroyed.
|
|
.PP
|
|
See also group().
|
|
.SH "void TQToolTip::remove ( TQWidget * widget )\fC [static]\fR"
|
|
Removes the tool tip from \fIwidget\fR.
|
|
.PP
|
|
If there is more than one tool tip on \fIwidget\fR, only the one covering the entire widget is removed.
|
|
.SH "void TQToolTip::remove ( TQWidget * widget, const TQRect & rect )\fC [static]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Removes any tool tip for \fIrect\fR from \fIwidget\fR.
|
|
.PP
|
|
If there is more than one tool tip on \fIwidget\fR, only the one covering rectangle \fIrect\fR is removed.
|
|
.SH "void TQToolTip::setEnabled ( bool enable )\fC [static]\fR"
|
|
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
|
|
.SH "void TQToolTip::setFont ( const TQFont & font )\fC [static]\fR"
|
|
Sets the font for all tool tips to \fIfont\fR.
|
|
.PP
|
|
See also font().
|
|
.SH "void TQToolTip::setGloballyEnabled ( bool enable )\fC [static]\fR"
|
|
If \fIenable\fR is TRUE sets all tool tips to be enabled (shown when needed); if \fIenable\fR is FALSE sets all tool tips to be disabled (never shown).
|
|
.PP
|
|
By default, tool tips are enabled. Note that this function affects all tool tips in the entire application.
|
|
.PP
|
|
See also TQToolTipGroup::enabled.
|
|
.SH "void TQToolTip::setPalette ( const TQPalette & palette )\fC [static]\fR"
|
|
Sets the palette for all tool tips to \fIpalette\fR.
|
|
.PP
|
|
See also palette().
|
|
.SH "void TQToolTip::setWakeUpDelay ( int i )\fC [static]\fR"
|
|
Sets the wakeup delay for all tooltips to \fIi\fR milliseconds.
|
|
.SH "TQString TQToolTip::textFor ( TQWidget * widget, const TQPoint & pos = TQPoint ( ) )\fC [static]\fR"
|
|
Returns the tool tip text for \fIwidget\fR at position \fIpos\fR, or TQString::null if there is no tool tip for the given widget and position.
|
|
.SH "void TQToolTip::tip ( const TQRect & rect, const TQString & text )\fC [protected]\fR"
|
|
Immediately pops up a tip saying \fItext\fR and removes the tip once the cursor moves out of rectangle \fIrect\fR (which is given in the coordinate system of the widget this TQToolTip relates to).
|
|
.PP
|
|
The tip will not reappear if the cursor moves back; your maybeTip() must reinstate it each time.
|
|
.SH "void TQToolTip::tip ( const TQRect & rect, const TQString & text, const TQString & groupText )\fC [protected]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Immediately pops up a tip saying \fItext\fR and removes that tip once the cursor moves out of rectangle \fIrect\fR (which is given in the coordinate system of the widget this TQToolTip relates to). \fIgroupText\fR is the text emitted from the group.
|
|
.PP
|
|
The tip will not reappear if the cursor moves back; your maybeTip() must reinstate it each time.
|
|
.SH "void TQToolTip::tip ( const TQRect & rect, const TQString & text, const TQRect & geometry )\fC [protected]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Immediately pops up a tip within the rectangle \fIgeometry\fR, saying \fItext\fR and removes the tip once the cursor moves out of rectangle \fIrect\fR. Both rectangles are given in the coordinate system of the widget this TQToolTip relates to.
|
|
.PP
|
|
The tip will not reappear if the cursor moves back; your maybeTip() must reinstate it each time.
|
|
.PP
|
|
If the tip does not fit inside \fIgeometry\fR, the tip expands.
|
|
.SH "void TQToolTip::tip ( const TQRect & rect, const TQString & text, const TQString & groupText, const TQRect & geometry )\fC [protected]\fR"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Immediately pops up a tip within the rectangle \fIgeometry\fR, saying \fItext\fR and removes the tip once the cursor moves out of rectangle \fIrect\fR. \fIgroupText\fR is the text emitted from the group. Both rectangles are given in the coordinate system of the widget this TQToolTip relates to.
|
|
.PP
|
|
The tip will not reappear if the cursor moves back; your maybeTip() must reinstate it each time.
|
|
.PP
|
|
If the tip does not fit inside \fIgeometry\fR, the tip expands.
|
|
|
|
.SH "SEE ALSO"
|
|
.BR http://doc.trolltech.com/tqtooltip.html
|
|
.BR http://www.trolltech.com/faq/tech.html
|
|
.SH COPYRIGHT
|
|
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
|
|
license file included in the distribution for a complete license
|
|
statement.
|
|
.SH AUTHOR
|
|
Generated automatically from the source code.
|
|
.SH BUGS
|
|
If you find a bug in Qt, please report it as described in
|
|
.BR http://doc.trolltech.com/bughowto.html .
|
|
Good bug reports help us to help you. Thank you.
|
|
.P
|
|
The definitive TQt documentation is provided in HTML format; it is
|
|
located at $TQTDIR/doc/html and can be read using TQt Assistant or with
|
|
a web browser. This man page is provided as a convenience for those
|
|
users who prefer man pages, although this format is not officially
|
|
supported by Trolltech.
|
|
.P
|
|
If you find errors in this manual page, please report them to
|
|
.BR qt-bugs@trolltech.com .
|
|
Please include the name of the manual page (tqtooltip.3qt) and the Qt
|
|
version (3.3.8).
|