Gnome::GObject::Object

Table of Contents
Description
Methods
freeze-notify
get-data
get-property
Example
get-qdata
notify
set-data
Example
set-property
set-qdata
thaw-notify
register-signal
Callback handlers
Example 1
Signals
notify

Description

The base object type.

Methods

freeze-notify

Increases the freeze count on $object. If the freeze count is non-zero, the emission of "notify" signals on $object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one notify signal is emitted for each property modified while the object is frozen.

This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

method freeze-notify ( )

get-data

Gets a named field from the objects table of associations (see .set-data()).

method get-data ( Str $key --> gpointer )

$key; name of the key for that association.

Return value; the data if found, or Nil if no such data exists.

get-property

Gets a property of an object.

The $value can be:

an empty GValue, which will be automatically initialized with the expected type of the property (since GLib 2.60)
a GValue initialized with the expected type of the property.
a GValue initialized with a type to which the expected type of the property can be transformed.

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling .unset().

Note that .get-property() is really intended for language bindings, .get() is much more convenient for C programming.

method get-property ( Str $property-name, CArray[N-Value] $value )

$property-name; the name of the property to get.
$value; return location for the property value.

Example

Get the label property of a Gnome::Gtk4::Label object.

with my Gnome::Gtk4::Label $label .= new-label {
  my Gnome::GObject::N-Value() $property-value .= new(:type(G_TYPE_STRING));

  $property-value.set-string('My label text');
  .set-property( 'label', $property-value);

  .get-property( 'label', $property-value);
  say 'Label string is ", $property-value.get-string;
}

Please note that most, if not all, properties of the classes are accessable using the class getters and setters. In the case above, .set-text() and .get-text() methods defined in the Gnome::Gtk4::Label class.

get-qdata

This function gets back user data pointers stored via .set-qdata().

method get-qdata ( UInt $quark --> gpointer )

$quark; A GQuark, naming the user data pointer.

Return value; The user data pointer set, or Nil.

notify

Emits a "notify" signal for the property $property_name in this object.

Note that emission of the notify signal may be blocked with .freeze-notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when .thaw-notify() is called.

method notify ( Str $property-name )

$property-name; the name of a property installed on the class of $object..

set-data

Each object carries around a table of associations from strings to pointers. This function lets you set an association.

If the object already had an association with that name, the old association will be destroyed.

Internally, the $key is converted to a GQuark using .from-string() in Gnome::Glib::T-quark.This means a copy of $key is kept permanently (even after this native object has been deleted) — so it is recommended to only use a small, bounded set of values for $key in your program, to avoid the GQuark storage growing unbounded.

method set-data ( Str $key, gpointer $data )

$key; name of the key.
$data; data to associate with that key.

Example

A label object is used to store extra data in the form of an N-Value structure. The example shows the use of .set-data(), .get-data(). Also the methods .set-qdata(), .get-qdata() are shown.

with my Gnome::Gtk4::Label $label .= new-label {
  my Gnome::GObject::N-Value() $extra-data .= new(:type(G_TYPE_INT));

  # Store
  $extra-data.set-int(12345);
  .set-data( 'my-data', $extra-data);

  # Retrieve
  $extra-data = .get-data('my-data');
  say "The stored integer is ", $extra-data.get-int;

  # Same using a quark
  my Gnome::Glib::T-quark $tq .= new;
  my GQuark $q = $tq.from-string('my-data2');

  # Store
  $extra-data.set-int(54321);
  .set-qdata( $q, $extra-data);

  # Retrieve
  $extra-data = .get-qdata($q);
  say "$extra-data.get-int, 54321, '.set-qdata() / .get-qdata() stored N-Value with quark';
}

set-property

Sets a property on an object.

method set-property ( Str $property-name, CArray[N-Value] $value )

$property-name; the name of the property to set.
$value; the value.

set-qdata

This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrieved e.g. via .from-string()), and the pointer can be gotten back from the $object with .get-qdata() until the object is finalized.

Setting a previously set user data pointer, overrides (frees) the old pointer set, using NULL as pointer essentially removes the data stored.

method set-qdata ( UInt $quark, gpointer $data )

$quark; A GQuark, naming the user data pointer.
$data; An opaque user data pointer.

thaw-notify

Reverts the effect of a previous call to .freeze-notify(). The freeze count is decreased on $object and when it reaches zero, queued "notify" signals are emitted.

Duplicate notifications for each property are squashed so that at most one notify signal is emitted for each property, in the reverse order in which they have been queued.

It is an error to call this function when the freeze count is zero.

method thaw-notify ( )

register-signal

Note: This method is a convenience method not defined by Gnome in the Object class. The method is defined in Gnome::N::GObjectSupport.

Register a handler to process a signal or an event. There are several types of callbacks which can be handled by this registration. They can be controlled by using a named argument with a special name.

method register-signal (
  $handler-object, Str:D $handler-name,
  Str:D $signal-name, *%user-options
  --> Int
)

$handler-object; The object wherein the handler is defined.
$handler-name; The name of the method.
$signal-name; The name of the event to be handled. Each gtk object has its own series of signals.

:$_handler-id; The handler id which is returned from the registration
:$_native-object; The native object provided by the caller.

%user-options; Any other user data in whatever type provided as one or more named arguments. These arguments are provided to the user handler when an event for the handler is fired. The names starting with '_' are reserved to provide other info to the user.
The following reserved named arguments are available;
```
method some-button-click-handler (
  …,
  Gnome::Gtk3::Button() :_native-object($button)
) {
  …
}
```

The method returns a handler id which can be used for example to disconnect the callback later.

Callback handlers

Simple handlers; e.g. a click event handler has only named arguments and are optional.
Complex handlers (only a bit) also have positional arguments and MUST be typed because they are checked to create a signature for the call to a native subroutine. You can use the raku native types like int32 but several types are automatically converted to native types. The types such as gboolean, etc are defined in Gnome::N::GlibToRakuTypes.

Raku type Native glib type Native Raku type

Bool gboolean int32

UInt guint uint32/uint64

Int gint int32/int64

Num gfloat num32

Rat gdouble num64
Some handlers must return a value and is used by the calling process. You MUST describe this too in the handlers API, otherwise the returned value is thrown away.
Any user options are provided via named arguments from the call to register-signal().

Raku type	Native glib type	Native Raku type
Bool	gboolean	int32
UInt	guint	uint32/uint64
Int	gint	int32/int64
Num	gfloat	num32
Rat	gdouble	num64

Example 1

An example of a registration and the handlers signature to handle a button click event.

# Handler class with callback methods
class ButtonHandlers {
  method click-button (
    Gnome::Gtk3::Button() :_native-object($button),
    Int :$_handler_id, :$my-option ) {
    …
  }
}

$button.register-signal(
  ButtonHandlers.new, 'click-button', 'clicked', :my-option(…)
);

Signals

notify

The notify signal is emitted on an object when one of its properties has its value set through .set-property().

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with %G_PARAM_EXPLICIT_NOTIFY, then any call to .set-property() results in notify being emitted, even if the new value is the same as the old. If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call .notify() or .notify-by-pspec(), and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

method handler (
  N-Object $pspec,
  Int :$_handle_id,
  Gnome::GObject::Object() :$_native-object,
  *%user-options
)

$pspec; the GParamSpec of the property which changed.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event.
%user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.