Flex SDK Wiki

# 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](PopUpAnchor%20Spec). 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](Spark%20TitleWindow) 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](Spark%20TitleWindow) 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 */ Event(name="close", type="mx.events.CloseEvent") /** * Dispatched when the user presses the moveArea and * begins to drag the window. * * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE_START */ Event(name="windowMoveStart", type="spark.events.TitleWindowBoundsEvent") /** * Dispatched when the user tries to drag the window. * * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVING */ Event(name="windowMoving", type="spark.events.TitleWindowBoundsEvent") /** * Dispatched when the user moves the window successfully. * * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE */ Event(name="windowMove", type="spark.events.TitleWindowBoundsEvent") /** * Dispatched when the user releases the moveArea after * dragging. * * @eventType spark.events.TitleWindowBoundsEvent.WINDOW_MOVE_END */ Event(name="windowMoveEnd", type="spark.events.TitleWindowBoundsEvent") /** * Inactive State which is assigned to TitleWindows * that are not in focus. * */ SkinState("inactive") /** * Active State with control bar present. * */ SkinState("inactiveWithControlBar") /** * 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(); SkinPart(required="false") /** * The Button that when clicked dispatches a "close" event. * Focus is disabled for this button. */ public var closeButton:Button; SkinPart(required="false") /** * 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") ... SkinPart(required="false") /** * 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 ---- <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> </fx:script> <s:panel title="Control Panel" left="10" top="10"> <s:layout> <s:verticallayout paddingleft="10" paddingtop="10" paddingright="10" paddingbottom="10"> </s:verticallayout></s:layout> <s:button label="Add PopUp Using PopUp Manager" click="addPopUp();"> </s:button></s:panel> </s:application> \\ <s:titlewindow id="tw1" creationcomplete="tw1.closeButton.visible=false;"> <s:layout> <s:verticallayout> </s:verticallayout></s:layout> <s:label text="I don't have a close button!" width="220"> </s:label></s:titlewindow> \\ <s:titlewindow id="tw2" creationcomplete="tw2.moveArea.visible=false;"> <s:layout> <s:verticallayout> </s:verticallayout></s:layout> <s:label text="I cannot be moved!" width="220"> </s:label></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.