home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 5 / amigaformatcd05.iso / mui / developer / autodocs / mui_application.doc < prev    next >
Text File  |  1996-08-13  |  47KB  |  1,522 lines
  1. TABLE OF CONTENTS
  2.  
  3. Application.mui/Application.mui
  4. Application.mui/MUIA_Application_Active
  5. Application.mui/MUIA_Application_Author
  6. Application.mui/MUIA_Application_Base
  7. Application.mui/MUIA_Application_Broker
  8. Application.mui/MUIA_Application_BrokerHook
  9. Application.mui/MUIA_Application_BrokerPort
  10. Application.mui/MUIA_Application_BrokerPri
  11. Application.mui/MUIA_Application_Commands
  12. Application.mui/MUIA_Application_Copyright
  13. Application.mui/MUIA_Application_Description
  14. Application.mui/MUIA_Application_DiskObject
  15. Application.mui/MUIA_Application_DoubleStart
  16. Application.mui/MUIA_Application_DropObject
  17. Application.mui/MUIA_Application_ForceQuit
  18. Application.mui/MUIA_Application_HelpFile
  19. Application.mui/MUIA_Application_Iconified
  20. Application.mui/MUIA_Application_Menu
  21. Application.mui/MUIA_Application_MenuAction
  22. Application.mui/MUIA_Application_MenuHelp
  23. Application.mui/MUIA_Application_Menustrip
  24. Application.mui/MUIA_Application_RexxHook
  25. Application.mui/MUIA_Application_RexxMsg
  26. Application.mui/MUIA_Application_RexxString
  27. Application.mui/MUIA_Application_SingleTask
  28. Application.mui/MUIA_Application_Sleep
  29. Application.mui/MUIA_Application_Title
  30. Application.mui/MUIA_Application_UseCommodities
  31. Application.mui/MUIA_Application_UseRexx
  32. Application.mui/MUIA_Application_Version
  33. Application.mui/MUIA_Application_Window
  34. Application.mui/MUIA_Application_WindowList
  35. Application.mui/MUIM_Application_AboutMUI
  36. Application.mui/MUIM_Application_AddInputHandler
  37. Application.mui/MUIM_Application_CheckRefresh
  38. Application.mui/MUIM_Application_GetMenuCheck
  39. Application.mui/MUIM_Application_GetMenuState
  40. Application.mui/MUIM_Application_Input
  41. Application.mui/MUIM_Application_InputBuffered
  42. Application.mui/MUIM_Application_Load
  43. Application.mui/MUIM_Application_NewInput
  44. Application.mui/MUIM_Application_OpenConfigWindow
  45. Application.mui/MUIM_Application_PushMethod
  46. Application.mui/MUIM_Application_RemInputHandler
  47. Application.mui/MUIM_Application_ReturnID
  48. Application.mui/MUIM_Application_Save
  49. Application.mui/MUIM_Application_SetConfigItem
  50. Application.mui/MUIM_Application_SetMenuCheck
  51. Application.mui/MUIM_Application_SetMenuState
  52. Application.mui/MUIM_Application_ShowHelp
  53. Application.mui/Application.mui
  54.  
  55.     Application class is the master class for all
  56.     MUI applications. It serves as a kind of anchor
  57.     for all input, either coming from the user or
  58.     somewhere from the system, e.g. commodities
  59.     or ARexx messages.
  60.  
  61.     An application can have any number of sub windows,
  62.     these windows are the children of the application.
  63. Application.mui/MUIA_Application_Active
  64.  
  65.     NAME
  66.     MUIA_Application_Active -- (V4 ) [ISG], BOOL
  67.  
  68.     FUNCTION
  69.     This attribute reflects the state that the user adjusted
  70.     with commodities Exchange. MUI itself doesn't pay any
  71.     attention to it, this is up to you.
  72.  
  73.     SEE ALSO
  74.     MUIA_Application_Broker
  75. Application.mui/MUIA_Application_Author
  76.  
  77.     NAME
  78.     MUIA_Application_Author -- (V4 ) [I.G], STRPTR
  79.  
  80.     FUNCTION
  81.     Name of the applications author.
  82.  
  83.     EXAMPLE
  84.     see MUIA_Application_Title
  85.  
  86.     SEE ALSO
  87.     MUIA_Application_Title, MUIA_Application_Copyright,
  88.     MUIA_Application_Version, MUIA_Application_Description,
  89.     MUIA_Application_Base
  90. Application.mui/MUIA_Application_Base
  91.  
  92.     NAME
  93.     MUIA_Application_Base -- (V4 ) [I.G], STRPTR
  94.  
  95.     FUNCTION
  96.     The basename for an application. This name is used
  97.     for the builtin ARexx port and for some internal
  98.     file management.
  99.  
  100.     A basename must neither contain spaces nor any
  101.     special characters such as ":/()#?*...".
  102.  
  103.     When your program is a single task application
  104.     (i.e. MUIA_Application_SingleTask is TRUE), the
  105.     base name will be used without further modification.
  106.  
  107.     Otherwise, it gets a ".1", ".2", etc. appended,
  108.     depending on how many applications are already
  109.     running. If you need to know the name of your
  110.     ARexx port, you can query the base name attribute
  111.     after the application is created.
  112.  
  113.     EXAMPLE
  114.     see MUIA_Application_Title
  115.  
  116.     SEE ALSO
  117.     MUIA_Application_Title, MUIA_Application_Version,
  118.     MUIA_Application_Author, MUIA_Application_Copyright,
  119.     MUIA_Application_Description
  120. Application.mui/MUIA_Application_Broker
  121.  
  122.     NAME
  123.     MUIA_Application_Broker -- (V4 ) [..G], Broker *
  124.  
  125.     FUNCTION
  126.     If you need to attach some additional commodities objects
  127.     to your application (e.g. because you need lots of hotkeys),
  128.     you can obtain a pointer to the applications Broker structure
  129.     and add some commodities objects.
  130.  
  131.     MUI will free the complete broker when the application is
  132.     disposed, no need for you to free your objects yourself.
  133.  
  134.     To receive input from your objects, you will also need to
  135.     install a MUIA_Application_BrokerHook.
  136.  
  137.     NOTES
  138.     Unless you have set MUIA_Application_RequiresCX, you must be
  139.     prepared to receive a NULL pointer. In this case, the
  140.     commodities interface is not available, maybe because the
  141.     user installed a light version of MUI.
  142.  
  143.     SEE ALSO
  144.     MUIA_Application_BrokerHook
  145. Application.mui/MUIA_Application_BrokerHook
  146.  
  147.     NAME
  148.     MUIA_Application_BrokerHook -- (V4 ) [ISG], struct Hook *
  149.  
  150.     FUNCTION
  151.     You specify a pointer to hook structure. The function
  152.     will be called whenever a commodities message arrives
  153.     (between MUI's GetMsg() and ReplyMsg()).
  154.  
  155.     You receive a pointer to the application object
  156.     as object in a2 and a pointer to commodities
  157.     CxMsg message in a1.
  158.  
  159.     NOTES
  160.     The commodities interface isn't available in the
  161.     memory saving "light" version of MUI. Your hook
  162.     will never be called in this case.
  163.  
  164.     SEE ALSO
  165.     MUIA_Application_Broker
  166. Application.mui/MUIA_Application_BrokerPort
  167.  
  168.     NAME
  169.     MUIA_Application_BrokerPort -- (V6 ) [..G], struct MsgPort *
  170.  
  171.     FUNCTION
  172.     Get a pointer to the applications commodities message port.
  173.     If you want to add own Hotkeys to your application, you
  174.     need a message port. Instead of creating your own, you
  175.     should better use this one.
  176.  
  177.     NOTES
  178.     Unless you have set MUIA_Application_RequiresCX, you must be
  179.     prepared to receive a NULL pointer. In this case, the
  180.     commodities interface is not available, maybe because the
  181.     user installed a light version of MUI.
  182.  
  183.     SEE ALSO
  184.     MUIA_Application_BrokerHook
  185. Application.mui/MUIA_Application_BrokerPri
  186.  
  187.     NAME
  188.     MUIA_Application_BrokerPri -- (V6 ) [I.G], LONG
  189.  
  190.     FUNCTION
  191.     Adjust the priority of an applications broker.
  192.  
  193.     SEE ALSO
  194.     MUIA_Application_BrokerHook
  195. Application.mui/MUIA_Application_Commands
  196.  
  197.     NAME
  198.     MUIA_Application_Commands -- (V4 ) [ISG], struct MUI_Command *
  199.  
  200.     FUNCTION
  201.     This attribute allows an application to include 
  202.     its own set of ARexx commands. You specify a
  203.     pointer to an array of MUI_Command structures,
  204.     which look like this:
  205.  
  206.     struct MUI_Command
  207.     {
  208.        char        *mc_Name;
  209.        char        *mc_Template;
  210.        LONG         mc_Parameters;
  211.        struct Hook *mc_Hook;
  212.        LONG         mc_Reserved[5];
  213.     };
  214.  
  215.     mc_Name       contains the name of your command.
  216.                   Commands are not case sensitive.
  217.  
  218.     mc_Template   is an argument template that follows
  219.                   the same rules as dos.library/ReadArgs().
  220.                   It may be NULL, in which case your command
  221.                   doesn't need any parameters.
  222.  
  223.     mc_Parameters is the number of parameters specified
  224.                   in the template array.
  225.  
  226.     mc_Hook       is a pointer to the callback hook defining
  227.                   the function to be called.
  228.  
  229.     You may specify any number of MUI_Command structures,
  230.     but you must terminate your array with a NULL field.
  231.  
  232.     When a command shows up an applications ARexx port,
  233.     MUI parses the arguments according to the given
  234.     template and calls the hook with the application
  235.     object as hook object in a2 and a pointer to
  236.     an array of longwords containing the parameters
  237.     in a1.
  238.  
  239.     The result code of your hook will be replied to
  240.     ARexx as rc.
  241.  
  242.     If you have some simple ARexx commands that just
  243.     emulate some user action (e.g. clicking a button),
  244.     you can use the magic cookie MC_TEMPLATE_ID for 
  245.     mc_Template and a return id value for mc_Parameters. 
  246.     In this case, MUI will do no argument parsing and 
  247.     instead simply return the specified id value on the 
  248.     next call to MUIM_Application_Input.
  249.  
  250.     For more sophisticated possibilities in ARexx
  251.     callback hooks, please refer to
  252.     MUIA_Application_RexxMsg and MUIA_Application_RexxString.
  253.  
  254.     EXAMPLE
  255.     static struct MUI_Command commands[] =
  256.     {
  257.        { "rescan", MC_TEMPLATE_ID, ID_RESCAN, NULL     },
  258.        { "select", "PATTERN/A"   , 1        , &selhook },
  259.        { NULL    , NULL          , NULL     , NULL     }
  260.     };
  261.  
  262.     SEE ALSO
  263.     MUIA_Application_RexxMsg, MUIA_Application_RexxString
  264. Application.mui/MUIA_Application_Copyright
  265.  
  266.     NAME
  267.     MUIA_Application_Copyright -- (V4 ) [I.G], STRPTR
  268.  
  269.     FUNCTION
  270.     A copyright string, containing the year and the
  271.     company.
  272.  
  273.     EXAMPLE
  274.     see MUIA_Application_Title
  275.  
  276.     SEE ALSO
  277.     MUIA_Application_Title, MUIA_Application_Version,
  278.     MUIA_Application_Author, MUIA_Application_Description,
  279.     MUIA_Application_Base
  280. Application.mui/MUIA_Application_Description
  281.  
  282.     NAME
  283.     MUIA_Application_Description -- (V4 ) [I.G], STRPTR
  284.  
  285.     FUNCTION
  286.     Short description, about 40 characters.
  287.     Shown e.g. in commodities exchange.
  288.  
  289.     EXAMPLE
  290.     see MUIA_Application_Title
  291.  
  292.     SEE ALSO
  293.     MUIA_Application_Title, MUIA_Application_Version,
  294.     MUIA_Application_Author, MUIA_Application_Copyright,
  295.     MUIA_Application_Base
  296. Application.mui/MUIA_Application_DiskObject
  297.  
  298.     NAME
  299.     MUIA_Application_DiskObject -- (V4 ) [ISG], struct DiskObject *
  300.  
  301.     FUNCTION
  302.     Pointer to a struct DiskObject, e.g. obtained
  303.     from GetDiskObject(). If present, MUI will use
  304.     this object for the AppIcon when your application
  305.     gets iconified.
  306.  
  307.     Otherwise MUI will try to locate "env:sys/dev_mui.info"
  308.     and, if not present, fall back to a default icon.
  309.  
  310.     EXAMPLE
  311.     ...
  312.     MUIA_Application_DiskObject, 
  313.        dobj = GetDiskObject("PROGDIR:MyApp"),
  314.     ...
  315.  
  316.     /* note that you have to free dobj yourself! */
  317.  
  318.     NOTES
  319.     Unless you have set MUIA_Application_RequiresIconification,
  320.     this attribute might have no effect, maybe because the
  321.     user installed a light version of MUI. You must be prepared
  322.     to receive a NULL pointer when you try to read it!
  323.  
  324.    SEE ALSO
  325.     MUIA_Application_Iconified
  326. Application.mui/MUIA_Application_DoubleStart
  327.  
  328.     NAME
  329.     MUIA_Application_DoubleStart -- (V4 ) [..G], BOOL
  330.  
  331.     FUNCTION
  332.     This attribute is set automatically when the user
  333.     tries to start a MUIA_SingleTask application twice.
  334.     You can react on this and take appropriate actions,
  335.     e.g. pop up a requester or quit yourself.
  336.  
  337.     SEE ALSO
  338.     MUIA_Application_SingleTask
  339. Application.mui/MUIA_Application_DropObject
  340.  
  341.     NAME
  342.     MUIA_Application_DropObject -- (V5 ) [IS.], Object *
  343.  
  344.     FUNCTION
  345.     If your application is iconified and the user drops
  346.     icons onto the AppIcon, the object specified here will 
  347.     receive the AppMessage.
  348.  
  349.     SEE ALSO
  350.     MUIA_Window_AppWindow, MUIM_CallHook
  351. Application.mui/MUIA_Application_ForceQuit
  352.  
  353.     NAME
  354.     MUIA_Application_ForceQuit -- (V8 ) [..G], BOOL
  355.  
  356.     FUNCTION
  357.     When your input loop receives a MUIV_Application_ReturnID_Quit,
  358.     you should query this attribute. In case its TRUE, your program
  359.     should exit quietly without popping up any safety requesters or 
  360.     other stuff.
  361.  
  362.     MUI will e.g. set this if the user issued a "QUIT FORCE" ARexx
  363.     command to your application.
  364. Application.mui/MUIA_Application_HelpFile
  365.  
  366.     NAME
  367.     MUIA_Application_HelpFile -- (V8 ) [ISG], STRPTR
  368.  
  369.     FUNCTION
  370.     This attribute allows defining an AmigaGuide style file
  371.     to be displayed when the user requests online help.
  372.  
  373.     When the HELP button is pressed and the application
  374.     defines a MUIA_Application_HelpFile, MUI tries to obtain
  375.     MUIA_HelpNode from the current object (the one under
  376.     the mouse pointer). If MUIA_HelpNode is not defined,
  377.     MUI continues asking the parent object for this
  378.     attribute (usually a group, but remember: the parent
  379.     of a windows root object is the window itself, the
  380.     parent of a window is the application).
  381.  
  382.     When a non NULL MUIA_HelpNode is found, the same procedure
  383.     is applied to MUIA_HelpLIne. Then MUI puts the application 
  384.     to sleep and displays the file at the position specified 
  385.     with MUIA_HelpNode and/or MUIA_HelpLine.
  386.  
  387.     This behaviour allows you to define one 
  388.     MUIA_Application_HelpFile for your application object 
  389.     and different help nodes and lines for your applications 
  390.     windows and/or gadgets.
  391.  
  392.     EXAMPLE
  393.  
  394.     ApplicationObject,
  395.        ...
  396.        MUIA_Application_HelpFile, "progdir:myapp.guide",
  397.        ...,
  398.        SubWindow, WindowObject,
  399.           MUIA_Window_Title, "Prefs Window",
  400.           ...,
  401.           MUIA_HelpNode, "prefs-section",
  402.           ...,
  403.           End,
  404.  
  405.        SubWindow, WindowObject,
  406.           MUIA_Window_Title, "Play Window",
  407.           ...
  408.           MUIA_HelpNode, "play-section",
  409.           ...
  410.           WindowContents, VGroup,
  411.              ...,
  412.              Child, StringObject,
  413.                 MUIA_HelpNode, "play-string",
  414.                 ...,
  415.                 End,
  416.              End,
  417.           End,
  418.        End;
  419.  
  420.     In this case, the user will get the prefs-section chapter
  421.     of "myapp.guide" when he requests help in the Prefs window,
  422.     the play-string chapter when he requests help over the
  423.     string gadget in the Play window or the play-section
  424.     chapter somewhere else in the Play window.
  425.  
  426.     NOTES
  427.     Since muimaster.library V8, this attribute replaces the old
  428.     and obsolete MUIA_HelpFile attribute. MUI no longer supports
  429.     the possibility to specify different help files for different
  430.     parts of your application. This step was necessary due to
  431.     some other internal changes and enhancements.
  432.  
  433.     SEE ALSO
  434.     MUIA_HelpNode, MUIA_HelpLine
  435. Application.mui/MUIA_Application_Iconified
  436.  
  437.     NAME
  438.     MUIA_Application_Iconified -- (V4 ) [.SG], BOOL
  439.  
  440.     FUNCTION
  441.     Setting this attribute to TRUE causes the application
  442.     to become iconified. Every open window will be closed
  443.     and a (configurable) AppIcon will appear on the workbench.
  444.  
  445.     Same thing happens when the user hits the iconify gadget
  446.     in the window border or uses commodities Exchange to
  447.     hide your applications interface.
  448.  
  449.     There is no way for you to prevent your application from
  450.     being iconified. However, you can react on the iconification
  451.     by listening to the MUIA_Application_Iconified attribute
  452.     with notification. This allows you to free some resources
  453.     you don't need in iconified state.
  454.  
  455.     When an application is iconified and you try to open a
  456.     window, the window won't open immediately. Instead MUI
  457.     remembers this action and opens the window once the
  458.     application is uniconified again.
  459.  
  460.     EXAMPLE
  461.  
  462.     /* inform the main input loop of iconification events */
  463.  
  464.     #define ID_HIDE 42
  465.     #define ID_SHOW 24
  466.  
  467.     DoMethod(app,MUIM_Notify,
  468.        MUIA_Application_Iconified, TRUE,
  469.        app, 2, MUIM_Application_ReturnID, ID_HIDE);
  470.  
  471.     DoMethod(app,MUIM_Notify,
  472.        MUIA_Application_Iconified, FALSE,
  473.        app, 2, MUIM_Application_ReturnID, ID_SHOW);
  474.  
  475.     SEE ALSO
  476.     MUIA_Application_DiskObject
  477. Application.mui/MUIA_Application_Menu
  478.  
  479.     NAME
  480.     MUIA_Application_Menu -- (V4 ) [I.G], struct NewMenu * (OBSOLETE)
  481.  
  482.     FUNCTION
  483.     Obsolete, use MUIA_Application_Menustrip instead.
  484.  
  485.     SEE ALSO
  486.     MUIA_Application_Menustrip
  487. Application.mui/MUIA_Application_MenuAction
  488.  
  489.     NAME
  490.     MUIA_Application_MenuAction -- (V4 ) [..G], ULONG
  491.  
  492.     FUNCTION
  493.     Whenever a menu item is selected, this attribute will be
  494.     set to the corresponding UserData field of the gadtools
  495.     NewMenu structure. This allows reacting on menu items
  496.     via broadcasting.
  497.  
  498.     SEE ALSO
  499.     MUIA_Application_Menu, MUIA_Application_MenuAction
  500. Application.mui/MUIA_Application_MenuHelp
  501.  
  502.     NAME
  503.     MUIA_Application_MenuHelp -- (V4 ) [..G], ULONG
  504.  
  505.     FUNCTION
  506.     Whenever a menu item is selected with the help key, this
  507.     attribute will be set to the corresponding UserData field
  508.     of the gadtools NewMenu structure. Together with
  509.     MUIM_Application_ShowHelp this allows creation of
  510.     menu help texts.
  511.  
  512.     SEE ALSO
  513.     MUIA_Application_Menu, MUIA_Application_ShowHelp
  514. Application.mui/MUIA_Application_Menustrip
  515.  
  516.     NAME
  517.     MUIA_Application_Menustrip -- (V8 ) [I..], Object *
  518.  
  519.     FUNCTION
  520.     Specify a menu strip object for the application. The object
  521.     is treated as a child of the application and will be disposed
  522.     when the application is disposed.
  523.  
  524.     Menustrip objects defined for the application are used
  525.     as menu for every window of the application, as long as
  526.     the window doesn't define its private menu.
  527.  
  528.     MUIA_Application_Menustrip replaces the old and obsolete
  529.     MUIA_Application_Menu tag.
  530.  
  531.     Usually, you will create the menu object with MUI's builtin
  532.     object library from a gadtools NewMenu structure, but its
  533.     also OK to define the menu tree "by hand" using the
  534.     Family class.
  535. Application.mui/MUIA_Application_RexxHook
  536.  
  537.     NAME
  538.     MUIA_Application_RexxHook -- (V7 ) [ISG], struct Hook *
  539.  
  540.     FUNCTION
  541.     When specified, MUI calls this hook whenever a rexx message 
  542.     arrives and MUI can't map it to a builtin or a programmer
  543.     specified command. The hook will be called with a pointer 
  544.     to itself in A0, a pointer to the application object in A2 
  545.     and a pointer to a struct RexxMsg in A1.
  546.  
  547.     The return code from the hook is used as result code
  548.     when replying the message, the secondary result can
  549.     be set with MUIA_Application_RexxString.
  550.  
  551.     SEE ALSO
  552.     MUIA_Application_Commands
  553. Application.mui/MUIA_Application_RexxMsg
  554.  
  555.     NAME
  556.     MUIA_Application_RexxMsg -- (V4 ) [..G], struct RxMsg *
  557.  
  558.     FUNCTION
  559.     Within an ARexx callback hook, you can obtain
  560.     a pointer to the RexxMsg that came with the
  561.     command. This allows you to use some ARexx
  562.     support functions coming with amiga.lib
  563.  
  564.     SEE ALSO
  565.     MUIA_Application_Commands, MUIA_Application_RexxString
  566. Application.mui/MUIA_Application_RexxString
  567.  
  568.     NAME
  569.     MUIA_Application_RexxString -- (V4 ) [.S.], STRPTR
  570.  
  571.     FUNCTION
  572.     ARexx allows returning a string as result of a
  573.     function call. This attribute allows setting the
  574.     result string within an ARexx callback hook.
  575.  
  576.     The string is temporarily copied.
  577.  
  578.     SEE ALSO
  579.     MUIA_Application_Commands, MUIA_Application_RexxMsg
  580. Application.mui/MUIA_Application_SingleTask
  581.  
  582.     NAME
  583.     MUIA_Application_SingleTask -- (V4 ) [I..], BOOL
  584.  
  585.     FUNCTION
  586.     Boolean value to indicate whether or not your application
  587.     is a single task program. When set to TRUE, MUI will
  588.     refuse to create more than one application object.
  589.  
  590.     In this case, the already running application gets its
  591.     MUIA_DoubleStart attribute set to TRUE. You can listen
  592.     to this and take appropriate actions, e.g. pop up
  593.     a requester.
  594.  
  595.     Examples for single task applications are the system
  596.     preferences program. It doesn't make sense for them
  597.     to run more than once.
  598.  
  599.     SEE ALSO
  600.     MUIA_Application_DoubleStart
  601. Application.mui/MUIA_Application_Sleep
  602.  
  603.     NAME
  604.     MUIA_Application_Sleep -- (V4 ) [.S.], BOOL
  605.  
  606.     FUNCTION
  607.     This attribute can be used to put a whole application
  608.     to sleep. All open windows get disabled and a busy
  609.     pointer appears.
  610.  
  611.     This attribute contains a nesting count, if you tell
  612.     your application to sleep twice, you will have to tell 
  613.     it to wake up twice too.
  614.  
  615.     If you need to do some time consuming actions, you
  616.     always should set this attribute to inform the user
  617.     that you are currently unable to handle input.
  618.  
  619.     A sleeping application's windows cannot be resized.
  620.  
  621.     EXAMPLES
  622.     set(app,MUIA_Application_Sleep,TRUE ); // go to bed
  623.     calc_fractals();
  624.     set(app,MUIA_Application_Sleep,FALSE); // wake up
  625.  
  626.     SEE ALSO
  627.     MUIA_Window_Sleep, MUIM_Application_InputBuffered
  628. Application.mui/MUIA_Application_Title
  629.  
  630.     NAME
  631.     MUIA_Application_Title -- (V4 ) [I.G], STRPTR
  632.  
  633.     FUNCTION
  634.     This tag defines the title of an application.
  635.     The title is e.g. shown in Commodities Exchange
  636.     or in the MUI preferences program.
  637.  
  638.     An application title shall not contain any version
  639.     information, just the pure title. Also, special
  640.     characters such as ":/()#?*..." are not allowed.
  641.  
  642.     You should use a quiet long and unique name for
  643.     your applications. Naming it "Viewer" or "Browser"
  644.     is not a wise choice.
  645.  
  646.     The length of the name must not exceed 30 characters!
  647.  
  648.     EXAMPLE
  649.     ApplicationObject,
  650.        MUIA_Application_Title      , "WbMan",
  651.        MUIA_Application_Version    , "$VER: WbMan 0.24 (19.7.93)",
  652.        MUIA_Application_Copyright  , "© 1993 by Klaus Melchior",
  653.        MUIA_Application_Author     , "Klaus Melchior",
  654.        MUIA_Application_Description, "Manages the WBStartup.",
  655.        MUIA_Application_Base       , "WBMAN",
  656.        ...
  657.  
  658.     SEE ALSO
  659.     MUIA_Application_Version, MUIA_Application_Copyright,
  660.     MUIA_Application_Author, MUIA_Application_Description,
  661.     MUIA_Application_Base
  662. Application.mui/MUIA_Application_UseCommodities
  663.  
  664.     NAME
  665.     MUIA_Application_UseCommodities -- (V10) [I..], BOOL
  666.  
  667.     FUNCTION
  668.     When set to FALSE, the application will run without a 
  669.     commodities interface. Think very well before using this
  670.     tag!
  671.  
  672.     SEE ALSO
  673.         MUIA_Application_UseRexx
  674. Application.mui/MUIA_Application_UseRexx
  675.  
  676.     NAME
  677.     MUIA_Application_UseRexx -- (V10) [I..], BOOL
  678.  
  679.     FUNCTION
  680.     When set to FALSE, the application will run without an
  681.     ARexx interface. Think very well before using this
  682.     tag!
  683.  
  684.     SEE ALSO
  685.         MUIA_Application_UseCommodities
  686. Application.mui/MUIA_Application_Version
  687.  
  688.     NAME
  689.     MUIA_Application_Version -- (V4 ) [I.G], STRPTR
  690.  
  691.     FUNCTION
  692.     Define a version string for an application.
  693.     This string shall follow standard version string
  694.     convetions but must *not* contain a leading "\0".
  695.  
  696.     EXAMPLE
  697.     see MUIA_Application_Title
  698.  
  699.     SEE ALSO
  700.     MUIA_Application_Title, MUIA_Application_Copyright,
  701.     MUIA_Application_Author, MUIA_Application_Description,
  702.     MUIA_Application_Base
  703. Application.mui/MUIA_Application_Window
  704.  
  705.     NAME
  706.     MUIA_Application_Window -- (V4 ) [I..], Object *
  707.  
  708.     FUNCTION
  709.     A pointer to a MUI object of Window class. An
  710.     application may have any number of sub windows,
  711.     each of them being a child of the application.
  712.  
  713.     When the application receives some kind of user
  714.     input through its IDCMP, it diverts the message
  715.     down to its children, as long as they are opened.
  716.  
  717.     Things like iconification or preferences changes
  718.     cause the application object to temporarily close
  719.     every open window (and reopen it later). Your
  720.     main program normally doesn't need to deal with
  721.     these things.
  722.  
  723.     As with the children of group class, it's common
  724.     to use a call to MUI_NewObject() as value for
  725.     this attribute. No error checking needs to be
  726.     done, the application object handles every
  727.     failure automatically.
  728.  
  729.     When you dispose your application, its sub windows
  730.     will also get deleted. Thus, the only thing to do
  731.     to remove your application is a
  732.  
  733.     MUI_DisposeObject(ApplicationObject);
  734.  
  735.     Every window, every gadget, every memory will be
  736.     freed by this single call.
  737.  
  738.     EXAMPLE
  739.     Please refer to one of the example programs.
  740.  
  741.     SEE ALSO
  742. Application.mui/MUIA_Application_WindowList
  743.  
  744.     NAME
  745.     MUIA_Application_WindowList -- (V13) [..G], struct List *
  746.  
  747.     FUNCTION
  748.     This attribute returns a pointer to the exec list structure
  749.     which contains the children (i.e. windows) of an application.
  750.     Parse this with intuition.library/NextObject()!
  751. Application.mui/MUIM_Application_AboutMUI
  752.  
  753.     NAME
  754.     MUIM_Application_AboutMUI (V14)
  755.  
  756.     SYNOPSIS
  757.     DoMethod(obj,MUIM_Application_AboutMUI,Object *refwindow);
  758.  
  759.     FUNCTION
  760.     Show the MUI about window. Please include that in all your 
  761.     applications and link with a menu item called "About MUI...".
  762.  
  763.     INPUTS
  764.     - refwindow: pointer to a window object as reference. If !=NULL,
  765.     the MUI about window is centered according to this window. Note
  766.     that this points to a MUI window object, not to a struct window.
  767.  
  768.     EXAMPLE
  769.     DoMethod((Object *)DoMethod(strip,MUIM_FindUData,MEN_ABOUT),
  770.        MUIM_Notify,MUIA_Menuitem_Trigger,MUIV_EveryTime,
  771.        MUIV_Notify_Application,2,MUIM_Application_AboutMUI,mywinobj);
  772. Application.mui/MUIM_Application_AddInputHandler
  773.  
  774.     NAME
  775.     MUIM_Application_AddInputHandler (V11)
  776.  
  777.     SYNOPSIS
  778.     DoMethod(obj,MUIM_Application_AddInputHandler,struct MUI_InputHandlerNode *ihnode);
  779.  
  780.     FUNCTION
  781.     Up to MUI 2.3, it was not easy to build custom classes which
  782.     should react on signals of private message ports. For example,
  783.     a clock class would want to be notified every second to update
  784.     its display. Old versions of MUI forced you to Wait() for
  785.     a timer signal in the main loop and notify the custom class.
  786.  
  787.     Since MUI 3, the existance of so called "input handlers"
  788.     (don't mix up with input.device input handler) eliminates
  789.     the need of dealing with the main loop in these cases.
  790.     A class can create message ports and react on their
  791.     signals on its own without interferring the main program.
  792.  
  793.     For a clock class, this would mean that you simply create
  794.     the object into any MUI window and it starts updating
  795.     itself every second automatically. A game class could open
  796.     the gameport.device and react on joystick messages, an
  797.     html class could talk to network ports all on its own.
  798.  
  799.     All this helps to further encapsulate your program into
  800.     subclasses and make it a lot more easy to maintain. Let
  801.     me repeat the main loop of an ideal MUI application here:
  802.  
  803.     ULONG sigs = 0;
  804.  
  805.     while (DoMethod(app,MUIM_Application_NewInput,&sigs)
  806.            != MUIV_Application_ReturnID_Quit)
  807.     {
  808.         if (sigs)
  809.         {
  810.             sigs = Wait(sigs | SIGBREAKF_CTRL_C);
  811.             if (sigs & SIGBREAKF_CTRL_C) break;
  812.         }
  813.     }
  814.  
  815.     To be able to react on signals, you must fill out a
  816.     MUI_InputHandlerNode structure (probably located in
  817.     your classes instance data) and call
  818.     MUIM_Application_AddInputHandler with the structure
  819.     as parameter. From now on, your class will receive
  820.     the specified method whenever one of the given signals
  821.     arrives.
  822.  
  823.     Since we're talking about a method of application
  824.     class here, it's clear that you cannot call it until
  825.     you know about your application object. Good places
  826.     for MUIM_Application_AddInputHandler/RemInputHandler
  827.     are probably the MUIM_Setup/MUIM_Cleanup methods
  828.     of your class.
  829.  
  830.     INPUTS
  831.     ihnode - Pointer to an initialized MUI_InputHandlerNode
  832.              structure:
  833.              ihn_Object  - fill in a pointer to your object.
  834.              ihn_Signals - signals you wish to be notified on.
  835.                            You can set more than one bit here.
  836.              ihn_Flags   - always set to 0 for now.
  837.              ihn_Method  - method that you want to receive
  838.                            when one of ihn_Signals is set.
  839.  
  840.     RESULT
  841.     MUIM_Application_AddInputHandler cannot fail, the result
  842.     value of the method is currently undefined.
  843.  
  844.     NOTES
  845.     You must match each AddInputHandler with exatly
  846.     one RemInputHandler method. Do not add a
  847.     MUI_InputHandlerNode which is currently in use.
  848.  
  849.     IMPORTANT: Your trigger method might also be
  850.     called when none of your signals arrived. You *must*
  851.     make sure that you check your conditions in
  852.     the trigger method (if (GetMsg(port) ... or
  853.     if (CheckIO(req)) ...). Also, please make these
  854.     checks quick and return FALSE as fast as possible
  855.     when none of your conditions was met. Return TRUE
  856.     if you have "used" the trigger method.
  857.  
  858.     TIMER
  859.     Since muimaster.library V13, MUIs application class
  860.     implements a builtin timer. By using this one instead
  861.     of creating your own IO requests, you avoid the problem
  862.     of having each instance of your object allocating a
  863.     signal bit.
  864.  
  865.     To make use of this timer, use the above described procedure
  866.     of initializing and adding your MUI_InputHandlerNode structure, 
  867.     but set the MUIIHNF_TIMER in ihn_Flags. Furthermore, specify
  868.     the number of milliseconds after which you want to receive your
  869.     method in ihn_Millis. Note that ihn_Millis is in fact part of a
  870.     union placed at the same memory location as ihn_Signals, do not
  871.     use ihn_Signals when MUIIHNF_TIMER is set.
  872.  
  873.     Besides from MUIIHNF_TIMER and ihn_Millis instead of ihn_Signals,
  874.     using the timer is similiar to other input handlers. Removing
  875.     with MUIM_RemoveInputHandler is not different at all.
  876.  
  877.     EXAMPLE
  878.     OM_NEW:
  879.        data->port = CreateMsgPort();
  880.        data->req = CreateIORequest(data->port,sizeof(struct timer));
  881.        OpenDevice(TIMERNAME,UNIT_VBLANK,(struct IORequest *)data->req,0);
  882.        data->ihnode.ihn_Object  = obj;
  883.        data->ihnode.ihn_Signals = IO_SIGMASK(data->req);
  884.        data->ihnode.ihn_Flags   = 0;
  885.        data->ihnode.ihn_Method  = MY_TRIGGER_METHOD;
  886.  
  887.     OM_DISPOSE:
  888.        CloseDevice((struct IORequest *)data->req);
  889.        DeleteIORequest(data->req);
  890.        DeleteMsgPort(data->port);
  891.  
  892.     MUIM_Setup:
  893.        data->req->tr_node.io_Command = TR_ADDREQUEST;
  894.        data->req->tr_time.tv_secs    = 1;
  895.        data->req->tr_time.tv_micro   = 0;
  896.        SendIO((struct IORequest *)data->req);
  897.        DoMethod(_app(obj),MUIM_Application_AddInputHandler,&data->ihnode);
  898.  
  899.     MUIM_Cleanup:
  900.        DoMethod(_app(obj),MUIM_Application_RemInputHandler,&data->ihnode);
  901.        if (!CheckIO(data->req)) AbortIO(data->req);
  902.        WaitIO(data->req);
  903.  
  904.     MY_TRIGGER_METHOD:
  905.        if (CheckIO(data->req))
  906.        {
  907.           WaitIO(data->req);
  908.  
  909.           /* update display or do anything else here ... */
  910.  
  911.           /* send a new timer event */
  912.           data->req->tr_node.io_Command = TR_ADDREQUEST;
  913.           data->req->tr_time.tv_secs    = 1;
  914.           data->req->tr_time.tv_micro   = 0;
  915.           SendIO((struct IORequest *)data->req);
  916.  
  917.           return(TRUE);
  918.        }
  919.        return(FALSE);
  920.  
  921.     SEE ALSO
  922.     MUIM_Application_RemInputHandler, MUIM_Application_Input
  923. Application.mui/MUIM_Application_CheckRefresh
  924.  
  925.     NAME
  926.     MUIM_Application_CheckRefresh (V11)
  927.  
  928.     SYNOPSIS
  929.     DoMethod(obj,MUIM_Application_CheckRefresh,);
  930.  
  931.     FUNCTION
  932.     This method checks all currently open windows if they
  933.     need refreshing and refreshes them if necessary.
  934.  
  935.     You won't need to call this method if you are within
  936.     your traditional MUI main loop. However, if you e.g.
  937.     spawn some kind of synchronous requester (AslRequest),
  938.     MUI cannot react on IDCMP_REFRESHWINDOW messages.
  939.  
  940.     The result is that the user may see a damaged MUI window
  941.     if he moves around a file requester and MUI is configured
  942.     for simple refresh.
  943.  
  944.     MUIA_Application_CheckRefresh is the solution for this
  945.     problem. Just open your requesters with
  946.  
  947.     ASLFR_UserData    , ApplicationObject,
  948.     ASLFR_IntuiMsgFunc, &IntuiMsgHook,
  949.  
  950.     and let IntuiMsgHook point to something like this:
  951.  
  952.     SAVEDS ASM VOID IntuiMsgFunc(
  953.        _a1 struct IntuiMessage *imsg,
  954.        _a2 struct FileRequester *req)
  955.     {
  956.        if (imsg->Class==IDCMP_REFRESHWINDOW)
  957.           DoMethod(req->fr_UserData,MUIM_Application_CheckRefresh);
  958.     }
  959.  
  960.     RESULT
  961.     Windows with damage will be refreshed. This may result in
  962.     MUI calling MUIM_Draw of some of your custom classes.
  963.     The result value of this method is undefined.
  964.  
  965.     SEE ALSO
  966.     MUIM_Application_InputBuffered
  967. Application.mui/MUIM_Application_GetMenuCheck
  968.  
  969.     NAME
  970.     MUIM_Application_GetMenuCheck (V4 ) (OBSOLETE)
  971.  
  972.     SYNOPSIS
  973.     DoMethod(obj,MUIM_Application_GetMenuCheck,ULONG MenuID);
  974.  
  975.     FUNCTION
  976.     Ask whether a checkmark menu item has its checkmark
  977.     set or cleared.
  978.     The application will ask its sub windows for a
  979.     menu item with the given id and return the state of
  980.     the first item it finds.
  981.  
  982.     INPUTS
  983.     MenuID - the value you wrote into the
  984.                  UserData field of struct NewMenu.
  985.  
  986.     SEE ALSO
  987.     MUIM_Application_SetMenuCheck, MUIA_Application_Menu
  988. Application.mui/MUIM_Application_GetMenuState
  989.  
  990.     NAME
  991.     MUIM_Application_GetMenuState (V4 ) (OBSOLETE)
  992.  
  993.     SYNOPSIS
  994.     DoMethod(obj,MUIM_Application_GetMenuState,ULONG MenuID);
  995.  
  996.     FUNCTION
  997.     Ask whether a menu item is enabled or disabled.
  998.     The application will ask its sub windows for a
  999.     menu item with the given id and return the state of
  1000.     the first item it finds.
  1001.  
  1002.     INPUTS
  1003.     MenuID - the value you wrote into the
  1004.                  UserData field of struct NewMenu.
  1005.  
  1006.     SEE ALSO
  1007.     MUIM_Application_SetMenuState, MUIA_Application_Menu
  1008. Application.mui/MUIM_Application_Input
  1009.  
  1010.     NAME
  1011.     MUIM_Application_Input (V4 ) (OBSOLETE)
  1012.  
  1013.     SYNOPSIS
  1014.     DoMethod(obj,MUIM_Application_Input,LONGBITS *signal);
  1015.  
  1016.     FUNCTION
  1017.     The MUI system itself does not wait for any user input.
  1018.     It just tells your application which signal bits it
  1019.     has allocated, then it's up to you to call MUIs input
  1020.     handle function when one of these signals gets set.
  1021.  
  1022.     In a simple MUI application you would just Wait()
  1023.     for these signals and call MUI when one is received.
  1024.     However, you can perfectly allocate some signal bits
  1025.     yourself and include them in your Wait() command.
  1026.     You needn't even Wait(), your application could
  1027.     maybe calculate some fractal graphics or copy
  1028.     disks, the only important thing is that you call
  1029.     MUI's input method when one of the MUI allocated
  1030.     signals arrives.
  1031.  
  1032.     The usual way of communication with your user
  1033.     interface is via return ids. Every action happening
  1034.     to the GUI can create return ids, e.g. pressing a
  1035.     button or trying to close a window. MUI buffers these
  1036.     ids and uses them as result codes for the input method.
  1037.     Thats where you can get it from and take the appropriate
  1038.     actions.
  1039.  
  1040.     Now lets have a look on a usual input loop of a
  1041.     MUI application. Imagine you have an Play and a
  1042.     Cancel button and have previously told them
  1043.     to return ID_PLAY and ID_CANCEL when pressed.
  1044.     (see MUIM_Notify and MUIM_Application_ReturnID
  1045.     on information about these topics). Your input
  1046.     loop would look like this:
  1047.  
  1048.  
  1049.     while (running)
  1050.     {
  1051.        ULONG signals;
  1052.  
  1053.        switch (DoMethod(app,MUIM_Application_Input,&signals))
  1054.        {
  1055.           case ID_PLAY:
  1056.              PlaySound();
  1057.              break;
  1058.  
  1059.           case ID_CANCEL:
  1060.           case MUIV_Application_ReturnID_Quit:
  1061.              running = FALSE;
  1062.              break;
  1063.        }
  1064.  
  1065.        if (running && signals) Wait(signals);
  1066.     }
  1067.  
  1068.  
  1069.     So what is happening here?
  1070.  
  1071.     First, you have to call the MUIM_Application_Input method.
  1072.     You supply the address of a ULONG as parameter, thats
  1073.     where MUI fills in the signals it needs. Note that you can
  1074.     call the input method at any time, regardless of signal
  1075.     setting. MUI will simply return when there is nothing
  1076.     to do.
  1077.  
  1078.     In case the user pressed the Play or the Cancel button,
  1079.     MUIM_Application_Input will return ID_PLAY or ID_CANCEL.
  1080.     Otherwise you will receive a 0, that's why you cannot
  1081.     use 0 as one of your id values.
  1082.  
  1083.     There is one predefined id called
  1084.     MUIV_Application_ReturnID_Quit. This will be sent to you
  1085.     when someone tried to quit your application from outside,
  1086.     e.g. via commodities exchange or the ARexx "quit" command.
  1087.     It is required that your application handles this id,
  1088.     just treat as if the user clicked on a "Quit" button or
  1089.     selected a "Quit" menu item.
  1090.  
  1091.     After handling the return value, you have to examine
  1092.     if MUI wants you to wait for any signals. If this
  1093.     is the case (signals != 0), just wait for it. If
  1094.     MUI puts a 0 into signals it wants to tell you to
  1095.     immediately call the input method again, maybe some
  1096.     other return ids have received and need to be handled.
  1097.     You *must* check this because Wait()ing on a zero
  1098.     signal mask is not a good idea!
  1099.  
  1100.     Note: It is very important that you call the input method
  1101.     whenever a signal arrives. MUI needs this to correctly
  1102.     refresh its windows, handle resizing and iconification
  1103.     operations and commodities and ARexx messages. If you
  1104.     don't, you will annoy your user!
  1105.  
  1106.     If your program needs to be in a state where you are
  1107.     for some reasons unable to call the input method for
  1108.     a considerable amount of time (maybe half a second or
  1109.     more), you should put your application to sleep. See
  1110.     MUIA_Application_Sleep on how to do this.
  1111.  
  1112.     SEE ALSO
  1113.     MUIA_Application_Sleep, MUIM_Application_InputBuffered,
  1114.     MUIM_Application_NewInput
  1115. Application.mui/MUIM_Application_InputBuffered
  1116.  
  1117.     NAME
  1118.     MUIM_Application_InputBuffered (V4 )
  1119.  
  1120.     SYNOPSIS
  1121.     DoMethod(obj,MUIM_Application_InputBuffered,);
  1122.  
  1123.     FUNCTION
  1124.     Imagine your application does some time consuming
  1125.     operation, e.g. copying a disk, and you are for
  1126.     some reasons unable to react on return ids during
  1127.     this period. One solution would be to simply
  1128.     put your application to sleep, it will get a
  1129.     busy pointer and the user knows whats going on.
  1130.  
  1131.     However, this will make it impossible for the user
  1132.     to resize your applications windows or iconify it,
  1133.     he will have to wait until you are done with your
  1134.     operation.
  1135.  
  1136.     MUIM_Application_InputBuffered offers a solution
  1137.     for this problem. Using this method, you needn't
  1138.     set to sleep your application. Just call it on a
  1139.     regular basis and MUI will be able to handle
  1140.     all actions concerning the GUI. You do not need
  1141.     to pay attention on return values, they remain
  1142.     on an internal stack until your next call to
  1143.     the non buffered input method.
  1144.  
  1145.     EXAMPLE
  1146.     for (track=0; track<80; track++)
  1147.     {
  1148.        read_track();
  1149.        DoMethod(app,MUIM_Application_InputBuffered);
  1150.        write_track();
  1151.        DoMethod(app,MUIM_Application_InputBuffered);
  1152.     }
  1153.  
  1154.     SEE ALSO
  1155.     MUIM_Application_Input, MUIA_Application_Sleep
  1156. Application.mui/MUIM_Application_Load
  1157.  
  1158.     NAME
  1159.     MUIM_Application_Load (V4 )
  1160.  
  1161.     SYNOPSIS
  1162.     DoMethod(obj,MUIM_Application_Load,STRPTR name);
  1163.  
  1164.     FUNCTION
  1165.     MUIM_Application_Save, MUIM_Application_Load and
  1166.     MUIA_ObjectID offer an easy way of saving and loading
  1167.     a programs configuration.
  1168.  
  1169.     Each gadget with a non NULL MUIA_ObjectID will get
  1170.     its contents saved during MUIM_Application_Save and
  1171.     restored during MUIM_Application_Load. This makes
  1172.     it very easy to design a configuration window
  1173.     with "Save", "Use" and "Cancel" buttons to allow
  1174.     the user storing the settings. When the application
  1175.     starts, you would just have to call MUIM_Application_Load
  1176.     and the stored settings will be read and installed.
  1177.  
  1178.     Not all classes are able to import and export their
  1179.     contents. Currently, you may define MUIA_ObjectIDs for
  1180.  
  1181.     String class   - MUIA_String_Contents is ex/imported.
  1182.     Radio class    - MUIA_Radio_Active is ex/imported.
  1183.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  1184.     List class     - MUIA_List_Active is /ex/imported.
  1185.     Text class     - MUIA_Text_Contents is ex/imported.
  1186.     Slider class   - MUIA_Slider_Level is ex/imported.
  1187.     Area class     - MUIA_Selected is ex/imported
  1188.                      (e.g. for Checkmark gadgets)
  1189.    Menuitem class - MUIA_Checked is ex/imported (V9).
  1190.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  1191.  
  1192.     INPUTS
  1193.     name - Name of the file you wish to load the settings from.
  1194.            Usually you won't need to think of a real name but
  1195.            instead use one of the magic cookies
  1196.            MUIV_Application_Load_ENV or
  1197.            MUIV_Application_Load_ENVARC.
  1198.  
  1199.     EXAMPLE
  1200.     see the sample program "Settings.c"
  1201.  
  1202.     SEE ALSO
  1203.     MUIM_Application_Save, notify.mui/MUIA_ObjectID
  1204. Application.mui/MUIM_Application_NewInput
  1205.  
  1206.     NAME
  1207.     MUIM_Application_NewInput (V11)
  1208.  
  1209.     SYNOPSIS
  1210.     DoMethod(obj,MUIM_Application_NewInput,LONGBITS *signal);
  1211.  
  1212.     FUNCTION
  1213.     This is an enhanced replacement for MUIM_Application_Input.
  1214.     It depends on receiving the return value from your Wait()
  1215.     or 0 as input to be able to perform the necessary actions
  1216.     more efficient.
  1217.  
  1218.     MUIM_Application_NewInput is generally preferrable over
  1219.     MUIM_Application_Input.
  1220.  
  1221.     EXAMPLE
  1222.     /*
  1223.     ** This is the ideal input loop for an object oriented MUI
  1224.     ** application. Everything is encapsulated in classes, no
  1225.     ** return ids need to be used, we just check if the program
  1226.     ** shall terminate.
  1227.     ** Note that MUIM_Application_NewInput expects sigs to
  1228.     ** contain the result from Wait() (or 0). This makes the
  1229.     ** input loop significantly faster.
  1230.     */
  1231.  
  1232.     {
  1233.        ULONG sigs = 0;
  1234.  
  1235.        while (DoMethod(app,MUIM_Application_NewInput,&sigs)
  1236.               !=MUIV_Application_ReturnID_Quit)
  1237.        {
  1238.           if (sigs)
  1239.           {
  1240.              sigs = Wait(sigs | SIGBREAKF_CTRL_C);
  1241.              if (sigs & SIGBREAKF_CTRL_C) break;
  1242.           }
  1243.        }
  1244.     }
  1245.  
  1246.     SEE ALSO
  1247.     MUIM_Application_Input
  1248.  
  1249. Application.mui/MUIM_Application_OpenConfigWindow
  1250.  
  1251.     NAME
  1252.     MUIM_Application_OpenConfigWindow (V11)
  1253.  
  1254.     SYNOPSIS
  1255.     DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags);
  1256.  
  1257.     FUNCTION
  1258.     Since MUI 3, applications can open their own MUI configuration
  1259.     window to allow users to adjust the local preferences without
  1260.     the need of an external program. Programmers are supposed to
  1261.     include a "Settings/MUI..." menu item which simply calls
  1262.     MUIM_Application_OpenConfigWindow. MUI will then automatically
  1263.     show the preferences window without blocking the rest of the
  1264.     program.
  1265.  
  1266.     Currently no flags are defined; pass 0 for the time being.
  1267. Application.mui/MUIM_Application_PushMethod
  1268.  
  1269.     NAME
  1270.     MUIM_Application_PushMethod (V4 )
  1271.  
  1272.     SYNOPSIS
  1273.     DoMethod(obj,MUIM_Application_PushMethod,Object *dest, LONG count, /* ... */);
  1274.  
  1275.     FUNCTION
  1276.     Usually, you may not talk to the MUI system from two
  1277.     tasks at the same time. MUIM_Application_PushMethod
  1278.     provides some kind of solution for this problem.
  1279.  
  1280.     This (and only this) method may be called from a
  1281.     second task. It takes another method as parameter
  1282.     and puts in onto a private stack of the application
  1283.     object. The next time MUIM_Application_Input
  1284.     is called, the pushed method will be executed
  1285.     in the context of the current task.
  1286.  
  1287.     INPUTS
  1288.     dest  - object on which to perform the pushed method.
  1289.         count - number of following arguments.
  1290.     ...   - the destination method.
  1291.  
  1292.     RESULT
  1293.     TRUE if successful, FALSE otherwise.
  1294.  
  1295.     EXAMPLE
  1296.     /* set a status line from a sub task */
  1297.     DoMethod(app,MUIM_Application_PushMethod,
  1298.        txstatus,3,MUIM_Set,MUIA_Text_Contents,"reading...");
  1299.  
  1300.     NOTE
  1301.     MUIM_Application_PushMethod has a limit of 7 arguments!
  1302.  
  1303.     SEE ALSO
  1304.     MUIM_Application_Input
  1305. Application.mui/MUIM_Application_RemInputHandler
  1306.  
  1307.     NAME
  1308.     MUIM_Application_RemInputHandler (V11)
  1309.  
  1310.     SYNOPSIS
  1311.     DoMethod(obj,MUIM_Application_RemInputHandler,struct MUI_InputHandlerNode *ihnode);
  1312.  
  1313.     FUNCTION
  1314.     Remove an input handler.
  1315.     MUI will no longer call your trigger method after you have
  1316.     removed the MUI_InputHandlerNode. You can add/remove
  1317.     input handler nodes any time as long as you know
  1318.     about your application object.
  1319.  
  1320.     RESULT
  1321.     MUIM_Application_RemInputHandler cannot fail, the result
  1322.     value of the method is currently undefined.
  1323.  
  1324.     INPUTS
  1325.     ihnode - input handler node structure you passed to
  1326.              MUIM_AddInputHandler previously.
  1327.  
  1328.     SEE ALSO
  1329.     MUIM_Application_AddInputHandler, MUIM_Application_Input
  1330. Application.mui/MUIM_Application_ReturnID
  1331.  
  1332.     NAME
  1333.     MUIM_Application_ReturnID (V4 )
  1334.  
  1335.     SYNOPSIS
  1336.     DoMethod(obj,MUIM_Application_ReturnID,ULONG retid);
  1337.  
  1338.     FUNCTION
  1339.     Tell MUI to return the given id with the next call to 
  1340.     MUIM_Application_Input.
  1341.  
  1342.     Together with the MUI's notification mechanism, this
  1343.     method connects your user interface and your program.
  1344.     If you e.g. want to be informed if the user presses
  1345.     a "Play" button, you would have define an id for
  1346.     this action and set up a notification event with
  1347.     MUIM_Notify.
  1348.  
  1349.     You can use any long word as return id, except
  1350.     from -255 up to 0. These values are reserved for
  1351.     MUI's internal use and for special return values
  1352.     like MUIV_Application_ReturnID_Quit.
  1353.  
  1354.     Note that MUI will put all incoming return ids
  1355.     onto a private fifo stack and feed this stack
  1356.     to its input methods result code later.
  1357.  
  1358.     NOTE
  1359.     The usage of ReturnIDs is no good MUI programming style.
  1360.     You should build your application with sub classes and
  1361.     hooks instead! See the PublicScreenManager source code
  1362.     for an example of good MUI programming!
  1363.  
  1364.     EXAMPLE
  1365.  
  1366.     /* inform me if a button is pressed (actually released, */
  1367.     /* since this is the way amiga buttons are handled)     */
  1368.  
  1369.     #define ID_PLAYBUTTON 42
  1370.  
  1371.     ...
  1372.  
  1373.     DoMethod(buttonobj, MUIM_Notify,
  1374.        MUIA_Pressed, FALSE,
  1375.        appobj, 2, MUIM_Application_ReturnID, ID_PLAYBUTTON);
  1376.  
  1377.     ...
  1378.  
  1379.     while (running)
  1380.     {
  1381.        switch (DoMethod(appobj,MUIM_Application_Input,&sigs))
  1382.        {
  1383.           case ID_PLAYBUTTON:
  1384.              printf("Ok, lets play a game...");
  1385.              break;
  1386.        }
  1387.     }
  1388.  
  1389.     SEE ALSO
  1390.     MUIM_Application_Input, MUIM_Notify
  1391. Application.mui/MUIM_Application_Save
  1392.  
  1393.     NAME
  1394.     MUIM_Application_Save (V4 )
  1395.  
  1396.     SYNOPSIS
  1397.     DoMethod(obj,MUIM_Application_Save,STRPTR name);
  1398.  
  1399.     FUNCTION
  1400.     MUIM_Application_Save, MUIM_Application_Load and
  1401.     MUIA_ObjectID offer an easy way of saving and loading
  1402.     a programs configuration.
  1403.  
  1404.     Each gadget with a non NULL MUIA_ObjectID will get
  1405.     its contents saved during MUIM_Application_Save and
  1406.     restored during MUIM_Application_Load. This makes
  1407.     it very easy to design a configuration window
  1408.     with "Save", "Use" and "Cancel" buttons to allow
  1409.     the user storing the settings. When the application
  1410.     starts, you would just have to call MUIM_Application_Load
  1411.     and the stored settings will be read and installed.
  1412.  
  1413.     Not all classes are able to import and export their
  1414.     contents. Currently, you may define MUIA_ObjectIDs for
  1415.  
  1416.     String class   - MUIA_String_Contents is ex/imported.
  1417.     Radio class    - MUIA_Radio_Active is ex/imported.
  1418.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  1419.     List class     - MUIA_List_Active is /ex/imported.
  1420.     Text class     - MUIA_Text_Contents is ex/imported.
  1421.     Slider class   - MUIA_Slider_Level is ex/imported.
  1422.     Area class     - MUIA_Selected is ex/imported
  1423.                      (e.g. for Checkmark gadgets)
  1424.    Menuitem class - MUIA_Checked is ex/imported (V9).
  1425.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  1426.  
  1427.     INPUTS
  1428.     name - Name of the file you wish to save the settings to.
  1429.            Usually you won't need to think of a real name but
  1430.            instead use one of the magic cookies
  1431.            MUIV_Application_Save_ENV or
  1432.            MUIV_Application_Save_ENVARC.
  1433.            This will save your application's settings somewhere
  1434.            in env:mui/ or envarc:mui/, you needn't worry about
  1435.            it.
  1436.  
  1437.     EXAMPLE
  1438.     see the sample program "Settings.c"
  1439.  
  1440.     SEE ALSO
  1441.     MUIM_Application_Load, Notify.mui/MUIA_ObjectID
  1442. Application.mui/MUIM_Application_SetConfigItem
  1443.  
  1444.     NAME
  1445.     MUIM_Application_SetConfigItem (V11)
  1446.  
  1447.     SYNOPSIS
  1448.     DoMethod(obj,MUIM_Application_SetConfigItem,ULONG item, APTR data);
  1449.  
  1450.     FUNCTION
  1451.     Private method, only for PSI.
  1452. Application.mui/MUIM_Application_SetMenuCheck
  1453.  
  1454.     NAME
  1455.     MUIM_Application_SetMenuCheck (V4 ) (OBSOLETE)
  1456.  
  1457.     SYNOPSIS
  1458.     DoMethod(obj,MUIM_Application_SetMenuCheck,ULONG MenuID, LONG stat);
  1459.  
  1460.     FUNCTION
  1461.     Set or clear the checkmark of a menu item.
  1462.     The application will ask its sub windows for menu items
  1463.     with the given id and set/clear all found
  1464.     entries.
  1465.  
  1466.     INPUTS
  1467.     MenuID - the value you wrote into the
  1468.                  UserData field of struct NewMenu.
  1469.  
  1470.     set    - TRUE to set checkmark, FALSE to clear
  1471.  
  1472.     SEE ALSO
  1473.     MUIM_Application_GetMenuCheck, MUIA_Application_Menu,
  1474. Application.mui/MUIM_Application_SetMenuState
  1475.  
  1476.     NAME
  1477.     MUIM_Application_SetMenuState (V4 ) (OBSOLETE)
  1478.  
  1479.     SYNOPSIS
  1480.     DoMethod(obj,MUIM_Application_SetMenuState,ULONG MenuID, LONG stat);
  1481.  
  1482.     FUNCTION
  1483.     Enable or disable a menu item.
  1484.     The application will ask its sub windows for menu items
  1485.     with the given id and enable/disable all found
  1486.     entries.
  1487.  
  1488.     INPUTS
  1489.     MenuID - the value you wrote into the
  1490.                  UserData field of struct NewMenu.
  1491.  
  1492.     set    - TRUE to enable item, FALSE to disable.
  1493.  
  1494.     SEE ALSO
  1495.     MUIM_Application_GetMenuState, MUIA_Application_Menu,
  1496. Application.mui/MUIM_Application_ShowHelp
  1497.  
  1498.     NAME
  1499.     MUIM_Application_ShowHelp (V4 )
  1500.  
  1501.     SYNOPSIS
  1502.     DoMethod(obj,MUIM_Application_ShowHelp,Object *window, char *name, char *node, LONG line);
  1503.  
  1504.     FUNCTION
  1505.     Show an AmigaGuide help file. The application will be
  1506.     put to sleep until the file is displayed.
  1507.  
  1508.     Usually, you don't need to call this method directly.
  1509.     MUI comes with a sophisticated online help system,
  1510.     you just need to supply your gadgets with help nodes
  1511.     and everything will be handled automatically.
  1512.  
  1513.     INPUTS
  1514.     window - (Object *) - Help will appear on this windows
  1515.                           screen. May be NULL.
  1516.     name   - (char *)   - name of the help file
  1517.     node   - (char *)   - name of a node in this help file
  1518.     line   - (char *)   - line number
  1519.  
  1520.     SEE ALSO
  1521.     MUIA_HelpFile, MUIA_HelpNode, MUIA_HelpLine
  1522.