Flex coordinate systems

In your application, you might have to determine the location of a component, or modify its location at run time. Adobe Flash and Flex support three coordinate systems for different purposes:

  • global

  • local

  • content

You can use Flex properties and methods to convert between coordinate systems.

About the coordinate systems

The following table describes the coordinate systems:

Coordinate system

Description

global

Coordinates are relative to the upper-left corner of the Stage in Adobe Flash Player and Adobe® AIR™, that is, the outermost edge of the application.

The global coordinate system provides a universal set of coordinates that are independent of the component context. Uses for this coordinate system include determining distances between objects and as an intermediate point in converting between coordinates relative to a subcontrol into coordinates relative to a parent control.

The MouseEvent class includes stageX and stageY properties that are in the global coordinate system.

local

Coordinates are relative to the upper-left corner of the component.

Flex uses the local coordinate system for mouse pointer locations; all components have mouseX and mouseY properties that use the local coordinate system.

The MouseEvent class includes localX and localY properties that are in the local coordinate system. Also, the Drag Manager uses local coordinates in drag-and-drop operations. The doDrag() method’s xOffset and yOffset properties, for example, are offsets relative to the local coordinates.

content

Coordinates are relative to the upper-left corner of the component’s content. Unlike the local and global coordinates, the content coordinates include all the component’s content area, including any regions that are currently clipped and must be accessed by scrolling the component. Thus, if you scrolled down a Canvas container by 100 pixels, the upper-left corner of the visible content is at position 0, 100 in the content coordinates.

You use the content coordinate system to set and get the positions of children of a container that uses absolute positioning. (For more information on absolute positioning, see About component positioning.)

The UIComponent contentMouseX and contentMouseY properties report the mouse pointer location in the content coordinate system.

The following image shows these coordinate systems and how they relate to each other.

View full size graphic
A.
Content bounds

B.
Component bounds

C.
Stage bounds

Using coordinate properties and methods

In some cases, you have to convert positions between coordinate systems. Examples where you convert between coordinates include the following:

  • The MouseEvent class has properties that provide the mouse position in the global coordinate system and the local coordinates of the event target. You use the content coordinates to specify the locations in any container that uses absolute positioning, such as an MX Canvas container or a Spark container that uses the BasicLayout class. To determine the location of the mouse event within the Canvas container contents, not just the visible region, determine the position in the content coordinate system.

  • Custom drag-and-drop handlers might have to convert between the local coordinate system and the content coordinate system when determining an object-specific drag action; for example, if you have a control with scroll bars and you want to know the drag (mouse) location over the component contents. The example in Example: Using the mouse position in a Canvas container shows this use.

  • Custom layout containers, where you include both visual elements, such as scroll bars or dividers, and content elements. For example, if you have a custom container that draws lines between its children, you have to know where each child is in the container’s content coordinates to draw the lines.

Often, you use mouse coordinates in event handlers; when you do, you should keep in mind the following considerations:

  • When you handle mouse events, it is best to use the coordinates from the MouseEvent object whenever possible, because they represent the mouse coordinates at the time the event was generated. Although you can use the container’s contentMouseX and contentMouseY properties to get the mouse pointer locations in the content coordinate system, you should, instead, get the local coordinate values from the event object and convert them to the content coordinate system.

  • When you use local coordinates that are reported in an event object, such as the MouseEvent localX and localY properties, remember that the event properties report the local coordinates of the mouse relative to the event target. The target component can be a subcomponent of the component in which you determine the position, such as a UITextField inside a Button component, not the component itself. In such cases, convert the local coordinates into the global coordinate system first, and then convert the global coordinates into the content coordinates container.

All Flex components provide read-only properties and methods that enable you to use and convert between coordinate systems. The following table describes these properties and methods:

Property or method

Description

contentMouseX

Returns the x position of the mouse, in the content coordinates of the component.

contentMouseY

Returns the y position of the mouse, in the content coordinates of the component.

contentToGlobal (point:Point):Point

Converts a Point object with x and y coordinates from the content coordinate system to the global coordinate system.

contentToLocal (point:Point):Point

Converts a Point object from the content coordinate system to the local coordinate system of the component.

globalToContent (point:Point):Point

Converts a Point object from the global coordinate system to the content coordinate system of the component.

globalToLocal (point:Point):Point

Converts a Point object from the global coordinate system to the local coordinate system of the component.

localToContent (point:Point):Point

Converts a Point object from the local coordinate system to the content coordinate system of the component.

localToGlobal (point:Point):Point

Converts a Point object from the local coordinate system to the global coordinate system.

Example: Using the mouse position in a Canvas container

The following example shows the use of the localToGlobal() and globalToContent() methods to determine the location of a mouse pointer within a Canvas container that contains multiple child Canvas containers.

This example is artificial, in that production code would use the MouseEvent class stageX and stageY properties, which represent the mouse position in the global coordinate system. The example uses the localX and localY properties, instead, to show how you can convert between local and content coordinates, including how first converting to using the global coordinates ensures the correct coordinate frame of reference.

<?xml version="1.0"?>
<!-- containers\intro\MousePosition.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">
    
    <fx:Script>
        <![CDATA[
          import mx.controls.Alert;

          // Handle the mouseDown event generated 
          // by clicking in the application.
          private function handleMouseDown(event:MouseEvent):void {
                 
            // Convert the mouse position to global coordinates.
            // The localX and localY properties of the mouse event contain
            // the coordinates at which the event occurred relative to the
            // event target, typically one of the 
            // colored internal Canvas containers.
            // A production version of this example could use the stageX 
            // and stageY properties, which use the global coordinates, 
            // and avoid this step.
            // This example uses the localX and localY properties only to
            // illustrate conversion between different frames of reference.
            var pt:Point = new Point(event.localX, event.localY);
            pt = event.target.localToGlobal(pt);
                
            // Convert the global coordinates to the content coordinates 
            // inside the outer c1 Canvas container.
            pt = c1.globalToContent(pt);
               
            // Figure out which quadrant was clicked.
            var whichColor:String = "border area";
              
            if (pt.x < 150) {
                if (pt.y < 150)
                    whichColor = "red";
                else
                    whichColor = "blue";
            }
            else {
                if (pt.y < 150)
                    whichColor = "green";
                else
                    whichColor = "magenta";
            }
                
            Alert.show("You clicked on the " + whichColor);
          }
        ]]>
    </fx:Script>

    <!-- Canvas container with four child Canvas containers -->
    <mx:Canvas id="c1" 
        borderStyle="none" 
        width="300" height="300" 
        mouseDown="handleMouseDown(event);">
        
        <mx:Canvas 
            width="150" height="150" 
            x="0" y="0" 
            backgroundColor="red">
            <mx:Button label="I'm in Red"/>
        </mx:Canvas>
        <mx:Canvas 
            width="150" height="150" 
            x="150" y="0"
            backgroundColor="green">
            <mx:Button label="I'm in Green"/>
        </mx:Canvas>
        <mx:Canvas 
            width="150" height="150" 
            x="0" y="150"
            backgroundColor="blue">
            <mx:Button label="I'm in Blue"/>
        </mx:Canvas>
        <mx:Canvas 
            width="150" height="150" 
            x="150" y="150"
            backgroundColor="magenta">
            <mx:Button label="I'm in Magenta"/>
        </mx:Canvas>
    </mx:Canvas>
</s:Application>

The executing SWF file for the previous example is shown below: