### ----------------------------------------------------
### -- Gnome::GObject
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: lib/Gnome/GObject/Object.rakumod
### ----------------------------------------------------
### -- Chunk 4 of 4

=head2 [[g_] object_] set_data_full

Like C<g_object_set_data()> except it adds notification
for when the association is destroyed, either by setting it
to a different value or when the object is destroyed.

Note that the I<destroy> callback is not called if I<data> is C<Any>.

  method g_object_set_data_full ( Str $key, Pointer $data, GDestroyNotify $destroy )

=item Str $key; name of the key
=item Pointer $data; (nullable): data to associate with that key
=item GDestroyNotify $destroy; (nullable): function to call when the association is destroyed

=end pod

sub g_object_set_data_full ( N-GObject $object, Str $key, Pointer $data, GDestroyNotify $destroy )
  is native(&gobject-lib)
  { * }
}}
#`{{


#-------------------------------------------------------------------------------
#TM:0:g_object_dup_data:
=begin pod
=head2 [[g_] object_] dup_data

This is a variant of C<g_object_get_data()> which returns
a 'duplicate' of the value. I<dup_func> defines the
meaning of 'duplicate' in this context, it could e.g.
take a reference on a ref-counted object.

If the I<key> is not set on the object then I<dup_func>
will be called with a C<Any> argument.

Note that I<dup_func> is called while user data of I<object>
is locked.

This function can be useful to avoid races when multiple
threads are using object data on the same key on the same
object.

Returns: the result of calling I<dup_func> on the value
associated with I<key> on I<object>, or C<Any> if not set.
If I<dup_func> is C<Any>, the value is returned
unmodified.


  method g_object_dup_data ( Str $key, GDuplicateFunc $dup_func, Pointer $user_data --> Pointer  )

=item Str $key; a string, naming the user data pointer
=item GDuplicateFunc $dup_func; (nullable): function to dup the value
=item Pointer $user_data; (nullable): passed as user_data to I<dup_func>

=end pod

sub g_object_dup_data ( N-GObject $object, Str $key, GDuplicateFunc $dup_func, Pointer $user_data )
  returns Pointer
  is native(&gobject-lib)
  { * }
}}

#`{{
}}
#`{{
#-------------------------------------------------------------------------------
#TM:0:g_object_watch_closure:
=begin pod
=head2 [[g_] object_] watch_closure

This function essentially limits the life time of the I<closure> to
the life time of the object. That is, when the object is finalized,
the I<closure> is invalidated by calling C<g_closure_invalidate()> on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, C<g_object_ref()> and C<g_object_unref()> are
added as marshal guards to the I<closure>, to ensure that an extra
reference count is held on I<object> during invocation of the
I<closure>.  Usually, this function will be called on closures that
use this I<object> as closure data.

  method g_object_watch_closure ( N-GObject $closure )

=item N-GObject $closure; I<GClosure> to watch

=end pod

sub g_object_watch_closure ( N-GObject $object, N-GObject $closure )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_cclosure_new_object:
=begin pod
=head2 [g_] cclosure_new_object

A variant of C<g_cclosure_new()> which uses I<object> as I<user_data> and
calls C<g_object_watch_closure()> on I<object> and the created
closure. This function is useful when you have a callback closely
associated with a I<GObject>, and want the callback to no longer run
after the object is is freed.

Returns: a new I<GCClosure>

  method g_cclosure_new_object ( GCallback $callback_func, N-GObject $object --> N-GObject  )

=item GCallback $callback_func; the function to invoke
=item N-GObject $object; a I<GObject> pointer to pass to I<callback_func>

=end pod

sub g_cclosure_new_object ( GCallback $callback_func, N-GObject $object )
  returns N-GObject
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_cclosure_new_object_swap:
=begin pod
=head2 [g_] cclosure_new_object_swap

A variant of C<g_cclosure_new_swap()> which uses I<object> as I<user_data>
and calls C<g_object_watch_closure()> on I<object> and the created
closure. This function is useful when you have a callback closely
associated with a I<GObject>, and want the callback to no longer run
after the object is is freed.

Returns: a new I<GCClosure>

  method g_cclosure_new_object_swap ( GCallback $callback_func, N-GObject $object --> N-GObject  )

=item GCallback $callback_func; the function to invoke
=item N-GObject $object; a I<GObject> pointer to pass to I<callback_func>

=end pod

sub g_cclosure_new_object_swap ( GCallback $callback_func, N-GObject $object )
  returns N-GObject
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_closure_new_object:
=begin pod
=head2 [g_] closure_new_object

A variant of C<g_closure_new_simple()> which stores I<object> in the
I<data> field of the closure and calls C<g_object_watch_closure()> on
I<object> and the created closure. This function is mainly useful
when implementing new types of closures.

Returns: (transfer full): a newly allocated I<GClosure>

  method g_closure_new_object ( UInt $sizeof_closure, N-GObject $object --> N-GObject  )

=item UInt $sizeof_closure; the size of the structure to allocate, must be at least `sizeof (GClosure)`
=item N-GObject $object; a I<GObject> pointer to store in the I<data> field of the newly allocated I<GClosure>

