amiga-bootcamp/09_intuition/frameworks/mui/04-core-concepts.md

← Home · Intuition · Frameworks

Core Concepts

Naming Conventions

MUI uses a strict prefix system defined in libraries/mui.h. Every identifier type has its own prefix:

Prefix	Meaning	Example
MUIC_	Class name	MUIC_Area, MUIC_Window
MUIM_	Method	MUIM_Draw, MUIM_AskMinMax
MUIP_	Method parameter structure	MUIP_Draw, MUIP_AskMinMax
MUIV_	Special method/attribute value	MUIV_Application_ReturnID_Quit
MUIA_	Attribute	MUIA_Window_Title
MUIE_	Error return code	MUIE_OutOfMemory
MUII_	Standard MUI image	MUII_BACKGROUND, MUII_SHADOW
MUIX_	Control code for text strings	MUIX_C (center), MUIX_B (bold)
MUIO_	Object type for MUI_MakeObject()	MUIO_Button, MUIO_HBar

Learning these prefixes makes reading MUI code significantly easier.

Attributes

Attributes are the properties of MUI objects. Each attribute definition in libraries/mui.h is followed by a comment with the letters I, S, and/or G:

• I - Can be specified at object creation time
• S - Can be changed later with SetAttrs() or the set() macro
• G - Can be read with GetAttr() or the get() macro

Example:

#define MUIA_Window_Title 0x8042c21d /* ISG */

This means MUIA_Window_Title can be set at creation, changed later, and queried at any time.

Setting Attributes

At creation time, attributes are passed as tag-value pairs:

app = ApplicationObject,
    MUIA_Application_Title, "MyApp",
    MUIA_Application_Base , "MYAPP",
    TAG_DONE;

After creation, use set():

set(window, MUIA_Window_Open, TRUE);

Or use SetAttrs() directly:

SetAttrs(window, MUIA_Window_Open, TRUE, TAG_DONE);

Getting Attributes

ULONG is_open;
get(window, MUIA_Window_Open, &is_open);

Object Creation Macros

MUI provides convenience macros that look like function calls but expand into NewObject() calls with the appropriate class and tags. These macros make code readable and maintainable.

Common Creation Macros

/* Application and Window */
ApplicationObject, ... , TAG_DONE;
WindowObject, ... , TAG_DONE;

/* Groups */
VGroup, ... , End;
HGroup, ... , End;
GroupObject, ... , End;

/* Widgets */
TextObject, ... , End;
StringObject, ... , End;
ListviewObject, ... , End;
ListObject, ... , End;
SliderObject, ... , End;
CycleObject, ... , End;
RadioObject, ... , End;
GaugeObject, ... , End;
ScaleObject, ... , End;
ImageObject, ... , End;
BitmapObject, ... , End;
ColorfieldObject, ... , End;
PaletteObject, ... , End;

/* Popups */
PopstringObject, ... , End;
PopaslObject, ... , End;
PopobjectObject, ... , End;
PoplistObject, ... , End;

/* Special helpers */
SimpleButton("Label")
HSpace(x)
VSpace(x)

The pattern is consistent: the macro name corresponds to the class, attributes follow as tag-value pairs, and the object is terminated with End or TAG_DONE.

Tag-Based Construction

MUI objects are created using the Amiga tag system. Tags are 32-bit values where the upper bits identify the attribute and the lower bits hold the value (or a pointer).

app = ApplicationObject,
    MUIA_Application_Title      , "Demo",
    MUIA_Application_Version    , "$VER: Demo 1.0",
    MUIA_Application_Copyright  , "1997 Author",
    MUIA_Application_Author     , "Author",
    MUIA_Application_Description, "A demo program",
    MUIA_Application_Base       , "DEMO",
    SubWindow, window = WindowObject,
        MUIA_Window_Title, "Demo Window",
        MUIA_Window_ID   , MAKE_ID('D','E','M','O'),
        WindowContents, VGroup,
            Child, TextObject,
                TextFrame,
                MUIA_Background, MUII_TextBack,
                MUIA_Text_Contents, "Hello",
                End,
            End,
        End,
    End;

Notice how nesting works: ApplicationObject contains SubWindow, which contains WindowObject, which contains WindowContents, which contains a VGroup, which contains Child widgets.

Methods

Methods are operations you perform on objects. The universal way to invoke a method is DoMethod():

DoMethod(obj, MUIM_MethodName, arg1, arg2, ...);

Common Methods

Method	Purpose
MUIM_Application_NewInput	Process input events (preferred loop)
MUIM_Application_Input	Process input events (legacy loop)
MUIM_Application_ReturnID	Trigger a return ID
MUIM_Notify	Set up attribute notifications
MUIM_CallHook	Invoke a callback hook
MUIM_Set	Set an attribute (method form)
MUIM_Get	Get an attribute (method form)
MUIM_Draw	Render an object
MUIM_AskMinMax	Query minimum/maximum sizes

Object Lifecycle

Creation

Objects are created with the macro constructors. The constructor returns a pointer or NULL on failure.

APTR obj = TextObject,
    MUIA_Text_Contents, "Hello",
    End;

if (!obj)
    /* handle error */;

Usage

Objects are manipulated through attributes and methods. They exist within a parent container (usually a Group) which manages their layout and visibility.

Disposal

When an object is no longer needed, dispose it:

MUI_DisposeObject(obj);

For the top-level Application object, disposing it automatically disposes all child Windows and their contents. This is the normal shutdown pattern:

MUI_DisposeObject(app);  /* disposes entire tree */

For custom classes, you must also delete the class itself:

MUI_DeleteCustomClass(mcc);

The Child Keyword

When adding widgets to a Group, the Child tag is used to introduce each child object:

VGroup,
    Child, widget1,
    Child, widget2,
    Child, HGroup,
        Child, subwidget1,
        Child, subwidget2,
        End,
    End,

Child is not a macro for a class; it is a tag that tells the Group class to add the following object to its internal list of children.

Special Attribute Values

MUI defines several special values used across multiple attributes:

Value	Meaning
MUIV_EveryTime	Trigger notification on any attribute change
MUIV_TriggerValue	Pass the triggering value as an argument
MUIV_Notification_Value	Use the value from the notification setup

These are used primarily with MUIM_Notify to create flexible event bindings.

---

Previous: Getting Started Next: Layout System