Skip to content

About

An enhanced fork of the original TiDraggable module by Pedro Enrique, allows for simple creation of "draggable" views.

Resources

Stars

3 stars

Watchers

1 watching

Forks

 
 

Latest commit

 

History

178 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

TiDraggable - Native Draggable Views

An enhanced fork of the original TiDraggable module by Pedro Enrique, allows for simple creation of "draggable" views.

New in iOS 4.6.0

  • Opt-in scrollHandoff.suppressScrollMomentum prevents an upward sheet flick from carrying residual momentum into the inner table. The first row retains its navigation-bar and safe-area positioning as the sheet expands.
  • scrollHandoff.scrollEnabledByDetent controls scrolling for individual detents, including keeping collapsed content at its adjusted top throughout the transition to the next detent.
  • Opt-in collapsedBounce adds progressively stronger pull resistance below the collapsed boundary and a native spring-back on release or cancellation. It is ignored while the dismiss policy is selected.
  • The existing detents, follower views, axis locking, and interactive/programmatic detent progress APIs remain available. The new options are disabled or unset by default.

Download the ZIP from the iOS v4.6.0 release, install it into your app or Titanium module directory, then add:

<module platform="iphone" version="4.6.0">ti.draggable</module>

This iOS package requires Titanium SDK 13.2.0.GA or newer. The 4.6.0 additions apply to iOS; Android source is unchanged.

Enhancements & Fixes

  • Improved drag performance for iOS and Android.
  • Updated public APIs for more seamless integration.
  • Removed the InfiniteScroll class as it doesn't really have much to do with the overall module.
  • Removed unnecessary APIs to reduce overall module footprint.
  • Removed unused variables and organized imports.
  • Added ability to unset boundaries.
  • Mapped the missing cancel gesture to the end gesture (firing the respective event).
  • Added ensureRight and ensureBottom, this allows for stable dragging of views where the dimensions are not known.
  • Added enabled boolean property for toggeling drag
  • Views can be mapped and translated with a draggable view.
  • iOS: Added native bottom-sheet detents, nested scroll handoff, and detent-aware follower views.
  • Draggable implementation now has its own configurable property called draggable.
  • iOS: Supports all Ti.UI.View subclasses and Ti.UI.View wrapped views (View, Window, Label)
  • Android: Fixed a bug where touch events were not correctly passed to children or bubbled to the parent.
  • Android: Fixed a bug where min and max bounds were being incorrectly reported after being set.
  • Android: Improved drag tracking. It plays nice with child views now.
  • Android: Added a touch threshold to ensure all child views have a chance to have their respective events fired.

Usage

var Draggable = require('ti.draggable'),
    mainWindow = Ti.UI.createWindow({
        backgroundColor : 'white'
    }),
    draggableView = Draggable.createView({
        width : 100,
        height : 100,
        backgroundColor : 'black'
    });

mainWindow.add(draggableView);
mainWindow.open();

If you are building the Android module, make sure you update the .classpath and build.properties files to match your setup.

Module Reference

Draggable.createView(viewOptions);

Create a draggable view. All of Titanium's properties are supported along the additional draggableConfig property containing any options that should be set upon creation. See Options

When the draggable proxy is created a new property is set called draggable which stores all the configuration properties and allows for options to be updated after creation.

iOS Notes You can pass almost all of iOS' supported Ti.UI creation methods to the draggable module such as Draggable.createView( ... ) or Draggable.createWindow( ... ). While Ti.UI.View and Ti.UI.Window are fully supported on iOS other APIs haven't been fully tested.

Android Notes Android only supports the creation of Ti.UI.Views. At this time there are no plans to add support for other APIs.

Options

Options can be set on view creation using draggableConfig or after creation using DraggableView.draggable.setConfig( ... )


The setConfig method can set options two different ways. You can pass an object containing the parameters you with to set or you can pass a key-value pair.

Setting Options With An Object

DraggableView.draggable.setConfig('enabled', false);

Setting Options With An Object

DraggableView.draggable.setConfig({
  enabled : false
});

Boolean - enabled

Flag to enable or disable dragging.

String - axis

Constrains how the view can be dragged.

Supported values:

  • x — drag horizontally only

  • y — drag vertically only

  • xy — drag on either axis, but only one axis at a time per gesture

When axis is set to xy, the drag locks to the first dominant direction of the gesture.

This means the view can move horizontally or vertically, but not diagonally during the same drag.

If axis is omitted, the view can move freely on both axes.

Native Bottom-Sheet Handoff (iOS)

