Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 107 lines (71 sloc) 6.512 kb
ede721b @jivadevoe docs
authored
1 README
dbd25c0 @jivadevoe more docs
authored
2 ======
ede721b @jivadevoe docs
authored
3
b861bbb @jivadevoe updated docs
authored
4 This is a quickie pair of categories on UIAlertView and UIActionSheet which enables you to use blocks to handle the button selection instead of implementing a delegate.
ede721b @jivadevoe docs
authored
5
6 HOW IT WORKS
dbd25c0 @jivadevoe more docs
authored
7 ------------
ede721b @jivadevoe docs
authored
8
b861bbb @jivadevoe updated docs
authored
9 Using UIAlertView as the main example here, instead of calling the traditional `-initWithTitle:message:delegate:cancelButtonTitle:otherButtonTitles:` initializer, you call the new initializer: `-initWithTitle:message:cancelButtonItem:otherButtonItems:`. This works just like the traditional initializer, except instead of using strings for the buttons, it takes instances of RIButtonItem's. This is a class also defined as part of this framework which simply encapsulates the button label and the action block to execute when that button is tapped. The last argument to the initializer is variadic, just like the traditional initializer, so it must be `nil` terminated.
ede721b @jivadevoe docs
authored
10
b861bbb @jivadevoe updated docs
authored
11 The action blocks are of type RISimpleAction, which is typedef'd to be a block as follows:
ede721b @jivadevoe docs
authored
12
b861bbb @jivadevoe updated docs
authored
13 typedef void (^RISimpleAction)();
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
14
b861bbb @jivadevoe updated docs
authored
15 This is just a simple block which takes no arguments and returns nothing.
ede721b @jivadevoe docs
authored
16
b861bbb @jivadevoe updated docs
authored
17 The RIButtonItem class also provides a convenience method which returns an autoreleased item called, conveniently enough, `+item`. If you don't specify an action, the button will still show, but won't do anything when tapped other than dismiss the dialog. This is pretty common with cancel buttons, so another convenience method called `+itemWithLabel:` allows you to quickly create an item that has no action.
dbd25c0 @jivadevoe more docs
authored
18
19 Under the covers, the category takes the button items you pass in, and it stores them as an associated object with the UIAlertView itself. It then initializes a traditional UIAlertView, setting itself as the delegate. When the UIAlertView gets the `-alertView:didDismissWithButtonIndex:` delegate method called, it pulls out the button items, looks up the one associated with the tapped button, and executes the block associated with that button.
20
8c90648 @jivadevoe updated the docs for the new no op button action
authored
21 One little bit of weirdness you may be curious about is this: In the initializer, it retains itself. The reason it does this is because the expectation is that you'll basically fire and forget this. I didn't want to have to hold onto an instance variable for this guy or anything, and I wasn't sure if the didDismiss method was called before or after the alertview was removed from the view hierarchy and thus, possibly deallocated. Since the UIAlertView itself is it's own delegate, if it gets deallocated before the didDismiss method is called, it would crash, and we don't want that. By retaining self, we don't need to worry about it. The only concern then is that we have to remember to release self in the delegate method, which we do. If anyone can confirm or deny that this code is required, I'd welcome the discussion. Does retaining self make me feel dirty? Yes. And naughty... oh yeah... so naughty... ;)
dbd25c0 @jivadevoe more docs
authored
22
23 HOW TO USE IT
24 -------------
25
26 Typically, you'll create items that represent the buttons and the actions to take when they are tapped. For example imagine a dialog box confirming deletion of an item:
27
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
28 RIButtonItem *cancelItem = [RIButtonItem itemWithLabel:@"No" action:^{
dbd25c0 @jivadevoe more docs
authored
29 // this is the code that will be executed when the user taps "No"
30 // this is optional... if you leave the action as nil, it won't do anything
31 // but here, I'm showing a block just to show that you can use one if you want to.
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
32 }];
dbd25c0 @jivadevoe more docs
authored
33
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
34 RIButtonItem *deleteItem = [RIButtonItem itemWithLabel:@"Yes" action:^{
dbd25c0 @jivadevoe more docs
authored
35 // this is the code that will be executed when the user taps "Yes"
36 // delete the object in question...
37 [context deleteObject:theObject];
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
38 }];
dbd25c0 @jivadevoe more docs
authored
39
8accdc3 @jivadevoe more docs
authored
40 The label property on the button items is the text that will be displayed in the button.
41
dbd25c0 @jivadevoe more docs
authored
42 Once you've created these, you simply initialize your UIAlertView using the initializer, passing your button items accordingly:
43
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
44 UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:@"Delete This Item?"
45 message:@"Are you sure you want to delete this really important thing?"
46 cancelButtonItem:cancelItem
8accdc3 @jivadevoe more docs
authored
47 otherButtonItems:deleteItem, nil];
dbd25c0 @jivadevoe more docs
authored
48 [alertView show];
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
49
50 Alternatively you can also use a single line to create buttons and declare the alert view
51
52 [[[UIAlertView alloc] initWithTitle:@"Delete This Item?"
53 message:@"Are you sure you want to delete this really important thing?"
c77ae49 @aporat fixed typo in UIAlertView blocks example
aporat authored
54 cancelButtonItem:[RIButtonItem itemWithLabel:@"Yes" action:^{
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
55 // Handle "Cancel"
56 }]
c77ae49 @aporat fixed typo in UIAlertView blocks example
aporat authored
57 otherButtonItems:[RIButtonItem itemWithLabel:@"Delete" action:^{
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
58 // Handle "Delete"
59 }], nil] show];
60
dbd25c0 @jivadevoe more docs
authored
61
62 Again, this is designed to be fire and forget, so you initialize it, show it, and release it. It'll take care of cleaning up after itself.
63
67bb8de @gfontenot Edited README to include info for addButtonItem method
gfontenot authored
64 You can also add a RIButtonItem to the UIAlertView after initialization, just like you normally would:
65
66 [alertView addButtonItem:deleteItem];
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
67
67bb8de @gfontenot Edited README to include info for addButtonItem method
gfontenot authored
68 This is useful if building an UIAlertView, or UIActionSheet dynamically from an Array:
69
70 for (RIButtonItem *item in buttonItemArray) {
71 [alertView addButtonItem:item];
72 }
73
8accdc3 @jivadevoe more docs
authored
74 That's it!
75
b861bbb @jivadevoe updated docs
authored
76 The UIActionSheet category works virtually the same as the UIAlertView. Just check out the header for the initializer you need to use. It's very straightforward.
77
f06a639 @jivadevoe Update README.md
authored
78 FIND THIS USEFUL?
79 -----------------
80
81 Why don't you buy me a beer with bitcoin?
82
83 My wallet address is: 1JtjkQFmJmbMumWquh5J2fuRuD6LkWr5QL
84
85 ![Wallet QR Code](http://www.random-ideas.net/qrcode.png)
86
87
8accdc3 @jivadevoe more docs
authored
88 LICENSE
89 -------
90
8c447a5 @jivadevoe Update README.md
authored
91 Copyright (C) 2011-2014 by Random Ideas, LLC
0829aa1 @jivadevoe more docs
authored
92
93 Permission is hereby granted, free of charge, to any person obtaining a copy
94 of this software and associated documentation files (the "Software"), to deal
95 in the Software without restriction, including without limitation the rights
96 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
97 copies of the Software, and to permit persons to whom the Software is
8c447a5 @jivadevoe Update README.md
authored
98 furnished to do so.
0829aa1 @jivadevoe more docs
authored
99
100 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
101 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
102 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
103 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
104 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
105 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
d7b803d @p-l Updated the README to include shorter form RIButton creation
p-l authored
106 THE SOFTWARE.
Something went wrong with that request. Please try again.