home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / gui / mui / developer / autodocs / mui_application.doc next >
Encoding:
Text File  |  1994-08-08  |  34.4 KB  |  1,152 lines

  1. TABLE OF CONTENTS
  2.  
  3. Application.mui/Application.mui
  4. Application.mui/MUIM_Application_GetMenuCheck
  5. Application.mui/MUIM_Application_GetMenuState
  6. Application.mui/MUIM_Application_Input
  7. Application.mui/MUIM_Application_InputBuffered
  8. Application.mui/MUIM_Application_Load
  9. Application.mui/MUIM_Application_PushMethod
  10. Application.mui/MUIM_Application_ReturnID
  11. Application.mui/MUIM_Application_Save
  12. Application.mui/MUIM_Application_SetMenuCheck
  13. Application.mui/MUIM_Application_SetMenuState
  14. Application.mui/MUIM_Application_ShowHelp
  15. Application.mui/MUIA_Application_Active
  16. Application.mui/MUIA_Application_Author
  17. Application.mui/MUIA_Application_Base
  18. Application.mui/MUIA_Application_Broker
  19. Application.mui/MUIA_Application_BrokerHook
  20. Application.mui/MUIA_Application_BrokerPort
  21. Application.mui/MUIA_Application_BrokerPri
  22. Application.mui/MUIA_Application_Commands
  23. Application.mui/MUIA_Application_Copyright
  24. Application.mui/MUIA_Application_Description
  25. Application.mui/MUIA_Application_DiskObject
  26. Application.mui/MUIA_Application_DoubleStart
  27. Application.mui/MUIA_Application_DropObject
  28. Application.mui/MUIA_Application_ForceQuit
  29. Application.mui/MUIA_Application_HelpFile
  30. Application.mui/MUIA_Application_Iconified
  31. Application.mui/MUIA_Application_Menu
  32. Application.mui/MUIA_Application_MenuAction
  33. Application.mui/MUIA_Application_MenuHelp
  34. Application.mui/MUIA_Application_Menustrip
  35. Application.mui/MUIA_Application_RexxHook
  36. Application.mui/MUIA_Application_RexxMsg
  37. Application.mui/MUIA_Application_RexxString
  38. Application.mui/MUIA_Application_SingleTask
  39. Application.mui/MUIA_Application_Sleep
  40. Application.mui/MUIA_Application_Title
  41. Application.mui/MUIA_Application_Version
  42. Application.mui/MUIA_Application_Window
  43. Application.mui/Application.mui
  44.  
  45. Application class is the master class for all
  46. MUI applications. It serves as a kind of anchor
  47. for all input, either coming from the user or
  48. somewhere from the system, e.g. commodities
  49. or ARexx messages.
  50.  
  51. An application can have any number of sub windows,
  52. these windows are the children of the application.
  53. Application.mui/MUIM_Application_GetMenuCheck
  54.  
  55.     NAME
  56.     MUIM_Application_GetMenuCheck (V4) (OBSOLETE)
  57.  
  58.     SYNOPSIS
  59.     DoMethod(obj,MUIM_Application_GetMenuCheck,ULONG MenuID);
  60.  
  61.     FUNCTION
  62.     Ask whether a checkmark menu item has its checkmark
  63.     set or cleared.
  64.     The application will ask its sub windows for a
  65.     menu item with the given id and return the state of
  66.     the first item it finds.
  67.  
  68.     INPUTS
  69.     MenuID - the value you wrote into the
  70.                  UserData field of struct NewMenu.
  71.  
  72.     SEE ALSO
  73.     MUIM_Application_SetMenuCheck, MUIA_Application_Menu
  74. Application.mui/MUIM_Application_GetMenuState
  75.  
  76.     NAME
  77.     MUIM_Application_GetMenuState (V4) (OBSOLETE)
  78.  
  79.     SYNOPSIS
  80.     DoMethod(obj,MUIM_Application_GetMenuState,ULONG MenuID);
  81.  
  82.     FUNCTION
  83.     Ask whether a menu item is enabled or disabled.
  84.     The application will ask its sub windows for a
  85.     menu item with the given id and return the state of
  86.     the first item it finds.
  87.  
  88.     INPUTS
  89.     MenuID - the value you wrote into the
  90.                  UserData field of struct NewMenu.
  91.  
  92.     SEE ALSO
  93.     MUIM_Application_SetMenuState, MUIA_Application_Menu
  94. Application.mui/MUIM_Application_Input
  95.  
  96.     NAME
  97.     MUIM_Application_Input (V4)
  98.  
  99.     SYNOPSIS
  100.     DoMethod(obj,MUIM_Application_Input,LONGBITS *signal);
  101.  
  102.     FUNCTION
  103.     The MUI system itself does not wait for any user input.
  104.     It just tells your application which signal bits it
  105.     has allocated, then it's up to you to call MUIs input
  106.     handle function when one of these signals gets set.
  107.  
  108.     In a simple MUI application you would just Wait()
  109.     for these signals and call MUI when one is received.
  110.     However, you can perfectly allocate some signal bits
  111.     yourself and include them in your Wait() command.
  112.     You needn't even Wait(), your application could
  113.     maybe calculate some fractal graphics or copy
  114.     disks, the only important thing is that you call
  115.     MUI's input method when one of the MUI allocated
  116.     signals arrives.
  117.  
  118.     The usual way of communication with your user
  119.     interface is via return ids. Every action happening
  120.     to the GUI can create return ids, e.g. pressing a
  121.     button or trying to close a window. MUI buffers these
  122.     ids and uses them as result codes for the input method.
  123.     Thats where you can get it from and take the appropriate
  124.     actions.
  125.  
  126.     Now lets have a look on a usual input loop of a
  127.     MUI application. Imagine you have an Play and a
  128.     Cancel button and have previously told them
  129.     to return ID_PLAY and ID_CANCEL when pressed.
  130.     (see MUIM_Notify and MUIM_Application_ReturnID
  131.     on information about these topics). Your input
  132.     loop would look like this:
  133.  
  134.  
  135.     while (running)
  136.     {
  137.        ULONG signals;
  138.  
  139.        switch (DoMethod(app,MUIM_Application_Input,&signals))
  140.        {
  141.           case ID_PLAY:
  142.              PlaySound();
  143.              break;
  144.  
  145.           case ID_CANCEL:
  146.           case MUIV_Application_ReturnID_Quit:
  147.              running = FALSE;
  148.              break;
  149.        }
  150.  
  151.        if (running && signals) Wait(signals);
  152.     }
  153.  
  154.  
  155.     So what is happening here?
  156.  
  157.     First, you have to call the MUIM_Application_Input method.
  158.     You supply the address of a ULONG as parameter, thats
  159.     where MUI fills in the signals it needs. Note that you can
  160.     call the input method at any time, regardless of signal
  161.     setting. MUI will simply return when there is nothing
  162.     to do.
  163.  
  164.     In case the user pressed the Play or the Cancel button,
  165.     MUIM_Application_Input will return ID_PLAY or ID_CANCEL.
  166.     Otherwise you will receive a 0, that's why you cannot
  167.     use 0 as one of your id values.
  168.  
  169.     There is one predefined id called
  170.     MUIV_Application_ReturnID_Quit. This will be sent to you
  171.     when someone tried to quit your application from outside,
  172.     e.g. via commodities exchange or the ARexx "quit" command.
  173.     It is required that your application handles this id,
  174.     just treat as if the user clicked on a "Quit" button or
  175.     selected a "Quit" menu item.
  176.  
  177.     After handling the return value, you have to examine
  178.     if MUI wants you to wait for any signals. If this
  179.     is the case (signals != 0), just wait for it. If
  180.     MUI puts a 0 into signals it wants to tell you to
  181.     immediately call the input method again, maybe some
  182.     other return ids have received and need to be handled.
  183.     You *must* check this because Wait()ing on a zero
  184.     signal mask is not a good idea!
  185.  
  186.     Note: It is very important that you call the input method
  187.     whenever a signal arrives. MUI needs this to correctly
  188.     refresh its windows, handle resizing and iconification
  189.     operations and commodities and ARexx messages. If you
  190.     don't, you will annoy your user!
  191.  
  192.     If your program needs to be in a state where you are
  193.     for some reasons unable to call the input method for
  194.     a considerable amount of time (maybe half a second or
  195.     more), you should put your application to sleep. See
  196.     MUIA_Application_Sleep on how to do this.
  197.  
  198.     SEE ALSO
  199.     MUIA_Application_Sleep, MUIM_Application_InputBuffered
  200. Application.mui/MUIM_Application_InputBuffered
  201.  
  202.     NAME
  203.     MUIM_Application_InputBuffered (V4)
  204.  
  205.     SYNOPSIS
  206.     DoMethod(obj,MUIM_Application_InputBuffered,);
  207.  
  208.     FUNCTION
  209.     Imagine your application does some time consuming
  210.     operation, e.g. copying a disk, and you are for
  211.     some reasons unable to react on return ids during
  212.     this period. One solution would be to simply
  213.     put your application to sleep, it will get a
  214.     busy pointer and the user knows whats going on.
  215.  
  216.     However, this will make it impossible for the user
  217.     to resize your applications windows or iconify it,
  218.     he will have to wait until you are done with your
  219.     operation.
  220.  
  221.     MUIM_Application_InputBuffered offers a solution
  222.     for this problem. Using this method, you needn't
  223.     set to sleep your application. Just call it on a
  224.     regular basis and MUI will be able to handle
  225.     all actions concerning the GUI. You do not need
  226.     to pay attention on return values, they remain
  227.     on an internal stack until your next call to
  228.     the non buffered input method.
  229.  
  230.     EXAMPLE
  231.     for (track=0; track<80; track++)
  232.     {
  233.        read_track();
  234.        DoMethod(app,MUIM_Application_InputBuffered);
  235.        write_track();
  236.        DoMethod(app,MUIM_Application_InputBuffered);
  237.     }
  238.  
  239.     SEE ALSO
  240.     MUIM_Application_Input, MUIA_Application_Sleep
  241. Application.mui/MUIM_Application_Load
  242.  
  243.     NAME
  244.     MUIM_Application_Load (V4)
  245.  
  246.     SYNOPSIS
  247.     DoMethod(obj,MUIM_Application_Load,STRPTR name);
  248.  
  249.     FUNCTION
  250.     MUIM_Application_Save, MUIM_Application_Load and
  251.     MUIA_ExportID offer an easy way of saving and loading
  252.     a programs configuration.
  253.  
  254.     Each gadget with a non NULL MUIA_ExportID will get
  255.     its contents saved during MUIM_Application_Save and
  256.     restored during MUIM_Application_Load. This makes
  257.     it very easy to design a configuration window
  258.     with "Save", "Use" and "Cancel" buttons to allow
  259.     the user storing the settings. When the application
  260.     starts, you would just have to call MUIM_Application_Load
  261.     and the stored settings will be read and installed.
  262.  
  263.     Not all classes are able to import and export their
  264.     contents. Currently, you may define MUIA_ExportIDs for
  265.  
  266.     String class   - MUIA_String_Contents is ex/imported.
  267.     Radio class    - MUIA_Radio_Active is ex/imported.
  268.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  269.     List class     - MUIA_List_Active is /ex/imported.
  270.     Text class     - MUIA_Text_Contents is ex/imported.
  271.     Slider class   - MUIA_Slider_Level is ex/imported.
  272.     Area class     - MUIA_Selected is ex/imported
  273.                      (e.g. for Checkmark gadgets)
  274.    Menuitem class - MUIA_Checked is ex/imported (V9).
  275.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  276.  
  277.     INPUTS
  278.     name - Name of the file you wish to load the settings from.
  279.            Usually you won't need to think of a real name but
  280.            instead use one of the magic cookies
  281.            MUIV_Application_Load_ENV or
  282.            MUIV_Application_Load_ENVARC.
  283.  
  284.     EXAMPLE
  285.     see the sample program "Settings.c"
  286.  
  287.     SEE ALSO
  288.     MUIM_Application_Save, MUIA_ExportID
  289. Application.mui/MUIM_Application_PushMethod
  290.  
  291.     NAME
  292.     MUIM_Application_PushMethod (V4)
  293.  
  294.     SYNOPSIS
  295.     DoMethod(obj,MUIM_Application_PushMethod,Object *dest, LONG count, /* ... */);
  296.  
  297.     FUNCTION
  298.     Usually, you may not talk to the MUI system from two
  299.     tasks at the same time. MUIM_Application_PushMethod
  300.     provides some kind of solution for this problem.
  301.  
  302.     This (and only this) method may be called from a
  303.     second task. It takes another method as parameter
  304.     and puts in onto a private stack of the application
  305.     object. The next time MUIM_Application_Input
  306.     is called, the pushed method will be executed
  307.     in the context of the current task.
  308.  
  309.     INPUTS
  310.     dest  - object on which to perform the pushed method.
  311.         count - number of following arguments.
  312.     ...   - the destination method.
  313.  
  314.     EXAMPLE
  315.     /* set a status line from a sub task */
  316.     DoMethod(app,MUIM_Application_PushMethod,
  317.        txstatus,3,MUIM_Set,MUIA_Text_Contents,"reading...");
  318.  
  319.     SEE ALSO
  320.     MUIM_Application_Input
  321. Application.mui/MUIM_Application_ReturnID
  322.  
  323.     NAME
  324.     MUIM_Application_ReturnID (V4)
  325.  
  326.     SYNOPSIS
  327.     DoMethod(obj,MUIM_Application_ReturnID,ULONG retid);
  328.  
  329.     FUNCTION
  330.     Tell MUI to return the given id with the next call to 
  331.     MUIM_Application_Input.
  332.  
  333.     Together with the MUI's notification mechanism, this
  334.     method connects your user interface and your program.
  335.     If you e.g. want to be informed if the user presses
  336.     a "Play" button, you would have define an id for
  337.     this action and set up a notification event with
  338.     MUIM_Notify.
  339.  
  340.     You can use any long word as return id, except
  341.     from -255 up to 0. These values are reserved for
  342.     MUI's internal use and for special return values
  343.     like MUIV_Application_ReturnID_Quit.
  344.  
  345.     Note that MUI will put all incoming return ids
  346.     onto a private fifo stack and feed this stack
  347.     to its input methods result code later.
  348.  
  349.     EXAMPLE
  350.  
  351.     /* inform me if a button is pressed (actually released, */
  352.     /* since this is the way amiga buttons are handled)     */
  353.  
  354.     #define ID_PLAYBUTTON 42
  355.  
  356.     ...
  357.  
  358.     DoMethod(buttonobj, MUIM_Notify,
  359.        MUIA_Pressed, FALSE,
  360.        appobj, 2, MUIM_Application_ReturndID, ID_PLAYBUTTON);
  361.  
  362.     ...
  363.  
  364.     while (running)
  365.     {
  366.        switch (DoMethod(appobj,MUIM_Application_Input,&sigs))
  367.        {
  368.           case ID_PLAYBUTTON:
  369.              printf("Ok, lets play a game...");
  370.              break;
  371.        }
  372.     }
  373.  
  374.     SEE ALSO
  375.     MUIM_Application_Input, MUIM_Notify
  376. Application.mui/MUIM_Application_Save
  377.  
  378.     NAME
  379.     MUIM_Application_Save (V4)
  380.  
  381.     SYNOPSIS
  382.     DoMethod(obj,MUIM_Application_Save,STRPTR name);
  383.  
  384.     FUNCTION
  385.     MUIM_Application_Save, MUIM_Application_Load and
  386.     MUIA_ExportID offer an easy way of saving and loading
  387.     a programs configuration.
  388.  
  389.     Each gadget with a non NULL MUIA_ExportID will get
  390.     its contents saved during MUIM_Application_Save and
  391.     restored during MUIM_Application_Load. This makes
  392.     it very easy to design a configuration window
  393.     with "Save", "Use" and "Cancel" buttons to allow
  394.     the user storing the settings. When the application
  395.     starts, you would just have to call MUIM_Application_Load
  396.     and the stored settings will be read and installed.
  397.  
  398.     Not all classes are able to import and export their
  399.     contents. Currently, you may define MUIA_ExportIDs for
  400.  
  401.     String class   - MUIA_String_Contents is ex/imported.
  402.     Radio class    - MUIA_Radio_Active is ex/imported.
  403.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  404.     List class     - MUIA_List_Active is /ex/imported.
  405.     Text class     - MUIA_Text_Contents is ex/imported.
  406.     Slider class   - MUIA_Slider_Level is ex/imported.
  407.     Area class     - MUIA_Selected is ex/imported
  408.                      (e.g. for Checkmark gadgets)
  409.    Menuitem class - MUIA_Checked is ex/imported (V9).
  410.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  411.  
  412.     INPUTS
  413.     name - Name of the file you wish to save the settings to.
  414.            Usually you won't need to think of a real name but
  415.            instead use one of the magic cookies
  416.            MUIV_Application_Save_ENV or
  417.            MUIV_Application_Save_ENVARC.
  418.            This will save your application's settings somewhere
  419.            in env:mui/ or envarc:mui/, you needn't worry about
  420.            it.
  421.  
  422.     EXAMPLE
  423.     see the sample program "Settings.c"
  424.  
  425.     SEE ALSO
  426.     MUIM_Application_Load, MUIA_ExportID
  427. Application.mui/MUIM_Application_SetMenuCheck
  428.  
  429.     NAME
  430.     MUIM_Application_SetMenuCheck (V4) (OBSOLETE)
  431.  
  432.     SYNOPSIS
  433.     DoMethod(obj,MUIM_Application_SetMenuCheck,ULONG MenuID, LONG stat);
  434.  
  435.     FUNCTION
  436.     Set or clear the checkmark of a menu item.
  437.     The application will ask its sub windows for menu items
  438.     with the given id and set/clear all found
  439.     entries.
  440.  
  441.     INPUTS
  442.     MenuID - the value you wrote into the
  443.                  UserData field of struct NewMenu.
  444.  
  445.     set    - TRUE to set checkmark, FALSE to clear
  446.  
  447.     SEE ALSO
  448.     MUIM_Application_GetMenuCheck, MUIA_Application_Menu,
  449. Application.mui/MUIM_Application_SetMenuState
  450.  
  451.     NAME
  452.     MUIM_Application_SetMenuState (V4) (OBSOLETE)
  453.  
  454.     SYNOPSIS
  455.     DoMethod(obj,MUIM_Application_SetMenuState,ULONG MenuID, LONG stat);
  456.  
  457.     FUNCTION
  458.     Enable or disable a menu item.
  459.     The application will ask its sub windows for menu items
  460.     with the given id and enable/disable all found
  461.     entries.
  462.  
  463.     INPUTS
  464.     MenuID - the value you wrote into the
  465.                  UserData field of struct NewMenu.
  466.  
  467.     set    - TRUE to enable item, FALSE to disable.
  468.  
  469.     SEE ALSO
  470.     MUIM_Application_GetMenuState, MUIA_Application_Menu,
  471. Application.mui/MUIM_Application_ShowHelp
  472.  
  473.     NAME
  474.     MUIM_Application_ShowHelp (V4)
  475.  
  476.     SYNOPSIS
  477.     DoMethod(obj,MUIM_Application_ShowHelp,Object *window, char *name, char *node, LONG line);
  478.  
  479.     FUNCTION
  480.     Show an AmigaGuide help file. The application will be
  481.     put to sleep until the file is displayed.
  482.  
  483.     Usually, you don't need to call this method directly.
  484.     MUI comes with a sophisticated online help system,
  485.     you just need to supply your gadgets with help nodes
  486.     and everything will be handled automatically.
  487.  
  488.     INPUTS
  489.     window - (Object *) - Help will appear on this windows
  490.                           screen. May be NULL.
  491.     name   - (char *)   - name of the help file
  492.     node   - (char *)   - name of a node in this help file
  493.     line   - (char *)   - line number
  494.  
  495.     SEE ALSO
  496.     MUIA_HelpFile, MUIA_HelpNode, MUIA_HelpLine
  497. Application.mui/MUIA_Application_Active
  498.  
  499.     NAME
  500.     MUIA_Application_Active -- (V4) [ISG], BOOL
  501.  
  502.     FUNCTION
  503.     This attribute reflects the state that the user adjusted
  504.     with commodities Exchange. MUI itself doesn't pay any
  505.     attention to it, this is up to you.
  506.  
  507.     SEE ALSO
  508.     MUIA_Application_Broker
  509. Application.mui/MUIA_Application_Author
  510.  
  511.     NAME
  512.     MUIA_Application_Author -- (V4) [I.G], STRPTR
  513.  
  514.     FUNCTION
  515.     Name of the applications author.
  516.  
  517.     EXAMPLE
  518.     see MUIA_Application_Title
  519.  
  520.     SEE ALSO
  521.     MUIA_Application_Title, MUIA_Application_Copyright,
  522.     MUIA_Application_Version, MUIA_Application_Description,
  523.     MUIA_Application_Base
  524. Application.mui/MUIA_Application_Base
  525.  
  526.     NAME
  527.     MUIA_Application_Base -- (V4) [I.G], STRPTR
  528.  
  529.     FUNCTION
  530.     The basename for an application. This name is used
  531.     for the builtin ARexx port and for some internal
  532.     file management.
  533.  
  534.     A basename must neither contain spaces nor any
  535.     special characters such as ":/()#?*...".
  536.  
  537.     When your program is a single task application
  538.     (i.e. MUIA_Application_SingleTask is TRUE), the
  539.     base name will be used without further modification.
  540.  
  541.     Otherwise, it gets a ".1", ".2", etc. appended,
  542.     depending on how many applications are already
  543.     running. If you need to know the name of your
  544.     ARexx port, you can query the base name attribute
  545.     after the application is created.
  546.  
  547.     EXAMPLE
  548.     see MUIA_Application_Title
  549.  
  550.     SEE ALSO
  551.     MUIA_Application_Title, MUIA_Application_Version,
  552.     MUIA_Application_Author, MUIA_Application_Copyright,
  553.     MUIA_Application_Description
  554. Application.mui/MUIA_Application_Broker
  555.  
  556.     NAME
  557.     MUIA_Application_Broker -- (V4) [..G], Broker *
  558.  
  559.     FUNCTION
  560.     If you need to attach some additional commodities objects
  561.     to your application (e.g. because you need lots of hotkeys),
  562.     you can obtain a pointer to the applications Broker structure
  563.     and add some commodities objects.
  564.  
  565.     MUI will free the complete broker when the application is
  566.     disposed, no need for you to free your objects yourself.
  567.  
  568.     To receive input from your objects, you will also need to
  569.     install a MUIA_Application_BrokerHook.
  570.  
  571.     NOTES
  572.     Unless you have set MUIA_Application_RequiresCX, you must be
  573.     prepared to receive a NULL pointer. In this case, the
  574.     commodities interface is not available, maybe because the
  575.     user installed a light version of MUI.
  576.  
  577.     SEE ALSO
  578.     MUIA_Application_BrokerHook
  579. Application.mui/MUIA_Application_BrokerHook
  580.  
  581.     NAME
  582.     MUIA_Application_BrokerHook -- (V4) [ISG], struct Hook *
  583.  
  584.     FUNCTION
  585.     You specify a pointer to hook structure. The function
  586.     will be called whenever a commodities message arrives
  587.     (between MUI's GetMsg() and ReplyMsg()).
  588.  
  589.     You receive a pointer to the application object
  590.     as object in a2 and a pointer to commodities
  591.     CxMsg message in a1.
  592.  
  593.     NOTES
  594.     The commodities interface isn't available in the
  595.     memory saving "light" version of MUI. Your hook
  596.     will never be called in this case.
  597.  
  598.     SEE ALSO
  599.     MUIA_Application_Broker
  600. Application.mui/MUIA_Application_BrokerPort
  601.  
  602.     NAME
  603.     MUIA_Application_BrokerPort -- (V6) [..G], struct MsgPort *
  604.  
  605.     FUNCTION
  606.     Get a pointer to the applications commodities message port.
  607.     If you want to add own Hotkeys to your application, you
  608.     need a message port. Instead of creating your own, you
  609.     should better use this one.
  610.  
  611.     NOTES
  612.     Unless you have set MUIA_Application_RequiresCX, you must be
  613.     prepared to receive a NULL pointer. In this case, the
  614.     commodities interface is not available, maybe because the
  615.     user installed a light version of MUI.
  616.  
  617.     SEE ALSO
  618.     MUIA_Application_BrokerHook
  619. Application.mui/MUIA_Application_BrokerPri
  620.  
  621.     NAME
  622.     MUIA_Application_BrokerPri -- (V6) [I.G], LONG
  623.  
  624.     FUNCTION
  625.     Adjust the priority of an applications broker.
  626.  
  627.     SEE ALSO
  628.     MUIA_Application_BrokerHook
  629. Application.mui/MUIA_Application_Commands
  630.  
  631.     NAME
  632.     MUIA_Application_Commands -- (V4) [ISG], struct MUI_Command *
  633.  
  634.     FUNCTION
  635.     This attribute allows an application to include 
  636.     its own set of ARexx commands. You specify a
  637.     pointer to an array of MUI_Command structures,
  638.     which look like this:
  639.  
  640.     struct MUI_Command
  641.     {
  642.        char        *mc_Name;
  643.        char        *mc_Template;
  644.        LONG         mc_Parameters;
  645.        struct Hook *mc_Hook;
  646.        LONG         mc_Reserved[5];
  647.     };
  648.  
  649.     mc_Name       contains the name of your command.
  650.                   Commands are not case sensitive.
  651.  
  652.     mc_Template   is an argument template that follows
  653.                   the same rules as dos.library/ReadArgs().
  654.                   It may be NULL, in which case your command
  655.                   doesn't need any parameters.
  656.  
  657.     mc_Parameters is the number of parameters specified
  658.                   in the template array.
  659.  
  660.     mc_Hook       is a pointer to the callback hook defining
  661.                   the function to be called.
  662.  
  663.     You may specify any number of MUI_Command structures,
  664.     but you must terminate your array with a NULL field.
  665.  
  666.     When a command shows up an applications ARexx port,
  667.     MUI parses the arguments according to the given
  668.     template and calls the hook with the application
  669.     object as hook object in a2 and a pointer to
  670.     an array of longwords containing the parameters
  671.     in a1.
  672.  
  673.     The result code of your hook will be replied to
  674.     ARexx as rc.
  675.  
  676.     If you have some simple ARexx commands that just
  677.     emulate some user action (e.g. clicking a button),
  678.     you can use the magic cookie MC_TEMPLATE_ID for 
  679.     mc_Template and a return id value for mc_Parameters. 
  680.     In this case, MUI will do no argument parsing and 
  681.     instead simply return the specified id value on the 
  682.     next call to MUIM_Application_Input.
  683.  
  684.     For more sophisticated possibilities in ARexx
  685.     callback hooks, please refer to
  686.     MUIA_Application_RexxMsg and MUIA_Application_RexxString.
  687.  
  688.     EXAMPLE
  689.     static struct MUI_Command commands[] =
  690.     {
  691.        { "rescan", MC_TEMPLATE_ID, ID_RESCAN, NULL     },
  692.        { "select", "PATTERN/A"   , 1        , &selhook },
  693.        { NULL    , NULL          , NULL     , NULL     }
  694.     };
  695.  
  696.     SEE ALSO
  697.     MUIA_Application_RexxMsg, MUIA_Application_RexxString
  698. Application.mui/MUIA_Application_Copyright
  699.  
  700.     NAME
  701.     MUIA_Application_Copyright -- (V4) [I.G], STRPTR
  702.  
  703.     FUNCTION
  704.     A copyright string, containing the year and the
  705.     company.
  706.  
  707.     EXAMPLE
  708.     see MUIA_Application_Title
  709.  
  710.     SEE ALSO
  711.     MUIA_Application_Title, MUIA_Application_Version,
  712.     MUIA_Application_Author, MUIA_Application_Description,
  713.     MUIA_Application_Base
  714. Application.mui/MUIA_Application_Description
  715.  
  716.     NAME
  717.     MUIA_Application_Description -- (V4) [I.G], STRPTR
  718.  
  719.     FUNCTION
  720.     Short description, about 40 characters.
  721.     Shown e.g. in commodities exchange.
  722.  
  723.     EXAMPLE
  724.     see MUIA_Application_Title
  725.  
  726.     SEE ALSO
  727.     MUIA_Application_Title, MUIA_Application_Version,
  728.     MUIA_Application_Author, MUIA_Application_Copyright,
  729.     MUIA_Application_Base
  730. Application.mui/MUIA_Application_DiskObject
  731.  
  732.     NAME
  733.     MUIA_Application_DiskObject -- (V4) [ISG], struct DiskObject *
  734.  
  735.     FUNCTION
  736.     Pointer to a struct DiskObject, e.g. obtained
  737.     from GetDiskObject(). If present, MUI will use
  738.     this object for the AppIcon when your application
  739.     gets iconified.
  740.  
  741.     Otherwise MUI will try to locate "env:sys/dev_mui.info"
  742.     and, if not present, fall back to a default icon.
  743.  
  744.     EXAMPLE
  745.     ...
  746.     MUIA_Application_DiskObject, 
  747.        dobj = GetDiskObject("PROGDIR:MyApp"),
  748.     ...
  749.  
  750.     /* note that you have to free dobj yourself! */
  751.  
  752.     NOTES
  753.     Unless you have set MUIA_Application_RequiresIconification,
  754.     this attribute might have no effect, maybe because the
  755.     user installed a light version of MUI. You must be prepared
  756.     to receive a NULL pointer when you try to read it!
  757.  
  758.    SEE ALSO
  759.     MUIA_Application_Iconified
  760. Application.mui/MUIA_Application_DoubleStart
  761.  
  762.     NAME
  763.     MUIA_Application_DoubleStart -- (V4) [..G], BOOL
  764.  
  765.     FUNCTION
  766.     This attribute is set automatically when the user
  767.     tries to start a MUIA_SingleTask application twice.
  768.     You can react on this and take appropriate actions,
  769.     e.g. pop up a requester or quit yourself.
  770.  
  771.     SEE ALSO
  772.     MUIA_Application_SingleTask
  773. Application.mui/MUIA_Application_DropObject
  774.  
  775.     NAME
  776.     MUIA_Application_DropObject -- (V5) [IS.], Object *
  777.  
  778.     FUNCTION
  779.     If your application is iconified and the user drops
  780.     icons onto the AppIcon, the object specified here will 
  781.     receive the AppMessage.
  782.  
  783.     SEE ALSO
  784.     MUIA_Window_AppWindow, MUIM_CallHook
  785. Application.mui/MUIA_Application_ForceQuit
  786.  
  787.     NAME
  788.     MUIA_Application_ForceQuit -- (V8) [..G], BOOL
  789.  
  790.     FUNCTION
  791.     When your input loop receives a MUIV_Application_ReturnID_Quit,
  792.     you should query this attribute. In case its TRUE, your program
  793.     should exit quietly without popping up any safety requesters or 
  794.     other stuff.
  795.  
  796.     MUI will e.g. set this if the user issued a "QUIT FORCE" ARexx
  797.     command to your application.
  798. Application.mui/MUIA_Application_HelpFile
  799.  
  800.     NAME
  801.     MUIA_Application_HelpFile -- (V8) [ISG], STRPTR
  802.  
  803.     FUNCTION
  804.     This attribute allows defining an AmigaGuide style file
  805.     to be displayed when the user requests online help.
  806.  
  807.     When the HELP button is pressed and the application
  808.     defines a MUIA_Application_HelpFile, MUI tries to obtain
  809.     MUIA_HelpNode from the current object (the one under
  810.     the mouse pointer). If MUIA_HelpNode is not defined,
  811.     MUI continues asking the parent object for this
  812.     attribute (usually a group, but remember: the parent
  813.     of a windows root object is the window itself, the
  814.     parent of a window is the application).
  815.  
  816.     When a non NULL MUIA_HelpNode is found, the same procedure
  817.     is applied to MUIA_HelpLIne. Then MUI puts the application 
  818.     to sleep and displays the file at the position specified 
  819.     with MUIA_HelpNode and/or MUIA_HelpLine.
  820.  
  821.     This behaviour allows you to define one 
  822.     MUIA_Application_HelpFile for your application object 
  823.     and different help nodes and lines for your applications 
  824.     windows and/or gadgets.
  825.  
  826.     EXAMPLE
  827.  
  828.     ApplicationObject,
  829.        ...
  830.        MUIA_Application_HelpFile, "progdir:myapp.guide",
  831.        ...,
  832.        SubWindow, WindowObject,
  833.           MUIA_Window_Title, "Prefs Window",
  834.           ...,
  835.           MUIA_HelpNode, "prefs-section",
  836.           ...,
  837.           End,
  838.  
  839.        SubWindow, WindowObject,
  840.           MUIA_Window_Title, "Play Window",
  841.           ...
  842.           MUIA_HelpNode, "play-section",
  843.           ...
  844.           WindowContents, VGroup,
  845.              ...,
  846.              Child, StringObject,
  847.                 MUIA_HelpNode, "play-string",
  848.                 ...,
  849.                 End,
  850.              End,
  851.           End,
  852.        End;
  853.  
  854.     In this case, the user will get the prefs-section chapter
  855.     of "myapp.guide" when he requests help in the Prefs window,
  856.     the play-string chapter when he requests help over the
  857.     string gadget in the Play window or the play-section
  858.     chapter somewhere else in the Play window.
  859.  
  860.     NOTES
  861.     Since muimaster.library V8, this attribute replaces the old
  862.     and obsolete MUIA_HelpFile attribute. MUI no longer supports
  863.     the possibility to specify different help files for different
  864.     parts of your application. This step was necessary due to
  865.     some other internal changes and enhancements.
  866.  
  867.     SEE ALSO
  868.     MUIA_HelpNode, MUIA_HelpLine
  869. Application.mui/MUIA_Application_Iconified
  870.  
  871.     NAME
  872.     MUIA_Application_Iconified -- (V4) [.SG], BOOL
  873.  
  874.     FUNCTION
  875.     Setting this attribute to TRUE causes the application
  876.     to become iconified. Every open window will be closed
  877.     and a (configurable) AppIcon will appear on the workbench.
  878.  
  879.     Same thing happens when the user hits the iconify gadget
  880.     in the window border or uses commodities Exchange to
  881.     hide your applications interface.
  882.  
  883.     There is no way for you to prevent your application from
  884.     being iconified. However, you can react on the iconification
  885.     by listening to the MUIA_Application_Iconified attribute
  886.     with notification. This allows you to free some resources
  887.     you don't need in iconified state.
  888.  
  889.     When an application is iconified and you try to open a
  890.     window, the window won't open immediately. Instead MUI
  891.     remembers this action and opens the window once the
  892.     application is uniconified again.
  893.  
  894.     EXAMPLE
  895.  
  896.     /* inform the main input loop of iconification events */
  897.  
  898.     #define ID_HIDE 42
  899.     #define ID_SHOW 24
  900.  
  901.     DoMethod(app,MUIM_Notify,
  902.        MUIA_Application_Iconified, TRUE,
  903.        app, 2, MUIM_Application_ReturnID, ID_HIDE);
  904.  
  905.     DoMethod(app,MUIM_Notify,
  906.        MUIA_Application_Iconified, FALSE,
  907.        app, 2, MUIM_Application_ReturnID, ID_SHOW);
  908.  
  909.     SEE ALSO
  910.     MUIA_Application_DiskObject
  911. Application.mui/MUIA_Application_Menu
  912.  
  913.     NAME
  914.     MUIA_Application_Menu -- (V4) [I.G], struct NewMenu * (OBSOLETE)
  915.  
  916.     FUNCTION
  917.     Obsolete, use MUIA_Application_Menustrip instead.
  918.  
  919.     SEE ALSO
  920.     MUIA_Application_Menustrip
  921. Application.mui/MUIA_Application_MenuAction
  922.  
  923.     NAME
  924.     MUIA_Application_MenuAction -- (V4) [..G], ULONG
  925.  
  926.     FUNCTION
  927.     Whenever a menu item is selected, this attribute will be
  928.     set to the corresponding UserData field of the gadtools
  929.     NewMenu structure. This allows reacting on menu items
  930.     via broadcasting.
  931.  
  932.     SEE ALSO
  933.     MUIA_Application_Menu, MUIA_Application_MenuAction
  934. Application.mui/MUIA_Application_MenuHelp
  935.  
  936.     NAME
  937.     MUIA_Application_MenuHelp -- (V4) [..G], ULONG
  938.  
  939.     FUNCTION
  940.     Whenever a menu item is selected with the help key, this
  941.     attribute will be set to the corresponding UserData field
  942.     of the gadtools NewMenu structure. Together with
  943.     MUIM_Application_ShowHelp this allows creation of
  944.     menu help texts.
  945.  
  946.     SEE ALSO
  947.     MUIA_Application_Menu, MUIA_Application_ShowHelp
  948. Application.mui/MUIA_Application_Menustrip
  949.  
  950.     NAME
  951.     MUIA_Application_Menustrip -- (V8) [I..], Object *
  952.  
  953.     FUNCTION
  954.     Specify a menu strip object for the application. The object
  955.     is treated as a child of the application and will be disposed
  956.     when the application is disposed.
  957.  
  958.     Menustrip objects defined for the application are used
  959.     as menu for every window of the application, as long as
  960.     the window doesn't define its private menu.
  961.  
  962.     MUIA_Application_Menustrip replaces the old and obsolete
  963.     MUIA_Application_Menu tag.
  964.  
  965.     Usually, you will create the menu object with MUI's builtin
  966.     object library from a gadtools NewMenu structure, but its
  967.     also OK to define the menu tree "by hand" using the
  968.     Family class.
  969. Application.mui/MUIA_Application_RexxHook
  970.  
  971.     NAME
  972.     MUIA_Application_RexxHook -- (V7) [ISG], struct Hook *
  973.  
  974.     FUNCTION
  975.     When specified, MUI calls this hook whenever a rexx message 
  976.     arrives and MUI can't map it to a builtin or a programmer
  977.     specified command. The hook will be called with a pointer 
  978.     to itself in A0, a pointer to the application object in A2 
  979.     and a pointer to a struct RexxMsg in A1.
  980.  
  981.     The return code from the hook is used as result code
  982.     when replying the message, the secondary result can
  983.     be set with MUIA_Application_RexxString.
  984.  
  985.     SEE ALSO
  986.     MUIA_Application_Commands
  987. Application.mui/MUIA_Application_RexxMsg
  988.  
  989.     NAME
  990.     MUIA_Application_RexxMsg -- (V4) [..G], struct RxMsg *
  991.  
  992.     FUNCTION
  993.     Within an ARexx callback hook, you can obtain
  994.     a pointer to the RexxMsg that came with the
  995.     command. This allows you to use some ARexx
  996.     support functions coming with amiga.lib
  997.  
  998.     SEE ALSO
  999.     MUIA_Application_Commands, MUIA_Application_RexxString
  1000. Application.mui/MUIA_Application_RexxString
  1001.  
  1002.     NAME
  1003.     MUIA_Application_RexxString -- (V4) [.S.], STRPTR
  1004.  
  1005.     FUNCTION
  1006.     ARexx allows returning a string as result of a
  1007.     function call. This attribute allows setting the
  1008.     result string within an ARexx callback hook.
  1009.  
  1010.     The string is temporarily copied.
  1011.  
  1012.     SEE ALSO
  1013.     MUIA_Application_Commands, MUIA_Application_RexxMsg
  1014. Application.mui/MUIA_Application_SingleTask
  1015.  
  1016.     NAME
  1017.     MUIA_Application_SingleTask -- (V4) [I..], BOOL
  1018.  
  1019.     FUNCTION
  1020.     Boolean value to indicate whether or not your application
  1021.     is a single task program. When set to TRUE, MUI will
  1022.     refuse to create more than one application object.
  1023.  
  1024.     In this case, the already running application gets its
  1025.     MUIA_DoubleStart attribute set to TRUE. You can listen
  1026.     to this and take appropriate actions, e.g. pop up
  1027.     a requester.
  1028.  
  1029.     Examples for single task applications are the system
  1030.     preferences program. It doesn't make sense for them
  1031.     to run more than once.
  1032.  
  1033.     SEE ALSO
  1034.     MUIA_Application_DoubleStart
  1035. Application.mui/MUIA_Application_Sleep
  1036.  
  1037.     NAME
  1038.     MUIA_Application_Sleep -- (V4) [.S.], BOOL
  1039.  
  1040.     FUNCTION
  1041.     This attribute can be used to put a whole application
  1042.     to sleep. All open windows get disabled and a busy
  1043.     pointer appears.
  1044.  
  1045.     This attribute contains a nesting count, if you tell
  1046.     your application to sleep twice, you will have to tell 
  1047.     it to wake up twice too.
  1048.  
  1049.     If you need to do some time consuming actions, you
  1050.     always should set this attribute to inform the user
  1051.     that you are currently unable to handle input.
  1052.  
  1053.     A sleeping application's windows cannot be resized.
  1054.  
  1055.     EXAMPLES
  1056.     set(app,MUIA_Application_Sleep,TRUE ); // go to bed
  1057.     calc_fractals();
  1058.     set(app,MUIA_Application_Sleep,FALSE); // wake up
  1059.  
  1060.     SEE ALSO
  1061.     MUIA_Window_Sleep, MUIM_Application_InputBuffered
  1062. Application.mui/MUIA_Application_Title
  1063.  
  1064.     NAME
  1065.     MUIA_Application_Title -- (V4) [I.G], STRPTR
  1066.  
  1067.     FUNCTION
  1068.     This tag defines the title of an application.
  1069.     The title is e.g. shown in Commodities Exchange
  1070.     or in the MUI preferences program.
  1071.  
  1072.     An application title shall not contain any version
  1073.     information, just the pure title. Also, special
  1074.     characters such as ":/()#?*..." are not allowed.
  1075.  
  1076.     You should use a quiet long and unique name for
  1077.     your applications. Naming it "Viewer" or "Browser"
  1078.     is not a wise choice.
  1079.  
  1080.     The length of the name must not exceed 30 characters!
  1081.  
  1082.     EXAMPLE
  1083.     ApplicationObject,
  1084.        MUIA_Application_Title      , "WbMan",
  1085.        MUIA_Application_Version    , "$VER: WbMan 0.24 (19.7.93)",
  1086.        MUIA_Application_Copyright  , "© 1993 by Klaus Melchior",
  1087.        MUIA_Application_Author     , "Klaus Melchior",
  1088.        MUIA_Application_Description, "Manages the WBStartup.",
  1089.        MUIA_Application_Base       , "WBMAN",
  1090.        ...
  1091.  
  1092.     SEE ALSO
  1093.     MUIA_Application_Version, MUIA_Application_Copyright,
  1094.     MUIA_Application_Author, MUIA_Application_Description,
  1095.     MUIA_Application_Base
  1096. Application.mui/MUIA_Application_Version
  1097.  
  1098.     NAME
  1099.     MUIA_Application_Version -- (V4) [I.G], STRPTR
  1100.  
  1101.     FUNCTION
  1102.     Define a version string for an application.
  1103.     This string shall follow standard version string
  1104.     convetions but must *not* contain a leading "\0".
  1105.  
  1106.     EXAMPLE
  1107.     see MUIA_Application_Title
  1108.  
  1109.     SEE ALSO
  1110.     MUIA_Application_Title, MUIA_Application_Copyright,
  1111.     MUIA_Application_Author, MUIA_Application_Description,
  1112.     MUIA_Application_Base
  1113. Application.mui/MUIA_Application_Window
  1114.  
  1115.     NAME
  1116.     MUIA_Application_Window -- (V4) [I..], Object *
  1117.  
  1118.     FUNCTION
  1119.     A pointer to a MUI object of Window class. An
  1120.     application may have any number of sub windows,
  1121.     each of them being a child of the application.
  1122.  
  1123.     When the application receives some kind of user
  1124.     input through its IDCMP, it diverts the message
  1125.     down to its children, as long as they are opened.
  1126.  
  1127.     Things like iconification or preferences changes
  1128.     cause the application object to temporarily close
  1129.     every open window (and reopen it later). Your
  1130.     main program normally doesn't need to deal with
  1131.     these things.
  1132.  
  1133.     As with the children of group class, it's common
  1134.     to use a call to MUI_NewObject() as value for
  1135.     this attribute. No error checking needs to be
  1136.     done, the application object handles every
  1137.     failure automatically.
  1138.  
  1139.     When you dispose your application, its sub windows
  1140.     will also get deleted. Thus, the only thing to do
  1141.     to remove your application is a
  1142.  
  1143.     MUI_DisposeObject(ApplicationObject);
  1144.  
  1145.     Every window, every gadget, every memory will be
  1146.     freed by this single call.
  1147.  
  1148.     EXAMPLE
  1149.     Please refer to one of the example programs.
  1150.  
  1151.     SEE ALSO
  1152.