Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 216 lines (186 sloc) 7.018 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
//
// Copyright 2009-2011 Facebook
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

// UI
#import "Three20UI/TTViewController.h"
#import "Three20UI/TTTextEditorDelegate.h"

@protocol TTTableViewDataSource;
@protocol TTMessageControllerDelegate;
@class TTPickerTextField;
@class TTActivityLabel;
@class TTTextEditor;

/**
* A view controller for composing email like messages, which is visually
* similar to Apple's in-app mail composer.
*
* This class was originally implemented before iPhone OS 3.0, which
* introduced the MFMailComposeViewController. It's original purpose
* was to fill that gap in the SDK. If you want to allow users to send
* an email via their existing Mail.app accounts, you should use
* MFMailComposeViewController.
*
* You may find this class useful if you need to present a visually similar
* view, but handle the delivery of the message yourself. This class is also
* useful when you want to customize the fields presented to the user.
*/
@interface TTMessageController : TTViewController <UITextFieldDelegate, TTTextEditorDelegate> {
@protected
  NSArray* _fields;
  NSMutableArray* _fieldViews;
  UIScrollView* _scrollView;
  TTTextEditor* _textEditor;
  TTActivityLabel* _activityView;
  NSArray* _initialRecipients;

  BOOL _showsRecipientPicker;
  BOOL _isModified;
  BOOL _requireNonEmptyMessageBody;

  id<TTTableViewDataSource> _dataSource;
  id<TTMessageControllerDelegate> _delegate;
}

/**
* The delegate that will receive messages from the TTMessageControllerDelegate
* protocol.
*/
@property (nonatomic, assign) id<TTMessageControllerDelegate> delegate;

/**
* The datasource used to autocomplete TTMessageRecipientFields. This class is
* also responsible for determining how cells representing recipients are
* labeled.
*/
@property (nonatomic, retain) id<TTTableViewDataSource> dataSource;

/**
* An array of TTMessageField instances representing the editable fields. These
* fields are rendered in order using appropriate views for each field type.
*/
@property (nonatomic, copy) NSArray* fields;

/**
* A convenience property for editing the text value of the
* TTMessageSubjectField. If no TTMessageSubjectField is found in the fields
* array, nil will be returned from the getter and the setter will be a no-op.
*/
@property (nonatomic, copy) NSString* subject;

/**
* The body of the message. The body is not required for the user to send a
* message.
*/
@property (nonatomic, copy) NSString* body;

/**
* Controls whether a contact add button is shown in the views for
* TTMessageRecipientField instances.
*/
@property (nonatomic) BOOL showsRecipientPicker;

/**
* Indicates if this message has been modified since it was originally
* shown. If the message has been modified, the user will be asked for
* confirmation before their cancel request is enacted.
*/
@property (nonatomic, readonly) BOOL isModified;

/**
* Indicates if the user must enter text in the editor field to be allowed to
* send the message.
*
* @default NO
*/
@property (nonatomic) BOOL requireNonEmptyMessageBody;

/**
* Initializes the class with an array of recipients. These recipients will
* be pre-filled in the TTMessageRecipientField's view.
*
* If a non-empty recipients array is provided, TTMessageController expects
* the first field to be an instance of TTMessageRecipientField. You may pass
* nil if you do not wish to supply initial recipients.
*/
- (id)initWithRecipients:(NSArray*)recipients;

/**
* Adds the supplied recipient to the field at the index provided. That
* recipient will be rendered as a cell within that field's view. The cell's
* label will be determined by asking the datasource for a string label for
* the recipient object provided.
*
* This method is a no-op if the datasource fails to provide a label for the
* cell, or if the fieldIndex provided does not refer to a
* TTPickerTextField.
*/
- (void)addRecipient:(id)recipient forFieldAtIndex:(NSUInteger)fieldIndex;

/**
* Returns the text value of the field at the supplied index. Passing
* fields.count returns the body contents.
*
* Whitespace has been trimmed from the returned value.
*/
- (NSString*)textForFieldAtIndex:(NSUInteger)fieldIndex;

/**
* Sets the text value for the field at fieldIndex. Passing fields.count
* sets the body text.
*/
- (void)setText:(NSString*)text forFieldAtIndex:(NSUInteger)fieldIndex;

/**
* Returns true if the field at the supplied index is not empty or has
* only whitespace. Passing fields.count returns true if the body has any
* text, whitespace included.
*/
- (BOOL)fieldHasValueAtIndex:(NSUInteger)fieldIndex;

/**
* Returns the UIView instance representing the field at fieldIndex. Passing
* fields.count returns the view representing the body contents.
*/
- (UIView*)viewForFieldAtIndex:(NSUInteger)fieldIndex;

/**
* Causes a view used to indicate message activity to be shown or dismissed
* depending on the value of show. This view obscures the editable field views.
* It is usually shown while the message is being sent.
*/
- (void)showActivityView:(BOOL)show;

/**
* Returns the title for the activity view that is shown by showActivityView.
* By default, the title is "Sending...", but subclasses may override this
* method to show a different title. The default title has been localized.
*/
- (NSString*)titleForSending;

/**
* Tells the delegate to send the message.
*/
- (void)send;

/**
* Cancel the message, but confirm first with the user if necessary.
*/
- (void)cancel:(BOOL)confirmIfNecessary;

/**
* Confirms with the user that it is ok to cancel.
*/
- (void)confirmCancellation;

/**
* Sent before the delegate is informed that it should send the message.
* Subclasses can override this method to implement custom logic.
*/
- (void)messageWillSend:(NSArray*)fields;

/**
* The user touched the recipient picker button. Subclasses can override
* this method to implement custom logic.
*/
- (void)messageWillShowRecipientPicker;

/**
* Sent after the delegate has been informed that it should send the message.
* Subclasses can override this method to implement custom logic.
*/
- (void)messageDidSend;

/**
* Determines if the message should cancel without confirming with the user.
* The default implementation is to allow the user to cancel without
* confirmation if no required fields have been modified and they have not
* entered any subject or body text.
*/
- (BOOL)messageShouldCancel;

@end
Something went wrong with that request. Please try again.