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
29       overloads the stringification operator, so a Glib::Error object will
30       act 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
34       messages in GErrors are often localized with NLS translation.  Thus,
35       it's not good for your code to attempt to handle errors by string
36       matching on the the error message.  Glib::Error provides a way to get
37       to the 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
46       binding maintainer if you get such an exception.
47

HIERARCHY

49         Glib::Boxed
50         +----Glib::Error
51

METHODS

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

SEE ALSO

123       Glib, Glib::Boxed
124
126       Copyright (C) 2003-2011 by the gtk2-perl team.
127
128       This software is licensed under the LGPL.  See Glib for a full notice.
129
130
131
132perl v5.38.0                      2023-08-01                    Glib::Error(3)
Impressum