RSSGui - A C++ wrapper for the IUP GUI toolkit

This is a short introduction to the GUI tookit RSSGui which is a simple and easy to use C++ wrapper for the ANSI C GUI toolkit IUP.

The current version of RSSGui is 0.5. This release contains wrappers for most of the IUP widgets and adds a widget type that can be used to create wizards. Not all events and functions availabe in IUP are already wrapped by RSSGui, but the event handling mechanism is very simple and easy to extend. If you miss somethin, please tell me. The current version is only tested on the Windows platform. If you can successfully use it on any other platform or if you have any problems anywhere, please tell me!

The goals

I know a lot of C++ GUI toolkits. Most of them have some drawbacks: Either they come with a lot of classes that represent strings, lists, vectors etc. which are already defined in a wunderful way in the C++ STL, they don't use native widgets or they have a complicated and error prone event handling (like MFC or wxWidgets) or they use language extensions (like Qt). So my goals when designing RSSGui where:

Simplicity

I think I reached these goals quite good. The event handling is really simple and easy to understand as well as easy to use. Unfortunately it is not typesafe. It could have been realized in a type safe way as I saw it in a signal and slot library that I found on the web. But, well - I don't consider type safety as a primary design goal, so I am happy with the current design.

Some examples

If you are still interested in using RSSGui for your applications, please have a look at the following examples...

Basics

The only file you need to include is RSSGui.h. You don't need to include any IUP headers if you don't want to use IUP functions directly. At the beginning of your program you should call the function rssGuiInit() and at the end rssGuiRelease(). Just by the way: You can use IUP functions directly on your RSSGui widgets - you can receive a widget pointer by calling the method getHandle() and cast the returned pointer from void * to Ihandle *, but this is not really tested or suggested...

Example 1: Creating a a dialog with a button

This simple example creates a dialog, places a button on it and starts the main event loop (but doesn't use an event handler):

#include "RSSGui.h"

int main()
{
  rssGuiInit(); 

  // create a dialog with a simple button
  RSSButton *b1 = new RSSButton("Click me!");
  RSSDialog *d1 = new RSSDialog(b1, "RSSGui Example"); 

  // set a tool tip for the button
  b1->setToolTip("A cool button"); 

  // show the dialog
  d1->show(); 

  // Start the main event loop
  RSSEventManager *eventManager = RSSEventManager::getInstance();
  eventManager->mainLoop(); 

  delete d1; 

  rssGuiRelease();
  return 0;
}

The button gets a tool tip simply by calling the method setToolTip() that is inherited from RSSWidget.

Example 2: Event handler

#include "RSSGui.h"

class MyDialog : RSSEventHandler
{
public:
  int button1Event(RSSEvent &event)
  {
    static int flag = 0;
    flag = 1 - flag; // toggle between 0 and 1

    ((RSSButton *)(event.getWidget()))->setLabel(flag ? "text1" : "text2");
    return RSSGUIDEFAULT;
  }

  int button2Event(RSSEvent &event)
  {
    return RSSGUICLOSE;
  }

  void doIt()
  {
    // create a dialog with a simple button
    RSSButton *b1 = new RSSButton("Button 1");
    RSSButton *b2 = new RSSButton("Close");
    RSSVBox *v1 = new RSSVBox(b1, b2, 0);
    RSSDialog *d1 = new RSSDialog(v1, "RSSGui Example");

    // set tool tips for the buttons
    b1->setToolTip("A cool button");
    b2->setToolTip("Close this wunderful application");

    // show the dialog
    d1->show();

    // register the event handlers
    rssRegisterEvent(b1, MyDialog::button1Event);
    rssRegisterEvent(b2, MyDialog::button2Event);

    // Start the main event loop
    RSSEventManager *eventManager = RSSEventManager::getInstance();
    eventManager->mainLoop();

    delete d1;
  }
};

int main()
{
  rssGuiInit();

  MyDialog d;
  d.doIt();

  rssGuiRelease();
  return 0;
}

An event handler is a method in a class that is derived from RSSEventHandler. All event handlers are methods that receive an argument of type RSSEvent and that return an integer value. This return value controls if the application should be continued or terminated etc. - exactly as in IUP itself. The class RSSEvent has a lot of member functions that you can use to access information about the event. For example you can use the method getWidget() to access the widget that caused the event - in this case the button that has been clicked.

The idea of the event handling mechanism is really simple - call the macro rssRegisterEvent and connect an event handler to an event type of a widget. That's it. No magic macros in your headers that are similarly repeated in the implementation files and no language extension. Simply calling a macro to connect the event and the event handler.

Support

The project RSSGui is not officially supported. But if you have any problems, need any missing features or just want to talk about the system, don't hesitate to contact me.

The License

RSSGui is distributed under the same license conditions as IUP itself. This means that you can use it in modified or unmodified form for any comercial and non comercial purpose. You should mention the copyright notice of the IUP project and additionally the following copyright notice somewhere in your program or in your documentation and you should put a Tecgraf and a Reinhold Software Services logo somewhere on your website:

RSSGui (C) 2005 by Reinhold Software Services

RSSGui is developed and sponsored by Reinhold Software Services.