para

use v6.d;
use NativeCall;

use Gnome::N::NativeLib;
use Gnome::N::X;

#-------------------------------------------------------------------------------
# Native object placed here because it is used by several modules. When placed
# in one of those module it can create circular dependencies
#
=begin rakudoc


head


Class at the top of many food chains. This native object is stored here to prevent circular dependencies.

Previously I thought this would be an object from everything GObject in glib and child classes. Now, I will use it for everything opaque and call it a I<Native Gnome Object>. This object is always stored in the C<Gnome::N> distribution. It is instanciated in a C<.BUILD()> submethod or imported using C<:native-object> or C<:build-id> named argument to a C<.new()> method. There are other objects which are not so opaque like B<N-GError> and B<N-GdkRGBA>. These objects are defined in their proper places. So, in short, every standalone class has its own native object (or even none like B<Gnome::Glib::Quark>), and every class inheriting from B<Gnome::N::TopLevelClassSupport>, directly or indirectly, has this opaque object B<N-Object>.

=end rakudoc

#TT:1:N-Object:
unit class N-Object is repr('CPointer') is export;

#-------------------------------------------------------------------------------
#tm:4:CALL-ME:
=begin rakudoc



Wrap this native object in a Raku object given by the C<$rk-type> or C<$rk-type-name> from the argument.

Example where the native object is a B<GtkWindow> type. The Raku type would then be B<Gnome::Gtk3::Window> (or B<Gnome::Gtk4::Window:api<2>>).

  my Gnome::Gtk3::Window $w .= new;
  $w.set-title('N-Object coercion');
  my N-Object() $no = $w;

  # CALL-ME is used here. There are 3 ways to use it.
  say $no(Gnome::Gtk3::Window).get-title;     # N-Object coercion
  say $no('Gnome::Gtk3::Window').get-title;   # N-Object coercion
  say $no().get-title;                        # N-Object coercion

In the last example, an exeption is thrown when the native object is not defined because there will be no way to know to which class to convert to. The other types will convert but the objects will be invalid.

Note that when a native object must be coerced into a Raku object while in a chain of calls, you must add a few extra dots, because, the intended coercion will be seen as a call to a method.

  my Gnome::Gdk3::Screen $s .= new;

  # The wrong way: get-rgba-visual() is seen as a call to the
  # get-rgba-visual method.
  $s.get-rgba-visual().get-depth;

  # The right way: Now there is a conversion at this point .(). and after
  # that the call get-depth() works on the Gnome::Gdk3::Visual object
  $s.get-rgba-visual.().get-depth;

  # Nice to write this for the same result and documents your statement
  $s.get-rgba-visual.('Gnome::Gdk3::Visual').get-depth;

=end rakudoc

multi method CALL-ME( $rk-type ) {
  self._wrap-native-type( $rk-type.^name, self)
}

multi method CALL-ME( Str:D $rk-type-name ) {
  self._wrap-native-type( $rk-type-name, self)
}

multi method CALL-ME( ) {
  if self.defined {
    self._wrap-native-type-from-no(self)
  }

  else {
    die X::Gnome.new(:message('No defined native object to work on'));
  }
}

#-------------------------------------------------------------------------------
#tm:4:_wrap-native-type:
# no doc, same routine as in TopLevelClassSupport
method _wrap-native-type ( Str:D $type where ?$type, Any $no --> Any ) {

  # get class and wrap the native object in it
  try require ::($type);
  if $Gnome::N::x-debug and ::($type) ~~ Failure {
    note "Failed to load $type!";
    ::($type).note;
  }

  else {
    if ?$no {
      note "Coercing N-Object to a valid $type type" if $Gnome::N::x-debug;
      ::($type).new(:native-object($no));
    }

    else {
      if $Gnome::N::x-debug && $type ~~ any(
        <Gnome::Glib::List::N-GList Gnome::Glib::SList::N-GSList>
      ) {
        note "Coercing N-Object to a valid $type type"
          if $Gnome::N::x-debug;
      }

      else {
        note "Coercing N-Object to an invalid $type type"
          if $Gnome::N::x-debug;
      }

      ::($type).new(:native-object(N-Object));
    }
  }
}

#-------------------------------------------------------------------------------
#tm:4:_wrap-native-type-from-no:
# no doc, same routine as in TopLevelClassSupport
method _wrap-native-type-from-no ( N-Object $no --> Any ) {
  my Str $type;
  $type = ?$no ?? _name_from_instance($no) !! '';
  return N-Object unless ( ?$type and $type ne '<NULL-class>');

  given $type {
    when /^ Gtk / { $type ~~ s/^ Gtk/Gtk3::/; }
    when /^ GdkX11 / { $type ~~ s/^ GdkX11/Gdk3::/; }
    when /^ GdkWayland / { $type ~~ s/^ GdkWayland/Gdk3::/; }
    when /^ Gdk / { $type ~~ s/^ Gdk/Gdk3::/; }
    when /^ Atk / { $type ~~ s/^ Atk/Atk::/; }

    # Checking other objects from GObject, Glib and Gio all start with 'G'
    # so it is difficult to map it to the proper raku object.
    #
    # However, wrapping like this is only used when there are multiple
    # native object types to return to the caller. This is mostly
    # restricted to Gtk3 modules. The other reason to call this wrapper is
    # to prevent circular dependencies which sometimes happen in Gdk3
    # modules.

#      when /^ G / { $native-name ~~ s/^ /::/; }
#      when /^  / { $native-name ~~ s/^ /::/; }
  }

  $type = [~] 'Gnome', '::', $type;

  #  my Str $type = [~] 'Gnome', '::', $native-name;
  note "wrap $type" if $Gnome::N::x-debug;

  # get class and wrap the native object in it
  require ::($type);
  ::($type).new(:native-object($no))
}

#-------------------------------------------------------------------------------
method COERCE ( Mu $any --> N-Object ) {
  nativecast( N-Object, $any)
}

#-------------------------------------------------------------------------------
#--[ some necessary native subroutines ]----------------------------------------
#-------------------------------------------------------------------------------
sub _name_from_instance ( N-Object $instance --> Str )
  is native(&gobject-lib)
  is symbol('g_type_name_from_instance')
  { * }




#`{{
# TODO - needed?
#-------------------------------------------------------------------------------
method FALLBACK( $routine, *@a, *%o ) {
  note 'a & o: ', self.^name, ', ', $routine, ', ', @a.gist, ', ', %o.gist;
  self._wrap-native-type-from-no(self)."$routine"( |@a, |%o);
}
}}

=finish
#-------------------------------------------------------------------------------
# TM:1:COERCE:
=begin rakudoc



Method to wrap a native object into a Raku object

Example;


code

=begin code
  my N-Object $no = …;
  my Gnome::Gtk3::Window() $w = $no;
=end code


=begin code
  method COERCE( $no --> Any )
=end code



=end rakudoc
method COERCE( $no --> Any ) {
note 'N-Object COERCE: ', $no;
  note "Coercing from N-Object to ", self.^name if $Gnome::N::x-debug;
  self._wrap-native-type( self.^name, $no)
}


root

Gnome::N::TopLevelClassSupport


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<AI|file:../mcp/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>
    =item2 L<Hand these documents to an AI assistant|file:../mcp/index.podlite>

=end nested
=begin nested :!nested
=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>

=end nested
=end React


Built with L<Podlite|https://podlite.org> — the markup and publishing tools behind this site.


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


N-Object

class N-Object

CALL-ME

COERCE

Gnome::N v0.1.54

Authors

License

Dependencies

Test Dependencies

Provides

Documentation