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


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.

Constructors

Public Member Functions

Accessors
Methods

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

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.


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