Table of Contents

Class Qml

Namespace
Qt.Quick
Assembly
Qt.Bridge.CSharp.Api.dll

Provides the static entry point for loading QML components and running the Qt application event loop from C#.

public static class Qml
Inheritance
Qml
Inherited Members

Remarks

Qml is the primary API for bootstrapping a Qt Bridge application. A typical application loads one or more QML components by URI and type name, then blocks on WaitForExit(int) until the user closes the window. 

static void Main(string[] args)
{
    Qml.LoadFromRootModule("MainWindow");
    Qml.WaitForExit();
}

Properties

RootModule

Gets the URI of the root QML module defined in the entry assembly.

public static string RootModule { get; }

Property Value

string

Remarks

The root module is identified by the Qt.Quick.QmlModuleAttribute with Qt.Quick.QmlModuleAttribute.IsRoot set to true. This attribute is generated automatically for the application's primary QML module.

Exceptions

InvalidOperationException

No root module was found in the entry assembly.

Methods

LoadFromModule(string, string)

Loads a QML component by module URI and type name.

public static void LoadFromModule(string uri, string typeName)

Parameters

uri string

The URI of the QML module that contains the component.

typeName string

The QML type name to load. The type name is normalized to PascalCase to match Qt's naming convention for QML types. For example, "mainWindow" becomes "MainWindow".

Remarks

Multiple components can be loaded before calling WaitForExit(int):

static void Main(string[] args)
{
    Qml.LoadFromModule("MyApp.Views", "ListView");
    Qml.LoadFromModule("MyApp.Views", "TableView");
    Qml.WaitForExit();
}

LoadFromRootModule(string)

Loads a QML component by type name from the application's root module.

public static void LoadFromRootModule(string typeName)

Parameters

typeName string

The QML type name to load. The type name is normalized to PascalCase to match Qt's naming convention for QML types. For example, "mainWindow" becomes "MainWindow".

Remarks

Convenience wrapper around LoadFromModule(string, string) that uses RootModule as the module URI. Most applications have a single root module and call this method once with the top-level window component.

See Also

ProcessEvents()

Pumps the Qt event loop from the main thread, keeping the UI responsive during long-running C# operations.

public static void ProcessEvents()

Remarks

This method must be called from the main thread.

The intended use is inside a C# method called by QML that takes a noticeable amount of time. Calling ProcessEvents() periodically prevents the UI from freezing while the operation completes: 

public void ImportData(string path)
{
    foreach (var record in ReadRecords(path)) {
        ProcessRecord(record);
        Qml.ProcessEvents(); // keep the UI alive
    }
}

WaitForExit(int)

Blocks the calling thread until the QML engine exits or the optional timeout elapses.

public static bool WaitForExit(int timeout = -1)

Parameters

timeout int

Maximum time to wait, in milliseconds. The default value of -1 waits indefinitely until the QML engine exits.

Returns

bool

true if the QML engine has exited; false if the timeout elapsed before the engine exited.

Remarks

A finite timeout makes it possible to interleave C# work with the event loop. A common pattern is a polling loop that modifies model data between short waits:

static void Main(string[] args)
{
    Qml.LoadFromRootModule("Main");
    while (!Qml.WaitForExit(100)) {
        // update model data while the UI remains responsive
    }
}