rtk.Viewport
¶
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.
Currently only vertical scrollbars are supported. Horizontal scrolling can be
achieved programmatically (e.g. via scrollto()) but horizontal scrollbars
haven't yet been implemented.
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. The user can only scroll the viewport by using the mouse wheel or by touch scrolling (if enabled). Programmatic scrolling is also possible. |
| rtk.Viewport.SCROLLBAR_HOVER¶ | 'hover' |
Only show the scrollbar when the mouse hovers over the viewport area. Space is not reserved for the scrollbar: the child is able to consume this space and the scrollbar will be drawn over top as a translucent overlay. This is the default mode. |
| rtk.Viewport.SCROLLBAR_AUTO¶ | 'auto' |
Spaces is reserved for the scrollbar only when there is content to be scrolled,
otherwise the child is allowed to fill the entire viewport size, which ensures the
scrollbar will never be drawn over child content. As with |
| rtk.Viewport.SCROLLBAR_ALWAYS¶ | 'always' |
Always reserve space for the scrollbar, even if scrolling isn't required to see all the viewport's contents. The scrollbar is only visible when there are contents to be scrolled, but unlike the other modes, in this case the scrollbar will always be drawn even when the mouse isn't inside the viewport area. |
| 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 |
| 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 |
| flexw | boolean | read/write |
Controls whether the |
| flexh | boolean | read/write |
Like |
| 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 |
| 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 |
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.
Vertical scroll offset in pixels. See also scrollby() and scrollto().
Horizontal scroll offset in pixels. See also scrollby() and scrollto().
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.
The thickness of the scrollbar handle in pixels. The scrollbar position ignores
padding and is always aligned to the viewport's border.
Visibility of the vertical scrollbar (default SCROLLBAR_HOVER).
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.
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.
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).
Like flexw but for height (default true).
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).
When shadow is set, this defines the apparent distance the viewport is hovering above
what's underneath (default 20).
Create a new viewport with the given attributes.
| (rtk.Viewport) | the new viewport widget |
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.
| 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 |
Scrolls the viewport horizontally and/or vertically by a relative offset.
| offx | (number or nil) | the offset from the current |
| offy | (number or nil) | the offset from the current |
| smooth | (boolean or nil) | true to force smooth scrolling even if |
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.
| (boolean) | true if the viewport's child is larger than the viewport, false otherwise. |
See also handlers for rtk.Widget.
| onscrollpre() | Called when the viewport scrolls before the |
| onscroll() | Called when the viewport scrolls after the |
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.
| 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 |
| (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. |
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/clienty will be available.
This callback is invoked prior to ondraw().
| 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 |
| (nil) | Return value has no significance. This is a notification event only. |