@database bebox.guide

@$VER: BeBox V1.10 - (C)Copyright Amiga Foundation Classes

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node Main "Amiga Foundation Classes: BeBox"



                       ** BeBox  - Original By Fabio Rotondo **

                       * Part of the Amiga Foundation Classes *

        @{" Introduction " link "BeBox_introduction"}             @{" Author's Info " link "author"}        @{" Amiga Foundation Classes " LINK "AFC.Guide/main"}

   Requires: Nothing.

   Class Base: $000C0000

   NEW COMMANDS                          BRIEF DESCRIPTION
   -------------------------------------------------------------------------
   @{" bebox(x=0,y=0,w=0,h=0)              " link "BeBox_BeBox"} Initailizes the class.
   @{" check(x,y)                          " link "BeBox_Check"} Checks if coords hit the box.
   @{" draw(mode=TRUE)                     " link "BeBox_Draw"} Draws the box.
   @{" error()                             " link "BeBox_Error"} Returns last error raised.
   @{" get(tag)                            " link "BeBox_Get"} Gets class values.
   @{" setattrs(tags)                      " link "BeBox_SetAttrs"} Sets class attributes.
   @{" version()                           " link "BeBox_version"} Returns BeBox version.

   @{" BeBox Structure                     " link "BeBox_Structure"}

   @{" Error Table " LINK BeBox_ErrorTable}
@endnode

@node "BeBox_Introduction" "Introduction"

  BeBox is a class to handle a "sensible" area on the screen.
  It is as simple as powerful: you can hook a procedure to add to the BeBox a
  drawing routine, or to teach it how to move on the screen.

  It can return relative mouse coordinates and so on.

  This class is _very_ useful. You'll learn how to use it.

@endnode

@node "author" "Author's Info"

    Original By:    Fabio Rotondo  (fsoft@intercom.it)

    E Version By:   Fabio Rotondo

    C++ Version By: Massimo Tantignone (tanti@intercom.it)


    Address:

            Fabio Rotondo
            C.so Vercelli 9
            28100 Novara
            ITALY

            e-mail: fsoft@intercom.it
                    Fabio.Rotondo@deagostini.it

            Phone:  (ITA) - (0)321 -   459676  (home)
                    (ITA) - (0)2   - 38086520  (office)
                    (ITA) - (0)338 -  7336477  (GSM Phone)

            Fax:    (ITA) - (0)2   - 38086278

            Web:    http://www.intercom.it/~fsoft               (my home page)

                    http://www.intercom.it/~fsoft/ablast.html   (Amiga Blast Home Page)

@endnode

@node BeBox_ErrorTable "BeBox / Error Table "

VALUE           | DESCRIPTION
----------------+----------------------------------
$0000           | No Memory.
@endnode

@node BeBox_Structure "BeBox Structure"

  BeBox Structure

  Here there is a very quick explanation of the BeBox Structure.
  Please, remember that these fields are *READ ONLY*: use tags
  to modify them!

  OBJECT bebox_data
    oldx  :INT              -> Old X Pos
    oldy  :INT              -> Old Y Pos
    oldw  :INT              -> Old width value
    oldh  :INT              -> Old height value
    oldcol:INT              -> Old color used

    x   :INT                -> Actual X Position
    y   :INT                -> Actual Y Position
    w   :INT                -> Width and Height
    h   :INT
    relx:INT                -> Last Relative Mouse Click inside the Box
    rely:INT

    minx:INT                -> min x,y bounds
    miny:INT
    maxx:INT                -> max x,y bounds
    maxy:INT

    rp  :PTR TO rastport    -> Rastport where to draw on.

    col :INT                -> Color to use

    userel:CHAR             -> This is a flag: TRUE means auto relative coords
    user  :PTR TO LONG      -> Pointer to anything
  ENDOBJECT

@endnode

@node "BeBox_bebox" "Amiga Foundation Classes: BeBox/bebox()"

           NAME: bebox(x=0, y=0, w=0, h=0)

       SYNOPSIS: bebox(ULONG x = 0, ULONG y = 0, ULONG w = 0, ULONG h = 0)

    DESCRIPTION: This is the class constructor. If you want, you can
                 pass the box dimensions and positions, while creating
                 the object.

          INPUT: x, y   - (Optional) Box left and top position.

                 w, h   - (Optional) Box width and height.


        RESULTS:

       SEE ALSO:
@endnode

