{-# LANGUAGE CPP #-} -- -*-haskell-*- -- GIMP Toolkit (GTK) Interface RecentChooser -- -- 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) -- -- Interface implemented by widgets displaying recently used files -- -- * Module available since Gtk+ version 2.10 -- module Graphics.UI.Gtk.Recent.RecentChooser ( -- * Detail -- -- | 'RecentChooser' is an interface that can be implemented by widgets -- displaying the list of recently used files. In Gtk+, the main objects that -- implement this interface are 'RecentChooserWidget', 'RecentChooserDialog' -- and 'RecentChooserMenu'. -- -- Recently used files are supported since Gtk+ 2.10. -- * Class Hierarchy -- -- | -- @ -- | 'GInterface' -- | +----RecentChooser -- @ #if GTK_CHECK_VERSION(2,10,0) -- * Types RecentChooser, RecentChooserClass, castToRecentChooser, toRecentChooser, -- * Enums RecentChooserError(..), RecentSortType(..), -- * Methods recentChooserSetSortFunc, recentChooserSetCurrentURI, recentChooserGetCurrentURI, recentChooserGetCurrentItem, recentChooserSelectURI, recentChooserUnselectURI, recentChooserSelectAll, recentChooserUnselectAll, recentChooserGetItems, recentChooserGetURIs, recentChooserAddFilter, recentChooserRemoveFilter, recentChooserListFilters, -- * Attributes recentChooserShowPrivate, recentChooserShowTips, recentChooserShowIcons, recentChooserShowNotFound, recentChooserSelectMultiple, recentChooserLocalOnly, recentChooserLimit, recentChooserSortType, recentChooserFilter, -- * Signals recentChooserSelectionChanged, recentChooserItemActivated, #endif ) where import Control.Monad (liftM) import System.Glib.FFI import System.Glib.UTFString import System.Glib.Attributes import System.Glib.Properties import System.Glib.GList import System.Glib.GObject (Quark, quarkFromString) import System.Glib.GError (GErrorDomain, GErrorClass(..), propagateGError, checkGError) import Graphics.UI.Gtk.Abstract.Object (makeNewObject) {#import Graphics.UI.Gtk.Recent.RecentInfo#} (RecentInfo, mkRecentInfo) {#import Graphics.UI.Gtk.Types#} {#import Graphics.UI.Gtk.Signals#} {# context lib="gtk" prefix="gtk" #} #if GTK_CHECK_VERSION(2,10,0) -------------------- -- Enums -- | These identify the various errors that can occur while calling 'RecentChooser' functions. {#enum RecentChooserError {underscoreToCase} deriving (Bounded,Eq,Show)#} -- | Used to specify the sorting method to be applyed to the recently used resource list. {#enum RecentSortType {underscoreToCase} deriving (Bounded,Eq,Show)#} -------------------- -- Methods -- | Sets the comparison function used when sorting to be @sortFunc@. If the -- @chooser@ has the sort type set to 'RecentSortCustom' then the chooser will -- sort using this function. -- -- To the comparison function will be passed two 'RecentInfo' structs and @sortData@; @sortFunc@ should return a positive -- integer if the first item comes before the second, zero if the two items are -- equal and a negative integer if the first item comes after the second. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSetSortFunc :: RecentChooserClass self => self -> (Maybe (RecentInfo -> IO Int)) -> IO () recentChooserSetSortFunc self Nothing = {# call gtk_recent_chooser_set_sort_func #} (toRecentChooser self) nullFunPtr nullPtr nullFunPtr recentChooserSetSortFunc self (Just func) = do fPtr <- mkRecentSortFunc $ \_ infoPtr _ -> do info <- mkRecentInfo infoPtr liftM fromIntegral (func info) {# call gtk_recent_chooser_set_sort_func #} (toRecentChooser self) fPtr (castFunPtrToPtr fPtr) destroyFunPtr {#pointer RecentSortFunc#} foreign import ccall "wrapper" mkRecentSortFunc :: (Ptr RecentInfo -> Ptr RecentInfo -> Ptr () -> IO {#type gint#}) -> IO RecentSortFunc -- | Sets @uri@ as the current URI for @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSetCurrentURI :: RecentChooserClass self => self -> String -- ^ @uri@ - a URI -> IO Bool -- ^ returns @True@ if the URI was found. recentChooserSetCurrentURI self uri = checkGError ( \errorPtr -> liftM toBool $ withUTFString uri $ \uriPtr -> {# call gtk_recent_chooser_set_current_uri #} (toRecentChooser self) uriPtr errorPtr) (\_ -> return False) -- | Gets the URI currently selected by @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserGetCurrentURI :: RecentChooserClass self => self -> IO String -- ^ returns a newly string holding a URI. recentChooserGetCurrentURI self = {# call gtk_recent_chooser_get_current_uri #} (toRecentChooser self) >>= readUTFString -- | Gets the 'RecentInfo' currently selected by -- @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserGetCurrentItem :: RecentChooserClass self => self -> IO RecentInfo -- ^ returns a 'RecentInfo'. -- Use 'recentInfoUnref' when when you have finished -- using it. recentChooserGetCurrentItem self = do info <- {# call gtk_recent_chooser_get_current_item #} (toRecentChooser self) mkRecentInfo info -- | Selects @uri@ inside @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSelectURI :: RecentChooserClass self => self -> String -- ^ @uri@ - a URI -> IO Bool -- ^ returns @True@ if @uri@ was found. recentChooserSelectURI self uri = checkGError ( \errorPtr -> liftM toBool $ withUTFString uri $ \uriPtr -> {# call gtk_recent_chooser_select_uri #} (toRecentChooser self) uriPtr errorPtr) (\_ -> return False) -- | Unselects @uri@ inside @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserUnselectURI :: RecentChooserClass self => self -> String -- ^ @uri@ - a URI -> IO () recentChooserUnselectURI self uri = withUTFString uri $ \uriPtr -> {# call gtk_recent_chooser_unselect_uri #} (toRecentChooser self) uriPtr -- | Selects all the items inside @chooser@, if the @chooser@ supports -- multiple selection. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSelectAll :: RecentChooserClass self => self -> IO () recentChooserSelectAll self = {# call gtk_recent_chooser_select_all #} (toRecentChooser self) -- | Unselects all the items inside @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserUnselectAll :: RecentChooserClass self => self -> IO () recentChooserUnselectAll self = {# call gtk_recent_chooser_unselect_all #} (toRecentChooser self) -- | Gets the list of recently used resources in form of 'RecentInfo' -- -- The return value of this function is affected by the \"sort-type\" and -- \"limit\" properties of @chooser@. -- recentChooserGetItems :: RecentChooserClass self => self -> IO [RecentInfo] -- ^ returns A list of 'RecentInfo' objects. recentChooserGetItems self = do glist <- {# call gtk_recent_chooser_get_items #} (toRecentChooser self) list <- fromGList glist mapM mkRecentInfo list -- | Gets the URI of the recently used resources. -- -- The return value of this function is affected by the \"sort-type\" and -- \"limit\" properties of @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserGetURIs :: RecentChooserClass self => self -> IO [String] recentChooserGetURIs self = alloca $ \lengthPtr -> do str <- {# call gtk_recent_chooser_get_uris #} (toRecentChooser self) lengthPtr length <- peek lengthPtr mapM peekUTFString =<< peekArray (fromIntegral length) str -- | Adds @filter@ to the list of 'RecentFilter' objects held by @chooser@. -- -- If no previous filter objects were defined, this function will call -- 'recentChooserSetFilter'. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserAddFilter :: (RecentChooserClass self, RecentFilterClass filter) => self -> filter -- ^ @filter@ - a 'RecentFilter' -> IO () recentChooserAddFilter self filter = {# call gtk_recent_chooser_add_filter #} (toRecentChooser self) (toRecentFilter filter) -- | Removes @filter@ from the list of 'RecentFilter' objects held by -- @chooser@. -- recentChooserRemoveFilter :: (RecentChooserClass self, RecentFilterClass filter) => self -> filter -- ^ @filter@ - a 'RecentFilter' -> IO () recentChooserRemoveFilter self filter = {# call gtk_recent_chooser_remove_filter #} (toRecentChooser self) (toRecentFilter filter) -- | Gets the 'RecentFilter' objects held by @chooser@. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserListFilters :: RecentChooserClass self => self -> IO [RecentFilter] -- ^ returns A singly linked list of 'RecentFilter'. recentChooserListFilters self = do glist <- {# call gtk_recent_chooser_list_filters #} (toRecentChooser self) list <- fromGList glist mapM (\x -> makeNewObject mkRecentFilter (return (castPtr x))) list -------------------- -- Attributes -- | Whether the private items should be displayed. -- -- Default value: 'False' -- -- * Available since Gtk+ version 2.10 -- recentChooserShowPrivate :: RecentChooserClass self => Attr self Bool recentChooserShowPrivate = newAttrFromBoolProperty "show-private" -- | Whether this 'RecentChooser' should display a tooltip containing the full path of the recently used -- resources. -- -- Default value: 'False' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserShowTips :: RecentChooserClass self => Attr self Bool recentChooserShowTips = newAttrFromBoolProperty "show-tips" -- | Whether this 'RecentChooser' should display an icon near the item. -- -- Default value: 'True' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserShowIcons :: RecentChooserClass self => Attr self Bool recentChooserShowIcons = newAttrFromBoolProperty "show-icons" -- | Whether this 'RecentChooser' should display the recently used resources even if not present -- anymore. Setting this to 'False' will perform a potentially expensive check on every local resource -- (every remote resource will always be displayed). -- -- Default value: 'True' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserShowNotFound :: RecentChooserClass self => Attr self Bool recentChooserShowNotFound = newAttrFromBoolProperty "show-not-found" -- | Allow the user to select multiple resources. -- -- Default value: 'False' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSelectMultiple :: RecentChooserClass self => Attr self Bool recentChooserSelectMultiple = newAttrFromBoolProperty "select-multiple" -- | Whether this 'RecentChooser' should display only local (file:) resources. -- -- Default value: 'True' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserLocalOnly :: RecentChooserClass self => Attr self Bool recentChooserLocalOnly = newAttrFromBoolProperty "local-only" -- | The maximum number of recently used resources to be displayed, or -1 to display all items. By -- default, the 'Setting':gtk-recent-files-limit setting is respected: you can override that limit on -- a particular instance of 'RecentChooser' by setting this property. -- -- Allowed values: >= 'GMaxulong' -- -- Default value: -1 -- -- -- * Available since Gtk+ version 2.10 -- recentChooserLimit :: RecentChooserClass self => Attr self Int recentChooserLimit = newAttrFromIntProperty "limit" -- | Sorting order to be used when displaying the recently used resources. -- -- Default value: ''RecentSortNone'' -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSortType :: RecentChooserClass self => Attr self RecentSortType recentChooserSortType = newAttrFromEnumProperty "sort-type" {# call pure unsafe gtk_recent_sort_type_get_type #} -- | The 'RecentFilter' object to be used when displaying the recently used resources. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserFilter :: (RecentChooserClass self, RecentFilterClass recentFilter) => ReadWriteAttr self RecentFilter recentFilter recentChooserFilter = newAttrFromObjectProperty "filter" {# call pure unsafe gtk_recent_filter_get_type #} -------------------- -- Signals -- | This signal is emitted when there is a change in the set of selected -- recently used resources. This can happen when a user modifies the selection -- with the mouse or the keyboard, or when explicitely calling functions to -- change the selection. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserSelectionChanged :: RecentChooserClass self => Signal self (IO ()) recentChooserSelectionChanged = Signal (connect_NONE__NONE "selection_changed") -- | This signal is emitted when the user \"activates\" a recent item in the -- recent chooser. This can happen by double-clicking on an item in the -- recently used resources list, or by pressing Enter. -- -- -- * Available since Gtk+ version 2.10 -- recentChooserItemActivated :: RecentChooserClass self => Signal self (IO ()) recentChooserItemActivated = Signal (connect_NONE__NONE "item_activated") #endif