Graphics.QML.Engine

Functions for starting QML engines, displaying content in a window.

Engines

data EngineConfig

Holds parameters for configuring a QML runtime engine.

Constructors

EngineConfig

Fields

• initialDocument :: DocumentPath

  Path to the first QML document to be loaded.

• contextObject :: Maybe AnyObjRef

  Context Object made available to QML script code.

• importPaths :: [FilePath]

  Additional search paths for QML modules

• pluginPaths :: [FilePath]

  Additional search paths for QML native plugins

defaultEngineConfig :: EngineConfig

Default engine configuration. Loads "main.qml" from the current working directory into a visible window with no context object.

data Engine

Represents a QML engine.

runEngine :: EngineConfig -> RunQML ()

Starts a new QML engine using the supplied configuration and blocks until the engine has terminated.

runEngineWith :: EngineConfig -> (Engine -> RunQML a) -> RunQML a

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.

runEngineAsync :: EngineConfig -> RunQML Engine

Starts a new QML engine using the supplied configuration and returns immediately without blocking.

runEngineLoop :: EngineConfig -> IO ()

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.

joinEngine :: Engine -> IO ()

Waits for the specified Engine to terminate.

killEngine :: Engine -> IO ()

Kills the specified Engine asynchronously.

Event Loop

data RunQML a

Wrapper around the IO monad for running actions which depend on the Qt event loop.

Instances

Monad RunQML

Methods

(>>=) :: RunQML a -> (a -> RunQML b) -> RunQML b

(>>) :: RunQML a -> RunQML b -> RunQML b

return :: a -> RunQML a

fail :: String -> RunQML a

Functor RunQML

Methods

fmap :: (a -> b) -> RunQML a -> RunQML b

(<$) :: a -> RunQML b -> RunQML a

Applicative RunQML

Methods

pure :: a -> RunQML a

(<*>) :: RunQML (a -> b) -> RunQML a -> RunQML b

liftA2 :: (a -> b -> c) -> RunQML a -> RunQML b -> RunQML c

(*>) :: RunQML a -> RunQML b -> RunQML b

(<*) :: RunQML a -> RunQML b -> RunQML a

MonadIO RunQML

Methods

liftIO :: IO a -> RunQML a

runEventLoop :: RunQML a -> IO a

This function enters the Qt event loop and executes the supplied function in the RunQML monad on a new unbound thread. The event loop will continue to run until all functions in the RunQML monad have completed. This includes both the RunQML function launched by this call and any launched asynchronously via requireEventLoop. 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 EventLoopException will be thrown.

If the event loop is entered for the first time then the currently set runtime command line arguments will be passed to Qt. Hence, while calling back to the supplied function, attempts to read the runtime command line arguments using the System.Environment module will only return those arguments not already consumed by Qt (per getQtArgs).

runEventLoopNoArgs :: RunQML a -> IO a

Enters the Qt event loop in the same manner as runEventLoop, but does not perform any processing related to command line arguments.

requireEventLoop :: RunQML a -> IO a

Executes a function in the RunQML 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 EventLoopException will be thrown. The event loop will not exit until the supplied function has completed.

setQtArgs :: String -> [String] -> IO Bool

Sets the program name and command line arguments used by Qt and returns True if successful. This must be called before the first time the Qt event loop is entered otherwise it will have no effect and return False. By default Qt receives no arguments and the program name is set to HsQML.

getQtArgs :: RunQML (String, [String])

Gets the program name and any command line arguments remaining from an earlier call to setQtArgs once Qt has removed any it understands, leaving only application specific arguments.

data QtFlag

Represents a Qt application flag.

Constructors

QtShareOpenGLContexts

Enables resource sharing between OpenGL contexts. This must be set in order to use QtWebEngine.

Instances

Show QtFlag

Methods

showsPrec :: Int -> QtFlag -> ShowS

show :: QtFlag -> String

showList :: [QtFlag] -> ShowS

setQtFlag :: QtFlag -> Bool -> IO Bool

Sets or clears one of the application flags used by Qt and returns True if successful. If the flag or flag value is not supported then it will return False. Setting flags once the Qt event loop is entered is unsupported and will also cause this function to return False.

getQtFlag :: QtFlag -> RunQML Bool

Gets the state of one of the application flags used by Qt.

shutdownQt :: IO ()

Shuts down and frees resources used by the Qt framework, preventing further use of the event loop. The framework is initialised when runEventLoop 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 EventLoopException will be thrown.

data EventLoopException

Exception type used to report errors pertaining to the event loop.

Instances

Show EventLoopException

Methods

showsPrec :: Int -> EventLoopException -> ShowS

show :: EventLoopException -> String

showList :: [EventLoopException] -> ShowS

Exception EventLoopException

Methods

toException :: EventLoopException -> SomeException

fromException :: SomeException -> Maybe EventLoopException

displayException :: EventLoopException -> String

Document Paths

data DocumentPath

Path to a QML document file.

fileDocument :: FilePath -> DocumentPath

Converts a local file path into a DocumentPath.

uriDocument :: String -> DocumentPath

Converts a URI string into a DocumentPath.