Inherits from UIView
Declared in SEssentialsPullToAction.h
Availability
Related samples

Overview

The SEssentialsPullToAction control attaches to a scrollview, or any class which is a sub-class of UIScrollView. When the user pulls down the scroll view, the Pull to Action control is displayed. If the user pulls down the scroll view past a certain threshold, an action is triggered by the Pull to Action control.

You can configure the look and feel of the control in a few ways. The control is provided with default behavior, where the control is displayed at the top of the scroll view. By default, the control status view will slide out aligned to the bottom of the control (SEssentialsPullToActionStatusViewAlignmentBottom), unless a different statusViewAlignment is specified. If you wish to tweak this default view, you can do this using the style property on the control. If you wish to display your own custom view when the Pull to Action control is displayed, you can set the statusView property on the control. If you do this, then modifying the style property will no longer have any effect.

If the default visualization behavior of the control doesn’t meet your needs, you can also set the visualizer property on the control. This allows you to configure exactly what is displayed in the control when it changes state, from being idle, to being pulled, to an action being triggered, and so on. This is advanced behavior, and will require more work on your part.

Tasks

Setup

Pull to Action State

  •   state

    The current state of the Pull to Action. Defaults to SEssentialsPullToActionStateIdle.

    property
  •   pulledAmount

    The current distance that the Pull to Action has been pulled down by, in points.

    property
  •   pullThreshold

    The distance at which an action is triggered, once the pulledAmount has exceeded this value.

    property
  •   executingHeight

    The height of the Pull to Action control during its executing state.

    property

Delegation

  •   delegate

    The delegate for the Pull to Action control.

    property
  • – actionCompleted

    The delegate should call this once it has completed its action. This tells the Pull to Action control to retract back to its idle state.

Basic Visual Properties

  • – applyTheme:

    Updates the style of the component using the specified theme.

  •   style

    By default, the control displays a default status view. This property allows you to configure how that default view looks.

    property
  •   statusView

    The status view which is displayed when you interact with the Pull to Action control.

    property

Advanced Visual Properties

  •   visualizer

    Handles the visualization of the Pull to Action control.

    property
  • – executeAction

    This is an optional method you can use to tell the control to execute its action if a custom visualizer was provided.

  • – resetToIdle

    This is an optional method you can use to tell the control that the animation back to the idle state has completed, if a custom visualizer was provided.

Properties

delegate

The delegate for the Pull to Action control.

@property (nonatomic, assign) id<SEssentialsPullToActionDelegate> delegate

Discussion

Will be sent notifications about changes in state, and the triggering of actions.

Declared In

SEssentialsPullToAction.h

executingHeight

The height of the Pull to Action control during its executing state.

@property (nonatomic, assign) CGFloat executingHeight

Discussion

Defaults to the height of the statusView. When the pull gesture ends after having passed the pullThreshold, the Pull to Action control will return to this height, until the actionCompleted method is called.

Declared In

SEssentialsPullToAction.h

pullThreshold

The distance at which an action is triggered, once the pulledAmount has exceeded this value.

@property (nonatomic, assign) CGFloat pullThreshold

Discussion

Defaults to 100 points. While the state of the control will change to SEssentialsPullToActionStateTriggered when this point is passed, the pullToActionTriggeredAction: method will only be called once the drag motion is released. If you wish to trigger as soon as the threshold is reached, you should instead use the pullToAction:didChangeStateTo: method, and fire on the state changing to SEssentialsPullToActionStateTriggered.

Declared In

SEssentialsPullToAction.h

pulledAmount

The current distance that the Pull to Action has been pulled down by, in points.

@property (nonatomic, readonly) CGFloat pulledAmount

Declared In

SEssentialsPullToAction.h

scrollView

The UIScrollView that the Pull to Action is attached to.

@property (nonatomic, assign) UIScrollView *scrollView

Discussion

We only hold a weak reference, as we are retained by the scrollView as one of its subviews.

Declared In

SEssentialsPullToAction.h

state

The current state of the Pull to Action. Defaults to SEssentialsPullToActionStateIdle.

@property (nonatomic, readonly) SEssentialsPullToActionState state

Discussion

Possible states are:

  • SEssentialsPullToActionStateIdle: The Pull to Action is not being animated, or interacted with.
  • SEssentialsPullToActionStatePulling: The Pull to Action is being pulled down, but has not yet triggered an action.
  • SEssentialsPullToActionStateTriggered: The Pull to Action has been pulled down past the pullThreshold, and an action has been triggered.
  • SEssentialsPullToActionStateExecuting: The pull gesture on the control has finished, and the action is now executing.
  • SEssentialsPullToActionStateRetracting: The action has now completed, and the control is now returning to the idle state.

Declared In

SEssentialsPullToAction.h

statusView

The status view which is displayed when you interact with the Pull to Action control.

@property (nonatomic, retain) UIView<SEssentialsPullToActionStatusView> *statusView

Discussion

This defaults to a view with an arrow and text showing the status of the control. The default view can be configured with the style property. You can set this view if you want to display your own custom view in the control.

Declared In

SEssentialsPullToAction.h

style

By default, the control displays a default status view. This property allows you to configure how that default view looks.

@property (nonatomic, retain) SEssentialsPullToActionStyle *style

Discussion

Warning: Setting the style will cause the component to apply the style when the component is next rendered.

Declared In

SEssentialsPullToAction.h

visualizer

Handles the visualization of the Pull to Action control.

@property (nonatomic, retain) id<SEssentialsPullToActionVisualizer> visualizer

Discussion

This defaults to a visualizer which anchors the status view to the bottom of the Pull to Action control.

You can provide your own visualizer to handle the look and feel of the Pull to Action control. The visualizer is notified of any changes in state, along with changes to the pulledAmount property on the control.

Declared In

SEssentialsPullToAction.h

Instance Methods

actionCompleted

The delegate should call this once it has completed its action. This tells the Pull to Action control to retract back to its idle state.

- (void)actionCompleted

Declared In

SEssentialsPullToAction.h

applyTheme:

Updates the style of the component using the specified theme.

- (void)applyTheme:(SEssentialsTheme *)theme

Declared In

SEssentialsPullToAction.h

executeAction

This is an optional method you can use to tell the control to execute its action if a custom visualizer was provided.

- (void)executeAction

Discussion

By default, this is called internally when the control moves into its executing state. If the control state is not SEssentialsPullToActionStateExecuting, calling this method will have no effect.

If the visualizer is set to a custom SEssentialsPullToActionVisualizer, then it will need to call executeAction to make the Pull to Action control begin the action and change state. Ideally, this would be in the visualizer’s implementation of pullToActionTriggeredAction:.

Declared In

SEssentialsPullToAction.h

initWithFrame:statusViewAlignment:

Create a Pull to Action control with the given frame. Specify how the Pull to Action control is visualized.

- (instancetype)initWithFrame:(CGRect)frame statusViewAlignment:(SEssentialsPullToActionStatusViewAlignment)statusViewAlignment

Discussion

The possible values of statusViewAlignment are:

  • SEssentialsPullToActionStatusViewAlignmentStretch: The status view of the Pull to Action control stretches to fill the available space outside of the scroll view, keeping the contents of the status view centered.
  • SEssentialsPullToActionStatusViewAlignmentBottom: The status view of the Pull to Action control remains a constant size. It is anchored to the bottom edge of the control.

Declared In

SEssentialsPullToAction.h

initWithScrollView:

Create a Pull to Action control, and attach it to the given UIScrollView.

- (instancetype)initWithScrollView:(UIScrollView *)scrollView

Declared In

SEssentialsPullToAction.h

initWithScrollView:statusViewAlignment:

Create a Pull to Action control, and attach it to the given UIScrollView. Specify how the Pull to Action control is visualized.

- (instancetype)initWithScrollView:(UIScrollView *)scrollView statusViewAlignment:(SEssentialsPullToActionStatusViewAlignment)statusViewAlignment

Discussion

The possible values of statusViewAlignment are:

  • SEssentialsPullToActionStatusViewAlignmentStretch: The status view of the Pull to Action control stretches to fill the available space outside of the scroll view, keeping the contents of the status view centered.
  • SEssentialsPullToActionStatusViewAlignmentBottom: The status view of the Pull to Action control remains a constant size. It is anchored to the bottom edge of the control.

Declared In

SEssentialsPullToAction.h

resetToIdle

This is an optional method you can use to tell the control that the animation back to the idle state has completed, if a custom visualizer was provided.

- (void)resetToIdle

Discussion

By default, this will call down to the statusView to inform it that it is safe to return to its idle state.

If the visualizer is set to a custom SEssentialsPullToActionVisualizer, then it will need to call resetToIdle in pullToActionActionCompleted:.

Declared In

SEssentialsPullToAction.h