README.md in bubble-wrap-1.2.0 vs README.md in bubble-wrap-1.3.0.osx
- old
+ new
@@ -411,12 +411,16 @@
end
```
### UIBarButtonItem
-`BW::UIBarButtonItem` provides an idiomatic Ruby syntax for instantiating `UIBarButtonItem` objects. Instead of a target-action pair, each method accepts a block. When the button is tapped, the block is executed. As a convenience, the block is optional.
+`BW::UIBarButtonItem` is a subclass of `UIBarButtonItem` with an natural Ruby syntax.
+#### Constructors
+
+Instead specifying a target-action pair, each constructor method accepts an optional block. When the button is tapped, the block is executed.
+
```ruby
BW::UIBarButtonItem.system(:save) do
# ...
end
@@ -441,44 +445,46 @@
# ...
end
# NOTE: The block is attached to the view as a single tap gesture recognizer.
```
-Alternatively, `BW::UIBarButtonItem` provides a flexible, builder-style syntax for dynamically instantiating `UIBarButtonItem` objects.
+The `.new` constructor provides a flexible, builder-style syntax.
```ruby
options = { :system => :save }
-BW::UIBarButtonItem.build(options) do
+BW::UIBarButtonItem.new(options) do
# ...
end
options = { :styled => :plain, :title => "Friends" }
-BW::UIBarButtonItem.build(options) do
+BW::UIBarButtonItem.new(options) do
# ...
end
options = { :styled => :bordered, :image => UIImage.alloc.init }
-BW::UIBarButtonItem.build(options) do
+BW::UIBarButtonItem.new(options) do
# ...
end
options = {
:styled => :bordered,
:image => UIImage.alloc.init,
:landscape => UIImage.alloc.init
}
-BW::UIBarButtonItem.build(options) do
+BW::UIBarButtonItem.new(options) do
# ...
end
options = { :custom => UIView.alloc.init }
-BW::UIBarButtonItem.build(options) do
+BW::UIBarButtonItem.new(options) do
# ...
end
# NOTE: The block is attached to the view as a single tap gesture recognizer.
```
+#### Button types
+
The `.styled` button types are:
```ruby
:plain
:bordered
@@ -512,10 +518,188 @@
:undo
:redo
:page_curl
```
+### UIAlertView
+
+`BW::UIAlertView` is a subclass of `UIAlertView` with an natural Ruby syntax.
+
+#### Default alert
+
+The `.default` constructor accepts an optional `Hash` of options and returns a `BW::UIAlertView` instance in the `UIAlertViewStyleDefault` style. The instance can then be given an `#on_click` callback to be executed when it's button is clicked. For example:
+
+
+
+```ruby
+options = { :title => "Are you ready?" }
+ready_alert = BW::UIAlertView.default(options).on_click do |alert|
+ # ...
+end
+
+ready_alert.show
+```
+
+#### Input alerts
+
+`BW::UIAlertView` has constructors for input alerts too.
+
+`.plain_text_input` returns an instance in the `UIAlertViewStylePlainTextInput` style.
+
+
+
+```ruby
+options = { :title => "Replicator" }
+replicator_alert = BW::UIAlertView.plain_text_input(options).on_click do |alert|
+ alert.plain_text_field.text #=> "Tea. Early Grey. Hot."
+end
+
+replicator_alert.show
+```
+
+`.secure_text_input` returns an instance in the `UIAlertViewStyleSecureTextInput` style.
+
+
+
+```ruby
+options = { :title => "Authorization" }
+replicator_alert = BW::UIAlertView.secure_text_input(options).on_click do |alert|
+ alert.secure_text_field.text #=> "Theta2997"
+end
+
+replicator_alert.show
+```
+
+And `.login_and_password_input` returns an instance in the `UIAlertViewStyleLoginAndPasswordInput` style.
+
+
+
+```ruby
+options = { :title => "Authorization" }
+auth_alert = BW::UIAlertView.login_and_password_input(options).on_click do |alert|
+ alert.login_text_field.text #=> "La Forge"
+ alert.password_text_field.text #=> "Theta2997"
+end
+
+auth_alert.show
+```
+
+#### Buttons
+
+Each alert style has sane, default button titles. Yet they're fully customizable by providing either a `String` to the constructor's `:buttons` argument
+
+
+
+```ruby
+alert = BW::UIAlertView.default(:title => "BubbleWrap is", :buttons => "Awesome")
+
+alert.show
+```
+
+Or an `Array` of strings to the constructor's `:buttons` argument.
+
+
+
+```ruby
+options = {
+ :title => "Dinner this Friday?",
+ :message => "My treat!",
+ :buttons => ["No", "Maybe", "Yes"]
+}
+alert = BW::UIAlertView.default(options)
+
+alert.show
+```
+
+Inside a callback, the `#clicked_button` method contains the `index` and `title` of the clicked button.
+
+
+
+```ruby
+options = {
+ :title => "Warp Engine Online",
+ :message => "Plot a course for Starbase 118. Warp 7.",
+ :buttons => ["Cancel", "Engage"],
+}
+warp_alert = BW::UIAlertView.default(options).on_click do |alert|
+ if alert.clicked_button.index == 0
+ # ...
+ else
+ # ...
+ end
+
+ if alert.clicked_button.title == "Cancel"
+ # ...
+ else
+ # ...
+ end
+end
+
+warp_alert.show
+```
+
+When the constructor's `:cancel_button_index` argument is provided, the `clicked_button` knows whether or not it's a `cancel?` button. Conveniently, the argument is automatically set to `0` for all constructors **EXCEPT** `.default` and `.new`.
+
+
+
+```ruby
+options = {
+ :title => "Warp Engine Online",
+ :message => "Plot a course for Starbase 118. Warp 7.",
+ :buttons => ["Cancel", "Engage"],
+ :cancel_button_index => 0 # set for all constructors EXCEPT `.default` and `.new`
+}
+warp_alert = BW::UIAlertView.default(options).on_click do |alert|
+ # NOTE: uses the :cancel_button_index argument
+ if alert.clicked_button.cancel?
+ # ...
+ else
+ # ...
+ end
+end
+
+warp_alert.show
+```
+
+#### Callbacks
+
+`BW::UIAlertView` instances are their own delegate. The complete `UIAlertViewDelegte` protocol is available via callbacks.
+
+```ruby
+alert = BW::UIAlertView.default
+
+alert.will_present do |alert|
+ # aka willPresentAlertView:
+end
+
+alert.did_present do |alert|
+ # aka didPresentAlertView:
+end
+
+alert.on_click do |alert|
+ # aka alertView:clickedButtonAtIndex:
+end
+
+alert.will_dismiss do |alert|
+ # aka alertView:willDismissWithButtonIndex:
+end
+
+alert.did_dismiss do |alert|
+ # aka alertView:didDismissWithButtonIndex:
+end
+
+alert.on_system_cancel do |alert|
+ # aka alertViewCancel:
+end
+
+alert.enable_first_other_button? do |alert|
+ # aka alertViewShouldEnableFirstOtherButton:
+ # NOTE: must return a boolean
+ true
+end
+```
+
## HTTP
`BW::HTTP` wraps `NSURLRequest`, `NSURLConnection` and friends to provide Ruby developers with a more familiar and easier to use API.
The API uses async calls and blocks to stay as simple as possible.
@@ -555,9 +739,35 @@
A `:download_progress` option can also be passed. The expected object
would be a Proc that takes two arguments: a float representing the
amount of data currently received and another float representing the
total amount of data expected.
+### Gotchas
+
+Because of how RubyMotion currently works, you sometimes need to assign objects as `@instance_variables` in order to retain their callbacks.
+
+For example:
+
+```ruby
+class HttpClient
+ def get_user(user_id, &callback)
+ BW::HTTP.get(user_url(user_id)) do |response|
+ # ..
+ end
+ end
+end
+```
+
+This class should be invoked in your code as:
+
+```ruby
+@http_client = HttpClient.new
+@http_client.get_user(user_id) do |user|
+ # ..
+end
+```
+
+(instead of doing an instance-variable-less `HttpClient.new.get_user`)
## RSS Parser
**Since: > version 1.0.0**
The RSS Parser provides an easy interface to consume RSS feeds in an