=end pod

sub g_closure_new_object ( uint32 $sizeof_closure, N-GObject $object )
  returns N-GObject
  is native(&gobject-lib)
  { * }
}}
#`{{
#-------------------------------------------------------------------------------
#TM:0:g_value_set_object:
=begin pod
=head2 [g_] value_set_object

Set the contents of a C<G_TYPE_OBJECT> derived I<GValue> to I<v_object>.

C<g_value_set_object()> increases the reference count of I<v_object>
(the I<GValue> holds a reference to I<v_object>).  If you do not wish
to increase the reference count of the object (i.e. you wish to
pass your current reference to the I<GValue> because you no longer
need it), use C<g_value_take_object()> instead.

It is important that your I<GValue> holds a reference to I<v_object> (either its
own, or one it has taken) to ensure that the object won't be destroyed while
the I<GValue> still exists).

  method g_value_set_object ( N-GObject $value, Pointer $v_object )

=item N-GObject $value; a valid I<GValue> of C<G_TYPE_OBJECT> derived type
=item Pointer $v_object; (type GObject.Object) (nullable): object value to be set

=end pod

sub g_value_set_object ( N-GObject $value, Pointer $v_object )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_value_get_object:
=begin pod
=head2 [g_] value_get_object

Get the contents of a C<G_TYPE_OBJECT> derived I<GValue>.

Returns: (type GObject.Object) (transfer none): object contents of I<value>

  method g_value_get_object ( N-GObject $value --> Pointer  )

=item N-GObject $value; a valid I<GValue> of C<G_TYPE_OBJECT> derived type

=end pod

sub g_value_get_object ( N-GObject $value )
  returns Pointer
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_value_dup_object:
=begin pod
=head2 [g_] value_dup_object

Get the contents of a C<G_TYPE_OBJECT> derived I<GValue>, increasing
its reference count. If the contents of the I<GValue> are C<Any>, then
C<Any> will be returned.

Returns: (type GObject.Object) (transfer full): object content of I<value>,
should be unreferenced when no longer needed.

  method g_value_dup_object ( N-GObject $value --> Pointer  )

=item N-GObject $value; a valid I<GValue> whose type is derived from C<G_TYPE_OBJECT>

=end pod

sub g_value_dup_object ( N-GObject $value )
  returns Pointer
  is native(&gobject-lib)
  { * }
}}
#`{{
#-------------------------------------------------------------------------------
#TM:0:g_signal_connect_object:
=begin pod
=head2 [g_] signal_connect_object

This is similar to C<g_signal_connect_data()>, but uses a closure which
ensures that the I<gobject> stays alive during the call to I<c_handler>
by temporarily adding a reference count to I<gobject>.

When the I<gobject> is destroyed the signal handler will be automatically
disconnected.  Note that this is not currently threadsafe (ie:
emitting a signal while I<gobject> is being destroyed in another thread
is not safe).

Returns: the handler id.

  method g_signal_connect_object ( Pointer $instance, Str $detailed_signal, GCallback $c_handler, Pointer $gobject, GConnectFlags $connect_flags --> UInt  )

=item Pointer $instance; (type GObject.TypeInstance): the instance to connect to.
=item Str $detailed_signal; a string of the form "signal-name::detail".
=item GCallback $c_handler; the I<GCallback> to connect.
=item Pointer $gobject; (type GObject.Object) (nullable): the object to pass as data to I<c_handler>.
=item GConnectFlags $connect_flags; a combination of I<GConnectFlags>.

=end pod

sub g_signal_connect_object ( Pointer $instance, Str $detailed_signal, GCallback $c_handler, Pointer $gobject, int32 $connect_flags )
  returns uint64
  is native(&gobject-lib)
  { * }
}}
#`{{
#-------------------------------------------------------------------------------
#TM:0:g_object_force_floating:
=begin pod
=head2 [[g_] object_] force_floating

This function is intended for I<GObject> implementations to re-enforce
a [floating][floating-ref] object reference. Doing this is seldom
required: all I<GInitiallyUnowneds> are created with a floating reference
which usually just needs to be sunken by calling C<g_object_ref_sink()>.


  method g_object_force_floating ( )


=end pod

sub g_object_force_floating ( N-GObject $object )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_object_run_dispose:
=begin pod
=head2 [[g_] object_] run_dispose

Releases all references to other objects. This can be used to break
reference cycles.

This function should only be called from object system implementations.

  method g_object_run_dispose ( )


=end pod

sub g_object_run_dispose ( N-GObject $object )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_value_take_object:
=begin pod
=head2 [g_] value_take_object

Sets the contents of a C<G_TYPE_OBJECT> derived I<GValue> to I<v_object>
and takes over the ownership of the callers reference to I<v_object>;
the caller doesn't have to unref it any more (i.e. the reference
count of the object is not increased).

If you want the I<GValue> to hold its own reference to I<v_object>, use
C<g_value_set_object()> instead.


  method g_value_take_object ( N-GObject $value, Pointer $v_object )

