Menu

Spark TitleWindow

SourceForge Editorial Staff

Spark TitleWindow

Functional and Design Specification


Glossary


Summary and Background


The new [Spark TitleWindow] component is similar to the Flex 3 TitleWindow. The [Spark TitleWindow] extends Panel and adds additional functionality. It can be popped up by PopUpManager or the new PopUpAnchor. Users can also move the TitleWindow around the stage as well as close it by using the Close button.

Usage Scenarios


1) Bob needs to create a preferences panel for his app that pops-up when a user clicks the preferences button. He uses TitleWindow to create this panel since by default it has a close button as well as the ability to be dragged around by the user.

2) Green Lantern would like to create a Search Window to search through documents in his Amazing Hero Text Editor. He uses a TitleWindow to create the Search Window that can float above his content as well as be dragged off to the side and closed when the user is finished.

3) TitleWindow can also be used to create Dialogue windows that pop-up after a user interaction. An example would be a confirmation dialogue after someone hits the submit button on a form.

Detailed Description


The Spark TitleWindow component will extend the Spark Panel and have two additional skin parts, closeButton and moveArea.

Skin Parts

The closeButton is an optional skin part of type Button that dispatches a "close" event of type mx.events.CloseEvent upon being clicked. The window does not close itself. The "close" event must be handled to both close the window and execute behavior associated with the event. This behavior is the same as in the Halo counterpart.

The moveArea is an optional skin part of type UIComponent. This skin part defines the area where the user can drag to move the TitleWindow around. Usually, this is the title bar area at the top of the TitleWindow.

TitleWindowBoundsEvent

Interacting with the moveArea will dispatch a series of events of type spark.events.TitleWindowBoundsEvent. When the user first presses and tries to drag the moveArea, TitleWindow will dispatch a cancelable "windowMoveStart" event. Each time the user tries to move the window while the mouse is down, the TitleWindow will dispatch a cancelable "windowMoving" event followed by a "windowMove" event when the move succeeds. Lastly, when the user releases the moveArea, TitleWindow will dispatch a "windowMoveEnd" event.

Each event contains two flash.geom.Rectangle's called beforeBounds and afterBounds. These are the bounds of the window before and after it has moved. In the case of "windowMoveStart", only beforeBounds is given as the starting position of the window. In the case of "windowMoveEnd", the starting position is again given as beforeBounds and the final position of the entire drag gesture is given by afterBounds.

Spark Skin

The Spark TitleWindow skin is similar to the Panel skin. It differs in that it adds the closeButton to the top right-hand corner, and places the moveArea on the title bar. It also adds two additional states, "inactive" and "inactiveWithControlBar". The new states refer to a TitleWindow that is currently not in focus. The difference in states is shown in the default skins by the lightening of the title area when the TitleWindow is inactive.

API Description


Additions to MXML Language and ActionScript Object Model

Include the relevant API for this feature using the following example as a guideline. Make sure you indicate whether APIs are public or protected. You do not need to present private or mx_internal APIs here.

package spark.components
{

/**
 *  Dispatched when the user selects the close button.
 *
 *  @eventType mx.events.CloseEvent.CLOSE
 */
<a href="Event%28name%3D%26quot%3Bclose%26quot%3B%2C%20type%3D%26quot%3Bmx.events.CloseEvent%26quot%3B%29">Event(name="close", type="mx.events.CloseEvent")</a>

/**
 *  Dispatched when the user presses the moveArea and
 *  begins to drag the window.
 *
 *  @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE_START
 */
<a href="Event%28name%3D%26quot%3BwindowMoveStart%26quot%3B%2C%20type%3D%26quot%3Bspark.events.TitleWindowBoundsEvent%26quot%3B%29">Event(name="windowMoveStart", type="spark.events.TitleWindowBoundsEvent")</a>

/**
 *  Dispatched when the user tries to drag the window.
 *
 *  @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVING
 */
<a href="Event%28name%3D%26quot%3BwindowMoving%26quot%3B%2C%20type%3D%26quot%3Bspark.events.TitleWindowBoundsEvent%26quot%3B%29">Event(name="windowMoving", type="spark.events.TitleWindowBoundsEvent")</a>

/**
 *  Dispatched when the user moves the window successfully.
 *
 *  @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE
 */
<a href="Event%28name%3D%26quot%3BwindowMove%26quot%3B%2C%20type%3D%26quot%3Bspark.events.TitleWindowBoundsEvent%26quot%3B%29">Event(name="windowMove", type="spark.events.TitleWindowBoundsEvent")</a>

/**
 *  Dispatched when the user releases the moveArea after
 *  dragging.
 *
 *  @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE_END
 */
<a href="Event%28name%3D%26quot%3BwindowMoveEnd%26quot%3B%2C%20type%3D%26quot%3Bspark.events.TitleWindowBoundsEvent%26quot%3B%29">Event(name="windowMoveEnd", type="spark.events.TitleWindowBoundsEvent")</a>

/**
 *  Inactive State which is assigned to TitleWindows
 *  that are not in focus.
 *  
 */
<a href="SkinState%28%26quot%3Binactive%26quot%3B%29">SkinState("inactive")</a>

/**
 *  Active State with control bar present.
 *
 */
<a href="SkinState%28%26quot%3BinactiveWithControlBar%26quot%3B%29">SkinState("inactiveWithControlBar")</a>

/**
 *  The TitleWindow Class extends Panel to include
 *  a close button and drag area. TitleWindow is 
 *  designed as a floating or pop-up window.
 */
public class TitleWindow extends Panel
{
    /**
     *  Constructor.
     */
    public function TitleWindow();

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

    /**
     *  The Button that when clicked dispatches a "close" event.
     *  Focus is disabled for this button.
     */
    public var closeButton:Button;

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

    /**
     *  The area where the user may click and drag to move the window.
     */
    public var moveArea:UIComponent;

    /**
     *  Dispatches the "close" event when the closeButton
     *  is clicked.
     */
    protected function closeButton_clickHandler(event:MouseEvent):void;

    /**
     *  Called when the user starts dragging a TitleWindow.
     *  It begins a move on the TitleWindow if it was popped
     *  up either by PopUpManager or PopUpAnchor.
     */
    protected function moveArea_mouseDownHandler(event:MouseEvent):void;

    /**
     *  Called when the user drags a TitleWindow.
     */
    protected function moveArea_mouseMoveHandler(event:MouseEvent):void;

    /**
     *  Called when the user releases a TitleWindow
     *  that has been popped up by either by PopUpManager or
     *  PopUpAnchor.
     */
    protected function moveArea_mouseUpHandler(event:Event):void;
}
}

