Div

From Frontal Wiki

Introduction to the div tag

The "div" (short for "division") tag is a basic building block of Frontal. It's basic format is simply:

<div />

Frontal uses the same box model as CSS2 described here: http://www.w3.org/TR/CSS2/box.html http://www.w3.org/TR/CSS2/box.html

In this model, each element has top, left, bottom and right margins, borders and padding (in that order) surrounding a content rectangle. In this model, applying a background-color style will color the padding and content rectangle but not the margins. Also in this model, the dimensions of the entire element are the sum of the margin, border, padding and content widths by their heights. We mention this in introduction to a Container's properties and methods.

Implementation

It is a visual element implemented by the Container class which extends the ubiquitous DocumentElement class.

Properties

On top of the DocumentElement properties, Container adds the following properties:

• movie: This is the movie used to render this element. It is an instance of FrontalSprite which extends the Flash Sprite class. Read only.
• mask: If this movie has the "overflow: hidden;" style then this Flash DisplayObject is used to mask the element's contents. Read only.
• childrenMovies: A Flash Dictionary keyed by our children objects' movies and with values that are the chidren objects. Read only.
• The following are evaluations of some of the element's styles. If the related style was not set on this element, then the property is NaN. Read only.
  • left
  • right
  • top
  • bottom
  • marginTop
  • marginBottom
  • marginLeft
  • marginRight
  • paddingTop
  • paddingBottom
  • paddingLeft
  • paddingRight
  • borderTop
  • borderBottom
  • borderLeft
  • borderRight
  • width
  • height
• xPos: The left side of the element's display box relative to it's parent's content rectangle. Read only.
• yPos: The top of the element's display box relative to it's parent's content rectangle. Read only.
• contentWidth: The width of the content rectangle. Read only.
• contentHeight: The height of the content rectangle. Read only.
• unboundedContentWidth: This is the combined width of this element's children. If this value is greater than contentWidth then a horizontal scrollbar is possible. Read only.
• unboundedContentHeight: This is the combined height of this element's children. If this value is greater than contentHeight then a vertical scrollbar is possible. Read only.
• containerWidth: The entire width of this element's box including margins, border, padding and content. Read only.
• containerHeight: The entire height of this element's box including margins, border, padding and content. Read only.
• intrinsicWidth: The width of the element as defined by its contents. By default, this is not a number but, for example, the video object will return the width of the FLVPlayback player. Read only.
• intrinsicHeight: See intrinsicWidth. Read only.
• enabled: Set to true or false to enabled or disable the user interactions on this object.
• scrollbarWidth: The width of the visible vertical scrollbar or zero. This may be set with the style scrollbar-width. Read only.
• scrollbarHeight: The height of the visible horizontal scrollbar or zero. This may be set with the style scrollbar-height. Read only.
• scrollTopMax: The maximum value for scrollTop. This is the maximum of zero and unboundedContentHeight - contentHeight. Read only.
• scrollTop: The current vertical scroll value.
• scrollLeftMax: The maximum value for scrollLeft. This is the maximum of zero and unboundedContentWidth - contentWidth. Read only.
• scrollLeft: The current horizontal scroll value.

Methods

It adds the following methods:

• synchStyles: This method looks at the properties of the movie that are mapped to styles and sets the styles to match. The utility of this is shown in an example below.
• scrollBy: This method will scroll the children boxes inside this objects content box limited by scrollTopMax and scrollLeftMax. It takes the following parameters:
  • delta: The amount to scroll by. delta is a length so the following are valid: 100, "100px," "80%." Percentages are relative to the container's dimensions and not the content's.
  • positive: Whether to scroll down or right (true) or up or down (false). Default is true.
  • isVertical: Whether to scroll vertically (true) or horizontally (false).
  • immediately: Whether to tween to the new position (false) or to jump there immediately (true).

Here is an example of how synchStyles lets us change a movie's properties (here by dragging it) and then update the styles to match them. Note that the Frontal console pops up to show the newly calculated values of the left and top styles when you release the square.

<style><![CDATA[
    #square
        {
            @onMouseDown
                {
                    sS ( "disable-rendering", true );
                    movie.startDrag ( );
                }
            @onMouseUpAnywhere
                {
                    movie.stopDrag ( );
                    sS ( "disable-rendering", false );
                    synchStyles ( );
                    com.frontalcode.Debugger.msg ( gS ( "left" ) + ", " + gS ( "top" ) );
                }
        }
]]></style>
<div id="square" style="left: 10px; top: 10px; width: 10px; height: 10px; background-color: red;" />

Notice that if we comment out the call to synchStyles then the square always jumps back to its original position whenever we release it. Also note that we are using the "disable-rendering" style. This isn't so useful in this simple example but in a more complex one where there might be renders occurring during the drag, we wouldn't want the square to return to its starting point then either. This style says to not render this object while it is true.

As a DocumentElement object, the "div" element supports many of the system interactions listed in the "Adding Interactions" section. And as a visual element, it supports all of the user interactions like onClick and onRollOver.

Styles

Styles particular to the div element are:

• overflow: "visible" or "hidden," this determines if the content rectangle including padding and borders will be masked or not. Note that due to a Flash bug, setting overflow to hidden and setting any styles that enable a filter on the movie makes the movie not reliably responsive to user interactions. A workaround is to wrap a div inside of a div and apply the mask to one and the filter styles to the other.
• mask: Use this style to specify the name of a class to use to instantiate the mask. The class may exist in an external resource (see the "include" tag) in which case the mask will not be applied until the external resource is loaded.
• scale-mask: If true then the mask will be scaled to the size of the content rectangle including padding and borders will be masked or not. This is useful when the mask style is a movie class name and so a fixed width and height.
• display: "block" or "none." If "none" then the object will not be displayed and will not affect the layout of elements. If "block" then it will be displayed normally.
• visibility: "visible" or "hidden." If "hidden" then the object will not be displayed and will affect the layout of elements.
• z-index: Set this to a number to control the depths of this object relative to its siblings.
• layout: "stack" or "normal." If "stack" then all children element will be top- and left-aligned. Otherwise, the layout is normal as described in the section "Frontal's Layout Scheme."
• float: "left," "right" or "none." This style is similar to the one used in HTML and CSS. It allows for the dimensions of an object to affect its sibling. See the section "Frontal's Layout Scheme."
• clear: "left," "right" or "both." This style allows us to control break points in the left, right and normal floating objects. See the section "Frontal's Layout Scheme."
• background-color: Sets the background color for the content rectangle and padding.
• background-alpha: The alpha for the background.
• background-shape: One of "rectangle," "ellipse" or "rounded rectangle." If "rounded rectangle" then the following styles also apply. (See the Flash documentation of drawRoundRect for more details.)
  • bg-shape-ellipse-width
  • bg-shape-ellipse-height
• border-color: The color for the border.
• border-alpha: The alpha for the border.
• border-shape: One of "rectangle," "ellipse" or "rounded rectangle." If "rounded rectangle" then the following styles also apply. (See the Flash documentation of drawRoundRect for more details.)
  • border-shape-ellipse-width
  • border-shape-ellipse-height
• resize-anchors: A combination of "left," "right," "bottom" and "top," this positions a div relative to its parent (where the concept of "parent" may be altered via the pin-to-container or pin-to-stage styles). You may apply left and right resize anchors (as well as top and bottom) to scale the div. Note that a value of "left" is equivalent to setting the "left" style to 0 and a value of "right" is equivalent to setting the "right" style to 100%. Similar equivalencies exist between the values "top" and "bottom" and the same-named styles. Using these styles then, you can achieve far more control than with the resize-anchors style.
• pin-to-container: This takes the id (set with the "id" attribute) of another element. It tells this object to position itself relative to that container. That is, in the Flash display list, the movie remains at its position as defined by the Frontal definition and so is masked and layered as normal. But in applying styles like "left," "top," "width" and "height," the containing block used in processing these values is no longer the parent in the Frontal definition but the container identified by this style's value.
• pin-to-stage: This is similar to pin-to-container but rather than evaluating styles relative to another DocumentElement, it is done relative to the Stage.

The following are dimension styles. They may take various values like "10px," "40%," "auto" or "20% leftover:"

• width
• height
• left
• right
• top
• bottom
• margin-top
• margin-left
• margin-bottom
• margin-right
• margin: This convenience style lets you set all four border width styles at once, e.g.,"margin: auto;" sets all four margins to auto. "margin: 0px 10%;" set the top and bottom margins to 0 and the right and left to 10%. "margin: 10px 20px 30px;" sets the top margin to 10px, the right and left margins to 20px and the bottom margin to 30px. Finally, "margin: 10px 20px 30px 40px;" does the same but sets the left margin to 40px.
• padding-top
• padding-left
• padding-bottom
• padding-right
• border-top-width
• border-left-width
• border-bottom-width
• border-right-width
• border: This convenience style lets you set all four border width styles at once. It works similarly to the "margin" style. (The shorthand method that CSS provides to set style, width and color all at once is not supported.)

There are a number of background gradient styles. These relate to Flash's beginGradientFill method and its documentation should be consulted:

• bg-gradient-type
• bg-gradient-colors
• bg-gradient-alphas
• bg-gradient-ratios
• bg-gradient-matrix
• bg-gradient-spread
• bg-gradient-interpolation
• bg-gradient-focal-point-ratio

There are a number of background gradient styles. These relate to Flash's lineGradientStyle method and its documentation should be consulted:

• border-gradient-type
• border-gradient-colors
• border-gradient-alphas
• border-gradient-ratios
• border-gradient-matrix
• border-gradient-spread
• border-gradient-interpolation
• border-gradient-focal-point-ratio

The following styles have a direct correlation to a FrontalSprite (and in many cases a Flash Sprite) property:

• movie-registration-x: Sets the point around which scaling and rotation will be done.
• movie-registration-y: Sets the point around which scaling and rotation will be done.
• cache-as-bitmap: Sets the movie's cacheAsBitmap property.
• blend-mode: Sets the movie's blend mode. One of add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen or subtract.
• tab-children: Sets the movie's tabChildren property.
• double-click-enabled: Set the movie's doubleClickEnabled property.
• mouse-enabled: Sets the movie's mouseEnabled property.
• scale-x: Maps to scaleX. The operation is performed around the point specified by movie-registration-x and movie-registration-y.
• scale-y: Maps to scaleY. The operation is performed around the point specified by movie-registration-x and movie-registration-y.
• scale: Maps to scale. (scale is specific to Frontal and sets both the x and y scale.) The operation is performed around the point specified by movie-registration-x and movie-registration-y.
• alpha: Sets the alpha.
• brightness: Sets the brightness (from -255 to 255) of the DocumentElement's movie. If this is non-zero, a ColorMatrixFilter is applied to do this.
• rotation: Sets the rotation of the movie. The operation is performed around the point specified by movie-registration-x and movie-registration-y.

The following are FrontalSprite properties that apply a Flash BlurFilter to the DocumentElement's movie. This filter is applied only when the blur-x and blur-y styles (or combined, the blur style) are non-zero.

• blur-x: Maps to the blurX property of the filter.
• blur-y: Maps to the blurY property of the filter.
• blur: Sets both the blurX and blurY properties.
• blur-quality: Sets the quality of the filter.

The following are FrontalSprite properties that apply a Flash DropShadowFilter to the DocumentElement's movie. This filter is applied only when the shadow-alpha, shadow-distance and shadow-strength styles are non-zero.

• shadow-alpha: Maps to the alpha property of the filter.
• shadow-distance: Maps to the distance property of the filter.
• shadow-strength: Maps to the strength property of the filter.
• shadow-angle: Maps to the angle property of the filter.
• shadow-blur-x: Maps to the blurX property of the filter.
• shadow-blur-y: Maps to the blurY property of the filter.
• shadow-blur: Set both the blurX and blurY properties of the filter.
• shadow-color: Maps to the color property of the filter.
• shadow-inner: Maps to the inner property of the filter.
• shadow-hide-object: Maps to the hideObject property of the filter.
• shadow-knockout: Maps to the knockout property of the filter.
• shadow-quality: Maps to the quality property of the filter.

The following are FrontalSprite properties that apply a Flash GlowFilter to the DocumentElement's movie. This filter is applied only when the glow-alpha and glow-strength styles are non-zero.

• glow-alpha: Maps to the alpha property of the filter.
• glow-strength: Maps to the strength property of the filter.
• glow-blur-x: Maps to the blurX property of the filter.
• glow-blur-y: Maps to the blurY property of the filter.
• glow-blur: Set both the blurX and blurY properties of the filter.
• glow-color: Maps to the color property of the filter.
• glow-inner: Maps to the inner property of the filter.
• glow-knockout: Maps to the knockout property of the filter.
• glow-quality: Maps to the quality property of the filter.

If a movie has a user interaction on it that is not "raw" (see "Adding Interactions") then Frontal will set the movie's buttonMode property to true, it's mouseChildren property to false and tabEnabled property to true. (See the documentation for the Flash Sprite for details of these properties.) Use the following styles to override this behavior or to set the properties on movies that do not have user interactions.

• button-mode: Sets the movie's buttonMode property.
• mouse-children: Sets the movie's mouseChildren property.
• tab-enabled: Sets the movie's tabEnabled property.
• use-hand-cursor: Sets the movie's useHandCursor property.

There are also styles for applying a scrollbar to a div (or any tag that is based on the Container class) and we will discuss those in the next section.

And finally, there are styles to control progress indicators for a div and we discuss those in the Progress Indicators section.

Laying Out Divs

Be sure to read Frontal's Layout Scheme to understand how a div's styles and relationship to other elements in the Frontal document determine how it will appear after rendering.

Applying a Scrollbar

See Scrollbars for details about adding a scrollbar to a 'div' or to any of the tags that extend the Container class.