Note: result[:from] will return nil the first time location services are started.

The :previous key in the BW::Location.get() result hash will always return an array of zero or more additional CLLocation objects aside from the locations returned from the :to and :from hash keys. While in most scenarios this array will be empty, per Apple's Documentation if there are deferred updates or multiple locations that arrived before they could be delivered, multiple locations will be returned in an order of oldest to newest.

iOS 8 Location Requirements

iOS 8 introduced stricter location services requirements. Although BubbleWrap will handle most of this for you automatically, you are required to add a few key/value pairs to the Info.plist. Add these two lines to your Rakefile (with your descriptions, obviously):

Note: you need both keys to use get_once, so it's probably best to just include both no matter what. See Apple's documentation on iOS 8 location services requirements for more information.

Motion

Interface for the accelerometer, gyroscope, and magnetometer sensors (the
CoreMotion framework). You can access each sensor individually, or you can get
data from all of them at once using the BW::Motion.device interface, which
delegates to CMMotionManager#deviceMotion.

Each sensor has an every and once method. every expects a time interval,
and you will need to retain the object it returns and call #stop on it when
you are done with the data.

The every and once methods can accept a :queue option. The default value
is a queue that runs on the main loop, so that UI updates can be processed in
the block. This is useful, but not recommended by Apple, since the events can
come in at a high rate. If you want to use a background queue, you can either
specify an NSOperationQueue object, or you can use one of these symbols:

:main - NSOperationQueue.mainQueue, this is the default value.

:background - BubbleWrap will create a new NSOperationQueue.

:current - BubbleWrap will use NSOperationQueue.currentQueue.

If you pass a string instead, a new queue will be created and its name
property will be set to that string.

The CMDeviceMotion interface (BW::Motion.device) accepts a :reference
option, which specifies the CMAttitudeReferenceFrame. The default value is
the same as the one that CMMotionManager uses, which is returned by the
CMMotionManager#attitudeReferenceFrame method. This option should be passed
to the repeat, every or once methods.

NetworkIndicator

Wrapper for showing and hiding the network indicator (the status bar spinner).

BW::NetworkIndicator.show # starts the spinnerBW::NetworkIndicator.hide # stops it# the nice thing is if you call 'show' multiple times, the 'hide' method will# not have any effect until you've called it the same number of times.BW::NetworkIndicator.show
# ...somewhere elseBW::NetworkIndicator.show
# ...down the lineBW::NetworkIndicator.hide
# indicator is still visibleBW::NetworkIndicator.hide
# NOW the indicator is hidden!# If you *really* want to hide the indicator immediately, you can call `reset!`# but this is in no way encouraged.BW::NetworkIndicator.reset!
# and for completeness, a check to see if the indicator is visibleBW::NetworkIndicator.visible?

UI

Gestures

Extra methods on UIView for working with gesture recognizers. A gesture recognizer can be added using a normal Ruby block, like so:

There are similar methods for pinched, rotated, swiped, panned, and pressed (for long presses). All of the methods return the actual recognizer object, so it is possible to set the delegate if more fine-grained control is needed.

In order to prevent retain cycles due to strong references within the passed block, use the use_weak_callbacks flag so the blocks do not retain a strong reference to self:

BubbleWrap.use_weak_callbacks =true

UIViewController

A custom method was added to UIViewController to return the content
frame of a view controller.

Reactor

BW::Reactor is a simplified, mostly complete implementation of
the Event Machine API. In fact
BW::Reactor is aliased to EM in the runtime environment.

Deferables

BubbleWrap provides both a Deferrable mixin and a DefaultDeferrable
class, which simply mixes in deferrable behaviour if you don't want to
implement your own.

A deferrable is an object with four states: unknown, successful, failure
and timeout. When you initially create a deferrable it is in an unknown
state, however you can assign callbacks to be run when the object
changes to either successful or failure state.

Using delegate, errback_delegate and callback_delegate you can link
deferrables together.

By default, callbacks will be made on the thread that the deferrable
succeeds/fails on. For multithreaded environments, it can be useful to use
EM::ThreadAwareDeferrable so that callbacks will be made on the threads they
are declared on.

Scheduling operations

You can use EM.schedule to schedule blocks to be executed
asynchronously. BubbleWrap deviates from the EventMachine
API here in that it also provides EM.schedule_on_main which
makes sure that the task is run asynchronously, but on the
application's main thread - this is necessary if you are
updating the user interface.

Deferrable operations

You can also use EM.defer in much the same way as EM.schedule
with one important difference, you can pass in a second proc
which will be called when the first has completed, and be passed
it's result as an argument. Just like EM.schedule, EM.defer
also has an EM.defer_on_main version.

Events

Although not part of the EventMachine API, BubbleWrap provides
an Eventable mixin for use instrumenting objects with simple
event triggering behaviour. BW::Reactor uses this
behind the scenes in several places, and as it's a very handy
idiom it is available as a public API.

Contributing

Do you have a suggestion for a specific wrapper? Feel free to open an
issue/ticket and tell us about what you are after. If you have a
wrapper/helper you are using and are thinking that others might enjoy,
please send a pull request with tests. If you need help writing the tests,
send the pull request anyways and we'll try to help you out with that.