Titanium.UI.EmailDialog

> Titanium.UI.EmailDialog

An email dialog is a modal window that allows users to compose and send an email.

AndroidiOSWindows 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.

Mobile Web Platform Notes

On Mobile Web, the application will open the OS's default e-mail client.

The to addresses, cc addresses, bcc addresses, subject, and body are appended together and formatted into a mailto: URL. This URL typically has a limit of approximately 2000 characters.

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
  • 1.8
  • 4.1.0
Defined By

Properties

Optional parameter to enable animation to hide and show.

Optional parameter to enable animation to hide and show.

  • 5.1.0
Titanium.UI.EmailDialog
: Numberreadonly
Constant for the CANCELLED status result. ...

Constant for the CANCELLED status result. On Android, this property exists but is not used.

  • 0.8
  • 0.8
  • 4.1.0
Titanium.UI.EmailDialog
FAILED : Numberreadonly

Constant for the FAILED status result.

Constant for the FAILED status result.

Titanium.UI.EmailDialog
: Numberreadonly
Constant for the SAVED status result. ...

Constant for the SAVED status result. On Android, this property exists but is not used.

Titanium.UI.EmailDialog
SENT : Numberreadonly

Constant for the SENT status result.

Constant for the SENT status result.

apiName : Stringreadonly

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
  • 3.2.0
  • 4.1.0
Titanium.UI.EmailDialog
barColor : String

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
Titanium.UI.EmailDialog
bccRecipients : String[]

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. ...

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
  • 4.1.0
Titanium.UI.EmailDialog
ccRecipients : String[]

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. ...

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
Titanium.UI.EmailDialog
: Boolean
Determines whether the email message, specifically the contents of messageBody, should be sent as HTML content type ...

Determines whether the email message, specifically the contents of messageBody, should be sent as HTML content type rather than plain text.

On Mobile Web, while iPhone and iPad properly interpret HTML messages, some email clients, especially those for the desktop, do not support them.

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
  • 4.1.0
Titanium.UI.EmailDialog
messageBody : String

Email message body.

Email message body.

The preview context used in the 3D-Touch feature "Peek and Pop". ...

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
Titanium.UI.EmailDialog
subject : String

Subject line for the email.

Subject line for the email.

Titanium.UI.EmailDialog
toRecipients : String[]

Recipients of the email included via the main TO field.

Recipients of the email included via the main TO field.

A name to identify this view in activity transition. ...

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. ...

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
Defined By

Methods

Titanium.UI.EmailDialog
( attachment )
Adds an attachment. ...

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.

  • 0.8
  • 0.8
  • 0.8
  • 4.1.0

Parameters

Returns

  • void
Adds the specified callback as an event listener for the named event. ...

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. ...

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
  • 3.0.0
  • 4.1.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. ...

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.

On Mobile Web, this method has no effect, but is included for parity.

  • 2.0.0
  • 2.0.0
  • 2.0.0
  • 2.0.0

Returns

  • void
Fires a synthesized event to any registered listeners. ...

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
Gets the value of the AnimationOption property. ...

Gets the value of the AnimationOption property.

  • 5.1.0

Returns

  • void
Gets the value of the apiName property. ...

Gets the value of the apiName property.

  • 3.2.0
  • 3.2.0
  • 3.2.0
  • 3.2.0
  • 4.1.0

Returns

  • String
Titanium.UI.EmailDialog
( ) : String
Gets the value of the barColor property. ...

Gets the value of the barColor property.

  • 0.8
  • 0.8

Returns

  • String
Titanium.UI.EmailDialog
( ) : String[]
Gets the value of the bccRecipients property. ...

Gets the value of the bccRecipients property.

Returns

  • String[]
Gets the value of the bubbleParent property. ...

Gets the value of the bubbleParent property.

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0

Returns

  • Boolean
Titanium.UI.EmailDialog
( ) : String[]
Gets the value of the ccRecipients property. ...

Gets the value of the ccRecipients property.

Returns

  • String[]
Gets the value of the elevation property. ...

Gets the value of the elevation property.

  • 5.0.0

Returns

  • Number
Titanium.UI.EmailDialog
( ) : Boolean
Gets the value of the html property. ...

Gets the value of the html property.

Returns

  • Boolean
Gets the value of the lifecycleContainer property. ...

Gets the value of the lifecycleContainer property.

  • 3.6.0
  • 4.1.0

Returns

Titanium.UI.EmailDialog
( ) : String
Gets the value of the messageBody property. ...

Gets the value of the messageBody property.

Returns

  • String
Gets the value of the previewContext property. ...

Gets the value of the previewContext property.

  • 5.1.0

Returns

Gets the value of the rotation property. ...

Gets the value of the rotation property.

  • 5.4.0

Returns

  • Number
Gets the value of the rotationX property. ...

Gets the value of the rotationX property.

  • 5.4.0

Returns

  • Number
Gets the value of the rotationY property. ...

Gets the value of the rotationY property.

  • 5.4.0

Returns

  • Number
Gets the value of the scaleX property. ...

Gets the value of the scaleX property.

  • 5.4.0

Returns

  • Number
Gets the value of the scaleY property. ...

Gets the value of the scaleY property.

  • 5.4.0

Returns

  • Number
Titanium.UI.EmailDialog
( ) : String
Gets the value of the subject property. ...

Gets the value of the subject property.

Returns

  • String
Titanium.UI.EmailDialog
( ) : String[]
Gets the value of the toRecipients property. ...

