All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
ScrollLayer

Detailed Description

Layer that scrolls its contents, animated.

scroll_layer.png

Key Points

Function Documentation

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.

Parameters
scroll_layerThe ScrollLayer to which to add the child layer.
childThe Layer to add to the content sub-layer of the ScrollLayer.
Note
You may need to update the size of the scrollable contents using scroll_layer_set_content_size().
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.

GPoint scroll_layer_get_content_offset ( ScrollLayer *  scroll_layer)

Gets the point by which the contents are offset.

Parameters
scroll_layerThe ScrollLayer for which to get the content offset
See Also
scroll_layer_set_content_offset
GSize scroll_layer_get_content_size ( const ScrollLayer *  scroll_layer)

Gets the size of the contents layer.

Parameters
scroll_layerThe ScrollLayer for which to get the content size
See Also
scroll_layer_set_content_size
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_layerPointer to the ScrollLayer for which to get the "root" Layer
Returns
The "root" Layer of the scroll layer.
bool scroll_layer_get_shadow_hidden ( const ScrollLayer *  scroll_layer)

Gets the visibility of the scroll layer shadow.

Parameters
scroll_layerThe scroll layer for which to get the visibility
Returns
True if the shadow is hidden, false if it is not hidden.
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
recognizerThe click recognizer for which the handler is called
contextA void pointer to the ScrollLayer that is the context of the click event
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
recognizerThe click recognizer for which the handler is called
contextA void pointer to the ScrollLayer that is the context of the click event
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_layerThe ScrollLayer for which to assign new callbacks.
callbacksThe new callbacks.
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_layerThe ScrollLayer that needs to receive click events.
windowThe window for which to set the click configuration.
See Also
Clicks
window_set_click_config_provider_with_context
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_layerThe ScrollLayer for which to set the content offset
offsetThe final content offset
animatedPass 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
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_layerThe ScrollLayer for which to set the content size.
sizeThe new content size.
See Also
scroll_layer_get_content_size
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_layerThe ScrollLayer for which to assign the new callback context.
contextThe new callback context.
See Also
scroll_layer_set_click_config_onto_window
scroll_layer_set_callbacks
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_layerThe ScrollLayer for which to set the frame
frameThe new frame
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_layerThe scroll layer for which to set the shadow visibility
hiddenSupply true to make the shadow hidden, or false to make it non-hidden.

Data Structure Documentation

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.

Typedef Documentation

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

Function signature for the .content_offset_changed_handler callback.