Dropping content isn't a drag!

2,284 views
2,190 views

Published on

Raise your hand if you've heard this before: Can I drag and drop (or paste) content from somewhere else into XMetaL? The answer is a qualified "yes" -- it can be done, but if the stuff being dropped is not already plain XML, someone has to write some script to make it happen. (That someone is you, the XMetaL customizer.) The stickiest part of the problem is transforming the dropped data into valid XML. But in addition to that, you need to know the mechanics of processing these user actions in XMetaL. In this webinar we will leave aside the "transformation" part of the problem, and focus on the XMetaL APIs for detecting and handling user drop/paste events and inspecting and accessing the user's data from the clipboard.

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
2,284
On SlideShare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
12
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Dropping content isn't a drag!

  1. 1. in 37 minutes<br />Episode 20<br />Dropping content isn’t a drag!<br />Handling drag & drop (& paste) into XMetaL documents<br />Tom Magliery, XML Technology Specialist<br />7 April 2011<br />Brought to you by XMetaL Technical Services<br />
  2. 2. A common authoring requirement is to allow users to paste or drop content from other applications into XMetaL<br />Via customization (script), you can capture and process content that is being pasted or dropped<br />Note: This talk is for customizers working with non-DITA document types<br />For DITA some of these techniques have already been used to customize XMetaL<br />Introduction<br />
  3. 3. Writing script to handle paste and drop events, and access the clipboard contents<br />Transforming the clipboard contents into valid XML for your doctype<br />We are focused solely on part 1 today.<br />Two-part problem<br />
  4. 4. When you copy something, the source application puts it on the clipboard in one or more formats<br />When you drag something, it will be available as drop data in the same formats<br />Some formats are defined as standard in Windows (e.g., CF_TEXT, CF_UNICODETEXT)<br />Others are defined by the source application (e.g., Adobe Photoshop Image)<br />Some are used by many applications (e.g., HTML Format)<br />Background info<br />
  5. 5. No customization (default XMetaL behavior)<br />Handling dropped/pasted text<br />Handling dropped/pasted other formats<br />Handling dropped files<br />Agenda<br />
  6. 6. XMetaL has some simple handling of drop/paste without any script customization<br />Text or files can be dropped/pasted into XMetaL with certain happy results<br />Part 1: No customization required<br />
  7. 7. If the clipboard object includes a text format:<br />If the text is valid markup that can be pasted at the current location, then it will be pasted as markup<br />Otherwise the full text will be pasted as text<br />Note: There are some strange “in-between” cases that depend on the context of your paste<br />Example 1: No customization required<br />
  8. 8. If the clipboard contains files<br />If any of the file(s) are images, and if your CTM file specifies an image element, then the files that are images will be pasted as image elements<br />Other files are ignored<br />Example 2: No customization required<br />Excerpt from simplepaper.ctm<br />...<br /><Images><br /> <Image><br /> <Name>Image</Name><br /> <Source-Attribute>href</Source-Attribute><br /> <Height-Attribute>height</Height-Attribute><br /> <Width-Attribute>width</Width-Attribute><br /> </Image><br /></Images><br />...<br />
  9. 9. Key event macro: On_Document_Before_DropText<br />Called immediately before the drop/paste is performed<br />Use script in the macro to manipulate the clipboard contents and drop/paste location<br />After this macro finishes, the drop/paste is performed<br />Part 2: Plain text<br />
  10. 10. ActiveDocument.DropClipboardText<br />Boolean property, returns true if the action is a paste; false if it is a drop<br />When text is being pasted<br />Application.Clipboard<br />Contains other properties and methods for accessing the clipboard<br />Application.Clipboard.Text<br />The text contents of the clipboard<br />Read/write property<br />Useful APIs in On_Document_Before_DropText<br />
  11. 11. When text is being dropped<br />ActiveDocument.DropText<br />The text being dropped<br />Read/write property<br />ActiveDocument.DropPoint<br />A Range object representing the location at which the text is being dropped/pasted<br />Read-only property<br />If a different drop location is desired, use Application.MoveDropPoint(range)<br />More useful APIs in On_Document_Before_DropText<br />
  12. 12. Example 3: On_Document_Before_DropText<br /><MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[<br />varmsg = "On_Document_Before_DropText";<br />if (ActiveDocument.DropClipboardText)<br />{<br />msg += "...pasting";<br />msg += "nnClipboard text is:nn" + Application.Clipboard.Text;<br />msg += "nnBeing pasted inside "; <br />} <br />else<br />{<br />msg += "...dropping";<br />msg += "nnDroptext is:nn" + ActiveDocument.DropText;<br />msg += "nnBeing dropped inside "; <br />}<br />varrng = ActiveDocument.DropPoint;<br />msg += "<" + rng.ContainerName + "> element.";<br />Application.Alert(msg);<br />]]></MACRO><br />
  13. 13. Example 3: On_Document_Before_DropText<br />Determine whether this is a drop or a paste<br /><MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[<br />varmsg = "On_Document_Before_DropText";<br />if (ActiveDocument.DropClipboardText)<br />{<br />msg += "...pasting";<br />msg += "nnClipboard text is:nn" + Application.Clipboard.Text;<br />msg += "nnBeing pasted inside "; <br />} <br />else<br />{<br />msg += "...dropping";<br />msg += "nnDroptext is:nn" + ActiveDocument.DropText;<br />msg += "nnBeing dropped inside "; <br />}<br />varrng = ActiveDocument.DropPoint;<br />msg += "<" + rng.ContainerName + "> element.";<br />Application.Alert(msg);<br />]]></MACRO><br />If pasting, access the Clipboard text<br />If dropping, access the DropText<br />Find out where the text is being dropped/pasted<br />
  14. 14. Suppose there is a clipboard format that you know how to process into markup of your type<br />“Declare” that format type in XMetaL and give it your own name<br />Application.AcceptDropFormat("HTML Format", “MyHTML");<br />Write an event macro matching your name<br /><MACRO name="On_Drop_MyHTML" hide="true" lang="JScript"><br />Drop/paste contents are available as a “DataObject”<br />Part 3: Other formats<br />
  15. 15. Example 4: Handling “HTML Format”<br /><MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[<br />Application.AcceptDropFormat("HTML Format", "MyHTML");<br />]]></MACRO><br />
  16. 16. Example 4: Handling “HTML Format”<br /><MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[<br />Application.AcceptDropFormat("HTML Format", "MyHTML");<br />]]></MACRO><br />Tells XMetaL to watch out for “HTML Format” and that our internal name is “MyHTML”<br />
  17. 17. Example 4 continued: Handling “HTML Format”<br /><MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[<br />varmsg = "On_Drop_MyHTML";<br />if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject)<br />{<br />msg += " ... pasting";<br />}<br />else<br />{<br />msg += " ... dropping";<br />}<br />msg += "nnContent to be pasted/dropped is:nn";<br />var data = ActiveDocument.DropDataObject;<br />msg += ActiveDocument.DataObjectAsText("HTML Format", data);<br />Application.Alert(msg);<br />]]></MACRO><br />
  18. 18. Example 4 continued: Handling “HTML Format”<br />Event macro name matches our internal name “MyHTML”<br /><MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[<br />varmsg = "On_Drop_MyHTML";<br />if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject)<br />{<br />msg += " ... pasting";<br />}<br />else<br />{<br />msg += " ... dropping";<br />}<br />msg += "nnContent to be pasted/dropped is:nn";<br />var data = ActiveDocument.DropDataObject;<br />msg += ActiveDocument.DataObjectAsText("HTML Format", data);<br />Application.Alert(msg);<br />]]></MACRO><br />How to test whether this is a drop or a paste<br />Get the text version of this HTML content (will include the tags)<br />
  19. 19. You can include handlers for as many clipboard formats as you wish<br />Example 5: Handling “Adobe Photoshop Image”<br /><MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[<br />Application.AcceptDropFormat("HTML Format", "MyHTML"); <br />Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop");<br />]]></MACRO><br />
  20. 20. You can include handlers for as many clipboard formats as you wish<br />Example 5: Handling “Adobe Photoshop Image”<br /><MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[<br />Application.AcceptDropFormat("HTML Format", "MyHTML"); <br />Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop");<br />]]></MACRO><br />Same idea aswith “HTML Format”<br />
  21. 21. Example 5 continued: Handling “Adobe Photoshop Image”<br /><MACRO name="On_Drop_MyPhotoshop" hide="false" lang="JScript"><![CDATA[<br />Application.Alert("You pasted an image from Photoshop!");<br />]]></MACRO><br />
  22. 22. Example 5 continued: Handling “Adobe Photoshop Image”<br /><MACRO name="On_Drop_MyPhotoshop" hide="false" lang="JScript"><![CDATA[<br />Application.Alert("You pasted an image from Photoshop!");<br />]]></MACRO><br />Not much of a “handler” at all, really :-o<br />
  23. 23. Key event macro:On_Drop_Files<br />Called if files are dropped into the editor<br />Replaces built-in behavior<br />(Contrast with On_Document_Before_DropText)<br />Use Application.DropFileCount and Application.DropFileName properties<br />Can get basic drop behavior on individual files with Selection.DropFile<br />Part 4: Dropping files<br />
  24. 24. Example 6: Handling dropped files<br /><MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[<br />vardp = Application.DropPoint;<br />if (dp.ContainerName == "Para") <br />{<br /> for (vari=1; i<=Application.DropFileCount; i++) {<br />Application.Alert(Application.DropFileName(i));<br />dp.DropFile(Application.DropFileName(i));<br /> }<br />}<br />]]></MACRO><br />
  25. 25. Example 6: Handling dropped files<br />Just for demo purposes we’ll do something only if we drop into a <Para><br />Returns a Range which represents the drop location<br /><MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[<br />vardp = Application.DropPoint;<br />if (dp.ContainerName == "Para") <br />{<br /> for (vari=1; i<=Application.DropFileCount; i++) {<br />Application.Alert(Application.DropFileName(i));<br />dp.DropFile(Application.DropFileName(i));<br /> }<br />}<br />]]></MACRO><br />For each file, display the filename and then do a regular “drop”<br />
  26. 26. On_Document_After_DropText<br />Event macro for performing operations after the drop/paste has occurred<br />Application.DropRange<br />Property returns a range that contains the dropped/pasted content<br />On_Drag_Over_MyFormatName<br />Event macro that fires while dragging content that matches a particular format<br />ActiveDocument.DropNotAllowed();<br />Sets the “drop not allowed” cursor (use after inspecting DropPoint during drag-over)<br />Handling DropFiles in the workspace (i.e., not in a document)<br />Further reading<br />
  27. 27. XMetaL Community Forums<br />http://forums.xmetal.com/<br />JustSystems Partner Center<br />http://justpartnercenter.com/<br />Ask us for help (partner tech support)<br />partnersupport-na@justsystems.com<br />Resources<br />
  28. 28. Thank you for attending!<br />Q&A<br />

×