home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 18 / amigaformatcd18.iso / mui / mui_developer / autodocs / mui_boopsi.doc < prev    next >
Text File  |  1997-03-10  |  11KB  |  394 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_Smart
  13. Boopsi.mui/MUIA_Boopsi_TagDrawInfo
  14. Boopsi.mui/MUIA_Boopsi_TagScreen
  15. Boopsi.mui/MUIA_Boopsi_TagWindow
  16. Boopsi.mui/Boopsi.mui
  17.  
  18.     MUI's boopsi class provides an interface to standard,
  19.     system style boopsi gadgets. Since boopsis gadgetclass
  20.     misses some important features needed for an automatic
  21.     layout system like MUI, there are several problems with
  22.     such an interface. MUI tries to solve these problems
  23.     with some additional attributes.
  24.  
  25.     Coming with release 3.x of the amiga operating system are
  26.     some very nice boopsi gadgets such as "colorwheel.gadget"
  27.     or "gradientslider.gadget". With MUI's boopsi class, you
  28.     can use these gadgets just as if they were MUI objects.
  29.  
  30.     You can talk to a MUIized boopsi object as if it was the
  31.     boopsi object itself. MUI will pass through all attributes
  32.     and try to be completely transparent. Additionally, if
  33.     a boopsi object generates notification events via
  34.     IDCMP_UPDATE, MUI turns them into MUI notification events.
  35.     Thus, you can e.g. react on the change of WHEEL_Saturation
  36.     in a MUI colorwheel boopsi gadget as on any other MUI
  37.     attribute.
  38.  
  39.     An example program "BoopsiDoor.c" is provided to show
  40.     how this magic works.
  41.  
  42.    Note: OS 3.0/3.1 colorwheel.gadget can accidently render itself
  43.          one pixel too big, overwriting other parts of the window.
  44.          As a workaround, MUI will subtract one from the width/height
  45.          before passing it on to a colorwheel boopsi object.
  46. Boopsi.mui/MUIA_Boopsi_Class
  47.  
  48.     NAME
  49.     MUIA_Boopsi_Class -- (V4 ) [ISG], struct IClass *
  50.  
  51.     FUNCTION
  52.     Pointer to the (private) class you want to create a boopsi
  53.     object from. Only useful if you previously generated your
  54.     own boopsi class with MakeClass().
  55.  
  56.     Of course you may not free the class until you're done
  57.     with your object.
  58.  
  59.     SEE ALSO
  60.     MUIA_Boopsi_ClassID
  61. Boopsi.mui/MUIA_Boopsi_ClassID
  62.  
  63.     NAME
  64.     MUIA_Boopsi_ClassID -- (V4 ) [ISG], char *
  65.  
  66.     FUNCTION
  67.     MUIA_Boopsi_ClassID specifies the name for the public
  68.     Boopsi class you want to create an object of. It will
  69.     only be used when MUIA_Boopsi_Class is NULL.
  70.  
  71.     The public class must be in memory before you can create
  72.     an instance of it, you will have to open the required class
  73.     library by hand.
  74.  
  75.     Note the string given to MUIA_Boopsi_ClassID must remain
  76.     valid until you're done with the object.
  77.  
  78.     EXAMPLE
  79.  
  80.     /* Complete example code can be found in BoopsiDoor.c */
  81.  
  82.     cwbase = OpenLibrary("gadgets/colorwheel.gadget",0);
  83.  
  84.     Wheel = BoopsiObject,  /* MUI and Boopsi tags mixed */
  85.      NeXTFrame,
  86.      MUIA_Boopsi_ClassID  , "colorwheel.gadget",
  87.      MUIA_Boopsi_MinWidth , 30, /* boopsi objects don't know */
  88.      MUIA_Boopsi_MinHeight, 30, /* their sizes, so we help   */
  89.       MUIA_Boopsi_Remember , WHEEL_Saturation, /* keep important values */
  90.      MUIA_Boopsi_Remember , WHEEL_Hue,        /* during window resize  */
  91.      MUIA_Boopsi_TagScreen, WHEEL_Screen, /* this magic fills in */
  92.      WHEEL_Screen         , NULL,         /* the screen pointer  */
  93.      GA_Left     , 0,
  94.      GA_Top      , 0, /* MUI will automatically     */
  95.      GA_Width    , 0, /* fill in the correct values */
  96.      GA_Height   , 0,
  97.      ICA_TARGET  , ICTARGET_IDCMP, /* needed for notification */
  98.      End;
  99.  
  100.     ...
  101.  
  102.     MUI_DisposeObject(wheel);
  103.     CloseLibrary(cwbase);
  104.  
  105.     SEE ALSO
  106.     MUIA_Boopsi_Class
  107. Boopsi.mui/MUIA_Boopsi_MaxHeight
  108.  
  109.     NAME
  110.     MUIA_Boopsi_MaxHeight -- (V4 ) [ISG], ULONG
  111.  
  112.     FUNCTION
  113.     For MUI's automatic layout system, it's required that
  114.     objects know their minimum and maximums sizes. Since boopsi 
  115.     gadgets don't support this feature, you will have to help
  116.     MUI and adjust these values by hand.
  117.  
  118.     Defaults:
  119.  
  120.        MUIA_Boopsi_MinWidth  - 1 pixel
  121.        MUIA_Boopsi_MinHeight - 1 pixel
  122.        MUIA_Boopsi_MaxWidth  - unlimited
  123.        MUIA_Boopsi_MaxHeight - unlimited
  124.  
  125.     EXAMPLE
  126.     see MUIA_Boopsi_ClassID
  127.  
  128.     SEE ALSO
  129.     MUIA_Boopsi_ClassID
  130. Boopsi.mui/MUIA_Boopsi_MaxWidth
  131.  
  132.     NAME
  133.     MUIA_Boopsi_MaxWidth -- (V4 ) [ISG], ULONG
  134.  
  135.     FUNCTION
  136.     For MUI's automatic layout system, it's required that
  137.     objects know their minimum and maximums sizes. Since boopsi 
  138.     gadgets don't support this feature, you will have to help
  139.     MUI and adjust these values by hand.
  140.  
  141.     Defaults:
  142.  
  143.        MUIA_Boopsi_MinWidth  - 1 pixel
  144.        MUIA_Boopsi_MinHeight - 1 pixel
  145.        MUIA_Boopsi_MaxWidth  - unlimited
  146.        MUIA_Boopsi_MaxHeight - unlimited
  147.  
  148.     EXAMPLE
  149.     see MUIA_Boopsi_ClassID
  150.  
  151.     SEE ALSO
  152.     MUIA_Boopsi_ClassID
  153. Boopsi.mui/MUIA_Boopsi_MinHeight
  154.  
  155.     NAME
  156.     MUIA_Boopsi_MinHeight -- (V4 ) [ISG], ULONG
  157.  
  158.     FUNCTION
  159.     For MUI's automatic layout system, it's required that
  160.     objects know their minimum and maximums sizes. Since boopsi 
  161.     gadgets don't support this feature, you will have to help
  162.     MUI and adjust these values by hand.
  163.  
  164.     Defaults:
  165.  
  166.        MUIA_Boopsi_MinWidth  - 1 pixel
  167.        MUIA_Boopsi_MinHeight - 1 pixel
  168.        MUIA_Boopsi_MaxWidth  - unlimited
  169.        MUIA_Boopsi_MaxHeight - unlimited
  170.  
  171.     EXAMPLE
  172.     see MUIA_Boopsi_ClassID
  173.  
  174.     SEE ALSO
  175.     MUIA_Boopsi_ClassID
  176. Boopsi.mui/MUIA_Boopsi_MinWidth
  177.  
  178.     NAME
  179.     MUIA_Boopsi_MinWidth -- (V4 ) [ISG], ULONG
  180.  
  181.     FUNCTION
  182.     For MUI's automatic layout system, it's required that
  183.     objects know their minimum and maximums sizes. Since boopsi 
  184.     gadgets don't support this feature, you will have to help
  185.     MUI and adjust these values by hand.
  186.  
  187.     Defaults:
  188.  
  189.        MUIA_Boopsi_MinWidth  - 1 pixel
  190.        MUIA_Boopsi_MinHeight - 1 pixel
  191.        MUIA_Boopsi_MaxWidth  - unlimited
  192.        MUIA_Boopsi_MaxHeight - unlimited
  193.  
  194.     EXAMPLE
  195.     see MUIA_Boopsi_ClassID
  196.  
  197.     SEE ALSO
  198.     MUIA_Boopsi_ClassID
  199. Boopsi.mui/MUIA_Boopsi_Object
  200.  
  201.     NAME
  202.     MUIA_Boopsi_Object -- (V4 ) [..G], Object *
  203.  
  204.     FUNCTION
  205.     No input, just an output since this attribute is
  206.     only getable. What MUI returns when generating a
  207.     BoopsiObject is a standard MUI object, not a pointer
  208.     to the Boopsi gadget itself. In case you really need
  209.     this Boopsi gadget pointer, you can obtain it by getting
  210.     MUIA_Boopsi_Object from the MUI object.
  211.  
  212.     Since MUI passes along every unknown attribute to the 
  213.     boopsi gadget, there should be no need for this tag anyway.
  214.  
  215.     Note that the boopsi object pointer is only valid when the
  216.     window is open!
  217.  
  218.     SEE ALSO
  219.     MUIA_Boopsi_Class, MUIA_Boopsi_ClassID
  220. Boopsi.mui/MUIA_Boopsi_Remember
  221.  
  222.     NAME
  223.     MUIA_Boopsi_Remember -- (V4 ) [I..], ULONG
  224.  
  225.     FUNCTION
  226.     Most boopsi objects are kind of silly, they don't support
  227.     automatic resizing or jumping from screen to screen.
  228.     Therefor, MUI sometimes needs to dispose and regenerate
  229.     a boopsi object. This will result in loosing the current
  230.     state of the object, e.g. saturation and hue values
  231.     in a colorwheel.
  232.  
  233.     To solve this problem, you can tell MUI what attributes
  234.     must be remembered during dispose/regeneration. For a
  235.     colorwheel, this would e.g. be WHEEL_Saturation and WHEEL_Hue.
  236.  
  237.     Before disposing the boopsi object, the remember tags are
  238.     read and stored in a private buffer. After regeneration,
  239.     the contents of this buffer are passed back to the boopsi
  240.     again.
  241.  
  242.     Note that you can define up to five MUIA_Boopsi_Remember tags.
  243.  
  244.     BUGS
  245.     The remember procedure will not work when the attributes
  246.     you want to remember are just pointers to data stored
  247.     somewhere in the boopsi object.
  248.  
  249.     EXAMPLE
  250.     see MUIA_Boopsi_ClassID
  251.  
  252.     SEE ALSO
  253.     MUIA_Boopsi_ClassID
  254. Boopsi.mui/MUIA_Boopsi_Smart
  255.  
  256.     NAME
  257.     MUIA_Boopsi_Smart -- (V9 ) [I..], BOOL
  258.  
  259.     FUNCTION
  260.     Specify TRUE for smart BOOPSI gadgets that allow resizing,
  261.     e.g. the textfield.class. In this case, MUI will not
  262.     dispose and recreate the object.
  263. Boopsi.mui/MUIA_Boopsi_TagDrawInfo
  264.  
  265.     NAME
  266.     MUIA_Boopsi_TagDrawInfo -- (V4 ) [ISG], ULONG
  267.  
  268.     FUNCTION
  269.     Unfortunately, most boopsi gadgets need information on
  270.     the display environment they will reside in at object
  271.     creation time. Due to MUI's concept, this information
  272.     is not available that early.
  273.  
  274.     To solve this problem, MUI doesn't generate the boopsi
  275.     object instantly, creation is delayed until the window
  276.     containing the gadget is opened.
  277.  
  278.     At this time, MUI fills some values about display
  279.     environment into the boopsi objects creation tag list.
  280.     You have to tell MUI, what tags are actually needed.
  281.  
  282.     With MUIA_Boopsi_TagDrawInfo you can tell MUI where
  283.     to fill in a needed DrawInfo structure.
  284.  
  285.     EXAMPLE
  286.     If your boopsi gadget needs a pointer to a DrawInfo
  287.     structure supplied with the MYBOOPSI_DrawInfo tag,
  288.     you would have to specify
  289.  
  290.     BoopsiObject,
  291.        RecessedFrame,
  292.        ...
  293.        MUIA_Boopsi_TagDrawInfo, MYBOOPSI_DrawInfo,
  294.        ...
  295.        MYBOOPSI_DrawInfo, 0, /* will be filled later by MUI */
  296.        ...
  297.        GA_Left  , 0, /* needs to be there, will */
  298.        GA_Top   , 0, /* be filled later by MUI  */
  299.        GA_Width , 0,
  300.        GA_Height, 0,
  301.  
  302.        End;
  303.  
  304.     SEE ALSO
  305.     MUIA_Boopsi_ClassID, MUIA_Boopsi_TagScreen, MUIA_Boopsi_TagWindow
  306. Boopsi.mui/MUIA_Boopsi_TagScreen
  307.  
  308.     NAME
  309.     MUIA_Boopsi_TagScreen -- (V4 ) [ISG], ULONG
  310.  
  311.     FUNCTION
  312.     Unfortunately, most boopsi gadgets need information on
  313.     the display environment they will reside in at object
  314.     creation time. Due to MUI's concept, this information
  315.     is not available that early.
  316.  
  317.     To solve this problem, MUI doesn't generate the boopsi
  318.     object instantly, creation is delayed until the window
  319.     containing the gadget is opened.
  320.  
  321.     At this time, MUI fills some values about display
  322.     environment into the boopsi objects creation tag list.
  323.     You have to tell MUI, what tags are actually needed.
  324.  
  325.     With MUIA_Boopsi_TagScreen you can tell MUI where
  326.     to fill in a needed Screen structure.
  327.  
  328.     EXAMPLE
  329.     If your boopsi gadget needs a pointer to a Screen
  330.     structure supplied with the MYBOOPSI_Screen tag,
  331.     you would have to specify
  332.  
  333.     BoopsiObject,
  334.        RecessedFrame,
  335.        ...
  336.        MUIA_Boopsi_TagScreen, MYBOOPSI_Screen,
  337.        ...
  338.        MYBOOPSI_Screen, 0, /* will be filled later by MUI */
  339.        ...
  340.        GA_Left  , 0, /* needs to be there, will */
  341.        GA_Top   , 0, /* be filled later by MUI  */
  342.        GA_Width , 0,
  343.        GA_Height, 0,
  344.  
  345.        End;
  346.  
  347.     SEE ALSO
  348.     MUIA_Boopsi_ClassID, MUIA_Boopsi_TagDrawInfo,
  349.     MUIA_Boopsi_TagWindow
  350. Boopsi.mui/MUIA_Boopsi_TagWindow
  351.  
  352.     NAME
  353.     MUIA_Boopsi_TagWindow -- (V4 ) [ISG], ULONG
  354.  
  355.     FUNCTION
  356.     Unfortunately, most boopsi gadgets need information on
  357.     the display environment they will reside in at object
  358.     creation time. Due to MUI's concept, this information
  359.     is not available that early.
  360.  
  361.     To solve this problem, MUI doesn't generate the boopsi
  362.     object instantly, creation is delayed until the window
  363.     containing the gadget is opened.
  364.  
  365.     At this time, MUI fills some values about display
  366.     environment into the boopsi objects creation tag list.
  367.     You have to tell MUI, what tags are actually needed.
  368.  
  369.     With MUIA_Boopsi_TagWindow you can tell MUI where
  370.     to fill in a needed Window structure.
  371.  
  372.     EXAMPLE
  373.     If your boopsi gadget needs a pointer to a Window
  374.     structure supplied with the MYBOOPSI_Window tag,
  375.     you would have to specify
  376.  
  377.     BoopsiObject,
  378.        RecessedFrame,
  379.        ...
  380.        MUIA_Boopsi_TagWindow, MYBOOPSI_Window,
  381.        ...
  382.        MYBOOPSI_Window, 0, /* will be filled later by MUI */
  383.        ...
  384.        GA_Left  , 0, /* needs to be there, will */
  385.        GA_Top   , 0, /* be filled later by MUI  */
  386.        GA_Width , 0,
  387.        GA_Height, 0,
  388.  
  389.        End;
  390.  
  391.     SEE ALSO
  392.     MUIA_Boopsi_ClassID, MUIA_Boopsi_TagDrawInfo, 
  393.     MUIA_Boopsi_TagWindow
  394.