1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
{-# LANGUAGE CPP #-}
-- -*-haskell-*-
-- GIMP Toolkit (GTK) Widget Tooltips
--
-- Author : Axel Simon
--
-- Created: 23 May 2001
--
-- Copyright (C) 1999-2005 Axel Simon
--
-- This library is free software; you can redistribute it and/or
-- modify it under the terms of the GNU Lesser General Public
-- License as published by the Free Software Foundation; either
-- version 2.1 of the License, or (at your option) any later version.
--
-- This library is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-- Lesser General Public License for more details.
--
-- |
-- Maintainer : gtk2hs-users@lists.sourceforge.net
-- Stability : provisional
-- Portability : portable (depends on GHC)
--
-- Add tips to your widgets
--
module Graphics.UI.Gtk.Misc.Tooltips (
-- * Detail
--
-- | Tooltips are the messages that appear next to a widget when the mouse
-- pointer is held over it for a short amount of time. They are especially
-- helpful for adding more verbose descriptions of things such as buttons in a
-- toolbar.
--
-- An individual tooltip belongs to a group of tooltips. A group is created
-- with a call to 'tooltipsNew'. Every tooltip in the group can then be turned
-- off with a call to 'tooltipsDisable' and enabled with 'tooltipsEnable'.
--
#ifndef DISABLE_DEPRECATED
-- The length of time the user must keep the mouse over a widget before the
-- tip is shown, can be altered with 'tooltipsSetDelay'. This is set on a \'per
-- group of tooltips\' basis.
--
#endif
-- To assign a tip to a particular 'Widget', 'tooltipsSetTip' is used.
--
-- To associate 'Tooltips' to a widget it is has to have its own 'DrawWindow'.
-- Otherwise the widget must be set into an 'EventBox'.
--
-- The default appearance of all tooltips in a program is determined by the
-- current Gtk+ theme that the user has selected.
--
-- Information about the tooltip (if any) associated with an arbitrary
-- widget can be retrieved using 'tooltipsDataGet'.
-- * Class Hierarchy
-- |
-- @
-- | 'GObject'
-- | +----'Object'
-- | +----Tooltips
-- @
-- * Types
Tooltips,
TooltipsClass,
castToTooltips, gTypeTooltips,
toTooltips,
-- * Constructors
tooltipsNew,
-- * Methods
tooltipsEnable,
tooltipsDisable,
#ifndef DISABLE_DEPRECATED
tooltipsSetDelay,
#endif
tooltipsSetTip,
tooltipsDataGet
) where
import System.Glib.FFI
import System.Glib.UTFString
import Graphics.UI.Gtk.Abstract.Object (makeNewObject)
{#import Graphics.UI.Gtk.Types#}
{# context lib="gtk" prefix="gtk" #}
--------------------
-- Constructors
-- | Create a new goup of 'Tooltips'.
--
tooltipsNew :: IO Tooltips
tooltipsNew =
makeNewObject mkTooltips $
{# call unsafe tooltips_new #}
--------------------
-- Methods
-- | Allows the user to see your tooltips as they navigate your application.
--
tooltipsEnable :: TooltipsClass self => self -> IO ()
tooltipsEnable self =
{# call unsafe tooltips_enable #}
(toTooltips self)
-- | Causes all tooltips in @tooltips@ to become inactive. Any widgets that
-- have tips associated with that group will no longer display their tips until
-- they are enabled again with 'tooltipsEnable'.
--
tooltipsDisable :: TooltipsClass self => self -> IO ()
tooltipsDisable self =
{# call unsafe tooltips_disable #}
(toTooltips self)
#ifndef DISABLE_DEPRECATED
-- | Sets the time between the user moving the mouse over a widget and the
-- widget's tooltip appearing.
--
-- * Warning: this function is deprecated and should not be used in
-- newly-written code.
--
tooltipsSetDelay :: TooltipsClass self => self
-> Int -- ^ @delay@ - the delay in milliseconds
-> IO ()
tooltipsSetDelay self delay =
{# call unsafe tooltips_set_delay #}
(toTooltips self)
(fromIntegral delay)
#endif
-- | Adds a tooltip containing the message @tipText@ to the specified
-- 'Widget'.
--
tooltipsSetTip :: (TooltipsClass self, WidgetClass widget) => self
-> widget -- ^ @widget@ - the 'Widget' you wish to associate the tip with.
-> String -- ^ @tipText@ - a string containing the tip itself.
-> String -- ^ @tipPrivate@ - a string of any further information that may be
-- useful if the user gets stuck.
-> IO ()
tooltipsSetTip self widget tipText tipPrivate =
withUTFString tipPrivate $ \tipPrivatePtr ->
withUTFString tipText $ \tipTextPtr ->
{# call unsafe tooltips_set_tip #}
(toTooltips self)
(toWidget widget)
tipTextPtr
tipPrivatePtr
{#pointer * TooltipsData#}
-- | Retrieves any 'Tooltips' previously associated with the given widget.
--
tooltipsDataGet :: WidgetClass w => w -> IO (Maybe (Tooltips, String, String))
tooltipsDataGet w = do
tipDataPtr <- {#call unsafe tooltips_data_get#} (toWidget w)
if tipDataPtr == nullPtr
then return Nothing
else do --next line is a hack, tooltips struct member is at offset 0
tooltips <- makeNewObject mkTooltips (return $ castPtr tipDataPtr)
tipText <- {#get TooltipsData->tip_text#} tipDataPtr
>>= peekUTFString
tipPrivate <- {#get TooltipsData->tip_private#} tipDataPtr
>>= peekUTFString
return $ Just $ (tooltips, tipText, tipPrivate)
|
