Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

216 lines (186 sloc) 7.018 kB
//
// 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
Jump to Line
Something went wrong with that request. Please try again.