Class ComponentInstance¶

Defined in File slint-interpreter.h

Inheritance Relationships¶

Base Type¶

private vtable::Dyn

Class Documentation¶

class ComponentInstance : private vtable::Dyn¶

The ComponentInstance represents a running instance of a component.

You can create an instance with the ComponentDefinition::create() function.

Properties and callback can be accessed using the associated functions.

An instance can be put on screen with the ComponentInstance::show() or the ComponentInstance::run()

Public Functions

inline void show() const¶: Marks the window of this component to be shown on the screen. This registers the window with the windowing system. In order to react to events from the windowing system, such as draw requests or mouse/touch input, it is still necessary to spin the event loop, using slint::run_event_loop().

inline void hide() const¶: Marks the window of this component to be hidden on the screen. This de-registers the window from the windowing system and it will not receive any further events.

inline const slint::Window &window()¶: Returns the Window associated with this component. The window API can be used to control different aspects of the integration into the windowing system, such as the position on the screen.

inline void run() const¶: This is a convenience function that first calls show(), followed by slint::run_event_loop() and hide().

inline QWidget *qwidget() const¶: Return a QWidget for this instance. This function is only available if the qt graphical backend was compiled in, and it may return nullptr if the Qt backend is not used at runtime.

inline bool set_property(std::string_view name, const Value &value) const¶

Set the value for a public property of this component

For example, if the component has a property <string> hello;, we can set this property

instance->set_property("hello", slint::SharedString("world"));

Returns true if the property was correctly set. Returns false if the property could not be set because it either do not exist (was not declared in .slint) or if the value is not of the proper type for the property’s type.

inline std::optional<Value> get_property(std::string_view name) const¶: Returns the value behind a property declared in .slint.

inline std::optional<Value> invoke(std::string_view name, std::span<const Value> args) const¶

Invoke the specified callback or function declared in .slint with the given arguments

Example: imagine the .slint file contains the given callback declaration:

callback foo(string, int) -> string;

Then one can call it with this function

slint::Value args[] = { SharedString("Hello"), 42. };
instance->invoke("foo", { args, 2 });

Returns an null optional if the callback don’t exist or if the argument don’t match Otherwise return the returned value from the callback, which may be an empty Value if the callback did not return a value.

template<std::invocable<std::span<const Value>> F> inline auto set_callback(std::string_view name, F callback) const -> bool¶

Set a handler for the callback with the given name.

A callback with that name must be defined in the document otherwise the function returns false.

The callback parameter is a functor which takes as argument a slice of Value and must return a Value.

Example: imagine the .slint file contains the given callback declaration:

callback foo(string, int) -> string;

Then one can set the callback handler with this function

instance->set_callback("foo", [](auto args) {
   std::cout << "foo(" << *args[0].to_string() << ", " << *args[1].to_number() << ")\n";
});

Note: Since the ComponentInstance holds the handler, the handler itself should not capture a strong reference to the instance.

inline bool set_global_property(std::string_view global, std::string_view prop_name, const Value &value) const¶

Set the value for a property within an exported global singleton.

For example, if the main file has an exported global TheGlobal with a property <int> hello, we can set this property

instance->set_global_property("TheGlobal", "hello", 42);

Returns true if the property was correctly set. Returns false if the property could not be set because it either does not exist (was not declared in .slint) or if the value is not of the correct type for the property’s type.

Note: Only globals that are exported or re-exported from the main .slint file will be accessible

inline std::optional<Value> get_global_property(std::string_view global, std::string_view prop_name) const¶: Returns the value behind a property in an exported global singleton.

template<std::invocable<std::span<const Value>> F> inline bool set_global_callback(std::string_view global, std::string_view name, F callback) const¶

Like set_callback() but on a callback in the specified exported global singleton.

Example: imagine the .slint file contains the given global:

,no-preview
  export global Logic {
       pure callback to_uppercase(string) -> string;
  }

Then you can set the callback handler

instance->set_global_callback("Logic", "to_uppercase", [](auto args) {
    std::string arg1(*args[0].to_string());
    std::transform(arg1.begin(), arg1.end(), arg1.begin(), toupper);
    return SharedString(arg1);
})

Note: Only globals that are exported or re-exported from the main .slint file will be accessible

inline std::optional<Value> invoke_global(std::string_view global, std::string_view callable_name, std::span<const Value> args) const¶: Invoke the specified callback or function declared in an exported global singleton.

inline ComponentDefinition definition() const¶: Return the ComponentDefinition that was used to create this instance.