Xfce Foundation Classes

Xfc::G::Error Class Reference

A C++ GLib error reporting class. More...

#include <xfc/glib/error.hh>

Inheritance diagram for Xfc::G::Error:

List of all members.

Public Member Functions

Constructors

Error ()
Create a properly initialized error object.
Error (GQuark domain, int code, const char *format,...)
Create a new error object with the given domain and code, and a message formatted with format.
Error (GQuark domain, int code, const String &message)
Create a new error object with the given domain, code, and message.
Error (GError *error)
Create an Error from an existing GError*. Used by XFC for error reporting.
Error (const Error &src)
Copy constructor.
~Error ()
Destructor.
Error & operator= (const Error &src)
Assignment operator.

Accessors

operator GError * () const
Returns the internal GError pointer.
operator GError ** ()
The return location for an allocated error.
bool get () const
Returns true if the error-reporting function failed and reported an error.
bool matches (GQuark domain, int code) const
Returns true if error matches domain and code, false otherwise.
Quark domain () const
Returns the error domain.
int code () const
Returns the error code.
const char * message () const
Returns the human-readable informative error message.

Methods

void set (GQuark domain, int code, const char *format,...)
A new error object is created and assigned to the internal error pointer.
void set (GQuark domain, int code, const String &message)
A new error object is created and assigned to the internal error pointer.
void propagate (const Error &src)
Moves src into the calling error object.
void clear ()
Frees the associated GError object and sets the internal error pointer to null.

Detailed Description

A C++ GLib error reporting class.

Error provides a C++ wrapper for GLib's standard method of reporting errors from a called function to the calling code. It's important to understand that this method is both a data type (the Error object) and a set of rules. If you use Error incorrectly, then your code will not properly interoperate with other code that uses Error, and users of your API will probably get confused.

First and foremost: Error should only be used to report recoverable runtime errors, never to report programming errors. If the programmer has screwed up, then you should use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some similar facility. (Incidentally, remember that the g_error() function should only be used for programming errors, it should not be used to print any error reportable via G::Error.)

Examples of recoverable runtime errors are "file not found" or "failed to parse input". Runtime errors should be handled or reported to the user, programming errors should be eliminated by fixing the bug in the program. This is why most functions in XFC do not use the Error facility. You will find examples of Error usage in the gfc-demo program. The following example is from "demowindow.cc".

    Pointer<Gdk::Pixbuf> pixbuf;
    G::Error error;
   
    String filename = find_file("gtk-logo-rgb.gif", &error);
    if (!filename.null())
        pixbuf = new Gdk::Pixbuf(filename, &error);
   
    if (error.get())
    {
        Gtk::MessageDialog dialog(Gtk::MESSAGE_ERROR, Gtk::BUTTONS_CLOSE, this);
        dialog.set_message("Failed to read icon file: %s", error.message());
        dialog.set_position(Gtk::WIN_POS_CENTER);
        dialog.run();
        dialog.dispose();
    }

Note that passing NULL for the error location ignores errors.

Constructor & Destructor Documentation

Xfc::G::Error::Error ( GQuark domain,

int code,

const char * format,

...

)

Create a new error object with the given domain and code, and a message formatted with format.

Parameters:

domain The error domain.

code The error code.

format Parameters for message format.

... Arguments to format.

Xfc::G::Error::Error ( GQuark domain,

int code,

const String & message

)

Create a new error object with the given domain, code, and message.

Parameters:

domain The error domain.

code The error code.

message The error message.

Unlike the other constructor, message is not a printf()-style format string. Use this constructor if message contains text you don't have control over, that could include printf() escape sequences.

Member Function Documentation

bool Xfc::G::Error::matches ( GQuark domain,

int code

) const

Returns true if error matches domain and code, false otherwise.

Parameters:

domain An error domain.

code An error code.

Returns:
Whether error has domain and code.

void Xfc::G::Error::set ( GQuark domain,

int code,

const String & message

)

A new error object is created and assigned to the internal error pointer.

Parameters:

domain The error domain.

code The error code.

message The error message.

Unlike the other set method, message is not a printf()-style format string. Use this method if message contains text you don't have control over, that could include printf() escape sequences.

void Xfc::G::Error::set ( GQuark domain,

int code,

const char * format,

...

)

A new error object is created and assigned to the internal error pointer.

Parameters:

domain The error domain.

code The error code.

format printf()-style message format.

... Arguments to format.

The documentation for this class was generated from the following file:

error.hh

Xfce Foundation Classes

XFC 4.3