B Features


  • Platform-specific title bar layout. (i.e. OS X vs. Windows).
  • Resizing capability and handle. Additional API below:\

    /*
    * Dispatched when the user grabs the resizeHandle.
    *
    * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_RESIZE_START
    /
    Event(name="windowResizeStart", type="spark.events.TitleWindowBoundsEvent")

    /*
    * Dispatched when the user tries to resize the TitleWindow.
    *
    * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_RESIZING
    /
    Event(name="windowResizing", type="spark.events.TitleWindowBoundsEvent")

    /*
    * Dispatched when the user has successfully resized the
    * TitleWindow.
    *
    * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_RESIZE
    /
    Event(name="windowResize", type="spark.events.TitleWindowBoundsEvent")

    /*
    * Dispatched when the user releases the resizeHandle.
    *
    * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_RESIZE_END
    /
    Event(name="windowResizeEnd", type="spark.events.TitleWindowBoundsEvent")

    /*
    * Resizing State when resizing the component.
    *
    /
    SkinState("resizing")

    ...

    <a href="SkinPart%28required%3D%26quot%3Bfalse%26quot%3B%29">SkinPart(required="false")</a>
    
    /**
     *  The skin part the defines the handle that
     *  is used to resize the TitleWindow.
     */
    public var resizeHandle:UIComponent;
    
    /**
     *  Called when the user starts resizing a TitleWindow
     *  that has been popped up either by PopUpManager or
     *  PopUpAnchor.
     */
    protected function resizeHandle_mouseDownHandler(event:MouseEvent):void;
    
    /**
     *  Called when the user resizes a TitleWindow
     *  that has been popped up by either by PopUpManager or
     *  PopUpAnchor.
     */
    protected function resizeHandle_mouseMoveHandler(event:MouseEvent):void;
    
    /**
     *  Called when the user stops resizing a TitleWindow
     *  that has been popped up by either by PopUpManager or
     *  PopUpAnchor.
     */
    protected function resizeHandle_mouseUpHandler(event:Event):void;
    

Examples and Usage


<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:mx="library://ns.adobe.com/flex/halo"
               width="600" height="600">

    <fx:Script>
        <![CDATA[
            import mx.core.IFlexDisplayObject;
            import mx.managers.PopUpManager;
            import spark.components.Label;
            import spark.components.TitleWindow;

            private var point1:Point = new Point();

            private function addPopUp():void
            {
                var tw:TitleWindow = new TitleWindow();

                tw.title="From PopUpManager...";
                tw.width = 250;
                tw.height = 150;
                tw.x = 300;
                tw.y = 10;

                var st:Label = new Label();
                st.text = "Hello World!";
                st.left = 10;
                st.top = 10;
                st.width = 220;

                PopUpManager.addPopUp(tw, this, false);
                tw.addEventListener("close", closeHandler);

                tw.addElement(st);
            }

            private function closeHandler(event:Event):void
            {
                event.target.removeEventListener("close", closeHandler);
                PopUpManager.removePopUp(event.target as IFlexDisplayObject);
            }

        ]]>
    </fx:Script>

    <s:Panel title="Control Panel" left="10" top="10">
        <s:layout>
            <s:VerticalLayout paddingLeft="10" paddingTop="10"
                              paddingRight="10" paddingBottom="10" />
        </s:layout>
        <s:Button label="Add PopUp Using PopUp Manager" click="addPopUp();" />
    </s:Panel>

</s:Application>

\

<s:TitleWindow id="tw1" creationComplete="tw1.closeButton.visible=false;">
    <s:layout>
        <s:VerticalLayout />
    </s:layout>
    <s:Label text="I don't have a close button!" width="220" />
</s:TitleWindow>

\

<s:TitleWindow id="tw2" creationComplete="tw2.moveArea.visible=false;">
    <s:layout>
        <s:VerticalLayout />
    </s:layout>
    <s:Label text="I cannot be moved!" width="220" />
</s:TitleWindow>

Additional Implementation Details


None

Prototype Work


Done.

Compiler Work


None

Web Tier Compiler Impact


None

Flex Feature Dependencies


None

Backwards Compatibility


Syntax changes

None

Behavior

None

Warnings/Deprecation

None

Accessibility


Yes, a counterpart of this component should be made

Performance


None

Globalization


None

Localization


Compiler Features

None

Framework Features

None

Issues and Recommendations


None yet.


Related

Wiki: Flex 4
Wiki: PopUpAnchor Spec
Wiki: Spark TitleWindow

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.