home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 18 / amigaformatcd18.iso / mui / mui_developer / autodocs / mui_popasl.doc < prev    next >
Text File  |  1997-03-10  |  5KB  |  152 lines
  1. TABLE OF CONTENTS
  2.  
  3. Popasl.mui/Popasl.mui
  4. Popasl.mui/MUIA_Popasl_Active
  5. Popasl.mui/MUIA_Popasl_StartHook
  6. Popasl.mui/MUIA_Popasl_StopHook
  7. Popasl.mui/MUIA_Popasl_Type
  8. Popasl.mui/Popasl.mui
  9.  
  10.     As a subclass of popstring class, popasl can be used to pop up
  11.     any kinds of standard system asl requesters. A seperate task is
  12.     spawned to handle these requesters, the application continues to
  13.     run.
  14.  
  15.     Using an asl popup class, you don't need to worry about handling
  16.     asl requesters. MUI will automatically open one when the popup
  17.     button is pressed and update the corresponding string gadget
  18.         when the user terminates the requester. From the programmers
  19.     point of view, all you have to do is to handle the string
  20.     gadgets contents.
  21.  
  22.     IMPORTANT: At object creation time, you can use all ASL library 
  23.     tags as well. They will be passed to the AllocAslRequest() call 
  24.     without further interpretation.
  25. Popasl.mui/MUIA_Popasl_Active
  26.  
  27.     NAME
  28.     MUIA_Popasl_Active -- (V7 ) [..G], BOOL
  29.  
  30.     FUNCTION
  31.     Popasl creates asynchronous popups. Requesters are opened in a
  32.     seperately spawned task and don't disturb the rest of the
  33.     application. You can ask for the state of a requester by
  34.     querying the MUIA_Popasl_Active attribute. It will return
  35.     TRUE when the requester is currently open, FALSE otherwise.
  36.  
  37.     Common use for this attribute is to prevent an application
  38.     from being terminated while a requester is open. If you
  39.     try to dispose the popasl object with a currently open
  40.     requester, MUI will freeze your task as long as the requester
  41.     stays there.
  42.  
  43.     EXAMPLE
  44.     case MUIV_Application_ReturnID_Quit:
  45.     {
  46.        LONG active;
  47.  
  48.        get(pop1,MUIA_Popasl_Active,&active);
  49.        if (!active) get(pop2,MUIA_Popasl_Active,&active);
  50.        if (!active) get(pop3,MUIA_Popasl_Active,&active);
  51.        if (!active) get(pop4,MUIA_Popasl_Active,&active);
  52.  
  53.        if (active)
  54.           MUI_Request(app,window,0,NULL,"OK",
  55.                       "Cannot quit now, still some asl popups opened.");
  56.        else
  57.           running = FALSE;
  58.     }
  59.     break;
  60.  
  61.    SEE ALSO
  62.     MUIA_Popasl_StartHook, MUIA_Popasl_StopHook, MUIA_Popasl_Type
  63. Popasl.mui/MUIA_Popasl_StartHook
  64.  
  65.     NAME
  66.     MUIA_Popasl_StartHook -- (V7 ) [ISG], struct Hook *
  67.  
  68.     FUNCTION
  69.     Before popasl class opens the asl requester, it has to
  70.     get some kind of parameters describing its initial contents.
  71.     A file popup would e.g. need to split the string gadgets
  72.     contents into path and file name part and pass these
  73.     as ASLFR_InititalFile and ASLFR_InitialDrawer to the
  74.     requester.
  75.  
  76.     The MUIA_Popasl_StartHook tag describes a hook function
  77.     that will be called immediately before the requester is
  78.     opened. It will receive a pointer to itself in A0,
  79.     a pointer to the popasl object in A2 and a pointer to
  80.     a taglist in A1. This taglist already contains some
  81.     tags:
  82.  
  83.     ASLFR/FO/..._Screen          : parent screen
  84.     ASLFR/FO/..._PrivateIDCMP    : TRUE
  85.     ASLFR/FO/..._InititalLeftEdge: left edge of popasl object
  86.     ASLFR/FO/..._InititalTopEdge : bottom edge of popasl object
  87.     ASLFR/FO/..._InititalWidth   : width of popasl object, only
  88.                                    present when the popup is called
  89.                                    for the first time.
  90.  
  91.     You may add other tags to the list, but beware that the
  92.     maximum allowed number of tags is 15. If you need more,
  93.     use the TAG_MORE tag.
  94.  
  95.     Since the asl requester will run in a seperate task, you should
  96.     not change the state of the ASLFR_PrivateIDCMP tag!
  97.  
  98.     If your hook returns TRUE, popasl class opens the requester
  99.     with the given taglist. A return value of FALSE should be
  100.     used when something went wrong, no requester will be opened
  101.     in this case.
  102.  
  103.     For file and font requester, popasl class will fall back to a
  104.     default tag handling when no start hook is specified. A file
  105.     name is automatically split into path and file part and passed
  106.     to the requester a ASLFR_InitialFile and ASLFR_InitialDrawer.
  107.     A font requester splits a string like "topaz/8" into 
  108.     font name and size for ASLFO_InitialName and ASLFO_InitialSize.
  109.  
  110.    SEE ALSO
  111.     MUIA_Popasl_StopHook, MUIA_Popasl_Type
  112. Popasl.mui/MUIA_Popasl_StopHook
  113.  
  114.     NAME
  115.     MUIA_Popasl_StopHook -- (V7 ) [ISG], struct Hook *
  116.  
  117.     FUNCTION
  118.     When the requester terminates, MUIA_Popasl_StopHook will be
  119.     called with a pointer to itself in A0, a pointer to the
  120.     popasl object in A2 and a pointer to the asl requester
  121.     structure in A1. The hook can then parse the requester 
  122.     structure and set the string gadgets contents respectively.
  123.  
  124.     For file and font requesters, a default handling is provided.
  125.  
  126.     SEE ALSO
  127.     MUIA_Popasl_StartHook, MUIA_Popasl_Type
  128. Popasl.mui/MUIA_Popasl_Type
  129.  
  130.     NAME
  131.     MUIA_Popasl_Type -- (V7 ) [I.G], ULONG
  132.  
  133.     FUNCTION
  134.     This tag allows to set the type of asl requester. Pass
  135.     the same value you would use for AllocAslRequest(), e.g.
  136.     ASL_FileRequest, ASL_FontRequest or ASL_ScreenModeRequest.
  137.  
  138.     For ASL_FileRequest and ASL_FontRequest, popasl class offers a
  139.     a standard start/stop handling. When a file requester is opened,
  140.     MUI splits the string gadgets contents into a path and a file
  141.     name and uses these as initial paremeters for the requester.
  142.     Font popups translate a font into a name/size pair, e.g.
  143.     "topaz/8". You can override these translations by specifying
  144.     a MUIA_Popasl_StartHook and a MUIA_Popasl_StopHook.
  145.  
  146.     For ASL_ScreenModeRequest, no standard handling is available.
  147.     Using such a popup without Start and Stop hooks won't make
  148.     much sense.
  149.  
  150.     SEE ALSO
  151.     MUIA_Popasl_StartHook, MUIA_Popasl_StopHook
  152.