|
System.Glib.GError | Portability | portable (depends on GHC) | Stability | provisional | Maintainer | gtk2hs-users@lists.sourceforge.net |
|
|
|
|
|
Description |
Error Reporting, glib's system for reporting errors.
GErrors are used by glib to report recoverable runtime errors.
This module provides functions for checking glib/gtk functions that report
GErrors. It also provides functions for throwing and catching GErrors as
Haskell exceptions.
|
|
Synopsis |
|
|
|
|
Data types
|
|
|
A GError consists of a domain, code and a human readable message.
| Constructors | |
|
|
type GErrorDomain = GQuark | Source |
|
A code used to identify the 'namespace' of the error. Within each error
domain all the error codes are defined in an enumeration. Each gtk/gnome
module that uses GErrors has its own error domain. The rationale behind
using error domains is so that each module can organise its own error codes
without having to coordinate on a global error code list.
|
|
|
A code to identify a specific error within a given GErrorDomain. Most of
time you will not need to deal with this raw code since there is an
enumeration type for each error domain. Of course which enumeraton to use
depends on the error domain, but if you use catchGErrorJustDomain or
handleGErrorJustDomain, this is worked out for you automatically.
|
|
|
A human readable error message.
|
|
Catching GError exceptions
|
|
To catch GError exceptions thrown by Gtk2Hs functions use the
catchGError* or handleGError* functions. They work in a similar way to
the standard Control.Exception.catch and Control.Exception.handle
functions.
catchGError / handleGError catches all GError exceptions, you provide
a handler function that gets given the GError if an exception was thrown.
This is the most general but is probably not what you want most of the
time. It just gives you the raw error code rather than a Haskell
enumeration of the error codes. Most of the time you will only want to
catch a specific error or any error from a specific error domain. To
catch just a single specific error use
catchGErrorJust / handleGErrorJust. To catch any error in a
particular error domain use catchGErrorJustDomain /
handleGErrorJustDomain
|
|
|
:: | | => IO a | Handler to invoke if an exception is raised
| -> GError -> IO a | | -> IO a | | This will catch any GError exception. The handler function will receive the
raw GError. This is probably only useful when you want to take some action
that does not depend on which GError exception has occured, otherwise it
would be better to use either catchGErrorJust or catchGErrorJustDomain.
For example:
catchGError
(do ...
...)
(\(GError dom code msg) -> fail msg)
|
|
|
|
:: GErrorClass err | | => err | The computation to run
| -> IO a | Handler to invoke if an exception is raised
| -> GErrorMessage -> IO a | | -> IO a | | This will catch just a specific GError exception. If you need to catch a
range of related errors, catchGErrorJustDomain is probably more
appropriate. Example:
do image <- catchGErrorJust PixbufErrorCorruptImage
loadImage
(\errorMessage -> do log errorMessage
return mssingImagePlaceholder)
|
|
|
|
:: GErrorClass err | | => IO a | Handler to invoke if an exception is raised
| -> err -> GErrorMessage -> IO a | | -> IO a | | Catch all GErrors from a particular error domain. The handler function
should just deal with one error enumeration type. If you need to catch
errors from more than one error domain, use this function twice with an
appropriate handler functions for each.
catchGErrorJustDomain
loadImage
(\err message -> case err of
PixbufErrorCorruptImage -> ...
PixbufErrorInsufficientMemory -> ...
PixbufErrorUnknownType -> ...
_ -> ...)
|
|
|
|
A verson of catchGError with the arguments swapped around.
handleGError (\(GError dom code msg) -> ...) $
...
|
|
|
A verson of handleGErrorJust with the arguments swapped around.
|
|
|
A verson of handleGErrorJustDomain with the arguments swapped around.
|
|
|
Catch all GError exceptions and convert them into a general failure.
|
|
|
Use this if you need to explicitly throw a GError or re-throw an existing
GError that you do not wish to handle.
|
|
Checking for GErrors returned by glib/gtk functions
|
|
- Note, these functions are only useful to implementors
If you are wrapping a new API that reports GErrors you should probably
use propagateGError to convert the GError into an exception. You should
also note in the documentation for the function that it throws GError
exceptions and the Haskell enumeration for the expected glib GError
domain(s), so that users know what exceptions they might want to catch.
If you think it is more appropriate to use an alternate return value (eg
Either/Maybe) then you should use checkGError.
|
|
|
Each error domain's error enumeration type should be an instance of this
class. This class helps to hide the raw error and domain codes from the
user. This interface should be implemented by calling the approrpiate
{error_domain}_error_quark. It is safe to use a pure FFI call for this.
Example for Graphics.UI.Gtk.Gdk.Pixbuf.PixbufError:
instance GErrorClass PixbufError where
gerrorDomain _ = {#call pure unsafe pixbuf_error_quark#}
| | Methods | |
|
|
|
Glib functions which report GErrors take as a parameter a GError
**error. Use this function to supply such a parameter. It checks if an
error was reported and if so throws it as a Haskell exception.
Example of use:
propagateGError $ \gerrorPtr ->
{# call g_some_function_that_might_return_an_error #} a b gerrorPtr
|
|
|
Like propagateGError but instead of throwing the GError as an exception
handles the error immediately using the supplied error handler.
Example of use:
checkGError
(\gerrorPtr -> {# call g_some_function_that_might_return_an_error #} a b gerrorPtr)
(\(GError domain code msg) -> ...)
|
|
Produced by Haddock version 2.6.0 |