wxScrollBar(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💅 wxScrollBar

okay bestie, so this is the wxScrollBar manual page — it's an Erlang module definition from the wx 2.6 docs, and yes I'm about to make a scrollbar sound like the most interesting thing you've read all week (because it kind of is??). 🌈

✨ NAME ✨

wxScrollBar — bestie, it's a control that represents a horizontal or vertical scrollbar. that's it. that's the vibe. 💅

🌸 DESCRIPTION 🌸

So, real talk: this one is distinct from the two scrollbars that some windows just... hand you automatically, unprompted, like a situationship. BUT 🫶 the two types of scrollbar share the way events are received, so you're not learning a whole new language, iykyk.

Remark: A scrollbar has the following main attributes: range, thumb size, page size, and position.

let's break that down because it's lowkey the whole personality of this class:

  • range — the total number of units associated with the view the scrollbar represents. a table with 15 columns? range is 15. periodt.
  • thumb size — the number of units that are currently visible. for that same table, maybe the window is sized so you can only see 5 columns, in which case the app would set the thumb size to 5.
  • page size — the number of units the scrollbar should scroll by when you're 'paging' through the data. normally this is the same as the thumb size length, because it's natural to assume that the visible window size defines a page. makes sense, slay.
  • position — the current thumb position.

⚠️ important: when the thumb size becomes the same as or greater than the range, the scrollbar will be automatically hidden on most platforms. it's not broken, it's just not needed anymore, okay?? 😭

Most applications will find it convenient to provide a function called AdjustScrollbars() which can be called initially, from an OnSize event handler, and whenever the application data changes in size. It will adjust the view, object and page size according to the size of the window and the size of the data. obsessed with a well-named helper function honestly 💖

🎀 Styles

This class supports the following styles:

  • wxSB_HORIZONTAL — Specifies a horizontal scrollbar. ➡️
  • wxSB_VERTICAL — Specifies a vertical scrollbar. ⬇️

🦋 The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED

okay this is the part where everybody gets confused so let's go sloooow 🧚

The EVT_SCROLL_THUMBRELEASE event is only emitted when you're actually dragging the thumb using the mouse and releasing it. (And heads up bestie, this EVT_SCROLL_THUMBRELEASE event is also followed by an EVT_SCROLL_CHANGED event. two for one 💅)

The EVT_SCROLL_CHANGED event also occurs when you use the keyboard to change the thumb position, and when clicking next to the thumb. (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen. nope. not invited. 🙈)

In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/moving has finished, independently of the way it had started. it doesn't care how you got there, it just cares that you arrived. main character energy fr fr ✨

Please see the page samples_widgets ("Slider" page) to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. 🍓

See:

  • Overview scrolling
  • Overview events

This class is derived, and can use functions, from:

  • wxControl
  • wxWindow
  • wxEvtHandler

wxWidgets docs: wxScrollBar

🌈 Events

Event types emitted from this class:

  • scroll_top
  • scroll_bottom
  • scroll_lineup
  • scroll_linedown
  • scroll_pageup
  • scroll_pagedown
  • scroll_thumbtrack
  • scroll_thumbrelease
  • scroll_changed
  • scroll_top
  • scroll_bottom
  • scroll_lineup
  • scroll_linedown
  • scroll_pageup
  • scroll_pagedown
  • scroll_thumbtrack
  • scroll_thumbrelease
  • scroll_changed

(yes bestie, the list really does appear twice. that's the original, I'm not touching it, and honestly? it's giving double the slay. 👑)

💜 DATA TYPES 💜

wxScrollBar() :: wx:wx_object().

that's the whole data type section. short. sweet. iconic. ⭐

🔥 FUNCTIONS 🔥

create(This, Parent, Id, [Option]) -> boolean()

when
    This :: wxScrollBar(),
    Parent :: wxWindow:wxWindow(),
    Id :: integer(),
    Option ::
        {pos, {X :: integer(), Y :: integer()}} |
        {size, {W :: integer(), H :: integer()}} |
        {style, integer()} |
        {validator, wx:wx_object()}.

Scrollbar creation function called by the scrollbar constructor. 🛠️

See new/3 for details.

destroy(This :: wxScrollBar()) -> ok.

Destroys the object. 💀 bye bestie, you were real.

getPageSize(This) -> integer() when This :: wxScrollBar().

Returns the page size of the scrollbar.

This is the number of scroll units that will be scrolled when the user pages up or down. Often it is the same as the thumb size.

See: setScrollbar/6

getRange(This) -> integer() when This :: wxScrollBar().

Returns the length of the scrollbar. 📏

See: setScrollbar/6

getThumbPosition(This) -> integer() when This :: wxScrollBar().

Returns the current position of the scrollbar thumb. 📍

See: setThumbPosition/2

getThumbSize(This) -> integer() when This :: wxScrollBar().

Returns the thumb or 'view' size. 👀

See: setScrollbar/6

new() -> wxScrollBar().

Default constructor. no args, no problems, just vibes. ✨

new(Parent, Id, [Option]) -> wxScrollBar()

when
    Parent :: wxWindow:wxWindow(),
    Id :: integer(),
    Option ::
        {pos, {X :: integer(), Y :: integer()}} |
        {size, {W :: integer(), H :: integer()}} |
        {style, integer()} |
        {validator, wx:wx_object()}.

Constructor, creating and showing a scrollbar. 🎀

See: create/4

setScrollbar(This, Position, ThumbSize, Range, PageSize, [Option]) -> ok

when
    This :: wxScrollBar(),
    Position :: integer(),
    ThumbSize :: integer(),
    Range :: integer(),
    PageSize :: integer(),
    Option :: {refresh, boolean()}.

Sets the scrollbar properties. 🔧

Remark: Let's say you wish to display 50 lines of text, using the same font. The window is sized so that you can only see 16 lines at a time. You would use: The page size is 1 less than the thumb size so that the last line of the previous page will be visible on the next page, to help orient the user. Note that with the window at this size, the thumb position can never go above 50 minus 16, or 34.

ngl, that little 50 - 16 = 34 moment? math but make it scrollable. 🧮✨

You can determine how many lines are currently visible by dividing the current view size by the character height in pixels. When defining your own scrollbar behaviour, you will always need to recalculate the scrollbar settings when the window size changes. You could therefore put your scrollbar calculations and setScrollbar/6 call into a function named AdjustScrollbars, which can be called initially and also from a wxSizeEvent event handler function. 🫶

setThumbPosition(This, ViewStart) -> ok

when
    This :: wxScrollBar(),
    ViewStart :: integer().

Sets the position of the scrollbar. 📌

See: getThumbPosition/1

and that's the whole page bestie, no cap, every option and every event present and accounted for 💖

this excellence was brought to you by Ericsson AB, from the wx 2.6 era — so if you're out here scrolling in 2024, just know the ancestors did it first. mwah 💋 🌸💅🦋

📦 where this page comes from