Module scroll

Scroll widgets, commands and properties.

The Scroll! widget accepts a single child of any size, overflow is clipped and can be brought into view by scrolling, the widget also supports content zooming and panning. The mode property can be used to dynamically change the ScrollMode.

use zng::prelude::*;

Scroll! {
    // ZOOM includes PAN that includes VERTICAL and HORIZONTAL
    mode = zng::scroll::ScrollMode::ZOOM;
    // mouse press and drag scrolls
    mouse_pan = true;
     
    child = Image! {
        // center_viewport uses the SCROLL service
        img_loading_fn = wgt_fn!(|_| center_viewport(Text!("loading..")));
         
        // content is a large image
        source = "https://upload.wikimedia.org/wikipedia/commons/e/ea/Van_Gogh_-_Starry_Night_-_Google_Art_Project.jpg";
        img_limits = zng::image::ImageLimits::none();
        img_downscale = zng::image::ImageDownscale::from(layout::Px(8000));
    }
}

fn center_viewport(msg: impl UiNode) -> impl UiNode {
    use zng::scroll::SCROLL;
    Container! {
        // center the message on the scroll viewport:
        //
        // the large images can take a moment to decode in debug builds, but the size
        // is already known after read, so the "loading.." message ends-up off-screen
        // because it is centered on the image.
        layout::x = merge_var!(SCROLL.horizontal_offset(), SCROLL.zoom_scale(), |&h, &s| h.0.fct_l() - 1.vw() / s * h);
        layout::y = merge_var!(SCROLL.vertical_offset(), SCROLL.zoom_scale(), |&v, &s| v.0.fct_l() - 1.vh() / s * v);
        layout::scale = SCROLL.zoom_scale().map(|&fct| 1.fct() / fct);
        layout::transform_origin = 0;
        widget::auto_hide = false;
        layout::max_size = (1.vw(), 1.vh());
         
        child_align = Align::CENTER;
        child = msg;
    }
}

The example above declares a scroll with zoom and mouse pan features enabled, is also makes use of the SCROLL service to implement the center_viewport widget that is place in the content, but transforms to always be in the viewport.

The SCROLL service can be used to interact with the parent Scroll!, you can also use commands in cmd to control any Scroll! widget.

Full API

See zng_wgt_scroll for the full widget API.

Modules

• cmd
  Scroll commands.
• scrollbar
  Scroll widget.
• thumb
  Scrollbar thumb widget.

Structs

• SCROLL
  Controls the parent scroll.
• Scroll
  W A container that can pan and zoom a child of any size.
• ScrollBarArgs
  Arguments for scrollbar widget functions.
• ScrollInfo
  Shared reference to the viewport bounds of a scroll.
• ScrollMode
  What dimensions are scrollable in a widget.
• ScrollUnitsMix
  m Properties that define scroll units.
• Scrollbar
  W Scrollbar widget.
• ScrollbarFnMix
  m Properties that defines the scrollbar widget used in scrolls.
• SmoothScrolling
  Smooth scrolling config.
• Thumb
  W Scrollbar thumb widget.

Enums

• LazyMode
  Lazy loading mode of a widget.
• ScrollFrom
  Defines a scroll delta and to what value source it is applied.

Traits

• WidgetInfoExt
  Scroll extensions for WidgetInfo.

Functions

• alt_factor
  P Scroll unit multiplier used when alternate scrolling.
• auto_hide_extra
  P Extra space added to the viewport auto-hide rectangle.
• clip_to_viewport
  c Clip content to only be visible within the viewport, not under scrollbars.
• define_viewport_unit
  P If the scroll defines its viewport size as the LayoutMetrics::viewport for the scroll content.
• h_line_unit
  P Horizontal offset added when the SCROLL_RIGHT_CMD runs and removed when the SCROLL_LEFT_CMD runs.
• h_page_unit
  P Horizontal offset added when the PAGE_RIGHT_CMD runs and removed when the PAGE_LEFT_CMD runs.
• h_scrollbar_fn
  P Horizontal scrollbar function for all scroll widget descendants.
• h_wheel_unit
  P Horizontal offset added when the mouse wheel is scrolling by lines.
• lazy
  P Enables lazy init for the widget.
• line_units
  P Horizontal and vertical offsets used when scrolling.
• max_zoom
  P Maximum scale allowed when ScrollMode::ZOOM is enabled.
• min_zoom
  P Minimum scale allowed when ScrollMode::ZOOM is enabled.
• mode
  c Scroll mode.
• mouse_pan
  P Scroll by grabbing and dragging the content with the mouse primary button.
• overscroll_color
  P Color of the overscroll indicator.
• page_units
  P Horizontal and vertical offsets used when page-scrolling.
• scroll_to_focused_mode
  P Scroll-to mode used by scroll widgets when scrolling to make the focused child visible.
• scrollbar_fn
  P Scrollbar function for both orientations applicable to all scroll widget descendants.
• scrollbar_joiner_fn
  P Widget function for the little square in the corner that joins the two scrollbars when both are visible.
• smooth_scrolling
  P Smooth scrolling config.
• v_line_unit
  P Vertical offset added when the SCROLL_DOWN_CMD runs and removed when the SCROLL_UP_CMD runs.
• v_page_unit
  P Vertical offset added when the PAGE_DOWN_CMD runs and removed when the PAGE_UP_CMD runs.
• v_scrollbar_fn
  P Vertical scrollbar function for all scroll widget descendants.
• v_wheel_unit
  P Vertical offset added when the mouse wheel is scrolling by lines.
• wheel_units
  P Horizontal and vertical offsets used when mouse wheel scrolling.
• zoom_origin
  P Center point of zoom scaling done using mouse scroll wheel and touch gesture.
• zoom_touch_origin
  P Center point of zoom scaling done using the touch pinch gesture.
• zoom_wheel_origin
  P Center point of zoom scaling done using the mouse scroll wheel.
• zoom_wheel_unit
  P Scale delta added when the mouse wheel is zooming by lines.