NewsBlur/clients/ios/Other Sources/Overshare Kit/OSKShareableContentItem.h

//
//  OSKShareableContentItem.h
//  Overshare
//
//   
//  Copyright (c) 2013 Overshare Kit. All rights reserved.
//

@import UIKit;

extern NSString * const OSKShareableContentItemType_MicroblogPost;
extern NSString * const OSKShareableContentItemType_BlogPost;
extern NSString * const OSKShareableContentItemType_Email;
extern NSString * const OSKShareableContentItemType_SMS;
extern NSString * const OSKShareableContentItemType_PhotoSharing;
extern NSString * const OSKShareableContentItemType_CopyToPasteboard;
extern NSString * const OSKShareableContentItemType_ReadLater;
extern NSString * const OSKShareableContentItemType_LinkBookmark;
extern NSString * const OSKShareableContentItemType_WebBrowser;
extern NSString * const OSKShareableContentItemType_PasswordManagementAppSearch;
extern NSString * const OSKShareableContentItemType_ToDoListEntry;
extern NSString * const OSKShareableContentItemType_AirDrop;

///---------------------------
/// @name Abstract Base Class
///---------------------------

/**
 An abstract base class for the many kinds of shareable content items.
 
 @discussion Never instantiate `OSKShareableContentItem` directly. You must use it via
 a subclass (either built-in or one of your own).
 
 @see OSKShareableContent
 */
@interface OSKShareableContentItem : NSObject

/**
 An alternate name to be used in place of the default name of any `<OSKActivity>` that
 is handling the content item. The default is `nil`.
 
 @discussion Useful for when you need multiple instances of the same content item, e.g.
 in Riposte, we have "Email Post" and "Email Conversation" in the
 conversation share sheet. If you don't set an alternate activity name, then the
 `<OSKActivity>`'s default name and icon will be used instead.
 
 If all you need to do is localize an activity name, it is better to do that
 via the `customizationsDelegate` of `OSKPresentationManager`.
 */
@property (copy, nonatomic) NSString *alternateActivityName;

/**
 An alternate icon to be displayed in place of the default icon of any `<OSKActivity>` that
 is handling the content item. The default is `nil`.
 */
@property (strong, nonatomic) UIImage *alternateActivityIcon;

/**
 Returns either one of the officially supported item types listed above,
 or a custom item type.
 
 @warning Required. Subclasses must override without calling super.
 */
- (NSString *)itemType;

@end

///---------------------------------------------------
/// @name Microblog Posts (Twitter, App.net, Facebook)
///---------------------------------------------------

/**
 Content for sharing to microblogging services like Twitter, Facebook, or App.net.
 */
@interface OSKMicroblogPostContentItem : OSKShareableContentItem

/**
 The plain-text content of the outgoing post. Must not be nil.
 */
@property (copy, nonatomic) NSString *text;

/**
 An optional array of `<UIImage>` objects to be attached to the outgoing post.
 
 @discussion Not all activities support multiple images. Those that do not will simply
 ignore all but the first image in the array when creating a new post.
 */
@property (strong, nonatomic) NSArray *images;

/**
 The latitude component of the user's geolocation.
 */
@property (nonatomic, assign) double latitude;

/**
 The longitude component of the user's geolocation.
 */
@property (nonatomic, assign) double longitude;

@end

///-----------------------------------------
/// @name Blog Posts (Tumblr)
///-----------------------------------------

/**
 Content for sharing to blogging services like Tumblr or WordPress.
 
 @warning As of October 31, 2013, no activities in Overshare Kit are using this item.
 */
@interface OSKBlogPostContentItem : OSKShareableContentItem

/**
 The plain-text content of the blog post. Must not be nil.
 */
@property (copy, nonatomic) NSString *text;

/**
 An optional array of `<UIImage>` objects to be attached to the outgoing post.
 */
@property (strong, nonatomic) NSArray *images;

/**
 An optional array of `NSString` tags for tagging the outgoing post.
 */
@property (strong, nonatomic) NSArray *tags;

/**
 An optional flag for creating the post in the drafts queue instead of immediately publishing the post.
 
 Defaults to NO (publishes immediately).
 */
@property (assign, nonatomic) BOOL publishAsDraft;

@end

///-----------------------------------------
/// @name Email
///-----------------------------------------

/**
 Content for creating a new email message.
 */
@interface OSKEmailContentItem : OSKShareableContentItem

/**
 An array of email addresses for the "to:" field. Optional.
 */
@property (copy, nonatomic) NSArray *toRecipients;

/**
 An array of email addresses for the "cc:" field. Optional.
 */
@property (copy, nonatomic) NSArray *ccRecipients;

/**
 An array of email addresses for the "bcc:" field. Optional.
 */
@property (copy, nonatomic) NSArray *bccRecipients;

/**
 A plain-text subject for the email. Optional.
 */
@property (copy, nonatomic) NSString *subject;

