GTK+ Widget State Manager

The Problem

Graphical User Interfaces are notoriously tricky and difficult to program: so much information to keep track of, events that must be handled, anticipating user actions, keeping all widgets properly updated, etc.

One aspect of good UI design is maintaining an accurate and consistent relationship between the User Interface state (at any given moment) and how all widgets should be presented when any given UI state is "active".

However, keeping this relationship well-behaved, consistent, and always accurate is a non-trivial exercise in programming GUI applications. And, worse still, when the total number of states and total number of widgets that must be managed is large, the problem increases dramatically in scale and complexity.

But why must this be so? Isn't there an easy way to handle this situation without all the work and pulling-of-hair that normally comes with it?

The Solution

With the GTK+ Widget State Manager (WSM) maintaining this relationship is made easy, logical and obvious.

Now, instead of having to keep track of what you need to do to every widget at every UI state change, simply call the WSM routine to invoke the new UI state and all widgets are updated automatically, guaranteeing consistency and accuracy 100% of the time.

Functionality

You do this by registering each widget needing to be managed (at widget creation) with the WSM library, defining exactly how the widget should appear for each defined UI state.

As delivered the WSM allows control of the following widget state settings:

• Visible - wsm_assign_visible()
• Editable - wsm_assign_editable()
• Sensitive - wsm_assign_sensitive()

Features

• Any widget having the concept of visibility, editibility, and/or sensitivity is handled
• UI states are defined per application at design time, i.e., they are fully descriptive for proper implementation of widget details during the coding phase.
• Ease-of-Use:
  • Widgets are registered once at creation, and may also be de-registered, if this is needed
  • No need to keep track of the previous state
  • Adding new widgets in the future as the application evolves is simply a matter of registering the widget, as per UI state specifications require, and you're done.
  • Changing a UI state is done by simply calling:

wsm_set_UIState( WSM_UISTATE_**APP-STATE** )

Advantages

• Logical and Easy to Implement
• Implementing into pre-existing code is straight-forward
• What was once a head-ache is now simple and easy
• You will gain a deeper understanding of your application, its behaviours and how these relate to end-user interactions.

Extensibility:

• Widget settings other than the three provided can be added to the library quite easily. This extends, then, any other widget-related behaviour(s) having a relationship to a GUI's display state.
• Code Base is very small, thus, quite easy to adapt. Either by adding language bindings for GTK+, or even adapting to other toolkits, e.g., Qt.

Deliverables:

• Source Code, Header Files, and makefile to create the wsm.a library archive
• Registration functions to handle widget visibility, editibility, and sensitivity
• Complete Documentation describing all aspects of how to use the library, detailed instructions to create new registration functions, etc.
• A GUI example implementation demonstrating 4 different UI states, how to register widgets and how to set the UI states.

Target Users:

• All GTK+ developers interested in having precise control over widget states and their relationship to UI states.

Technical Requirements:

• Up-to-date C compiler
• GTK+-2 installed. Gtk+-2 is standard on all *NIX platforms and should not be an issue.

Installation:

• Library is provided as a single file source code (plus header files) for compilation.
• Makefile is provided to create an archive named wsm.a, to be used when linking the final program.

#include "wsm.h"

// In this example, we have the following GUI states to manage:
// 1) No Connection to a Database - DBNOCONN
// 2) Connected to a DB in read-only mode - DBDISPLAY
// 3) Connected and able to edit DB - DBEDIT
// 4) Not connected but creating a new DB - DBCREATE
//   All of these known states are referred to using their ENUM specifier:
//   WSM_UISTATE_APPSTATE - where APPSTATE is one of the above values

void makeWidgets()
{
    // A Connect Button that is only displayed when no DB Connection exists, otherwise not visible
    button = gtk_button_new_with_label("Connect");
    wsm_assign_visible(WSM_UISTATE_DBNOCONN, WSM_TRUE, button);
    wsm_assign_visible(WSM_UISTATE_DBDISPLAY, WSM_FALSE, button);
    wsm_assign_visible(WSM_UISTATE_DBEDIT, WSM_FALSE, button);
    wsm_assign_visible(WSM_UISTATE_DBCREATE, WSM_FALSE, button);

    // An Entry Area that is only editable when creating a database, otherwise read-only
    entry = gtk_entry_new();
    gtk_widget_set_tooltip_text("Name of the Database");
    wsm_assign_editable(WSM_UISTATE_DBNOCONN, WSM_FALSE, entry);
    wsm_assign_editable(WSM_UISTATE_DBDISPLAY, WSM_FALSE, entry);
    wsm_assign_editable(WSM_UISTATE_DBEDIT, WSM_FALSE, entry);
    wsm_assign_editable(WSM_UISTATE_DBCREATE, WSM_TRUE, entry);

    // A 'SAVE' button that is sensitive only when editing a database, otherwise not selectable
    button = gtk_button_new_with_label("SAVE");
    wsm_assign_sensitive(WSM_UISTATE_DBNOCONN, WSM_FALSE, button);
    wsm_assign_sensitive(WSM_UISTATE_DBDISPLAY, WSM_FALSE, button);
    wsm_assign_sensitive(WSM_UISTATE_DBEDIT, WSM_TRUE, button);
    wsm_assign_sensitive(WSM_UISTATE_DBCREATE, WSM_TRUE, button);

    // A more complex and interesting example where we have:
    // A Frame widget housing a Horizontal Box... 
    //  ...this Box housing a Label and Entry Area
    // Here we want to achieve the following:
    //   1) frame (and all contents) is visible only when connected to a DB 
    //   2) entry area is editable only when in DB Edit and Create modes

    frame = gtk_frame_new("WSM Example Frame");
    hbox = gtk_hbox_new(FALSE, 0);
    label = gtk_label_new("DB Description:");
    entry = gtk_entry_new();
    gtk_container_add(GTK_CONTAINER(hbox), label);
    gtk_container_add(GTK_CONTAINER(hbox), entry);
    gtk_container_add(GTK_CONTAINER(frame), hbox);

    // set the entry area states
    wsm_assign_editable(WSM_UISTATE_DBNOCONN, WSM_FALSE, entry);
    wsm_assign_editable(WSM_UISTATE_DBDISPLAY, WSM_FALSE, entry);
    wsm_assign_editable(WSM_UISTATE_DBEDIT, WSM_TRUE, entry);
    wsm_assign_editable(WSM_UISTATE_DBCREATE, WSM_TRUE, entry);

    // set the frame states
    wsm_assign_visible(WSM_UISTATE_DBNOCONN, WSM_FALSE, frame);
    wsm_assign_visible(WSM_UISTATE_DBDISPLAY, WSM_TRUE, frame);
    wsm_assign_visible(WSM_UISTATE_DBEDIT, WSM_TRUE, frame);
    wsm_assign_visible(WSM_UISTATE_DBCREATE, WSM_TRUE, frame);

    // assign all other widgets appropriately as they are created
    //...

}

int main(int argc, char **argv)
{
    // make the widgets of our UI
    make_widgets();

    // Initialize UI Display State to NO DB Connection
    wsm_set_UIState(WSM_UISTATE_DBNOCONN);

    gtk_main();

    exit(0);
}