.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Glib::Error 3pm"
.TH Glib::Error 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Glib::Error \-  Exception Objects based on GError
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\&  eval {
\&     my $pixbuf = Gtk2::Gdk::Pixbuf\->new_from_file ($filename);
\&     $image\->set_from_pixbuf ($pixbuf);
\&  };
\&  if ($@) {
\&     print "$@\en";
\&     if (Glib::Error::matches ($@, \*(AqGtk2::Gdk::Pixbuf::Error\*(Aq,
\&                                   \*(Aqunknown\-format\*(Aq)) {
\&        change_format_and_try_again ();
\&     } elsif (Glib::Error::matches ($@, \*(AqGlib::File::Error\*(Aq, \*(Aqnoent\*(Aq)) {
\&        change_source_dir_and_try_again ();
\&     } else {
\&        # don\*(Aqt know how to handle this
\&        die $@;
\&     }
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Gtk2\-Perl translates GLib's GError runtime errors into Perl exceptions, by
creating exception objects based on Glib::Error.  Glib::Error overloads the
stringification operator, so a Glib::Error object will act like a string if
used with \fBprint()\fR or \fBwarn()\fR, so most code using $@ will not even know the
difference.
.PP
The point of having exception objects, however, is that the error messages
in GErrors are often localized with NLS translation.  Thus, it's not good
for your code to attempt to handle errors by string matching on the the 
error message.  Glib::Error provides a way to get to the deterministic
error code.
.PP
You will typically deal with objects that inherit from Glib::Error, such as
Glib::Convert::Error, Glib::File::Error, Gtk2::Gdk::Pixbuf::Error, etc; these
classes are provided by the libraries that define the error domains.  However,
it is possible to get a base Glib::Error when the bindings encounter an unknown
or unbound error domain.  The interface used here degrades nicely in such a
situation, but in general you should submit a bug report to the binding
maintainer if you get such an exception.
.SH HIERARCHY
.IX Header "HIERARCHY"
.Vb 2
\&  Glib::Boxed
\&  +\-\-\-\-Glib::Error
.Ve
.SH METHODS
.IX Header "METHODS"
.ie n .SS "scalar = Glib::Error::new ($class, $code, $message)"
.el .SS "scalar = Glib::Error::new ($class, \f(CW$code\fP, \f(CW$message\fP)"
.IX Subsection "scalar = Glib::Error::new ($class, $code, $message)"
.ie n .SS "scalar = $class\->\fBnew\fP ($code, $message)"
.el .SS "scalar = \f(CW$class\fP\->\fBnew\fP ($code, \f(CW$message\fP)"
.IX Subsection "scalar = $class->new ($code, $message)"
.IP \(bu 4
\&\f(CW$code\fR (Glib::Enum) an enumeration value, depends on \fR\f(CI$class\fR\fI\fR
.IP \(bu 4
\&\f(CW$message\fR (string)
.PP
Create a new exception object of type \fR\f(CI$class\fR\fI\fR, where \fI\fR\f(CI$class\fR\fI\fR is associated
with a GError domain.  \fI\fR\f(CI$code\fR\fI\fR should be a value from the enumeration type
associated with this error domain.  \fI\fR\f(CI$message\fR\fI\fR can be anything you like, but
should explain what happened from the point of view of a user.
.ie n .SS "integer = $error\->\fBcode\fP"
.el .SS "integer = \f(CW$error\fP\->\fBcode\fP"
.IX Subsection "integer = $error->code"
This is the numeric error code.  Normally, you'll want to use \f(CW\*(C`value\*(C'\fR instead,
for readability.
.ie n .SS "string = $error\->\fBdomain\fP"
.el .SS "string = \f(CW$error\fP\->\fBdomain\fP"
.IX Subsection "string = $error->domain"
The error domain.  You normally do not need this, as the object will be blessed
into a corresponding class.
.ie n .SS "string = $error\->\fBlocation\fP"
.el .SS "string = \f(CW$error\fP\->\fBlocation\fP"
.IX Subsection "string = $error->location"
The source line and file closest to the emission of the exception, in the same
format that you'd get from \fBcroak()\fR or \fBdie()\fR.
.PP
If there's non-ascii characters in the filename Perl leaves them as
raw bytes, so you may have to put the string through
Glib::filename_display_name for a wide-char form.
.ie n .SS "boolean = $error\->\fBmatches\fP ($domain, $code)"
.el .SS "boolean = \f(CW$error\fP\->\fBmatches\fP ($domain, \f(CW$code\fP)"
.IX Subsection "boolean = $error->matches ($domain, $code)"
.IP \(bu 4
\&\f(CW$domain\fR (string)
.IP \(bu 4
\&\f(CW$code\fR (scalar)
.PP
Returns true if the exception in \fR\f(CI$error\fR\fI\fR matches the given \fI\fR\f(CI$domain\fR\fI\fR and
\&\fI\fR\f(CI$code\fR\fI\fR.  \fI\fR\f(CI$domain\fR\fI\fR may be a class name or domain quark (that is, the real
string used in C).  \fI\fR\f(CI$code\fR\fI\fR may be an integer value or an enum nickname;
the enum type depends on the value of \fI\fR\f(CI$domain\fR\fI\fR.
.ie n .SS "string = $error\->\fBmessage\fP"
.el .SS "string = \f(CW$error\fP\->\fBmessage\fP"
.IX Subsection "string = $error->message"
The error message.  This may be localized, as it is intended to be shown to a
user.
.ie n .SS "Glib::Error::register ($package, $enum_package)"
.el .SS "Glib::Error::register ($package, \f(CW$enum_package\fP)"
.IX Subsection "Glib::Error::register ($package, $enum_package)"
.IP \(bu 4
\&\f(CW$package\fR (string) class name to register as a Glib::Error.
.IP \(bu 4
\&\f(CW$enum_package\fR (string) class name of the enum type to use for this domain's error codes.
.PP
Register a new error domain.  Glib::Error will be added @\fIpackage\fR::ISA for
you.  \fIenum_package\fR must be a valid Glib::Enum type, either from a C library
or registered with \f(CW\*(C`Glib::Type::register_enum\*(C'\fR.  After registering an
error domain, you can create or throw exceptions of this type.
.ie n .SS "scalar = Glib::Error::throw ($class, $code, $message)"
.el .SS "scalar = Glib::Error::throw ($class, \f(CW$code\fP, \f(CW$message\fP)"
.IX Subsection "scalar = Glib::Error::throw ($class, $code, $message)"
.ie n .SS "scalar = $class\->\fBthrow\fP ($code, $message)"
.el .SS "scalar = \f(CW$class\fP\->\fBthrow\fP ($code, \f(CW$message\fP)"
.IX Subsection "scalar = $class->throw ($code, $message)"
.IP \(bu 4
\&\f(CW$code\fR (Glib::Enum) an enumeration value, depends on \fR\f(CI$class\fR\fI\fR
.IP \(bu 4
\&\f(CW$message\fR (string)
.PP
Throw an exception with a Glib::Error exception object.
Equivalent to \f(CW\*(C`croak (Glib::Error::new ($class, $code, $message));\*(C'\fR.
.ie n .SS "string = $error\->\fBvalue\fP"
.el .SS "string = \f(CW$error\fP\->\fBvalue\fP"
.IX Subsection "string = $error->value"
The enumeration value nickname of the integer value in \f(CW\*(C`$error\->code\*(C'\fR, 
according to this error domain.  This will not be available if the error
object is a base Glib::Error, because the bindings will have no idea how to
get to the correct nickname.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Glib, Glib::Boxed
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2003\-2011 by the gtk2\-perl team.
.PP
This software is licensed under the LGPL.  See Glib for a full notice.