Version 4.6.0 can coordinate a vertical draggable view with a descendant Ti.UI.TableView, Ti.UI.ListView, or Ti.UI.ScrollView. The inner scroll view scrolls while the sheet is expanded. A downward gesture first returns the inner content to its adjusted top offset, then transfers the same gesture to the draggable sheet without waiting for JavaScript.

var Draggable = require('ti.draggable');
var window = Ti.UI.createWindow({ backgroundColor: '#F3F2F8' });
var rows = [];
for (var index = 1; index <= 40; index++) {
  rows.push({ title: 'Nearby place ' + index, height: 58 });
}

var tableView = Ti.UI.createTableView({
  top: 72,
  bottom: 0,
  data: rows
});

var mapButtons = Ti.UI.createView({
  right: 16,
  width: 48,
  height: 104
});

var expandedTop = 80;
var screenHeight = Ti.Platform.displayCaps.platformHeight;

var sheet = Draggable.createView({
  top: 700,
  left: 0,
  right: 0,
  height: screenHeight - expandedTop,
  draggableConfig: {
    axis: 'y',
    detents: {
      expanded: expandedTop,
      middle: 420,
      collapsed: 700
    },
    initialDetent: 'collapsed',
    collapsedBounce: { enabled: true },
    progressRanges: [
      { id: 'collapsedToMiddle', from: 'collapsed', to: 'middle' },
      { id: 'middleToExpanded', from: 'middle', to: 'expanded' }
    ],
    scrollHandoff: {
      view: tableView,
      atTopBehavior: 'drag',
      suppressScrollMomentum: true,
      scrollEnabledByDetent: { collapsed: false, middle: true, expanded: true }
    },
    followers: [{
      view: mapButtons,
      attachUntil: 'middle',
      offset: -12,
      fadeBetween: ['middle', 'expanded'],
      passThroughTouches: true,
      disableTouchesWhenHidden: true
    }]
  }
});

sheet.add(tableView);
window.add(mapButtons); // Followers should be siblings of the sheet.
window.add(sheet);
window.open();

All scrolling, dragging, snapping, follower positioning, and fading occurs in UIKit. JavaScript can optionally observe interactive progress without driving the native motion.

Detents

detents accepts a dictionary of names and absolute top positions. Names are arbitrary and positions are sorted from smallest (expanded) to largest (collapsed). When detents are configured they also become the vertical drag bounds.

  • initialDetent (String) — Positions the sheet at a named detent after its native view is ready.
  • detentVelocityThreshold (Number, default 500) — Vertical velocity in points per second that advances to the next detent in the release direction.
  • detentDuration (Number, default 0.42) — Native snap duration in seconds.
  • detentDamping (Number, default 0.86) — Native snap spring damping ratio from 0.01 through 1.0.

Move to a detent programmatically:

sheet.draggable.setDetent('middle');
sheet.draggable.setDetent('expanded', { animated: false });
sheet.draggable.setDetent('expanded', { animated: true, updateProgress: true });

Collapsed Pull Resistance

collapsedBounce optionally lets a vertical sheet stretch a short distance below its lowest (largest-top) detent. Resistance increases with finger travel, then a native spring returns the sheet to that same detent on release or cancellation. The return emits releaseAction: 'bounce' through the existing release/detent events. Followers move with the sheet and detent progress remains clamped to its configured ranges.

sheet.draggable.setConfig('collapsedBounce', {
  enabled: true,
  maxDistance: 48,
  resistance: 0.35,
  duration: 0.32,
  damping: 0.8
});
  • enabled (Boolean, default false) — Enables resistance and spring-back below the collapsed boundary. Requires configured detents.
  • maxDistance (Number, default 48) — Maximum elastic travel in points; the sheet approaches this limit as the user pulls farther.
  • resistance (Number, default 0.35, range 0.01–1) — Initial fraction of finger movement applied to the sheet. Smaller values feel firmer; movement progressively decreases beyond that initial fraction.
  • duration (Number, default 0.32) — Return spring duration in seconds.
  • damping (Number, default 0.8, range 0.01–1) — Return spring damping ratio.

The option works with scrollEnabledByDetent and suppressScrollMomentum. It is ignored while scrollHandoff.atTopBehavior is 'dismiss'. Other drag boundaries retain their existing constraints. Disable it at runtime with sheet.draggable.setConfig('collapsedBounce.enabled', false).

Detent Progress

progressRanges accepts multiple named ranges. Each item requires a unique id plus from and to values that reference detent names or numeric sheet-top positions.

sheet.addEventListener('detentprogress', function (event) {
  if (event.id === 'middleToExpanded') {
    detailsView.opacity = event.progress;
  }
});

For each range, progress is clamped from 0 at from to 1 at to. It returns from 1 to 0 when the sheet moves in the opposite direction. The event also includes id, from, to, fromTop, toTop, top, and interactive.

Progress starts with the user's drag and continues from the sheet's visible presentation position during the native release animation. The destination is finalized at exactly 0 or 1. interactive is true while the finger is moving the sheet and false while the native animation is settling it.

Programmatic progress is opt-in through setDetent() options:

  • updateProgress (Boolean, default false) — Emits detentprogress while moving to the requested detent.
  • With animated: true, progress follows the visible native animation and finishes at the exact destination value.
  • With animated: false, one exact destination update is emitted.

Initial detent placement does not emit progress. Calling setDetent() without updateProgress: true retains the existing behavior and emits no programmatic progress.

Scroll Handoff

scrollHandoff.view is the descendant TableView, ListView, or ScrollView to coordinate. atTopBehavior may be changed at runtime:

sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'scroll');
sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'drag');
sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'dismiss');
sheet.draggable.setConfig('scrollHandoff.suppressScrollMomentum', true);
  • drag (default) — A downward pull transfers from the inner content to the sheet when the content reaches its adjusted top offset.
  • scroll — The inner view retains downward pulls while the sheet is expanded, including its normal edge behavior.
  • dismiss — Uses the same native handoff as drag, then targets dismissDetent and emits dismiss when the release passes dismissThreshold or detentVelocityThreshold.
  • top (Number) — Optional expanded sheet position used for handoff when no detents are configured. Otherwise the smallest detent or minTop is used.
  • topTolerance (Number, default 1) — Content and sheet top-edge tolerance in points.
  • suppressScrollMomentum (Boolean, default false) — When an upward gesture that began inside the scrolling view is owned by the sheet and targets a higher detent, cancels the scrolling view's residual flick momentum and keeps its content at the adjusted top offset. Normal scrolling and deceleration remain unchanged when the scrolling view owns the gesture.
  • scrollEnabledByDetent (Object, optional) — Maps detent names to scrolling booleans. A false entry disables native scrolling and pins the content to its current adjusted top, including during a drag and release from that detent. Scrolling stays disabled until the destination settles; moving into a disabled detent locks it as settling begins. A true entry enables scrolling subject to the normal sheet handoff rules. Omitted names use the scrolling state captured before this policy took control.
  • dismissThreshold (Number, default 120) — Downward distance required for the dismiss policy.
  • dismissDetent (String) — Named dismissal target. Defaults to the largest configured detent.

With suppression enabled, the adjusted top is recalculated throughout the sheet's release animation and after final layout. This preserves UIKit's navigation-bar and safe-area positioning of the first row while the sheet continues expanding beneath the bars.

For example, scrollEnabledByDetent: { collapsed: false, middle: true, expanded: true } keeps the table at its adjusted top while collapsed and throughout the transition out of collapsed. The destination's setting takes effect before detentchange fires. Update entries at runtime with sheet.draggable.setConfig('scrollHandoff.scrollEnabledByDetent.collapsed', false). Remove the policy with sheet.draggable.setConfig('scrollHandoff.scrollEnabledByDetent', null) to restore the original native scrolling state; removing the handoff or gesture also restores it.

The module does not remove the sheet automatically. Handle the dismiss event to close, hide, or recycle it after the native motion completes.

Size the sheet so its bottom edge meets the window bottom at the expanded detent (height: screenHeight - expandedTop). Extra offscreen height also enlarges the native scroll view's viewport and can leave its final rows below the visible window.

Follower Views

followers keeps sibling controls visually attached to the sheet without JavaScript move events. This is useful for map buttons or other controls that should travel with a collapsed sheet, clamp at a middle detent, and fade as the sheet expands.

  • view (Ti.UI.View, required) — A sibling of the draggable sheet.
  • attachUntil (String or Number) — Detent name or sheet top where the follower stops moving upward.
  • offset (Number, default -12) — Vertical offset from the sheet top to the follower's bottom edge. A negative value creates a gap above the sheet.
  • gap (Number) — Positive shorthand for a gap above the sheet; overrides offset.
  • fadeBetween (Array) — Two detent names or numeric tops: fully visible first, fully hidden second.
  • visibleAlpha / hiddenAlpha (Number, defaults 1 / 0) — Alpha endpoints.
  • bringToFront (Boolean, default true) — Keeps the follower above the sheet so its detent fade remains visible. Set to false when the application manages sibling z-order itself.
  • passThroughTouches (Boolean, default false) — Passes touches on the follower's root view to underlying content while preserving normal touch handling for every child and nested descendant.
  • disableTouchesWhenHidden (Boolean, default true) — Disables native hit testing at the hidden endpoint and restores the view's original interaction state when visible.

