home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / mui-2.1.lha / MUI-2.1 / Developer / Autodocs / MUI_Popstring.doc < prev    next >
Encoding:
Text File  |  1994-07-04  |  5.9 KB  |  182 lines
  1. TABLE OF CONTENTS
  2.  
  3. Popstring.mui/Popstring.mui
  4. Popstring.mui/MUIM_Popstring_Close
  5. Popstring.mui/MUIM_Popstring_Open
  6. Popstring.mui/MUIA_Popstring_Button
  7. Popstring.mui/MUIA_Popstring_CloseHook
  8. Popstring.mui/MUIA_Popstring_OpenHook
  9. Popstring.mui/MUIA_Popstring_String
  10. Popstring.mui/MUIA_Popstring_Toggle
  11. Popstring.mui/Popstring.mui
  12.  
  13.     Popstring class is the base class for creating so called
  14.     popup objects. Usually, a popup consists of a string or
  15.     text gadget, followed by a little button. Pressing this
  16.     button brings up a little window with a listview and lets
  17.     the user choose an entry with the mouse.
  18.  
  19.     Popstring class features the basic functions for creating
  20.     such objects. Given a string object and a button object,
  21.     it places them horizontally and sets up some notification.
  22.     Whenever the popup button is pressed, a hook will be called 
  23.     which itself should open and prepare the popup window.
  24.  
  25.     The string and the button object are not created by popstring
  26.     class, they have to be supplied as attributes during object
  27.     creation time. This makes popstring class very flexible,
  28.     one could e.g. use a text object instead of a string or
  29.     a popup button with some text in it.
  30.  
  31.     However, creating simple popups with popstring class would
  32.     be too much overhead. Instead of using it directly, you
  33.     should have a look at one of its subclasses. They offer
  34.     a more specialized set of popups and are a lot easier
  35.     to use.
  36. Popstring.mui/MUIM_Popstring_Close
  37.  
  38.     NAME
  39.     MUIM_Popstring_Close (V7)
  40.  
  41.     SYNOPSIS
  42.     DoMethod(obj,MUIM_Popstring_Close,LONG result);
  43.  
  44.     FUNCTION
  45.     This method closes the popup. In fact, it only calls the
  46.     predefined MUIA_Popstring_CloseHook with the supplied
  47.     success parameter.
  48.  
  49.     EXAMPLE
  50.     DoMethod(poplist,MUIM_Notify,MUIA_Listview_DoubeClick,TRUE,
  51.        popobj,2,MUIM_Popstring_Close,TRUE);
  52. Popstring.mui/MUIM_Popstring_Open
  53.  
  54.     NAME
  55.     MUIM_Popstring_Open (V7)
  56.  
  57.     SYNOPSIS
  58.     DoMethod(obj,MUIM_Popstring_Open,);
  59.  
  60.     FUNCTION
  61.     This method opens the popup. In fact, it only calls the
  62.     predefined MUIA_Popstring_OpenHook and checks its return
  63.     value. In case of TRUE, the popup button object is disabled
  64.     as long as MUIA_Popstring_Toggle is unset.
  65.  
  66.     If the toggle mode is enabled, using MUIA_Popstring_Open on
  67.     a currently opened popup will result in closing this popup
  68.     (i.e. calling the close hook) with a success value of FALSE.
  69.  
  70.     EXAMPLE
  71.     DoMethod(popbutton,MUIM_Notify,MUIA_Pressed,FALSE,
  72.        popobj,1,MUIM_Popstring_Open);
  73. Popstring.mui/MUIA_Popstring_Button
  74.  
  75.     NAME
  76.     MUIA_Popstring_Button -- (V7) [I.G], Object *
  77.  
  78.     FUNCTION
  79.     Specify the button object to be used in the popup. Depending
  80.     on the type of your popup, you should use an image button
  81.     with MUII_PopUp, MUII_PopFile or MUII_PopDrawer here.
  82.     However, its also possible to have a button with some
  83.     text or other things in it.
  84.  
  85.     When the popstring object is disposed, the string
  86.     and the button objects are disposed as well.
  87.  
  88.     EXAMPLE
  89.     pop = PopstringObject,
  90.        MUIA_Popstring_String, KeyString(0,60,'n'),
  91.        MUIA_Popstring_Button, PopButton(MUII_PopUp),
  92.        MUIA_Popstring_OpenHook, &OpenHook,
  93.        MUIA_Popstring_CloseHook, &CloseHook,
  94.        End;
  95.  
  96.     SEE ALSO
  97.     MUIA_Popstring_String, MUIA_Popstring_OpenHook, MUIA_Popstring_CloseHook
  98. Popstring.mui/MUIA_Popstring_CloseHook
  99.  
  100.     NAME
  101.     MUIA_Popstring_CloseHook -- (V7) [ISG], struct Hook *
  102.  
  103.     FUNCTION
  104.     Whenever the popup receives a MUIM_Popstring_Close method and
  105.     the popup is currently opened, this hook will be called. 
  106.     It will receive a pointer to itself in register A0, a pointer
  107.     to the complete popup object in A2 and a pointer to a
  108.     struct
  109.     {
  110.        Object *stringobject;
  111.        LONG success;
  112.     },
  113.     in A1. The success parameter is a copy of the methods success
  114.     parameter and indicates whether the popup was closed successfully
  115.     (e.g. with a double click in a listview) or was just cancelled
  116.     (e.g. by pressing the popup button again for toggle popups).
  117.  
  118.     Due to internal message handling issues, calling the close hook is
  119.     delayed until the next MUIM_HandleInput method is called. This
  120.     allows you to remove and dispose windows without danger.
  121.  
  122.     SEE ALSO
  123.     MUIA_Popstring_OpenHook, MUIM_Popstring_Open, MUIM_Popstring_Close
  124. Popstring.mui/MUIA_Popstring_OpenHook
  125.  
  126.     NAME
  127.     MUIA_Popstring_OpenHook -- (V7) [ISG], struct Hook *
  128.  
  129.     FUNCTION
  130.     Whenever the popup receives a MUIM_Popstring_Open method,
  131.     this hook will be called. It will receive a pointer to itself in
  132.     register A0, a pointer to the complete popup object in A2 and
  133.     a pointer to a pointer (!) to the string object contained in
  134.     the popup object in A1.
  135.  
  136.     When this hook returns TRUE, MUI assumes the popup was opened
  137.     succesfully and will disabled the popup button (as long as
  138.     MUIA_Popstring_Toggle is not set). Return FALSE to indicate
  139.     that something went wrong and the popup could not be opened.
  140.  
  141.     SEE ALSO
  142.     MUIA_Popstring_CloseHook, MUIM_Popstring_Open, MUIM_Popstring_Close
  143. Popstring.mui/MUIA_Popstring_String
  144.  
  145.     NAME
  146.     MUIA_Popstring_String -- (V7) [I.G], Object *
  147.  
  148.     FUNCTION
  149.     Specify the string object to be used in the popup.
  150.     This does not necessarily need to be a real string
  151.     object, using text objects or even complete groups
  152.     of other objects is perfectly ok.
  153.  
  154.     When the popstring object is disposed, the string
  155.     and the button objects are disposed as well.
  156.  
  157.     EXAMPLE
  158.     pop = PopstringObject,
  159.        MUIA_Popstring_String, KeyString(0,60,'n'),
  160.        MUIA_Popstring_Button, PopButton(MUII_PopUp),
  161.        MUIA_Popstring_OpenHook, &OpenHook,
  162.        MUIA_Popstring_CloseHook, &CloseHook,
  163.        End;
  164.  
  165.     SEE ALSO
  166.     MUIA_Popstring_Button, MUIA_Popstring_OpenHook, MUIA_Popstring_CloseHook
  167. Popstring.mui/MUIA_Popstring_Toggle
  168.  
  169.     NAME
  170.     MUIA_Popstring_Toggle -- (V7) [ISG], BOOL
  171.  
  172.     FUNCTION
  173.     Set/Clear the toggle mode for a popstring object.
  174.     With toggling disabled, the popup button will get
  175.     disabled whenever the user hits it and the popup
  176.     opens. With toggling enabled, the popup button
  177.     always stays enabled and can be used to cancel
  178.     (== close with a FALSE return value) the popup.
  179.  
  180.     SEE ALSO
  181.     MUIM_Popstring_OpenHook
  182.