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


-- | Haskell binding for Qt Quick
--   
--   A Haskell binding for Qt Quick, a cross-platform framework for
--   creating graphical user interfaces. For further information on
--   installing and using this library, please see the project's web site.
@package hsqml
@version 0.3.3.0


-- | Parameter Name Lists
module Graphics.QML.Objects.ParamNames

-- | Represents a list of parameter names. The number of names in the list
--   is statically encoded using the length of the function type held in
--   the type parameter <tt>a</tt>.
data ParamNames a

-- | Coverts a <a>ParamNames</a> list to an ordinary list of strings.
paramNames :: ParamNames a -> [String]

-- | An empty <a>ParamNames</a> list.
noNames :: ParamNames ()

-- | Produces a <a>ParamNames</a> list with a single name.
fstName :: String -> ParamNames (String -> ())

-- | Adds one parameter name to a <a>ParamNames</a> list.
plusName :: ParamNames a -> String -> ParamNames (String -> a)

-- | Polymorphically produces <a>ParamNames</a> lists of any length filled
--   with blank parameter names.
anonParams :: AnonParams a => ParamNames a

-- | Helper class for generating anonymous parameter lists.
class AnonParams a
instance AnonParams ()
instance AnonParams b => AnonParams (String -> b)
instance Show (ParamNames a)


-- | Debug Options
module Graphics.QML.Debug

-- | Sets the global debug log level. At level zero, no logging information
--   will be printed. Higher levels will increase debug verbosity.
setDebugLogLevel :: Int -> IO ()


-- | Facilities for working with weak references, finalisers, and factory
--   pools.
module Graphics.QML.Objects.Weak

-- | Represents a weak reference to a QML object which wraps the type
--   <tt>tt</tt>.
--   
--   Unlike ordinary strong references, a weak reference does not prevent
--   the QML garbage collector from collecting the underlying object. Weak
--   references can be used to monitor the life cycles of QML objects.
data WeakObjRef tt

-- | Converts a strong <a>ObjRef</a> into a <a>WeakObjRef</a>.
toWeakObjRef :: ObjRef tt -> IO (WeakObjRef tt)

-- | Converts a <a>WeakObjRef</a> into a strong <a>ObjRef</a>.
--   
--   If the underlying QML object has already been collected then the
--   resulting <a>ObjRef</a> can be used to reincarnate it.
fromWeakObjRef :: WeakObjRef tt -> IO (ObjRef tt)

-- | Represents an object finaliser function for QML objects which wrap the
--   type <tt>tt</tt>.
data ObjFinaliser tt

-- | Create a new object finaliser from a finaliser function.
--   
--   Note that at the time the finaliser is called the runtime will have
--   already comitted to collecting the underlying QML object. The
--   <a>ObjRef</a> passed into the finaliser can be used to reincarnate the
--   object, but this QML object will have a distinct identity to the
--   original.
newObjFinaliser :: (ObjRef tt -> IO ()) -> IO (ObjFinaliser tt)

-- | Adds an object finaliser to an QML object.
--   
--   The finaliser will be called no more than once for each time it was
--   added to an object. The timing of finaliser execution is subject to
--   the combined behaviour of the Haskell and QML garbage collectors. All
--   outstanding finalisers will be run when the QML engine is terminated
--   provided that the program does not prematurely exit.
addObjFinaliser :: ObjFinaliser tt -> ObjRef tt -> IO ()

-- | Represents an object factory which maintains a one-to-one mapping
--   between values of type <tt>tt</tt> and QML object instances.
--   
--   <a>ObjRef</a>s manufactured by the pool are cached using the wrapped
--   type <tt>tt</tt> as the lookup key in an ordered map. The pool uses
--   weak references to automatically purge objects which no longer have
--   any strong references leading to them from either Haskell or QML code.
data FactoryPool tt

-- | Creates a new <a>FactoryPool</a> using the supplied factory function.
newFactoryPool :: Ord tt => (tt -> IO (ObjRef tt)) -> IO (FactoryPool tt)

