Use AI to improve documentation of MorphOS SDK
  • Yokemate of Keyboards
    Yokemate of Keyboards
    Papiosaur
    Posts: 2174 from 2003/4/10
    From: France
    Hello,

    as said in the other thread about the use of the AI, it could be used to improve documentation of MorphOS SDK.

    This is an example what the AI can give as information about MUI_AboutMUI.doc:

    Quote:

    ABOUTMUI.doc

    Overview
    The Aboutmui.mui class is part of the MUI (Magic User Interface) framework used in MorphOS for creating graphical user interfaces. It provides an easy way to display an "About" window in MUI applications.

    Class Description
    Aboutmui.mui is used to create and manage an "About" window for MUI applications. Once created, this window takes care of itself, including handling its own closing and disposal when the application is removed.
    Attributes

    MUIA_Aboutmui_Application
    • Type: MUIApplication *
    • Access: [I..] (Init)
    • ID: 0x80422523
    • Introduced: V11

    Function
    Informs the Aboutmui object of the application it's associated with. If not specified, Aboutmui will create a normal window object and leave the responsibility of closing to the programmer.

    Usage
    To use Aboutmui.mui, typically you would:
    1.Add a "Project/About..." menu item to your application.
    2.When this menu item is selected, create and display the About window.

    Example
    Here's an example of how to implement an "About" window in your application:

    Code:
    #include <exec/types.h>          // For MorphOS exec types
    #include <libraries/mui.h> // For MUI specific definitions
    #include <proto/exec.h> // For MorphOS exec functions
    #include <proto/intuition.h> // For Intuition functions
    #include <proto/muimaster.h> // For MUI functions
    #include <stdio.h> // For printf function

    /* Function prototypes */
    static void cleanup(void); // Function to clean up resources
    BOOL init(void); // Function to initialize the application

    /* MUI application object */
    Object *app; // Global pointer to our application object
    struct Library *MUIMasterBase; // Pointer to the MUI master library

    /* Custom methods */
    #define ID_QUIT 1 // ID for quit action
    #define ID_ABOUT 2 // ID for about action
    #define ID_ICONIFY 3 // ID for iconify action

    int main(void)
    {
    // Initialize the application
    if (!init()) return 20; // If initialization fails, exit with error code 20

    ULONG signals = 0; // For storing signal bits
    BOOL running = TRUE; // Flag to control the main loop

    // Main event loop
    while (running)
    {
    // Handle input events, store signals in 'signals'
    ULONG ret = DoMethod(app, MUIM_Application_NewInput, &signals);

    // Handle return values from input method
    switch(ret)
    {
    case ID_QUIT:
    running = FALSE; // Exit the main loop
    break;

    case ID_ABOUT:
    // Show an about box
    MUI_RequestA(app, NULL, 0, "About", "OK", "Simple MUI ApplicationnCreated as an example", NULL);
    break;

    case ID_ICONIFY:
    // Iconify the application
    set(app, MUIA_Application_Iconified, TRUE);
    break;

    case MUIV_Application_ReturnID_Quit:
    // Ask for confirmation before quitting
    if (MUI_RequestA(app, NULL, 0, "Quit", "_Yes|_No", "Are you sure you want to quit?", NULL) == 1)
    running = FALSE;
    break;
    }

    // If we're still running and have signals to wait for
    if (running && signals)
    {
    // Wait for signals, including the break signal
    signals = Wait(signals | SIGBREAKF_CTRL_C);
    if (signals & SIGBREAKF_CTRL_C) break; // Break if Ctrl-C is pressed
    }
    }

    // Clean up resources
    cleanup();
    return 0;
    }

    BOOL init(void)
    {
    // Open the MUI master library
    MUIMasterBase = OpenLibrary("muimaster.library", 0);
    if (!MUIMasterBase)
    {
    printf("Can't open muimaster.libraryn");
    return FALSE;
    }

    // Declare objects for our GUI elements
    Object *window, *quit_button, *about_button, *iconify_button;

    // Create the application object and GUI
    app = ApplicationObject,
    // Set application attributes
    MUIA_Application_Title , "SimpleApp",
    MUIA_Application_Version , "$VER: SimpleApp 1.0 (01.01.2023)",
    MUIA_Application_Copyright , "©2023 by Your Name",
    MUIA_Application_Author , "Your Name",
    MUIA_Application_Description, "A simple MUI application example",
    MUIA_Application_Base , "SIMPLEAPP",

    // Create a window
    SubWindow, window = WindowObject,
    MUIA_Window_Title, "Simple MUI Application",
    MUIA_Window_ID , MAKE_ID('M','A','I','N'),
    WindowContents, VGroup,
    Child, HGroup,
    Child, quit_button = SimpleButton("Quit"),
    Child, about_button = SimpleButton("About"),
    Child, iconify_button = SimpleButton("Iconify"),
    End,
    End,
    End,
    End;

    // Check if application object was created successfully
    if (!app)
    {
    printf("Can't create applicationn");
    cleanup();
    return FALSE;
    }

    // Set up notifications

    // Notify when window close gadget is clicked
    DoMethod(window, MUIM_Notify, MUIA_Window_CloseRequest, TRUE,
    app, 2, MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);

    // Notify when Quit button is clicked
    DoMethod(quit_button, MUIM_Notify, MUIA_Pressed, FALSE,
    app, 2, MUIM_Application_ReturnID, ID_QUIT);

    // Notify when About button is clicked
    DoMethod(about_button, MUIM_Notify, MUIA_Pressed, FALSE,
    app, 2, MUIM_Application_ReturnID, ID_ABOUT);

    // Notify when Iconify button is clicked
    DoMethod(iconify_button, MUIM_Notify, MUIA_Pressed, FALSE,
    app, 2, MUIM_Application_ReturnID, ID_ICONIFY);

    // Open the window
    set(window, MUIA_Window_Open, TRUE);

    return TRUE;
    }

    void cleanup(void)
    {
    // Dispose of the application object if it exists
    if (app) MUI_DisposeObject(app);
    // Close the MUI master library if it was opened
    if (MUIMasterBase) CloseLibrary(MUIMasterBase);
    }


    Notes
    • Once created, you don't need to manage the window yourself. It will handle its own closing and disposal.
    • If the MUIA_Aboutmui_Application attribute is not set, you'll need to manage the window's lifecycle manually.
    • The AboutmuiObject macro is used to create an instance of the Aboutmui class.

    Best Practices
    • Create the About window only when it's needed (lazy initialization).
    • Use the MUIA_Aboutmui_Application attribute to let the window manage itself.
    • Provide keyboard shortcuts for accessibility (as shown in the example with 'A' and '?').
    Remember to include the necessary MUI headers and link against the required libraries when compiling your MorphOS application.


    There are errors at compilation, but i think if a MorphOS developper could verify informations and fix the code, it could be a precious documentation for developpers.

    I can propose this for each file of the SDK i think.
  • »08.09.24 - 15:45
    Profile Visit Website
  • Order of the Butterfly
    Order of the Butterfly
    igracki
    Posts: 411 from 2003/2/25
    From: Berlin
    The example doesn't uses the special Aboutmui class!
    It uses a simple Requester.
  • »09.09.24 - 10:17
    Profile Visit Website
  • Yokemate of Keyboards
    Yokemate of Keyboards
    Papiosaur
    Posts: 2174 from 2003/4/10
    From: France
    @igracki: you have right... i will propose a new code...

    Code:
    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    #include <proto/exec.h>
    #include <proto/intuition.h>
    #include <proto/muimaster.h>
    #include <proto/utility.h>
    #include <proto/graphics.h>
    #include <proto/dos.h>
    #include <libraries/mui.h>
    #include <clib/alib_protos.h>

    #define MAKE_ID(a,b,c,d) ((ULONG) (a)<<24 | (ULONG) (b)<<16 | (ULONG) (c)<<8 | (ULONG) (d))

    struct Library *MUIMasterBase;
    struct Library *UtilityBase;
    struct IntuitionBase *IntuitionBase;
    struct GfxBase *GfxBase;

    BOOL Open_Libs(void);
    void Close_Libs(void);
    void ShowAboutMUI(void);

    Object *app, *window, *aboutwin;

    int main(void)
    {
    Object *menu;
    Object *menuItemQuit, *menuItemAbout;

    BOOL running = TRUE;
    ULONG signals;

    if (!Open_Libs()) {
    printf("Failed to open librariesn");
    return 20;
    }

    app = ApplicationObject,
    MUIA_Application_Title, "Simple MUI App",
    MUIA_Application_Version, "$VER: SimpleMUIApp 1.0 (09.09.24)",
    MUIA_Application_Copyright, "©2024 Your Name",
    MUIA_Application_Author, "Your Name",
    MUIA_Application_Description, "Simple MUI application with About",
    MUIA_Application_Base, "SIMPLEMUIAPP",

    SubWindow, window = WindowObject,
    MUIA_Window_Title, "Simple MUI Window",
    MUIA_Window_ID, MAKE_ID('S','I','M','P'),
    MUIA_Window_Width, 400,
    MUIA_Window_Height, 300,
    WindowContents, VGroup,
    // La fenêtre est vide, sans contenu
    End,
    End,

    MUIA_Application_Menustrip, menu = MenustripObject,
    Child, MenuObject,
    MUIA_Menu_Title, "File",
    Child, menuItemAbout = MenuitemObject,
    MUIA_Menuitem_Title, "About MUI...",
    End,
    Child, menuItemQuit = MenuitemObject,
    MUIA_Menuitem_Title, "Quit",
    End,
    End,
    End,
    End;

    if (!app) {
    printf("Failed to create applicationn");
    Close_Libs();
    return 20;
    }

    DoMethod(window, MUIM_Notify, MUIA_Window_CloseRequest, TRUE,
    app, 2, MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);
    DoMethod(menuItemQuit, MUIM_Notify, MUIA_Menuitem_Trigger, MUIV_EveryTime,
    app, 2, MUIM_Application_ReturnID, MUIV_Application_ReturnID_Quit);

    DoMethod(menuItemAbout, MUIM_Notify, MUIA_Menuitem_Trigger, MUIV_EveryTime,
    app, 2, MUIM_Application_ReturnID, 1);

    set(window, MUIA_Window_Open, TRUE);

    while (running) {
    ULONG id = DoMethod(app, MUIM_Application_Input, &signals);

    switch(id) {
    case MUIV_Application_ReturnID_Quit:
    if (MUI_RequestA(app, window, 0, "Quit?", "_Yes|_No", "33cAre you sure?", NULL) == 1)
    running = FALSE;
    break;
    case 1: // About
    ShowAboutMUI();
    break;
    }

    if (running && signals) Wait(signals);
    }

    set(window, MUIA_Window_Open, FALSE);

    MUI_DisposeObject(app);
    Close_Libs();
    return 0;
    }

    void ShowAboutMUI(void)
    {
    if (!aboutwin)
    {
    aboutwin = AboutmuiObject,
    MUIA_Window_RefWindow, window,
    MUIA_Aboutmui_Application, app,
    End;
    }

    if (aboutwin)
    set(aboutwin, MUIA_Window_Open, TRUE);
    else
    DisplayBeep(NULL);
    }

    BOOL Open_Libs(void)
    {
    if (!(IntuitionBase = (struct IntuitionBase *)OpenLibrary("intuition.library", 39))) return FALSE;
    if (!(GfxBase = (struct GfxBase *)OpenLibrary("graphics.library", 39))) { CloseLibrary((struct Library *)IntuitionBase); return FALSE; }
    if (!(UtilityBase = OpenLibrary("utility.library", 39))) { CloseLibrary((struct Library *)GfxBase); CloseLibrary((struct Library *)IntuitionBase); return FALSE; }
    if (!(MUIMasterBase = OpenLibrary(MUIMASTER_NAME, 19))) { CloseLibrary(UtilityBase); CloseLibrary((struct Library *)GfxBase); CloseLibrary((struct Library *)IntuitionBase); return FALSE; }
    return TRUE;
    }

    void Close_Libs(void)
    {
    if (MUIMasterBase) CloseLibrary(MUIMasterBase);
    if (UtilityBase) CloseLibrary(UtilityBase);
    if (GfxBase) CloseLibrary((struct Library *)GfxBase);
    if (IntuitionBase) CloseLibrary((struct Library *)IntuitionBase);
    }


    This one is better ;-)
  • »09.09.24 - 11:17
    Profile Visit Website