Fresh Fish 5/FreshFish_July-August1994.bin/bbs/dev/mui-2.1.lha/MUI-2.1/Developer/Autodocs/MUI_Boopsi.doc

Text File | 1994-07-04 | 10.8 KB | 384 lines

TABLE OF CONTENTS

Boopsi.mui/Boopsi.mui
Boopsi.mui/MUIA_Boopsi_Class
Boopsi.mui/MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_MaxHeight
Boopsi.mui/MUIA_Boopsi_MaxWidth
Boopsi.mui/MUIA_Boopsi_MinHeight
Boopsi.mui/MUIA_Boopsi_MinWidth
Boopsi.mui/MUIA_Boopsi_Object
Boopsi.mui/MUIA_Boopsi_Remember
Boopsi.mui/MUIA_Boopsi_TagDrawInfo
Boopsi.mui/MUIA_Boopsi_TagScreen
Boopsi.mui/MUIA_Boopsi_TagWindow
Boopsi.mui/Boopsi.mui

    MUI's boopsi class provides an interface to standard,
    system style boopsi gadgets. Since boopsis gadgetclass
    misses some important features needed for an automatic
    layout system like MUI, there are several problems with
    such an interface. MUI tries to solve these problems
    with some additional attributes.

    Coming with release 3.x of the amiga operating system are
    some very nice boopsi gadgets such as "colorwheel.gadget"
    or "gradientslider.gadget". With MUI's boopsi class, you
    can use these gadgets just as if they were MUI objects.

    You can talk to a MUIized boopsi object as if it was the
    boopsi object itself. MUI will pass through all attributes
    and try to be completely transparent. Additionally, if
    a boopsi object generates notification events via
    IDCMP_UPDATE, MUI turns them into MUI notification events.
    Thus, you can e.g. react on the change of WHEEL_Saturation
    in a MUI colorwheel boopsi gadget as on any other MUI
    attribute.

    An example program "BoopsiDoor.c" is provided to show
    how this magic works.

   Note: OS 3.0/3.1 colorwheel.gadget can accidently render itself
         one pixel too big, overwriting other parts of the window.
         As a workaround, MUI will subtract one from the width/height
         before passing it on to a colorwheel boopsi object.
Boopsi.mui/MUIA_Boopsi_Class

    NAME
    MUIA_Boopsi_Class -- (V4) [ISG], struct IClass *

    FUNCTION
    Pointer to the (private) class you want to create a boopsi
    object from. Only useful if you previously generated your
    own boopsi class with MakeClass().

    Of course you may not free the class until you're done
    with your object.

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_ClassID

    NAME
    MUIA_Boopsi_ClassID -- (V4) [ISG], char *

    FUNCTION
    MUIA_Boopsi_ClassID specifies the name for the public
    Boopsi class you want to create an object of. It will
    only be used when MUIA_Boopsi_Class is NULL.

    The public class must be in memory before you can create
    an instance of it, you will have to open the required class
    library by hand.

    Note the string given to MUIA_Boopsi_ClassID must remain
    valid until you're done with the object.

    EXAMPLE

    /* Complete example code can be found in BoopsiDoor.c */

    cwbase = OpenLibrary("gadgets/colorwheel.gadget",0);

    Wheel = BoopsiObject,  /* MUI and Boopsi tags mixed */
     NeXTFrame,
     MUIA_Boopsi_ClassID  , "colorwheel.gadget",
     MUIA_Boopsi_MinWidth , 30, /* boopsi objects don't know */
     MUIA_Boopsi_MinHeight, 30, /* their sizes, so we help   */
      MUIA_Boopsi_Remember , WHEEL_Saturation, /* keep important values */
     MUIA_Boopsi_Remember , WHEEL_Hue,        /* during window resize  */
     MUIA_Boopsi_TagScreen, WHEEL_Screen, /* this magic fills in */
     WHEEL_Screen         , NULL,         /* the screen pointer  */
     GA_Left     , 0,
     GA_Top      , 0, /* MUI will automatically     */
     GA_Width    , 0, /* fill in the correct values */
     GA_Height   , 0,
     ICA_TARGET  , ICTARGET_IDCMP, /* needed for notification */
     End;

    ...

    MUI_DisposeObject(wheel);
    CloseLibrary(cwbase);

    SEE ALSO
    MUIA_Boopsi_Class