=item N-GObject $value; a valid I<GValue> of C<G_TYPE_OBJECT> derived type
=item Pointer $v_object; (nullable): object value to be set

=end pod

sub g_value_take_object ( N-GObject $value, Pointer $v_object )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_clear_object:
=begin pod
=head2 [g_] clear_object

Clears a reference to a I<GObject>.

I<object_ptr> must not be C<Any>.

If the reference is C<Any> then this function does nothing.
Otherwise, the reference count of the object is decreased and the
pointer is set to C<Any>.

A macro is also included that allows this function to be used without
pointer casts.


  method g_clear_object ( )


=end pod

sub g_clear_object ( N-GObject $object_ptr )
  is native(&gobject-lib)
  { * }
}}
#`{{
#-------------------------------------------------------------------------------
#TM:0:g_weak_ref_init:
=begin pod
=head2 [g_] weak_ref_init

Initialise a non-statically-allocated I<GWeakRef>.

This function also calls C<g_weak_ref_set()> with I<object> on the
freshly-initialised weak reference.

This function should always be matched with a call to
C<g_weak_ref_clear()>.  It is not necessary to use this function for a
I<GWeakRef> in static storage because it will already be
properly initialised.  Just use C<g_weak_ref_set()> directly.


  method g_weak_ref_init ( GWeakRef $weak_ref, Pointer $object )

=item GWeakRef $weak_ref; (inout): uninitialized or empty location for a weak reference
=item Pointer $object; (type GObject.Object) (nullable): a I<GObject> or C<Any>

=end pod

sub g_weak_ref_init ( GWeakRef $weak_ref, Pointer $object )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_weak_ref_clear:
=begin pod
=head2 [g_] weak_ref_clear

Frees resources associated with a non-statically-allocated I<GWeakRef>.
After this call, the I<GWeakRef> is left in an undefined state.

You should only call this on a I<GWeakRef> that previously had
C<g_weak_ref_init()> called on it.


  method g_weak_ref_clear ( GWeakRef $weak_ref )

=item GWeakRef $weak_ref; (inout): location of a weak reference, which may be empty

=end pod

sub g_weak_ref_clear ( GWeakRef $weak_ref )
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_weak_ref_get:
=begin pod
=head2 [g_] weak_ref_get

If I<weak_ref> is not empty, atomically acquire a strong
reference to the object it points to, and return that reference.

This function is needed because of the potential race between taking
the pointer value and C<g_object_ref()> on it, if the object was losing
its last reference at the same time in a different thread.

The caller should release the resulting reference in the usual way,
by using C<g_object_unref()>.

Returns: (transfer full) (type GObject.Object): the object pointed to
by I<weak_ref>, or C<Any> if it was empty


  method g_weak_ref_get ( GWeakRef $weak_ref --> Pointer  )

=item GWeakRef $weak_ref; (inout): location of a weak reference to a I<GObject>

=end pod

sub g_weak_ref_get ( GWeakRef $weak_ref )
  returns Pointer
  is native(&gobject-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:g_weak_ref_set:
=begin pod
=head2 [g_] weak_ref_set

Change the object to which I<weak_ref> points, or set it to
C<Any>.

You must own a strong reference on I<object> while calling this
function.


  method g_weak_ref_set ( GWeakRef $weak_ref, Pointer $object )

=item GWeakRef $weak_ref; location for a weak reference
=item Pointer $object; (type GObject.Object) (nullable): a I<GObject> or C<Any>

=end pod

sub g_weak_ref_set ( GWeakRef $weak_ref, Pointer $object )
  is native(&gobject-lib)
  { * }
}}

#-------------------------------------------------------------------------------
=begin pod
=head1 Signals

Registering example

  class MyHandlers {
    method my-click-handler ( :$widget, :$my-data ) { ... }
  }

  # elsewhere
  my MyHandlers $mh .= new;
  $button.register-signal( $mh, 'click-handler', 'clicked', :$my-data);

See also method C<register-signal> in Gnome::GObject::Object.

=head2 Not yet supported signals
=head3 notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

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 C<G_PARAM_EXPLICIT_NOTIFY>, then any call to g_object_set_property() results in C<notify> being emitted, even if the new value is the same as the old. If they did pass C<G_PARAM_EXPLICIT_NOTIFY>, then this signal is emitted only when they explicitly call C<g_object_notify()> or C<g_object_notify_by_pspec()>, and common practice is to do that only when the value has actually changed.

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

  g_signal_connect(
    text_view->buffer, "notify::paste-target-list",
    G_CALLBACK (gtk_text_view_target_list_notify), text_view
  );

It is important to note that you must use [canonical parameter names][canonical-parameter-names] as detail strings for the notify signal.
=end comment

  method handler (
    Int :$_handler_id,
    Gnome::GObject::Object :_widget($gobject),
    :handler-arg0($pspec),
    :$user-option1, ..., :$user-optionN
  );

=item $gobject; the object which received the signal.
=item $pspec; the I<N-GParamSpec> of the property which changed.

=end pod


