Xfce Foundation Classes
Main Page | Index | Namespace 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:

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

Copyright © 2004-2005 The XFC Development Team | XFC 4.3