Trait ObjectExt

pub trait ObjectExt: ObjectType {
    // Required methods
    fn is<T: StaticType>(&self) -> bool;
    fn type_(&self) -> Type;
    fn object_class(&self) -> &ObjectClass;
    fn class(&self) -> &Class<Self>
       where Self: IsClass;
    fn class_of<T: IsClass>(&self) -> Option<&Class<T>>;
    fn interface<T: IsInterface>(&self) -> Option<InterfaceRef<'_, T>>;
    fn set_property(&self, property_name: &str, value: impl Into<Value>);
    fn set_property_from_value(&self, property_name: &str, value: &Value);
    fn set_properties(&self, property_values: &[(&str, &dyn ToValue)]);
    fn set_properties_from_value(&self, property_values: &[(&str, Value)]);
    fn property<V: for<'b> FromValue<'b> + 'static>(
        &self,
        property_name: &str,
    ) -> V;
    fn property_value(&self, property_name: &str) -> Value;
    fn has_property(&self, property_name: &str, type_: Option<Type>) -> bool;
    fn property_type(&self, property_name: &str) -> Option<Type>;
    fn find_property(&self, property_name: &str) -> Option<ParamSpec>;
    fn list_properties(&self) -> PtrSlice<ParamSpec>;
    fn freeze_notify(&self) -> PropertyNotificationFreezeGuard;
    unsafe fn set_qdata<QD: 'static>(&self, key: Quark, value: QD);
    unsafe fn qdata<QD: 'static>(&self, key: Quark) -> Option<NonNull<QD>>;
    unsafe fn steal_qdata<QD: 'static>(&self, key: Quark) -> Option<QD>;
    unsafe fn set_data<QD: 'static>(&self, key: &str, value: QD);
    unsafe fn data<QD: 'static>(&self, key: &str) -> Option<NonNull<QD>>;
    unsafe fn steal_data<QD: 'static>(&self, key: &str) -> Option<QD>;
    fn block_signal(&self, handler_id: &SignalHandlerId);
    fn unblock_signal(&self, handler_id: &SignalHandlerId);
    fn stop_signal_emission(&self, signal_id: SignalId, detail: Option<Quark>);
    fn stop_signal_emission_by_name(&self, signal_name: &str);
    fn connect<F>(
        &self,
        signal_name: &str,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static;
    fn connect_id<F>(
        &self,
        signal_id: SignalId,
        details: Option<Quark>,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static;
    fn connect_local<F>(
        &self,
        signal_name: &str,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value> + 'static;
    fn connect_local_id<F>(
        &self,
        signal_id: SignalId,
        details: Option<Quark>,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value> + 'static;
    unsafe fn connect_unsafe<F>(
        &self,
        signal_name: &str,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value>;
    unsafe fn connect_unsafe_id<F>(
        &self,
        signal_id: SignalId,
        details: Option<Quark>,
        after: bool,
        callback: F,
    ) -> SignalHandlerId
       where F: Fn(&[Value]) -> Option<Value>;
    fn connect_closure(
        &self,
        signal_name: &str,
        after: bool,
        closure: RustClosure,
    ) -> SignalHandlerId;
    fn connect_closure_id(
        &self,
        signal_id: SignalId,
        details: Option<Quark>,
        after: bool,
        closure: RustClosure,
    ) -> SignalHandlerId;
    fn watch_closure(&self, closure: &impl AsRef<Closure>);
    fn emit<R: TryFromClosureReturnValue>(
        &self,
        signal_id: SignalId,
        args: &[&dyn ToValue],
    ) -> R;
    fn emit_with_values(
        &self,
        signal_id: SignalId,
        args: &[Value],
    ) -> Option<Value>;
    fn emit_by_name<R: TryFromClosureReturnValue>(
        &self,
        signal_name: &str,
        args: &[&dyn ToValue],
    ) -> R;
    fn emit_by_name_with_values(
        &self,
        signal_name: &str,
        args: &[Value],
    ) -> Option<Value>;
    fn emit_by_name_with_details<R: TryFromClosureReturnValue>(
        &self,
        signal_name: &str,
        details: Quark,
        args: &[&dyn ToValue],
    ) -> R;
    fn emit_by_name_with_details_and_values(
        &self,
        signal_name: &str,
        details: Quark,
        args: &[Value],
    ) -> Option<Value>;
    fn emit_with_details<R: TryFromClosureReturnValue>(
        &self,
        signal_id: SignalId,
        details: Quark,
        args: &[&dyn ToValue],
    ) -> R;
    fn emit_with_details_and_values(
        &self,
        signal_id: SignalId,
        details: Quark,
        args: &[Value],
    ) -> Option<Value>;
    fn disconnect(&self, handler_id: SignalHandlerId);
    fn connect_notify<F: Fn(&Self, &ParamSpec) + Send + Sync + 'static>(
        &self,
        name: Option<&str>,
        f: F,
    ) -> SignalHandlerId;
    fn connect_notify_local<F: Fn(&Self, &ParamSpec) + 'static>(
        &self,
        name: Option<&str>,
        f: F,
    ) -> SignalHandlerId;
    unsafe fn connect_notify_unsafe<F: Fn(&Self, &ParamSpec)>(
        &self,
        name: Option<&str>,
        f: F,
    ) -> SignalHandlerId;
    fn notify(&self, property_name: &str);
    fn notify_by_pspec(&self, pspec: &ParamSpec);
    fn downgrade(&self) -> WeakRef<Self>;
    fn add_weak_ref_notify<F: FnOnce() + Send + 'static>(
        &self,
        f: F,
    ) -> WeakRefNotify<Self>;
    fn add_weak_ref_notify_local<F: FnOnce() + 'static>(
        &self,
        f: F,
    ) -> WeakRefNotify<Self>;
    fn bind_property<'a, 'f, 't, O: ObjectType>(
        &'a self,
        source_property: &'a str,
        target: &'a O,
        target_property: &'a str,
    ) -> BindingBuilder<'a, 'f, 't>;
    fn ref_count(&self) -> u32;
    unsafe fn run_dispose(&self);
}

Required Methods

fn is<T: StaticType>(&self) -> bool

Returns true if the object is an instance of (can be cast to) T.

fn type_(&self) -> Type

Returns the type of the object.

fn object_class(&self) -> &ObjectClass

Returns the ObjectClass of the object.

This is equivalent to calling obj.class().upcast_ref::<ObjectClass>().

fn class(&self) -> &Class<Self>

where Self: IsClass,

Returns the class of the object.

fn class_of<T: IsClass>(&self) -> Option<&Class<T>>

Returns the class of the object in the given type T.

None is returned if the object is not a subclass of T.

fn interface<T: IsInterface>(&self) -> Option<InterfaceRef<'_, T>>

Returns the interface T of the object.

None is returned if the object does not implement the interface T.

fn set_property(&self, property_name: &str, value: impl Into<Value>)

Sets the property property_name of the object to value value.

Panics

If the property does not exist, if the type of the property is different than the provided value, or if the property is not writable.

fn set_property_from_value(&self, property_name: &str, value: &Value)

Sets the property property_name of the object to value value.

Panics

If the property does not exist, the type of the property is different than the provided value, or if the property is not writable.

fn set_properties(&self, property_values: &[(&str, &dyn ToValue)])

Sets multiple properties of the object at once.

Panics

This does not set any properties if one or more properties don’t exist, values of the wrong type are provided, or if any of the properties is not writable.

fn set_properties_from_value(&self, property_values: &[(&str, Value)])

Sets multiple properties of the object at once.

Panics

This does not set any properties if one or more properties don’t exist, values of the wrong type are provided, or if any of the properties is not writable.

fn property<V: for<'b> FromValue<'b> + 'static>(&self, property_name: &str) -> V

Gets the property property_name of the object and cast it to the type V.

Panics

If the property doesn’t exist or is not readable or of a different type than V.

fn property_value(&self, property_name: &str) -> Value

Gets the property property_name of the object.

Panics

If the property does not exist or is not writable.

fn has_property(&self, property_name: &str, type_: Option<Type>) -> bool

Check if the object has a property property_name of the given type_.

If no type is provided then only the existence of the property is checked.

fn property_type(&self, property_name: &str) -> Option<Type>

Get the type of the property property_name of this object.

This returns None if the property does not exist.

fn find_property(&self, property_name: &str) -> Option<ParamSpec>

Get the ParamSpec of the property property_name of this object.

fn list_properties(&self) -> PtrSlice<ParamSpec>

Return all ParamSpec of the properties of this object.

fn freeze_notify(&self) -> PropertyNotificationFreezeGuard

Freeze all property notifications until the return guard object is dropped.

This prevents the notify signal for all properties of this object to be emitted.

unsafe fn set_qdata<QD: 'static>(&self, key: Quark, value: QD)

Set arbitrary data on this object with the given key.

Safety

This function doesn’t store type information

unsafe fn qdata<QD: 'static>(&self, key: Quark) -> Option<NonNull<QD>>

Return previously set arbitrary data of this object with the given key.

Safety

The returned pointer can become invalid by a call to set_qdata, steal_qdata, set_data or steal_data.

The caller is responsible for ensuring the returned value is of a suitable type

unsafe fn steal_qdata<QD: 'static>(&self, key: Quark) -> Option<QD>

Retrieve previously set arbitrary data of this object with the given key.

The data is not set on the object anymore afterwards.

Safety

The caller is responsible for ensuring the returned value is of a suitable type

unsafe fn set_data<QD: 'static>(&self, key: &str, value: QD)

Set arbitrary data on this object with the given key.

Safety

This function doesn’t store type information

unsafe fn data<QD: 'static>(&self, key: &str) -> Option<NonNull<QD>>

Return previously set arbitrary data of this object with the given key.

Safety

The returned pointer can become invalid by a call to set_qdata, steal_qdata, set_data or steal_data.

The caller is responsible for ensuring the returned value is of a suitable type

unsafe fn steal_data<QD: 'static>(&self, key: &str) -> Option<QD>

Retrieve previously set arbitrary data of this object with the given key.

The data is not set on the object anymore afterwards.

Safety

The caller is responsible for ensuring the returned value is of a suitable type

fn block_signal(&self, handler_id: &SignalHandlerId)

Block a given signal handler.

It will not be called again during signal emissions until it is unblocked.

fn unblock_signal(&self, handler_id: &SignalHandlerId)

Unblock a given signal handler.

fn stop_signal_emission(&self, signal_id: SignalId, detail: Option<Quark>)

Stop emission of the currently emitted signal.

fn stop_signal_emission_by_name(&self, signal_name: &str)

Stop emission of the currently emitted signal by the (possibly detailed) signal name.

