starling-framework

import TextOptions from "./TextOptions"; import TextFormat from "./TextFormat"; import ITextCompositor from "./ITextCompositor"; import BitmapFont from "./BitmapFont"; import MeshStyle from "../styles/MeshStyle"; import Painter from "../rendering/Painter"; import DisplayObjectContainer from "../display/DisplayObjectContainer"; import DisplayObject from "../display/DisplayObject"; import Rectangle from "openfl/geom/Rectangle"; import Point from "openfl/geom/Point"; declare namespace starling.text { /** * A TextField displays text, using either standard true type fonts, custom bitmap fonts, * * or a custom text representation. * * * * Access the <code>format</code> property to modify the appearance of the text, like the * * font name and size, a color, the horizontal and vertical alignment, etc. The border property * * is useful during development, because it lets you see the bounds of the TextField. * * * * There are several types of fonts that can be displayed: * * * * <ul> * * <li>Standard TrueType fonts. This renders the text just like a conventional Flash * * TextField. It is recommended to embed the font, since you cannot be sure which fonts * * are available on the client system, and since this enhances rendering quality. * * Simply pass the font name to the corresponding property.</li> * * <li>Bitmap fonts. If you need speed or fancy font effects, use a bitmap font instead. * * That is a font that has its glyphs rendered to a texture atlas. To use it, first * * register the font with the method <code>registerBitmapFont</code>, and then pass * * the font name to the corresponding property of the text field.</li> * * <li>Custom text compositors. Any class implementing the <code>ITextCompositor</code> * * interface can be used to render text. If the two standard options are not sufficient * * for your needs, such a compositor might do the trick.</li> * * </ul> * * * * For bitmap fonts, we recommend one of the following tools: * * * * <ul> * * <li>Windows: <a href="http://www.angelcode.com/products/bmfont">Bitmap Font Generator</a> * * from Angel Code (free). Export the font data as an XML file and the texture as a png * * with white characters on a transparent background (32 bit).</li> * * <li>Mac OS: <a href="http://glyphdesigner.71squared.com">Glyph Designer</a> from * * 71squared or <a href="http://http://www.bmglyph.com">bmGlyph</a> (both commercial). * * They support Starling natively.</li> * * <li>Cross-Platform: <a href="http://kvazars.com/littera/">Littera</a> or * * <a href="http://renderhjs.net/shoebox/">ShoeBox</a> are great tools, as well. * * Both are free to use and were built with Adobe AIR.</li> * * </ul> * * * * When using a bitmap font, the 'color' property is used to tint the font texture. This * * works by multiplying the RGB values of that property with those of the texture's pixel. * * If your font contains just a single color, export it in plain white and change the 'color' * * property to any value you like (it defaults to zero, which means black). If your font * * contains multiple colors, change the 'color' property to <code>Color.WHITE</code> to get * * the intended result. * * * * Batching of TextFields * * * * Normally, TextFields will require exactly one draw call. For TrueType fonts, you cannot * * avoid that; bitmap fonts, however, may be batched if you enable the "batchable" property. * * This makes sense if you have several TextFields with short texts that are rendered one * * after the other (e.g. subsequent children of the same sprite), or if your bitmap font * * texture is in your main texture atlas. * * * * The recommendation is to activate "batchable" if it reduces your draw calls (use the * * StatsDisplay to check this) AND if the text fields contain no more than about 15-20 * * characters. For longer texts, the batching would take up more CPU time than what is saved * * by avoiding the draw calls. * */ export class TextField extends DisplayObjectContainer { /** * Create a new text field with the given properties. */ constructor(width: number, height: number, text?: string, format?: TextFormat, options?: TextOptions); /** * The Context3D texture format that is used for rendering of all TrueType texts. * * The default provides a good compromise between quality and memory consumption; * * use <pre>Context3DTextureFormat.BGRA</pre> for the highest quality. * * * * @default Context3DTextureFormat.BGRA_PACKED */ static get defaultTextureFormat(): string; static set defaultTextureFormat(value: string) /** * The default compositor used to arrange the letters of the text. * * If a specific compositor was registered for a font, it takes precedence. * * * * @default TrueTypeCompositor * */ static get defaultCompositor(): ITextCompositor; static set defaultCompositor(value: ITextCompositor) /** * Updates the list of embedded fonts. Call this method when you loaded a TrueType font * * at runtime so that Starling can recognize it as such. */ static updateEmbeddedFonts(): void; /** * Makes a text compositor (like a <code>BitmapFont</code>) available to any TextField in * * the current stage3D context. The font is identified by its <code>name</code> (not * * case sensitive). */ static registerCompositor(compositor: ITextCompositor, name: string): void; /** * Unregisters the text compositor and, optionally, disposes it. */ static unregisterCompositor(name: string, dispose?: boolean): void; /** * Returns a registered text compositor (or null, if the font has not been registered). * * The name is not case sensitive. */ static getCompositor(name: string): ITextCompositor; /** * Makes a bitmap font available at any TextField in the current stage3D context. * * The font is identified by its <code>name</code> (not case sensitive). * * Per default, the <code>name</code> property of the bitmap font will be used, but you * * can pass a custom name, as well. @return the name of the font. */ static registerBitmapFont(bitmapFont: BitmapFont, name?: string): string; /** * Unregisters the bitmap font and, optionally, disposes it. */ static unregisterBitmapFont(name: string, dispose?: boolean): void; /** * Returns a registered bitmap font compositor (or null, if no compositor has been * * registered with that name, or if it's not a bitmap font). The name is not case * * sensitive. */ static getBitmapFont(name: string): BitmapFont; /** * Disposes the underlying texture data. */ override dispose(): void; /** * @inheritDoc */ override render(painter: Painter): void; /** * Forces the text to be recomposed before rendering it in the upcoming frame. Any changes * * of the TextField itself will automatically trigger recomposition; changes in its * * parents or the viewport, however, need to be processed manually. For example, you * * might want to force recomposition to fix blurring caused by a scale factor change. * */ setRequiresRecomposition(): void; /** * Returns the bounds of the text within the text field. */ get textBounds(): Rectangle; /** * @inheritDoc */ override getBounds(targetSpace: DisplayObject, out?: Rectangle): Rectangle; /** * Returns the bounds of the text within the text field in the given coordinate space. */ getTextBounds(targetSpace: DisplayObject, out?: Rectangle): Rectangle; /** * @inheritDoc */ override hitTest(localPoint: Point): DisplayObject; /** * The displayed text. */ get text(): string; set text(value: string) /** * The format describes how the text will be rendered, describing the font name and size, * * color, alignment, etc. * * * * Note that you can edit the font properties directly; there's no need to reassign * * the format for the changes to show up. * * * * <listing> * * var textField:TextField = new TextField(100, 30, "Hello Starling"); * * textField.format.font = "Arial"; * * textField.format.color = Color.RED;</listing> * * * * @default Verdana, 12 pt, black, centered * */ get format(): TextFormat; set format(value: TextFormat) /** * Draws a border around the edges of the text field. Useful for visual debugging. * * @default false */ get border(): boolean; set border(value: boolean) get_border(): boolean; set_border(value: boolean): boolean; /** * Indicates whether the font size is automatically reduced if the complete text does * * not fit into the TextField. @default false */ get autoScale(): boolean; set autoScale(value: boolean) /** * Specifies the type of auto-sizing the TextField will do. * * Note that any auto-sizing will implicitly deactivate all auto-scaling. * * @default none */ get autoSize(): string; set autoSize(value: string) /** * Indicates if the text should be wrapped at word boundaries if it does not fit into * * the TextField otherwise. @default true */ get wordWrap(): boolean; set wordWrap(value: boolean) /** * Indicates if TextField should be batched on rendering. * * * * This works only with bitmap fonts, and it makes sense only for TextFields with no * * more than 10-15 characters. Otherwise, the CPU costs will exceed any gains you get * * from avoiding the additional draw call. * * * * @default false * */ get batchable(): boolean; set batchable(value: boolean) /** * Indicates if text should be interpreted as HTML code. For a description * * of the supported HTML subset, refer to the classic Flash 'TextField' documentation. * * Clickable hyperlinks and images are not supported. Only works for * * TrueType fonts! @default false */ get isHtmlText(): boolean; set isHtmlText(value: boolean) /** * The padding (in points) that's added to the sides of text that's rendered to a Bitmap. * * If your text is truncated on the sides (which may happen if the font returns incorrect * * bounds), padding can make up for that. Value must be positive. @default 0.0 */ get padding(): number; set padding(value: number) /** * Controls whether or not the instance snaps to the nearest pixel. This can prevent the * * object from looking blurry when it's not exactly aligned with the pixels of the screen. * * @default true */ get pixelSnapping(): boolean; set pixelSnapping(value: boolean) /** * The mesh style that is used to render the text. * * Note that a style instance may only be used on one mesh at a time. */ get style(): MeshStyle; set style(value: MeshStyle) } } export default starling.text.TextField;