Shareware Overload/ShartewareOverload.cdr/progm/flash-c1.zip/CH6_1.DOC

Text File | 1990-02-11 | 16KB | 654 lines

..pgno01
..foot63A6-##
..head02L──────────────────────────────────────────────────────────────────────
..head04L──────────────────────────────────────────────────────────────────────
..head03LGlobal Variables
UINT NEvents       contains the number of events waiting in the mouse
                   event handler queue.
..page
..head03AMButtonPress
■ Description

  Returns the current button status information.


■ Summary

  Function MButtonPress(     Button   : Integer;
                         Var ButPress : Integer;
                         Var x, y     : Integer ) : Integer;

  Button      specifies the button to check.
                 0 - left button
                 1 - right button
                 2 - middle button

  ButPress    number of button presses since the last call to
              MButtonPress.

  x           column the mouse cursor was in the last time the button
              was pressed.

  y           row the mouse cursor was in the last time the button was
              pressed.


■ Remarks

  MButtonPress will return an integer indicating the current state of
  the mouse button requested.

     0 - Button is released
     1 - Button is pressed
..page
■ Example

  #include <fpclib.h>

  main()
  {
     INT NBut,ButPresses,x,y
     if ( MResetMouse( &NBut ) ) {

        MInitEventHandler( 14 );
        while ( NEvents < 10 )
        ;

        printf( "left button status is ==> " );

        switch ( MButtonPress( 0, &ButPresses, &x, &y ) ) {
           case 0 : printf( "UP" );
           case 1 : printf( "DOWN" );
        }

        printf( "\n\nTotal Button presses = %u", ButPresses );
     }
  }

  This example will report the number of times the left button was
  pressed and also the current state of the left button.
..page
..head03AMButtonRel
■ Description

  Returns the current button status information.


■ Summary

  Function MButtonRel(     Button   : Integer;
                       Var ButPress : Integer;
                       Var x, y     : Integer ) : Integer;

  Button      specifies the button to check.
                 0 - left button
                 1 - right button
                 2 - middle button

  ButPress    number of button releases since the last call to
              MButtonRel.

  x           column the mouse cursor was in the last time the button
              was released.

  y           row the mouse cursor was in the last time the button was
              released.


■ Remarks

  MButtonReleased will return an integer indicating the current state
  of the mouse button requested.
     0 - Button is released
     1 - Button is pressed
..page
■ Example

  #include <fpclib.h>

  main()
  {
     INT NBut,ButPresses,x,y
     if ( MResetMouse( &NBut ) ) {

        MInitEventHandler( 14 );
        while ( NEvents < 10 )
        ;

        printf( "left button status is ==> " );

        switch ( MButtonRel( 0, &ButPresses, &x, &y ) ) {
           case 0 : printf( "UP" );
           case 1 : printf( "DOWN" );
        }

        printf( "\n\nTotal Button releases = %u", ButPresses );
     }
  }

  This example will report the number of times the left button was
  released and also the current state of the left button.
..page
..head03AMGetPos
■ Description

  Returns the current button status and the location of the mouse
  cursor.


■ Summary

  Procedure MGetPos( Var Button, x, y : Integer );

  Button      returns the status of each button by its corresponding
              bit value. If a bit is 0 then that button is up.  If a
              bit is 1 then that button is pressed.

              Bit  Value  Button
              ───  ───── ─────────────
              0     1    left button
              1     2    right button
              2     4    middle button

  x           column the mouse cursor is in.

  y           row the mouse cursor is in.


■ Remarks

  In 80 column text mode the upper left corner of the screen is 1,1
  and the lower right corner is 80,25.


■ Example

  MGetPos( &ButStat, &x, &y );

  if ( ButStat & 1 )
     printf( "button is pressed" );

  if ( ButStat & 2 )
     printf( "button is pressed" );

  if ( ButStat & 4 )
     printf( "button is pressed" );

  printf( "The cursor is located at %u,%u", x, y );
..page
..head03AMGetSpeed
■ Description

  Returns the distance the mouse has moved since the last call to this
  routine.


■ Summary

  Procedure MGetSpeed( Var HorCnt, VerCnt : Integer );

  HorCnt      returns horizontal step count since last call.

  VerCnt      returns vertical step count since last call.


■ Remarks

  The step count is always in the range -32768 to 32767. A positive
  value specifies movements to the right and down while negative
  values specify movements to the left and up.  After the call is
  completed the step counts are reset to zero.

■ Example

  MGetSpeed( &HorCnt, &VerCnt );

  if ( HorCnt > 0 )
     printf(" Mouse moved to the right ")
  else if ( HorCnt < 0 )
     printf(" Mouse moved to the left ")
  else
     printf(" Mouse did not move horizontally" );

  This example will report the horizontal direction the mouse has
  moved since the last call to this routine.
..page
..head03AMGraphCursor
■ Description

  Defines the shape and color of the mouse cursor when in graphics
  mode.

■ Summary

  Procedure MGraphCursor( XHotSpot, YHotSpot : Integer;
                          CMaskSeg, CMaskOfs : Word    );

  XHotSpot    a value in the range -16 to 16 used to define the X
              pixel within or outside the cursor block

  YHotSpot    a value in the range -16 to 16 used to define the Y
              pixel within or outside the cursor block.

  CMaskSeg    the segment of the cursor mask description variable.

  CMaskOfs    the offset of the cursor mask description variable.


■ Remarks

  The cursor mask variable is two arrays of 16 words each.  The first
  16 words define the screen mask and the second 16 words define the
  cursor mask.  Each array of 16 words defines the set of pixels that
  are 16x16.

  The screen mask is used to determine which pixels become part of the
  cursor shape while the cursor mask is used to determine the
  color/shape of the cursor.

■ Example

  UINT CMask[32] =
     {
     0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff,
     0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff, 0xffff,

     0xffff, 0xffff, 0xf00f, 0xf00f, 0xf00f, 0xf00f, 0xf00f, 0xf00f,
     0xf00f, 0xf00f, 0xf00f, 0xf00f, 0xf00f, 0xf00f, 0xffff, 0xffff
     };

  MGraphCursor( -5, 5, FP_SEG( CMask ), FP_OFF( CMask ) );

  The cursor defined by CMask will be a solid block with a smaller
  block inside being a different color.
..page
..head03AMHideCursor
■ Description

  Removes the mouse cursor from the screen.


■ Summary

  Procedure MHideCursor;


■ Remarks

  Although the mouse cursor is hidden from view its motion is still
  tracked.


■ Example

  MHideCursor();
..page
..head03AMInitEventHandler
■ Description

  Initializes the mouse interrupt event handler.


■ Summary

  Procedure MInitEventHandler( EventMask : Integer );

  EventMask   defines the event types the mouse event handler will
              place in its queue.


■ Remarks

  Each bit in the event mask corresponds to a specific event:

  Bit     Value   Event
  ───     ─────   ────────────────────────────────────────
   0         1    cursor position moved
   1         2    left button pressed
   2         4    left button released
   3         8    right button pressed
   4        16    right button released
   5        32    middle button pressed
   6        64    middle button released
   7-15           not used


■ Example

  MInitEventHandler( 4 );

  In this example the only time an event is recorded in the event
  handler queue is when the left button of the mouse is released.
  When this happens the global variable NEvents will be incremented.
  The maximum number of events that is kept in the event queue at one
  time is 20. MRetQue must be used to empty the queue. DO NOT change
  the value of NEvents as this may cause severe problems.

  When you have finished using the event handler you must uninstall
  the event handler with:

  MInitEventHandler( 0 );
..page
..head03AMPollQue
■ Description

  Returns a copy of the oldest event in the mouse event queue.  The
  event queue is left unchanged.


■ Summary

  Procedure MPollQue( Var Event, ButStat, x, y : Integer );

  Event       an integer describing the event that occurred (See
              MInitEventHandler).

  ButStat     button status at time of event.

  x           column mouse cursor was located in at the time of event.

  y           row mouse cursor was located in at the time of event.


■ Remarks

  If the number of events in the queue is zero when this procedure is
  called the values in the return variables will be -1.  Use the
  global variable NEvents to determine if an event is in the queue.

■ Example

  MPollQue( &Event, &ButStat, &x, &y );

  In this example MPollQue is called to get the oldest event
  information without removing the event from the queue.
..page
..head03AMResetMouse
■ Description

  Determines if the mouse hardware and software are installed.


■ Summary

  Function MResetMouse( NBut : Integer ) : Integer;

  Button      returns the number of buttons on the mouse.


■ Remarks

  MResetMouse will return:
      0 - Mouse hardware and software are not installed.
     -1 - Mouse hardware and software are installed.

  Every call to MResetMouse will also reset the position of the mouse
  cursor to the middle of the video dispaly.


■ Example

  #include <fpclib.h>

  main()
  {
     INT NBut;

     if ( !MResetMouse( &NBut ) )
        printf( "Mouse NOT installed on your computer" );
     else {
        printf( "You have a mouse in your computer" );
        printf( "Squeak Squeak Squeak..." );
     }
  }
..page
..head03AMRetQue
■ Description

  Returns the oldest event in the mouse event queue and removes the
  event from the queue.


■ Summary

  Procedure MRetQue( Var Event, ButStat, x, y : Integer );

  Event       returns the event that occurred (see MInitEventHandler).

  ButStat     button status at the time of this event.

  x           column mouse cursor was located in at time of event.

  y           row mouse cursor was located in at time of event.


