Scrollbars

From Frontal Wiki

Showing a Scrollbar

Any visual tag ('div', 'document', 'img', 'text', 'video', 'form' or any custom tag extending the Container class) will have a scrollbar when the "scroll" style is appropriately set and when the dimensions of its contents exceed the dimensions of its content rectangle. (That is, when it has more stuff in it than it can show.)

Here is an example of a scrollbar. Run the following code sample:

<style><![CDATA[
    #outer
        {
            width: 200px;
            height: 200px;
            scroll: auto;
        }
    #inner
        {
            width: 400px;
            height: 400px;
            background-color: red;
            @onRenderBackground
                {
                    if ( state == "afterRender" )
                    {
                        movie.graphics.beginFill(0xffffff);
                        movie.graphics.drawCircle(200, 200, 180);
                        movie.graphics.endFill();
                    }
                }
        }
 
]]></style>
<div id="outer">
    <div id="inner" />
</div>

So note in this example what is happening; we've placed a 400-pixel square div inside of a 200-pixel square div and so there is more content than space to display it. This coupled with the "scroll: auto;" style turns on the vertical and horizontal scrollbars. The scrollbars are positioned inside of the scrollable div (the "outer" div) and that's why they appear where they do - in the middle of the inner div. To achieve a more conventional appearance, we can add the style "overflow: hidden;" to the outer div. Go ahead and do that now.

Styling the Scrollbar

So adding a scrollbar is as easy as that but it is likely that this scrollbar does not fit your design needs. Frontal provides several mechanisms to customize their appearance and behaviors and we describe those next.

Note the structure of the scrollbar in our example. We have a track that holds the scrollbar's draggable slider. Also in this track (and beneath this slider) is a track button. It is this button that captures and responds to clicks on the track above and below the slider. So how is the scrollbar created? The answer is that it uses the Frontal templating feature (see the "template" tag) to insert a small Frontal definition into the scrollable div to create a scrollbar. This scrollbar definition has particular names on the contained elements that the Frontal renderer looks for and applies behaviors to that make them act like a scrollbar. To understand this better, let's take a look at the template included in the Frontal default style sheet for the vertical scrollbar:

<template name="frScrollbarVert">
    <div class="frScrollbarVert">
        <div name="track">
            <div name="trackButton" />
            <div name="slider" />
        </div>
    </div>
</template>

As you can see, the basic structure of the scrollbar is a track that contains a trackButton div and a slider div. The appearance of this scrollbar is controlled by several rulesets that are also in the Frontal default style sheet. The relevant ones for the vertical scrollbar are presented here.

This style class applies to the entire vertical scrollbar. Its primary purpose is to reset the scrollbar to the top whenever the element it is scrolling is reset. The "height: auto;" style will make the scrollbar as tall as the scrollable div.

.frScrollbarVert
{
    wants-reset: true;
    height: auto;
    width: auto;
    overflow: visible;
    @onReset { parent.scrollTop = 0; }
}

This style class applies to the track. The size of the track will in turn set the size of the track button and slider. In this case, we're saying that its height should be whatever is leftover in the parent. (For our scrollbar, that is the entire height but later we will see how we can add scroll buttons and in that case the "leftover" qualifier will leave space for those buttons.)

.frScrollbarVert [name=track]
{
    height: 100% leftover;
    width: auto;
    overflow: visible;
    layout: stack;
}

This style class applies to the track button. It is here that we give the scrollbar its gray appearance and its border. This is also where we attach this button to certain Frontal built-in scrollbar behaviors.

.frScrollbarVert [name=trackButton]
{
    is-link: true;
    width: 100% leftover;
    height: 100% leftover;
    overflow: visible;
    background-color: #cccccc;
    border-color: #999999;
    border-width: 1px;
    @onMouseDown { getScrollbarContainer ( ).startPressScrollbarTrack ( event ); }
    @onMouseUp   { getScrollbarContainer ( ).stopPressScrollbarTrack ( ); }
    @onRollOut   { getScrollbarContainer ( ).stopPressScrollbarTrack ( ); }
}

This style class applies to the slider button. It is here that we give the slider its appearance. This is also where we attach this button to certain Frontal built-in scrollbar behaviors.

.frScrollbarVert [name=slider]
{
    is-link: true;
    width: 100% leftover;
    height: 20px;
    overflow: visible;
    background-color: #666666;
    border-color: #999999;
    border-width: 1px;
    @onMouseDown { getScrollbarContainer ( ).startDragScrollbarSlider ( ); }
    @onMouseUpAnywhere { getScrollbarContainer ( ).stopDragScrollbarSlider ( ); }
}

So imagine that we want to make some cosmetic changes to the vertical scrollbar. For example, let's change its color and give the slider hover and active states. To do this, let's add the following to our style sheet in the previous example:

