Commit 71818d2b authored by Aral Balkan's avatar Aral Balkan

Updated readme with the latest installation instructions (and formatted the code samples better).

parent 3d5a1b86
......@@ -4,41 +4,17 @@ Delay is an easy-to-use micro-framework for delaying code execution in a cancell
## Installation
### Carthage
[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
1. Add the framework to your Carfile. e.g.,
```git "git@source.ind.ie:project/delay.git" ~> 1.0```
2. [Follow the instructions on Carthage’s readme](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).
### Manual
#### iOS
Run the `./install` script to install the dependencies for the demo apps.
This requires hacking the Xcode project file but it’s still the most elegant way of doing things. If you want a better way, [dupe this radar for seamless support of fat frameworks in Xcode](http://openradar.appspot.com/radar?id=4951631992979456).
1. Build the framework target.
2. In Xcode, add the framework to the Embed Binaries
3. Edit the `project.pbxproj` (in the <your-project>.xcodeproj folder) file and replace the line that reads something like:
```A7E653511C2496F700988537 /* Delay.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Delay.framework; path = "../../path/in/DerivedData/to/Delay.framework"; sourceTree = "<group>"; };```
See the [detailed installation instructions](#detailed-installation-instructions), below, for instructions on how to add Delay to your own apps.
With:
```A7E653511C2496F700988537 /* Delay.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Delay.framework; path = "$(CONFIGURATION_BUILD_DIR)/Delay.framework"; sourceTree = "<group>"; };```
(In other words, you’re replacing the hardcoded path to the Delay.framework within your particular Derived Data folder with a generic one. This means that anyone else who checks out your project will get the correct framework.)
#### OS X
1. Just drag the framework into the Linked Frameworks and Binaries section of your project (under General).
## Usage
(For an example of manually adding the framework, see the iOS and OS X demo apps that ship with this framework.)
Run the `./dev` script and play with the iOS and OS X demo apps.
## Usage
## Detailed usage instructions
Delay has three main use cases:
......@@ -48,70 +24,78 @@ Delay has three main use cases:
### Execute on next stack frame
delay(0.0)
{
// Do something.
}
```swift
delay(0.0)
{
// Do something.
}
```
### Execute after an arbitrary number of seconds
delay(42.0)
{
// Do something.
}
```swift
delay(42.0)
{
// Do something.
}
```
### Cancel before execution
let cancellableBlock = delay(42.0)
{
// Do something.
}
cancellableBlock.cancel()
```swift
let cancellableBlock = delay(42.0)
{
// Do something.
}
cancellableBlock.cancel()
```
### Idiom: throttle user input
var cancellableCommand:CancellableDelayedCommand?
```swift
var cancellableCommand:CancellableDelayedCommand?
// …
// …
// Throttle expensive operation so it is performed at
// most every second, no matter how often a signal is received.
cancellableCommand = cancellableCommand?.reset() ?? delay(1.0)
{
// Perform expensive operation:
// …
}
// Throttle expensive operation so it is performed at
// most every second, no matter how often a signal is received.
cancellableCommand = cancellableCommand?.reset() ?? delay(1.0)
{
// Perform expensive operation:
// …
}
```
For example, you can use this to implement auto-complete without flooding the lookup method on every keystroke.
var textDidChangeHandler:NotificationHandler?
var cancellableAutoCompleteCommand:CancellableDelayedCommand?
```swift
var textDidChangeHandler:NotificationHandler?
var cancellableAutoCompleteCommand:CancellableDelayedCommand?
// …
// …
override func viewWillAppear()
{
textDidChangeHandler = handle(NSControlTextDidChangeNotification, from: myTextInput)
{
/* with */ notification in
override func viewWillAppear()
{
textDidChangeHandler = handle(NSControlTextDidChangeNotification, from: myTextInput)
{
/* with */ notification in
let text = self.myTextInput.stringValue
let text = self.myTextInput.stringValue
// Throttle auto-complete lookups to every 1/3rd of a second.
cancellableAutoCompleteCommand = cancellableAutoCompleteCommand?.reset() ?? delay(0.3)
{
// Perform expensive operation: look-up text for auto-complete
// …
}
}
}
// Throttle auto-complete lookups to every 1/3rd of a second.
cancellableAutoCompleteCommand = cancellableAutoCompleteCommand?.reset() ?? delay(0.3)
{
// Perform expensive operation: look-up text for auto-complete
// …
}
}
}
override func viewWillDisappear()
{
cancellableAutoCompleteCommand.cancel()
textDidChangeHandler.remove()
}
override func viewWillDisappear()
{
cancellableAutoCompleteCommand.cancel()
textDidChangeHandler.remove()
}
```
Read more about the library [in this blog post](https://ind.ie/labs/blog/delay) on [Ind.ie Labs](https://ind.ie/labs).
......@@ -119,6 +103,40 @@ Read more about the library [in this blog post](https://ind.ie/labs/blog/delay)
Note that Delay is optimised for ease of authoring, beauty of interface and clarity of intent. I haven’t run into performance issues and hence haven’t felt the need to run any benchmarks at the moment but [Evgenii Rtishchev’s purely-block-based CancelBlocks](https://github.com/katleta3000/CancelBlocks/blob/master/CancelBlocks.swift), on which my solution is based, is a lighter alternative should you need it.
## Detailed installation instructions
### Carthage
1. Add the framework to your Carfile. e.g.,
```git "git@source.ind.ie:project/delay.git" ~> 1.0```
2. [Follow the instructions on Carthage’s readme](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application).
### Manual
#### iOS
This requires hacking the Xcode project file but it’s still the most elegant way of doing things. If you want a better way, [dupe this radar for seamless support of fat frameworks in Xcode](http://openradar.appspot.com/radar?id=4951631992979456).
1. Build the framework target.
2. In Xcode, add the framework to the Embed Binaries
3. Edit the `project.pbxproj` (in the <your-project>.xcodeproj folder) file and replace the line that reads something like:
```A7E653511C2496F700988537 /* Delay.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Delay.framework; path = "../../path/in/DerivedData/to/Delay.framework"; sourceTree = "<group>"; };```
With:
```A7E653511C2496F700988537 /* Delay.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Delay.framework; path = "$(CONFIGURATION_BUILD_DIR)/Delay.framework"; sourceTree = "<group>"; };```
(In other words, you’re replacing the hardcoded path to the Delay.framework within your particular Derived Data folder with a generic one. This means that anyone else who checks out your project will get the correct framework.)
#### OS X
1. Just drag the framework into the Linked Frameworks and Binaries section of your project (under General).
(For an example of manually adding the framework, see the iOS and OS X demo apps that ship with this framework.)
## Credits
Delay based on the work of [Evgenii Rtishchev](https://github.com/katleta3000/CancelBlocks) and [Chris Brind](http://stackoverflow.com/questions/24034544/dispatch-after-gcd-in-swift/24318861#24318861) (with thanks to [Cezary Wojcik](http://stackoverflow.com/a/24034838/253485).)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment