mirror of
https://github.com/alfishe/amiga-bootcamp.git
synced 2026-06-13 00:26:28 +00:00
doc: MUI framework documentation — whitepaper overview, SDK-derived architecture, layout mockups
- README.md: comprehensive whitepaper-style overview with historical context, paradigm shift analysis, BOOPSI comparison, version history (Stefan Stuntz as sole author 1.0-3.8), licensing model breakdown, parallel evolution timeline (NeXTSTEP/Qt/MUI convergence), community-sourced developer values - 02-architecture.md: complete rewrite from MUI 3.8 SDK sources — object lifecycle state machine, three-level resource binding, method dispatch chain, notification system with sequence diagrams, layout engine internals (3-pass constraint system), input handling, dynamic object linking, rendering model, tag ID namespace - 05-layout-system.md: Mermaid visual mockups for VGroup, HGroup, nested groups, column grids, scrollgroups, file requester real-world example, layout algorithm and resize sequence diagrams - frameworks/README.md: framework index with comparison table - All content in American English
This commit is contained in:
Ilia Sharin
parent
c79d5e8459
commit
94a3ad1614
15 changed files with 4911 additions and 0 deletions
273
09_intuition/frameworks/mui/03-getting-started.md
Normal file
273
09_intuition/frameworks/mui/03-getting-started.md
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
[← Home](../../../README.md) · [Intuition](../../README.md) · [Frameworks](../README.md)
|
||||
|
||||
# Getting Started
|
||||
|
||||
## Required Includes
|
||||
|
||||
Every MUI application needs at minimum:
|
||||
|
||||
```c
|
||||
#include <libraries/mui.h>
|
||||
```
|
||||
|
||||
Depending on your compiler, you also need one of the following for function prototypes:
|
||||
|
||||
```c
|
||||
/* 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:
|
||||
|
||||
```c
|
||||
#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`:
|
||||
|
||||
```c
|
||||
#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:
|
||||
|
||||
```c
|
||||
CloseLibrary(MUIMasterBase);
|
||||
```
|
||||
|
||||
## Minimal "Hello MUI" Application
|
||||
|
||||
Here is the smallest possible MUI application that opens a window with some text:
|
||||
|
||||
```c
|
||||
#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:
|
||||
|
||||
```c
|
||||
/* 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:
|
||||
|
||||
```c
|
||||
#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:
|
||||
|
||||
```c
|
||||
#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:
|
||||
|
||||
```c
|
||||
#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](02-architecture.md)
|
||||
Next: [Core Concepts](04-core-concepts.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue