Ross McFarland > Glib-1.043 > GType.xs

Download:
Gtk2-Perl/Glib-1.043.tar.gz

Annotate this POD

CPAN RT

New  3
Open  3
View/Report Bugs
Source  

GType / GEnum / GFlags

void gperl_register_fundamental (GType gtype, const char * package)

register a mapping between gtype and package. this is for "fundamental" types which have no other requirements for metadata storage, such as GEnums, GFlags, or real GLib fundamental types like G_TYPE_INT, G_TYPE_FLOAT, etc.

GType gperl_fundamental_type_from_package (const char * package)

look up the GType corresponding to a package registered by gperl_register_fundamental().

const char * gperl_fundamental_package_from_type (GType gtype)

look up the package corresponding to a gtype registered by gperl_register_fundamental().

gboolean gperl_try_convert_enum (GType gtype, SV * sv, gint * val)

return FALSE if sv can't be mapped to a valid member of the registered enum type gtype; otherwise, return TRUE write the new value to the int pointed to by val.

you'll need this only in esoteric cases.

gint gperl_convert_enum (GType type, SV * val)

croak if val is not part of type, otherwise return corresponding value

SV * gperl_convert_back_enum_pass_unknown (GType type, gint val)

return a scalar containing the nickname of the enum value val, or the integer value of val if val is not a member of the enum type.

SV * gperl_convert_back_enum (GType type, gint val)

return a scalar which is the nickname of the enum value val, or croak if val is not a member of the enum.

gboolean gperl_try_convert_flag (GType type, const char * val_p, gint * val)

like gperl_try_convert_enum(), but for GFlags.

gint gperl_convert_flag_one (GType type, const char * val)

croak if val is not part of type, otherwise return corresponding value.

gint gperl_convert_flags (GType type, SV * val)

collapse a list of strings to an integer with all the correct bits set, croak if anything is invalid.

SV * gperl_convert_back_flags (GType type, gint val)

convert a bitfield to a list of strings.

Inheritance management

void gperl_set_isa (const char * child_package, const char * parent_package)

tell perl that child_package inherits parent_package, after whatever else is already there. equivalent to push @{$parent_package}::ISA, $child_package;

void gperl_prepend_isa (const char * child_package, const char * parent_package)

tell perl that child_package inherits parent_package, but before whatever else is already there. equivalent to unshift @{$parent_package}::ISA, $child_package;

GType gperl_type_from_package (const char * package)

Look up the GType associated with package, regardless of how it was registered. Returns 0 if no mapping can be found.

GType gperl_package_from_type (GType gtype)

Look up the name of the package associated with gtype, regardless of how it was registered. Returns NULL if no mapping can be found.

Boxed type support for SV

In order to allow GValues to hold perl SVs we need a GBoxed wrapper.

GPERL_TYPE_SV

Evaluates to the GType for SVs. The bindings register a mapping between GPERL_TYPE_SV and the package 'Glib::Scalar' with gperl_register_boxed().

SV * gperl_sv_copy (SV * sv)

implemented as newSVsv (sv).

void gperl_sv_free (SV * sv)

implemented as SvREFCNT_dec (sv).

UTF-8 strings with gchar

By convention, gchar* is assumed to point to UTF8 string data, and char* points to ascii string data. Here we define a pair of wrappers for the boilerplate of upgrading Perl strings. They are implemented as functions rather than macros, because comma expressions in macros are not supported by all compilers.

These functions should be used instead of newSVpv and SvPV_nolen in all cases which deal with gchar* types.

gchar * SvGChar (SV * sv)

extract a UTF8 string from sv.

SV * newSVGChar (const gchar * str)

copy a UTF8 string into a new SV. if str is NULL, returns &PL_sv_undef.

DESCRIPTION ^

This package defines several utilities for dealing with the GLib type system from Perl. Because of some fundamental differences in how the GLib and Perl type systems work, a fair amount of the binding magic leaks out, and you can find most of that in the Glib::Type::register* functions, which register new types with the GLib type system.

Most of the rest of the functions provide introspection functionality, such as listing properties and values and other cool stuff that is used mainly by Glib's reference documentation generator (see Glib::GenPod).

This is a traffic-cop function. If $parent_type derives from Glib::Object, this passes the arguments through to register_object. If $parent_type is Glib::Flags or Glib::Enum, this strips $parent_type and passes the remaining args on to register_enum or register_flags. See those functions' documentation for more information.

Register new_package as an officially GLib-sanctioned derivative of the (GObject derivative) parent_package. This automatically sets up an @ISA entry for you, and creates a new GObjectClass under the hood.

The ... parameters are key/value pairs, currently supporting:

signals => HASHREF

The signals key contains a hash, keyed by signal names, which describes how to set up the signals for new_package.

If the value is a code reference, the named signal must exist somewhere in parent_package or its ancestry; the code reference will be used to override the class closure for that signal. This is the officially sanctioned way to override virtual methods on Glib::Objects. The value may be a string rather than a code reference, in which case the sub with that name in new_package will be used. (The function should not be inherited.)

