Social

Social Components

• ContactPicker
• EmailPicker
• PhoneCall
• PhoneNumberPicker
• Texting
• Twitter

ContactPicker

Use a contact picker component to let the user choose an entry from the Android contact list.

A contact picker is a button that displays a list of contacts to choose from when the user taps it. After the user has made a selection, the following properties are set:

• ContactName: contact's name.
• EmailAddress: contact's primary email address.
• Picture: name of the file containing the contact's image, which can be used as a Picture property value for the Image or ImageSprite component.

Other properties affect the appearance of the button (including TextAlignment and BackgroundColor) and whether it can be tapped (Enabled).

Properties

Enabled

If set, user can tap contact picker to use it.

Image

Image to display on contact picker

BackgroundColor

Color for contact picker background.

ContactName

Name of selected contact.

EmailAddress

Primary email address of selected contact.

Picture

Picture of selected contact.

FontBold

If set, contact picker text is displayed in bold.

FontItalic

If set, contact picker text is displayed in italics.

FontSize

Point size for contact picker text.

FontTypeface

Font family for contact picker text.

Image

Specifies the path of the button's image. If there is both an Image and a BackgroundColor, only the Image will be visible.

Shape (designer only)

Specifies the button's shape (default, rounded, rectangular, oval). The shape will not be visible if an Image is being displayed.

ShowFeedback

Specifies if a visual feedback should be shown for a button that as an image as background.

Text

Text to display on contact picker.

TextAlignment

Left, center, or right.

TextColor

Color for contact picker text.

Visible

If set, contact picker is visible.

Width

Contact picker width (x-size).

Height

Contact picker height (y-size).

Events

AfterPicking()

Called after user picks a contact.

BeforePicking()

Called after user taps contact picker but before contact list is displayed.

GotFocus()

Contact picker became the focused component.

LostFocus()

Contact picker stopped being the focused component.

Methods

Open()

Opens the picker, as though the user clicked on it.

EmailPicker

Use an email picker component to let the user enter a user's email address from the Android contact list.

An email picker is a text box in which a user can begin entering an email address of a contact and be offered auto-completion. The initial value of the box and the value after user entry is in the Text property. If the Text property is initially empty, the contents of the Hint property will be faintly shown in the text box as a hint to the user.

Other properties affect the appearance of the email picker (including TextAlignment and BackgroundColor) and whether it can be used (Enabled).

Email pickers are usually used with a button. The user taps the button when text entry is complete.

Properties

Enabled

If set, user can tap email picker to use it.

BackgroundColor

Color for email picker background.

FontBold

If set, email picker text is displayed in bold.

FontItalic

If set, email picker text is displayed in italics.

FontSize

Point size for email picker text.

FontTypeface

Font family for email picker text.

Text

Initial text to display in email picker.

TextAlignment

Left, center, or right.

TextColor

Color for email picker text.

Hint

If Text property is empty, Hint is shown in gray.

Visible

If set, email picker is visible.

Width

Email picker width (x-size).

Height

Email picker height (y-size).

Events

GotFocus()

Email picker became the focused component.

LostFocus()

Email picker stopped being the focused component.

Methods

none

PhoneCall

Use this component to dial the phone and make a call.

PhoneCall is a non-visible component that makes a phone call to the number specified in the PhoneNumber property, which can be set either in the Designer or Blocks Editor. You can use the MakePhoneCall method to make a phone call programatically from your app.

This component is often used with the ContactPicker component, which lets the user select from the contacts stored on the phone and sets the PhoneNumber property to the contact's phone number.

To directly specify the phone number, set the PhoneNumber property to a Text with the specified digits (for example, "6505551212"). The number can be formatted with hyphens, periods, and parentheses; they are ignored. You can't include spaces in the number.

Properties

PhoneNumber

Phone number to dial.

Events

none

Methods

MakePhoneCall()

Dials the number specified by the component's PhoneNumber property.

PhoneNumberPicker

Use this component to allow users to choose a phone number from a list of Android contacts' phone numbers.

When the user taps a phone number picker button, it displays a list of the phone numbers of contacts to choose from. After the user has made a selection, the following properties will be set to information about the chosen contact:

• ContactName: contact's name.
• PhoneNumber: contact's selected phone number.
• EmailAddress: contact's primary email address.
• Picture: name of the file containing the contact's image, which can be used as a Picture property value for the Image or ImageSprite component.

Other properties affect the appearance of the button (including TextAlignment and BackgroundColor) and whether it can be tapped (Enabled).