-- | Return the pool's canonical QML object for a value of <tt>tt</tt>,
--   either by creating it or looking it up in the pool's cache of objects.
getPoolObject :: Ord tt => FactoryPool tt -> tt -> IO (ObjRef tt)


-- | Facilities for defining new object types which can be marshalled
--   between Haskell and QML.
module Graphics.QML.Objects

-- | Represents an instance of the QML class which wraps the type
--   <tt>tt</tt>.
data ObjRef tt

-- | Creates a QML object given a <a>Class</a> and a Haskell value of type
--   <tt>tt</tt>.
newObject :: Class tt -> tt -> IO (ObjRef tt)

-- | Creates a QML object given a Haskell value of type <tt>tt</tt> which
--   has a <a>DefaultClass</a> instance.
newObjectDC :: DefaultClass tt => tt -> IO (ObjRef tt)

-- | Returns the associated value of the underlying Haskell type
--   <tt>tt</tt> from an instance of the QML class which wraps it.
fromObjRef :: ObjRef tt -> tt

-- | Represents an instance of a QML class which wraps an arbitrary Haskell
--   type. Unlike <a>ObjRef</a>, an <a>AnyObjRef</a> only carries the type
--   of its Haskell value dynamically and does not encode it into the
--   static type.
data AnyObjRef

-- | Upcasts an <a>ObjRef</a> into an <a>AnyObjRef</a>.
anyObjRef :: ObjRef tt -> AnyObjRef

-- | Attempts to downcast an <a>AnyObjRef</a> into an <a>ObjRef</a> with
--   the specific underlying Haskell type <tt>tt</tt>.
fromAnyObjRef :: Typeable tt => AnyObjRef -> Maybe (ObjRef tt)

-- | Represents a QML class which wraps the type <tt>tt</tt>.
data Class tt

-- | Creates a new QML class for the type <tt>tt</tt>.
newClass :: Typeable tt => [Member tt] -> IO (Class tt)

-- | The class <a>DefaultClass</a> specifies a standard class definition
--   for the type <tt>tt</tt>.
class Typeable tt => DefaultClass tt
classMembers :: DefaultClass tt => [Member tt]

-- | Represents a named member of the QML class which wraps type
--   <tt>tt</tt>.
data Member tt

-- | Defines a named method using a function <tt>f</tt> in the IO monad.
--   
--   The first argument to <tt>f</tt> receives the "this" object and hence
--   must match the type of the class on which the method is being defined.
--   Subsequently, there may be zero or more parameter arguments followed
--   by an optional return argument in the IO monad.
defMethod :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, MethodSuffix ms) => String -> (tt -> ms) -> Member (GetObjType tt)

-- | Alias of <a>defMethod</a> which is less polymorphic to reduce the need
--   for type signatures.
defMethod' :: (Typeable obj, MethodSuffix ms) => String -> (ObjRef obj -> ms) -> Member obj

-- | Supports marshalling Haskell functions with an arbitrary number of
--   arguments.
class MethodSuffix a

-- | Defines a named signal. The signal is identified in subsequent calls
--   to <a>fireSignal</a> using a <a>SignalKeyValue</a>. This can be either
--   i) type-based using <a>Proxy</a> <tt>sk</tt> where <tt>sk</tt> is an
--   instance of the <a>SignalKeyClass</a> class or ii) value-based using a
--   <a>SignalKey</a> value creating using <a>newSignalKey</a>.
defSignal :: SignalKeyValue skv => String -> skv -> Member obj

-- | Defines a named signal with named parameters. This is otherwise
--   identical to <a>defSignal</a>, but allows QML code to reference signal
--   parameters by-name in addition to by-position.
defSignalNamedParams :: SignalKeyValue skv => String -> skv -> ParamNames (SignalParamNames (SignalValueParams skv)) -> Member obj

-- | Fires a signal defined on an object instance. The signal is identified
--   using either a type- or value-based signal key, as described in the
--   documentation for <a>defSignal</a>. The first argument is the signal
--   key, the second is the object, and the remaining arguments, if any,
--   are the arguments to the signal as specified by the signal key.
--   
--   If this function is called using a signal key which doesn't match a
--   signal defined on the supplied object, it will silently do nothing.
--   
--   This function is safe to call from any thread. Any attached signal
--   handlers will be executed asynchronously on the event loop thread.
fireSignal :: (Marshal tt, CanPassTo tt ~ Yes, IsObjType tt ~ Yes, SignalKeyValue skv) => skv -> tt -> SignalValueParams skv

-- | Values of the type <a>SignalKey</a> identify distinct signals by
--   value. The type parameter <tt>p</tt> specifies the signal's signature.
data SignalKey p

-- | Creates a new <a>SignalKey</a>.
newSignalKey :: SignalSuffix p => IO (SignalKey p)

-- | Instances of the <a>SignalKeyClass</a> class identify distinct signals
--   by type. The associated <a>SignalParams</a> type specifies the
--   signal's signature.
class SignalSuffix (SignalParams sk) => SignalKeyClass sk where type family SignalParams sk

-- | Supports marshalling an arbitrary number of arguments into a QML
--   signal.
class AnonParams (SignalParamNames ss) => SignalSuffix ss

-- | Defines a named constant property using an accessor function in the IO
--   monad.
defPropertyConst :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, Marshal tr, CanReturnTo tr ~ Yes) => String -> (tt -> IO tr) -> Member (GetObjType tt)

-- | Defines a named read-only property using an accessor function in the
--   IO monad.
defPropertyRO :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, Marshal tr, CanReturnTo tr ~ Yes) => String -> (tt -> IO tr) -> Member (GetObjType tt)

-- | Defines a named read-only property with an associated signal.
defPropertySigRO :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, Marshal tr, CanReturnTo tr ~ Yes, SignalKeyValue skv) => String -> skv -> (tt -> IO tr) -> Member (GetObjType tt)

-- | Defines a named read-write property using a pair of accessor and
--   mutator functions in the IO monad.
defPropertyRW :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, Marshal tr, CanReturnTo tr ~ Yes, CanGetFrom tr ~ Yes) => String -> (tt -> IO tr) -> (tt -> tr -> IO ()) -> Member (GetObjType tt)

-- | Defines a named read-write property with an associated signal.
defPropertySigRW :: (Marshal tt, CanGetFrom tt ~ Yes, IsObjType tt ~ Yes, Marshal tr, CanReturnTo tr ~ Yes, CanGetFrom tr ~ Yes, SignalKeyValue skv) => String -> skv -> (tt -> IO tr) -> (tt -> tr -> IO ()) -> Member (GetObjType tt)

-- | Alias of <a>defPropertyConst</a> which is less polymorphic to reduce
--   the need for type signatures.
defPropertyConst' :: (Typeable obj, Marshal tr, CanReturnTo tr ~ Yes) => String -> (ObjRef obj -> IO tr) -> Member obj

-- | Alias of <a>defPropertyRO</a> which is less polymorphic to reduce the
--   need for type signatures.
defPropertyRO' :: (Typeable obj, Marshal tr, CanReturnTo tr ~ Yes) => String -> (ObjRef obj -> IO tr) -> Member obj

-- | Alias of <a>defPropertySigRO</a> which is less polymorphic to reduce
--   the need for type signatures.
defPropertySigRO' :: (Typeable obj, Marshal tr, CanReturnTo tr ~ Yes, SignalKeyValue skv) => String -> skv -> (ObjRef obj -> IO tr) -> Member obj

-- | Alias of <a>defPropertyRW</a> which is less polymorphic to reduce the
--   need for type signatures.
defPropertyRW' :: (Typeable obj, Marshal tr, CanReturnTo tr ~ Yes, CanGetFrom tr ~ Yes) => String -> (ObjRef obj -> IO tr) -> (ObjRef obj -> tr -> IO ()) -> Member obj

