-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Binding to the GNOME configuration database system.
--   
--   GConf is a configuration database system for storing application
--   preferences. It supports default or mandatory settings set by the
--   administrator, and changes to the database are instantly applied to
--   all running applications. It is written for the GNOME desktop but
--   doesn't require it.
@package gconf
@version 0.12.1.1


-- | GConf is a system for maintaining program configuration information.
--   
--   The main difference between GConf and traditional configuration file
--   API's is that GConf is 'live'. Applications can be notified of changes
--   in their configuration, it allows desktop wide setting to be
--   propogated without restarting all applications, or multiple instances
--   of a single application to synchronise their configuration. It is
--   similar in many ways to the Win32 Registry with its directory-like
--   structure.
--   
--   This module only binds the client library which is the only interface
--   that normal applications should need. Only special GConf apps need
--   lower level access.
--   
--   <ul>
--   <li>Some low level functions have not been bound eg
--   <tt>gconf_client_get_for_engine</tt></li>
--   </ul>
module System.Gnome.GConf.GConfClient
data GConf
data GConfPreloadType

-- | The <a>GError</a> exceptions that can be thrown by functions in this
--   module
data GConfError

-- | Create a new GConf object using the default configuration engine.
gconfGetDefault :: IO GConf

-- | Add a directory to the list of directories the GConf will watch. You
--   should use gconfNotifyAdd to associate change handlers with specific
--   keys.
--   
--   <ul>
--   <li>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 <a>gconfRemoveDir</a> an equal
--   number of times.</li>
--   <li>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
--   "/".</li>
--   </ul>
gconfAddDir :: GConf -> String -> IO ()

-- | Remove a directory from the list created with <a>gconfAddDir</a>. If
--   any notifications have been added below this directory with
--   <a>gconfNotifyAdd</a>, those notifications will be disabled until you
--   re-add the removed directory.
--   
--   <ul>
--   <li>Note that if a directory has been added multiple times, you must
--   remove it the same number of times before the remove takes
--   effect.</li>
--   </ul>
gconfRemoveDir :: GConf -> String -> IO ()
gconfNotifyAdd :: GConfValueClass value => GConf -> String -> (String -> value -> IO ()) -> IO GConfConnectId
gconfNotifyRemove :: GConf -> GConfConnectId -> IO ()
onValueChanged :: GConf -> (String -> Maybe GConfValueDyn -> IO ()) -> IO (ConnectId GConf)
afterValueChanged :: GConf -> (String -> Maybe GConfValueDyn -> IO ()) -> IO (ConnectId GConf)

-- | Gets the value of a configuration key.
gconfGet :: GConfValueClass value => GConf -> String -> IO value

-- | Sets the value of a configuration key.
gconfSet :: GConfValueClass value => GConf -> String -> value -> IO ()

-- | Gets the value of a configuration key.
--   
--   Same as <a>gconfGet</a>, but doesn't look for a default value if the
--   key is unset.
gconfGetWithoutDefault :: GConfValueClass value => GConf -> String -> IO value

-- | 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 <a>gconfSet</a> 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

-- | Unsets the value of key; if key is already unset, has no effect. An
--   error of note is <a>GconfErrorOverridden</a>, indicating that the
--   system administrator has "forced" a value for this key.
gconfUnset :: GConf -> String -> IO ()

-- | 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 ()

-- | Preloads a directory. Normally you do this when you call
--   <a>gconfAddDirWithPreload</a>, but if you've called
--   <a>gconfClearCache</a> there may be a reason to do it again.
gconfPreload :: GConf -> String -> GConfPreloadType -> IO ()

-- | 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
--   <a>gconfSuggestSync</a>. This function is just a <a>hint</a> provided
--   to gconfd to maximize efficiency and minimize data loss.
gconfSuggestSync :: GConf -> IO ()
gconfAllEntries :: GConf -> String -> IO [(String, GConfValueDyn)]
gconfAllDirs :: GConf -> String -> IO [String]
gconfDirExists :: GConf -> String -> IO Bool

-- | Class of types which can be kept by GConf
class GConfValueClass value where marshalFromGConfValue value = do { checkForNullAndExpectedType (typeofGConfValue (undefined :: value)) value; unsafeMarshalFromGConfValue value }
class GConfValueClass value => GConfPrimitiveValueClass value
data GConfValue

-- | Dynamic version for when the type is not known statically.
data GConfValueDyn
GConfValueString :: String -> GConfValueDyn
GConfValueInt :: Int -> GConfValueDyn
GConfValueFloat :: Double -> GConfValueDyn
GConfValueBool :: Bool -> GConfValueDyn

-- | Not supported
GConfValueSchema :: GConfValueDyn

-- | Must all be of same primitive type
GConfValueList :: [GConfValueDyn] -> GConfValueDyn

-- | Must both be primitive
GConfValuePair :: (GConfValueDyn, GConfValueDyn) -> GConfValueDyn
instance Enum GConfPreloadType
instance GErrorClass GConfError
instance Enum GConfError

module System.Gnome.GConf
