Win32::GUI::Tooltip - Create and manipulate Tooltip controls
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().
-rect
@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).
LARGER = 1
LARGER = 0
LEFT, TOP, RIGHT, BOTTOM identify the corners to the rect to convert.
LEFT
TOP
RIGHT
BOTTOM
LARGER identifies whether the provided rect is a text rect (to be made larger) if true, or a window rect otherwise.
LARGER
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:
TOOL
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().
WINDOW
ID
-window
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.
ENUM_ID
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.
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().
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:
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.
BUFSIZE
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:
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,Y
X and Y are in client co-ordinates of the WINDOW. WINDOW is a window object or window handle
X
Y
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.
LEFT,TOP,RIGHT,BOTTOM identifies the new tool rect.
LEFT,TOP,RIGHT,BOTTOM
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.
-track
FLAG identifies whether tracking is activated (1) or deactivated (0)
FLAG
TrackPosition(X,Y)
Sets the position of a tracking tooltip. X and Y are in screen co-ordinates. See AddTool(), -track and -absolute options.
-absolute
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:
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.
-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
Show(TOOL,FLAG)
Sent whenever a tooltip window is just about to be displayed
Documentation for Win32::GUI v1.11 created 08 Nov 2014
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 from the website at http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users. There is a searchable list archive at http://sourceforge.net/p/perl-win32-gui/mailman/perl-win32-gui-users/.
Copyright (c) 1997..2014 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.
To install Win32::GUI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::GUI
CPAN shell
perl -MCPAN -e shell install Win32::GUI
For more information on module installation, please visit the detailed CPAN module installation guide.