home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / RTGMaster / goodies / rtggadtools / autodocs / rtggadtools.doc
Encoding:
Text File  |  1998-06-24  |  12.5 KB  |  428 lines
  1. TABLE OF CONTENTS
  2.  
  3. RTGGadTools/RGAddGadget
  4. RTGGadTools/RGDisposeAnchor
  5. RTGGadTools/RGDisposeGadget
  6. RTGGadTools/RGDoGadgets
  7. RTGGadTools/RGGadgetState
  8. RTGGadTools/RGNewAnchor
  9. RTGGadTools/RGNewGadget
  10. RTGGadTools/RGRefreshGList
  11. RTGGadTools/RGRemGadget
  12. RTGGadTools/RGAddGadget                               RTGGadTools/RGAddGadget
  13.  
  14.    NAME   
  15.        RGAddGadget -- Add a gadget to an anchor list
  16.  
  17.    SYNOPSIS
  18.        err=RGAddGadget(anchor, gadget, pos);
  19.        D0              A0      A1      D0
  20.        BOOL RGAddGadget(APTR, RGGadget, LONG);
  21.  
  22.    FUNCTION
  23.        Add a given gadget to an achor list. Gadgets in the anchor
  24.        list are considered "active", and thus get rendered/used
  25.        within a RGDoGadget() call.
  26.  
  27.    INPUTS
  28.        anchor  -   Gadget anchor.
  29.        gadget  -   The gadget to be added.
  30.        pos     -   the position where the gadget should be added.
  31.                    see notes.
  32.  
  33.    RESULT
  34.        err     -   Boolean value representing success (TRUE) or
  35.                    failuer (error)
  36.  
  37.    EXAMPLE
  38.        see example programs
  39.  
  40.    NOTES
  41.        The position you specify should be either a positive integer
  42.        representing the position where the gadget should be added,
  43.        zero if you want to add to the beginning of the list (fastest)
  44.        and -1 if you want to add to the end. Normally there shouldn't
  45.        be a reason not to use zero.
  46.  
  47.    BUGS
  48.        none known
  49.  
  50.    SEE ALSO
  51.        RGDoGadget(), RGRemGadget(), RGDisposeGadget(), RGNewAnchor()
  52.  
  53. RTGGadTools/RGDisposeAnchor                       RTGGadTools/RGDisposeAnchor
  54.  
  55.    NAME   
  56.        RGDisposeAnchor -- Delete an Anchor structure (V1)
  57.  
  58.    SYNOPSIS
  59.        RGDisposeAnchor(anchor);
  60.                        A0
  61.        void RGDisposeAnchor(APTR);
  62.  
  63.    FUNCTION
  64.        Dispose an Anchor created by RGNewAnchor()
  65.  
  66.    INPUTS
  67.        anchor - the anchor to be disposed
  68.  
  69.    RESULT
  70.        none
  71.  
  72.    EXAMPLE
  73.        see example programs
  74.  
  75.    NOTES
  76.        If there are still gadgets attached to the anchor, they get
  77.        deleted along with it. If you do not want this behavior, you
  78.        will have to remove the gadgets manually.
  79.  
  80.    BUGS
  81.        none known
  82.  
  83.    SEE ALSO
  84.        RGNewAnchor()
  85.  
  86. RTGGadTools/RGDisposeGadget                       RTGGadTools/RGDisposeGadget
  87.  
  88.    NAME   
  89.        RGDisposeGadget -- Delete a RGGadget (V1)
  90.  
  91.    SYNOPSIS
  92.        RGDisposeGadget(gad);
  93.                        A0
  94.        RGDiposeGadget(RGGadget);
  95.  
  96.    FUNCTION
  97.        Dispose the gadget created by RGNewGadget()
  98.  
  99.    INPUTS
  100.        gad - pointer to a RGGadget
  101.  
  102.    RESULT
  103.        none
  104.  
  105.    EXAMPLE
  106.        see example programs
  107.  
  108.    NOTES
  109.        Don't pass an invalid pointer. NULL pointers will be dealt
  110.        with correctly, but anything else may be lethal.
  111.  
  112.    BUGS
  113.        None known.
  114.  
  115.    SEE ALSO
  116.        RGNewGadget
  117.  
  118. RTGGadTools/RGDoGadgets                               RTGGadTools/RGDoGadgets
  119.  
  120.    NAME   
  121.        RGDoGadgets -- Do the gadget man (V1)
  122.  
  123.    SYNOPSIS
  124.        ret=RGDoGadgets(anchor,msg);
  125.        D0              A0     A1
  126.        LONG RGDoGadgets(APTR,APTR);
  127.  
  128.    FUNCTION
  129.        This is the core of the gadgets system. This routine should be
  130.        called each time in your applications main loop, with the current
  131.        RDCMP message, even if this is NULL.
  132.  
  133.    INPUTS
  134.        anchor  -   the anchor structure
  135.        msg     -   the current RDCMP message
  136.  
  137.    RESULT
  138.        ret -   NULL if no gadget was used. Otherwise, returns
  139.            the number specified in UpAction/DownAction if this
  140.            wasn't a hook function.
  141.  
  142.    EXAMPLE
  143.        see the example programs
  144.  
  145.    NOTES
  146.        Calling this function with a msg value of -1 will just render
  147.        the complete list of gadgets.
  148.  
  149.    BUGS
  150.        none known
  151.  
  152.    SEE ALSO
  153.        RGNewGadget(), RGAddGadget()
  154.  
  155. RTGGadTools/RGGadgetState                           RTGGadTools/RGGadgetState
  156.  
  157.    NAME   
  158.        RGGadgetState -- Change the state of a gadget (V1)
  159.  
  160.    SYNOPSIS
  161.        RGGadgetState(gadget, state);
  162.                      A0      D0
  163.        void RGGadgetState(RGGadget, ULONG);
  164.  
  165.    FUNCTION
  166.        This function enables or disables a gadget. This is nothing
  167.        more than setting the gadgets RGF_Disabled field, depending
  168.        on the value of state.
  169.  
  170.    INPUTS
  171.        gadget  -   The gadget to manipulate
  172.        state   -   one of the following:
  173.                    RGS_Disable :   Disable the gadget for input
  174.                    RGS_Enable  :   Enable the gadget for input
  175.                    RGS_Toggle  :   Toggle the enable/disable state
  176.  
  177.    RESULT
  178.        This function does not have a return value
  179.  
  180.    EXAMPLE
  181.        see example programs
  182.  
  183.    NOTES
  184.        Disabled gadgets are no longer active for input. They are,
  185.        however, still a part of the anchor and as such are redrawn
  186.        whenever parts of the list get refreshed containing the gadget.
  187.  
  188.    BUGS
  189.        none known.
  190.  
  191.    SEE ALSO
  192.        RGNewGadget()
  193.  
  194. RTGGadTools/RGNewAnchor                               RTGGadTools/RGNewAnchor
  195.  
  196.    NAME   
  197.        RGNewAnchor -- Create an Anchor structure (V1)
  198.  
  199.    SYNOPSIS
  200.        anchor=RGNewAnchor(screen, buffers, colormodel);
  201.        D0                 A0      D0       D1
  202.        APTR RGNewAnchor(APTR, ULONG, BOOL);
  203.  
  204.    FUNCTION
  205.        Create a new anchor structure. An Anchor structure is used as a
  206.        reference for active gadgets. This is a blackbox structure, should
  207.        not be read directly.
  208.  
  209.    INPUTS
  210.        screen      - The RTGScreen you want the gadgets to appear on.
  211.                      This is needed when RTGGadTools wants to render it's
  212.                      gadgets automatically.
  213.        buffers     - The number of buffers you opened this screen with
  214.        colormodel  - A boolean indicating wether this screen is a
  215.                      Direct-Color screen with more than 256 colors (TRUE)
  216.                      or a color-mapped screen (FALSE).
  217.  
  218.    RESULT
  219.        An Anchor structure or NULL on failure.
  220.  
  221.    EXAMPLE
  222.        see examples programs
  223.  
  224.    NOTES
  225.        THe Anchor structure should not be accessed directly. Apart from
  226.        that, there isn't anything it it you really want to see...
  227.  
  228.        The Color model is required since RTGGadTools must select the
  229.        appropriate functions when using the default rendering method.
  230.  
  231.    BUGS
  232.        none known.
  233.  
  234.    SEE ALSO
  235.        RGDoGadgets(), RGAddGadget(), RGRemGadget()
  236.  
  237. RTGGadTools/RGNewGadget                               RTGGadTools/RGNewGadget
  238.  
  239.    NAME   
  240.        RGNewGadget -- Create a new RTGGadTools Gadget (V1)
  241.  
  242.    SYNOPSIS
  243.        gadget = RGNewGadget(tags);
  244.        D0                   A0
  245.        RGGadget RGNewGadget(struct TagItem *);
  246.  
  247.        gadget = RGNewGadgetTags(tag1...);
  248.        RGGadget RGNewGadget(Tag ...);
  249.  
  250.    FUNCTION
  251.        This function creates a new gadget with the parameters given
  252.        in the taglist. The gadget's parameters must be passed via a
  253.        taglist. Ommitted parameters will be given default values.
  254.  
  255.    INPUTS
  256.        This functions accepts the following tag items:
  257.  
  258.        RGG_LeftEdge
  259.        RGG_TopEdge
  260.        RGG_Width
  261.        RGG_Height          (ULONG)
  262.            The Obvious. If you don't specify LeftEdge or TopEdge,
  263.            zero will be assumed. Width and Height are calculated to
  264.            the best of knowledge when the gadget is created, but
  265.            this is very likely to break. Better specify everything.
  266.  
  267.        RGG_RenderText      (STRPTR)
  268.            Gives a text string that should be rendered inside the
  269.            gadget
  270.  
  271.        RGG_RenderImage     (APTR)
  272.            The rectangular area pointed to by his tag value is to be
  273.            used as the source for a WritePixelArray/WritePixelRGBArray
  274.            when rendering this gadget. Note that you *MUST* specify
  275.            Width and Height if you want to use this feature. See
  276.            also RGG_SelectRender
  277.  
  278.        RGG_SelectRender    (APTR)
  279.            Gives a pointer to an alternate image to be drawn when the
  280.            button is pressed. Only valid if a RGG_RenderImage was given,
  281.            will be ignored otherwise. Images should match in size, or
  282.            you will get artefacts from improper deleting images.
  283.  
  284.        RGG_UpAction        (function or ULONG)
  285.            Depending on the flags value, the value of this tag item
  286.            is interpreted either as a function which is to be called
  287.            when the gadget is pressed (if the RGF_UpAction flag is set)
  288.            or an ULONG which is returned by RGDoGadgets(). This function
  289.            is called with a pointer to the gadget structure in register
  290.            a0.
  291.  
  292.        RGG_DownAction      (function or ULONG)
  293.            Same as RGG_UpAction when the gadget is released...
  294.  
  295.        RGG_RenderHook      (function pointer)
  296.            When this TagItem is given, the value is interpreted as a
  297.            function that gets called whenever the gadget needs to be
  298.            rendered. The function is called with these parameters:
  299.  
  300.            A0: Pointer to the gadget structure
  301.  
  302.            It is completely up to you what this function does. You should
  303.            however examine the flags word in the gadget structure and
  304.            take care of the RGF_Selected and RGF_Disabled flags when
  305.            rendering...
  306.  
  307.        RGG_HitTest         (function pointer)
  308.            If you need arbitrarily shaped gadgets, you can insert your
  309.            own hittest here. Normally, gadgets assume they are hit
  310.            if their HitBox got clicked. If you want parts of your gadget
  311.            to react different, supply this method. The function gets
  312.            called with these parameters:
  313.  
  314.            A0:     Pointer to the gadget structure
  315.            D0/D1:  X/Y coords of mouse hit.
  316.  
  317.            The coordinates you receive are absolute screen coordinates,
  318.            and there's no guarantee that they are within you bounding
  319.            box. This means that you could (theoretically) create gadgets
  320.            with hit areas bigger than their bounding box. This is, however,
  321.            considered bad behaviour.
  322.  
  323.            You should clear D0 on return to indicate your gadget has
  324.            been missed, or TRUE otherwise.
  325.  
  326.        RGG_Flags           (ULONG)
  327.            One of the #define'd flags. See rtggadtools.h
  328.  
  329.        RGG_HiPen
  330.        RGG_LoPen
  331.        RGG_TextPen         (UWORD)
  332.            A pen value (i.e. 0..2^depth) for the "highlighted" edges of
  333.            the 3D frame, "shadowed edges" and the text color, respectively
  334.  
  335.  
  336.    RESULT
  337.        gadget  -   NULL in case an error occured during creation.
  338.                    otherwise an RGGadget.
  339.  
  340.    EXAMPLE
  341.        see examples programs provieded with this package
  342.  
  343.    NOTES
  344.        The RGGadget structure is read_only. You may not directly modify
  345.        the values, use RGSetAttr().
  346.  
  347.    BUGS
  348.        Many, probably.
  349.  
  350.    SEE ALSO
  351.        RGDoGadgets(), RGSetAttrs()
  352.  
  353. RTGGadTools/RGRefreshGList                         RTGGadTools/RGRefreshGList
  354.  
  355.    NAME   
  356.        RGRefreshGList -- Redraw a list of gadgets (V1)
  357.  
  358.    SYNOPSIS
  359.        RGRefreshGList(anchor, gadget, num);
  360.                       A0      A1      D0
  361.        void RGRefreshGList(APTR, RGGadget, LONG);
  362.  
  363.    FUNCTION
  364.        Refresh a number of gadgets (redraw them), starting from gadget
  365.        in anchor, drawing num gadgets. The gadgets are drawn in every
  366.        available buffer to fix problems with double buffering.
  367.  
  368.    INPUTS
  369.        anchor  -   A valid Anchor structure
  370.        gadget  -   A gadget within this anchor, or NULL for all gadgets
  371.        num     -   Number of gadgets to draw. May be -1 to redraw all
  372.                    gadgets after gadget.
  373.  
  374.    RESULT
  375.        This function does not have a return value.
  376.  
  377.    EXAMPLE
  378.        see example programs
  379.  
  380.    NOTES
  381.        Handling gadgets consistantly on multi-buffered screens is a
  382.        bit of a problem with the minimal control RTGGadTools has
  383.        over the screen switching process. Therefore, every time a
  384.        gadget is redrawn, it is redrawn in every buffer. This should
  385.        not pose too much overhead, since gadgets are usually small.
  386.        This behavior might change in future version.
  387.  
  388.  
  389.    BUGS
  390.        None known.
  391.  
  392.    SEE ALSO
  393.        RGNewAnchor(), RGDoGadgets(), RGNewGadget()
  394.  
  395. RTGGadTools/RGRemGadget                               RTGGadTools/RGRemGadget
  396.  
  397.    NAME   
  398.        RGRemGadget -- Remove a gadget from the active list (V1)
  399.  
  400.    SYNOPSIS
  401.        gad=RGRemGadget(anchor, gadget);
  402.        D0              A0      A1
  403.        RGGadget RGRemGadget(APTR, RGGadget);
  404.  
  405.    FUNCTION
  406.        Remove the gadget from the anchor's list.
  407.  
  408.    INPUTS
  409.        anchor  -   The Gadget Anchor
  410.        gadget  -   Gadget to remove
  411.  
  412.    RESULT
  413.        gad     -   Pointer to the removed gadget or NULL on failure
  414.  
  415.    EXAMPLE
  416.        see example programs
  417.  
  418.    NOTES
  419.        Gadgets removed from the list will not be handled anymore by
  420.        RGDoGadgets().
  421.  
  422.    BUGS
  423.        None known.
  424.  
  425.    SEE ALSO
  426.        RGDoGadget(), RGAddGadget();
  427.  
  428.