Gets the value of the toRecipients property.

Returns

  • String[]
Gets the value of the transitionName property. ...

Gets the value of the transitionName property.

  • 5.0.2

Returns

  • String
Gets the value of the translationX property. ...

Gets the value of the translationX property.

  • 5.0.0

Returns

  • Number
Gets the value of the translationY property. ...

Gets the value of the translationY property.

  • 5.0.0

Returns

  • Number
Gets the value of the translationZ property. ...

Gets the value of the translationZ property.

  • 5.0.0

Returns

  • Number
Hides this view. ...

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. ...

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
  • 4.1.0

Parameters

  • params : Dictionary

    Pass an object with the following key-value pairs:

    • view (Titanium.UI.View): View to insert
    • position (Number): Position in the children array to insert the view. If omitted, inserts the view to the end of the array.

Returns

  • void
Titanium.UI.EmailDialog
( ) : Boolean
Indicates whether sending email is supported by the system. ...

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
Titanium.UI.EmailDialog
( properties )
Opens this email dialog. ...

Opens this email dialog.

Parameters

  • properties : Object

    Animation properties. Set animated Boolean property to true to animate dialog on open. (iPhone, iPad only)

Returns

  • void
Removes the specified callback as an event listener for the named event. ...

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. ...

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
  • 4.1.0

Parameters

  • params : Dictionary

    Pass an object with the following key-value pairs:

    • view (Titanium.UI.View): View to insert
    • position (Number): Position in the children array of the view elment to replace.

Returns

  • void
Sets the value of the AnimationOption property. ...

Sets the value of the AnimationOption property.

  • 5.1.0

Parameters

  • AnimationOption : String

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( barColor )
Sets the value of the barColor property. ...

Sets the value of the barColor property.

  • 0.8
  • 0.8

Parameters

  • barColor : String

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( bccRecipients )
Sets the value of the bccRecipients property. ...

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. ...

Sets the value of the bubbleParent property.

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0

Parameters

  • bubbleParent : Boolean

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( ccRecipients )
Sets the value of the ccRecipients property. ...

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. ...

Sets the value of the elevation property.

  • 5.0.0

Parameters

  • elevation : Number

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( html )
Sets the value of the html property. ...

Sets the value of the html property.

Parameters

  • html : Boolean

    New value for the property.

Returns

  • void
Sets the value of the lifecycleContainer property. ...

Sets the value of the lifecycleContainer property.

  • 3.6.0
  • 4.1.0

Parameters

Returns

  • void
Titanium.UI.EmailDialog
( messageBody )
Sets the value of the messageBody property. ...

Sets the value of the messageBody property.

Parameters

  • messageBody : String

    New value for the property.

Returns

  • void
Sets the value of the previewContext property. ...

Sets the value of the previewContext property.

  • 5.1.0

Parameters

Returns

  • void
Sets the value of the rotation property. ...

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. ...

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. ...

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. ...

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. ...

Sets the value of the scaleY property.

  • 5.4.0

Parameters

  • scaleY : Number

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( subject )
Sets the value of the subject property. ...

Sets the value of the subject property.

Parameters

  • subject : String

    New value for the property.

Returns

  • void
Titanium.UI.EmailDialog
( toRecipients )
Sets the value of the toRecipients property. ...

Sets the value of the toRecipients property.

Parameters

  • toRecipients : Array<String>

    New value for the property.

Returns

  • void
Sets the value of the transitionName property. ...

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. ...

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. ...

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. ...

Sets the value of the translationZ property.

  • 5.0.0

Parameters

  • translationZ : Number

    New value for the property.

Returns

  • void
Makes this view visible. ...

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. ...

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, while on Mobile Web, the label text is updated immediately but the control is not resized until finishLayout is called.

See also: updateLayout, finishLayout, postlayout event.

On Mobile Web, this method is included for parity only, and thus has no effect.

  • 2.0.0
  • 2.0.0
  • 2.0.0
  • 2.0.0

Returns

  • void
( params )deprecated
Performs a batch update of all supplied layout properties and schedules a layout pass after they have been updated. ...

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.

On Mobile Web, this method is included for parity only, and thus has no effect.

  • 2.0.0
  • 2.0.0
  • 2.0.0
  • 2.0.0

Parameters

  • params : Dictionary

    Layout properties to be updated.

Returns

  • void
Defined By

Events

Titanium.UI.EmailDialog
Fired when this email dialog has completed sending an email. ...

Fired when this email dialog has completed sending an email.

On Mobile Web, as the platform cannot determine whether a message has been sent or not, this event fires immediately after calling open() and always reports success.

  • 0.8
  • 0.8
  • 0.8
  • 1.8

Properties

  • success : Boolean

    Indicates if the email was handled successfully. Returns true if request succeeded, false otherwise. Note that emails being deleted or saved for later do count as success.

  • error : String

    Error message, if any returned. Will be undefined if success is true.

  • code : Number

    Error code. Error code will be 0 if success is true, 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

    Status of the email send process.

    The SAVED and CANCELLED constants are iOS only.

    On Android, this property will return SENT when the user discards or saves a message.

    This API can be assigned the following constants:

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

    •  
    •  
    •  
  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

    •  
    •  
    •  
  • source : Object

    Source object that fired the event.

    •  
    •  
    •  
    •  
    •  
  • type : String

    Name of the event fired.

    •  
    •  
    •  
    •  
    •