mouse.doc

这是一个C++编程文档

	0x40	CB_RELEASED

	Table 1: Mouse events
-----------------------------------------------------------------------

A Demonstration

    demo.cpp  is a demo program that utilizes most of the  mouse  func-
tions described.  main() installs the event handler,  runs a text  mode
demo, and a graphics mode demo.  The event mask is FFh which will trig-
ger the handler on any mouse event. Since that includes mouse movement,
the default handler that only calls Save() is used to store the parame-
ters and keep execution time to a minimum.

    Both  demos  (textdemo() and graphicdemo()) call  a  function  that
draws the screen and another that processes mouse events.  textscreen()
assumes  a  color video card and draws a screen  with  eight  different
characters and colors to demonstrate how the cursor masks work.  Notice
that  the loop that draws the screen actually writes 50 lines of  video
even though the demo starts out with 25 lines.  A graphical representa-
tion  of a three-button mouse is drawn to show the cursor position  and
button status. After calling textscreen(), textdemo() prints the infor-
mation from the mouse.Info structure to the screen.  The mouse  y-limit
is  set to full screen (25 lines, which is the default) and the  cursor
is turned on with Show().  nexttdemo() is the processing loop for  text
mode  and is called with the name of text cursor structure and a  title
string.  nexttdemo() is called with several different cursors and  also
for 43/50 line mode.

    nexttdemo() first sets the text cursor and prints the title string.
It then runs a loop that process mouse events. A counter that shows the
mouse position calls x() and y() which read variables that are  contin-
uously  updated by the event handler via GetEvent().  Button status  is
also  checked and displayed.  Released() is called to check for a  left
button release event which will terminate the loop if the cursor is in-
side the [Next] box at the time of release.  The loop will also be ter-
minated  if the right button is double-clicked anywhere on the  screen.
If the center button is double-clicked, the mouse is disabled until any
keyboard key is pressed.  Pressing the <Shift> key and the left  button
will  switch video pages (note that the alternate video page lacks  all
the  functionality of the main page).  Pressing the <Ctrl> key  and the
left button will set the global flag "done" which exits the rest of the
text demo and proceeds with the graphics demo.

    graphicdemo()  works  the same way as textdemo().  In  addition  to
trying several cursors, it also tests different mickey-to-pixel ratios.
Notice that the ratio of 2 for the jet cursor will cause the cursor  to
locate  on every fourth pixel as it moves across the  screen.  graphic-
screen()  paints several background colors as well as black  and  white
boxes in the center. These boxes demonstrate the use of the cursor bor-
der created by the screen mask.  A graphical representation of a three-
button mouse is again drawn to show the cursor position and button sta-
tus.  nextgdemo()  sets the graphics cursor and  then  processes  mouse
events,  checking the position and button status.  The last cursor is a
ColorGraphicsCursor that is 9x39 pixels.

    During  the  graphics demo any multiclick events are  displayed  as
different colors of the buttons on the screen (up to four).  The center
button  is  set up as a repeater button, so that holding it  down  will
generate multiple PRESSED events as well as multiclicks. A right button
triple-click  will advance to the next cursor,  and <Ctrl>-left  button
will exit the demo.

-----------------------------------------------------------------------

Supporting SuperVGA/VESA Modes

    As mentioned before,  the mouse driver performs the draw &  restore
for the graphics cursor as it moves across the screen.  The drivers  do
not  currently support color cursors or video modes beyond  640x480x16.
The ColorGraphicsCursor feature of Mouse++ shows how color cursors  can
be supported by manually drawing the cursor.  This method can be exten-
ded to higher resolutions by modifying the VideoDraw() and CursorDraw()
functions.

    If you are using a third party graphics library, the best method of
supporting color or high-res modes is to simply use the functions  that
are available in the library for manipulating bit images.  In the  BGI,
these are getimage() and putimage().  The file cgc_bgi.cpp contains the
code that uses the BGI to display the cursor.  This approach is  incom-
plete in that it does not properly mask the cursor at the edges of  the
screen (to display a partial cursor) nor does it attempt to insure that
the viewport is set to the entire screen.  The ColorGraphicsCursor con-
structor  in cgc_bgi.cpp converts the cgc image array to the BGI  image
format,  after which getimage() and putimage() are used to display  the
cursor.

    The BGI,  however, also does not support SuperVGA or VESA modes  as
provided by Borland.  There is a set of VESA BGI drivers available that
extend the BGI up to 1024x768x256. They are shareware and are available
from the address listed below.  Using these drivers would allow cursors
to be displayed in any mode,  but you would still have to take care  of
masking the image at the screen edges and taking care of the viewport.

BGI VESA Drivers:

 Jordan Powell Hargrave          Internet: [e-mail]
 1000 Morewood Ave, Box #3277      Bitnet: jh5y%andrew.cmu.edu@cmccvb
 Pittsburgh, PA 15213                UUCP: uunet!andrew.cmu.edu!jh5y
 [phone]                Compuserve: [72510,1143]

-----------------------------------------------------------------------

The Mouse++ Functions

-----------------------------------------------------------------------
Mouse::Exists()

Syntax: 	unsigned char Exists(void)

