Name: mouseWithin

Type: message

Syntax: mouseWithin

Summary:
Sent periodically to an <object(glossary)> while the <mouse pointer> is
within its borders.

Associations: stack, card, field, button, graphic, scrollbar, player,
image

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Description:
Handle the <mouseWithin> <message> to perform some repeating task (such
as an update) for as long as the <mouse pointer> is over a <control>.

The period between <mouseWithin> <message|messages> is specified by the
<idleRate> and <idleTicks> <properties>.

The <mouseWithin> <message> is sent only when the <Browse tool> is being
used. 

If two controls overlap, a <mouseWithin> <message> is sent whenever the
<mouse pointer> is in a visible portion of a <control>. The <control> on
the bottom receives a <mouseWithin> <message> only when the <mouse
pointer> is in a portion of the <control> that can be seen. A <control>
that is completely hidden by another <control> on top of it will never
receive a <mouseWithin> <message>.

If the mouse button is down when the mouse pointer enters the control,
no <mouseWithin> <message|messages> are sent until the mouse button is
released. If the <mouse pointer> leaves the <control> while the 
<mouse button> is still down, no <mouseWithin> <message|messages> are 
sent. If the <mouse button> is pressed while the <pointer> is in the 
<control>, however, <mouseWithin> <message|messages> continue to be 
sent, even while the <mouse button> is down.

Usually, it is easier and more efficient to use the mouseMove <message>
to track the movement of the mouse while the button is being held down.
The <mouseWithin> <message> is sent continually and must be handled
several times a second, taking up a great deal of processor time. The
<mouseMove> <message> is sent only when the mouse is moved, making it
more efficient.

>*Note:* If there is no <mouseWithin> <handler> in the target
> <object|object's> <script>, no <mouseWithin> <message> is sent, even
> if there is a <mouseWithin> <handler> in an <object(glossary)> that's
> further along the <message path>.

References: focus (command), object (glossary), handler (glossary),
Browse tool (glossary), mouse button (glossary), message (glossary),
message path (glossary), control (glossary), mouse pointer (glossary),
pointer (keyword), mouseMove (message), mouseLeave (message),
script (property), properties (property), idleRate (property),
idleTicks (property)

Tags: ui

