pebble
Privacy
Cookies
Publish

Pebble C API

ScrollLayer

Layer that scrolls its contents, animated.

Key Points

  • Facilitates vertical scrolling of a layer sub-hierarchy zero or more arbitrary layers. The example image shows a scroll layer containing one large TextLayer.

  • Shadows to indicate that there is more content are automatically drawn on top of the content. When the end of the scroll layer is reached, the shadow will automatically be retracted.

  • Scrolling from one offset to another is animated implicitly by default.

  • The scroll layer contains a "content" sub-layer, which is the layer that is actually moved up an down. Any layer that is a child of this "content" sub-layer, will be moved as well. Effectively, an entire layout of layers can be scrolled this way. Use the convenience function scroll_layer_add_child() to add child layers to the "content" sub-layer.

  • The scroll layer needs to be informed of the total size of the contents, in order to calculate from and to what point it should be able to scroll. Use scroll_layer_set_content_size() to set the size of the contents.

  • The button behavior is set up, using the convenience function scroll_layer_set_click_config_onto_window(). This will associate the UP and DOWN buttons with scrolling up and down.

  • The SELECT button can be configured by installing a click configuration provider using scroll_layer_set_callbacks().

  • To scroll programatically to a certain offset, use scroll_layer_set_content_offset().

  • It is possible to get called back for each scrolling increment, by installing the .content_offset_changed_handler callback using scroll_layer_set_callbacks().

  • Only vertical scrolling is supported at the moment.

Function

ScrollLayer * scroll_layer_create(GRect frame)

Creates a new ScrollLayer on the heap and initalizes it with the default values:

  • Clips: true

  • Hidden: false

  • Content size: frame.size

  • Content offset: GPointZero

  • Callbacks: None (NULL for each one)

  • Callback context: NULL

Returns

A pointer to the ScrollLayer. NULL if the ScrollLayer could not be created

void scroll_layer_destroy(ScrollLayer * scroll_layer)

Destroys a ScrollLayer previously created by scroll_layer_create.

Layer * scroll_layer_get_layer(const ScrollLayer * scroll_layer)

Gets the "root" Layer of the scroll layer, which is the parent for the sub- layers used for its implementation.

Parameters

scroll_layer

Pointer to the ScrollLayer for which to get the "root" Layer

Returns

The "root" Layer of the scroll layer.

void scroll_layer_add_child(ScrollLayer * scroll_layer, Layer * child)

Adds the child layer to the content sub-layer of the ScrollLayer. This will make the child layer part of the scrollable contents. The content sub-layer of the ScrollLayer will become the parent of the child layer.

Note

You may need to update the size of the scrollable contents using scroll_layer_set_content_size().

Parameters

scroll_layer

The ScrollLayer to which to add the child layer.

child

The Layer to add to the content sub-layer of the ScrollLayer.

void scroll_layer_set_click_config_onto_window(ScrollLayer * scroll_layer, struct Window * window)

Convenience function to set the ClickConfigProvider callback on the given window to scroll layer's internal click config provider. This internal click configuration provider, will set up the default UP & DOWN scrolling behavior. This function calls window_set_click_config_provider_with_context to accomplish this.

If you application has set a .click_config_provider callback using scroll_layer_set_callbacks(), this will be called by the internal click config provider, after configuring the UP & DOWN buttons. This allows your application to configure the SELECT button behavior and optionally override the UP & DOWN button behavior. The callback context for the SELECT click recognizer is automatically set to the scroll layer's context (see scroll_layer_set_context() ). This context is passed into ClickHandler callbacks. For the UP and DOWN buttons, the scroll layer itself is passed in by default as the callback context in order to deal with those buttons presses to scroll up and down automatically.

Parameters

scroll_layer

The ScrollLayer that needs to receive click events.

window

The window for which to set the click configuration.

See Also

Clicks
void scroll_layer_set_callbacks(ScrollLayer * scroll_layer, ScrollLayerCallbacks callbacks)

Sets the callbacks that the scroll layer exposes. The context as set by scroll_layer_set_context() is passed into each of the callbacks. See ScrollLayerCallbacks for the different callbacks.

Note

If the context is NULL, a pointer to scroll_layer is used as context parameter instead when calling callbacks.

Parameters

scroll_layer

The ScrollLayer for which to assign new callbacks.

callbacks

The new callbacks.

void scroll_layer_set_context(ScrollLayer * scroll_layer, void * context)

Sets a new callback context. This context is passed into the scroll layer's callbacks and also the ClickHandler for the SELECT button. If NULL or not set, the context defaults to a pointer to the ScrollLayer itself.

Parameters

scroll_layer

The ScrollLayer for which to assign the new callback context.

context

The new callback context.

See Also

scroll_layer_set_click_config_onto_window
void scroll_layer_set_content_offset(ScrollLayer * scroll_layer, GPoint offset, bool animated)

Scrolls to the given offset, optionally animated.

Note

When scrolling down, the offset's .y decrements. When scrolling up, the offset's .y increments. If scrolled completely to the top, the offset is GPointZero.

The .x field must be 0. Horizontal scrolling is not supported.

Parameters

scroll_layer

The ScrollLayer for which to set the content offset

offset

The final content offset

animated

Pass in true to animate to the new content offset, or false to set the new content offset without animating.

See Also

scroll_layer_get_content_offset
GPoint scroll_layer_get_content_offset(ScrollLayer * scroll_layer)

Gets the point by which the contents are offset.

Parameters

scroll_layer

The ScrollLayer for which to get the content offset

See Also

scroll_layer_set_content_offset
void scroll_layer_set_content_size(ScrollLayer * scroll_layer, GSize size)

Sets the size of the contents layer. This determines the area that is scrollable. At the moment, this needs to be set "manually" and is not derived from the geometry of the contents layers.

Parameters

scroll_layer

The ScrollLayer for which to set the content size.

size

The new content size.

See Also

scroll_layer_get_content_size
GSize scroll_layer_get_content_size(const ScrollLayer * scroll_layer)

Gets the size of the contents layer.

Parameters

scroll_layer

The ScrollLayer for which to get the content size

See Also

scroll_layer_set_content_size
void scroll_layer_set_frame(ScrollLayer * scroll_layer, GRect frame)

Set the frame of the scroll layer and adjusts the internal layers' geometry accordingly. The scroll layer is marked dirty automatically.

Parameters

scroll_layer

The ScrollLayer for which to set the frame

frame

The new frame

void scroll_layer_scroll_up_click_handler(ClickRecognizerRef recognizer, void * context)

The click handlers for the UP button that the scroll layer will install as part of scroll_layer_set_click_config_onto_window().

Note

This handler is exposed, in case one wants to implement an alternative handler for the UP button, as a way to invoke the default behavior.

Parameters

recognizer

The click recognizer for which the handler is called

context

A void pointer to the ScrollLayer that is the context of the click event

void scroll_layer_scroll_down_click_handler(ClickRecognizerRef recognizer, void * context)

The click handlers for the DOWN button that the scroll layer will install as part of scroll_layer_set_click_config_onto_window().

Note

This handler is exposed, in case one wants to implement an alternative handler for the DOWN button, as a way to invoke the default behavior.

Parameters

recognizer

The click recognizer for which the handler is called

context

A void pointer to the ScrollLayer that is the context of the click event

void scroll_layer_set_shadow_hidden(ScrollLayer * scroll_layer, bool hidden)

Sets the visibility of the scroll layer shadow. If the visibility has changed, layer_mark_dirty() will be called automatically on the scroll layer.

Parameters

scroll_layer

The scroll layer for which to set the shadow visibility

hidden

Supply true to make the shadow hidden, or false to make it non-hidden.

bool scroll_layer_get_shadow_hidden(const ScrollLayer * scroll_layer)

Gets the visibility of the scroll layer shadow.

Parameters

scroll_layer

The scroll layer for which to get the visibility

Returns

True if the shadow is hidden, false if it is not hidden.