Properties

Enabled

If set, user can tap phone number picker to use it.

Image

Image to display on phone number picker.

BackgroundColor

Color for phone number picker background.

ContactName

Name of selected contact.

EmailAddress

Primary email address of selected contact.

PhoneNumber

Selected phone number of selected contact.

Picture

Picture of selected contact.

FontBold

If set, phone number picker text is displayed in bold.

FontItalic

If set, phone number picker text is displayed in italics.

FontSize

Point size for phone number picker text.

FontTypeface

Font family for phone number picker text.

Shape (designer only)

Specifies the button's shape (default, rounded, rectangular, oval). The shape will not be visible if an Image is being displayed.

ShowFeedback

Specifies if a visual feedback should be shown for a button that as an image as background.

Text

Text to display on phone number picker.

TextAlignment

Left, center, or right.

TextColor

Color for phone number picker text.

Visible

If set, phone number picker is visible.

Width

Phone number picker width (x-size).

Height

Phone number picker height (y-size).

Events

AfterPicking()

Called after user picks a phone number.

BeforePicking()

Called after user taps phone number picker but before phone number list is displayed.

GotFocus()

Phone number picker became the focused component.

LostFocus()

Phone number picker stopped being the focused component.

Methods

Open()

Opens the picker, as though the user clicked on it.

Texting

A component that will, when the SendMessage method is called, send the text message specified in the Message property to the phone number specified in the PhoneNumber property.

This component can also receive text messages unless the ReceivingEnabled property is False. When a message arrives, the MessageReceived event is raised and provides the sending number and message.

If the GoogleVoiceEnabled property is true, messages can be sent and received over Wifi. This option requires that the user have a Google Voice account and that the mobile Voice app is installed on the phone. This option works only on phones that support Android 2.0 (Eclair) or higher.

Often, this component is used with the ContactPicker component, which lets the user select a contact from the ones stored on the phone and sets the PhoneNumber property to the contact's phone number.

To directly specify the phone number (e.g., 650-555-1212), set the PhoneNumber property to a Text with the specified digits (e.g., "6505551212"). Dashes, dots, and parentheses may be included (e.g., "(650)-555-1212") but will be ignored; spaces may not be included.

Properties>

GoogleVoiceEnabled

Whether or not the component will be able to be used with Google Voice compatibility.

PhoneNumber

Phone number that text will be sent to.

Message

Text of message that will be sent.

ReceivingEnabled

If set to 1 (OFF) no messages will be received. If set to 2 (FOREGROUND) or 3 (ALWAYS) the component will respond to messages if it is running. If the app is not running then the message will be discarded if set to 2 (FOREGROUND). If set to 3 (ALWAYS) and the app is not running the phone will show a notification. Selecting the notification will bring up the app and signal the MessageReceived event. Messages received when the app is dormant will be queued, and so several MessageReceived events might appear when the app awakens. As an app developer, it would be a good idea to give your users control over this property, so they can make their phones ignore text messages when your app is installed.

Events

MessageReceived(text number, text messageText)

Event that's raised when a new text message is received by the phone. This method shouldn't be called until the app is initialized. If dispatch fails, the message is cached.

Methods

SendMessage()

Sends the text specified by Message to the number given in PhoneNumber.

Twitter

A non-visible component that enables communication with Twitter. Once a user has logged into their Twitter account (and the authorization has been confirmed successful by the IsAuthorized event), many more operations are available:

• Searching Twitter for tweets or labels (SearchTwitter)
• Setting the status of the logged-in user (SetStatus)
• Directing a message to a specific user (DirectMessage)
• Receiving the most recent messages directed to the logged-in user (RequestDirectMessages)
• Following a specific user (Follow)
• Ceasing to follow a specific user (StopFollowing)
• Getting a list of users following the logged-in user (RequestFollowers)
• Getting the most recent messages of users followed by the logged-in user (RequestFriendTimeline)
• Getting the most recent mentions of the logged-in user (RequestMentions)

You must obtain a Comsumer Key and Consumer Secret for Twitter authorization specific to your app from http://twitter.com/oauth_clients/new

Properties

ConsumerKey

ConsumerSecret

DirectMessages

This property contains a list of the most recent messages mentioning the logged-in user. Initially, the list is empty. To set it, the program must:

1. Call the Authorize method.
2. Wait for the Authorized event.
3. Call the RequestDirectMessages method.
4. Wait for the DirectMessagesReceived event.

The value of this property will then be set to the list of direct messages retrieved (and maintain that value until any subsequent call to RequestDirectMessages).

