Piles

Introduction

The UserMsg class provides a way to manage and dispatch messages that are intended for the user. The library does not provide the GUI to actually show the messages. Instread, a callback mechanism is employed and the user is expected to provide necessary callbacks. Also, the Qt signal/slot mechanism is also used, so the user has some flexibility in implementing the front-end.

Manager class

UserMsgMan is the manager class. A singleton is created internally and it manages the settings and behaviour of UserMsg. The manager can be explicitly initialized but it does not have to. Any static function that will be invoked will first check for its existance and it will create it if it does not exist. Resources can be freed using UserMsgMan::end(), for example at the end of the application.

The messaging system can be disabled temporarly by calling UserMsgMan::disable(). It will accumulate the messages internaly and show them when UserMsgMan::enable() is called. The messages can be collapsed into one per type.

An initialization sequence that makes use of all the features of the manager may look like so:

int main (int argc, char *argv[])
{
    QApplication apl(argc, argv);
    int ret_val = 0;

    UserMsgMan::init (true); // true - start disabled; cache the messages until GUI is in place
    UserMsgMan::filter (UserMsg::ERROR | UserMsg::WARNING);

    MainWindow mw;
    mw.show ();

    // connect the signals to MainWindow
    UserMsgMan::connect (&mw, SLOT("userMessage(UserMsg::Type, const QString &)));

    UserMsgMan::enable (true); // show any cached messages
    // we can choose to collapse all messages in a single message before
    // transmitting them to be shown. In a gui that uses as front-end
    // QMessageBox, for example, without this option the user would see
    // one message box for each message that was produced.

    apl.exec ();

    return 0;
}
UserMsg::err ("An error message that is shown right away.");
UserMsg::wrn ("A warning message that is shown right away.");
UserMsg::info ("An informative message that is shown right away.");
UserMsg::msg (UserMsg::ERROR, "An error message that is shown right away.");

GUI Front-end

The frontend has a range of options to connect and use the library.

Callbacks

Following callbacks are available:

• enabled / disabled
• show message for all kinds of messages
• show message for a particular kind (one per kind)

Qt Signals

Following signals are available:

• show message for all kinds of messages
• show message for a particular kind (one per kind)
• show message for a particular kind (one per kind) with extended information (time, title)

UserMsg

A message consists of an optional title, an optional user defined value (payload) and a list of zero or more entries.

Each entry consists of a timestamp, a type and a message.

Informative messages

The informative messages are errors, warnings and general information that is intended to the user. The user is only informed about the event and, depending on the GUI front-end, may need to confirm message acknowledgement.

A message can be shown right away:

UserMsg::err ("An error message that is shown right away.");
UserMsg::wrn ("A warning message that is shown right away.");
UserMsg::info ("An informative message that is shown right away.");
UserMsg::msg (UserMsg::ERROR, "An error message that is shown right away.");

Messages can be accumulated in an instance of the class and presented later (or never presented):

UserMsg um;
um.addErr ("An error message that is not shown right away.");
um.addWrn ("A warning message that is not shown right away.");
um.addInfo ("A warning message that is not shown right away.");
um.add (UserMsg::DEBUG_WARNING, "A warning message that is not shown right away.");

To show the content accumulated in the structure, if any, use:

um.show ();

This will present the user with the messages the user elected to see.