What is the purpose of Stage's DocumentClass?

TypeScript
#1

I see the tutorials mostly always pass in some Sprite as the argument, but I haven’t found any explanation of what the heck it is for, does, why I should / should not use it / leave it out, etc. so I am hoping somebody knows and can maybe explain succinctly what the ramifications are. Thanks!

#2

The OpenFL API is based on the Flash API, if you can’t find informations with the search term “openfl” try “flash” instead and you will get links like this:

As for the parameter itself, i never had any use for it after giving up on the Flash IDE. So someone else has to tell you if or why it’s usefull when using OpenFL.

#3

Given this example:

app.ts

import Stage from "openfl/display/Stage";
import Main from "./Main";

var stage = new Stage (550, 400, 0xFFFFFF, Main);
document.body.appendChild (stage.element);

Main.ts

import Sprite from "openfl/display/Sprite";
import Loader from "openfl/display/Loader";
import URLRequest from "openfl/net/URLRequest";
import Event from "openfl/events/Event";


export class Main extends Sprite {
	
	
	constructor () {
		
		super ();
		
		console.log (this.stage);
		
		var loader = new Loader ();
		loader.contentLoaderInfo.addEventListener (Event.COMPLETE, this.loader_onComplete);
		loader.load (new URLRequest ("openfl.png"));
		
	}
	
	
	
	
	// Event Handlers
	
	
	
	
	private loader_onComplete = (event:Event) => {
		
		var bitmap = event.target.loader.content;
		bitmap.x = (this.stage.stageWidth - bitmap.width) / 2;
		bitmap.y = (this.stage.stageHeight - bitmap.height) / 2;
		this.addChild (bitmap);
		
	}
	
	
}


export default Main;

Instances of Sprite can only reference the stage property when it has already been added to the stage. Optionally, we give you the ability to define a class that will be the entry-point for your application. This avoids the need to wait until you have been added to the stage. For example, the console.log (this.stage) call in Main.ts would read null if you did this another way. Applications that don’t require a direct reference to the stage should work fine without being initialized by the Stage, or you can listen to the ADDED_TO_STAGE event.

Here’s an alternative version:

app.ts

import Stage from "openfl/display/Stage";
import Main from "./Main";

var stage = new Stage (550, 400);
document.body.appendChild (stage.element);

stage.color = 0xFFFFFF;

var main = new Main ();
stage.addChild (main);

Main.ts

import Sprite from "openfl/display/Sprite";
import Loader from "openfl/display/Loader";
import URLRequest from "openfl/net/URLRequest";
import Event from "openfl/events/Event";


export class Main extends Sprite {
	
	
	constructor () {
		
		super ();
		
		this.addEventListener (Event.ADDED_TO_STAGE, (event) => {
			// this will occur after the `new Loader` code below due to the callback
			console.log (this.stage);
		});
		
		var loader = new Loader ();
		loader.contentLoaderInfo.addEventListener (Event.COMPLETE, this.loader_onComplete);
		loader.load (new URLRequest ("openfl.png"));
		
	}
	
	
	
	
	// Event Handlers
	
	
	
	
	private loader_onComplete = (event:Event) => {
		
		var bitmap = event.target.loader.content;
		bitmap.x = (this.stage.stageWidth - bitmap.width) / 2;
		bitmap.y = (this.stage.stageHeight - bitmap.height) / 2;
		this.addChild (bitmap);
		
	}
	
	
}


export default Main;
#4

ok i don’t get what are the some use cases?! like, would i do this if i wanted a “root” sprite so that i could do a kids painting program where they can draw lines and i just wanted to do it by editing the full-root bitmap data directly (vs. having multiple “line” sprites in a more vector-illustrator style)?

i mean if my app is just going to be a zillion individual sprites i might as well let them each individually add themselves to the stage? i don’t get why all the TS examples I saw show this optional last argument being in use and being a sprite. I mean even the Bitmap TS tutorial shows the bitmap being added as a child to the root sprite, not having the bitmap graphics blitted directly into the sprite’s own graphcis! so what’s the point there?!

#5

I suppose part of this is to mirror the behavior of the Haxelib/Flash version.

Under those circumstances, you choose an entry point class. At the beginning of your project, that class will be initialized, and already be on the stage. It’s subtle, but it’s just how things work there.

We opened the possibility to new Stage (which is not available in Haxelib and Flash versions), and decided to add an optional property so that you can reproduce this same behavior. It keeps the NPM and Haxelib samples more similar, but no, this isn’t strictly necessary