# Function Reference

# _GUIToolTip_AddTool

Registers a tool with the ToolTip control

#include <GuiToolTip.au3>
_GUIToolTip_AddTool ( $hTool, $hWnd, $sText [, $iID = 0 [, $iLeft = 0 [, $iTop = 0 [, $iRight = 0 [, $iBottom = 0 [, $iFlags = Default [, $iParam = 0 [, $hInst = 0]]]]]]]] )

## Parameters

$hTool | Handle to the ToolTip control (returned by _GUIToolTip_Create.)
$hWnd | Handle of the window that contains the tool, or 0
$sText | Text for the ToolTip control. See remark.
$iID | [optional] Identifier of the tool, or Window handle of the control the tool is to be assigned to
$iLeft | [optional] X coordinate of the upper left corner of the rectangle
$iTop | [optional] Y coordinate of the upper left corner of the rectangle
$iRight | [optional] X coordinate of the lower right corner of the rectangle
$iBottom | [optional] Y coordinate of the lower right corner of the rectangle
$iFlags | [optional] Flags that control the ToolTip display: $TTF_IDISHWND - Indicates that $iID is a window or control handle, instead of the ID of the tool $TTF_CENTERTIP - Centers the tooltip below the control specified by $iID $TTF_RTLREADING - Indicates that text will be displayed in the opposite direction of the parent window (see remarks) $TTF_SUBCLASS - Indicates that the control should subclass the tool's window $TTF_TRACK - Positions the tooltip window next to the tool to which it corresponds $TTF_ABSOLUTE - Positions the window at the same coordinates provided by TTM_TRACKPOSITION. (see remarks) $TTF_TRANSPARENT- Causes the control to forward mouse messages to the parent window $TTF_PARSELINKS - Indicates that links in the control text should be displayed as links Default = BitOr($TTF_SUBCLASS, $TTF_IDISHWND)
$iParam | [optional] Application-defined value that is associated with the tool
$hInst | [optional] Handle to the instance that is associated with the tool

## Return Value

Success: | True.
Failure: | False, @error can be set (see remark).

## Remarks

If $hWnd referenced control is not in the same process and both processes run in different AutoIt mode (@AutoItVersion), the @error is set to 6.
If a notification callback is needed, you have to set $sText = -1 (LPSTR_TEXTCALLBACK).
If you use the flag $TTF_IDISHWND then the coordinates in $iLeft, $iTop, $iRight and $iBottom are ignored.
If you use the flag $TTF_ABSOLUTE it must be used with the $TTF_TRACK flag.
Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, tooltip text is displayed in the same direction as the text in its parent window. If $TTF_RTLREADING is set, tooltip text will read in the opposite direction from the text in the parent window.

## Related

_GUIToolTip_DelTool

## Example

### Example 1

    #include "Extras\HelpFileInternals.au3"

    #include <GUIConstantsEx.au3>
    #include <GUIToolTip.au3>

    Example()

    Func Example()
        Local $hGUI = GUICreate("ToolTip Add Tool v(" & @AutoItVersion & ")", 450, 300, 100, 100)
        Local $iGUI = 1

        ; create a tooltip control using default settings
        Local $hToolTip = _GUIToolTip_Create(0)
        _MemoSetHandleInProcess($hToolTip)

        Local $idButton = GUICtrlCreateButton("Button", 30, 32, 130, 28)
        Local $hButton = GUICtrlGetHandle($idButton)

    ;~  $iGUI = 0 ; is OK
        ; add a tool to the tooltip control
        _GUIToolTip_AddTool($hToolTip, $iGUI * $hGUI, "This is a ToolTip", $hButton)
        _GUIToolTip_AddTool($hToolTip, $iGUI * $hGUI, "This is a ToolTip for the non another ctrl's", $hGUI)

        GUISetState(@SW_SHOW)

        ; Show the tooltip associated with the button
        Opt("MouseCoordMode", 2)
        MouseMove(50, 42, 0)
        Sleep(250)

        While 1
            If GUIGetMsg() = $GUI_EVENT_CLOSE Then ExitLoop
        WEnd

        ; Destroy the tooltip control
        _MemoResetHandleInProcess($hToolTip)
        _GUIToolTip_Destroy($hToolTip)
        GUIDelete($hGUI)
    EndFunc   ;==>Example