The sheet emits these lifecycle events:

  • handoff — Gesture ownership changes; owner is scroll or draggable.
  • detentprogress — Clamped 0 through 1 progress for each configured range whose value changed, including native settling after release.
  • detentwillchange — A native detent animation is about to begin.
  • detentchange — The native detent animation completed; includes detent and top.
  • dismiss — A dismiss policy release completed at its dismissal detent.

Native Horizontal Release (iOS)

Set nativeReleaseAnimation to true to let the native pan recognizer decide and begin the horizontal release animation immediately. This avoids waiting for an end event to cross the JavaScript bridge before starting the swipe or snapback animation.

var card = Draggable.createView({
  draggableConfig: {
    axis: 'xy',
    nativeReleaseAnimation: true,
    swipeThreshold: 80,
    swipeVelocityThreshold: 650,
    swipeOutDistance: Ti.Platform.displayCaps.platformWidth + 100,
    swipeOutDuration: 0.25,
    snapBack: true,
    snapBackDuration: 0.42,
    snapBackDamping: 0.84
  }
});

The native release path applies only to horizontal releases. With axis: 'xy', vertical releases continue through the existing end event so the application can handle its own vertical behavior.

  • nativeReleaseAnimation (Boolean, default false) — Enables the native horizontal release path.
  • swipeThreshold (Number, default 80) — Horizontal distance in points required to dismiss. Set to 0 to disable the distance threshold.
  • swipeVelocityThreshold (Number, default 650) — Horizontal release velocity in points per second required to dismiss. Set to 0 to disable the velocity threshold.
  • swipeOutDistance (Number) — Horizontal distance from the gesture's starting center to the offscreen target. The default is the parent width plus the draggable view width.
  • swipeOutDuration (Number, default 0.25) — Swipe completion duration in seconds.
  • snapBack (Boolean, default true) — Returns a horizontal release that misses both thresholds to its starting position.
  • snapBackDuration (Number, default 0.42) — Snapback duration in seconds.
  • snapBackDamping (Number, default 0.84) — Snapback spring damping ratio from 0.01 through 1.0.

The existing end event still fires. Its payload includes nativeReleaseHandled and, when handled, releaseAction (swipe or snapback). The module also emits:

  • release — Fires immediately after the native release animation starts.
  • swipe — Fires when a native offscreen swipe finishes and includes direction (left or right).
  • snapback — Fires when the native return animation finishes.

Number - minLeft

The left-most boundary of the view being dragged. Can be set to null to disable property.

Number - maxLeft

The right-most boundary of the view being dragged. Can be set to null to disable property.

Number - minTop

The top-most boundary of the view being dragged. Can be set to null to disable property.

Number - maxTop

The bottom-most boundary of the view being dragged. Can be set to null to disable property.

Boolean - ensureRight

Ensure that that the right edge of the view being dragged keeps its integrity. Can be set to null to disable property.

Boolean - ensureBottom

Ensure that that the bottom edge of the view being dragged keeps its integrity. Can be set to null to disable property.

Array - maps

An array of views that should be translated along with the view being dragged. See View Mapping.

View Mapping

In the case where you want multiple views to be translated at the same time you can pass the maps property to the draggable config. This functionality is useful for creating parallax or 1:1 movements.

The maps property accepts an array of objects containing any of the following. The view property is required.

Map Options

Ti.UI.View - view

The view to translate.

Number - parallaxAmount

A positive or negative number. Numbers less than |1| such as 0.1, 0.2, or 0.3 will cause the translation to move faster then the translation. A parallaxAmount of 1 will translate mapped views 1:1. A parallaxAmount > 1 will result in a slower translation.

Object - constrain

An object containing the boundaries of the mapped view. Can have the following:

  • x
    • start The start position for the mapped view.
    • end The end position for the mapped view.
    • callback A function that will receive the completed percentage of the mapped translation. . Android does not support this option.
    • fromCenter Translate the view from its center. Android does not support this option.
  • y
    • start The start position for the mapped view.
    • end The end position for the mapped view.
    • callback A function that will receive the completed percentage of the mapped translation. . Android does not support this option.
    • fromCenter Translate the view from its center. Android does not support this option.

Credits & Notes

The work is largely based on Pedro Enrique's TiDraggable module license under the MIT (V2) license.

About

An enhanced fork of the original TiDraggable module by Pedro Enrique, allows for simple creation of "draggable" views.

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages