Scrolling
PBScrollView
Opaque object handle: An element that displays scroll bars to let the user pan through more content than will fit in the window.
This is a subclass of PBElement. You can safely cast from PBScrollView to PBElement. To cast from PBElement to PBScrollView, call PBScrollViewCast; this performs a runtime assertion to check the cast is possible. This function is thread-safe.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBElementRetain; to decrement the reference count, call PBElementRelease. These functions are thread-safe.
PBEnsureVisibleMode
Enumeration/bitset of type uint16_t:
Constants
PBEnsureVisibleMode_TO_START_OF_VIEWPORT
PBEnsureVisibleMode_TO_START_OF_VIEWPORT = 1
Scroll the element to the start of the viewport, but only if it is not already fully inside the viewport.
PBEnsureVisibleMode_TO_CENTER_OF_VIEWPORT
PBEnsureVisibleMode_TO_CENTER_OF_VIEWPORT = 2
Scroll the element to the center of the viewport, but only if it is not already fully inside the viewport.
PBEnsureVisibleMode_TO_END_OF_VIEWPORT
PBEnsureVisibleMode_TO_END_OF_VIEWPORT = 3
Scroll the element to the end of the viewport, but only if it is not already fully inside the viewport.
PBEnsureVisibleMode_MINIMIZE_SCROLL_DISTANCE
PBEnsureVisibleMode_MINIMIZE_SCROLL_DISTANCE = 4
Scroll the minimum distance to ensure the element is fully within the viewport (unless the element is too large to fit). If the element is already fully inside the viewport, this will have no effect.
PBEnsureVisibleMode_TO_START_OF_VIEWPORT_ALWAYS
PBEnsureVisibleMode_TO_START_OF_VIEWPORT_ALWAYS = 5
Scroll the element to the start of the viewport, regardless of whether it is already fully inside the viewport.
PBEnsureVisibleMode_TO_CENTER_OF_VIEWPORT_ALWAYS
PBEnsureVisibleMode_TO_CENTER_OF_VIEWPORT_ALWAYS = 6
Scroll the element to the center of the viewport, regardless of whether it is already fully inside the viewport.
PBEnsureVisibleMode_TO_END_OF_VIEWPORT_ALWAYS
PBEnsureVisibleMode_TO_END_OF_VIEWPORT_ALWAYS = 7
Scroll the element to the end of the viewport, regardless of whether it is already fully inside the viewport.
PBEnsureVisibleMode_H_ONLY
PBEnsureVisibleMode_H_ONLY = 1<<12
Only scroll on the x-axis, PBAxis_H.
PBEnsureVisibleMode_V_ONLY
PBEnsureVisibleMode_V_ONLY = 1<<13
Only scroll on the y-axis, PBAxis_V.
PBEnsureVisibleMode_IS_FIRST_ITEM
PBEnsureVisibleMode_IS_FIRST_ITEM = 1<<14
This is the first logical item in its container. If possible, scroll to the very top. This creates a more pleasing result when the container has insets.
PBEnsureVisibleMode_IS_LAST_ITEM
PBEnsureVisibleMode_IS_LAST_ITEM = 1<<15
This is the last logical item in its container. If possible, scroll to the very bottom. This creates a more pleasing result when the container has insets.
PBMessageEnsureVisible
Structure:
Fields
[in] descendent (referenced PBElement):
[in] mode (PBEnsureVisibleMode):
PBScrollViewFlags
Enumeration/bitset of type uint32_t:
Constants
PBScrollView_MOVE_FREELY_IN_2D
PBScrollView_MOVE_FREELY_IN_2D = 1<<0
Reserved.
PBScrollView_DRAG_OUTSIDE_TO_MOVE
PBScrollView_DRAG_OUTSIDE_TO_MOVE = 1<<1
Reserved.
PBScrollView_PREFER_BOTTOM
PBScrollView_PREFER_BOTTOM = 1<<2
Consider a scroll view where the content fits in the viewport on the vertical axis. Suppose the view or content is resized so that the content no longer fits in the viewport on this axis. By default, the vertical scroll position will stay at 0. But if this flag is set, the vertical scroll position will be set to the maximum value.
PBScrollView_PREFER_RIGHT
PBScrollView_PREFER_RIGHT = 1<<3
The equivalent of PBScrollView_PREFER_BOTTOM for the horizontal axis.
PBScrollView_MEASURE_CONTENT_HEIGHT_FIRST
PBScrollView_MEASURE_CONTENT_HEIGHT_FIRST = 1<<4
Consider a scroll view where both the horizontal axis and vertical axis are scrolled. If this flag is not set, the scroll view first measures the width of its content, and passes the maximum of this value and the viewport's width as the otherDimensionSize when measuring the content's height. If this flag is set, the height is measured first and the maximum of that and the viewport's height is used as the otherDimensionSize when measuring the width. Useful for complex mixing of vertical line-wrapped text with other elements. You probably don't need this flag. See also: PBGrid_LAYOUT_ROWS_FIRST.
Or any of the values from PBElementFlags.
PBScrollMode
Enumeration/bitset of type uint16_t:
Constants
PBScrollMode_NONE
PBScrollMode_NONE = 0
This axis is not scrolled. If there is not enough room to display the content, it will be permanently cut off.
PBScrollMode_HIDDEN
PBScrollMode_HIDDEN = 1
This axis is scrolled, but no scroll bar is displayed. The content element should automatically adjust the scroll position with PBScrollViewScrollTo, PBScrollViewEnsurePointVisible and PBElementEnsureVisible.
PBScrollMode_FIXED
PBScrollMode_FIXED = 2
This axis is scrolled. If the content size on this axis is smaller than the viewport size, an empty scroll bar track will be displayed at the side. If the user has enabled transient scroll bars then this is equivalent to PBScrollMode_AUTO, since the scroll bars will float above the content and disappear automatically. See PBSystemProperty_TRANSIENT_SCROLL_BARS.
PBScrollMode_AUTO
PBScrollMode_AUTO = 3
This axis is scrolled. If the content size on this axis is smaller than the viewport size, no scroll bar track will be displayed. Because the presence of the scroll bars affects the available viewport size and because the available viewport size may affect the content size, this option may be undesirable. For example, consider an image display with a fixed aspect ratio: if the viewport width is increased, the content height is increased correspondingly; this may then cause a vertical scroll bar to show, thus decreasing the viewport width and then decreasing the content height. If this is a concern, use PBScrollMode_FIXED instead.
PBScrollState
Structure: The state of a scroll view for an axis.
Fields
position (double): The current scroll offset. This ranges from 0 to the maximum, inclusive. If the scroll view is in the middle of updating, the position may temporarily go past the maximum value; it will be clamped later.
maximum (double): The maximum position. If 0, the content was determined to fit in the viewport for this axis. This is determined using the content size during the last relayout of the scroll view. For PBScrollMode_NONE, this is always 0.
barVisible (bool): True if a scroll bar is currently being displayed for this axis; otherwise, false.
PBMessageScroll
Structure: Information sent to the scroll view's child element when the scroll position changes.
Fields
[in] positionH (double): The new horizontal scroll offset. This is also obtainable from PBScrollViewGetState.
[in] positionV (double): The new vertical scroll offset. This is also obtainable from PBScrollViewGetState.
PBScrollViewCreate
Function: Create a scroll view element.
Syntax (C/C++)
PBScrollViewPtr _Nullable PBScrollViewCreate(PBElementRef parent,
PBScrollViewFlags flags);
Syntax (Python)
ScrollViewCreate(parent, flags) -> (scrollView)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBScrollViewFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[out] scrollView (nullable owned PBScrollView): The created scroll view, or null if there was insufficient available memory. If non-null, release with PBElementRelease when you no longer need to access the element.
Discussion
You should add exactly one child element to the scroll view.
You may want to setup the scroll view using PBScrollViewSetup. By default both axes will be scrolled, showing scroll bars only when necessary (PBScrollMode_AUTO).
The scroll view determines the size of the scrollable region by measuring its child with PBElementMeasure. You can notify the scroll view that the size of the child element has changed using PBElementContentsChanged, in the same manner as with any other layout.
If the scroll view is measured it returns the size of its content, so as to try to prevent the need for scrolling.
There are two modes for a scroll view: normal mode and direct mode. A description of the difference is given in PBScrollViewUseDirectMode.
Example (C/C++)
// Create a scroll view that fills the space of its parent element.
PBScrollView *scrollView = PBScrollViewAdd(parent,
PBElement_H_FILL | PBElement_V_FILL);
// Scroll on both axes, showing scroll bars automatically.
PBScrollViewSetup(scrollView, PBScrollMode_AUTO, PBScrollMode_AUTO);
// Create a column layout element to layout the contents.
PBElement *column = PBLayoutColumnAdd((PBElement *) scrollView, 0, 5, PB_RECT_1(5));
// TODO Add elements to the column.
See Also
PBScrollViewSetup
Function: Select the scrolling modes of a scroll view on each axis.
Syntax (C/C++)
void PBScrollViewSetup(PBScrollViewRef scrollView, PBScrollMode xMode,
PBScrollMode yMode);
Syntax (Python)
ScrollViewSetup(scrollView, xMode, yMode)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
[in] xMode (PBScrollMode): The horizontal scrolling mode.
[in] yMode (PBScrollMode): The vertical scrolling mode.
See Also
PBScrollViewGetState
Function: Get the state of a scroll view on a specific axis.
Syntax (C/C++)
PBScrollState PBScrollViewGetState(PBScrollViewRef scrollView, PBAxis axis);
Syntax (Python)
ScrollViewGetState(scrollView, axis) -> (state)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
[in] axis (PBAxis): PBAxis_H or PBAxis_V.
[out] state (PBScrollState): The current state.
See Also
PBScrollViewGetMode
Function: Get the scrolling mode for a specific axis from a scroll view.
Syntax (C/C++)
PBScrollMode PBScrollViewGetMode(PBScrollViewRef scrollView, PBAxis axis);
Syntax (Python)
ScrollViewGetMode(scrollView, axis) -> (mode)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
[in] axis (PBAxis):
[out] mode (PBScrollMode): The current mode, as set in PBScrollViewSetup.
See Also
PBScrollViewScrollTo
Function: Scroll a scroll view axis to a specific position value.
Syntax (C/C++)
void PBScrollViewScrollTo(PBScrollViewRef scrollView, PBAxis axis,
double position);
Syntax (Python)
ScrollViewScrollTo(scrollView, axis, position)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
[in] axis (PBAxis): PBAxis_H or PBAxis_V.
[in] position (double): The new scroll offset.
Discussion
The request is ignored if the axis has scroll mode PBScrollMode_NONE.
During layout, the scroll position will be clamped between 0 and the maximum possible value: the size of the content minus the size of the viewport.
See Also
PBScrollViewEnsurePointVisible
Function: Ensure a point is visible within a scroll view's viewport.
Syntax (C/C++)
bool PBScrollViewEnsurePointVisible(PBScrollViewRef scrollView, PBAxis axis,
int64_t point, int32_t safeArea);
Syntax (Python)
ScrollViewEnsurePointVisible(scrollView, axis, point, safeArea) -> (didMove)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
[in] axis (PBAxis): The axis to potentially scroll. PBAxis_H or PBAxis_V.
[in] point (int64_t): The point in coordinates (pixels) relative to the top-left corner of the scrolled contents.
[in] safeArea (int32_t): The size of the border in pixels around the edge of the viewport that determine the viewport's safe area. If the point is outside the safe area, the scroll position will be adjusted so that it is just inside the safe area. Pass -1 to use the default border size.
[out] didMove (bool): False if the point was already inside the safe area; otherwise, true.
Discussion
If you want to ensure a descendent element of the scroll view is visible, use PBElementEnsureVisible instead.
The scroll view will be updated later in the event cycle to reflect the new scroll position.
If passing a point near the very start or end of the content, the point may end up outside the safe area (but still within the viewport). This uses the content size at the time of the call, so the result may be slightly off if the content size changes later in the event.
See Also
PBScrollViewUseDirectMode
Function: Use the direct scrolling mode in a scroll view.
Syntax (C/C++)
void PBScrollViewUseDirectMode(PBScrollViewRef scrollView);
Syntax (Python)
ScrollViewUseDirectMode(scrollView)
Parameters and Return Values
[in] scrollView (referenced PBScrollView): The scroll view.
Discussion
By default, the scroll view creates a intermediary element between the scroll view and the added child content. This intermediary element receives the PBMsg_SCROLL messages and is responsible for moving the content element. In direct mode however, this intermediary element is not created, and the content element is directly responsible for handling PBMsg_SCROLL.
This function must be called before adding the content element to the scroll view.
In normal mode, the content element is sized according to its measured width and height, and its position is offset by the current scroll position. In direct mode, the content element is sized and positioned to the viewport of the scroll view.
In direct mode, the content element should have the PBElement_CLIP_LAYER flag.
In direct mode, the content element will also be sent PBMsg_SCROLL_GET_FIXED_SIZE, which it can handle to reduce the size of the viewport.