-- | Alias of <a>defPropertySigRW</a> which is less polymorphic to reduce
--   the need for type signatures.
defPropertySigRW' :: (Typeable obj, Marshal tr, CanReturnTo tr ~ Yes, CanGetFrom tr ~ Yes, SignalKeyValue skv) => String -> skv -> (ObjRef obj -> IO tr) -> (ObjRef obj -> tr -> IO ()) -> Member obj
instance SignalSuffix (IO ())
instance (Marshal a, CanPassTo a ~ Yes, SignalSuffix b) => SignalSuffix (a -> b)
instance SignalSuffix p => SignalKeyValue (SignalKey p)
instance (SignalKeyClass sk, Typeable sk) => SignalKeyValue (Proxy sk)
instance IsVoidIO VoidIO
instance IsVoidIO b => IsVoidIO (a -> b)
instance MethodSuffix VoidIO
instance (Marshal a, CanReturnTo a ~ Yes) => MethodSuffix (IO a)
instance (Marshal a, CanGetFrom a ~ Yes, MethodSuffix b) => MethodSuffix (a -> b)


-- | Type classs and instances for marshalling values between Haskell and
--   QML.
module Graphics.QML.Marshal

-- | The class <a>Marshal</a> allows Haskell values to be marshalled to and
--   from the QML environment.
class Marshal t where type family MarshalMode t c d
marshaller :: Marshal t => MarshallerFor t

-- | <a>MarshalMode</a> for non-object types with bidirectional
--   marshalling.

-- | <a>MarshalMode</a> for non-object types with from-only marshalling.

-- | <a>MarshalMode</a> for non-object types with to-only marshalling.

-- | <a>MarshalMode</a> for void in method returns.

-- | <a>MarshalMode</a> for object types with bidirectional marshalling.

-- | <a>MarshalMode</a> for object types with from-only marshalling.

-- | <a>MarshalMode</a> for object types with to-only marshalling.

-- | Type value indicating a capability is supported.
data Yes

-- | Type function equal to <a>Yes</a> if the marshallable type <tt>t</tt>
--   supports being received from QML.
type CanGetFrom t = MarshalMode t ICanGetFrom ()

-- | Type index into <a>MarshalMode</a> for querying if the mode supports
--   receiving values from QML.
data ICanGetFrom

-- | Type function equal to <a>Yes</a> if the marshallable type <tt>t</tt>
--   supports being passed to QML.
type CanPassTo t = MarshalMode t ICanPassTo ()

-- | Type index into <a>MarshalMode</a> for querying if the mode supports
--   passing values to QML.
data ICanPassTo

-- | Type function equal to <a>Yes</a> if the marshallable type <tt>t</tt>
--   supports being returned to QML.
type CanReturnTo t = MarshalMode t ICanReturnTo ()

-- | Type index into <a>MarshalMode</a> for querying if the mode supports
--   returning values to QML.
data ICanReturnTo

-- | Type function equal to <a>Yes</a> if the marshallable type <tt>t</tt>
--   is an object.
type IsObjType t = MarshalMode t IIsObjType ()

-- | Type index into <a>MarshalMode</a> for querying if the mode supports
--   an object type.
data IIsObjType

-- | Type function which returns the type encapsulated by the object
--   handles used by the marshallable type <tt>t</tt>.
type GetObjType t = MarshalMode t IGetObjType ()

-- | Type index into <a>MarshalMode</a> for querying the type encapsulated
--   by the mode's object handles.
data IGetObjType

-- | Encapsulates the functionality to needed to implement an instance of
--   <a>Marshal</a> so that such instances can be defined without access to
--   implementation details.
data Marshaller t u v w x y

-- | Represents an argument whose value is ignored.
data Ignored
Ignored :: Ignored

-- | Provides a bidirectional <a>Marshaller</a> which allows you to define
--   an instance of <a>Marshal</a> for your own type <tt>b</tt> in terms of
--   another marshallable type <tt>a</tt>. Type <tt>b</tt> should have a
--   <a>MarshalMode</a> of <a>ModeObjBidi</a> or <a>ModeBidi</a> depending
--   on whether <tt>a</tt> was an object type or not.
bidiMarshallerIO :: (Marshal a, CanGetFrom a ~ Yes, CanPassTo a ~ Yes) => (a -> IO b) -> (b -> IO a) -> BidiMarshaller a b