■ Remarks

  If the number of events in the queue is zero when this procedure is
  called the values in the return variables will be -1.  Use the
  global variable NEvents to determine if an event is in the queue.


■ Example

  #include <fpclib.h>

  main()
  {
     INT NBut;

     if ( MResetMouse( &NBut ) ) {
        MInitEventHandler( 2 );

        while ( NEvents > 0 )
           MRetQue( &Event, &ButStat, &x, &y );
     }
  }

  In this example MRetQue is called until the mouse event queue is
  empty.
..page
..head03AMSetEvent
■ Description

  Simulates a mouse event.


■ Summary


  void MRetQue( INT PTR Event, INT PTR ButStat,
                INT PTR x,     INT PTR y       );

  Event       event that should occur (see MInitEventHandler).

  ButStat     button status for this event.

  x           column of the mouse cursor for this event.

  y           row of the mouse cursor for this event.


■ Remarks

  If the number of events in the queue is less than the maximum number
  of events allowed in the queue then the event will be placed as the
  newest or last mouse event to occur.  All global and local variables
  used for this procedure will be updated exactly the same as if an
  actual mouse event had occurred.

■ Example

  MSetEvent( 1, 0, 80, 25 );

  In this example MSetEvent will place in the mouse event queue an
  event that says the left button was pressed with the position of the
  mouse cursor being at column 80 row 25.
..page
..head03AMSetPos
■ Description

  Set the position of the mouse cursor.


■ Summary

  Procedure MSetPos( x, y : Integer );

  x           column to put mouse cursor in

  y           row to put mouse cursor in


■ Remarks

  Checks for valid X and Y values are NOT performed.  In 80 column
  text mode the upper left corner of the screen is 1,1 and the lower
  right corner is 80,25.

■ Example

  MSetPos( 1, 1 );

  Assuming text mode this example will place the mouse cursor in row
  one column one of the display screen.
..page
..head03AMSetSpeed
■ Description

  Sets mouse motion to screen pixel ratio.


■ Summary

  Procedure MSetSpeed( HorCnt, VerCnt : Integer );

  HorCnt      the horizontal step ratio.  The value is in the range of
              1 to 32767 where the ratio will be HorCnt steps to 8
              pixels horizontally.

  VerCnt      the vertical step ratio.  The value is in the range of 1
              to 32767 where the ratio will be VerCnt steps to 8
              pixels vertically.


■ Remarks

  The step values refer to the amount of mouse movement.

■ Example

  MSetSpeed( 16, 8 );

  This example sets the ratios as follows:
     Horizontal - 16 steps to 8 pixels
     Vertical   - 8 steps to 8 pixels
..page
..head03AMSetXRange
■ Description

  Sets the column boundaries the mouse cursor will be allowed to move
  within.


■ Summary

  Procedure MSetXRange( Min, Max : Integer );

  Min         left column boundary for the mouse cursor.

  Max         right column boundary for the mosue cursor.


■ Remarks

  Range checks are not performed on the parameters.


■ Example

  MSetXRange( 10, 20 );

  In this example the mouse cursor will not be allowed to move to the
  left of column 10 and to the right of column 20.
..page
..head03AMSetYRange
■ Description

  Sets the row boundaries the mouse cursor will be allowed to move
  within.


■ Summary

  Procedure MSetYRange( Min, Max : Integer );

  Min         top row boundary of mouse cursor.

  Max         bottom row boundary of mouse cursor.


■ Remarks

  Range checks are not performed on the parameters.


■ Example

  MSetYRange( 3, 20 );

  In this example the mouse cursor will not be allowed to move above
  row 3 and below row 20.
..page
..head03AMShowCursor
■ Description

  Display the mouse cursor on the screen


■ Summary

  Procedure MShowCursor;


■ Example

  MShowCursor()
..page
..head03AMTextCursor
■ Description

  Defines the mouse text cursor


■ Summary

  Procedure MTextCursor( CType, SMask, CMask : Integer );

  CType       selects the type of mouse cursor to use.
                 0 - software cursor
                 1 - hardware cursor

  SMask       if the software cursor is selected the screen mask is
              defined.  If the hardware cursor is selected the
              starting scan line is defined.

  CMask       if the software cursor is selected the cursor mask is
              defined.  If the hardware cursor is selected the ending
              scan line is defined.

■ Remarks

  The screen mask is an integer that defines which of the character
  attributes are preserved.  The cursor mask is used to determine
  which of the characteristics are changed by the cursor.

  See SetCursor Size in chapter two for a description of the starting
  and ending scan lines.


■ Example

  MTextCursor( CType, SMask, CMask );
..page