If the value is a hash reference, the key will be the name of a new signal created with the properties defined in the hash. All of the properties are optional, with defaults provided:

class_closure => subroutine or undef

Use this code reference (or sub name) as the class closure (that is, the default handler for the signal). If not specified, "do_signal_name", in the current package, is used.

return_type => package name or undef

Return type for the signal. If not specified, then the signal has void return.

param_types => ARRAYREF

Reference to a list of parameter types (package names), omitting the instance and user data. Callbacks connected to this signal will receive the instance object as the first argument, followed by arguments with the types listed here, and finally by any user data that was supplied when the callback was connected. Not specifying this key is equivalent to supplying an empty list, which actually means instance and maybe data.

flags => Glib::SignalFlags

Flags describing this signal's properties. See the GObject C API reference' description of GSignalFlags for a complete description.

accumulator => subroutine or undef

The signal accumulator is a special callback that can be used to collect return values of the various callbacks that are called during a signal emission. Generally, you can omit this parameter; custom accumulators are used to do things like stopping signal propagation by return value or creating a list of returns, etc.

properties => ARRAYREF

Array of Glib::ParamSpec objects, each describing an object property to add to the new type. These properties are available for use by all code that can access the object, regardless of implementation language. See Glib::ParamSpec. This list may be empty; if it is not, the functions GET_PROPERTY and SET_PROPERTY in $new_package will be called to get and set the values. Note that an object property is just a mechanism for getting and setting a value -- it implies no storage. As a convenience, Glib::Object::Subclass provides a default implementation of GET_PROPERTY and SET_PROPERTY which use the property nicknames as hash keys in the object variable for storage.

FIXME finish this

The list of values is used to create the "nicknames" that are used in general Perl code; the actual numeric values used at the C level are automatically assigned, starting with 1. If you need to specify a particular numeric value for a nick, use an array reference containing the nickname and the numeric value, instead. You may mix and match the two styles.

  Glib::Type->register_enum ('MyFoo::Bar',
          'value-one',            # assigned 1
          'value-two',            # assigned 2
          ['value-three' => 15 ], # explicit 15
          ['value-four' => 35 ],  # explicit 35
          'value-five',           # assigned 5
  );

If you use the array-ref form, beware: the code performs no validation for unique values.

The list of values is used to create the "nicknames" that are used in general Perl code; the actual numeric values used at the C level are automatically assigned, of the form 1<<i, starting with i = 0. If you need to specify a particular numeric value for a nick, use an array reference containing the nickname and the numeric value, instead. You may mix and match the two styles.

  Glib::Type->register_flags ('MyFoo::Baz',
           'value-one',               # assigned 1<<0
           'value-two',               # assigned 1<<1
           ['value-three' => 1<<10 ], # explicit 1<<10
           ['value-four' => 0x0f ],   # explicit 0x0f
           'value-five',              # assigned 1<<4
  );

If you use the array-ref form, beware: the code performs no validation for unique values.

List the ancestry of package, as seen by the GLib type system. The important difference is that GLib's type system implements only single inheritance, whereas Perl's @ISA allows multiple inheritance.

This returns the package names of the ancestral types in reverse order, with the root of the tree at the end of the list.

See also list_interfaces ().

List the GInterfaces implemented by the type associated with package. The interfaces are returned as package names.

List the signals associated with package. This lists only the signals for package, not any of its parents. The signals are returned as a list of anonymous hashes which mirror the GSignalQuery structure defined in the C API reference.

- signal_id

Numeric id of a signal. It's rare that you'll need this in Gtk2-Perl.

- signal_name

Name of the signal, such as what you'd pass to signal_connect.

- itype

The instance type for which this signal is defined.

- signal_flags

GSignalFlags describing this signal.

- return_type

The return type expected from handlers for this signal. If undef or not present, then no return is expected. The type name is mapped to the corresponding Perl package name if it is known, otherwise you get the raw C name straight from GLib.

- param_types

The types of the parameters passed to any callbacks connected to the emission of this signal. The list does not include the instance, which is always first, and the user data from signal_connect, which is always last (unless the signal was connected with "swap", which swaps the instance and the data, but you get the point).

List the legal values for the GEnum or GFlags type $package. If $package is not a package name registered with the bindings, this name is passed on to g_type_from_name() to see if it's a registered flags or enum type that just hasn't been registered with the bindings by gperl_register_fundamental() (see Glib::xsapi). If $package is not the name of an enum or flags type, this function will croak.

Returns the values as a list of hashes, one hash for each value, containing that value's name and nickname.

Convert a C type name to the corresponding Perl package name. If no package is registered to that type, returns $cname.

DESCRIPTION ^

Glib maps flag and enum values to the nicknames strings provided by the underlying C libraries. Representing flags this way in Perl is an interesting problem, which Glib solves by using some cool overloaded operators.

The functions described here actually do the work of those overloaded operators. See the description of the flags operators in the "This Is Now That" section of Glib for more info.

syntax highlighting: