From: Duncan C. <dun...@us...> - 2004-08-08 19:10:06
|
Update of /cvsroot/gtk2hs/gtk2hs/gconf/System/Gnome/GConf In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1550/gconf/System/Gnome/GConf Modified Files: GConfValue.chs GConfClient.chs Log Message: Make the documentation for GConfClient haddock compatible. Add back partial support for the GConfSchema type so getting a schema key will not cause a pattern match failure. Index: GConfValue.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gconf/System/Gnome/GConf/GConfValue.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- GConfValue.chs 6 Aug 2004 02:03:46 -0000 1.2 +++ GConfValue.chs 8 Aug 2004 19:09:56 -0000 1.3 @@ -73,13 +73,14 @@ -- The code that uses marshalTo must ensure that it hands the value off to a -- function that is prepared to asume ownership of the value. --- dynamic version for when the type is not known statically +-- | Dynamic version for when the type is not known statically. data GConfValueDyn = GConfValueString String | GConfValueInt Int | GConfValueFloat Double | GConfValueBool Bool - | GConfValueList [GConfValueDyn] --must all be of same primitive type - | GConfValuePair (GConfValueDyn, GConfValueDyn) --must both be primitive + | GConfValueSchema -- ^ Not supported + | GConfValueList [GConfValueDyn] -- ^ Must all be of same primitive type + | GConfValuePair (GConfValueDyn, GConfValueDyn) -- ^ Must both be primitive -- Allow variant using Maybe, where Nothing means the value was not set -- Use this variant when you expect the gconf key to not be set somethimes; @@ -306,6 +307,7 @@ GconfValueInt -> liftM GConfValueInt $ unsafeMarshalFromGConfValue value GconfValueFloat -> liftM GConfValueFloat $ unsafeMarshalFromGConfValue value GconfValueBool -> liftM GConfValueBool $ unsafeMarshalFromGConfValue value + GconfValueSchema -> return GConfValueSchema GconfValueList -> liftM GConfValueList $ unsafeMarshalGConfValueDynListFromGConfValue value GconfValuePair -> liftM GConfValuePair $ unsafeMarshalGConfValueDynPairFromGConfValue value @@ -318,6 +320,7 @@ (GConfValueInt v') -> marshalToGConfValue v' (GConfValueFloat v') -> marshalToGConfValue v' (GConfValueBool v') -> marshalToGConfValue v' + (GConfValueSchema ) -> fail "GConf: setting schema types not supported" (GConfValueList v') -> marshalGConfValueDynListToGConfValue v' (GConfValuePair v') -> marshalGConfValueDynPairToGConfValue v' Index: GConfClient.chs =================================================================== RCS file: /cvsroot/gtk2hs/gtk2hs/gconf/System/Gnome/GConf/GConfClient.chs,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- GConfClient.chs 6 Aug 2004 02:03:46 -0000 1.2 +++ GConfClient.chs 8 Aug 2004 19:09:56 -0000 1.3 @@ -65,7 +65,7 @@ gconfGetDefaultFromSchema, gconfUnset, - -- * caching control + -- * Caching control -- gconfClearCache, gconfPreload, gconfSuggestSync, @@ -86,7 +86,8 @@ ) where import Monad (liftM, when) -import LocalData (newIORef, readIORef, writeIORef, unsafePerformIO) +import Data.IORef (newIORef, readIORef, writeIORef) +import System.IO.Unsafe (unsafePerformIO) import FFI {#import Hierarchy#} {#import Signal#} @@ -111,31 +112,28 @@ {# pointer *GConfEntry newtype #} --- |Operations --- ----------- +-- Operations --- |Creation operations --- - +-- Creation operations --- @constructor gconfGetDefault@ Create a new GConf object --- using the default configuration engine. +-- | Create a new GConf object using the default configuration engine. -- gconfGetDefault :: IO GConf gconfGetDefault = makeNewGObject mkGConf {# call gconf_client_get_default #} --- |Registering for change notifications --- - +-- Registering for change notifications --- @method gconfAddDir@ Add a directory to the list of directories the +-- | Add a directory to the list of directories the -- GConf will watch. You should use gconfNotifyAdd to associate -- change handlers with specific keys. -- --- * Added directories may not overlap. That is, if you add "/foo", you may not --- add "/foo/bar". However you can add "/foo" and "/bar". You can also add --- "/foo" multiple times; if you add a directory multiple times, it will not --- be removed until you call gconfRemoveDir an equal number of times. +-- * Added directories may not overlap. That is, if you add \"\/foo\", you may +-- not add \"\/foo\/bar\". However you can add \"\/foo\" and \"\/bar\". You can +-- also add \"\/foo\" multiple times; if you add a directory multiple times, it +-- will not be removed until you call 'gconfRemoveDir' an equal number of +-- times. -- -- * Note that the watch is recursive, all keys below the given directory will -- be watched. So it would be a bad idea to watch the root "/". @@ -143,8 +141,7 @@ gconfAddDir :: GConf -> String -> IO () gconfAddDir gc key = gconfAddDirWithPreload gc key PreloadNone --- @method gconfAddDirWithPreload@ Like gconfAddDir but with the --- option to specify a preload mode. +-- | Like 'gconfAddDir' but with the option to specify a preload mode. -- -- As a rule of thumb, if you plan to get the value of almost all the keys in a -- directory, preloading that directory will probably enhance performance. If @@ -162,13 +159,12 @@ {# call gconf_client_add_dir #} gc strPtr (fromIntegral $ fromEnum preload) gerrorPtr --- @method gconfRemoveDir@ Remove a directory from the list created with --- gconfAddDir. If any notifications have been added below this directory --- with gconfNotifyAdd, those notifications will be disabled until you --- re-add the removed directory. +-- | Remove a directory from the list created with 'gconfAddDir'. If any +-- notifications have been added below this directory with 'gconfNotifyAdd', +-- those notifications will be disabled until you re-add the removed directory. -- -- * Note that if a directory has been added multiple times, you must remove it --- the same number of times before the remove takes effect. +-- the same number of times before the remove takes effect. -- gconfRemoveDir :: GConf -> String -> IO () gconfRemoveDir gc key = @@ -193,12 +189,10 @@ #if __GLASGOW_HASKELL__>=504 foreign import ccall "wrapper" mkHandler_GConfClientNotifyFunc :: - GConfClientNotifyFunc -> - IO (FunPtr GConfClientNotifyFunc) + GConfClientNotifyFunc -> IO (FunPtr GConfClientNotifyFunc) #else foreign export dynamic mkHandler_GConfClientNotifyFunc :: - GConfClientNotifyFunc -> - IO (FunPtr GConfClientNotifyFunc) + GConfClientNotifyFunc -> IO (FunPtr GConfClientNotifyFunc) #endif connect_GConfClientNotifyFunc :: @@ -245,15 +239,13 @@ {# call gconf_client_notify_remove #} gc cxid --- |Getting and setting configuration values --- - +-- Getting and setting configuration values --- @method gconfGet@ Gets the value of a configuration key. --- --- * the second parameter is name of the key +-- | Gets the value of a configuration key. -- -gconfGet :: GConfValueClass value => - GConf -> String -> IO value +gconfGet :: GConfValueClass value => GConf + -> String -- ^ Name of the key + -> IO value gconfGet gc key = do value <- propagateGError $ \gerrorPtr -> withCString key $ \strPtr -> @@ -280,12 +272,12 @@ GConf -> String -> IO [a] gconfGetList = gconfGet --- @method gconfSet@ Sets the value of a configuration key. --- --- * the second parameter is name of the key, the third is the new value +-- | Sets the value of a configuration key. -- -gconfSet :: GConfValueClass value => - GConf -> String -> value -> IO () +gconfSet :: GConfValueClass value => GConf + -> String -- ^ Name of the key + -> value -- ^ New value + -> IO () gconfSet gc key val = do value@(GConfValue ptr) <- marshalToGConfValue val if ptr == nullPtr @@ -314,8 +306,9 @@ GConf -> String -> [a] -> IO () gconfSetList = gconfSet --- @method gconfGetWithoutDefault@ Gets the value of a configuration key. --- Same as gconfGet, but doesn't look for a default value if the key is +-- | Gets the value of a configuration key. +-- +-- Same as 'gconfGet', but doesn't look for a default value if the key is -- unset. -- gconfGetWithoutDefault :: GConfValueClass value => @@ -326,11 +319,10 @@ {# call gconf_client_get_without_default #} gc strPtr gerrorPtr marshalFromGConfValue value --- @method gconfGetDefaultFromSchema@ Returns the default value stored in --- the key's schema, if the key has a schema associated and the schema exists --- and the schema contains a default value. Note that gconfSet already --- returns the default value if no other value is found, so normally you do not --- need this function. +-- | Returns the default value stored in the key's schema, if the key has a +-- schema associated and the schema exists and the schema contains a default +-- value. Note that 'gconfSet' already returns the default value if no other +-- value is found, so normally you do not need this function. -- gconfGetDefaultFromSchema :: GConfValueClass value => GConf -> String -> IO value @@ -340,9 +332,9 @@ {# call gconf_client_get_default_from_schema #} gc strPtr gerrorPtr marshalFromGConfValue value --- @method gconfGetWithoutDefault@ Unsets the value of key; if key is --- already unset, has no effect. An error of note is GCONF_OVERRIDDEN, --- indicating that the system administrator has "forced" a value for this key. +-- | Unsets the value of key; if key is already unset, has no effect. An error +-- of note is 'GConfOverridden', indicating that the system administrator has +-- \"forced\" a value for this key. -- gconfUnset :: GConf -> String -> IO () gconfUnset gc key = @@ -351,16 +343,16 @@ {# call gconf_client_unset #} gc strPtr gerrorPtr return () --- @method gconfClearCache@ Dumps everything out of the GConf --- client-side cache. If you know you're done using the GConf for a while, --- you can call this function to save some memory. +-- | Dumps everything out of the GConf client-side cache. If you know you're +-- done using the GConf for a while, you can call this function to save some +-- memory. -- gconfClearCache :: GConf -> IO () gconfClearCache gc = {# call gconf_client_clear_cache #} gc --- @method gconfPreload@ Preloads a directory. Normally you do this when --- you call gconfAddDirWithPreload, but if you've called --- gconfClearCache there may be a reason to do it again. +-- | Preloads a directory. Normally you do this when you call +-- 'gconfAddDirWithPreload', but if you've called 'gconfClearCache' there may +-- be a reason to do it again. -- gconfPreload :: GConf -> String -> GConfPreloadType -> IO () gconfPreload gc key preload = @@ -369,18 +361,18 @@ {# call gconf_client_preload #} gc strPtr (fromIntegral $ fromEnum preload) gerrorPtr --- @method gconfSuggestSync@ Suggests to gconfd that you've just finished --- a block of changes, and it would be an optimal time to sync to permanent --- storage. This is only a suggestion; and gconfd will eventually sync even if --- you don't call gconfSuggestSync. This function is just a "hint" --- provided to gconfd to maximize efficiency and minimize data loss. +-- | Suggests to gconfd that you've just finished a block of changes, and it +-- would be an optimal time to sync to permanent storage. This is only a +-- suggestion; and gconfd will eventually sync even if you don't call +-- 'gconfSuggestSync'. This function is just a "hint" provided to gconfd to +-- maximize efficiency and minimize data loss. -- gconfSuggestSync :: GConf -> IO () gconfSuggestSync gc = propagateGError $ \gerrorPtr -> {# call gconf_client_suggest_sync #} gc gerrorPtr --- @method gconfAllEntries@ +-- | -- gconfAllEntries :: GConf -> String -> IO [(String, GConfValueDyn)] gconfAllEntries gc dir = do @@ -400,7 +392,7 @@ return (key,value)) entryList --- @method gconfAllDirs@ +-- | -- gconfAllDirs :: GConf -> String -> IO [String] gconfAllDirs gc dir = do @@ -412,7 +404,7 @@ return str) dirList --- @method gconfDirExists@ +-- | -- gconfDirExists :: GConf -> String -> IO Bool gconfDirExists gc dir = @@ -420,8 +412,7 @@ liftM toBool $ {# call gconf_client_dir_exists #} gc strPtr nullPtr --- |Signals --- - +-- Signals onValueChanged, afterValueChanged :: GConf -> (String -> Maybe GConfValueDyn -> IO ()) -> |