-- | Variant of <a>bidiMarshallerIO</a> where the conversion functions
--   between types <tt>a</tt> and <tt>b</tt> do not live in the IO monad.
bidiMarshaller :: (Marshal a, CanGetFrom a ~ Yes, CanPassTo a ~ Yes) => (a -> b) -> (b -> a) -> BidiMarshaller a b

-- | Provides a "from" <a>Marshaller</a> which allows you to define an
--   instance of <a>Marshal</a> for your own type <tt>b</tt> in terms of
--   another marshallable type <tt>a</tt>. Type <tt>b</tt> should have a
--   <a>MarshalMode</a> of <a>ModeObjFrom</a> or <a>ModeFrom</a> depending
--   on whether <tt>a</tt> was an object type or not.
fromMarshallerIO :: (Marshal a, CanGetFrom a ~ Yes) => (a -> IO b) -> FromMarshaller a b

-- | Variant of <a>fromMarshallerIO</a> where the conversion function
--   between types <tt>a</tt> and <tt>b</tt> does not live in the IO monad.
fromMarshaller :: (Marshal a, CanGetFrom a ~ Yes) => (a -> b) -> FromMarshaller a b

-- | Provides a "to" <a>Marshaller</a> which allows you to define an
--   instance of <a>Marshal</a> for your own type <tt>b</tt> in terms of
--   another marshallable type <tt>a</tt>. Type <tt>b</tt> should have a
--   <a>MarshalMode</a> of <a>ModeObjTo</a> or <a>ModeTo</a> depending on
--   whether <tt>a</tt> was an object type or not.
toMarshallerIO :: (Marshal a, CanPassTo a ~ Yes) => (b -> IO a) -> ToMarshaller a b

-- | Variant of <a>toMarshallerIO</a> where the conversion function between
--   types <tt>a</tt> and <tt>b</tt> does not live in the IO monad.
toMarshaller :: (Marshal a, CanPassTo a ~ Yes) => (b -> a) -> ToMarshaller a b
instance Marshal Ignored
instance Marshal a => Marshal [a]
instance Marshal a => Marshal (Maybe a)
instance Marshal Text
instance Marshal Double
instance Marshal Int
instance Marshal Int32
instance Marshal Bool


