{-# LINE 2 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
-- -*-haskell-*-
-- GIMP Toolkit (GTK) Widget Tooltip
--
-- Author : Andy Stewart
--
-- Created: 24 Mar 2010
--
-- Copyright (C) 2010 Andy Stewart
--
-- 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 available since Gtk+ version 2.12
--
module Graphics.UI.Gtk.Misc.Tooltip (

-- * Detail
--
-- | 'Tooltip' belongs to the new tooltips API that was introduced in Gtk+
-- 2.12 and which deprecates the old 'Tooltips' API.
--
-- Basic tooltips can be realized simply by using 'widgetTooltipText' or
-- 'widgetTooltipMarkup' without any explicit tooltip object.
--
-- When you need a tooltip with a little more fancy contents, like adding an
-- image, or you want the tooltip to have different contents per 'TreeView' row
-- or cell, you will have to do a little more work:
--
-- * Set the 'hasTooltip' property to 'True', this will make GTK+ monitor the widget for motion and
-- related events which are needed to determine when and where to show a tooltip.
--
-- * Connect to the 'queryTooltip' signal. This signal will be emitted when a tooltip is supposed to
-- be shown. One of the arguments passed to the signal handler is a 'Tooltip' object. This is the
-- object that we are about to display as a tooltip, and can be manipulated in your callback using
-- functions like 'tooltipSetIcon'. There are functions for setting the tooltip's markup,
-- setting an image from a stock icon, or even putting in a custom widget.
--
-- * Return 'True' from your query-tooltip handler. This causes the tooltip to be show. If you return
-- 'False', it will not be shown.
--
-- In the probably rare case where you want to have even more control over the tooltip that is about to
-- be shown, you can set your own 'Window' which will be used as tooltip window. This works as
-- follows:
--
-- * Set 'hasTooltip' and connect to 'queryTooltip' as before.
--
-- * Use 'widgetSetTooltipWindow' to set a 'Window' created by you as tooltip window.
--
-- * In the 'queryTooltip' callback you can access your window using 'widgetGetTooltipWindow'
-- and manipulate as you wish. The semantics of the return value are exactly as before, return 'True'
-- to show the window, 'False' to not show it.

-- * Class Hierarchy
--
-- |
-- @
-- | 'GObject'
-- | +----Tooltip
-- @


-- * Types
  Tooltip,
  TooltipClass,
  castToTooltip,
  toTooltip,

-- * Methods
  tooltipSetMarkup,
  tooltipSetText,
  tooltipSetIcon,
  tooltipSetIconFromStock,

  tooltipSetIconFromIconName,

  tooltipSetCustom,
  tooltipTriggerTooltipQuery,
  tooltipSetTipArea,


  tooltipSetIconFromGIcon,



  ) where



import Data.Maybe (fromMaybe)

import System.Glib.FFI
import System.Glib.UTFString
import Graphics.UI.Gtk.General.Structs (IconSize(..), Rectangle)
import Graphics.UI.Gtk.Types
{-# LINE 110 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}

import System.GIO.Types
{-# LINE 112 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}



{-# LINE 115 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}

--------------------
-- Methods

-- | Sets the text of the tooltip to be @markup@, which is marked up with the
-- Pango text markup language. If @markup@ is 'Nothing', the label will be hidden.
--
tooltipSetMarkup :: (TooltipClass self, GlibString markup) => self
 -> Maybe markup -- ^ @markup@ - a markup string (see Pango markup format) or 'Nothing'
 -> IO ()
tooltipSetMarkup self markup =
  maybeWith withUTFString markup $ \markupPtr ->
  (\(Tooltip arg1) arg2 -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_set_markup argPtr1 arg2)
{-# LINE 128 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    markupPtr

-- | Sets the text of the tooltip to be @text@. If @text@ is 'Nothing'
-- the label will be hidden. See also 'tooltipSetMarkup'.
--
tooltipSetText :: (TooltipClass self, GlibString string) => self
 -> Maybe string -- ^ @text@ - a text string or 'Nothing'
 -> IO ()
tooltipSetText self text =
  maybeWith withUTFString text $ \textPtr ->
  (\(Tooltip arg1) arg2 -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_set_text argPtr1 arg2)
{-# LINE 140 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    textPtr

-- | Sets the icon of the tooltip (which is in front of the text) to be
-- @pixbuf@. If @pixbuf@ is 'Nothing' the image will be hidden.
--
tooltipSetIcon :: TooltipClass self => self
  -> Maybe Pixbuf -- ^ @pixbuf@ - a 'Pixbuf' or 'Nothing'
  -> IO ()
tooltipSetIcon self pixbuf =
  (\(Tooltip arg1) (Pixbuf arg2) -> withForeignPtr arg1 $ \argPtr1 ->withForeignPtr arg2 $ \argPtr2 ->gtk_tooltip_set_icon argPtr1 argPtr2)
{-# LINE 151 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    (fromMaybe (Pixbuf nullForeignPtr) pixbuf)

-- | Sets the icon of the tooltip (which is in front of the text) to be the
-- stock item indicated by @stockId@ with the size indicated by @size@. If
-- @stockId@ is 'Nothing' the image will be hidden.
--
tooltipSetIconFromStock :: (TooltipClass self, GlibString string) => self
  -> Maybe string -- ^ @id@ a stock id, or 'Nothing'
  -> IconSize -- ^ @size@ a stock icon size
  -> IO ()
tooltipSetIconFromStock self id size =
  maybeWith withUTFString id $ \ idPtr ->
  (\(Tooltip arg1) arg2 arg3 -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_set_icon_from_stock argPtr1 arg2 arg3)
{-# LINE 165 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    idPtr
    ((fromIntegral . fromEnum) size)


-- | Sets the icon of the tooltip (which is in front of the text) to be the
-- icon indicated by @iconName@ with the size indicated by @size@. If
-- @iconName@ is 'Nothing' the image will be hidden.
--
-- * Available since Gtk+ version 2.14
--
tooltipSetIconFromIconName :: (TooltipClass self, GlibString string) => self
  -> Maybe string -- ^ @iconName@ an icon name, or 'Nothing'
  -> IconSize -- ^ @size@ a stock icon size
  -> IO ()
tooltipSetIconFromIconName self iconName size =
  maybeWith withUTFString iconName $ \ iconPtr ->
  (\(Tooltip arg1) arg2 arg3 -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_set_icon_from_icon_name argPtr1 arg2 arg3)
{-# LINE 183 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    iconPtr
    ((fromIntegral . fromEnum) size)


-- | Replaces the widget packed into the tooltip with @customWidget@.
-- @customWidget@ does not get destroyed when the tooltip goes away. By default
-- a box with a 'Image' and 'Label' is embedded in the tooltip, which can be
-- configured using 'tooltipSetMarkup' and 'tooltipSetIcon'.
--
tooltipSetCustom :: (TooltipClass self, WidgetClass widget) => self
  -> Maybe widget -- ^ @customWidget@ a 'Widget', or 'Nothing' to unset the old custom widget.
  -> IO ()
tooltipSetCustom self customWidget =
  (\(Tooltip arg1) (Widget arg2) -> withForeignPtr arg1 $ \argPtr1 ->withForeignPtr arg2 $ \argPtr2 ->gtk_tooltip_set_custom argPtr1 argPtr2)
{-# LINE 198 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    (maybe (Widget nullForeignPtr) toWidget customWidget)

-- | Triggers a new tooltip query on @display@, in order to update the current
-- visible tooltip, or to show\/hide the current tooltip. This function is
-- useful to call when, for example, the state of the widget changed by a key
-- press.
--
tooltipTriggerTooltipQuery ::
    Display -- ^ @display@ - a 'Display'
 -> IO ()
tooltipTriggerTooltipQuery display =
  (\(Display arg1) -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_trigger_tooltip_query argPtr1)
{-# LINE 211 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    display

-- | Sets the area of the widget, where the contents of this tooltip apply, to
-- be @rect@ (in widget coordinates). This is especially useful for properly
-- setting tooltips on 'TreeView' rows and cells, 'IconView'
--
-- For setting tooltips on 'TreeView', please refer to the convenience
-- functions for this: 'treeViewSetTooltipRow' and 'treeViewSetTooltipCell'.
--
tooltipSetTipArea :: TooltipClass self => self -> Rectangle -> IO ()
tooltipSetTipArea self rect =
  with rect $ \ rectPtr ->
  (\(Tooltip arg1) arg2 -> withForeignPtr arg1 $ \argPtr1 ->gtk_tooltip_set_tip_area argPtr1 arg2)
{-# LINE 224 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip self)
    (castPtr rectPtr)




-- | Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by gicon with
-- the size indicated by size. If gicon is 'Nothing', the image will be hidden.
tooltipSetIconFromGIcon :: TooltipClass self => self
                        -> Maybe Icon -- ^ @gicon@ a GIcon representing the icon, or 'Nothing'. allow-none.
                        -> IconSize
                        -> IO ()
tooltipSetIconFromGIcon tooltip icon size =
  (\(Tooltip arg1) (Icon arg2) arg3 -> withForeignPtr arg1 $ \argPtr1 ->withForeignPtr arg2 $ \argPtr2 ->gtk_tooltip_set_icon_from_gicon argPtr1 argPtr2 arg3)
{-# LINE 238 "./Graphics/UI/Gtk/Misc/Tooltip.chs" #-}
    (toTooltip tooltip)
    (fromMaybe (Icon nullForeignPtr) icon)
    ((fromIntegral . fromEnum) size)

foreign import ccall safe "gtk_tooltip_set_markup"
  gtk_tooltip_set_markup :: ((Ptr Tooltip) -> ((Ptr CChar) -> (IO ())))

foreign import ccall safe "gtk_tooltip_set_text"
  gtk_tooltip_set_text :: ((Ptr Tooltip) -> ((Ptr CChar) -> (IO ())))

foreign import ccall safe "gtk_tooltip_set_icon"
  gtk_tooltip_set_icon :: ((Ptr Tooltip) -> ((Ptr Pixbuf) -> (IO ())))

foreign import ccall safe "gtk_tooltip_set_icon_from_stock"
  gtk_tooltip_set_icon_from_stock :: ((Ptr Tooltip) -> ((Ptr CChar) -> (CInt -> (IO ()))))

foreign import ccall safe "gtk_tooltip_set_icon_from_icon_name"
  gtk_tooltip_set_icon_from_icon_name :: ((Ptr Tooltip) -> ((Ptr CChar) -> (CInt -> (IO ()))))

foreign import ccall safe "gtk_tooltip_set_custom"
  gtk_tooltip_set_custom :: ((Ptr Tooltip) -> ((Ptr Widget) -> (IO ())))

foreign import ccall safe "gtk_tooltip_trigger_tooltip_query"
  gtk_tooltip_trigger_tooltip_query :: ((Ptr Display) -> (IO ()))

foreign import ccall safe "gtk_tooltip_set_tip_area"
  gtk_tooltip_set_tip_area :: ((Ptr Tooltip) -> ((Ptr ()) -> (IO ())))

foreign import ccall safe "gtk_tooltip_set_icon_from_gicon"
  gtk_tooltip_set_icon_from_gicon :: ((Ptr Tooltip) -> ((Ptr Icon) -> (CInt -> (IO ()))))