krpano 1.19-pr16 (build 2018-04-04)

Textfield Plugin internal / build-in plugin

  • A plugin for displaying HTML/CSS formatted text.
  • The position and size of the plugin can by adjusted with the standard layer attributes.
  • When no custom width/height size will be set, the plugin will resize itself to fit the text.
  • For formating the text, a few HTML-tags, simple CSS-styles or BBCode-like tags can be used. But please note that only a small subset of HTML and CSS is supported by the Flashplayer! Don't try to use real HTML / CSS code! CSS-classes are not supported!
  • Since version 1.19 the the textfield plugin is directly integrated into the viewer and can be used by using type="text". For backward-compatibility the plugin will be also used automatically when trying to load a textfield.swf file (regardless of the path).

Topics

Syntax

As layer: 
<layer name="mytext"
       type="text"
       align="lefttop" x="10" y="10"
       html="Text...[br][b]Bold Text...[/b]"
       css="font-family:Arial; font-size:16px; color:#000000;"
       vcenter="false"
       padding="2"
       wordwrap="true"
       bg="true"
       bgcolor="0xFFFFFF"
       bgalpha="1.0"
       bgborder="0"
       bgroundedge="0"
       bgshadow=""
       txtshadow=""
       mergedalpha="true"
       interactivecontent="false"
       onautosized=""
       />

As hotspot: 
<hotspot name="mytext"
         type="text"
         ath="0" atv="0" edge="center" distorted="true" renderer="webgl"
         html="Text...[br][b]Bold Text...[/b]"
         css="font-family:Arial; font-size:16px; color:#000000;"
         vcenter="false"
         padding="2"
         wordwrap="true"
         bg="true"
         bgcolor="0xFFFFFF"
         bgalpha="1.0"
         bgborder="0"
         bgroundedge="0"
         bgshadow=""
         txtshadow=""
         mergedalpha="true"
         oversampling="1.0"
         mipmapping="false"
         onautosized=""
         />

Plugin Attributes

Attribute nameTypeDefault value
htmlString""
  • Set the HTML / CSS / BBCode formated text.
  • The HTML / CSS code will be rendered by the Flashplayer (Flash-viewer) or by the Browser (HTML5-viewer)! The Flashplayer itself supports only a very small subset of HTML4! For equal results in Flash and HTML5 only very simple html formating code should be used. Using images inside the html code is not recommended, the Flashplayer was very bad and buggy support here.
  • Here a link to the Flashplayer documentation about the HTML support: http://help.adobe.com/.../TextField.html#htmlText
  • When using the < and > characters is not possible (e.g. inside xml attributes), then the [ and ] characters or the tags [lt] and [gt] could be used instead.
  • When using the single-quote ' or double-quote " characters is not possible (e.g. because of xml syntax limitations or the usage as escape character), then [sq] for the 'single-quote' character and [dq] for the 'double-quote' character can be used instead.
  • To get the [ and ] characters itself, use them twice as [[ and ]].
  • There are two possiblites to set the html text:
    1. Either directly in the html attribute: 
      html="[b]Bold Text[/b]"
    2. Or by referring to a <data> xml element and via data:name: 
      html="data:htmltext"
  • It is possible to create links in the html code that can call krpano actions, by using event:actions as link target: 
    <a href="event:showlog(); trace('link clicked');">link</a>
Attribute nameTypeDefault value
cssString""
  • Set the CSS styles for the HTML text.
  • The HTML / CSS code will be rendered by the Flashplayer (Flash-viewer) or by the Browser (HTML5-viewer)! The Flashplayer itself supports only a very small subset of CSS1! For equal results in Flash and HTML5 only very simple css styles code should be used. The usage of CSS classes is not supported
  • Here a link to the Flashplayer documentation about the CSS support: http://help.adobe.com/.../StyleSheet.html
  • There are two possiblites to set the css style:
    1. Either directly in the css attribute: 
      css="text-align:center; color:#FFFFFF; font-family:Arial;"
    2. Or by referring to a <data> xml element and via data:name: 
      css="data:cssstyles"
  • When setting font-sizes, it is important to use 'px' as entity to get the same results in Flash and HTML5.
  • Any occurrence of 0x in the css value will be automatically converted to # to allow using the same color value syntax as in the krpano xml.
Attribute nameTypeDefault value
vcenterBooleanfalse
  • Vertically center the text within the given plugin height.
  • Tip - for horizontal centering use the css style text-align:center;
Attribute nameTypeDefault value
paddingString"2"
Padding / space in pixels around the text. Can be individually for each side.

There are 4 different ways to set the paddings (same as in CSS):
  • padding="25"
    • all four paddings are 25px
  • padding="25 50"
    • top and bottom paddings are 25px
    • right and left paddings are 50px
  • padding="25 50 75"
    • top padding is 25px
    • right and left paddings are 50px
    • bottom padding is 75px
  • padding="25 50 75 100"
    • top padding is 25px
    • right padding is 50px
    • bottom padding is 75px
    • left padding is 100px
Attribute nameTypeDefault value
wordwrapBooleantrue
  • Set if the text should automatically wrap around (line-break) to new lines when the text doesn't fit into the current line.
  • This setting was only an effect when using / setting a custom width.
  • When disabled the text could get cut-off when it is larger than the given width.
Attribute nameTypeDefault value
bg Boolean true
Draw a background shape behind the text.
Attribute nameTypeDefault value
bgcolor int 0xFFFFFF
Background color of the textfield.
Attribute nameTypeDefault value
bgalpha Number 1.0
Transparency / alpha of the background color of the textfield.
Attribute nameTypeDefault value
bgborder String "0"
Add borders around the textfield.

Syntax: 
bgborder="width color alpha"

Parameters:
  • width
    The border line-width.
  • color (optionally)
    The color of the border lines. The default is 0x000000 (black).
  • alpha (optionally)
    Transparency / alpha of the border lines (0.0 to 1.0, default=1.0).
Attribute nameTypeDefault value
bgroundedge String "0"
Define rounded edges of the textfield background color shape.
A value sets the edge rounding radius in pixels.

Four values can be set, one for each edge (separated by space characters). They are given in the order: top-left, top-right, bottom-right, bottom-left. If bottom-left is omitted, it is the same as top-right. If bottom-right is omitted, it is the same as top-left. If top-right is omitted, it is the same as top-left.
Attribute nameTypeDefault value
bgshadow String ""
Add a shadow behind the textfield background shape.

Syntax: 
bgshadow="xoffset yoffset blur color alpha"

Parameters:
  • xoffset, yoffset
    The offset / distance of the shadow in pixels.
  • blur
    The blur radius / range in pixels - defines how strong the shadow will be blurred.
    0 = no blur ⇒ sharp edges.
  • color
    The color of the shadow.
  • alpha
    The alpha / transparency of the shadow.
Attribute nameTypeDefault value
txtshadow String ""
Add a shadow behind the text.

Syntax: 
txtshadow="xoffset yoffset blur color alpha"

Parameters:
  • xoffset, yoffset
    The offset / distance of the shadow in pixels.
  • blur
    The blur radius / range in pixels - defines how strong the shadow will be blurred.
    0 = no blur ⇒ sharp edges.
  • color
    The color of the shadow.
  • alpha
    The alpha / transparency of the shadow.
Attribute nameTypeDefault value
mergedalpha Boolean true
By default the alpha transparency of the background will be applied also to the border and shadow, but by disabling that setting, it would be possible to render the border and shadow with their own and independent alpha transparency.
Attribute name (only for WebGL-Hotspots usage)TypeDefault value
oversampling Number 1.0
Upscale the internal bitmap rendering target by the given oversampling factor for a higher-resolution (sharper) text.

Settings larger 1.0 are improving the text-rendering-quality, but also requiring more memory- and rendering-resources.
Attribute name (only for WebGL-Hotspots usage)TypeDefault value
mipmapping Boolean false
Enable mipmapping - this reduces aliasing effects when displaying the text as scaled-down element.

Mipmapping works by automatically upscaling the internal bitmap rendering target to the next power-of-two size (because that's required for mipmapping). Because of this scaling, it would be recommended to use additionally also oversampling for a better image/text quality - e.g. mipmapping="true" and oversampling="2.0".
Attribute name (HTML5 only)TypeDefault value
interactivecontentBooleanfalse
  • By default krpano doesn't pass mouse events to the inner textfield html content to avoid event tracking conflicts.
  • By enabling this setting this can be disabled, then the mouse events will be also sent also to the textfield html content.
  • When the html content contains <a> or <iframe> elements, then this setting will be automatically enabled.

Plugin Events

Attribute nameTypeDefault value
onautosizedString""
  • This event will be called when the textfield will resize itself automatically. This happens when no custom width and height settings will be set.
  • Note - due the automatic word-breaking, there can be more than one onautosized event when the width or the html content will be changed. The number of events can differ between Flash and HTML5.