1//////////////////////////////////////////////////////////////////////////////// 2// 3// ADOBE SYSTEMS INCORPORATED 4// Copyright 2005-2007 Adobe Systems Incorporated 5// All Rights Reserved. 6// 7// NOTICE: Adobe permits you to use, modify, and distribute this file 8// in accordance with the terms of the license agreement accompanying it. 9// 10//////////////////////////////////////////////////////////////////////////////// 11 12package mx.managers 13{ 14 15import flash.display.DisplayObject; 16import flash.display.InteractiveObject; 17import flash.display.LoaderInfo; 18import flash.display.Sprite; 19import flash.display.Stage; 20import flash.events.Event; 21import flash.events.IEventDispatcher; 22import flash.geom.Rectangle; 23import flash.text.TextFormat; 24 25import mx.core.IChildList; 26import mx.core.IFlexModuleFactory; 27import mx.managers.IFocusManagerContainer; 28 29/** 30 * An ISystemManager manages an "application window". 31 * Every application that runs on the desktop or in a browser 32 * has an area where the visuals of the application will be 33 * displayed. It may be a window in the operating system 34 * or an area within the browser. That is an "application window" 35 * and different from an instance of <code>mx.core.Application</code>, which 36 * is the main "top-level" window within an application. 37 * 38 * <p>Every application has an ISystemManager. 39 * The ISystemManager sends an event if 40 * the size of the application window changes (you cannot change it from 41 * within the application, but only through interaction with the operating 42 * system window or browser). It parents all displayable items within the 43 * application, such as the main mx.core.Application instance and all popups, 44 * tooltips, cursors, an so on. Any object parented by the ISystemManager is 45 * considered to be a "top-level" window, even tooltips and cursors.</p> 46 * 47 * <p>The ISystemManager also switches focus between top-level windows 48 * if there are more than one IFocusManagerContainer displayed and users 49 * are interacting with components within the IFocusManagerContainers.</p> 50 * 51 * <p>All keyboard and mouse activity that is not expressly trapped is seen 52 * by the ISystemManager, making it a good place to monitor activity 53 * should you need to do so.</p> 54 * 55 * <p>If an application is loaded into another application, an ISystemManager 56 * will still be created, but will not manage an "application window", 57 * depending on security and domain rules. 58 * Instead, it will be the <code>content</code> of the <code>Loader</code> 59 * that loaded it and simply serve as the parent of the sub-application</p> 60 * 61 * <p>The ISystemManager maintains multiple lists of children, one each for 62 * tooltips, cursors, popup windows. 63 * This is how it ensures that popup windows "float" above the main 64 * application windows and that tooltips "float" above that 65 * and cursors above that. 66 * If you examine the <code>numChildren</code> property 67 * or <code>getChildAt()</code> method on the ISystemManager 68 * you are accessing the main application window and any other windows 69 * that aren't popped up. 70 * To get the list of all windows, including popups, tooltips and cursors, 71 * use the <code>rawChildren</code> property.</p> 72 * 73 * @langversion 3.0 74 * @playerversion Flash 9 75 * @playerversion AIR 1.1 76 * @productversion Flex 3 77 */ 78public interface ISystemManager extends IEventDispatcher, IChildList, IFlexModuleFactory 79{ 80 //-------------------------------------------------------------------------- 81 // 82 // Properties 83 // 84 //-------------------------------------------------------------------------- 85 86 //---------------------------------- 87 // cursorChildren 88 //---------------------------------- 89 90 /** 91 * An list of the custom cursors 92 * being parented by this ISystemManager. 93 * 94 * <p>An ISystemManager has various types of children, 95 * such as the Application, popups, top-most windows, 96 * tooltips, and custom cursors. 97 * You can access the custom cursors through 98 * the <code>cursorChildren</code> property.</p> 99 * 100 * <p>The IChildList object has methods like <code>getChildAt()</code> 101 * and properties like <code>numChildren</code>. 102 * For example, <code>cursorChildren.numChildren</code> gives 103 * the number of custom cursors (which will be either 0 or 1) 104 * and, if a custom cursor exists, you can access it as 105 * <code>cursorChildren.getChildAt(0)</code>.</p> 106 * 107 * @langversion 3.0 108 * @playerversion Flash 9 109 * @playerversion AIR 1.1 110 * @productversion Flex 3 111 */ 112 function get cursorChildren():IChildList; 113 114 //---------------------------------- 115 // document 116 //---------------------------------- 117 118 /** 119 * A reference to the document object. 120 * A document object is an Object at the top of the hierarchy of a 121 * Flex application, MXML component, or AS component. 122 * 123 * @langversion 3.0 124 * @playerversion Flash 9 125 * @playerversion AIR 1.1 126 * @productversion Flex 3 127 */ 128 function get document():Object; 129 130 /** 131 * @private 132 */ 133 function set document(value:Object):void; 134 135 //---------------------------------- 136 // embeddedFontList 137 //---------------------------------- 138 139 /** 140 * @private 141 */ 142 function get embeddedFontList():Object; 143 144 //---------------------------------- 145 // focusPane 146 //---------------------------------- 147 148 /** 149 * A single Sprite shared among components used as an overlay for drawing focus. 150 * You share it if you parent a focused component, not if you are IFocusManagerComponent. 151 * 152 * @langversion 3.0 153 * @playerversion Flash 9 154 * @playerversion AIR 1.1 155 * @productversion Flex 3 156 */ 157 function get focusPane():Sprite; 158 159 /** 160 * @private 161 */ 162 function set focusPane(value:Sprite):void; 163 164 //---------------------------------- 165 // loaderInfo 166 //---------------------------------- 167 168 /** 169 * True if the ISystemManager is a proxy and not a root class. 170 * 171 * @langversion 3.0 172 * @playerversion Flash 9 173 * @playerversion AIR 1.1 174 * @productversion Flex 3 175 */ 176 function get isProxy():Boolean; 177 178 //---------------------------------- 179 // loaderInfo 180 //---------------------------------- 181 182 /** 183 * The LoaderInfo object that represents information about the application. 184 * 185 * @langversion 3.0 186 * @playerversion Flash 9 187 * @playerversion AIR 1.1 188 * @productversion Flex 3 189 */ 190 function get loaderInfo():LoaderInfo; 191 192 //---------------------------------- 193 // numModalWindows 194 //---------------------------------- 195 196 /** 197 * The number of modal windows. 198 * 199 * <p>Modal windows don't allow 200 * clicking in another windows which would normally 201 * activate the FocusManager in that window. The PopUpManager 202 * modifies this count as it creates and destroy modal windows.</p> 203 * 204 * @langversion 3.0 205 * @playerversion Flash 9 206 * @playerversion AIR 1.1 207 * @productversion Flex 3 208 */ 209 function get numModalWindows():int; 210 211 /** 212 * @private 213 */ 214 function set numModalWindows(value:int):void; 215 216 //---------------------------------- 217 // popUpChildren 218 //---------------------------------- 219 220 /** 221 * An list of the topMost (popup) 222 * windows being parented by this ISystemManager. 223 * 224 * <p>An ISystemManager has various types of children, 225 * such as the Application, popups, 226 * tooltips, and custom cursors. 227 * You can access the top-most windows through 228 * the <code>popUpChildren</code> property.</p> 229 * 230 * <p>The IChildList object has methods like <code>getChildAt()</code> 231 * and properties like <code>numChildren</code>. 232 * For example, <code>popUpChildren.numChildren</code> gives 233 * the number of topmost windows and you can access them as 234 * <code>popUpChildren.getChildAt(i)</code>.</p> 235 * 236 * 237 * @langversion 3.0 238 * @playerversion Flash 9 239 * @playerversion AIR 1.1 240 * @productversion Flex 3 241 */ 242 function get popUpChildren():IChildList; 243 244 //---------------------------------- 245 // rawChildren 246 //---------------------------------- 247 248 /** 249 * A list of all children 250 * being parented by this ISystemManager. 251 * 252 * <p>An ISystemManager has various types of children, 253 * such as the Application, popups, 254 * tooltips, and custom cursors.</p> 255 * 256 * <p>The IChildList object has methods like <code>getChildAt()</code> 257 * and properties like <code>numChildren</code>.</p> 258 * 259 * @langversion 3.0 260 * @playerversion Flash 9 261 * @playerversion AIR 1.1 262 * @productversion Flex 3 263 */ 264 function get rawChildren():IChildList; 265 266 //---------------------------------- 267 // screen 268 //---------------------------------- 269 270 /** 271 * The size and position of the application window. 272 * 273 * The Rectangle object contains <code>x</code>, <code>y</code>, 274 * <code>width</code>, and <code>height</code> properties. 275 * 276 * The Rectangle is in sandbox root coordinates. 277 * 278 * @langversion 3.0 279 * @playerversion Flash 9 280 * @playerversion AIR 1.1 281 * @productversion Flex 3 282 */ 283 function get screen():Rectangle 284 285 //---------------------------------- 286 // stage 287 //---------------------------------- 288 289 /** 290 * The flash.display.Stage that represents the application window 291 * mapped to this SystemManager 292 * 293 * @langversion 3.0 294 * @playerversion Flash 9 295 * @playerversion AIR 1.1 296 * @productversion Flex 3 297 */ 298 function get stage():Stage 299 300 //---------------------------------- 301 // toolTipChildren 302 //---------------------------------- 303 304 /** 305 * A list of the tooltips 306 * being parented by this ISystemManager. 307 * 308 * <p>An ISystemManager has various types of children, 309 * such as the Application, popups, topmost windows, 310 * tooltips, and custom cursors.</p> 311 * 312 * <p>The IChildList object has methods like <code>getChildAt()</code> 313 * and properties like <code>numChildren</code>. 314 * For example, <code>toolTipChildren.numChildren</code> gives 315 * the number of tooltips (which will be either 0 or 1) 316 * and, if a tooltip exists, you can access it as 317 * <code>toolTipChildren.getChildAt(0)</code>.</p> 318 * 319 * @langversion 3.0 320 * @playerversion Flash 9 321 * @playerversion AIR 1.1 322 * @productversion Flex 3 323 */ 324 function get toolTipChildren():IChildList; 325 326 //---------------------------------- 327 // topLevelSystemManager 328 //---------------------------------- 329 330 /** 331 * The ISystemManager responsible for the application window. 332 * This will be the same ISystemManager unless this application 333 * has been loaded into another application. 334 * 335 * @langversion 3.0 336 * @playerversion Flash 9 337 * @playerversion AIR 1.1 338 * @productversion Flex 3 339 */ 340 function get topLevelSystemManager():ISystemManager; 341 342 343 //-------------------------------------------------------------------------- 344 // 345 // Methods 346 // 347 //-------------------------------------------------------------------------- 348 349 /** 350 * Converts the given String to a Class or package-level Function. 351 * Calls the appropriate <code>ApplicationDomain.getDefinition()</code> 352 * method based on 353 * whether you are loaded into another application or not. 354 * 355 * @param name Name of class, for example "mx.video.VideoManager". 356 * 357 * @return The Class represented by the <code>name</code>, or null. 358 * 359 * @langversion 3.0 360 * @playerversion Flash 9 361 * @playerversion AIR 1.1 362 * @productversion Flex 3 363 */ 364 function getDefinitionByName(name:String):Object; 365 366 /** 367 * Returns <code>true</code> if this ISystemManager is responsible 368 * for an application window, and <code>false</code> if this 369 * application has been loaded into another application. 370 * 371 * @return <code>true</code> if this ISystemManager is responsible 372 * for an application window. 373 * 374 * @langversion 3.0 375 * @playerversion Flash 9 376 * @playerversion AIR 1.1 377 * @productversion Flex 3 378 */ 379 function isTopLevel():Boolean; 380 381 /** 382 * Returns <code>true</code> if the required font face is embedded 383 * in this application, or has been registered globally by using the 384 * <code>Font.registerFont()</code> method. 385 * 386 * @param tf The TextFormat class representing character formatting information. 387 * 388 * @return <code>true</code> if the required font face is embedded 389 * in this application, or has been registered globally by using the 390 * <code>Font.registerFont()</code> method. 391 * 392 * @langversion 3.0 393 * @playerversion Flash 9 394 * @playerversion AIR 1.1 395 * @productversion Flex 3 396 */ 397 function isFontFaceEmbedded(tf:TextFormat):Boolean; 398 399 /** 400 * Tests if this system manager is the root of all 401 * top level system managers. 402 * 403 * @return <code>true</code> if the SystemManager 404 * is the root of all SystemManagers on the display list, 405 * and <code>false</code> otherwise. 406 * 407 * @langversion 3.0 408 * @playerversion Flash 9 409 * @playerversion AIR 1.1 410 * @productversion Flex 3 411 */ 412 function isTopLevelRoot():Boolean; 413 414 /** 415 * Attempts to get the system manager that is the in the main application. 416 * 417 * @return The main application's systemManager if allowed by 418 * security restrictions or null if it is in a different SecurityDomain. 419 * 420 * @langversion 3.0 421 * @playerversion Flash 9 422 * @playerversion AIR 1.1 423 * @productversion Flex 3 424 */ 425 function getTopLevelRoot():DisplayObject; 426 427 /** 428 * Gets the system manager that is the root of all 429 * top level system managers in this SecurityDomain. 430 * 431 * @return the highest-level systemManager in the sandbox 432 * 433 * @langversion 3.0 434 * @playerversion Flash 9 435 * @playerversion AIR 1.1 436 * @productversion Flex 3 437 */ 438 function getSandboxRoot():DisplayObject; 439 440 /** 441 * Get the bounds of the loaded application that are visible to the user 442 * on the screen. 443 * 444 * @param bounds Optional. The starting bounds for the visible rect. The 445 * bounds are in global coordinates. If <code>bounds</code> is null the 446 * starting bounds is defined by the <code>screen</code> property of the 447 * system manager. 448 * 449 * @return a <code>Rectangle</code> including the visible portion of the this 450 * object. The rectangle is in global coordinates. 451 * 452 * @langversion 3.0 453 * @playerversion Flash 9 454 * @playerversion AIR 1.1 455 * @productversion Flex 3 456 */ 457 function getVisibleApplicationRect(bounds:Rectangle = null, skipToSandboxRoot:Boolean = false):Rectangle; 458 459 /** 460 * Deploy or remove mouse shields. Mouse shields block mouse input to untrusted 461 * applications. The reason you would want to block mouse input is because 462 * when you are dragging over an untrusted application you would normally not 463 * receive any mouse move events. The Flash Player does not send events 464 * across trusted/untrusted boundries due to security concerns. By covering 465 * the untrusted application with a mouse shield (assuming you are its parent) 466 * you can get mouse move message and the drag operation will work as expected. 467 * 468 * @param deploy <code>true</code> to deploy the mouse shields, <code>false</code> 469 * to remove the mouse shields. 470 * 471 * @langversion 3.0 472 * @playerversion Flash 9 473 * @playerversion AIR 1.1 474 * @productversion Flex 3 475 */ 476 function deployMouseShields(deploy:Boolean):void; 477 478 /** 479 * Attempt to notify the parent SWFLoader that the application's size may 480 * have changed. 481 * 482 * @langversion 3.0 483 * @playerversion Flash 10 484 * @playerversion AIR 1.5 485 * @productversion Flex 4 486 */ 487 function invalidateParentSizeAndDisplayList():void; 488 489} 490 491} 492