/**
 The body text for the outgoing email. May be plain text or HTML markup. 
 
 If HTML, the `isHTML` property must set to `YES`.
 */
@property (copy, nonatomic) NSString *body;

/**
 Flags whether or not the `body` contents are HTML markup.
 */
@property (assign, nonatomic) BOOL isHTML;

/**
 An array of `UIImage` objects to attach to the outgoing message.
 */
@property (copy, nonatomic) NSArray *attachments;

@end

///-----------------------------------------
/// @name SMS & iMessage
///-----------------------------------------

/**
 Content for sharing via iMessage or SMS.
 */
@interface OSKSMSContentItem : OSKShareableContentItem

/**
 An array of recipient phone numbers or email addresses. Optional.
 */
@property (copy, nonatomic) NSArray *recipients;

/**
 The plain-text content of the outgoing message.
 */
@property (copy, nonatomic) NSString *body;

/**
 An array of `UIImage` objects to attach to the outgoing message.
 */
@property (copy, nonatomic) NSArray *attachments;

@end

///-----------------------------------------
/// @name Photo Sharing (Instagram, etc.)
///-----------------------------------------

/**
 Content for sharing to photo services like Instagram or Flickr.
 */
@interface OSKPhotoSharingContentItem : OSKShareableContentItem

/**
 An array of one or more `UIImage` objects.
 */
@property (copy, nonatomic) NSArray *images;

/**
 A plain-text caption to be applied to all the images.
 */
@property (copy, nonatomic) NSString *caption;

/**
 The latitude component of the user's location.
 */
@property (nonatomic, assign) double latitude;

/**
 The longitude component of the user's location.
 */
@property (nonatomic, assign) double longitude;

@end

///-----------------------------------------
/// @name Copy-to-Pasteboard
///-----------------------------------------

/**
 Content for saving to the system pasteboard.
 */
@interface OSKCopyToPasteboardContentItem : OSKShareableContentItem

/**
 Plain text content for copying & pasting.
 */
@property (copy, nonatomic) NSString *text;

@end

///---------------------------------------------
/// @name Read Later (Instapaper, Pocket, etc.)
///---------------------------------------------

/**
 Content for sending to read-later services like Instapaper or Pocket.
 */
@interface OSKReadLaterContentItem : OSKShareableContentItem

/**
 The url to be saved.
 */
@property (copy, nonatomic) NSURL *url;

@end

///-----------------------------------------
/// @name Link Bookmarking (Pinboard)
///-----------------------------------------

/**
 Content for sending to link-bookmarking services like Pinboard.
 */
@interface OSKLinkBookmarkContentItem : OSKShareableContentItem

/**
 The url to be saved. Required.
 */
@property (copy, nonatomic) NSURL *url;

/**
 The title of the bookmark. Optional.
 
 If left blank, `OSKPinboardActivity` will attempt to fetch
 the page title before sending the link to Pinboard.
 */
@property (copy, nonatomic) NSString *title;

/**
 Optional plain-text notes describing the link.
 */
@property (copy, nonatomic) NSString *notes;

/**
 Option to flag a saved item as "to-read." 
 
 Not all services may support this flag. At the very least, Pinboard does. It is
 recommended to set this to YES (it is YES by default).
 */
@property (assign, nonatomic) BOOL markToRead;

/**
 Optional array of tags for the saved item.
 */
@property (copy, nonatomic) NSArray *tags;

@end

///--------------------------------------------
/// @name Web Browsers (Safari.app, Chrome.app)
///--------------------------------------------

/**
 Content that can be opened in another app's web browser.
 */
@interface OSKWebBrowserContentItem : OSKShareableContentItem

/**
 The url to opened. Required.
 */
@property (copy, nonatomic) NSURL *url;

@end

///-----------------------------------------
/// @name 1Password Searches
///-----------------------------------------

/**
 Content for performing a search in a password management app like 1Password.
 */
@interface OSKPasswordManagementAppSearchContentItem : OSKShareableContentItem

/**
 The search query.
 */
@property (copy, nonatomic) NSString *query;

@end

///-----------------------------------------------
/// @name Creating To-Do Items (OmniFocus, Things)
///-----------------------------------------------

/**
 Content for creating a new to-do item in a task management app like OmniFocus or Things.
 */
@interface OSKToDoListEntryContentItem : OSKShareableContentItem

/**
 The title of the entry. Required.
 */
@property (copy, nonatomic) NSString *title;

/**
 Optional notes for the body of the entry.
 */
@property (copy, nonatomic) NSString *notes;

@end

///-----------------------------------------
/// @name AirDrop
///-----------------------------------------

/**
 Content that can be shared via AirDrop.
 */
@interface OSKAirDropContentItem : OSKShareableContentItem

/**
 The items in this array should be the same items that you would pass to an
 instance of `UIActivityViewController`.
 */
@property (copy, nonatomic) NSArray *items;

@end