.frScrollbarVert [name=trackButton] { background-color: #ffcccc; }
.frScrollbarVert [name=slider] { background-color: #ff6666; }
.frScrollbarVert [name=slider]:hover { background-color: #ff0000; }
.frScrollbarVert [name=slider]:active { background-color: #0000ff; }

Changing the Structure of the Scrollbar

That's fairly simple. Now let's imagine that we want to add scroll buttons. How would we do this? The first thing we'd need to do is to redefine the scrollbar template. We do that by simply including a template in our document definition that has the same name as the one included by default:

<template name="frScrollbarVert">
    <div class="frScrollbarVert">
        <img name="up" symbol="MyButton" style="width: 10px; height: 10px; background-color: #ffffff;" />
        <div name="track">
            <div name="trackButton" />
            <div name="slider" />
        </div>
        <img name="down" symbol="MyButton" style="width: 10px; height: 10px; background-color: #ffffff; rotation: 180; movie-registration-x: 5; movie-registration-y: 5;" />
    </div>
</template>

So here we've taken the 'template' defined above for the vertical scrollbar but added two "img" tags one with the name "up" and one with the name "down." (For a horizontal scrollbar, we would have named them "left" and "right.") First, let's add this to the bottom of our example that we've been working on along with this line which will load the "MyButton" symbol:

<include rel="assets" type="application/x-shockwave-flash" src="http://frontalcode.com/assets/swfs/assets.swf" />

So how did that work? Well, the Frontal default style sheet was ready for us as it includes these two rulesets for just this occasion:

.frScrollbarVert [name=up] 
{
    is-link: true;
    @onMouseDown { getScrollbarContainer ( ).startPressScrollButton ( false ); }
    @onMouseUp   { getScrollbarContainer ( ).stopPressScrollButton ( ); }
    @onRollOut   { getScrollbarContainer ( ).stopPressScrollButton ( ); }
}
.frScrollbarVert [name=down] 
{
    is-link: true;
    @onMouseDown { getScrollbarContainer ( ).startPressScrollButton ( true ); }
    @onMouseUp   { getScrollbarContainer ( ).stopPressScrollButton ( ); }
    @onRollOut   { getScrollbarContainer ( ).stopPressScrollButton ( ); }
}

These rulesets make our buttons links and attach certain Frontal built-in scrollbar behaviors.

An obvious question is, how did scrollbar buttons get hover and active behaviors? And how do they go into a disabled state when the scrollbar reaches them? We'll discuss this further in the section on the 'img' tag.

We could also have created a new scrollbar template with a different name rather in case we wanted to have multiple scrollbar layouts in the same document. If we did that, then we'd use the styles scrollbar-horizontal-template and scrollbar-vertical-template to determine which scrollbar to apply to a particular tag.

Frontal assigns functionality to a scrollbar based on what named elements it can find within. So if you don't want the track to be clickable, remove the element with the name "trackButton." Or if you don't want a slider and only want a track button, then just remove the element with the name "slider." In this way you can create scrollbars that only have buttons too.

Properties

These properties are available on all visual elements:

• 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

This method is available on all visual elements:

• 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).

Styles

There are a number of styles to affect how scrollbars appear and behave:

• scrollbar-placement: A combination of "left" or "right" and "bottom" or "top." This style places the scrollbar for this object. By default, the vertical scrollbar is placed to the right and the horizontal scrollbar at the bottom.
• scrollbar-height: This sets the height of a horizontal scrollbar. It may be specified in pixels or as a percentage.
• scrollbar-width: This sets the width of a vertical scrollbar. It may be specified in pixels or as a percentage.
• scrollbar-horizontal-template: The specifies the name of the template to use for this element's horizontal scrollbar.
• scrollbar-vertical-template: The specifies the name of the template to use for this element's horizontal scrollbar.
• scrollbar-scale-slider: If true then the length of the scrollbar slider will be proportional to the amount of content that is visible. If false then the slider will be whatever length its styles set it to. By default this is true.
• scroll-disable-buttons: If true then the elements named "up," "down," "left," and "right" have their "enabled" property appropriately set according to whether or not the current scroll is at is minimum or maximum. Note that it is the enabled property that drives the pseudo-class ":disabled" and so this style allows for scroll buttons to support this pseudo-class. By default this is true.
• scroll-by-button-click: This is how far to scroll when a scroll button is clicked. By default it is 12 pixels. It may also be a percentage.
• scroll-by-button-press: This is how far to scroll each frame that a scroll button is pressed. By default it is 12 pixels. It may also be a percentage.
• scroll-text-by-button-click: This is how far to scroll the text in a text tag in lines when a scroll button is clicked. By default it is 1.
• scroll-text-by-button-press: This is how far to scroll the text in a text tag in lines ch frame that a scroll button is pressed. By default it is 1.
• scroll-by-track-click: This is how far to scroll when the scrollbar's track is clicked. By default it is 100% (of the scrollable div's dimension).
• scroll-by-track-press: This is how far to scroll for each frame that the scrollbar's track is pressed. By default it is 25%.
• scroll-tween-duration: When scrolling, a tween is used to move from the current location to the new one. This style sets how long that tween should take. By default it is 5 (frames). (For text tags, the default is 0 which disables the tween and just does an immediate jump.)
• scroll-scale-tween-duration: As noted, a tween is used to scroll to a new position. If the scroll limit were to be hit during this tween then suddenly the scroll might appear to be moving slowly (since the scroll is traveling a shorter distance but taking the same time as if the limit weren't hit). To make the tween time scale to the distance that actually has to be traveled, set this style to true. By default it is false.
• scroll-tween-use-secs: Set to true if scroll-tween-duration is in seconds. By default this is false.
• scroll-tween-ease: Use this to set the tween function for scrolling. By default it is fl.transitions.easing.Regular.easeOut.
• click-max-frames: This style determines the difference between a press and a click. When the user clicks down on the mouse button then a frame counter is started. When the mouse comes up, if the number of frames counted is less than or equal to this style, then it is counted as a click. If the counter passes the value of this style, then a press is begun and continues until the mouse is released.
• scrollable: This styles determines is a particular document element is subject to the scrollbar or not. By default all elements are but it is convenient to be able to turn it off in some cases like when adding a complex div that acts as a progress indicator. See the Advanced Topics for more details on progress indicators.

Scrollbars on text Tags

See Scrolling a text Tag for specific details of adding a scrollbar to a 'text' tag.