Followers

This property contains a list of the followers of the logged-in user. Initially, the list is empty. To set it, the program must:

1. Call the Authorize method.
2. Wait for the IsAuthorized event.
3. Call the RequestFollowers method.
4. Wait for the FollowersReceived event.

The value of this property will then be set to the list of followers (and maintain its value until any subsequent call to RequestFollowers).

FriendTimeline

This property contains the 20 most recent messages of users being followed. Initially, the list is empty. To set it, the program must:

1. Call the Authorize method.
2. Wait for the IsAuthorized event.
3. Specify users to follow with one or more calls to the Follow method.
4. Call the RequestFriendTimeline method.
5. Wait for the FriendTimelineReceived event.

The value of this property will then be set to the list of messages (and maintain its value until any subsequent call to RequestFriendTimeline.

Mentions

This property contains a list of mentions of the logged-in user. Initially, the list is empty. To set it, the program must:

1. Call the Authorize method.
2. Wait for the IsAuthorized event.
3. Call the RequestMentions method.
4. Wait for the MentionsReceived event.

The value of this property will then be set to the list of mentions (and will maintain its value until any subsequent calls to RequestMentions).

SearchResults

This property, which is initially empty, is set to a list of search results after the program:

1. Calls the SearchTwitter method.
2. Waits for the SearchSuccessful event.

The value of the property will then be the same as the parameter to SearchSuccessful. Note that it is not necessary to call the Authorize method before calling SearchTwitter.

Username

The user name of the authorized user. Empty if there is no authorized user.

Events

DirectMessagesReceived(list messages)

This event is raised when the recent messages requested through RequestDirectMessages have been retrieved. A list of the messages can then be found in the messages parameter or the Messages property.

FollowersReceived(list followers)

This event is raised when all of the followers of the logged-in user requested through RequestFollowers have been retrieved. A list of the followers can then be found in the followers parameter or the Followers property.

FriendTimelineReceived(list timeline)

This event is raised when the messages requested through RequestFriendTimeline have been retrieved. The timeline parameter and the Timeline property will contain a list of lists, where each sub-list contains a status update of the form (username message)

IsAuthorized()

This event is raised after the program calls Authorize if the authorization was successful. It is also called after a call to CheckAuthorized if we already have a valid access token. After this event has been raised, any other method for this component can be called.

MentionsReceived(list mentions)

This event is raised when the mentions of the logged-in user requested through RequestMentions have been retrieved. A list of the mentions can then be found in the mentions parameter or the Mentions property.

SearchSuccessful(list searchResults)

This event is raised when the results of the search requested through SearchSuccessful have been retrieved. A list of the results can then be found in the results parameter or the Results property.

Methods

Authorize()

Redirects user to login to Twitter via the Web browser using the OAuth protocol if we don't already have authorization.

CheckAuthorized()

Checks whether we already have access, and if so, causes IsAuthorized event handler to be called.

DeAuthorize()

Removes Twitter authorization from this running app instance

DirectMessage(text user, text message)

This sends a direct (private) message to the specified user. The message will be trimmed if it exceeds 160characters.

Requirements: This should only be called after the IsAuthorized event has been raised, indicating that the user has successfully logged in to Twitter.

Follow(text user)

Starts following a user.

RequestDirectMessages()

Requests the 20 most recent direct messages sent to the logged-in user. When the messages have been retrieved, the system will raise the DirectMessagesReceived event and set the DirectMessages property to the list of messages.

Requirements: This should only be called after the IsAuthorized event has been raised, indicating that the user has successfully logged in to Twitter.

RequestFollowers()

Gets who is following you.

RequestFriendTimeline()

Gets the most recent 20 messages of usernames that you follow.

RequestMentions()

Requests the 20 most recent mentions of the logged-in user. When the mentions have been retrieved, the system will raise the MentionsReceived event and set the Mentions property to the list of mentions.

Requirements: This should only be called after the IsAuthorized event has been raised, indicating that the user has successfully logged in to Twitter.

SearchTwitter(text query)

This searches Twitter for the given String query.

Requirements: This should only be called after the IsAuthorized event has been raised, indicating that the user has successfully logged in to Twitter.

SetStatus(text status)

This updates the logged-in user's status to the specified Text, which will be trimmed if it exceeds 160 characters.

Requirements: This should only be called after the IsAuthorized event has been raised, indicating that the user has successfully logged in to Twitter.

StopFollowing(text user)

Stops following a user.