Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Public Member Functions
Xfc::G::Error Class Reference

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

#include <xfc/glib/error.hh>

Inheritance diagram for Xfc::G::Error:
Xfc::StackObject

List of all members.

Public Member Functions

Constructors

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.)

This class can be thrown, as an std exception too.

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,
  ... 
) throw ()

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

Parameters:
domainThe error domain.
codeThe error code.
formatParameters for message format.
...Arguments to format.
Xfc::G::Error::Error ( GQuark  domain,
int  code,
const String message 
) throw ()

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

Parameters:
domainThe error domain.
codeThe error code.
messageThe 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:
domainAn error domain.
codeAn error code.
Returns:
Whether error has domain and code.
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:
domainThe error domain.
codeThe error code.
formatprintf()-style message format.
...Arguments to format.
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:
domainThe error domain.
codeThe error code.
messageThe 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.


The documentation for this class was generated from the following file:
Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC