### ----------------------------------------------------
### -- Gnome::Gtk3
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: lib/Gnome/Gtk3/Builder.rakumod
### ----------------------------------------------------
### -- Chunk 3 of 3
 in the application and connects the signals. Note that this
function can only be called once, subsequent calls will do nothing.

Note that unless C<gtk_builder_add_callback_symbol()> is called for
all signal callbacks which are referenced by the loaded XML, this
function will require that C<GModule> be supported on the platform.

If you rely on C<GModule> support to lookup callbacks in the symbol table,
the following details should be noted:

When compiling applications for Windows, you must declare signal callbacks
with C<G_MODULE_EXPORT>, or they will not be put in the symbol table.
On Linux and Unices, this is not necessary; applications should instead
be compiled with the -Wl,--export-dynamic CFLAGS, and linked against
gmodule-export-2.0.

  method gtk_builder_connect_signals ( Pointer $user_data )

=item $user_data; user data to pass back with all signals

=end pod

sub gtk_builder_connect_signals ( N-GObject $builder, Pointer $user_data )
  is native(&gtk-lib)
  { * }
}}

#-------------------------------------------------------------------------------
#TM:0:gtk_builder_connect_signals_full:
=begin pod
=head2 [[gtk_] builder_] connect_signals_full

This method will process the signal elements from the loaded XML and with the help of the provided $handlers table register each handler to a signal.

  method gtk_builder_connect_signals_full ( Hash $handlers )

=item $handlers; a table used to register handlers to process a signal. Each entry in this table has a key which is the name of the handler method. The value is a list of which the first element is the object wherin the method is defined. The rest of the list are optional named attributes and are provided to the method. See also C<register-signal()> in B<Gnome::GObject::Object>.

An example where a gui is described in XML. It has a Window with a Button, both having a signal description;

  my Str $ui = q:to/EOUI/;
      <?xml version="1.0" encoding="UTF-8"?>
      <interface>
        <requires lib="gtk+" version="3.20"/>

        <object class="GtkWindow" id="top">
          <property name="title">top window</property>
          <signal name="destroy" handler="window-quit"/>
          <child>
            <object class="GtkButton" id="help">
              <property name="label">Help</property>
              <signal name="clicked" handler="button-click"/>
            </object>
          </child>
        </object>
      </interface>
      EOUI

  # First handler class
  class X {
    method window-quit ( :$o1, :$o2 ) {
      # ... do something with options $o1 and $o2 ...

      Gnome::Gtk3::Main.new.gtk-main-quit;
    }
  }

  # Second handler class
  class Y {
    method button-click ( :$o3, :$o4 ) {
      # ... do something with options $o3 and $o4 ...
    }
  }

  # Load the user interface description
  my Gnome::Gtk3::Builder $builder .= new(:string($ui));
  my Gnome::Gtk3::Window $w .= new(:build-id<top>);

  # It is possible to devide the works over more than one class
  my X $x .= new;
  my Y $y .= new;

  # Create the handlers table
  my Hash $handlers = %(
    :window-quit( $x, :o1<o1>, :o2<o2>),
    :button-click( $y, :o3<o3>, :o4<o4>)
  );

  # Register all signals
  $builder.connect-signals-full($handlers);


=end pod

sub gtk_builder_connect_signals_full ( N-GObject $builder, Hash $handlers ) {
  _gtk_builder_connect_signals_full(
    $builder,
    sub (
      N-GObject $builder, N-GObject $object, Str $signal-name,
      Str $handler-name, N-GObject $ignore-d0, int32 $ignore-d1,
      OpaquePointer $ignore-d2
    ) {
      my Str $oname = Gnome::GObject::Type.name-from-instance($object);
      if $oname ~~ /^ Gtk / and $handlers{$handler-name}:exists {
        $oname ~~ s/^ Gtk /Gnome::Gtk3::/;
        my $handler-object = $handlers{$handler-name}[0];
        my %options = %(|$handlers{$handler-name}[1..*-1]);

        require ::($oname);
        my $gtk-object = ::($oname).new(:native-object($object));
        note "Connect $oname, $handler-name for signal $signal-name"
          if $Gnome::N::x-debug;

        if $handler-object.^can("$handler-name") {
          $gtk-object.register-signal(
            $handler-object, $handler-name, $signal-name, |%options
          );
        }

        else {
          note "Signalhandler $handler-name for signal $signal-name not available" if $Gnome::N::x-debug;
        }
      }

      else {
        note "Cannot handle $oname typed objects. Signalhandler for signal $signal-name not activated" if $Gnome::N::x-debug;
      }
    },
    OpaquePointer
  )
}