Description:	Returns the value of an internal flag that is set by
		the Mouse constructor.

Return Value:	1 if a mouse was found, 0 otherwise.

-----------------------------------------------------------------------
Mouse::Visible()

Syntax: 	unsigned char Visible(void)

Description:	Returns the status of the cursor visibility.

Return Value:	1 if the cursor is visible, 0 otherwise.

-----------------------------------------------------------------------
Mouse::Buttons()

Syntax: 	unsigned char Buttons(void)

Description:	Returns the number of buttons for the mouse

Return Value:	2 for a 2-button mouse, 3 for a 3-button mouse.

-----------------------------------------------------------------------
Mouse::Button()

Syntax: 	unsigned char Button(void)

Description:	Returns the status of the mouse buttons and shift keys
		that is stored internal to the Mouse class. Call
		Position() before using this function to insure an
		accurate value, or when using the event handler call
		GetEvent().

Return Value:	A mask corresponding to the status of the mouse buttons
		and the shift keys (down=1, up=0):
		-------------------------------------------------------
		0x01	Left button
		0x02	Right button
		0x04	Center button
		0x08	Either shift key
		0x10	Right shift key
		0x20	Left shift key
		0x40	Alt key
		0x80	Ctrl key

-----------------------------------------------------------------------
Mouse::Enable()

Syntax: 	void Enable(void)

Description:	Enables the mouse. This function must be called before
		the mouse can be used for the first time, or after a
		call to Disable(). A separate call to Show() is neces-
		sary to display the cursor.

Return Value:	None.

-----------------------------------------------------------------------
Mouse::Disable()

Syntax: 	void Disable(void)

Description:	Disables the mouse and hides the cursor. If an event
		handler has been installed, it is disabled and the
		event buffer and multi-click buffer are cleared.

Return Value:	None.

-----------------------------------------------------------------------
Mouse::Show()

Syntax: 	void Show(void)

Description:	Turns on the mouse cursor.

Return Value:	None. Sets the internal visible flag to 1.

-----------------------------------------------------------------------
Mouse::Hide()

Syntax: 	void Hide(void)

Description:	Turns off the mouse cursor. All other mouse functions
		will continue to operate. You should hide the cursor
		prior to any screen writes to avoid having the mouse
		restore an incorrect background.

Return Value:	None. Sets the internal visible flag to 0.

-----------------------------------------------------------------------
Mouse::Position()

Syntax: 	void Position(void)

Description:	Reads the cursor position and saves the coordinates
		in internal variables. Use x() & y() to read the inter-
                nal variables. This function is not intended for use
                with the event handler.

Return Value:	None. Sets internal class position variables and button
		status.

-----------------------------------------------------------------------
Mouse::x()

Syntax: 	int x(void)

Description:	Returns the x-position of the mouse cursor that is
		stored internal to the Mouse class. Call Position()
		before using this function to insure an accurate
		value, or when using the event handler call GetEvent().

Return Value:	An integer that corresponds to the pixel location of
		the cursor, even if the screen is in text mode.

-----------------------------------------------------------------------
Mouse::y()

Syntax: 	int y(void)

Description:	Returns the y-position of the mouse cursor that is
		stored internal to the Mouse class. Call Position()
		before using this function to insure an accurate
		value, or when using the event handler call GetEvent().

Return Value:	An integer that corresponds to the pixel location of
		the cursor, even if the screen is in text mode.

-----------------------------------------------------------------------
Mouse::Motion()

Syntax: 	void Motion(void)

Description:	Reads the internal motion counters which give the dis-
		tance (in mickeys) the mouse has moved since the last
		call to this function, and stores the values in class
		variables. Use xCount() & yCount() to read these vari-
		ables. This function is not intended for use with the
		event handler.

Return Value:	None.

-----------------------------------------------------------------------
Mouse::xCount()

Syntax: 	int xCount(void)

Description:	Returns the distance the mouse has moved in the x-
		direction. The distance is in mickeys, which may or may
		not be the same as pixels, depending on the mickey-to-
		pixel ratio. This function is useful for seeing if the
		mouse has moved.

Return Value:	An integer that corresponds to the x distance in mic-
		keys, regardless of screen mode.

-----------------------------------------------------------------------
Mouse::yCount()

Syntax: 	int yCount(void)

Description:	Returns the distance the mouse has moved in the y-
		direction. The distance is in mickeys, which may or may
		not be the same as pixels, depending on the mickey-to-
		pixel ratio. This function is useful for seeing if the
		mouse has moved.

Return Value:	An integer that corresponds to the y distance in mic-
		keys, regardless of screen mode.

-----------------------------------------------------------------------
Mouse::Move()

Syntax: 	void Move(int x, int y)

Description:	Moves the cursor to a new position. x & y must be
		pixel coordinates even if the screen is in text mode.

Return Value:	None.

-----------------------------------------------------------------------
Mouse::Pressed()

Syntax: 	int Pressed(int button)

Description:	In manual mode, this checks to see if button has been
		pressed since the last call to this command. In event
		driven mode, this checks to see if the current event
		was triggered by button being pressed. button can be 0
		(LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON).

Return Value:	1 if button has a pressed event, 0 otherwise.