Setting Stage properties

The Stage class overrides most properties and methods of the DisplayObject class. If you call one of these overridden properties or methods, OpenFL will ignore the request. For example, the Stage object does not have x or y properties, since its position is fixed as the main container for the application. The x and y properties refer to the position of a display object relative to its container, and since the Stage is not contained in another display object container, these properties do not apply.

Controlling the playback frame rate

The frameRate property of the Stage class is used to set the frame rate for all projects loaded into the application. For more information, see the API Reference.

Controlling Stage scaling

When the portion of the screen representing OpenFL is resized, the runtime automatically adjusts the Stage contents to compensate. The Stage class’s scaleMode property determines how the Stage contents are adjusted. This property can be set to four different values, defined as constants in the openfl.display.StageScaleMode class:

  • StageScaleMode.EXACT_FIT scales the project to fill the new stage dimensions without regard for the original content aspect ratio. The scale factors might not be the same for width and height, so the content can appear squeezed or stretched if the aspect ratio of the stage is changed.
  • StageScaleMode.SHOW_ALL scales the project to fit entirely within the new stage dimensions without changing the content aspect ratio. This scale mode displays all of the content, but can result in "letterbox" borders, like the black bars that appear when viewing a wide-screen movie on a standard television.
  • StageScaleMode.NO_BORDER scales the project to entirely fill the new stage dimensions without changing the aspect ratio of the content. This scale mode makes full use of the stage display area, but can result in cropping.
  • StageScaleMode.NO_SCALE — does not scale the project. If the new stage dimensions are smaller, the content is cropped; if larger, the added space is blank.

On Flash Player, OpenFL will respect the above StageScaleMode settings, but on other platforms, OpenFL will behave like StageScaleMode.NO_SCALE by default, or StageScaleMode.SHOW_ALL if you set a window width and height in your project file

In the StageScaleMode.NO_SCALE scale mode only, the stageWidth and stageHeight properties of the Stage class can be used to determine the actual pixel dimensions of the resized stage. (In the other scale modes, the stageWidth and stageHeight properties always reflect the original width and height of the project.) In addition, when scaleMode is set to StageScaleMode.NO_SCALE and the project is resized, the Stage class’s resize event is dispatched, allowing you to make adjustments accordingly.

Consequently, having scaleMode set to StageScaleMode.NO_SCALE allows you to have greater control over how the screen contents adjust to the window resizing if you desire. For example, in a project containing a video and a control bar, you might want to make the control bar stay the same size when the Stage is resized, and only change the size of the video window to accommodate the Stage size change. This is demonstrated in the following example:

// mainContent is a display object containing the main content;
// it is positioned at the top-left corner of the Stage, and
// it should resize when the window resizes.
// controlBar is a display object (e.g. a Sprite) containing several
// buttons; it should stay positioned at the bottom-left corner of the
// Stage (below mainContent) and it should not resize when the project
// resizes.

import openfl.display.Stage;
import openfl.display.StageAlign;
import openfl.display.StageScaleMode;
import openfl.events.Event;

...

var stage = mainContent.stage;
stage.scaleMode = StageScaleMode.NO_SCALE;
stage.align = StageAlign.TOP_LEFT;
stage.addEventListener (Event.RESIZE, resizeDisplay);

...

private function resizeDisplay (event:Event):Void {

    var width = stage.stageWidth;
    var height = stage.stageHeight;

    // Resize the main content area
    var newContentHeight = height - controlBar.height;
    mainContent.height = newContentHeight;
    mainContent.scaleX = mainContent.scaleY;

    // Reposition the control bar
    controlBar.y = newContentHeight;

}

Working with full-screen mode

Full-screen mode allows you to set a movie’s stage to fill a viewer’s entire monitor without any container borders or menus. The Stage class’s displayState property is used to toggle full-screen mode on and off for an OpenFL project. The displayState property can be set to one of the values defined by the constants in the openfl.display.StageDisplayState class. To turn on full-screen mode, set the displayState property to StageDisplayState.FULL_SCREEN:

stage.displayState = StageDisplayState.FULL_SCREEN;

To turn on full-screen interactive mode, set the displayState property to StageDisplayState.FULL_SCREEN_INTERACTIVE:

stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;

OpenFL allows interactive access for both StageDisplayState.FULL_SCREEN or StageDisplayState.FULL_SCREEN_INTERACTIVE on platforms other than Flash

In Flash Player, full-screen mode can only be initiated through Haxe in response to a mouse click (including right-click) or keypress. Other platforms content do not require that full-screen mode be entered in response to a user gesture.

To exit full-screen mode, set the displayState property to StageDisplayState.NORMAL.

stage.displayState = StageDisplayState.NORMAL;

In addition, a user can choose to leave full-screen mode by switching focus to a different window or by using one of several key combinations: the Esc key (all platforms), Control-W (Windows), Command-W (Mac), or Alt-F4 (Windows).

Enabling full-screen mode in Flash Player

To enable full-screen mode for a SWF embedded in an HTML page, the HTML code to embed the SWF file must include a param tag and embed attribute with the name allowFullScreen and value true, like this:

<object>
    ...
    <param name="allowFullScreen" value="true" />
    <embed ... allowFullScreen="true" />
</object>

In the Flash authoring tool, select File -> Publish Settings and in the Publish Settings dialog box, on the HTML tab, select the Flash Only - Allow Full Screen template.

If you are using JavaScript in a web page to generate the SWF-embedding tags, you must alter the JavaScript to add the allowFullScreen param tag and attribute. For example, if your HTML page uses the AC_FL_RunContent() function (which is used in HTML pages generated by Flash Professional and Flash Builder), you should add the allowFullScreen parameter to that function call as follows:

AC_FL_RunContent(
    ...
    'allowFullScreen','true',
    ...
); //end AC code

This does not apply to projects running in the stand-alone Flash Player.

Note: If you set the Window Mode (wmode in the HTML) to Opaque Windowless (opaque) or Transparent Windowless (transparent), the full-screen window is always opaque

Enabling full-screen interactive mode in Flash Player 11.3 and higher

Flash Player 11.3 and higher support full-screen interactive mode, which enables full support for all keyboard keys (except for Esc, which exits full-screen interactive mode). Full-screen interactive mode is useful for gaming (for example, to enable chat in a multi-player game or WASD keyboard controls in a first-person shooter game.)

To enable full-screen interactive mode for a project embedded in an HTML page, the HTML code to embed the SWF file must include a param tag and embed attribute with the name allowFullScreenInteractive and value true, like this:

<object>
    ...
    <param name="allowFullScreenInteractive" value="true" />
    <embed ... allowFullScreenInteractive="true" />
</object>

In the Flash authoring tool, select File -> Publish Settings and in the Publish Settings dialog box, on the HTML tab, select the Flash Only - Allow Full Screen Interactive template.

If you are using JavaScript in a web page to generate the SWF-embedding tags, you must alter the JavaScript to add the allowFullScreenInteractive param tag and attribute. For example, if your HTML page uses the AC_FL_RunContent() function (which is used in HTML pages generated by Flash Professional and Flash Builder), you should add the allowFullScreenInteractive parameter to that function call as follows:

AC_FL_RunContent(
    ...
    'allowFullScreenInteractive','true',
    ...
); //end AC code

This does not apply to projects running in the stand-alone Flash Player.

Full screen stage size and scaling

The Stage.fullScreenHeight and Stage.fullScreenWidth properties return the height and the width of the monitor that’s used when going to full-screen size, if that state is entered immediately. These values can be incorrect if the user has the opportunity to move the browser from one monitor to another after you retrieve these values but before entering full-screen mode. If you retrieve these values in the same event handler where you set the Stage.displayState property to StageDisplayState.FULL_SCREEN, the values are correct. For users with multiple monitors, the content expands to fill only one monitor. OpenFL uses a metric to determine which monitor contains the greatest portion of the application window, and uses that monitor for full-screen mode. The fullScreenHeight and fullScreenWidth properties only reflect the size of the monitor that is used for full-screen mode. For more information, see Stage.fullScreenHeight and Stage.fullScreenWidth in the API Reference.

Stage scaling behavior for full-screen mode is the same as under normal mode; the scaling is controlled by the Stage class’s scaleMode property. If the scaleMode property is set to StageScaleMode.NO_SCALE, the Stage’s stageWidth and stageHeight properties change to reflect the size of the screen area occupied by the content (the entire screen, in this case); if viewed in the browser the HTML parameter for this controls the setting.

You can use the Stage class’s fullScreen event to detect and respond when full-screen mode is turned on or off. For example, you might want to reposition, add, or remove items from the screen when entering or leaving full-screen mode, as in this example:

import openfl.events.FullScreenEvent;

...

private function fullScreenRedraw (event:FullScreenEvent):Void {

    if (event.fullScreen) {

        // Remove input text fields.
        // Add a button that closes full-screen mode.

    } else {

        // Re-add input text fields.
        // Remove the button that closes full-screen mode.

    }

}

...

mySprite.stage.addEventListener (FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

As this code shows, the event object for the fullScreen event is an instance of the openfl.events.FullScreenEvent class, which includes a fullScreen property indicating whether full-screen mode is enabled (true) or not (false).

Keyboard support in full-screen mode

When Flash Player runs in a browser, all keyboard-related code, such as keyboard events and text entry in TextField instances, is disabled in full-screen mode. The exceptions (the keys that are enabled) are:

  • Selected non-printing keys, specifically the arrow keys, space bar, and tab key
  • Keyboard shortcuts that terminate full-screen mode: Esc (Windows and Mac), Control-W (Windows), Command- W (Mac), and Alt-F4

These restrictions are not present for Flash content running in the stand-alone Flash Player.

results matching ""

    No results matching ""