Name: mouseWithin

Type: message

Syntax: mouseWithin

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

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,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> that's further along the <message path>.

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

Tags: ui