void scroll_layer_set_paging(ScrollLayer * scroll_layer, bool paging_enabled)

Enables or disables paging of the ScrollLayer (default: disabled). When enabled, every button press will change the scroll offset by the frame's height.

Parameters

scroll_layer

The scroll layer for which to enable or disable paging

paging_enabled

True, if paging should be enabled. False to enable.

bool scroll_layer_get_paging(ScrollLayer * scroll_layer)

Check whether or not the ScrollLayer uses paging when pressing buttons.

Parameters

scroll_layer

The scroll layer for which to get the paging behavior.

Returns

True, if paging is enabled; false otherwise.

ContentIndicator * scroll_layer_get_content_indicator(ScrollLayer * scroll_layer)

Gets the ContentIndicator for a ScrollLayer.

Parameters

scroll_layer

The ScrollLayer for which to get the ContentIndicator

Returns

A pointer to the ContentIndicator, or NULL upon failure.

ContentIndicator * content_indicator_create(void)

Creates a ContentIndicator on the heap.

Returns

A pointer to the ContentIndicator. NULL if the ContentIndicator could not be created.

void content_indicator_destroy(ContentIndicator * content_indicator)

Destroys a ContentIndicator previously created using content_indicator_create().

Parameters

content_indicator

The ContentIndicator to destroy.

bool content_indicator_configure_direction(ContentIndicator * content_indicator, ContentIndicatorDirection direction, const ContentIndicatorConfig * config)

Configures a ContentIndicator for the given direction.

Parameters

content_indicator

The ContentIndicator to configure.

direction

The direction for which to configure the ContentIndicator.

config

The configuration to use to configure the ContentIndicator. If NULL, the data for the specified direction will be reset.

Returns

True if the ContentIndicator was successfully configured for the given direction, false otherwise.

bool content_indicator_get_content_available(ContentIndicator * content_indicator, ContentIndicatorDirection direction)

Retrieves the availability status of content in the given direction.

Parameters

content_indicator

The ContentIndicator for which to get the content availability.

direction

The direction for which to get the content availability.

Returns

True if content is available in the given direction, false otherwise.

void content_indicator_set_content_available(ContentIndicator * content_indicator, ContentIndicatorDirection direction, bool available)

Sets the availability status of content in the given direction.

Note

If times_out is enabled, calling this function resets any previously scheduled timeout timer for the ContentIndicator.

Parameters

content_indicator

The ContentIndicator for which to set the content availability.

direction

The direction for which to set the content availability.

available

Whether or not content is available.

Data Structure

struct ContentIndicatorConfig

Struct used to configure directions for ContentIndicator.

Data Fields

Layer * layer

The layer where the arrow indicator will be rendered when content is available.

bool times_out

Whether the display of the arrow indicator should timeout.

GAlign alignment

The alignment of the arrow within the provided layer.

struct ContentIndicatorConfig::@14 colors

See Also

content_indicator_configure_direction
struct ScrollLayerCallbacks

All the callbacks that the ScrollLayer exposes for use by applications.

Note

The context parameter can be set using scroll_layer_set_context() and gets passed in as context with all of these callbacks.

Data Fields

ClickConfigProvider click_config_provider

Provider function to set up the SELECT button handlers. This will be called after the scroll layer has configured the click configurations for the up/down buttons, so it can also be used to modify the default up/down scrolling behavior.

ScrollLayerCallback content_offset_changed_handler

Called every time the the content offset changes. During a scrolling animation, it will be called for each intermediary offset as well.

Enum

enum ContentIndicatorDirection

Value to describe directions for ContentIndicator.

content_indicator_configure_direction content_indicator_set_content_available

Enumerators

ContentIndicatorDirectionUp

The up direction.

ContentIndicatorDirectionDown

The down direction.

NumContentIndicatorDirections

The number of supported directions.

Typedef

typedef struct ScrollLayer ScrollLayer
typedef void(* ScrollLayerCallback)(struct ScrollLayer *scroll_layer, void *context)

Function signature for the .content_offset_changed_handler callback.

typedef struct ContentIndicator ContentIndicator