### Example 2

    #include "Extras\HelpFileInternals.au3"

    #include <GUIConstantsEx.au3>
    #include <GUIToolTip.au3>
    #include <StaticConstants.au3>

    ; This example demonstrates how to add a tool, it does not assign the tool to any control, just an area of the GUI
    Example()

    Func Example()
        Local $hGUI = GUICreate("ToolTip AddTool - v(" & @AutoItVersion & ")", 350, 200, 100, 100)
        ; create frames to indicate where the tooltip will display when the mouse is in the
        ; correct location on the GUI, these frames do not have a tooltip assigned to it
        ; these frames are ONLY for visual representation as to where the tooltip will display,
        ; they are not needed to make the tooltip display.
        GUICtrlCreateLabel("", 10, 10, 160, 75, $SS_ETCHEDFRAME)
        ; this label control must be disabled or the tooltip will not display when the mouse
        ; is over it.
        GUICtrlSetState(-1, $GUI_DISABLE)
        GUICtrlCreateLabel("", 10, 84, 160, 75, $SS_ETCHEDFRAME)
        ; this label control must be disabled or the tooltip will not display when the mouse
        ; is over it.
        GUICtrlSetState(-1, $GUI_DISABLE)
        GUICtrlCreateLabel("", 169, 10, 160, 75, $SS_ETCHEDFRAME)
        ; this label control must be disabled or the tooltip will not display when the mouse
        ; is over it.
        GUICtrlSetState(-1, $GUI_DISABLE)
        GUICtrlCreateLabel("", 169, 84, 160, 75, $SS_ETCHEDFRAME)
        ; this label control must be disabled or the tooltip will not display when the mouse
        ; is over it.
        GUICtrlSetState(-1, $GUI_DISABLE)
        Local $idButton = GUICtrlCreateButton("This is a button", 30, 32, 130, 28)
        Local $hButton = GUICtrlGetHandle($idButton)
        ; create a tooltip control using default settings
        Local $hToolTip = _GUIToolTip_Create(0)

        ; add 4 tools to the tooltip control, these tools are created using the location on the GUI
        ; rather than assigning them to a specific control.
        _GUIToolTip_AddTool($hToolTip, $hGUI, "Upper Left corner", 0, 10, 10, 168, 85, $TTF_SUBCLASS)
        _GUIToolTip_AddTool($hToolTip, $hGUI, "Upper Right corner", 0, 168, 10, 328, 85, $TTF_SUBCLASS)
        _GUIToolTip_AddTool($hToolTip, $hGUI, "Lower Left corner", 0, 10, 85, 168, 160, $TTF_SUBCLASS)
        _GUIToolTip_AddTool($hToolTip, $hGUI, "Lower Right corner", 0, 168, 85, 328, 160, $TTF_SUBCLASS)
        ; add a tool to the tooltip control that is assigned to the button control
        _GUIToolTip_AddTool($hToolTip, $hGUI, "This tooltip belongs to the button", $hButton)
        GUISetState(@SW_SHOW)

        While 1
            If GUIGetMsg() = $GUI_EVENT_CLOSE Then ExitLoop
        WEnd
        ; Destroy the tooltip control
        _GUIToolTip_Destroy($hToolTip)
        GUIDelete($hGUI)
    EndFunc   ;==>Example

### Example (OutProcess) : ToolTip Add Tool to an External process

    #include "Extras\HelpFileInternals.au3"

    #include <GUIToolTip.au3>

    Example()

    Func Example()
        Local $sFromTo
        Local $hWin = _MemoRunAU3OutProcess($sFromTo, True) ; OK same mode, KO if different mode

        Local $hToolTip = _MemoGetHandleInProcess()
        Local $hButton = _MemoCreateOutProcess($hWin, "Button", 0, $sFromTo)

        ; add a tool to the tooltip control
        Local $iRet = _GUIToolTip_AddTool($hToolTip, $hWin, "<<<This is a ToolTip", $hButton)
        If @error Then
            _MemoMsgBox($MB_ICONERROR, "Info" & $sFromTo, "_GUIToolTip_AddTool()" & " @error = " & @error & @CRLF & _
                    @TAB & "cannot be added to an external process" & @CRLF & _
                    @TAB & "running in different mode")
        Else
            ; only working if both processes are running in "same mode"
            _MemoWrite("Info" & $sFromTo & " _GUIToolTip_AddTool() $iRet= " & $iRet)
            _Memowrite(_GUIToolTip_GetText($hWin, $hToolTip, $hButton))
        EndIf

        _MemoMsgBoxStatus("", Default, $hWin) ; no more action, wait GUI for closing, close also OutProcess GUI

    EndFunc   ;==>Example