An email dialog is a modal window that allows users to compose and send an email.
 |
 |
 |
| Android | iOS | Windows Phone |
|---|
The Email Dialog is created with the Titanium.UI.createEmailDialog method. The user needs to register an e-mail account on the device in order to open the dialog. The dialog will not open when there is not a registered e-mail account.
iOS Platform Notes
On iOS, you cannot test the e-mail dialog on the iOS 8.0 simulator or greater. Test the email dialog on device.
Examples
Simple Email Dialog with Attachment
Create and send an email with a file attachment.
var emailDialog = Ti.UI.createEmailDialog()
emailDialog.subject = "Hello from Titanium";
emailDialog.toRecipients = ['foo@yahoo.com'];
emailDialog.messageBody = '<b>Appcelerator Titanium Rocks!</b>';
var f = Ti.Filesystem.getFile('cricket.wav');
emailDialog.addAttachment(f);
emailDialog.open();
- 0.8
- 0.8
- 0.8
Properties
Constant for the CANCELLED status result. On Android, this property exists but is not used.
- 0.8
- 0.8
Constant for the FAILED status result.
Constant for the FAILED status result.
Constant for the SAVED status result. On Android, this property exists but is not used.
The name of the API that this proxy corresponds to.
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
- 3.2.0
- 3.2.0
- 3.2.0
Bar color of the email dialog window, as a color name or hex triplet.
Bar color of the email dialog window, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
- 0.8
- 0.8
Recipients of the email included via the BCC (Blind Carbon Copy) field.
Recipients of the email included via the BCC (Blind Carbon Copy) field.
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
- 3.0.0
- 3.0.0
- 3.0.0
Recipients of the email included via the CC (Carbon Copy) field.
Recipients of the email included via the CC (Carbon Copy) field.
Base elevation of the view relative to its parent in pixels.
Requires: Android 5 and later
The elevation of a view determines the appearance of its shadow. Higher elevations produce larger and softer shadows.
Note: The elevation property only works on Titanium.UI.View objects.
Many Android components have a default elevation that cannot be modified.
For more information, see
Google design guidelines: Elevation and shadows.
- 5.0.0
Determines whether the email message, specifically the contents of messageBody, should be sent as HTML content type rather than plain text.
Default: false
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
- 3.6.0
The preview context used in the 3D-Touch feature "Peek and Pop".
Requires: iOS 9.0 and later
Preview context to present the "Peek and Pop" of a view. Use an configured instance of Titanium.UI.iOS.PreviewContext here.
Note: This property can only be used on devices running iOS9 or later and supporting 3D-Touch. It is ignored on older devices and can manually be checked using Titanium.UI.iOS.forceTouchSupported.
- 5.1.0
Clockwise 2D rotation of the view in degrees.
Clockwise 2D rotation of the view in degrees.
Translation values are applied to the static post layout value.
- 5.4.0
Clockwise rotation of the view in degrees (x-axis).
Clockwise rotation of the view in degrees (x-axis).
Translation values are applied to the static post layout value.
- 5.4.0
Clockwise rotation of the view in degrees (y-axis).
Clockwise rotation of the view in degrees (y-axis).
Translation values are applied to the static post layout value.
- 5.4.0
Scaling of the view in x-axis in pixels.
Scaling of the view in x-axis in pixels.
Translation values are applied to the static post layout value.
- 5.4.0
Scaling of the view in y-axis in pixels.
Scaling of the view in y-axis in pixels.
Translation values are applied to the static post layout value.
- 5.4.0
Recipients of the email included via the main TO field.
Recipients of the email included via the main TO field.
A material design visual construct that provides an instantaneous visual confirmation of touch point.
Requires: Android 5.0 and later
This is an opt-in feature available from Android Lollipop. Touch feedback is applied only if the backgroundColor is a solid color.
Default: false
- 6.1.0
Optional touch feedback ripple color. This has no effect unless touchFeedback is true.
Requires: Android 5.0 and later
Default: Theme provided color.
- 6.1.0
A name to identify this view in activity transition.
Requires: Android 5 and later
Name should be unique in the View hierarchy.
- 5.0.2
Horizontal location of the view relative to its left position in pixels.
Horizontal location of the view relative to its left position in pixels.
Translation values are applied to the static post layout value.
- 5.0.0
Vertical location of the view relative to its top position in pixels.
Vertical location of the view relative to its top position in pixels.
Translation values are applied to the static post layout value.
- 5.0.0
Depth of the view relative to its elevation in pixels.
Requires: Android 5 and later
Translation values are applied to the static post layout value.
- 5.0.0
Methods
Adds an attachment.
On Android, multiple attachments may be added, but will only work if the user chooses to send via the Android Gmail or K9 mail clients.
The Android "Mail" app, which is only available on some handsets, will only accept one attachment from a Titanium app.
Parameters
- attachment : Titanium.Blob/Titanium.Filesystem.File
Attachment to include in the email.
Returns
- void
Adds the specified callback as an event listener for the named event.
Parameters
- name : String
Name of the event.
- callback : Callback<Object>
Callback function to invoke when the event is fired.
Returns
- void
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
- 3.0.0
- 3.0.0
- 3.0.0
Parameters
- props : Dictionary
A dictionary of properties to apply.
Returns
- void
Finishes a batch update of the View's layout properties and schedules a layout pass of the view tree.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
Since the layout pass scheduled is asynchronous, the rect
and size values may not be available immediately after
finishLayout is called.
To be notified when the layout pass completes, add a listener for the postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Returns
- void
Fires a synthesized event to any registered listeners.
Parameters
- name : String
Name of the event.
- event : Dictionary
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
Returns
- void
Returns the matching view of a given view ID.
- 6.1.0
- 6.1.0
- 6.1.0
Parameters
- id : String
The ID of the view that should be returned. Use the
idproperty in your views to enable it for indexing in this method.
Returns
Hides this view.
Parameters
- options : AnimationOption (optional)
Animation options for Android. Since Release 5.1.0.
Returns
- void
Inserts a view at the specified position in the children array.
Useful if the layout property is set to horizontal or vertical.
- 3.3.0
- 3.3.0
- 3.3.0
Parameters
- params : Dictionary
Pass an object with the following key-value pairs:
view(Titanium.UI.View): View to insertposition(Number): Position in the children array to insert the view. If omitted, inserts the view to the end of the array.
Returns
- void
Indicates whether sending email is supported by the system.
On iOS 10, the user is able to uninstall the built-in applications including Mail. Because of that, you should ensure to check if the email dialog is supported on the current device.
Returns
- Boolean
Opens this email dialog.
Parameters
- properties : Object
Animation properties. Set
animatedBoolean property totrueto animate dialog on open. (iPhone, iPad only)
Returns
- void
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Parameters
- name : String
Name of the event.
- callback : Callback<Object>
Callback function to remove. Must be the same function passed to
addEventListener.
Returns
- void
Replaces a view at the specified position in the children array.
Useful if the layout property is set to horizontal or vertical.
- 3.3.0
- 3.3.0
- 3.3.0
Parameters
- params : Dictionary
Pass an object with the following key-value pairs:
view(Titanium.UI.View): View to insertposition(Number): Position in the children array of the view elment to replace.
Returns
- void
Sets the value of the barColor property.
- 0.8
- 0.8
Parameters
- barColor : String
New value for the property.
Returns
- void
Sets the value of the bccRecipients property.
Parameters
- bccRecipients : Array<String>
New value for the property.
Returns
- void
Sets the value of the bubbleParent property.
- 3.0.0
- 3.0.0
- 3.0.0
Parameters
- bubbleParent : Boolean
New value for the property.
Returns
- void
Sets the value of the ccRecipients property.
Parameters
- ccRecipients : Array<String>
New value for the property.
Returns
- void
Sets the value of the elevation property.
- 5.0.0
Parameters
- elevation : Number
New value for the property.
Returns
- void
Sets the value of the hiddenBehavior property.
- 6.1.0
Parameters
- hiddenBehavior : Number
New value for the property.
Returns
- void
Sets the value of the html property.
Parameters
- html : Boolean
New value for the property.
Returns
- void
Sets the value of the lifecycleContainer property.
- 3.6.0
Parameters
- lifecycleContainer : Titanium.UI.Window/Titanium.UI.TabGroup
New value for the property.
Returns
- void
Sets the value of the messageBody property.
Parameters
- messageBody : String
New value for the property.
Returns
- void
Sets the value of the previewContext property.
- 5.1.0
Parameters
- previewContext : Titanium.UI.iOS.PreviewContext
New value for the property.
Returns
- void
Sets the value of the rotation property.
- 5.4.0
Parameters
- rotation : Number
New value for the property.
Returns
- void
Sets the value of the rotationX property.
- 5.4.0
Parameters
- rotationX : Number
New value for the property.
Returns
- void
Sets the value of the rotationY property.
- 5.4.0
Parameters
- rotationY : Number
New value for the property.
Returns
- void
Sets the value of the scaleX property.
- 5.4.0
Parameters
- scaleX : Number
New value for the property.
Returns
- void
Sets the value of the scaleY property.
- 5.4.0
Parameters
- scaleY : Number
New value for the property.
Returns
- void
Sets the value of the subject property.
Parameters
- subject : String
New value for the property.
Returns
- void
Sets the value of the toRecipients property.
Parameters
- toRecipients : Array<String>
New value for the property.
Returns
- void
Sets the value of the touchFeedback property.
- 6.1.0
Parameters
- touchFeedback : Boolean
New value for the property.
Returns
- void
Sets the value of the touchFeedbackColor property.
- 6.1.0
Parameters
- touchFeedbackColor : String
New value for the property.
Returns
- void
Sets the value of the transitionName property.
- 5.0.2
Parameters
- transitionName : String
New value for the property.
Returns
- void
Sets the value of the translationX property.
- 5.0.0
Parameters
- translationX : Number
New value for the property.
Returns
- void
Sets the value of the translationY property.
- 5.0.0
Parameters
- translationY : Number
New value for the property.
Returns
- void
Sets the value of the translationZ property.
- 5.0.0
Parameters
- translationZ : Number
New value for the property.
Returns
- void
Makes this view visible.
Parameters
- options : AnimationOption (optional)
Animation options for Android. Since Release 5.1.0.
Returns
- void
Starts a batch update of this view's layout properties.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
To prevent a layout pass each time a property is modified, call startLayout before
changing any properties that may change this view's layout. This initiates a batch update
mode where layout changes are deferred.
Call finishLayout to end batch update mode and trigger a layout pass. For example:
view.startLayout();
view.top = 50;
view.left = 50;
view.finishLayout();
Note that any property changes made during the batch update may be deferred until
finishLayout is called. This may vary somewhat by platform. For example, changing the
text of a label may trigger a layout pass. In iOS, updating the label text is
deferred.
See also: updateLayout, finishLayout, postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Returns
- void
Performs a batch update of all supplied layout properties and schedules a layout pass after they have been updated.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
This is another way to perform a batch update. The updateLayout method is called with a
dictionary of layout properties to perform the batch update. For example:
view.updateLayout({top:50, left:50});
This is equivalent to the following:
view.startLayout();
view.top = 50;
view.left = 50;
view.finishLayout();
See also: startLayout, finishLayout, postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Parameters
- params : Dictionary
Layout properties to be updated.
Returns
- void
Events
Fired when this email dialog has completed sending an email.
Properties
- success : Boolean
Indicates if the email was handled successfully. Returns
trueif request succeeded,falseotherwise. Note that emails being deleted or saved for later do count as success. - error : String
Error message, if any returned. Will be undefined if
successistrue. - code : Number
Error code. Error code will be 0 if
successistrue, nonzero otherwise. If the error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1. - result : Number
- source : Object
Source object that fired the event.
- type : String
Name of the event fired.
- bubbles : Boolean
True if the event will try to bubble up if possible.
- cancelBubble : Boolean
Set to true to stop the event from bubbling.