RecentInfo.chs

{-# LANGUAGE CPP #-}
-- -*-haskell-*-
--  GIMP Toolkit (GTK) Widget RecentInfo
--
--  Author : Andy Stewart
--
--  Created: 27 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)
--
--
module Graphics.UI.Gtk.Recent.RecentInfo (

#if GTK_CHECK_VERSION(2,10,0)
-- * Types
  RecentInfo,
  mkRecentInfo,

-- * Methods
  recentInfoExists,
  recentInfoGetAdded,
  recentInfoGetAge,
  recentInfoGetApplicationInfo,
  recentInfoGetApplications,
  recentInfoGetDescription,
  recentInfoGetDisplayName,
  recentInfoGetGroups,
  recentInfoGetIcon,
  recentInfoGetMimeType,
  recentInfoGetModified,
  recentInfoGetPrivateHint,
  recentInfoGetShortName,
  recentInfoGetURI,
  recentInfoGetURIDisplay,
  recentInfoGetVisited,
  recentInfoHasApplication,
  recentInfoHasGroup,
  recentInfoIsLocal,
  recentInfoLastApplication,
  recentInfoMatch,
#endif
  ) where

import Control.Monad	(liftM)

import System.Glib.FFI
import System.Glib.Attributes
import System.Glib.Properties
import System.Glib.UTFString
{#import Graphics.UI.Gtk.Types#}

{# context lib="gtk" prefix="gtk" #}

#if GTK_CHECK_VERSION(2,10,0)
--------------------
-- Types
{#pointer *RecentInfo foreign newtype#}

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

-- | Helper function for build 'RecentInfo'
mkRecentInfo :: Ptr RecentInfo -> IO RecentInfo
mkRecentInfo rPtr = do
  info <- newForeignPtr rPtr gtk_recent_info_unref
  return (RecentInfo info)

foreign import ccall unsafe "&gtk_recent_info_unref"
  gtk_recent_info_unref :: FinalizerPtr RecentInfo

-- | Checks whether the resource pointed by info still exists. At the moment this check is done only on
-- resources pointing to local files.
--
-- * Available since Gtk+ version 2.10
--
recentInfoExists :: RecentInfo 
                 -> IO Bool -- ^ returns 'True' if the resource exists 
recentInfoExists self =
  liftM toBool $
  {# call gtk_recent_info_exists #}
    self

-- | Gets the timestamp (seconds from system's Epoch) when the resource was added to the recently used
-- resources list.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetAdded :: RecentInfo 
                   -> IO Int -- ^ returns the number of seconds elapsed from system's Epoch when the resource was added to the list, or -1 on failure.
recentInfoGetAdded self =
  liftM fromIntegral $
  {# call gtk_recent_info_get_added #}
    self

-- | Gets the number of days elapsed since the last update of the resource pointed by info.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetAge :: RecentInfo 
                 -> IO Int -- ^ returns a positive integer containing the number of days elapsed since the time this resource was last modified.
recentInfoGetAge self =
  liftM fromIntegral $
  {# call gtk_recent_info_get_age #}
    self

-- | Gets the data regarding the application that has registered the resource pointed by info.
-- 
-- If the command line contains any escape characters defined inside the storage specification, they
-- will be expanded.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetApplicationInfo :: RecentInfo 
                             -> String  -- ^ @appName@ the name of the application that has registered this item
                             -> IO (Maybe ([String], Int, Int))
                              -- ^ @appExec@ return location for the string containing the command line. transfer none.
                              -- ^ @count@    return location for the number of times this item was registered. out.
                              -- ^ @time@    out. out.
recentInfoGetApplicationInfo self appName =
  alloca $ \countPtr ->
  alloca $ \timePtr ->
  allocaArray 0 $ \execPtr -> 
  withUTFString appName $ \appNamePtr -> do
    success <- liftM toBool $
              {# call gtk_recent_info_get_application_info #}
                self
                appNamePtr
                execPtr
                countPtr
                timePtr
    if success 
       then do
         exec <- mapM peekUTFString =<< peekArray 0 execPtr
         count <- peek countPtr
         time <- peek timePtr
         return (Just (exec, fromIntegral count, fromIntegral time))
       else return Nothing

-- | Retrieves the list of applications that have registered this resource.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetApplications :: RecentInfo -> IO [String]
recentInfoGetApplications self = 
  alloca $ \lengthPtr -> do
    str <- {# call gtk_recent_info_get_applications #} self lengthPtr
    length <- peek lengthPtr
    mapM peekUTFString =<< peekArray (fromIntegral length) str

-- | Gets the (short) description of the resource.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetDescription :: RecentInfo 
                         -> IO String -- ^ returns the description of the resource. 
recentInfoGetDescription self =
  {# call gtk_recent_info_get_description #}
    self
  >>= peekUTFString

-- | Gets the name of the resource. If none has been defined, the basename of the resource is obtained.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetDisplayName :: RecentInfo 
                         -> IO String -- ^ returns the display name of the resource. 
recentInfoGetDisplayName self =
  {# call gtk_recent_info_get_display_name #}
    self
  >>= peekUTFString

-- | Returns all groups registered for the recently used item info. 
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetGroups :: RecentInfo -> IO [String]
recentInfoGetGroups self = 
  alloca $ \lengthPtr -> do
    str <- {# call gtk_recent_info_get_groups #} self lengthPtr
    length <- peek lengthPtr
    mapM peekUTFString =<< peekArray (fromIntegral length) str

-- | Retrieves the icon of size size associated to the resource MIME type.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetIcon :: RecentInfo 
                  -> Int  -- ^ @size@    the size of the icon in pixels
                  -> IO (Maybe Pixbuf) -- ^ returns a 'Pixbuf' containing the icon, or 'Nothing'
recentInfoGetIcon self size =
  maybeNull (makeNewGObject mkPixbuf) $
  {# call gtk_recent_info_get_icon #}
    self
    (fromIntegral size)

-- | Gets the MIME type of the resource.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetMimeType :: RecentInfo 
                      -> IO String -- ^ returns the MIME type of the resource. 
recentInfoGetMimeType self =
  {# call gtk_recent_info_get_mime_type #}
    self
  >>= peekUTFString

-- | Gets the timestamp (seconds from system's Epoch) when the resource was last modified.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetModified :: RecentInfo 
                      -> IO Int -- ^ returns the number of seconds elapsed from system's Epoch when the resource was last modified, or -1 on failure.
recentInfoGetModified self =
  liftM fromIntegral $
  {# call gtk_recent_info_get_modified #}
    self

-- | Gets the value of the "private" flag. Resources in the recently used list that have this flag set to
-- 'True' should only be displayed by the applications that have registered them.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetPrivateHint :: RecentInfo 
                         -> IO Bool -- ^ returns 'True' if the private flag was found, 'False' otherwise. 
recentInfoGetPrivateHint self =
  liftM toBool $
  {# call gtk_recent_info_get_private_hint #}
    self

-- | Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For
-- example, calling this function on an item that refers to \"file:///foo/bar.txt\" will yield \"bar.txt\".
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetShortName :: RecentInfo 
                       -> IO String
recentInfoGetShortName self =
  {# call gtk_recent_info_get_short_name #}
    self
  >>= readUTFString

-- | Gets the URI of the resource.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetURI :: RecentInfo 
                 -> IO String -- ^ returns the URI of the resource. 
recentInfoGetURI self =
  {# call gtk_recent_info_get_uri #}
    self
  >>= peekUTFString

-- | Gets a displayable version of the resource's URI. If the resource is local, it returns a local path;
-- if the resource is not local, it returns the UTF-8 encoded content of 'recentInfoGetUri'.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetURIDisplay :: RecentInfo -> IO String
recentInfoGetURIDisplay self =
  {# call gtk_recent_info_get_uri_display #}
    self
  >>= readUTFString

-- | Gets the timestamp (seconds from system's Epoch) when the resource was last visited.
--
-- * Available since Gtk+ version 2.10
--
recentInfoGetVisited :: RecentInfo 
                     -> IO Int -- ^ returns the number of seconds elapsed from system's Epoch when the resource was last visited, or -1 on failure.
recentInfoGetVisited self =
  liftM fromIntegral $
  {# call gtk_recent_info_get_visited #}
    self

-- | Checks whether an application registered this resource using @appName@.
--
-- * Available since Gtk+ version 2.10
--
recentInfoHasApplication :: RecentInfo 
                         -> String  -- ^ @appName@ a string containing an application name                              
                         -> IO Bool -- ^ returns  'True' if an application with name @appName@ was found, 'False' otherwise.
recentInfoHasApplication self appName =
  liftM toBool $
  withUTFString appName $ \appNamePtr ->
  {# call gtk_recent_info_has_application #}
    self
    appNamePtr

-- | Checks whether @groupName@ appears inside the groups registered for the recently used item info.
--
-- * Available since Gtk+ version 2.10
--
recentInfoHasGroup :: RecentInfo 
                   -> String  -- ^ @groupName@ name of a group              
                   -> IO Bool -- ^ returns    'True' if the group was found. 
recentInfoHasGroup self groupName =
  liftM toBool $
  withUTFString groupName $ \groupNamePtr ->
  {# call gtk_recent_info_has_group #}
    self
    groupNamePtr

-- | Checks whether the resource is local or not by looking at the scheme of its URI.
--
-- * Available since Gtk+ version 2.10
--
recentInfoIsLocal :: RecentInfo 
                  -> IO Bool -- ^ returns 'True' if the resource is local. 
recentInfoIsLocal self =
  liftM toBool $
  {# call gtk_recent_info_is_local #}
    self

-- | Gets the name of the last application that have registered the recently used resource represented by
-- info.
--
-- * Available since Gtk+ version 2.10
--
recentInfoLastApplication :: RecentInfo 
                          -> IO String -- ^ returns an application name. 
recentInfoLastApplication self =
  {# call gtk_recent_info_last_application #}
    self
  >>= readUTFString

-- | Checks whether two 'RecentInfo' structures point to the same resource.
--
-- * Available since Gtk+ version 2.10
--
recentInfoMatch :: RecentInfo -> RecentInfo 
                -> IO Bool -- ^ returns 'True' if both 'RecentInfo' structures point to se same resource, 'False' otherwise.
recentInfoMatch self infoB =
  liftM toBool $
  {# call gtk_recent_info_match #}
    self
    infoB
#endif