Boopsi.mui/MUIA_Boopsi_MaxHeight

    NAME
    MUIA_Boopsi_MaxHeight -- (V4) [ISG], ULONG

    FUNCTION
    For MUI's automatic layout system, it's required that
    objects know their minimum and maximums sizes. Since boopsi
    gadgets don't support this feature, you will have to help
    MUI and adjust these values by hand.

    Defaults:

       MUIA_MinWidth  - 1 pixel
       MUIA_MinHeight - 1 pixel
       MUIA_MaxWidth  - unlimited
       MUIA_MaxHeight - unlimited

    EXAMPLE
    see MUIA_Boopsi_ClassID

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_MaxWidth

    NAME
    MUIA_Boopsi_MaxWidth -- (V4) [ISG], ULONG

    FUNCTION
    For MUI's automatic layout system, it's required that
    objects know their minimum and maximums sizes. Since boopsi
    gadgets don't support this feature, you will have to help
    MUI and adjust these values by hand.

    Defaults:

       MUIA_MinWidth  - 1 pixel
       MUIA_MinHeight - 1 pixel
       MUIA_MaxWidth  - unlimited
       MUIA_MaxHeight - unlimited

    EXAMPLE
    see MUIA_Boopsi_ClassID

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_MinHeight

    NAME
    MUIA_Boopsi_MinHeight -- (V4) [ISG], ULONG

    FUNCTION
    For MUI's automatic layout system, it's required that
    objects know their minimum and maximums sizes. Since boopsi
    gadgets don't support this feature, you will have to help
    MUI and adjust these values by hand.

    Defaults:

       MUIA_MinWidth  - 1 pixel
       MUIA_MinHeight - 1 pixel
       MUIA_MaxWidth  - unlimited
       MUIA_MaxHeight - unlimited

    EXAMPLE
    see MUIA_Boopsi_ClassID

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_MinWidth

    NAME
    MUIA_Boopsi_MinWidth -- (V4) [ISG], ULONG

    FUNCTION
    For MUI's automatic layout system, it's required that
    objects know their minimum and maximums sizes. Since boopsi
    gadgets don't support this feature, you will have to help
    MUI and adjust these values by hand.

    Defaults:

       MUIA_MinWidth  - 1 pixel
       MUIA_MinHeight - 1 pixel
       MUIA_MaxWidth  - unlimited
       MUIA_MaxHeight - unlimited

    EXAMPLE
    see MUIA_Boopsi_ClassID

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_Object

    NAME
    MUIA_Boopsi_Object -- (V4) [..G], Object *

    FUNCTION
    No input, just an output since this attribute is
    only getable. What MUI returns when generating a
    BoopsiObject is a standard MUI object, not a pointer
    to the Boopsi gadget itself. In case you really need
    this Boopsi gadget pointer, you can obtain it by getting
    MUIA_Boopsi_Object from the MUI object.

    Since MUI passes along every unknown attribute to the
    boopsi gadget, there should be no need for this tag anyway.

    Note that the boopsi object pointer is only valid when the
    window is open!

    SEE ALSO
    MUIA_Boopsi_Class, MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_Remember

    NAME
    MUIA_Boopsi_Remember -- (V4) [I..], ULONG

    FUNCTION
    Most boopsi objects are kind of silly, they don't support
    automatic resizing or jumping from screen to screen.
    Therefor, MUI sometimes needs to dispose and regenerate
    a boopsi object. This will result in loosing the current
    state of the object, e.g. saturation and hue values
    in a colorwheel.

    To solve this problem, you can tell MUI what attributes
    must be remembered during dispose/regeneration. For a
    colorwheel, this would e.g. be WHEEL_Saturation and WHEEL_Hue.

    Before disposing the boopsi object, the remember tags are
    read and stored in a private buffer. After regeneration,
    the contents of this buffer are passed back to the boopsi
    again.

    Note that you can define up to five MUIA_Remember tags.

    BUGS
    The remember procedure will not work when the attributes
    you want to remember are just pointers to data stored
    somewhere in the boopsi object.

    EXAMPLE
    see MUIA_Boopsi_ClassID

    SEE ALSO
    MUIA_Boopsi_ClassID
