Class rtk.Viewport

Class Hierarchy

A scrollable single-child container.

Viewports intentionally only support a single child, but that child can of course be a container.

When child widgets within the viewport are dragging (where ondragstart() returns a positive value), the viewport's scrollbar will appear if the dragging child has its show_scrollbar_on_drag attribute set to true (as is default). This is a common idiom for drag-and-drop as it reveals where in the viewport the user is dragging, and also invites edge scrolling by dragging outside the boundary of the viewport (and this is supported by rtk.Viewport).

The default rtk.Viewport behavior is optimized for vertical scrolling while trying to minimize the need to scroll horizontally.

Vertical scrollbars only

Currently only vertical scrollbars are supported. Horizontal scrolling can be achieved programmatically (e.g. via scrollto()) but horizontal scrollbars haven't yet been implemented.

Scrollbar Constants

Used with the vscrollbar attribute, where lowercase strings of these constants without the SCROLLBAR_ prefix can be used for convenience (e.g. never instead of rtk.Viewport.SCROLLBAR_NEVER).

rtk.Viewport.SCROLLBAR_NEVER

'never'

Never show the scrollbar, and so user can only scroll the viewport by using the mouse wheel. Programmatic scrolling is also possible.

rtk.Viewport.SCROLLBAR_HOVER

'hover'

Only show the scrollbar when the mouse hovers over the gutter area. Space is not reserved for the scrollbar: the child is able to consume this space and the scrollbar will be drawn over top.

rtk.Viewport.SCROLLBAR_ALWAYS

'always'

Always show the scrollbar when there is content to be scrolled. Unlike SCROLLBAR_HOVER, space is reserved for the scrollbar and so the child won't overlap with the scrollbar handle.

Class API

Synopsis

Attributes
child rtk.Widget

read/write

The child widget that is to scroll within this viewport

scroll_left number

read/write

Vertical scroll offset in pixels

scroll_top number

read/write

Horizontal scroll offset in pixels

smoothscroll boolean or nil

read/write

Controls whether scrolling the viewport either programmatically or via the mouse wheel should animate smoothly (default nil)

scrollbar_size number

read/write

The thickness of the scrollbar handle in pixels

vscrollbar scrollbarconst

read/write

Visibility of the vertical scrollbar (default SCROLLBAR_HOVER)

vscrollbar_offset number

read/write

Number of pixels inside the viewport area to offset the vertical scrollbar, where 0 positions the scrollbar at the right edge of the viewport as normal (default 0)

vscrollbar_gutter number

read/write

Number of pixels from the edge of the viewport that defines the "hot zone" where, when the mouse enters this region, a SCROLLBAR_HOVER scrollbar will appear with a low opacity

flexw boolean

read/write

Controls whether the child widget should be asked to constrain its width to the viewport's box (false) or if the viewport's inner width should be flexible and allow the child infinite width under the assumption that we want to allow horizontal scrolling (true) (default is false)

flexh boolean

read/write

Like flexw but for height (default true)

shadow colortype

read/write

If set, a shadow will be drawn around the viewport with the specified color (default nil)

elevation number

read/write

When shadow is set, this defines the apparent distance the viewport is hovering above what's underneath (default 20)

Methods
rtk.Viewport()

Create a new viewport with the given attributes

scrollto()

Scrolls the viewport to a specific horizontal and/or vertical offset

scrollby()

Scrolls the viewport horizontally and/or vertically by a relative offset

scrollable()

Returns true if the viewport's child has at least one dimension greater than the viewport's own bounding box such that scrolling would be necessary to see the entire child

Attributes

rtk.Viewport.child rtk.Widget read/write

The child widget that is to scroll within this viewport.

This attribute may be passed as the first positional argument during initialization:

-- This ...
local vp = rtk.Viewport{box}
-- ... is equivalent to this
local vp = rtk.Viewport{child=box}

Because rtk.Viewport doesn't implement the rtk.Container interface (instead being a much simpler single-child type container), there's no method analogous to rtk.Container:add(). Placing the single child within the viewport is done by setting this attribute. It does mean that viewports don't provide the cell attributes capability; the widget's margin is respected, however, and can be used to provide visual distance between the viewport boundary and the child widget.

rtk.Viewport.scroll_left number read/write

Vertical scroll offset in pixels. See also scrollby() and scrollto().

rtk.Viewport.scroll_top number read/write

Horizontal scroll offset in pixels. See also scrollby() and scrollto().

rtk.Viewport.smoothscroll boolean or nil read/write

Controls whether scrolling the viewport either programmatically or via the mouse wheel should animate smoothly (default nil).

If nil, the global rtk.smoothscroll value is used. If true or false, it explicitly overrides the global default for this viewport.

rtk.Viewport.scrollbar_size number read/write

The thickness of the scrollbar handle in pixels. The scrollbar position ignores padding and is always aligned to the viewport's border.

rtk.Viewport.vscrollbar scrollbarconst read/write

Visibility of the vertical scrollbar (default SCROLLBAR_HOVER).

rtk.Viewport.vscrollbar_offset number read/write

Number of pixels inside the viewport area to offset the vertical scrollbar, where 0 positions the scrollbar at the right edge of the viewport as normal (default 0).

Any positive value will draw the scrollbar that number of pixels inside the viewport. Negative values will have undefined behavior.

rtk.Viewport.vscrollbar_gutter number read/write

Number of pixels from the edge of the viewport that defines the "hot zone" where, when the mouse enters this region, a SCROLLBAR_HOVER scrollbar will appear with a low opacity. The opacity increases once the mouse moves directly over the scrollbar handle.

rtk.Viewport.flexw boolean read/write

Controls whether the child widget should be asked to constrain its width to the viewport's box (false) or if the viewport's inner width should be flexible and allow the child infinite width under the assumption that we want to allow horizontal scrolling (true) (default is false).

rtk.Viewport.flexh boolean read/write

Like flexw but for height (default true).

rtk.Viewport.shadow colortype read/write

If set, a shadow will be drawn around the viewport with the specified color (default nil). The alpha channel in the color affects the weight of the shadow (e.g. #00000066).

rtk.Viewport.elevation number read/write

When shadow is set, this defines the apparent distance the viewport is hovering above what's underneath (default 20).

Methods

rtk.Viewport(attrs, ...)

Create a new viewport with the given attributes.

Return Values
(rtk.Viewport)

the new viewport widget

rtk.Viewport:scrollto(x, y, smooth)

Scrolls the viewport to a specific horizontal and/or vertical offset.

If either value is nil then the current position will be used, allowing you to scroll only in one direction. Values that exceed the viewport bounds will be clamped as needed.

This is a shorthand for calling attr() on the scroll_left and scroll_top attributes, but unlike attr() this also allows overriding smoothscroll.

Parameters
x (number or nil)

the offset from the left edge to scroll the viewport, or nil to not scroll horizontally

y (number or nil)

the offset from the top edge to scroll the viewport, or nil to not scroll vertically

smooth (boolean or nil)

true to force smooth scrolling even if smoothscroll is false, false to force-disable smooth scrolling even if smoothscroll is true, or nil to use the current value of smoothscroll

rtk.Viewport:scrollby(offx, offy, smooth)

Scrolls the viewport horizontally and/or vertically by a relative offset.

Parameters
offx (number or nil)

the offset from the current scroll_left value, or nil to not scroll horizontally

offy (number or nil)

the offset from the current scroll_top value, or nil to not scroll vertically

smooth (boolean or nil)

true to force smooth scrolling even if smoothscroll is false, false to force-disable smooth scrolling even if smoothscroll is true, or nil to use the current value of smoothscroll

rtk.Viewport:scrollable()

Returns true if the viewport's child has at least one dimension greater than the viewport's own bounding box such that scrolling would be necessary to see the entire child.

Return Values
(boolean)

true if the viewport's child is larger than the viewport, false otherwise.

Event Handlers

See also handlers for rtk.Widget.

Synopsis

Methods
onscrollpre()

Called when the viewport scrolls before the child is drawn

onscroll()

Called when the viewport scrolls after the child is drawn

rtk.Viewport:onscrollpre(last_left, last_top, event)

Called when the viewport scrolls before the child is drawn.

The scroll_left and scroll_top attributes indicate the new scroll offsets.

This callback has the opportunity to block or mutate the scroll position before the viewport child is drawn. Because it's invoked before the child is drawn, handlers must not access any of the child's attributes that are populated on draw, such as offx/offy or clientx/clienty.

Parameters
last_left (number)

the last horizontal scroll offset before the change

last_top (number)

the last vertical scroll offset before the change

event (rtk.Event)

the event that occurred at the time of the redraw when the change in scroll position was noticed

Return Values
(boolean or nil)

if false, the scroll is rejected and the previous scroll offsets are restored, otherwise any other value allows the scroll to occur.

rtk.Viewport:onscroll(last_left, last_top, event)

Called when the viewport scrolls after the child is drawn.

The scroll_left and scroll_top attributes indicate the new scroll offsets.

Because this is invoked after the child is drawn, draw-provided attributes such as offx/offy or [clientx](../class/rtk.Widget.html#rtk.Widget.clientx)/[clienty`](../class/rtk.Widget.html#rtk.Widget.clienty) will be available.

This callback is invoked prior to ondraw().

Parameters
last_left (number)

the last horizontal scroll offset before the change

last_top (number)

the last vertical scroll offset before the change

event (rtk.Event)

the event that occurred at the time of the redraw when the change in scroll position was noticed

Return Values
(nil)

Return value has no significance. This is a notification event only.