@node "BeBox_setattrs" "Amiga Foundation Classes: BeBox/setattrs()"

           NAME: setattrs(tags:PTR TO LONG)

       SYNOPSIS: setattrs(struct TagItem *tags)

    DESCRIPTION: This method is used to change Box attributes, such
                 as dimensions, positions and so on.
                 It is *the only way* to access to BeBox class structure.

          INPUT: tags     - (PTR TO LONG) taglist. Avaible tags are:


              SIZE:

                 BB_WIDTH    - Box's Width
                 BB_HEIGHT   - Box's Height
                 BB_ENDX     - Box's end X coord (instead of specify the Width, you
                               just specify box's end x position: BeBox will
                               compute automagically the width for you).
                 BB_ENDY     - Box's end Y coord.

            COORDS:

                 BB_POSX     - Box's X Position

                 BB_POSY     - Box's Y Position

                 BB_RELX     - Box's Relative X coord. You can specify an "offset"
                               that will be added to the box's X coord.
                 BB_RELY     - Box's Relative Y coord.

                 BB_OLDX     - Box's last x position. (-1 = erase last value)

                 BB_OLDY     - Box's last y position. (-1 = erase last value)

            BOUNDS:

                 You can "bound" the box inside a rectangle. With the following
                 tags you can set the coords of that rectangle.
                 Please note that MAXX and MAXY refer to box's x+width.


                 BB_MINX     - Box's Min X coord.
                 BB_MINY     - Box's Min Y coord.
                 BB_MAXX     - Box's Max X coord.
                 BB_MAXY     - Box's Max Y coord.

           GRAPHIC:

                 You can set rastport, draw color and other values.
                 Here come the tags...

                 BB_RPORT    - Box's rastport to draw on.

                 BB_COL      - Box's drawing color.

                 BB_USEREL   - This is a flag: if set to TRUE, box will compute
                               new coords by checking mouse coords inside the box.

                 BB_DRAW     - You can assign a pointer to a function right here.
                               The destination function *must* accept the following
                               parameters, in this order:

                                  drawingproc(data:PTR TO bebox_data, mode)

                               where data is a PTR TO a @{" bebox_data " LINK bebox_structure}
                               structure.

                               Mode is a flag: TRUE means "draw", while FALSE means
                               "delete obj from the screen".

              USER:

                 BB_USER     - Box's user tag. Place here whatever you want.

        RESULTS:

       SEE ALSO: @{" get() " LINK bebox_get}
@endnode

@node "BeBox_get" "Amiga Foundation Classes: BeBox/get()"

           NAME: get(tagname)

       SYNOPSIS: APTR get(ULONG tag)

    DESCRIPTION: This method returns the current value of the specified
                 tag. Please refer to @{" setattrs() " LINK bebox_setattrs} for a
                 complete list of tags.

          INPUT: tagname      - Tag to query the value.

        RESULTS: a LONG value containing the result

       SEE ALSO: @{" setattrs() " LINK bebox_setattrs}
@endnode

@node "BeBox_check" "Amiga Foundation Classes: BeBox/check()"

           NAME: check(x, y)

       SYNOPSIS: BOOL check(ULONG x, ULONG y)

    DESCRIPTION: This method checks the given coords and returns
                 whether they are inside or outside the bebox.

          INPUT: x,y          - Corrdinates to check.

        RESULTS: TRUE         - The coords are inside the box.

                 FALSE        - Coords are outside the box.

       SEE ALSO:
@endnode

@node "BeBox_draw" "Amiga Foundation Classes: BeBox/draw()"

           NAME: draw(mode = TRUE)

       SYNOPSIS: void draw(BOOL mode = TRUE)

    DESCRIPTION: This method invokes the drawing routine.

          INPUT: mode     - (Optional) If TRUE then the box will be drawn on the
                            screen. If FALSE the box will be erased from the screen.
                            Default: TRUE.

        RESULTS:

       SEE ALSO:
@endnode

@node "BeBox_version" "Amiga Foundation Classes: BeBox/version()"

           NAME: version()

       SYNOPSIS: ULONG version(BOOL revision = FALSE)

    DESCRIPTION: This method returns class version and revision.

          INPUT: NONE.

        RESULTS: this method returns TWO values: VERSION and REVISION.

       SEE ALSO:
@endnode

@node "BeBox_error" "Amiga Foundation Classes: BeBox/error()"

           NAME: error()

       SYNOPSIS: ULONG error(void)

    DESCRIPTION: This method returns the last error raised.

          INPUT: NONE.

        RESULTS: the last error raised by this class.

       SEE ALSO:
@endnode

