MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

The source app sample provides a number of scenarios that demonstrate how to share different
types of data. They also show how to programmatically invoke the Share charm. This isn’t typically
recommended, but it is possible. If it really fits in your app scenario, here’s how:
Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
Calling this will, as when the user invokes the charm, trigger the datarequested event where
eventArgs.request object is a Windows.ApplicationModel.DataTransfer.DataRequest object. This
request object contains two properties and two methods:
• data is the DataPackage to populate. It contains methods to make various data formats available,
though it’s important to note that not all formats will be immediately rendered. Instead, they’re
rendered only when a share target asks for them.
• deadline is a Date property indicating the time in the future when the data you’re making
available will no longer be valid (that is, will not render). This recognizes that there might be an
indeterminate amount of time between when the source app is asked for data and when the
target actually tries to use it. With delayed rendering, as noted above for the data property, it’s
possible that some transient source data might disappear after some time. By indicating that
time in deadline, rendering requests that occur past the deadline will be ignored.
• failWithDisplayText is a method to tell the share broker that sharing isn’t possible right now,
along with a string that will tell the user why (perhaps the lack of a usable selection). You call this
when you don’t have appropriate data formats or an appropriate selection to share, or if there’s
an error in populating the data package for whatever reason. The text you provide will then be
displayed in the Share charm (and thus should be localized). Scenario 8 of the source app sample
shows the use of this in the simple case when don’t provide data in response to the
datarequested event..
• getDeferral provides for async operations you might need to perform while populating the data
package (just like other deferrals elsewhere in the WinRT API). Do note that datarequested has
a 200ms timout period, after which time the Share charm will display “can’t share right now”.
Requesting a deferral does not change that timeout; it only prevents datarequested from
assuming that the data package is ready once you return from your handler.
The basic structure of a datarequested handler, then, will attempt to populate the minimal
properties of eventArgs.request.data and call eventArgs.request.failWithDisplayText when errors
occur. We see this structure in most of the scenarios in the sample:
var dataTransferManager =
Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
// Remove this listener as required
dataTransferManager.addEventListener("datarequested", dataRequested);
function dataRequested(e) {
var request = e.request;
// Title is required
496