fn connect<F>( &self, signal_name: &str, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static,

Connect to the signal signal_name on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Panics

If the signal does not exist.

fn connect_id<F>( &self, signal_id: SignalId, details: Option<Quark>, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static,

Connect to the signal signal_id on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Same as Self::connect but takes a SignalId instead of a signal name.

Panics

If the signal does not exist.

fn connect_local<F>( &self, signal_name: &str, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value> + 'static,

Connect to the signal signal_name on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Same as Self::connect but takes a non-Send+Sync closure. If the signal is emitted from a different thread than it was connected to then the signal emission will panic.

Panics

If the signal does not exist.

fn connect_local_id<F>( &self, signal_id: SignalId, details: Option<Quark>, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value> + 'static,

Connect to the signal signal_id on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Same as Self::connect_id but takes a non-Send+Sync closure. If the signal is emitted from a different thread than it was connected to then the signal emission will panic.

Panics

This panics if the signal does not exist.

unsafe fn connect_unsafe<F>( &self, signal_name: &str, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value>,

Connect to the signal signal_name on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Same as Self::connect but takes a non-Send+Sync and non-'static' closure. No runtime checks are performed for ensuring that the closure is called correctly.

Safety

The provided closure must be valid until the signal handler is disconnected, and it must be allowed to call the closure from the threads the signal is emitted from.

Panics

If the signal does not exist.

unsafe fn connect_unsafe_id<F>( &self, signal_id: SignalId, details: Option<Quark>, after: bool, callback: F, ) -> SignalHandlerId

where F: Fn(&[Value]) -> Option<Value>,

Connect to the signal signal_id on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

Same as Self::connect_id but takes a non-Send+Sync and non-'static' closure. No runtime checks are performed for ensuring that the closure is called correctly.

Safety

The provided closure must be valid until the signal handler is disconnected, and it must be allowed to call the closure from the threads the signal is emitted from.

Panics

If the signal does not exist.

fn connect_closure( &self, signal_name: &str, after: bool, closure: RustClosure, ) -> SignalHandlerId

Connect a closure to the signal signal_name on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

This panics if the signal does not exist.

A recurring case is connecting a handler which will be automatically disconnected when an object it refers to is destroyed, as it happens with g_signal_connect_object in C. This can be achieved with a closure that watches an object: see the documentation of the closure! macro for more details.

Same as Self::connect but takes a Closure instead of a Fn.

fn connect_closure_id( &self, signal_id: SignalId, details: Option<Quark>, after: bool, closure: RustClosure, ) -> SignalHandlerId

Connect a closure to the signal signal_id on this object.

If after is set to true then the callback will be called after the default class handler of the signal is emitted, otherwise before.

This panics if the signal does not exist.

Same as Self::connect_closure but takes a SignalId instead of a signal name.

fn watch_closure(&self, closure: &impl AsRef<Closure>)

Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to invoke_with_values, or invoke when using Rust closures.

fn emit<R: TryFromClosureReturnValue>( &self, signal_id: SignalId, args: &[&dyn ToValue], ) -> R

Emit signal by signal id.

If the signal has a return value then this is returned here.

Panics

If the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_with_values(&self, signal_id: SignalId, args: &[Value]) -> Option<Value>

Same as Self::emit but takes Value for the arguments.

fn emit_by_name<R: TryFromClosureReturnValue>( &self, signal_name: &str, args: &[&dyn ToValue], ) -> R

Emit signal by its name.

If the signal has a return value then this is returned here.

Panics

If the signal does not exist, the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_by_name_with_values( &self, signal_name: &str, args: &[Value], ) -> Option<Value>

Emit signal by its name.

If the signal has a return value then this is returned here.

Panics

If the signal does not exist, the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_by_name_with_details<R: TryFromClosureReturnValue>( &self, signal_name: &str, details: Quark, args: &[&dyn ToValue], ) -> R

Emit signal by its name with details.

If the signal has a return value then this is returned here.

Panics

If the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_by_name_with_details_and_values( &self, signal_name: &str, details: Quark, args: &[Value], ) -> Option<Value>

Emit signal by its name with details.

If the signal has a return value then this is returned here.

Panics

If the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_with_details<R: TryFromClosureReturnValue>( &self, signal_id: SignalId, details: Quark, args: &[&dyn ToValue], ) -> R

Emit signal by signal id with details.

If the signal has a return value then this is returned here.

Panics

If the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn emit_with_details_and_values( &self, signal_id: SignalId, details: Quark, args: &[Value], ) -> Option<Value>

Emit signal by signal id with details.

If the signal has a return value then this is returned here.

Panics

If the wrong number of arguments is provided, or arguments of the wrong types were provided.

fn disconnect(&self, handler_id: SignalHandlerId)

Disconnect a previously connected signal handler.

fn connect_notify<F: Fn(&Self, &ParamSpec) + Send + Sync + 'static>( &self, name: Option<&str>, f: F, ) -> SignalHandlerId

Connect to the notify signal of the object.

This is emitted whenever a property is changed. If name is provided then the signal handler is only called for this specific property.

fn connect_notify_local<F: Fn(&Self, &ParamSpec) + 'static>( &self, name: Option<&str>, f: F, ) -> SignalHandlerId

Connect to the notify signal of the object.

This is emitted whenever a property is changed. If name is provided then the signal handler is only called for this specific property.

This is like connect_notify but doesn’t require a Send+Sync closure. Signal emission will panic if the signal is emitted from the wrong thread.

unsafe fn connect_notify_unsafe<F: Fn(&Self, &ParamSpec)>( &self, name: Option<&str>, f: F, ) -> SignalHandlerId

Connect to the notify signal of the object.

This is emitted whenever a property is changed. If name is provided then the signal handler is only called for this specific property.

This is like connect_notify but doesn’t require a Send+Sync or 'static closure. No runtime checks for wrongly calling the closure are performed.

Safety

The provided closure must be valid until the signal handler is disconnected, and it must be allowed to call the closure from the threads the signal is emitted from.

fn notify(&self, property_name: &str)

Notify that the given property has changed its value.

This emits the notify signal.

fn notify_by_pspec(&self, pspec: &ParamSpec)

Notify that the given property has changed its value.

This emits the notify signal.

fn downgrade(&self) -> WeakRef<Self>

Downgrade this object to a weak reference.

fn add_weak_ref_notify<F: FnOnce() + Send + 'static>( &self, f: F, ) -> WeakRefNotify<Self>

Add a callback to be notified when the Object is disposed.

fn add_weak_ref_notify_local<F: FnOnce() + 'static>( &self, f: F, ) -> WeakRefNotify<Self>

Add a callback to be notified when the Object is disposed.

This is like add_weak_ref_notify but doesn’t require the closure to be Send. Object dispose will panic if the object is disposed from the wrong thread.

fn bind_property<'a, 'f, 't, O: ObjectType>( &'a self, source_property: &'a str, target: &'a O, target_property: &'a str, ) -> BindingBuilder<'a, 'f, 't>

Bind property source_property on this object to the target_property on the target object.

This allows keeping the properties of both objects in sync.

The binding can be unidirectional or bidirectional and optionally it is possible to transform the property values before they’re passed to the other object.

fn ref_count(&self) -> u32

Returns the strong reference count of this object.

unsafe fn run_dispose(&self)

Runs the dispose mechanism of the object.

This will dispose of any references the object has to other objects, and among other things will disconnect all signal handlers.

Safety

Theoretically this is safe to run and afterwards the object is simply in a non-functional state, however many object implementations in C end up with memory safety issues if the object is used after disposal.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T: ObjectType> ObjectExt for T