package spark.components
{

//--------------------------------------
//  Styles
//--------------------------------------

/**
 *  Appearance of the contentGroup. Valid MXML values are inset
 *  flat and transparent.
 *
 *  In ActionScript, you can use the following constants
 *  to set this property:
 *  ContentBackgroundAppearance.INSET,
 *  ContentBackgroundAppearance.FLAT and
 *  ContentBackgroundAppearance.NONE.
 */
<a href="Style%28name%3D%26quot%3BcontentBackgroundAppearance%26quot%3B%2C%20type%3D%26quot%3BString%26quot%3B%2C%20enumeration%3D%26quot%3Binset%2Cflat%2Cnone%26quot%3B%2C%20inherit%3D%26quot%3Bno%26quot%3B%29">Style(name="contentBackgroundAppearance", type="String", enumeration="inset,flat,none", inherit="no")</a>

public class Callout extends SkinnablePopUpContainer
{

<a href="Bindable">Bindable</a>
<a href="SkinPart%28required%3D%26quot%3Bfalse%26quot%3B%29">SkinPart(required="false")</a>

/**
 *  An optional skin part that visually connects the owner to the
 *  component.
 */
public var arrow:UIComponent;

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bauto%2Cbefore%2Cstart%2Cmiddle%2Cend%2Cafter%26quot%3B%2C%20defaultValue%3D%26quot%3Bauto%26quot%3B%29">Inspectable(category="General", enumeration="auto,before,start,middle,end,after", defaultValue="auto")</a>

/**
 * Horizontal position of the pop-over relative to the owner point.
 *
 * @see spark.components.CalloutPosition
 */
public function get horizontalPosition():String
public function set horizontalPosition(value:String):void

/**
 * Resolved horizontal position when using CalloutPosition.AUTO or opposite
 * horizontal position (when using BEFORE/AFTER or START/END) when the callout
 * does not fit in on screen using the specified horizontalPosition.
 *
 * @see spark.components.CalloutPosition
 */
protected function get actualHorizontalPosition():String
protected function set actualHorizontalPosition(value:String):void

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bauto%2Cbefore%2Cstart%2Cmiddle%2Cend%2Cafter%26quot%3B%2C%20defaultValue%3D%26quot%3Bauto%26quot%3B%29">Inspectable(category="General", enumeration="auto,before,start,middle,end,after", defaultValue="auto")</a>

/**
 * Vertical position of the pop-over relative to the owner point.
 *
 * @see spark.components.CalloutPosition
 */
public function get verticalPosition():String
public function set verticalPosition(value:String):void

/**
 * Resolved vertical position when using CalloutPosition.AUTO or opposite
 * vertical position (when using BEFORE/AFTER or START/END) when the callout
 * does not fit in on screen using the specified verticalPosition.
 *
 * @see spark.components.CalloutPosition
 */
protected function get actualVerticalPosition():String
protected function set actualVerticalPosition(value:String):void

/**
 * Sets the bounds of arrow, whose geometry isn't fully
 * specified by the skin's layout.
 */
protected function updateSkinDisplayList():void

/**
 * @see spark.components.SkinnablePopUpContainer#updatePopUpPosition()
 */
override public function updatePopUpPosition():void

}

package spark.components
{
public class SkinnablePopUpContainer extends SkinnableContainer
{

/**
 *  Positions the pop-up after the pop-up is added to PopUpManager but
 *  before any state transitions occur. The base implementation of open()
 *  calls updatePopUpPosition() immediately after the pop-up is added.
 *
 *  This method may also be called at any time to update the pop-up's
 *  position. Pop-ups that are positioned relative to their owner should
 *  call this method after position or size changes occur on the owner or
 *  it's ancestors.
 */
protected function updatePopUpPosition():void

}
}

package spark.components
{
/**
 * Enumeration of arrow directions for the Callout component.
 */
public class ArrowDirection
{
//--------------------------------------------------------------------------
//
//  Class constants
//
//--------------------------------------------------------------------------

/**
 * Point right towards the Callout owner
 */
public static const RIGHT:String = "right";

/**
 * Point up towards the Callout owner
 */
public static const UP:String = "up";

/**
 * Point left towards the Callout owner
 */
public static const LEFT:String = "left";

/**
 * Point down towards the Callout owner
 */
public static const DOWN:String = "down";

/**
 * Arrow is not visible due to corner or center placement relative to the
 * Callout owner
 */
public static const NONE:String = "none";
}
}

package spark.components
{
/**
 * The ContentBackgroundAppearance class defines the constants for the allowed values of the contentBackgroundAppearance style of Callout.
 */
public class ContentBackgroundAppearance
{
//--------------------------------------------------------------------------
//
//  Class constants
//
//--------------------------------------------------------------------------

/**
 *  Applies a shadow and mask to the contentGroup.
 */
public static const INSET:String = "inset";

/**
 *  Applies mask to the contentGroup.
 */
public static const FLAT:String = "flat";

/**
 *  Disables both the contentBackgroundColor style and
 *  contentGroup masking. Use this value when Callout's contents should
 *  appear directly on top of the backgroundColor or when
 *  contents provide their own masking.
 */
public static const NONE:String = "none";
}

package spark.components
{

/**
 * Position of the Callout relative to the owner.
 */
public final class CalloutPosition
{

/**
 * Position the trailing edge of the popUp before the leading edge of the owner
 */
public static const BEFORE:String = "before";

/**
 * Position the leading edge of the popUp at the leading edge of the owner
 *
 */
public static const START:String = "start";

/**
 * Position the horizontalCenter of the popUp to the horizontalCenter of the owner
 */
public static const MIDDLE:String = "middle";

/**
 * Position the trailing edge of the popUp at the trailing edge of the owner
 */
public static const END:String = "end";

/**
 * Position the leading edge of the popUp after the trailing edge of the owner
 */
public static const AFTER:String = "after";

/**
 * Position the popUp on the exterior of the owner where the popUp
 * requires the least amount of resizing to fit.
 */
public static const AUTO:String = "auto";

}

}

package spark.components
{
public class DropDownController extends EventDispatcher
{

/**
 * When true, resizing the system manager will close the the drop down.
 *
 * @default true
 */
public function get closeOnResize():Boolean
public function set closeOnResize(value:Boolean):void

}
}

package spark.components
{

/**
 *  Dispatched when the drop-down closes for any reason, such when
 *  the user:
 *  <ul>
 *      <li>The drop-down is programmatically closed.</li>
 *      <li>Clicks outside of the drop-down.</li>
 *      <li>Clicks the open button while the drop-down is
 *  displayed.</li>
 *  </ul>
 *
 *  @eventType spark.events.DropDownEvent.CLOSE
 */
<a href="Event%28name%3D%26quot%3Bclose%26quot%3B%2C%20type%3D%26quot%3Bspark.events.DropDownEvent%26quot%3B%29">Event(name="close", type="spark.events.DropDownEvent")</a>

/**
 *  Dispatched when the user clicks the open button
 *  to display the drop-down.
 *
 *  @eventType spark.events.DropDownEvent.OPEN
 */
<a href="Event%28name%3D%26quot%3Bopen%26quot%3B%2C%20type%3D%26quot%3Bspark.events.DropDownEvent%26quot%3B%29">Event(name="open", type="spark.events.DropDownEvent")</a>

<a href="DefaultProperty%28%26quot%3BcalloutContent%26quot%3B%29">DefaultProperty("calloutContent")</a>

public class CalloutButton extends Button
{

<a href="SkinPart%28required%3D%26quot%3Bfalse%26quot%3B%29">SkinPart(required="false")</a>

/**
 *  A skin part that defines the drop-down area. When the CalloutButton is open,
 *  clicking anywhere outside of the dropDown skin part closes the drop-down.
 * If dropDown is not defined on the skin, a default Callout instance is created.
 */
public var dropDown:IFactory;

/**
 * The set of components to include in the Callout's content.
 */
public function get calloutContent():Array
public function set calloutContent(value:Array):void

/**
 * Defines the layout of the Callout.
 */
public function get calloutLayout():LayoutBase
public function set calloutLayout(value:LayoutBase):void

/**
 *  The Callout instance created after the <code>DropDownEvent.OPEN</code> is
 *  triggered. The instance is created using the <code>dropDown</code>
 *  <code>IFactory</code> skin part.
 */
public function get callout():Callout

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bauto%2Cnever%26quot%3B%2C%20defaultValue%3D%26quot%3Bauto%26quot%3B%29">Inspectable(category="General", enumeration="auto,never", defaultValue="auto")</a>

/**
 *  Defines the destruction policy the callout button should use
 *  when the callout is closed. If set to "auto", the button will
 *  destroy the callout when it is closed.  If set to "never", the
 *  callout will be cached in memory.
 */
public function get calloutDestructionPolicy():String
public function set calloutDestructionPolicy(value:String):void

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bauto%2Cbefore%2Cstart%2Cmiddle%2Cend%2Cafter%26quot%3B%2C%20defaultValue%3D%26quot%3Bauto%26quot%3B%29">Inspectable(category="General", enumeration="auto,before,start,middle,end,after", defaultValue="auto")</a>

/**
 * Horizontal position of the pop-over relative to the owner point.
 *
 * @see spark.components.CalloutPosition
 */
public function get horizontalPosition():String
public function set horizontalPosition(value:String):void

<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bauto%2Cbefore%2Cstart%2Cmiddle%2Cend%2Cafter%26quot%3B%2C%20defaultValue%3D%26quot%3Bauto%26quot%3B%29">Inspectable(category="General", enumeration="auto,before,start,middle,end,after", defaultValue="auto")</a>

/**
 * Vertical position of the pop-over relative to the owner point.
 *
 * @see spark.components.CalloutPosition
 */
public function get verticalPosition():String
public function set verticalPosition(value:String):void

/**
 *  Instance of the DropDownController class that handles all of the mouse, keyboard
 *  and focus user interactions.
 */
protected function get dropDownController():DropDownController;
protected function set dropDownController(value:DropDownController):void;

/**
 *  Open the drop-down and dispatch a DropDownEvent.OPEN event.
 */
public function openDropDown():void;

/**
 *  Close the drop-down and dispatch a DropDownEvent.CLOSE event.
 */
public function closeDropDown():void;

}

}

package spark.skins.mobile
{
/**
 *  The default skin class for the Spark Callout component in mobile
 *  applications.
 *
 *  <p>The <code>contentGroup</code> lies above a <code>backgroundColor</code> fill
 *  which frames the <code>contentGroup</code>. The position and size of the frame
 *  adjust based on the host component <code>arrowDirection</code>, leaving
 *  space for the <code>arrow</code> to appear on the outside edge of the
 *  frame.</p>
 *
 *  <p>The <code>arrow</code> skin part is not positioned by the skin. Instead,
 *  the Callout component positions the arrow relative to the owner in
 *  <code>updateSkinDisplayList()</code>. This method assumes that Callout skin
 *  and the <code>arrow</code> use the same coordinate space.</p>
 */
public class CalloutSkin extends MobileSkin
{

/**
 *  @copy spark.skins.spark.ApplicationSkin#hostComponent
 */
public var hostComponent:Callout;

/**
 *  @copy spark.components.SkinnableContainer#contentGroup
 */
public var contentGroup:Group;

/**
 * @copy spark.components.Callout#arrow
 */
public var arrow:UIComponent;

/**
 *  Enables a RectangularDropShadow behind the <code>backgroundColor</code> frame.
 */
protected var dropShadowVisible = true;

/**
 *  Enables a vertical linear gradient in the <code>backgroundColor</code> frame. This
 *  gradient fill is drawn across both the arrow and the frame. By default,
 *  the gradient brightens the background color by 15% and darkens it by 60%.
 *
 *  @default true
 */
protected var useBackgroundGradient:Boolean = true;

/**
 *  Corner radius used for the <code>contentBackgroundColor</code> fill.
 */
protected var contentCornerRadius:uint;

/**
 *  Corner radius of the <code>backgroundColor</code> "frame". Also controls the inset
 *  of the <code>contentGroup</code>.
 */
protected var backgroundCornerRadius:Number;

/**
 *  The thickness of the <code>backgroundColor</code> "frame" that surrounds the
 *  <code>contentGroup</code>.
 */
protected var frameThickness:Number;

/**
 *  Color of the border stroke around the <code>backgroundColor</code> "frame".
 */
protected var borderColor:Number = 0;

/**
 *  Thickness of the border stroke around the <code>backgroundColor</code>
 *  "frame".
 */
protected var borderThickness:Number = NaN;

/**
 *  Width of the arrow in vertical directions. This property also controls
 *  the height of the arrow in horizontal directions.
 */
protected var arrowWidth:Number;

/**
 *  Height of the arrow in vertical directions. This property also controls
 *  the width of the arrow in horizontal directions.
 */
protected var arrowHeight:Number;
}
}

package spark.skins.mobile.supportClasses
{
/**
 *  The arrow skin part for CalloutSkin.
 */
public class CalloutArrow extends UIComponent
{

/**
 *  A gap on the frame-adjacent side of the arrow graphic to avoid
 *  drawing past the CalloutSkin backgroundCornerRadius.
 *
 *  @see spark.skins.mobile.CalloutSkin#backgroundCornerRadius
 */
protected var gap:Number;

/**
 *  @copy spark.skins.mobile.CalloutSkin#useBackgroundGradient
 */
protected var useBackgroundGradient:Boolean;

/**
 *  @copy spark.skins.mobile.CalloutSkin#borderColor
 */
protected var borderColor:Number;

/**
 *  @copy spark.skins.mobile.CalloutSkin#borderThickness
 */
protected var borderThickness:Number = NaN;
}
}

<s:HGroup top="20" right="20">

  <s:Button label="Mute" click="handleMute(event)"/>

  <!-- "EQ" button at the top-right of an application with a popUp appearing below it -->
  <s:CalloutButton
    verticalPosition="after"
    horizontalPosition="end"
    icon="@Embed('equalizer.png')"
    label="EQ"
    close="handleEqualizerClosed(event)">

    <s:calloutLayout>
      <s:VerticalLayout/>
    </s:calloutLayout>

    <custom:SliderControls/>
    <custom:GraphicEqualizer/>

  </s:CalloutButton>

</s:HGroup>

<mobile:ButtonSkin xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mobile="spark.skins.mobile.*">
    <fx:Declarations>
        <fx:Component id="dropDown">
            <s:Callout skinClass="skins.SimpleCalloutSkin" backgroundColor="0xFFFFFF"/>
        </fx:Component>
    </fx:Declarations>
</mobile:ButtonSkin>

private function button_clickHandler(event:MouseEvent):void
{
  // close triggers for the pop over
  systemManager.getSandboxRoot().addEventListener(MouseEvent.MOUSE_DOWN,
      systemManager_mouseDownHandler);
  systemManager.getSandboxRoot().addEventListener(SandboxMouseEvent.MOUSE_DOWN_SOMEWHERE,
      systemManager_mouseDownHandler);

  // open a Callout in response to a mouse click
  popUp = new MyToolTip(); /* MyToolTip extends Callout */

  // position the popUp to the right if the click is on the left side of the stage
  popUp.horizontalPosition = (event.stageX < (stage.stageWidth / 2))
      ? CalloutPosition.AFTER : CalloutPosition.BEFORE;
  popUp.verticalPosition = CalloutPosition.MIDDLE;

  popUp.open(button, false);
}