sub _gtk_builder_connect_signals_full (
  N-GObject $builder,
  Callable $func (
    N-GObject $b, N-GObject $object,
    Str $signal_name, Str $handler_name,
    N-GObject $connect_object, int32 $flags,
    OpaquePointer $d
  ),
  Pointer $user_data
) is symbol('gtk_builder_connect_signals_full')
  is native(&gtk-lib)
  { * }
#}}

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] set_translation_domain

Sets the translation domain of I<builder>.
See prop C<translation-domain>.

  method gtk_builder_set_translation_domain ( Str $domain )

=item $domain; (allow-none): the translation domain or C<Any>

=end pod

sub gtk_builder_set_translation_domain ( N-GObject $builder, Str $domain )
  is native(&gtk-lib)
  { * }

#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] get_translation_domain

Gets the translation domain of I<builder>.

Returns: the translation domain. This string is owned
by the builder object and must not be modified or freed.

  method gtk_builder_get_translation_domain ( --> Str  )


=end pod

sub gtk_builder_get_translation_domain ( N-GObject $builder )
  returns Str
  is native(&gtk-lib)
  { * }
}}

#-------------------------------------------------------------------------------
#TM:0:gtk_builder_get_type_from_name:
=begin pod
=head2 [[gtk_] builder_] get_type_from_name

Looks up a type by name, using the virtual function that
B<Gnome::Gtk3::Builder> has for that purpose. This is mainly used when
implementing the B<Gnome::Gtk3::Buildable> interface on a type.

Returns: the C<GType> found for I<type_name> or C<G_TYPE_INVALID>
if no type was found

  method gtk_builder_get_type_from_name ( Str $type_name --> UInt  )

=item $type_name; type name to lookup

=end pod

sub gtk_builder_get_type_from_name ( N-GObject $builder, Str $type_name )
  returns uint64
  is native(&gtk-lib)
  { * }

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] value_from_string

This function demarshals a value from a string. This function
calls C<g_value_init()> on the I<value> argument, so it need not be
initialised beforehand.

This function can handle char, uchar, boolean, int, uint, long,
ulong, enum, flags, float, double, string, B<Gnome::Gdk3::Color>, B<Gnome::Gdk3::RGBA> and
B<Gnome::Gtk3::Adjustment> type values. Support for B<Gnome::Gtk3::Widget> type values is
still to come.

Upon errors C<0> will be returned and I<error> will be assigned a
C<GError> from the C<GTK_BUILDER_ERROR> domain.

Returns: C<1> on success

  method gtk_builder_value_from_string ( GParamSpec $pspec, Str $string, N-GObject $value, N-GObject $error --> Int  )

=item $pspec; the C<GParamSpec> for the property
=item $string; the string representation of the value
=item $value; (out): the C<GValue> to store the result in
=item $error; (allow-none): return location for an error, or C<Any>

=end pod

sub gtk_builder_value_from_string ( N-GObject $builder, GParamSpec $pspec, Str $string, N-GObject $value, N-GObject $error )
  returns int32
  is native(&gtk-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] value_from_string_type

Like C<gtk_builder_value_from_string()>, this function demarshals
a value from a string, but takes a C<GType> instead of C<GParamSpec>.
This function calls C<g_value_init()> on the I<value> argument, so it
need not be initialised beforehand.

Upon errors C<0> will be returned and I<error> will be assigned a
C<GError> from the C<GTK_BUILDER_ERROR> domain.

Returns: C<1> on success

  method gtk_builder_value_from_string_type ( N-GObject $type, Str $string, N-GObject $value, N-GObject $error --> Int  )

=item $type; the C<GType> of the value
=item $string; the string representation of the value
=item $value; (out): the C<GValue> to store the result in
=item $error; (allow-none): return location for an error, or C<Any>

=end pod

sub gtk_builder_value_from_string_type ( N-GObject $builder, N-GObject $type, Str $string, N-GObject $value, N-GObject $error )
  returns int32
  is native(&gtk-lib)
  { * }
}}

#-------------------------------------------------------------------------------
#TM:1:_gtk_builder_new_from_file:
#`{{
=begin pod
=head2 [[gtk_] builder_] new_from_file

Builds the [B<Gnome::Gtk3::Builder> UI definition](https://developer.gnome.org/gtk3/3.24/GtkBuilder.html#BUILDER-UI) in the file I<filename>.

If there is an error opening the file or parsing the description then
the program will be aborted.  You should only ever attempt to parse
user interface descriptions that are shipped as part of your program.

Returns: a B<Gnome::Gtk3::Builder> containing the described interface

  method gtk_builder_new_from_file ( Str $filename --> N-GObject  )

=item $filename; filename of user interface description file

=end pod
}}
sub _gtk_builder_new_from_file ( Str $filename )
  returns N-GObject
  is symbol('gtk_builder_new_from_file')
  is native(&gtk-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:4:_gtk_builder_new_from_resource:ex-application.pl6
#`{{
=begin pod
=head2 [[gtk_] builder_] new_from_resource

Builds the [B<Gnome::Gtk3::Builder> UI definition](https://developer.gnome.org/gtk3/3.24/GtkBuilder.html#BUILDER-UI) at I<resource_path>.

If there is an error locating the resource or parsing the description, then the program will be aborted.

Returns: a B<Gnome::Gtk3::Builder> containing the described interface

  method gtk_builder_new_from_resource ( Str $resource_path --> N-GObject )

=item $resource_path; a C<GResource> resource path

=end pod
}}
sub _gtk_builder_new_from_resource ( Str $resource_path )
  returns N-GObject
  is native(&gtk-lib)
  is symbol('gtk_builder_new_from_resource')
  { * }


#-------------------------------------------------------------------------------
#TM:1:_gtk_builder_new_from_string:
#`{{
=begin pod
=head2 [[gtk_] builder_] new_from_string

Builds the user interface described by I<string> (in the [B<Gnome::Gtk3::Builder> UI definition](https://developer.gnome.org/gtk3/3.24/GtkBuilder.html#BUILDER-UI) format).

If I<string> is C<Any>-terminated, then I<length> should be -1.
If I<length> is not -1, then it is the length of I<string>.

If there is an error parsing I<string> then the program will be
aborted. You should not attempt to parse user interface description
from untrusted sources.

Returns: a B<Gnome::Gtk3::Builder> containing the interface described by I<string>

  method gtk_builder_new_from_string ( Str $string, Int $length --> N-GObject  )

=item $string; a user interface (XML) description
=item $length; the length of I<string>, or -1

=end pod
}}

sub _gtk_builder_new_from_string (
  Str $string, Int $length? --> N-GObject
) {

  Gnome::N::deprecate(
    '.gtk_builder_new_from_string( $string, $length)',
    '.gtk_builder_new_from_string($string)', '0.27.4', '0.35.0'
  ) if $length.defined;

  __gtk_builder_new_from_string( $string, $string.chars)
}

sub __gtk_builder_new_from_string ( Str $string, int64 $length --> N-GObject )
  is native(&gtk-lib)
  is symbol('gtk_builder_new_from_string')
  { * }

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] add_callback_symbol

Adds the I<callback_symbol> to the scope of I<builder> under the given I<callback_name>.

Using this function overrides the behavior of C<gtk_builder_connect_signals()>
for any callback symbols that are added. Using this method allows for better
encapsulation as it does not require that callback symbols be declared in
the global namespace.

  method gtk_builder_add_callback_symbol ( Str $callback_name, GCallback $callback_symbol )

=item $callback_name; The name of the callback, as expected in the XML
=item $callback_symbol; (scope async): The callback pointer

=end pod

sub gtk_builder_add_callback_symbol ( N-GObject $builder, Str $callback_name, GCallback $callback_symbol )
  is native(&gtk-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] add_callback_symbols

A convenience function to add many callbacks instead of calling
C<gtk_builder_add_callback_symbol()> for each symbol.

  method gtk_builder_add_callback_symbols ( Str $first_callback_name, GCallback $first_callback_symbol )

