Hello World

This section shows how to code a simple "Hello World" application. It will display a window with a clickable button. Clicking on the button will exit the application. In addition, the user can click on the system menu and click on close or press the ESCAPE key to exit.

Code

Hello World

#include "fdostui.hpp"
#include <stdio.h>

// button callback. signal the window manager to exit.
void
button_clicked_cb(button const*, void*)
{
    wm_quit(ERROR_USER_ESC);
    return;
}

int
main(void)
{

    // initialize the FDOSTUI subsytem (mouse and display)
    wm_error error= wm_init();

    // if an error occurred exit
    if (error)
    {
        printf("Unable to initialze FDOSTUI subsystem\n");
        return error;
    }

    // create our main window
    window* win= new window(30, 9, 20, 8);

    // register it with the window manager
    wm_register_window(win);

    // create a button widget and add it to the window
    button* btn= new button(1, 1, 16, 4);
    btn->set_text((unsigned char*)"Hello World!");
    btn->set_style(button::STYLE_BOX|button::STYLE_SHADOW);
    btn->set_signal_clicked(button_clicked_cb);
    win->add(btn);

    // draw the window
    wm_draw(win);

    // enter the window manager loop
    wm_run();

    // restore the system to it's default settings
    wm_deinit();

    return 0;
}

Compiling

wcl -i=\source\fdostui\include -0 -mm -bcl=DOS -k4096 hello.cpp \source\fdostui\lib\fdtuid16.lib

For debugging data, add '-d3' on the command line.

Explanation

The steps are as follows:

• Initialize the subsystem
• Create application window
• Create controls
• Call the run loop
• Restore the subsystem

Initialize the subsystem

// initialize the FDOSTUI subsytem (mouse and display)
wm_error error= wm_init();

// if an error occurred exit
if (error)
{
    printf("Unable to initialze FDOSTUI subsystem\n");
    return error;
}

The first step is to initialize the FDOSTUI subsystem. This will change the display and register a mouse handler. When the application is finished running, it is important that the system is restored back to default settings.

Following the call to wm_init the code checks for an error. If an error has occurred, the library can not be used. In the example above an error message is displayed and control returned to the operating system.

Create application window

// create our main window
window* win= new window(30, 9, 20, 8);

// register it with the window manager
wm_register_window(win);

The second step is to create the application window. A window is a container, which can hold other widgets. Following, it is registered to the window manager. The window manager will then take both ownership and control of the widget.
The window must not be deleted after it has been registered. To do that, unregister the window wm_unregister_window. Following, it is safe to be disposed of.

Create controls

// create a button widget and add it to the window
button* btn= new button(1, 1, 16, 4);
btn->set_text((unsigned char*)"Hello World!");
btn->set_style(button::STYLE_BOX|button::STYLE_SHADOW);
btn->set_signal_clicked(button_clicked_cb);
win->add(btn);

The third step is to create controls that are added to the widget. In this example, a button widget is created and added to the window. The button widget adds a signal that will be called when the user clicks on the button.

void
button_clicked_cb(button const*, void*)
{
    wm_quit(ERROR_USER_ESC);
    return;
}

The signal sends a signal indicating that the window manager should exit. Internally, a flag is set and during the next ieteration of the run loop, the flag will be checked. If it is not zero, the window manager will cleanup and then exit.

Call the run loop

// draw the window
wm_draw(win);

// enter the window manager loop
wm_run();

The forth step is to draw (show) the widget to the screen. The run loop will not do this. Following, the run loop is called. At this point the application will spin in a loop collecting and dispatching events. However, it will capture the EScAPE key and exit the loop if it was pressed.

Restore the subsystem

// restore the system to it's default settings
wm_deinit();

The fith and final step is critical. The initialization step had registered a mouse handler, which if not turned off will crash the system after the application exits. In addition, it may have altered the display. wm_deinit will restore the system back to default settings. After this point, the library is no longer in a usable state.