2
-- GIMP Toolkit (GTK) Widget Tooltips
6
-- Created: 23 May 2001
8
-- Version $Revision: 1.6 $ from $Date: 2005/10/19 12:57:37 $
10
-- Copyright (C) 1999-2005 Axel Simon
12
-- This library is free software; you can redistribute it and/or
13
-- modify it under the terms of the GNU Lesser General Public
14
-- License as published by the Free Software Foundation; either
15
-- version 2.1 of the License, or (at your option) any later version.
17
-- This library is distributed in the hope that it will be useful,
18
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
19
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20
-- Lesser General Public License for more details.
23
-- Maintainer : gtk2hs-users@lists.sourceforge.net
24
-- Stability : provisional
25
-- Portability : portable (depends on GHC)
27
-- Add tips to your widgets
29
module Graphics.UI.Gtk.Misc.Tooltips (
32
-- | Tooltips are the messages that appear next to a widget when the mouse
33
-- pointer is held over it for a short amount of time. They are especially
34
-- helpful for adding more verbose descriptions of things such as buttons in a
37
-- An individual tooltip belongs to a group of tooltips. A group is created
38
-- with a call to 'tooltipsNew'. Every tooltip in the group can then be turned
39
-- off with a call to 'tooltipsDisable' and enabled with 'tooltipsEnable'.
41
#ifndef DISABLE_DEPRECATED
42
-- The length of time the user must keep the mouse over a widget before the
43
-- tip is shown, can be altered with 'tooltipsSetDelay'. This is set on a \'per
44
-- group of tooltips\' basis.
47
-- To assign a tip to a particular 'Widget', 'tooltipsSetTip' is used.
49
-- To associate 'Tooltips' to a widget it is has to have its own 'DrawWindow'.
50
-- Otherwise the widget must be set into an 'EventBox'.
52
-- The default appearance of all tooltips in a program is determined by the
53
-- current Gtk+ theme that the user has selected.
55
-- Information about the tooltip (if any) associated with an arbitrary
56
-- widget can be retrieved using 'tooltipsDataGet'.
78
#ifndef DISABLE_DEPRECATED
87
import System.Glib.FFI
88
import System.Glib.UTFString
89
import Graphics.UI.Gtk.Abstract.Object (makeNewObject)
90
{#import Graphics.UI.Gtk.Types#}
91
{#import Graphics.UI.Gtk.Signals#}
93
{# context lib="gtk" prefix="gtk" #}
98
-- | Create a new goup of 'Tooltips'.
100
tooltipsNew :: IO Tooltips
102
makeNewObject mkTooltips $
103
{# call unsafe tooltips_new #}
108
-- | Allows the user to see your tooltips as they navigate your application.
110
tooltipsEnable :: TooltipsClass self => self -> IO ()
111
tooltipsEnable self =
112
{# call unsafe tooltips_enable #}
115
-- | Causes all tooltips in @tooltips@ to become inactive. Any widgets that
116
-- have tips associated with that group will no longer display their tips until
117
-- they are enabled again with 'tooltipsEnable'.
119
tooltipsDisable :: TooltipsClass self => self -> IO ()
120
tooltipsDisable self =
121
{# call unsafe tooltips_disable #}
124
#ifndef DISABLE_DEPRECATED
125
-- | Sets the time between the user moving the mouse over a widget and the
126
-- widget's tooltip appearing.
128
-- * Warning: this function is deprecated and should not be used in
129
-- newly-written code.
131
tooltipsSetDelay :: TooltipsClass self => self
132
-> Int -- ^ @delay@ - the delay in milliseconds
134
tooltipsSetDelay self delay =
135
{# call unsafe tooltips_set_delay #}
140
-- | Adds a tooltip containing the message @tipText@ to the specified
143
tooltipsSetTip :: (TooltipsClass self, WidgetClass widget) => self
144
-> widget -- ^ @widget@ - the 'Widget' you wish to associate the tip with.
145
-> String -- ^ @tipText@ - a string containing the tip itself.
146
-> String -- ^ @tipPrivate@ - a string of any further information that may be
147
-- useful if the user gets stuck.
149
tooltipsSetTip self widget tipText tipPrivate =
150
withUTFString tipPrivate $ \tipPrivatePtr ->
151
withUTFString tipText $ \tipTextPtr ->
152
{# call unsafe tooltips_set_tip #}
158
{#pointer * TooltipsData#}
160
-- | Retrieves any 'Tooltips' previously associated with the given widget.
162
tooltipsDataGet :: WidgetClass w => w -> IO (Maybe (Tooltips, String, String))
163
tooltipsDataGet w = do
164
tipDataPtr <- {#call unsafe tooltips_data_get#} (toWidget w)
165
if tipDataPtr == nullPtr
167
else do --next line is a hack, tooltips struct member is at offset 0
168
tooltips <- makeNewObject mkTooltips (return $ castPtr tipDataPtr)
169
tipText <- {#get TooltipsData->tip_text#} tipDataPtr
171
tipPrivate <- {#get TooltipsData->tip_private#} tipDataPtr
173
return $ Just $ (tooltips, tipText, tipPrivate)
added
removed
gtk/Graphics/UI/Gtk/Misc/Tooltips.chs.pp
