Hello MUI – How to Write Your First AmigaOS App Using MUI

By / / Amiga / AmigaOS

Today, I’m going to show you how to create your very first MUI app on this next-gen Amiga system. We’re going to keep things very simple. Just a window with a hello message. Yes, its basic, but it’s also the first step toward building sleek and functional GUIs on Amiga computers using MUI. Lets get started.

NOTE: The code can be downloaded from the Kea Campus by Creator & higher tiers. Click here for more.

MUI is a Retained Mode GUI System

MUI, (a.k.a., Magic User Interface) is what’s known as a retained-mode GUI. Sounds complicated? That’s a fancy way of saying that you build the GUI ahead of time, and then your program runs an event loop that waits for and responds to events such as user mouse clicks and key presses.

If you look at the code, you can see each of these steps (see below).

  • First, there’s the code that creates the MUI objects, and builds a window
  • Next, you see code signalling the window to open
  • That’s followed by the main loop that waits for and processes events
  • And the final code shuts down the GUI and deallocates everything
int main(intargc, constchar**argv) {
    if(!openLibraries()) {
        // Cleanup any libraries that were opened
        closeLibraries();
        return EXIT_FAILURE;
    }
    Object *mainWindow = NULL;
    Object *app = buildGUI(&mainWindow);
    if(!app) {
        // This should never happen, but just in case…
        showErrorMessage(“Critical Error”,
“Couldn’t create MUI application.”);
        return EXIT_FAILURE;
    }
    // Main loop
    SetAttrs(mainWindow, MUIA_Window_Open, TRUE, TAG_DONE);
    ULONG signals = 0;
    while (DoMethod(app, MUIM_Application_NewInput, &signals) !=
MUIV_Application_ReturnID_Quit) {
        // Check for Ctrl+C
        signals = Wait(signals | SIGBREAKF_CTRL_C);
        if (signals & SIGBREAKF_CTRL_C) break;
    }
    // Cleanup
    SetAttrs(mainWindow, MUIA_Window_Open, FALSE, TAG_DONE);
    MUI_DisposeObject(app);
    closeLibraries();
    return EXIT_SUCCESS;
}

Notice how the main loop is essentially empty. It basically waits for the GUI to signal that it’s time to exit, either by clicking the window’s close gadget, or pushing the escape key.

That’s because MUI’s preferred method of working is to handle events by passing notifications between objects directly. One advantage of this approach, is that MUI gadgets can directly update each other instead of having to go through the application’s main loop.

This isn’t unique MUI, though. Reaction and even AmigaOS 3 BOOPSI gadgets can also directly notify each other. From memory, that’s done via the OM_NOTIFY method.

What is different, is how MUI sends events to the application itself. MUI’s ideal is actually to never return anything to the main loop except for the close event. Everything else is implemented as MUI classes instead. For example, you’d create your own MUI application sub-class, and add all your notification and event handling code to your custom application class.

This makes for a small clean main loop, and improves code modularity because the notifications are sent directly to the objects that need them rather than having to go through the classic wait loop with a big centralized switch() statement. I’m not convinced that the notification/messaging approach really is superior than the classic centralized switch() statement. Sure, using a big switch statement might be big and ugly, but it’s very clear what the program’s execution path is.

Anyway, MUI is designed to use notifications, sub-classes and callbacks, so lets use it as designed. Actually, since our “Hello MUI” program is so basic, we don’t have any notifications other than the window close event. So, we don’t need to sub-class anything.

The Code in Detail

Let’s go through the code bit by bit. First, we open the libraries that are needed, which is basically the muimaster.library. Be sure to use the provided MUIMASTER_NAME, & MUIMASTER_VMIN macros, so that the minimum muimaster.library matches the MUI header files.

static bool openLibraries() {
    MUIMasterBase = (typeof(MUIMasterBase))
openLibraryOrShowError(MUIMASTER_NAME, MUIMASTER_VMIN);
    if(!MUIMasterBase) { return false; }

On AmigaOS 4, we also need to open the muimaster.library’s main interface.

#ifdef __amigaos4__
    // Need to open all the interfaces
    IMUIMaster = (typeof(IMUIMaster))getInterfaceOrShowError(
(struct Library*)MUIMasterBase, MUIMASTER_NAME, “main”, 1);
    if(!IMUIMaster) { return false; }
#endif
    return true;
}

Oh yeah, I also define __USE_INLINE__ and __USE_BASETYPE__ at the top of the source file. This eliminates the need to use interface pointers on AmigaOS 4, and allows me to write code that’s portable across all AmigaOS variants and clones.

/** Allows us to call library functions without AmigaOS 4 interfaces
* (e.g., OpenLibrary() instead of IExec->OpenLibrary()).
 */
#define__USE_INLINE__
#define__USE_BASETYPE__

The next step is to build the GUI, which I’ve put in the function buildGUI(). This creates an application with a single window, that in turn contains a static text gadget contained in a MUI group object. MUI groups are used to lay out gadgets in the window. It’ll become more important once we start building GUIs with more than one gadget.

Object*buildGUI(Object**window) {
    Object *win = NULL;
    Object *app = MUI_NewObject(MUIC_Application,
        MUIA_Application_Author, (ULONG)PROG_AUTHOR,
        MUIA_Application_Base, (ULONG)PROG_NAME,
        MUIA_Application_Copyright, (ULONG)PROG_COPYRIGHT,
        MUIA_Application_Description, (ULONG)PROG_DESCRIPTION,
        MUIA_Application_Title, (ULONG)PROG_TITLE,
        MUIA_Application_Version, (ULONG)VERSTAG,
        MUIA_Application_Window, (ULONG)(win = MUI_NewObject(MUIC_Window,
            MUIA_Window_Title, (ULONG)WINDOW_TITLE,
            MUIA_Window_RootObject, MUI_NewObject(MUIC_Group,
                MUIA_Group_Child, MUI_NewObject(MUIC_Text,
                    MUIA_Text_Contents, (ULONG)“Hello world! I’m a MUI program”,
                TAG_END),
            TAG_END),
        TAG_END)),
    TAG_END);

If the application object is successfully created, then we set up a notification from the Window object to the application object via the following code:

    if(app) {
        // Setup GUI notifications
        DoMethod(win, MUIM_Notify, MUIA_Window_CloseRequest, TRUE, app, 2,
            MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);
    }
    *window = win;
    return app;
}

It calls the MUIM_Notify method on the Window, telling it to send the app an application quit notification if the window’s close button is clicked.

We open the window just before entering the main loop. This must be done manually, because you might want to create a window, but show it later.

SetAttrs(mainWindow, MUIA_Window_Open, TRUE, TAG_DONE);

Next, we have the main loop. It basically waits for the application object to either receive a MUIV_Application_ReturnID_Quit notification. Or, for a Ctrl+C signal. In both cases, the loop exits, and drops into the cleanup code.

    ULONG signals = 0;
    while (DoMethod(app, MUIM_Application_NewInput, &signals) !=
MUIV_Application_ReturnID_Quit) {
        // Check for Ctrl+C
        signals = Wait(signals | SIGBREAKF_CTRL_C);
        if (signals & SIGBREAKF_CTRL_C) break;
    }

The cleanup code closes the window, deallocates the app object, which in turn deletes the window and everything in it. The muimaster.library is closed, and the program exists:

    // Cleanup
    SetAttrs(mainWindow, MUIA_Window_Open, FALSE, TAG_DONE);
    MUI_DisposeObject(app);
    closeLibraries();
    returnEXIT_SUCCESS;
}

 Let’s compile and test this (see the image below).

Congratulations, you’ve got your first MUI program working. The source code for this example can be downloaded below (Creator & higher tiers).

Next time we can add some actual gadgets, and make an app that does something useful. I’ll see you then.

Thanks to Kea Campus Amiga Corner Members

Thanks to Kea Campus Amiga Corner members for sponsoring this video. If you want the source code and/or want to support future Amiga videos, then click here and join the Kea Campus.

Download

he source code for this example can be downloaded from the Kea Campus by Creator and higher tier members.

Click here to join the Kea Campus; get the code, and support Amiga content.

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *

 


Shopping Cart
Scroll to Top