You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Toolkit Data Flavors

Mike Pinkerton (pinkerton@netscape.com)
7/3/2000

XPToolkit has a variety of intrinsic data flavors which it uses to give meaning to the data on the clipboard or in a drag. This document details only the flavors needed by the toolkit for basic operation. Clients of XPTookit may at any time invent their own data flavors, but they are not discussed here.

Flavor

Brief Description

text/unicode

Two-byte unicode plain text with no formatting information

text/xif

An XML interchange format that includes text and its formatting similar to html

text/html

HTML

text/plain

One-byte plain text, for internal use only.

AOLMAIL

A format used by AOL/AIM for formatted text, similar to HTML

image/png

Binary PNG image data

image/jpg

Binary JPEG image data

image/gif

Binary GIF image data

application/x-moz-file

A file object (supporting nsIFile) for identifying a local file

text/x-moz-url

A url and title for identifying the data is a URL for platforms that care

Flavor	Brief Description
text/unicode	Two-byte unicode plain text with no formatting information
text/xif	An XML interchange format that includes text and its formatting similar to html
text/html	HTML
text/plain	One-byte plain text, for internal use only.
AOLMAIL	A format used by AOL/AIM for formatted text, similar to HTML
image/png	Binary PNG image data
image/jpg	Binary JPEG image data
image/gif	Binary GIF image data
application/x-moz-file	A file object (supporting nsIFile) for identifying a local file
text/x-moz-url	A url and title for identifying the data is a URL for platforms that care

text/unicode

Description

Probably the most common data flavor, text/unicode represents text with no inherent formatting (if you want to encode style, such as bold or italics, use a different flavor). As this is the most universal of flavors, and is used and understood by most external applications, every drop site should accept this flavor and every drag source should advertise it.

Format Of Data

Two byte, unicode text. The length of the string is not explicitly in the format but can be computed by dividing the size of the data by two. The text is not null terminated.

FE-Specific Information

Since most operating systems and external applications don't speak two-byte text, this flavor is internally translated to and from text/plain within the toolkit. Clients of XPToolkit do not need to worry about this and should only use text/unicode.

Win32: Translated to the CF_UNICODE flavor on the clipboard
MacOS: No native translation
Unix: No native translation

Description
Probably the most common data flavor, text/unicode represents text with no inherent formatting (if you want to encode style, such as bold or italics, use a different flavor). As this is the most universal of flavors, and is used and understood by most external applications, every drop site should accept this flavor and every drag source should advertise it.
Format Of Data
Two byte, unicode text. The length of the string is not explicitly in the format but can be computed by dividing the size of the data by two. The text is not null terminated.
FE-Specific Information
Since most operating systems and external applications don't speak two-byte text, this flavor is internally translated to and from text/plain within the toolkit. Clients of XPToolkit do not need to worry about this and should only use text/unicode. Win32: Translated to the CF_UNICODE flavor on the clipboard MacOS: No native translation Unix: No native translation

text/xif

Description

XIF, eXchange Information Format, is an intermediate representation of styled text used for easy conversion to a variety of formats such as HTML or plain text. The presentation shell spits out XIF when asked to serialize portions of the content model.

Most cut/copy/drags that involve content from a browser or composer widget will put only XIF into the transferable along with registering a converter that knows how to translate the XIF to a variety of formats.

Format Of Data

Two-byte XML. See XXX for a description.

FE-Specific Information

No operating systems or external applications understand this flavor. It is for internal use only.

Description
XIF, eXchange Information Format, is an intermediate representation of styled text used for easy conversion to a variety of formats such as HTML or plain text. The presentation shell spits out XIF when asked to serialize portions of the content model. Most cut/copy/drags that involve content from a browser or composer widget will put only XIF into the transferable along with registering a converter that knows how to translate the XIF to a variety of formats.
Format Of Data
Two-byte XML. See XXX for a description.
FE-Specific Information
No operating systems or external applications understand this flavor. It is for internal use only.

text/html

Description

Styled text described by HTML.

Format Of Data

An HTML fragment, not a full HTML document (ie, missing <HEAD> and <BODY> tags, etc).

FE-Specific Information

No operating systems or external applications understand this flavor. It is for internal use only.

Description
Styled text described by HTML.
Format Of Data
An HTML fragment, not a full HTML document (ie, missing <HEAD> and <BODY> tags, etc).
FE-Specific Information
No operating systems or external applications understand this flavor. It is for internal use only.

text/plain

Description

Since most platforms and external applications don't understand the unicode format we use internally, the toolkit provides text/plain as a bridge.

Do not use this flavor explicitly as it is handled internally by the toolkit:

If an XPToolkit client asks the toolkit for text/unicode (eg, on a paste) and it is not present, the toolkit will look for text/plain and do the appropriate conversion to unicode from the platform charset.

If the XPToolkit client is publishing data to the OS (eg, on a copy) and the list of flavors includes text/unicode, the toolkit will automatically add an additional text/plain flavor containing the unicode data coverted to single byte and encoded using the platform's native charset.

Format Of Data

One byte, unstyled text in the platform's native encoding.

FE-Specific Information

Win32: Translated to the CF_TEXT flavor on the clipboard

MacOS: Translated to the 'TEXT' flavor. If the data is a URL, the OS will create a special favorite file instead of the standard clipping if this is a drag to the Finder.

Unix: Translated to UTF8_STRING.