-- | Facility for drawing OpenGL graphics into the QML scenegraph.
--   
--   To use this facility, you must place a <tt>HaskellCanvas</tt> item
--   into your QML scene. This item can be imported from the
--   <tt>HsQML.Canvas 1.0</tt> module using an <tt>import</tt> statement in
--   your QML script. It has several properties which can be set from QML:
--   
--   <ul>
--   <li><i><tt>displayMode</tt></i> Specifies how the canvas is rendered
--   with respect to the rest of the scene. Possible values
--   are:<ul><li><i><tt>HaskellCanvas.Above</tt></i> The canvas shares a
--   buffer with the scenegraph and is painted top of other
--   items.</li><li><i><tt>HaskellCanvas.Inline</tt></i> The canvas has its
--   own framebuffer object and the contents of this buffer are painted
--   inline with other items
--   (default).</li><li><i><tt>HaskellCanvas.Below</tt></i> The canvas
--   shares a buffer with the scenegraph and is painted underneath other
--   items.</li></ul></li>
--   <li><i><tt>canvasWidth</tt></i> Width of the framebuffer object in
--   pixels. Defaults to the item width.</li>
--   <li><i><tt>canvasHeight</tt></i> Height of the framebuffer object in
--   pixels. Defaults to the item height.</li>
--   <li><i><tt>delegate</tt></i> A marshalled <a>OpenGLDelegate</a> value
--   which specifies the Haskell functions used to render the canvas.</li>
--   <li><i><tt>model</tt></i> A value passed to delegate's paint function.
--   The canvas is repainted whenever this value changes.</li>
--   <li><i><tt>status</tt></i> Either <tt>HaskellCanvas.Okay</tt> or an
--   error code (read only).</li>
--   </ul>
--   
--   The <tt>HsQML.Canvas 1.0</tt> module also contains another type of
--   item called <tt>OpenGLConextControl</tt> which can be used to
--   configure the OpenGL context used by your windows. When placed inside
--   a QML window, it has several properties which when read return the
--   current state of that window's OpenGL context, and when written to
--   cause the window's context to be reconfigured with a request for the
--   supplied setting. Note that as reconfiguring the context may cause a
--   visible window to dis- and re-appear, it's recommended to supply the
--   desired settings at startup or otherwise before the corresponding
--   window is made visible. Available properties are as below:
--   
--   <ul>
--   <li><i><tt>majorVersion</tt></i> Major component of the OpenGL
--   version.</li>
--   <li><i><tt>minorVersion</tt></i> Minor component of the OpenGL
--   version.</li>
--   <li><i><tt>contextType</tt></i> The type of OpenGL context. One of:
--   <tt>OpenGLContextControl.UnknownType</tt>,
--   <tt>OpenGLContextControl.OpenGL</tt>, or
--   <tt>OpenGLContextControl.OpenGLES</tt>.</li>
--   <li><i><tt>contextProfile</tt></i> The OpenGL context's profile. One
--   of: <tt>OpenGLContextControl.NoProfile</tt>,
--   <tt>OpenGLContextControl.CoreProfile</tt>, or
--   <tt>OpenGLContextControl.CompatibilityProfile</tt>.</li>
--   <li><i><tt>deprecatedFunctions</tt></i> True if deprecated functions
--   are available.</li>
--   <li><i><tt>depthBufferSize</tt></i> Depth buffer size in bits.</li>
--   <li><i><tt>stencilBufferSize</tt></i> Stencil buffer size in
--   bits.</li>
--   <li><i><tt>when</tt></i> Any changes to the OpenGL context while this
--   property is set to false will be deferred until it is true again. The
--   default value is true.</li>
--   </ul>
module Graphics.QML.Canvas

-- | Delegate for painting OpenGL graphics.
data OpenGLDelegate

-- | Creates a new <a>OpenGLDelegate</a> from setup, paint, and cleanup
--   functions.
newOpenGLDelegate :: (Marshal m, CanGetFrom m ~ Yes) => (OpenGLSetup -> IO i) -> (OpenGLPaint i m -> IO ()) -> (i -> IO ()) -> IO OpenGLDelegate

-- | Represents the type of an OpenGL context.
data OpenGLType

-- | Desktop OpenGL context.
OpenGLDesktop :: OpenGLType

-- | OpenGL ES context.
OpenGLES :: OpenGLType

-- | Encapsulates parameters for OpenGL setup.
data OpenGLSetup

-- | Type of OpenGL context.
openGLType :: OpenGLSetup -> OpenGLType

-- | Major version number of OpenGL context.
openGLMajor :: OpenGLSetup -> Int

-- | Minor version number of OpenGL context.
openGLMinor :: OpenGLSetup -> Int

-- | Encapsulates parameters for OpenGL paint.
data OpenGLPaint s m

-- | Specialised version of <a>OpenGLPaint</a> with no model.
type OpenGLPaint' s = OpenGLPaint s Ignored

-- | Gets the setup state.
setupData :: OpenGLPaint s m -> s

-- | Gets the active model.
modelData :: OpenGLPaint s m -> m

-- | Pointer to a 4 by 4 matrix which transform coordinates in the range
--   (-1, -1) to (1, 1) on to the target rectangle in the scene.
matrixPtr :: OpenGLPaint s m -> Ptr CFloat

-- | Width of the canvas item in its local coordinate system.
itemWidth :: OpenGLPaint s m -> Float

-- | Height of the canvas item in its local coordinate system.
itemHeight :: OpenGLPaint s m -> Float
instance Eq OpenGLType
instance Show OpenGLType
instance Marshal OpenGLDelegate


-- | Functions for starting QML engines, displaying content in a window.
module Graphics.QML.Engine