Boopsi.mui/MUIA_Boopsi_TagDrawInfo

    NAME
    MUIA_Boopsi_TagDrawInfo -- (V4) [ISG], ULONG

    FUNCTION
    Unfortunately, most boopsi gadgets need information on
    the display environment they will reside in at object
    creation time. Due to MUI's concept, this information
    is not available that early.

    To solve this problem, MUI doesn't generate the boopsi
    object instantly, creation is delayed until the window
    containing the gadget is opened.

    At this time, MUI fills some values about display
    environment into the boopsi objects creation tag list.
    You have to tell MUI, what tags are actually needed.

    With MUIA_Boopsi_TagDrawInfo you can tell MUI where
    to fill in a needed DrawInfo structure.

    EXAMPLE
    If your boopsi gadget needs a pointer to a DrawInfo
    structure supplied with the MYBOOPSI_DrawInfo tag,
    you would have to specify

    BoopsiObject,
       RecessedFrame,
       ...
       MUIA_Boopsi_TagDrawInfo, MYBOOPSI_DrawInfo,
       ...
       MYBOOPSI_DrawInfo, 0, /* will be filled later by MUI */
       ...
       GA_Left  , 0, /* needs to be there, will */
       GA_Top   , 0, /* be filled later by MUI  */
       GA_Width , 0,
       GA_Height, 0,

       End;

    SEE ALSO
    MUIA_Boopsi_ClassID, MUIA_Boopsi_TagScreen, MUIA_Boopsi_TagWindow
Boopsi.mui/MUIA_Boopsi_TagScreen

    NAME
    MUIA_Boopsi_TagScreen -- (V4) [ISG], ULONG

    FUNCTION
    Unfortunately, most boopsi gadgets need information on
    the display environment they will reside in at object
    creation time. Due to MUI's concept, this information
    is not available that early.

    To solve this problem, MUI doesn't generate the boopsi
    object instantly, creation is delayed until the window
    containing the gadget is opened.

    At this time, MUI fills some values about display
    environment into the boopsi objects creation tag list.
    You have to tell MUI, what tags are actually needed.

    With MUIA_Boopsi_TagScreen you can tell MUI where
    to fill in a needed Screen structure.

    EXAMPLE
    If your boopsi gadget needs a pointer to a Screen
    structure supplied with the MYBOOPSI_Screen tag,
    you would have to specify

    BoopsiObject,
       RecessedFrame,
       ...
       MUIA_Boopsi_TagScreen, MYBOOPSI_Screen,
       ...
       MYBOOPSI_Screen, 0, /* will be filled later by MUI */
       ...
       GA_Left  , 0, /* needs to be there, will */
       GA_Top   , 0, /* be filled later by MUI  */
       GA_Width , 0,
       GA_Height, 0,

       End;

    SEE ALSO
    MUIA_Boopsi_ClassID, MUIA_Boopsi_TagDrawInfo,
    MUIA_Boopsi_TagWindow
Boopsi.mui/MUIA_Boopsi_TagWindow

    NAME
    MUIA_Boopsi_TagWindow -- (V4) [ISG], ULONG

    FUNCTION
    Unfortunately, most boopsi gadgets need information on
    the display environment they will reside in at object
    creation time. Due to MUI's concept, this information
    is not available that early.

    To solve this problem, MUI doesn't generate the boopsi
    object instantly, creation is delayed until the window
    containing the gadget is opened.

    At this time, MUI fills some values about display
    environment into the boopsi objects creation tag list.
    You have to tell MUI, what tags are actually needed.

    With MUIA_Boopsi_TagWindow you can tell MUI where
    to fill in a needed Window structure.

    EXAMPLE
    If your boopsi gadget needs a pointer to a Window
    structure supplied with the MYBOOPSI_Window tag,
    you would have to specify

    BoopsiObject,
       RecessedFrame,
       ...
       MUIA_Boopsi_TagWindow, MYBOOPSI_Window,
       ...
       MYBOOPSI_Window, 0, /* will be filled later by MUI */
       ...
       GA_Left  , 0, /* needs to be there, will */
       GA_Top   , 0, /* be filled later by MUI  */
       GA_Width , 0,
       GA_Height, 0,

       End;

    SEE ALSO
    MUIA_Boopsi_ClassID, MUIA_Boopsi_TagDrawInfo,
    MUIA_Boopsi_TagWindow