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_Boopsi.doc < prev    next >
Text File  |  1994-07-03  |  11KB  |  384 lines
  1. TABLE OF CONTENTS
  2.  
  3. Boopsi.mui/Boopsi.mui
  4. Boopsi.mui/MUIA_Boopsi_Class
  5. Boopsi.mui/MUIA_Boopsi_ClassID
  6. Boopsi.mui/MUIA_Boopsi_MaxHeight
  7. Boopsi.mui/MUIA_Boopsi_MaxWidth
  8. Boopsi.mui/MUIA_Boopsi_MinHeight
  9. Boopsi.mui/MUIA_Boopsi_MinWidth
  10. Boopsi.mui/MUIA_Boopsi_Object
  11. Boopsi.mui/MUIA_Boopsi_Remember
  12. Boopsi.mui/MUIA_Boopsi_TagDrawInfo
  13. Boopsi.mui/MUIA_Boopsi_TagScreen
  14. Boopsi.mui/MUIA_Boopsi_TagWindow
  15. Boopsi.mui/Boopsi.mui
  16.  
  17.     MUI's boopsi class provides an interface to standard,
  18.     system style boopsi gadgets. Since boopsis gadgetclass
  19.     misses some important features needed for an automatic
  20.     layout system like MUI, there are several problems with
  21.     such an interface. MUI tries to solve these problems
  22.     with some additional attributes.
  23.  
  24.     Coming with release 3.x of the amiga operating system are
  25.     some very nice boopsi gadgets such as "colorwheel.gadget"
  26.     or "gradientslider.gadget". With MUI's boopsi class, you
  27.     can use these gadgets just as if they were MUI objects.
  28.  
  29.     You can talk to a MUIized boopsi object as if it was the
  30.     boopsi object itself. MUI will pass through all attributes
  31.     and try to be completely transparent. Additionally, if
  32.     a boopsi object generates notification events via
  33.     IDCMP_UPDATE, MUI turns them into MUI notification events.
  34.     Thus, you can e.g. react on the change of WHEEL_Saturation
  35.     in a MUI colorwheel boopsi gadget as on any other MUI
  36.     attribute.
  37.  
  38.     An example program "BoopsiDoor.c" is provided to show
  39.     how this magic works.
  40.  
  41.    Note: OS 3.0/3.1 colorwheel.gadget can accidently render itself
  42.          one pixel too big, overwriting other parts of the window.
  43.          As a workaround, MUI will subtract one from the width/height
  44.          before passing it on to a colorwheel boopsi object.
  45. Boopsi.mui/MUIA_Boopsi_Class
  46.  
  47.     NAME
  48.     MUIA_Boopsi_Class -- (V4) [ISG], struct IClass *
  49.  
  50.     FUNCTION
  51.     Pointer to the (private) class you want to create a boopsi
  52.     object from. Only useful if you previously generated your
  53.     own boopsi class with MakeClass().
  54.  
  55.     Of course you may not free the class until you're done
  56.     with your object.
  57.  
  58.     SEE ALSO
  59.     MUIA_Boopsi_ClassID
  60. Boopsi.mui/MUIA_Boopsi_ClassID
  61.  
  62.     NAME
  63.     MUIA_Boopsi_ClassID -- (V4) [ISG], char *
  64.  
  65.     FUNCTION
  66.     MUIA_Boopsi_ClassID specifies the name for the public
  67.     Boopsi class you want to create an object of. It will
  68.     only be used when MUIA_Boopsi_Class is NULL.
  69.  
  70.     The public class must be in memory before you can create
  71.     an instance of it, you will have to open the required class
  72.     library by hand.
  73.  
  74.     Note the string given to MUIA_Boopsi_ClassID must remain
  75.     valid until you're done with the object.
  76.  
  77.     EXAMPLE
  78.  
  79.     /* Complete example code can be found in BoopsiDoor.c */
  80.  
  81.     cwbase = OpenLibrary("gadgets/colorwheel.gadget",0);
  82.  
  83.     Wheel = BoopsiObject,  /* MUI and Boopsi tags mixed */
  84.      NeXTFrame,
  85.      MUIA_Boopsi_ClassID  , "colorwheel.gadget",
  86.      MUIA_Boopsi_MinWidth , 30, /* boopsi objects don't know */
  87.      MUIA_Boopsi_MinHeight, 30, /* their sizes, so we help   */
  88.       MUIA_Boopsi_Remember , WHEEL_Saturation, /* keep important values */
  89.      MUIA_Boopsi_Remember , WHEEL_Hue,        /* during window resize  */
  90.      MUIA_Boopsi_TagScreen, WHEEL_Screen, /* this magic fills in */
  91.      WHEEL_Screen         , NULL,         /* the screen pointer  */
  92.      GA_Left     , 0,
  93.      GA_Top      , 0, /* MUI will automatically     */
  94.      GA_Width    , 0, /* fill in the correct values */
  95.      GA_Height   , 0,
  96.      ICA_TARGET  , ICTARGET_IDCMP, /* needed for notification */
  97.      End;
  98.  
  99.     ...
  100.  
  101.     MUI_DisposeObject(wheel);
  102.     CloseLibrary(cwbase);
  103.  
  104.     SEE ALSO
  105.     MUIA_Boopsi_Class
  106. Boopsi.mui/MUIA_Boopsi_MaxHeight
  107.  
  108.     NAME
  109.     MUIA_Boopsi_MaxHeight -- (V4) [ISG], ULONG
  110.  
  111.     FUNCTION
  112.     For MUI's automatic layout system, it's required that
  113.     objects know their minimum and maximums sizes. Since boopsi 
  114.     gadgets don't support this feature, you will have to help
  115.     MUI and adjust these values by hand.
  116.  
  117.     Defaults:
  118.  
  119.        MUIA_MinWidth  - 1 pixel
  120.        MUIA_MinHeight - 1 pixel
  121.        MUIA_MaxWidth  - unlimited
  122.        MUIA_MaxHeight - unlimited
  123.  
  124.     EXAMPLE
  125.     see MUIA_Boopsi_ClassID
  126.  
  127.     SEE ALSO
  128.     MUIA_Boopsi_ClassID
  129. Boopsi.mui/MUIA_Boopsi_MaxWidth
  130.  
  131.     NAME
  132.     MUIA_Boopsi_MaxWidth -- (V4) [ISG], ULONG
  133.  
  134.     FUNCTION
  135.     For MUI's automatic layout system, it's required that
  136.     objects know their minimum and maximums sizes. Since boopsi 
  137.     gadgets don't support this feature, you will have to help
  138.     MUI and adjust these values by hand.
  139.  
  140.     Defaults:
  141.  
  142.        MUIA_MinWidth  - 1 pixel
  143.        MUIA_MinHeight - 1 pixel
  144.        MUIA_MaxWidth  - unlimited
  145.        MUIA_MaxHeight - unlimited
  146.  
  147.     EXAMPLE
  148.     see MUIA_Boopsi_ClassID
  149.  
  150.     SEE ALSO
  151.     MUIA_Boopsi_ClassID
  152. Boopsi.mui/MUIA_Boopsi_MinHeight
  153.  
  154.     NAME
  155.     MUIA_Boopsi_MinHeight -- (V4) [ISG], ULONG
  156.  
  157.     FUNCTION
  158.     For MUI's automatic layout system, it's required that
  159.     objects know their minimum and maximums sizes. Since boopsi 
  160.     gadgets don't support this feature, you will have to help
  161.     MUI and adjust these values by hand.
  162.  
  163.     Defaults:
  164.  
  165.        MUIA_MinWidth  - 1 pixel
  166.        MUIA_MinHeight - 1 pixel
  167.        MUIA_MaxWidth  - unlimited
  168.        MUIA_MaxHeight - unlimited
  169.  
  170.     EXAMPLE
  171.     see MUIA_Boopsi_ClassID
  172.  
  173.     SEE ALSO
  174.     MUIA_Boopsi_ClassID
  175. Boopsi.mui/MUIA_Boopsi_MinWidth
  176.  
  177.     NAME
  178.     MUIA_Boopsi_MinWidth -- (V4) [ISG], ULONG
  179.  
  180.     FUNCTION
  181.     For MUI's automatic layout system, it's required that
  182.     objects know their minimum and maximums sizes. Since boopsi 
  183.     gadgets don't support this feature, you will have to help
  184.     MUI and adjust these values by hand.
  185.  
  186.     Defaults:
  187.  
  188.        MUIA_MinWidth  - 1 pixel
  189.        MUIA_MinHeight - 1 pixel
  190.        MUIA_MaxWidth  - unlimited
  191.        MUIA_MaxHeight - unlimited
  192.  
  193.     EXAMPLE
  194.     see MUIA_Boopsi_ClassID
  195.  
  196.     SEE ALSO
  197.     MUIA_Boopsi_ClassID
  198. Boopsi.mui/MUIA_Boopsi_Object
  199.  
  200.     NAME
  201.     MUIA_Boopsi_Object -- (V4) [..G], Object *
  202.  
  203.     FUNCTION
  204.     No input, just an output since this attribute is
  205.     only getable. What MUI returns when generating a
  206.     BoopsiObject is a standard MUI object, not a pointer
  207.     to the Boopsi gadget itself. In case you really need
  208.     this Boopsi gadget pointer, you can obtain it by getting
  209.     MUIA_Boopsi_Object from the MUI object.
  210.  
  211.     Since MUI passes along every unknown attribute to the 
  212.     boopsi gadget, there should be no need for this tag anyway.
  213.  
  214.     Note that the boopsi object pointer is only valid when the
  215.     window is open!
  216.  
  217.     SEE ALSO
  218.     MUIA_Boopsi_Class, MUIA_Boopsi_ClassID
  219. Boopsi.mui/MUIA_Boopsi_Remember
  220.  
  221.     NAME
  222.     MUIA_Boopsi_Remember -- (V4) [I..], ULONG
  223.  
  224.     FUNCTION
  225.     Most boopsi objects are kind of silly, they don't support
  226.     automatic resizing or jumping from screen to screen.
  227.     Therefor, MUI sometimes needs to dispose and regenerate
  228.     a boopsi object. This will result in loosing the current
  229.     state of the object, e.g. saturation and hue values
  230.     in a colorwheel.
  231.  
  232.     To solve this problem, you can tell MUI what attributes
  233.     must be remembered during dispose/regeneration. For a
  234.     colorwheel, this would e.g. be WHEEL_Saturation and WHEEL_Hue.
  235.  
  236.     Before disposing the boopsi object, the remember tags are
  237.     read and stored in a private buffer. After regeneration,
  238.     the contents of this buffer are passed back to the boopsi
  239.     again.
  240.  
  241.     Note that you can define up to five MUIA_Remember tags.
  242.  
  243.     BUGS
  244.     The remember procedure will not work when the attributes
  245.     you want to remember are just pointers to data stored
  246.     somewhere in the boopsi object.
  247.  
  248.     EXAMPLE
  249.     see MUIA_Boopsi_ClassID
  250.  
  251.     SEE ALSO
  252.     MUIA_Boopsi_ClassID
  253. Boopsi.mui/MUIA_Boopsi_TagDrawInfo
  254.  
  255.     NAME
  256.     MUIA_Boopsi_TagDrawInfo -- (V4) [ISG], ULONG
  257.  
  258.     FUNCTION
  259.     Unfortunately, most boopsi gadgets need information on
  260.     the display environment they will reside in at object
  261.     creation time. Due to MUI's concept, this information
  262.     is not available that early.
  263.  
  264.     To solve this problem, MUI doesn't generate the boopsi
  265.     object instantly, creation is delayed until the window
  266.     containing the gadget is opened.
  267.  
  268.     At this time, MUI fills some values about display
  269.     environment into the boopsi objects creation tag list.
  270.     You have to tell MUI, what tags are actually needed.
  271.  
  272.     With MUIA_Boopsi_TagDrawInfo you can tell MUI where
  273.     to fill in a needed DrawInfo structure.
  274.  
  275.     EXAMPLE
  276.     If your boopsi gadget needs a pointer to a DrawInfo
  277.     structure supplied with the MYBOOPSI_DrawInfo tag,
  278.     you would have to specify
  279.  
  280.     BoopsiObject,
  281.        Recessed