1Glib::Error(3)        User Contributed Perl Documentation       Glib::Error(3)
2
3
4

NAME

6       Glib::Error -  Exception Objects based on GError
7

SYNOPSIS

9         eval {
10            my $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename);
11            $image->set_from_pixbuf ($pixbuf);
12         };
13         if ($@) {
14            print "$@\n";
15            if (Glib::Error::matches ($@, 'Gtk2::Gdk::Pixbuf::Error',
16                                          'unknown-format')) {
17               change_format_and_try_again ();
18            } elsif (Glib::Error::matches ($@, 'Glib::File::Error', 'noent')) {
19               change_source_dir_and_try_again ();
20            } else {
21               # don't know how to handle this
22               die $@;
23            }
24         }
25

DESCRIPTION

27       Gtk2-Perl translates GLib's GError runtime errors into Perl exceptions,
28       by creating exception objects based on Glib::Error.  Glib::Error over‐
29       loads the stringification operator, so a Glib::Error object will act
30       like a string if used with print() or warn(), so most code using $@
31       will not even know the difference.
32
33       The point of having exception objects, however, is that the error mes‐
34       sages in GErrors are often localized with NLS translation.  Thus, it's
35       not good for your code to attempt to handle errors by string matching
36       on the the error message.  Glib::Error provides a way to get to the
37       deterministic error code.
38
39       You will typically deal with objects that inherit from Glib::Error,
40       such as Glib::Convert::Error, Glib::File::Error,
41       Gtk2::Gdk::Pixbuf::Error, etc; these classes are provided by the
42       libraries that define the error domains.  However, it is possible to
43       get a base Glib::Error when the bindings encounter an unknown or
44       unbound error domain.  The interface used here degrades nicely in such
45       a situation, but in general you should submit a bug report to the bind‐
46       ing maintainer if you get such an exception.
47

METHODS

49       scalar = Glib::Error::new ($class, $code, $message)
50
51       scalar = $class->new ($code, $message)
52
53           * $code (GEnum) an enumeration value, depends on $class
54           * $message (string)
55
56           Create a new exception object of type $class, where $class is asso‐
57           ciated with a GError domain.  $code should be a value from the enu‐
58           meration type associated with this error domain.  $message can be
59           anything you like, but should explain what happened from the point
60           of view of a user.
61
62       integer = $error->code
63
64           This is the numeric error code.  Normally, you'll want to use
65           "value" instead, for readability.
66
67       string = $error->domain
68
69           The error domain.  You normally do not need this, as the object
70           will be blessed into a corresponding class.
71
72       string = $error->location
73
74           The source line and file closest to the emission of the exception,
75           in the same format that you'd get from croak() or die().
76
77       boolean = $error->matches ($domain, $code)
78
79           * $domain (string)
80           * $code (scalar)
81
82           Returns true if the exception in $error matches the given $domain
83           and $code.  $domain may be a class name or domain quark (that is,
84           the real string used in C).  $code may be an integer value or an
85           enum nickname; the enum type depends on the value of $domain.
86
87       string = $error->message
88
89           The error message.  This may be localized, as it is intended to be
90           shown to a user.
91
92       Glib::Error::register ($package, $enum_package)
93
94           * $package (string) class name to register as a Glib::Error.
95           * $enum_package (string) class name of the enum type to use for
96           this domain's error codes.
97
98           Register a new error domain.  Glib::Error will be added @pack‐
99           age::ISA for you.  enum_package must be a valid Glib::Enum type,
100           either from a C library or registered with "Glib::Type::regis‐
101           ter_enum".  After registering an error domain, you can create or
102           throw exceptions of this type.
103
104       scalar = Glib::Error::throw ($class, $code, $message)
105
106       scalar = $class->throw ($code, $message)
107
108           * $code (GEnum) an enumeration value, depends on $class
109           * $message (string)
110
111           Throw an exception with a Glib::Error exception object.  Equivalent
112           to "croak (Glib::Error::new ($class, $code, $message));".
113
114       string = $error->value
115
116           The enumeration value nickname of the integer value in
117           "$error->code", according to this error domain.  This will not be
118           available if the error object is a base Glib::Error, because the
119           bindings will have no idea how to get to the correct nickname.
120

ENUMS AND FLAGS

122       enum GEnum
123

SEE ALSO

125       Glib
126

128       Copyright (C) 2003-2007 by the gtk2-perl team.
129
130       This software is licensed under the LGPL.  See Glib for a full notice.
131
132
133
134perl v5.8.8                       2007-02-26                    Glib::Error(3)
Impressum