Struct egui::containers::scroll_area::ScrollArea
source · pub struct ScrollArea {
scroll_enabled: Vec2b,
auto_shrink: Vec2b,
max_size: Vec2,
min_scrolled_size: Vec2,
scroll_bar_visibility: ScrollBarVisibility,
id_source: Option<Id>,
offset_x: Option<f32>,
offset_y: Option<f32>,
scrolling_enabled: bool,
drag_to_scroll: bool,
stick_to_end: Vec2b,
animated: bool,
}
Expand description
Add vertical and/or horizontal scrolling to a contained Ui
.
By default, scroll bars only show up when needed, i.e. when the contents
is larger than the container.
This is controlled by Self::scroll_bar_visibility
.
There are two flavors of scroll areas: solid and floating.
Solid scroll bars use up space, reducing the amount of space available
to the contents. Floating scroll bars float on top of the contents, covering it.
You can change the scroll style by changing the crate::style::Spacing::scroll
.
§Coordinate system
- content: size of contents (generally large; that’s why we want scroll bars)
- outer: size of scroll area including scroll bar(s)
- inner: excluding scroll bar(s). The area we clip the contents to.
If the floating scroll bars settings is turned on then inner == outer
.
§Example
egui::ScrollArea::vertical().show(ui, |ui| {
// Add a lot of widgets here.
});
You can scroll to an element using Response::scroll_to_me
, Ui::scroll_to_cursor
and Ui::scroll_to_rect
.
Fields§
§scroll_enabled: Vec2b
Do we have horizontal/vertical scrolling enabled?
auto_shrink: Vec2b
§max_size: Vec2
§min_scrolled_size: Vec2
§scroll_bar_visibility: ScrollBarVisibility
§id_source: Option<Id>
§offset_x: Option<f32>
§offset_y: Option<f32>
§scrolling_enabled: bool
If false, we ignore scroll events.
drag_to_scroll: bool
§stick_to_end: Vec2b
If true for vertical or horizontal the scroll wheel will stick to the end position until user manually changes position. It will become true again once scroll handle makes contact with end.
animated: bool
If false, scroll_to_*
functions will not be animated
Implementations§
source§impl ScrollArea
impl ScrollArea
sourcepub fn horizontal() -> Self
pub fn horizontal() -> Self
Create a horizontal scroll area.
sourcepub fn neither() -> Self
pub fn neither() -> Self
Create a scroll area where both direction of scrolling is disabled. It’s unclear why you would want to do this.
sourcepub fn new(scroll_enabled: impl Into<Vec2b>) -> Self
pub fn new(scroll_enabled: impl Into<Vec2b>) -> Self
Create a scroll area where you decide which axis has scrolling enabled.
For instance, ScrollArea::new([true, false])
enables horizontal scrolling.
sourcepub fn max_width(self, max_width: f32) -> Self
pub fn max_width(self, max_width: f32) -> Self
The maximum width of the outer frame of the scroll area.
Use f32::INFINITY
if you want the scroll area to expand to fit the surrounding Ui
(default).
See also Self::auto_shrink
.
sourcepub fn max_height(self, max_height: f32) -> Self
pub fn max_height(self, max_height: f32) -> Self
The maximum height of the outer frame of the scroll area.
Use f32::INFINITY
if you want the scroll area to expand to fit the surrounding Ui
(default).
See also Self::auto_shrink
.
sourcepub fn min_scrolled_width(self, min_scrolled_width: f32) -> Self
pub fn min_scrolled_width(self, min_scrolled_width: f32) -> Self
The minimum width of a horizontal scroll area which requires scroll bars.
The ScrollArea
will only become smaller than this if the content is smaller than this
(and so we don’t require scroll bars).
Default: 64.0
.
sourcepub fn min_scrolled_height(self, min_scrolled_height: f32) -> Self
pub fn min_scrolled_height(self, min_scrolled_height: f32) -> Self
The minimum height of a vertical scroll area which requires scroll bars.
The ScrollArea
will only become smaller than this if the content is smaller than this
(and so we don’t require scroll bars).
Default: 64.0
.
sourcepub fn scroll_bar_visibility(
self,
scroll_bar_visibility: ScrollBarVisibility,
) -> Self
pub fn scroll_bar_visibility( self, scroll_bar_visibility: ScrollBarVisibility, ) -> Self
Set the visibility of both horizontal and vertical scroll bars.
With ScrollBarVisibility::VisibleWhenNeeded
(default), the scroll bar will be visible only when needed.
sourcepub fn id_source(self, id_source: impl Hash) -> Self
pub fn id_source(self, id_source: impl Hash) -> Self
A source for the unique Id
, e.g. .id_source("second_scroll_area")
or .id_source(loop_index)
.
sourcepub fn scroll_offset(self, offset: Vec2) -> Self
pub fn scroll_offset(self, offset: Vec2) -> Self
Set the horizontal and vertical scroll offset position.
Positive offset means scrolling down/right.
See also: Self::vertical_scroll_offset
, Self::horizontal_scroll_offset
,
Ui::scroll_to_cursor
and
Response::scroll_to_me
sourcepub fn vertical_scroll_offset(self, offset: f32) -> Self
pub fn vertical_scroll_offset(self, offset: f32) -> Self
Set the vertical scroll offset position.
Positive offset means scrolling down.
See also: Self::scroll_offset
, Ui::scroll_to_cursor
and
Response::scroll_to_me
sourcepub fn horizontal_scroll_offset(self, offset: f32) -> Self
pub fn horizontal_scroll_offset(self, offset: f32) -> Self
Set the horizontal scroll offset position.
Positive offset means scrolling right.
See also: Self::scroll_offset
, Ui::scroll_to_cursor
and
Response::scroll_to_me
sourcepub fn scroll(self, scroll_enabled: impl Into<Vec2b>) -> Self
pub fn scroll(self, scroll_enabled: impl Into<Vec2b>) -> Self
Turn on/off scrolling on the horizontal/vertical axes.
You can pass in false
, true
, [false, true]
etc.
sourcepub fn scroll2(self, scroll_enabled: impl Into<Vec2b>) -> Self
👎Deprecated: Renamed to scroll
pub fn scroll2(self, scroll_enabled: impl Into<Vec2b>) -> Self
scroll
Turn on/off scrolling on the horizontal/vertical axes.
sourcepub fn enable_scrolling(self, enable: bool) -> Self
pub fn enable_scrolling(self, enable: bool) -> Self
Control the scrolling behavior.
- If
true
(default), the scroll area will respond to user scrolling. - If
false
, the scroll area will not respond to user scrolling.
This can be used, for example, to optionally freeze scrolling while the user
is typing text in a TextEdit
widget contained within the scroll area.
This controls both scrolling directions.
sourcepub fn drag_to_scroll(self, drag_to_scroll: bool) -> Self
pub fn drag_to_scroll(self, drag_to_scroll: bool) -> Self
Can the user drag the scroll area to scroll?
This is useful for touch screens.
If true
, the ScrollArea
will sense drags.
Default: true
.
sourcepub fn auto_shrink(self, auto_shrink: impl Into<Vec2b>) -> Self
pub fn auto_shrink(self, auto_shrink: impl Into<Vec2b>) -> Self
For each axis, should the containing area shrink if the content is small?
- If
true
, egui will add blank space outside the scroll area. - If
false
, egui will add blank space inside the scroll area.
Default: true
.
sourcepub fn animated(self, animated: bool) -> Self
pub fn animated(self, animated: bool) -> Self
Should the scroll area animate scroll_to_*
functions?
Default: true
.
sourcepub(crate) fn is_any_scroll_enabled(&self) -> bool
pub(crate) fn is_any_scroll_enabled(&self) -> bool
Is any scrolling enabled?
sourcepub fn stick_to_right(self, stick: bool) -> Self
pub fn stick_to_right(self, stick: bool) -> Self
The scroll handle will stick to the rightmost position even while the content size changes dynamically. This can be useful to simulate text scrollers coming in from right hand side. The scroll handle remains stuck until user manually changes position. Once “unstuck” it will remain focused on whatever content viewport the user left it on. If the scroll handle is dragged all the way to the right it will again become stuck and remain there until manually pulled from the end position.
sourcepub fn stick_to_bottom(self, stick: bool) -> Self
pub fn stick_to_bottom(self, stick: bool) -> Self
The scroll handle will stick to the bottom position even while the content size changes dynamically. This can be useful to simulate terminal UIs or log/info scrollers. The scroll handle remains stuck until user manually changes position. Once “unstuck” it will remain focused on whatever content viewport the user left it on. If the scroll handle is dragged to the bottom it will again become stuck and remain there until manually pulled from the end position.
source§impl ScrollArea
impl ScrollArea
fn begin(self, ui: &mut Ui) -> Prepared
sourcepub fn show<R>(
self,
ui: &mut Ui,
add_contents: impl FnOnce(&mut Ui) -> R,
) -> ScrollAreaOutput<R>
pub fn show<R>( self, ui: &mut Ui, add_contents: impl FnOnce(&mut Ui) -> R, ) -> ScrollAreaOutput<R>
Show the ScrollArea
, and add the contents to the viewport.
If the inner area can be very long, consider using Self::show_rows
instead.
sourcepub fn show_rows<R>(
self,
ui: &mut Ui,
row_height_sans_spacing: f32,
total_rows: usize,
add_contents: impl FnOnce(&mut Ui, Range<usize>) -> R,
) -> ScrollAreaOutput<R>
pub fn show_rows<R>( self, ui: &mut Ui, row_height_sans_spacing: f32, total_rows: usize, add_contents: impl FnOnce(&mut Ui, Range<usize>) -> R, ) -> ScrollAreaOutput<R>
Efficiently show only the visible part of a large number of rows.
let text_style = egui::TextStyle::Body;
let row_height = ui.text_style_height(&text_style);
// let row_height = ui.spacing().interact_size.y; // if you are adding buttons instead of labels.
let total_rows = 10_000;
egui::ScrollArea::vertical().show_rows(ui, row_height, total_rows, |ui, row_range| {
for row in row_range {
let text = format!("Row {}/{}", row + 1, total_rows);
ui.label(text);
}
});
sourcepub fn show_viewport<R>(
self,
ui: &mut Ui,
add_contents: impl FnOnce(&mut Ui, Rect) -> R,
) -> ScrollAreaOutput<R>
pub fn show_viewport<R>( self, ui: &mut Ui, add_contents: impl FnOnce(&mut Ui, Rect) -> R, ) -> ScrollAreaOutput<R>
This can be used to only paint the visible part of the contents.
add_contents
is given the viewport rectangle, which is the relative view of the content.
So if the passed rect has min = zero, then show the top left content (the user has not scrolled).
fn show_viewport_dyn<'c, R>( self, ui: &mut Ui, add_contents: Box<dyn FnOnce(&mut Ui, Rect) -> R + 'c>, ) -> ScrollAreaOutput<R>
Trait Implementations§
source§impl Clone for ScrollArea
impl Clone for ScrollArea
source§fn clone(&self) -> ScrollArea
fn clone(&self) -> ScrollArea
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more