Description
Since most platforms and external applications don't understand the unicode format we use internally, the toolkit provides text/plain as a bridge. Do not use this flavor explicitly as it is handled internally by the toolkit: If an XPToolkit client asks the toolkit for text/unicode (eg, on a paste) and it is not present, the toolkit will look for text/plain and do the appropriate conversion to unicode from the platform charset. If the XPToolkit client is publishing data to the OS (eg, on a copy) and the list of flavors includes text/unicode, the toolkit will automatically add an additional text/plain flavor containing the unicode data coverted to single byte and encoded using the platform's native charset.
Format Of Data
One byte, unstyled text in the platform's native encoding.
FE-Specific Information
Win32: Translated to the CF_TEXT flavor on the clipboard MacOS: Translated to the 'TEXT' flavor. If the data is a URL, the OS will create a special favorite file instead of the standard clipping if this is a drag to the Finder. Unix: Translated to UTF8_STRING.

application/x-moz-file

Description

Used during drags between the desktop and the application, the presence of the application/x-moz-file flavor indicates that a file has been dragged onto the app or that a file should be created.

Do not use this flavor to create an Internet Shortcut (or MacOS favorite) on the desktop. See the text/x-moz-url for how to do that.

Format Of Data

An object which supports nsIFile. To get the URL, create an url object (component://netscape/network/standard-url), set the file property to the object you get from the transferable, then access it's spec property. For example:

var dataObj = aData.data.data.QueryInterface(Components.interfaces.nsIFile); if (dataObj) { var fileURL = nsJSComponentManager .createInstance("component://netscape/network/standard-url", "nsIFileURL"); fileURL.file = dataObj; // use fileURL.spec to get the path }

FE-Specific Information

Creation of the object which supports nsIFile at the OS boundary is handled internally to the Drag Service. XPToolkit clients should not rely on any particular implementation.

Description
Used during drags between the desktop and the application, the presence of the application/x-moz-file flavor indicates that a file has been dragged onto the app or that a file should be created. Do not use this flavor to create an Internet Shortcut (or MacOS favorite) on the desktop. See the text/x-moz-url for how to do that.
Format Of Data
An object which supports nsIFile. To get the URL, create an url object (component://netscape/network/standard-url), set the file property to the object you get from the transferable, then access it's spec property. For example: var dataObj = aData.data.data.QueryInterface(Components.interfaces.nsIFile); if (dataObj) { var fileURL = nsJSComponentManager .createInstance("component://netscape/network/standard-url", "nsIFileURL"); fileURL.file = dataObj; // use fileURL.spec to get the path }
FE-Specific Information
Creation of the object which supports nsIFile at the OS boundary is handled internally to the Drag Service. XPToolkit clients should not rely on any particular implementation.

text/x-moz-url

Description

The Drag Service needs to know when a drag item is a URL so that it can do certain platform integration work under the hood. Since it's not possible to know the semantic meaning of, say, text/unicode, this is accomplished by additionally registering the text/x-moz-url flavor.

Whenever you have data that is known to be a URL (such as dragging a link or a bookmark), XPToolkit clients should add this flavor.

Format Of Data

<url> <space> <page title>

for example:

http://www.aol.com America Online's Home Page

FE-Specific Information

When the Drag Service sees this flavor, it does a bunch of platform-specific work under the hood, both for integration with the desktop, but also mapping to previous versions of Navigator.

Win32: Adds the CFSTR_FILECONTENTS and CFSTR_FILEDESCRIPTOR flavors so that the Windows desktop will allow creation of an Internet Shortcut.

MacOS: Nothing at the present time.

Unix: Mapped to _NETSCAPE_URL so that existing applications recognize this as a url. (not yet implemented)

Description
The Drag Service needs to know when a drag item is a URL so that it can do certain platform integration work under the hood. Since it's not possible to know the semantic meaning of, say, text/unicode, this is accomplished by additionally registering the text/x-moz-url flavor. Whenever you have data that is known to be a URL (such as dragging a link or a bookmark), XPToolkit clients should add this flavor.
Format Of Data
<url> <space> <page title> for example: http://www.aol.com America Online's Home Page
FE-Specific Information
When the Drag Service sees this flavor, it does a bunch of platform-specific work under the hood, both for integration with the desktop, but also mapping to previous versions of Navigator. Win32: Adds the CFSTR_FILECONTENTS and CFSTR_FILEDESCRIPTOR flavors so that the Windows desktop will allow creation of an Internet Shortcut. MacOS: Nothing at the present time. Unix: Mapped to _NETSCAPE_URL so that existing applications recognize this as a url. (not yet implemented)

AOLMAIL

Description

A format known to the win32 AOL and AIM clients for transferring styled text. It is basically HTML with an extra wrapping tag.

Hopefully, we can one day forget that this ugly step-sister of text/html exists. Our implementation of the AIM client should only use text/html except when handling incoming data (eg, a paste).

Format Of Data

<HTML> <...html data...> </HTML>

FE-Specific Information

This flavor is a legacy of the win32 AOL clients. It has no meaning on Mac or Unix.

Description
A format known to the win32 AOL and AIM clients for transferring styled text. It is basically HTML with an extra wrapping tag. Hopefully, we can one day forget that this ugly step-sister of text/html exists. Our implementation of the AIM client should only use text/html except when handling incoming data (eg, a paste).
Format Of Data
<HTML> <...html data...> </HTML>
FE-Specific Information
This flavor is a legacy of the win32 AOL clients. It has no meaning on Mac or Unix.

Description

Format Of Data

FE-Specific Information

Mozilla