=item $first_callback_name; The name of the callback, as expected in the XML
=item $first_callback_symbol; (scope async): The callback pointer @...: A list of callback name and callback symbol pairs terminated with C<Any>

=end pod

sub gtk_builder_add_callback_symbols ( N-GObject $builder, Str $first_callback_name, GCallback $first_callback_symbol, Any $any = Any )
  is native(&gtk-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
=begin pod
=head2 [[gtk_] builder_] lookup_callback_symbol

Fetches a symbol previously added to I<builder>
with C<gtk_builder_add_callback_symbols()>

This function is intended for possible use in language bindings
or for any case that one might be cusomizing signal connections
using C<gtk_builder_connect_signals_full()>

Returns: (nullable): The callback symbol in I<builder> for I<callback_name>, or C<Any>

  method gtk_builder_lookup_callback_symbol ( Str $callback_name --> GCallback  )

=item $callback_name; The name of the callback

=end pod

sub gtk_builder_lookup_callback_symbol ( N-GObject $builder, Str $callback_name )
  returns GCallback
  is native(&gtk-lib)
  { * }
}}

#-------------------------------------------------------------------------------
#TM:0:gtk_builder_set_application:
=begin pod
=head2 [[gtk_] builder_] set_application

Sets the application associated with I<builder>.

You only need this function if there is more than one C<Application> in your process. I<application> cannot be C<Any>.

  method gtk_builder_set_application ( N-GObject $application )

=item $application; a B<Gnome::Gtk3::Application>

=end pod

sub gtk_builder_set_application ( N-GObject $builder, N-GObject $application )
  is native(&gtk-lib)
  { * }

#-------------------------------------------------------------------------------
#TM:0:gtk_builder_get_application:
=begin pod
=head2 [[gtk_] builder_] get_application

Gets the B<Gnome::Gtk3::Application> associated with the builder.

The B<Gnome::Gtk3::Application> is used for creating action proxies as requested
from XML that the builder is loading.

By default, the builder uses the default application: the one from
C<g_application_get_default()>. If you want to use another application
for constructing proxies, use C<gtk_builder_set_application()>.

Returns: (nullable) (transfer none): the application being used by the builder,
or C<Any>

  method gtk_builder_get_application ( --> N-GObject  )


=end pod

sub gtk_builder_get_application ( N-GObject $builder )
  returns N-GObject
  is native(&gtk-lib)
  { * }

#-------------------------------------------------------------------------------
#`{{
=begin pod
=head2 [[gtk_] builder_] extend_with_template

Main private entry point for building composite container
components from template XML.

This is exported purely to let gtk-builder-tool validate
templates, applications have no need to call this function.

Returns: A positive value on success, 0 if an error occurred

  method gtk_builder_extend_with_template ( N-GObject $widget, N-GObject $template_type, Str $buffer, UInt $length, N-GObject $error --> UInt  )

=item $widget; the widget that is being extended
=item $template_type; the type that the template is for
=item $buffer; the string to parse
=item $length; the length of I<buffer> (may be -1 if I<buffer> is nul-terminated)
=item $error; (allow-none): return location for an error, or C<Any>

=end pod

sub gtk_builder_extend_with_template ( N-GObject $builder, N-GObject $widget, N-GObject $template_type, Str $buffer, uint64 $length, N-GObject $error )
  returns uint32
  is native(&gtk-lib)
  { * }
}}

#-------------------------------------------------------------------------------
=begin pod
=head1 Properties

An example of using a string type property of a B<Gnome::Gtk3::Label> object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use B<new(:label('my text label'))> or B<gtk_label_set_text('my text label')>.

  my Gnome::Gtk3::Label $label .= new;
  my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
  $label.g-object-get-property( 'label', $gv);
  $gv.g-value-set-string('my text label');

=head2 Supported properties

=head3 translation-domain

The translation domain used when translating property values that
have been marked as translatable in interface descriptions.
If the translation domain is C<Any>, B<Gnome::Gtk3::Builder> uses C<gettext()>,
otherwise C<g_dgettext()>.

The B<Gnome::GObject::Value> type of property I<translation-domain> is C<G_TYPE_STRING>.

=end pod


