Article
06/13/2011

MouseLeftButtonDown

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Occurs when the left mouse button is pressed while the mouse is over the object (or the mouse is captured).

<object MouseLeftButtonDown="eventhandlerFunction".../>

[token = ]object.AddEventListener("MouseLeftButtonDown", eventhandlerFunction)

Arguments

AddEventListener Parameters

token

integer

A token that is returned from the function, which you can optionally retain as a variable. If you intend to call RemoveEventListener to remove the handler, you will need this token.

eventhandlerFunction

object

The name of your event handler function as it is defined in script. When used as an AddEventListener parameter, quotation marks around the function name are not required. (See the "Remarks" section.)

Event Handler Parameters

sender

object

The object that invoked the event.

mouseButtonEventArgs

object

MouseButtonEventArgs

mouseButtonEventArgs.GetPosition(element).X identifies the x-coordinate position of the mouse.

mouseButtonEventArgs.GetPosition(element).Y identifies the y-coordinate position of the mouse.

mouseButtonEventArgs.Shift determines whether the SHIFT key is down.

mouseButtonEventArgs.Ctrl determines whether the CTRL key is down.

mouseButtonEventArgs.Handled: A Boolean value that determines whether event routing should continue. (Silverlight 2)

mouseButtonEventArgs.Source: Reports the object that raised the event. (Silverlight 2)

Managed Equivalent

MouseLeftButtonDown

Remarks

The MouseLeftButtonDown event can be defined for any UIElement-derived class, such as Canvas, TextBlock, or Rectangle.

The MouseLeftButtonDown event is raised when the left mouse button is pressed while the mouse pointer is over the object. When the mouse button is released, the MouseLeftButtonUp event is raised. However, if the mouse pointer is moved over another object when the button is released, the object that received the MouseLeftButtonDown event will not receive the MouseLeftButtonUp event. There is no discrete double-click event. A double-click consists of two sequences of MouseLeftButtonDown and MouseLeftButtonUp events.

The MouseLeftButtonDown event is a bubbling event. This means that if multiple MouseLeftButtonDown events are defined for a tree of elements, the event is received by each object in the object hierarchy, starting with the object that directly receives the event, and then bubbles to each successive parent element. The bubbling metaphor indicates that the event starts at the bottom and works its way up the object tree. For a bubbling event, the sender parameter identifies the object where the event is handled, not necessarily the object that actually received the input condition that initiated the event.

For more information on basic concepts, see Mouse Support. Note that the Mouse Support topic is written primarily for users of the managed API, and may not have code examples or specific information that address the JavaScript API scenarios.

You can also add handlers in script by using a quoted string for the event handler name, as follows:

object.AddEventListener("MouseLeftButtonDown", "eventhandlerFunction")

This syntax also returns a token. However, the token is not an absolute requirement for removing the handler in cases where the handler was added by using a quoted string. For details, see RemoveEventListener.

Example

The following XAML example illustrates event bubbling. It shows MouseLeftButtonDown events defined for two Canvas objects and one TextBlock object. In this case, if you press the mouse button when the pointer is over the TextBlock object, it receives the MouseLeftButtonDown event. The event then bubbles up to the parent Canvas, and finally to the top-level Canvas object.

<!-- The TextBlock event occurs first. -->
<Canvas 
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  MouseLeftButtonDown="rootCanvasMouseLeftButtonDown">

  <Canvas
    Canvas.Left="20" Canvas.Top="20"
    MouseLeftButtonDown="canvasMouseLeftButtonDown">

    <TextBlock 
      x:Name="myTextBlock" 
      Canvas.Left="25" Canvas.Top="5"
      MouseLeftButtonDown="textMouseLeftButtonDown"
      FontSize="24"
      Text="Click me" />

  </Canvas>
</Canvas>

The following JavaScript example shows how to implement a MouseLeftButtonDown event handler function.

function rootCanvasMouseLeftButtonDown(sender, mouseEventArgs)
{
    // Set the TextBlock to display the mouse position.
    sender.findName("myTextBlock").text = "x = " + mouseEventArgs.getPosition(null).x + "  y = " + mouseEventArgs.getPosition(null).y;
}