-- | Holds parameters for configuring a QML runtime engine.
data EngineConfig
EngineConfig :: DocumentPath -> Maybe AnyObjRef -> [FilePath] -> [FilePath] -> EngineConfig

-- | Path to the first QML document to be loaded.
initialDocument :: EngineConfig -> DocumentPath

-- | Context <tt>Object</tt> made available to QML script code.
contextObject :: EngineConfig -> Maybe AnyObjRef

-- | Additional search paths for QML modules
importPaths :: EngineConfig -> [FilePath]

-- | Additional search paths for QML native plugins
pluginPaths :: EngineConfig -> [FilePath]

-- | Default engine configuration. Loads <tt>"main.qml"</tt> from the
--   current working directory into a visible window with no context
--   object.
defaultEngineConfig :: EngineConfig

-- | Represents a QML engine.
data Engine

-- | Starts a new QML engine using the supplied configuration and blocks
--   until the engine has terminated.
runEngine :: EngineConfig -> RunQML ()

-- | Starts a new QML engine using the supplied configuration. The 'with'
--   function is executed once the engine has been started and after it
--   returns this function blocks until the engine has terminated.
runEngineWith :: EngineConfig -> (Engine -> RunQML a) -> RunQML a

-- | Starts a new QML engine using the supplied configuration and returns
--   immediately without blocking.
runEngineAsync :: EngineConfig -> RunQML Engine

-- | Conveniance function that both runs the event loop and starts a new
--   QML engine. It blocks keeping the event loop running until the engine
--   has terminated.
runEngineLoop :: EngineConfig -> IO ()

-- | Wrapper around the IO monad for running actions which depend on the Qt
--   event loop.
data RunQML a

-- | This function enters the Qt event loop and executes the supplied
--   function in the <a>RunQML</a> monad on a new unbound thread. The event
--   loop will continue to run until all functions in the <a>RunQML</a>
--   monad have completed. This includes both the <a>RunQML</a> function
--   launched by this call and any launched asynchronously via
--   <a>requireEventLoop</a>. When the event loop exits, all engines will
--   be terminated.
--   
--   It's recommended that applications run the event loop on their
--   primordial thread as some platforms mandate this. Once the event loop
--   has finished, it can be started again, but only on the same operating
--   system thread as before. If the event loop fails to start then an
--   <a>EventLoopException</a> will be thrown.
runEventLoop :: RunQML a -> IO a

-- | Executes a function in the <a>RunQML</a> monad asynchronously to the
--   event loop. Callers must apply their own sychronisation to ensure that
--   the event loop is currently running when this function is called,
--   otherwise an <a>EventLoopException</a> will be thrown. The event loop
--   will not exit until the supplied function has completed.
requireEventLoop :: RunQML a -> IO a

-- | Shuts down and frees resources used by the Qt framework, preventing
--   further use of the event loop. The framework is initialised when
--   <a>runEventLoop</a> is first called and remains initialised afterwards
--   so that the event loop can be reentered if desired (e.g. when using
--   GHCi). Once shut down, the framework cannot be reinitialised.
--   
--   It is recommended that you call this function at the end of your
--   program as this library will try, but cannot guarantee in all
--   configurations to be able to shut it down for you. Failing to shutdown
--   the framework has been known to intermittently cause crashes on
--   process exit on some platforms.
--   
--   This function must be called from the event loop thread and the event
--   loop must not be running at the time otherwise an
--   <a>EventLoopException</a> will be thrown.
shutdownQt :: IO ()

-- | Exception type used to report errors pertaining to the event loop.
data EventLoopException

-- | Path to a QML document file.
data DocumentPath

-- | Converts a local file path into a <a>DocumentPath</a>.
fileDocument :: FilePath -> DocumentPath

-- | Converts a URI string into a <a>DocumentPath</a>.
uriDocument :: String -> DocumentPath
instance Typeable EventLoopException
instance Functor RunQML
instance Applicative RunQML
instance Monad RunQML
instance Show EventLoopException
instance Exception EventLoopException
instance MonadIO RunQML


-- | This module imports the entire package, except <a>Debug</a>.
module Graphics.QML
