Class ComponentInstance

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_callback(std::string_view name, std::span<const Value> args) const

Invoke the specified callback 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_callback("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<typename F>
inline bool set_callback(std::string_view name, F callback) const

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<typename 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: 

export global Logic := {
     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_callback(std::string_view global, std::string_view callback_name, std::span<const Value> args) const

Invoke the specified callback declared in an exported global singleton.