Module qmetaobject::connections [−][src]
Expand description
Signals, slots and connections between them.
First of all, make sure you read about Signals & Slots on Qt documentation website, then the series of articles about How Qt Signals and Slots Work on woboq blog.
This module implements several concepts related to Qt’s signals and slot mechanism such as wrappers for Qt types and extensions specific to Rust.
Key points:
- emitting signal is equivalent to just calling a method marked as such;
- signal method takes ownership over its arguments, and borrows them to connected slots;
- argument number zero (
a[0]) usually used to communicate returned value from the signal/slot back to the caller, but is currently ignored by this implementation;
Subclasses of QObject defined in Rust code declare their signals using qt_signal!
pseudo-macro. It generates both struct member and a method with the same name. Those members
will be generated as RustSignal<fn(...)> with appropriate generics, and calling
corresponding methods actually emits the signal which invokes all connected slots.
RustSignals are useless on their own, and in fact are only needed to take space in the
struct, so that we could take a reference to it. In order to use them, e.g. connect to a slot,
they must be converted into the corresponding Signal via to_cpp_representation
method.
Signal is a type-safe wrapper for the SignalInner, which in turn is what
Qt recognizes as a signal ID. For signals defined in C++ they are “a pointer to a member
function”, but for signals defined in Rust we are currently using RustSignal fields’ offsets
for that. SignalInner objects can be obtained both from objects defined in Rust
(by calling to_cpp_representation on their signal members), as well as from
objects defined in C++ and wrapped in Rust (by using cpp! macro).
Note: Currently neither Signal nor any other type hold the information about type of
object a signal belongs to, so care must be taken to ensure Signal is used to connect
the same type of objects it was derived from. It is surprising behavior to use signals
representations with non-related types. In the best case, specified signal would not be found
which would result in a warning; in the worst case, signal IDs may clash (e.g. same offset)
resulting in a warning about incompatible types or even connecting to a wrong function.
Signals connect to Slots. Slot can be any rust closure with compatible argument count
and types. This trait is implemented for up to ten arguments. In terms of Qt, there also
exist a return value of a slot, but it is ignored (assumed void) by current implementation.
Finally, function connect is used to connect Signals (obtained by any means either
from RustSignals defined on rust QObjects, or from Rust wrappers for C++ classes) to slots
(usual Rust closures with compatible argument count and types).
Implementation details
Many traits like Default, Copy etc are not derived but instead manually
implemented in this module because #[derive(...)] generated code like this:
impl<Args: Copy> Copy for ... { ... }
but we don’t want to require the Args: Copy constraint.
To learn more about internals, take a look at documentation in qmetaobject_rust.hpp source
file.
Structs
Wrapper for QMetaObject::Connection class.
Types of signals constructed with the qt_signal! macro.
High-level typed wrapper for a pointer to a C++/Qt signal.
Internal class that can be used to construct C++ signal. Should only be used as an implementation
details when writing bindings to Qt signals to construct a Signal<...>.
Traits
Convert a signal’s array of arguments into tuple.
Trait for slots that can be connected to Signal