amiga-bootcamp/09_intuition/frameworks/mui/03-getting-started.md

← Home · Intuition · Frameworks

Getting Started

Required Includes

Every MUI application needs at minimum:

#include <libraries/mui.h>

Depending on your compiler, you also need one of the following for function prototypes:

/* For SAS/C, DICE, and other traditional compilers */
#include <clib/muimaster_protos.h>
#include <pragmas/muimaster_pragmas.h>

/* For GCC */
#include <inline/muimaster.h>

A typical MUI program also includes standard AmigaOS headers:

#include <dos/dos.h>
#include <graphics/gfxmacros.h>
#include <workbench/workbench.h>
#include <clib/alib_protos.h>
#include <clib/exec_protos.h>
#include <clib/dos_protos.h>
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>
#include <clib/gadtools_protos.h>
#include <clib/utility_protos.h>
#include <clib/asl_protos.h>

Opening the Library

Before using any MUI functions, open muimaster.library:

#define MUIMASTER_NAME    "muimaster.library"
#define MUIMASTER_VMIN    11

struct Library *MUIMasterBase;

if (!(MUIMasterBase = OpenLibrary(MUIMASTER_NAME, MUIMASTER_VMIN)))
{
    /* handle error */
}

The minimum required version is 11. Some macros in libraries/mui.h require V11 or above.

When your application exits, close the library:

CloseLibrary(MUIMasterBase);

Minimal "Hello MUI" Application

Here is the smallest possible MUI application that opens a window with some text:

#include <libraries/mui.h>
#include <clib/muimaster_protos.h>
#include <clib/exec_protos.h>
#include <clib/intuition_protos.h>
#include <pragmas/muimaster_pragmas.h>
#include <pragmas/exec_pragmas.h>
#include <pragmas/intuition_pragmas.h>
#include <stdio.h>
#include <stdlib.h>

struct Library *MUIMasterBase;
extern struct Library *SysBase;

int main(int argc, char *argv[])
{
    APTR app, window;

    if (!(MUIMasterBase = OpenLibrary(MUIMASTER_NAME, MUIMASTER_VMIN)))
    {
        printf("Failed to open %s\n", MUIMASTER_NAME);
        return 20;
    }

    app = ApplicationObject,
        MUIA_Application_Title      , "HelloMUI",
        MUIA_Application_Version    , "$VER: HelloMUI 1.0",
        MUIA_Application_Copyright  , "Your Name",
        MUIA_Application_Author     , "Your Name",
        MUIA_Application_Description, "A minimal MUI application",
        MUIA_Application_Base       , "HELLOMUI",

        SubWindow, window = WindowObject,
            MUIA_Window_Title, "Hello MUI",
            MUIA_Window_ID   , MAKE_ID('H','L','O','1'),

            WindowContents, VGroup,
                Child, TextObject,
                    MUIA_Text_Contents, "\33cHello, MUI World!",
                    End,
                End,

            End,
        End;

    if (!app)
    {
        printf("Failed to create Application.\n");
        CloseLibrary(MUIMasterBase);
        return 20;
    }

    /* Close window when requested */
    DoMethod(window, MUIM_Notify, MUIA_Window_CloseRequest, TRUE,
        app, 2, MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);

    set(window, MUIA_Window_Open, TRUE);

    {
        ULONG sigs = 0;

        while (DoMethod(app, MUIM_Application_NewInput, &sigs)
               != MUIV_Application_ReturnID_Quit)
        {
            if (sigs)
            {
                sigs = Wait(sigs | SIGBREAKF_CTRL_C);
                if (sigs & SIGBREAKF_CTRL_C)
                    break;
            }
        }
    }

    set(window, MUIA_Window_Open, FALSE);
    MUI_DisposeObject(app);
    CloseLibrary(MUIMasterBase);

    return 0;
}

The demo.h Pattern

The official MUI examples use a common header file called demo.h that centralizes includes and provides helper functions. This is a recommended pattern for your own projects:

/* demo.h - common includes and helpers for MUI applications */

#include <libraries/mui.h>
#include <dos/dos.h>
#include <graphics/gfxmacros.h>
#include <workbench/workbench.h>
#include <clib/alib_protos.h>
#include <clib/exec_protos.h>
#include <clib/dos_protos.h>
#include <clib/icon_protos.h>
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>
#include <clib/gadtools_protos.h>
#include <clib/utility_protos.h>
#include <clib/asl_protos.h>

#ifndef __GNUC__
#include <clib/muimaster_protos.h>
#else
#include <inline/muimaster.h>
#endif

#include <stdlib.h>
#include <string.h>
#include <stdio.h>

extern struct Library *SysBase, *IntuitionBase, *UtilityBase;
extern struct Library *GfxBase, *DOSBase, *IconBase;
struct Library *MUIMasterBase;

/* A fail function that cleans up and exits */
static VOID fail(APTR app, char *str)
{
    if (app)
        MUI_DisposeObject(app);

#ifndef _DCC
    if (MUIMasterBase)
        CloseLibrary(MUIMasterBase);
#endif

    if (str)
    {
        puts(str);
        exit(20);
    }
    exit(0);
}

/* Open muimaster.library */
static VOID init(VOID)
{
#ifndef _DCC
    if (!(MUIMasterBase = OpenLibrary(MUIMASTER_NAME, MUIMASTER_VMIN)))
        fail(NULL, "Failed to open " MUIMASTER_NAME ".");
#endif
}

Compiler Setup

SAS/C

The official examples were written for SAS/C. Key settings:

• Stack size: at least 8192 bytes (LONG __stack = 8192;)
• Include pragmas for library calls
• Use __saveds and __asm register keywords for dispatcher functions

DICE

DICE requires slightly different macros:

#define REG(x) __ ## x
#define ASM
#define SAVEDS __geta4

DICE also handles library opening differently; the examples use conditional compilation for DICE.

GCC

GCC uses inline headers rather than pragmas:

#include <inline/muimaster.h>

GCC does not need __asm or __saveds for dispatcher functions.

MAXON C

Similar to GCC in that ASM and SAVEDS are defined as empty:

#define ASM
#define SAVEDS

Build Workflow

A typical build for SAS/C:

sc LINK AppWindow.c demo.h

For GCC cross-compilation:

m68k-amigaos-gcc -o AppWindow AppWindow.c -lmuimaster

Ensure your NDK (Native Developer Kit) include paths are set correctly so that libraries/mui.h and the clib/inline headers are found.

---

Previous: Architecture Next: Core Concepts