Tooltip controls are probably one of the most unintuitave of the Win32 controls when you first come accross them. A Tooltip control is a single window that supports one or more 'tools'. A tool is a window, or an area of a window that when the mouse hovers over, the tooltip window is displayed. The Tooltip is always a top level window (so don't try adding the WS_CHILD window style), and is typically owned by the top level window of your application/dialog.
Create a tooltip window:
my $tt = Win32::GUI::Tooltip->new( $main_window, );
Add a tool to the tooltip:
$tt->AddTool( -window => $main_window, -text => "Text that pops up", );
and hover the mouse over an area of your main window.
Common methods apply to most windows, controls and resources.
new(PARENT, %OPTIONS)
Creates a new Tooltip object.
Can also be called as PARENT->AddTooltip(%OPTIONS).
Class specific %OPTIONS are:
-alwaystip => 0/1 (default: 1)
Show the tooltip, even if the window is not active.
-noprefix => 0/1 (default: 0)
Prevent the tooltip control stripping '&' prefixes
-noanimate => 0/1 (default: 0)
Turn off tooltip window animation
-nofade => 0/1 (default: 0)
Turn off tooltip window fading effect
-balloon => 0/1 (default: 0)
Give the tooltip window 'balloon' style
See also the common options.
Activate([FLAG=TRUE])
Activates or deactivates a tooltip control. A deactivated tooltip does not show it's window when the mouse hovers over a tool.
Add(@OPTIONS)
See AddTool()
AddTool(@OPTIONS)
Registers a tool with a Tooltip. When the house hovers over a tool, the
tooltip window is displayed. A tool is identified either by a window
(handle) alone, or by a window (handle) and an application defined id.
If identified by a window (handle) alone, then the associated area for
the mouse to hover is the whole client area of the window, and adjusts
automatically if the window changes size. Otherwise the rect
is fixed, as provided by the -rect options (in client co-ordinates of
the window it is associated with) and must be adjusted manually if
necessary - See NewToolRect().
@OPTIONS:
-window => HANDLE (default: owner window of tooltip control)
Window object or window handle for the tool.
-id => ID
application set ID for the tool.
-rect => [LEFT,TOP,RIGHT,BOTTOM] (defult: client rect of -window)
Area of the tool (ignored unless ID is provided)
-text => STRING or ID
String containd the Tool text, or a resource ID (see -hinst)
-hinst => HINSTANCE
If -text contains a resource ID, then -hinst gives the instance
handle from which the string resource is loaded. Ignored otherwise.
-needtext => 0/1 (default: 0)
Use NeedText Event. Don't mix this and -text.
-flags => FLAGS
Set of TTF_ bit flags. Better set using these options:
-absolute => 0/1 (default: 0)
Use with -track. Position the window at the co_ordinates
set using the TrackPosition() method.
-centertip => 0/1 (default: 0)
Center the window below the tool.
-idishwnd => 0/1 (default: 0 if -id used, 1 otherwise)
indicates that the tool applies to the whole window.
-rtlreading => 0/1 (default: 0)
indicates that text will be rendered in the opposite direction
to text in the parent window
-subclass => 0/1 (default: 0 if -track is used, 1 otherwise)
the tooltip control will arrange to get mouse messages from the
winodw containing the tool automatically. If this option is not
set then the application must relay mouse messages itself.
-track => 0/1 (default: 0)
Positions the ToolTip window next to the tool to which it
corresponds and moves the window according to coordinates
supplied by the TrackPosition() method. You must activate
this type of tool using the TrackActivate() method.
-transparent => 0/1 (default: 0)
Causes the ToolTip control to forward mouse event messages to the
parent window. This is limited to mouse events that occur within
the bounds of the ToolTip window.
Returns true on success, false on failure.
AdjustRect(LEFT, TOP, RIGHT, BOTTOM, [LARGER=1])
Adjust either a wanted text rect to a window rect (if LARGER = 1) or
a window rect to a text rect (if LARGER = 0).
LEFT, TOP, RIGHT, BOTTOM identify the corners to the rect to
convert.
LARGER identifies whether the provided rect is a text rect (to be made
larger) if true, or a window rect otherwise.
Returns a 4-element list containing the adjusted left, top, right and bottom co-ordinates of the window on success, or an empty list on failure.
Count()
Returns the number of tools in the Tooltip.
Del(TOOL)
See DelTool()
DelTool(TOOL)
Removes a tool from a Tooltip.
TOOL identifies the tool to use to calculate the window size.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
EnumTools(ENUM_ID, [BUFSIZE=0])
Retrieves the information for a tool in a tooltip control, identified by
an enumerated number ENUM_ID, starting at 0.
Returns a list of options and values on success, or an empty list on
failure (if ENUM_ID > GetToolCount()-1). For details of the possible
options see AddTool().
BUFSIZE sets the size of the buffer for retrieving the text associated with the tool. By default this is zero, and the text is not retrieved. As there is no way to automatically determine the size of the buffer required, this is a potential security hole, as the text may overrun the size of the buffer provided. Only use this if you really need to find out the text, and are prepared to live with the consequences.
Example:
my $tt = Win32::GUI::Tooltip->new( ... ); .... require Data::Dump; my $i=0; while(my %h = $tt->EnumTools($i)) { print "TOOL:$i\n"; print Data::Dump::dump(\%h), "\n"; ++$i; } my $j = $tt->GetToolCount()-1;
Or:
for my $k (0 .. $j) { my %h = $tt->EnumTools($k); print "TOOL:$k\n"; print Data::Dump::dump(\%h), "\n"; }
GetBubbleSize(TOOL)
Retrieves the width and height of a tooltip control for a given tool.
TOOL identifies the tool to use to calculate the window size.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
Returns a 2-element list containing the width and height of the tooltip window on success, or an empty list on failure.
GetCurrentTool([BUFSIZE=0])
Retrieves the information for the current tool (the one being displayed) in a tooltip control.
Returns a list of options and values on success, or an empty list on failure (if there is no current tool). For details of the possible options see AddTool().
BUFSIZE sets the size of the buffer for retrieving the text associated with the tool. By default this is zero, and the text is not retrieved. As there is no way to automatically determine the size of the buffer required, this is a potential security hole, as the text may overrun the size of the buffer provided. Only use this if you really need to find out the text, and are prepared to live with the consequences.
GetDelayTime([FLAG=TTDT_INITIAL])
Retrieves the initial, pop-up, and reshow durations currently set for a tooltip control.
FLAG : Which duration value to retrieve.
TTDT_RESHOW = 1 : Length of time it takes for subsequent tooltip
windows to appear as the pointer moves from one
tool to another.
TTDT_AUTOPOP = 2 : Length of time the tooltip window remains visible
if the pointer is stationary within a tool's
bounding rectangle.
TTDT_INITIAL = 3 : Length of time the pointer must remain stationary
within a tool's bounding rectangle before the
tooltip window appears.
Return value is the requested duration in milliseconds.
GetMargin()
Retrieves the top, left, bottom, and right margins set for a tooltip window. A margin is the distance, in pixels, between the tooltip window border and the text contained within the tooltip window.
Returns a 4-element list containing the left, top, right and bottom marign values in pixels.
GetMaxTipWidth()
Retrieves the maximum width for a tooltip window.
Returns the maximum width in pixels, or -1 if no maximum width has been set.
GetText(TOOL, [BUFSIZE=0])
Retrieves the text associated with a tool.
TOOL identifies the tool whose text is retrieved.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
BUFSIZE sets the size of the buffer for retrieving the text associated
with the tool. By default this is zero, and the text is not retrieved.
As there is no way to automatically determine the size of the buffer
required, this is a potential security hole, as the text may overrun
the size of the buffer provided. Only use this if you really need to
find out the text, and are prepared to live with the consequences.
Returns the text associated with the tooltip (if any, and
BUFSIZE > 0), otherwise FALSE.
GetTipBkColor()
Retrieves the background color in a tooltip window.
GetTipTextColor()
Retrieves the text color in a tooltip window.
GetToolCount()
See Count()
GetToolInfo(TOOL, [BUFSIZE=0])
Retrieves the information that a tooltip control maintains about a tool.
TOOL identifies the tool whose info is retrieved.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
BUFSIZE sets the size of the buffer for retrieving the text associated with the tool. By default this is zero, and the text is not retrieved. As there is no way to automatically determine the size of the buffer required, this is a potential security hole, as the text may overrun the size of the buffer provided. Only use this if you really need to find out the text, and are prepared to live with the consequences.
Returns a list of options and values on success, or an empty list on failure. For details of the possible options see AddTool().
HitTest(WINDOW, X, Y, [BUFSIZE=0])
Retrieves the information about the tool at X,Y in window WINDOW
X and Y are in client co-ordinates of the WINDOW.
WINDOW is a window object or window handle
BUFSIZE sets the size of the buffer for retrieving the text associated with the tool. By default this is zero, and the text is not retrieved. As there is no way to automatically determine the size of the buffer required, this is a potential security hole, as the text may overrun the size of the buffer provided. Only use this if you really need to find out the text, and are prepared to live with the consequences.
Returns a list of options and values on success, or an empty list on
failure (no tool at X,Y). For details of the possible options see
AddTool().
NewToolRect(TOOL, LEFT, TOP, RIGHT, BOTTOM)
Sets a new bounding rectangle for a tool.
TOOL identifies the tool to use to calculate the window size.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
LEFT,TOP,RIGHT,BOTTOM identifies the new tool rect.
Pop()
Removes a displayed tooltip window from view.
SetDelayTime(TIME,[FLAG=TTDT_INITIAL])
Sets the initial, pop-up, and reshow durations for a tooltip control.
FLAG :
TTDT_RESHOW = 1 : Length of time it takes for subsequent tooltip
windows to appear as the pointer moves from one
tool to another. To reset the reshow duration to
it's default value set TIME to -1.
TTDT_AUTOPOP = 2 : Length of time the tooltip window remains visible
if the pointer is stationary within a tool's
bounding rectangle. To reset the pop-up duration to
it's default value set TIME to -1.
TTDT_INITIAL = 3 : Length of time the pointer must remain stationary
within a tool's bounding rectangle before the
tooltip window appears. To reset the initial duration
to it's default value set TIME to -1.
TTDT_AUTOMATIC = 0 : Set all three delay times to default proportions. The
autopop time will be ten times the initial time and
the reshow time will be one fifth the initial time. If
this flag is set, use a positive value of TIME to
specify the initial time, in milliseconds. Set TIME to
a negative value to return all three delay times to
their default values.
SetMargin(LEFT, TOP, RIGHT, BOTTOM)
Sets the left, top, right, and bottom margins for a tooltip window. A margin is the distance, in pixels, between the tooltip window border and the text contained within the tooltip window.
SetMaxTipWidth(WIDTH)
Sets the maximum width for a tooltip window.
The maximum ToolTip width value does not indicate a ToolTip window's actual width. Rather, if a ToolTip string exceeds the maximum width, the control breaks the text into multiple lines, using spaces to determine line breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this line may exceed the maximum ToolTip width.
Returns the previous maximum width (-1 if no previous maximum width has been set)
SetTipBkColor(COLOR)
Sets the background color in a tooltip window.
SetTipTextColor(COLOR)
Sets the text color in a tooltip window.
SetTitle(TITLE, [ICON])
Sets the title and icon for a balloon tooltip.
Allowed values for ICON are: error, info, warning, none. Defaults to 'none'.
Returns a true value on success, a false value on failure
SetToolInfo(@OPTIONS)
Sets the information that a tooltip control maintains for a tool.
@OPTIONS: See Add().
Some internal properties of a tool are established when the tool is
created, and are not recomputed when the SetToolInfo() method is used.
If you simply using SetToolInfo(), setting the required values
these properties may be lost. Instead, your application should first
request the tool's current properties using the GetToolInfo() method,
then, modify the options as needed and pass them back to the ToolTip
control with SetToolInfo().
TrackActivate(TOOL, [FLAG=1])
Activates or deactivates a tracking tooltip.
See AddTool(), -track option.
TOOL identifies the tool to use to calculate the window size.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
FLAG identifies whether tracking is activated (1) or deactivated (0)
TrackPosition(X,Y)
Sets the position of a tracking tooltip.
X and Y are in screen co-ordinates.
See AddTool(), -track and -absolute options.
Update()
Forces the current tool to be redrawn.
UpdateTipText(TOOL, STRING_OR_RESID, [HINSTANCE=NULL])
Sets the tooltip text for a tool.
TOOL identifies the tool whose text is set.
TOOL may be one of the following:
ID - only for backwards compatibility with Win32::GUI v1.03
and earlier. A tool id identifying a tool that occupies
part of a window. The associated window defaults to the
owner window of the tooltip control, as for the default
for the -window option of the AddTool() method.
See L<AddTool()|Win32::GUI::Tooltip/AddTool>.
WINDOW - a window object or window handle, identifying a tool
that occupies the whole window.
[WINDOW] - an array reference containing a window object or window
handle, identifying a tool that occupies the whole
window.
[WINDOW, ID] - an array reference containing a window object or window
handle and a tool id, identifying a tool that occupies
part of a window.
WINDOW and/or ID are the values used for the -window and/or <-id>
options used with the AddTool() method. See AddTool().
Common events apply to most windows and controls.
NeedText(TOOL,FLAG)
Sent when a tooltip window needs to get the text for a tool
created with -needtext => 1.
TOOL is the identifier of the tool: it is the window handle of the tool if FLAG is TRUE, otherwise it is the tool ID.
Return a string from the event handler containing the text to be displayed.
Pop(TOOL,FLAG)
Sent whenever a tooltip window has just been hidden
TOOL is the identifier of the tool: it is the window handle of the tool if FLAG is TRUE, otherwise it is the tool ID.
Show(TOOL,FLAG)
Sent whenever a tooltip window is just about to be displayed
TOOL is the identifier of the tool: it is the window handle of the tool if FLAG is TRUE, otherwise it is the tool ID.
Documentation for Win32::GUI v1.06 created 13 Feb 2008
This document is autogenerated by the build process. Edits made here will be lost. Edit docs/per_package.tpl instead.
Homepage: http://perl-win32-gui.sourceforge.net/.
For further support join the users mailing list(perl-win32-gui-users@lists.sourceforge.net) from the website
at http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users. There is a searchable list archive at http://sourceforge.net/mail/.
Copyright (c) 1997..2008 Aldo Calpini. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
