Posted on by

pasteboardA common requirement for business app developers is the ability to copy and paste items — in specific, the ability to select something from your app and paste it into another, or copy something from another app and paste it into yours.

Corona’s native text objects native.newTextField() and native.newTextBox() already support copying and pasting text using the operating system’s methods, but because normal text displayed via display.newText() is rendered into a graphical object, you couldn’t select those characters and copy them elsewhere, until now.

Pasteboard Plugin

For Corona Pro and Enterprise subscribers using iOS, you can now use the pasteboard plugin to provide some copy/paste features in your app. To get started, simply include the plugin in your build.settings file:

settings = 
{
   plugins =
   {
      -- key is the name passed to Lua's 'require()'
      ["plugin.pasteboard"] =
      {
         -- required
         publisherId = "com.coronalabs",
         supportedPlatforms = { iphone = true },
      },
   },
}

Next, in main.lua or other modules where you want to use this feature, require the plugin as follows:

local pasteboard = require( "plugin.pasteboard" )

Selecting and Copying

The pasteboard plugin can be used to bring in data from other apps, or provide data to other apps. Using it, you have the option of selecting:

  • an image
  • a string
  • a URL

Selecting objects in Corona-based apps is not done in the same way as a web browser or text editor, since it’s primarily rendered graphics/objects. You cannot simply touch an area of the screen, drag “select handles” around something, and gather the contents. Instead, you must program some method which allows the object to be selected, like a button or a touch handler upon the object. You could also change the object visually, for example, invert its color using the invert filter. In the following simple example, if the user touches the text object, you invert the color and copy the value of that text object (its string) to the pasteboard using the pasteboard.copy() API:

local function selectMe( event )
   if ( event.phase == "ended" ) then
      event.target.fill.effect = "filter.invert"
      pasteboard.copy( "string", event.target.text )
   end
   return true
end

local myString = display.newText( "Hello World", 0, 0, "Helvetica", 32 )
myString:setFillColor( 1,0,0 )

myString:addEventListener( "touch", selectMe )

To copy an image, use the copy function with the copyType parameter set to "image":

pasteboard.copy( "image", filename, baseDirectory )

For a URL, follow the "string" model, but specify "url" instead:

pasteboard.copy( "url", "http://coronalabs.com" )

You could even present a series of images, each with an associated URL, and when the user touches the image, it copies a URL instead. The potential options are considerable!

Pasting Content Into Your App

Getting data from other apps is useful as well. As noted above, native objects like native.newTextField() and native.newTextBox() already support pasting of text copied from other sources. To paste content into other aspects of your app, you’ll need a paste handler function and a way to invoke it. Consider this code:

local textField = display.newText( "", display.contentCenterX, 100, "Helvetica", 32 )
local pastedImage = nil

-- Callback function for the paste method
local function onPaste( event )
   print( "event name:", event.name )
   print( "event type:", event.type )
   print( "Pasting a/an ", pasteboard.getType() )

   -- Paste an image
   if ( event.filename ) then
      pastedImage = display.newImageRect( event.filename, event.baseDir, 80, 80 )
      pastedImage.x = display.contentCenterX
      pastedImage.y = 200
   end

   -- Paste a string
   if ( event.string ) then
      -- Update the textfield's text
      textField.text = event.string
   end

   -- Paste a URL
   if ( event.url ) then
      -- Update the textfield's text
      textField.text = event.url
   end
end

pasteboard.paste( onPaste )

In this block of code, we set up two objects to handle the pasted-in values: an image called pastedImage and a text object called textField. Then, based on the type of content being pasted in, the object is filled/updated accordingly.

Other Routines

You can limit the types of items being pasted in by calling:

pasteboard.setAllowedTypes( { "url", "string", "image" } )

If you only want to allow strings, include just the "string" entry in the array.

You can also determine the type of data currently on the pasteboard:

local pType = pasteboard.getType()
print( "Data type on the pasteboard is:", pType )

Finally, you can empty the pasteboard by calling the clear() API:

pasteboard.clear()

Limitations

At time of this writing, the pasteboard plugin is in a beta test state, and it’s currently only available on iOS to Corona Pro or Enterprise subscribers. You must also build the app for an actual device to test your pasteboard functionality. We encourage you to experiment with the plugin and provide your feedback below.


Posted by . Thanks for reading...

3 Responses to “Tutorial: Introducing the Pasteboard Plugin (iOS)”

  1. Greg

    would be very useful to be able to test on the simulator – will this be the case in the 1.0 version? or is there some constraint with the plugin’s approach that prevents this?

    Reply
    • Rob Miracle

      There probably isn’t an OS-X equivalent to the iOS SDK we are using. Obviously OS-X supports the concepts of copy/paste, but the underling architecture for it could be drastically different.

      Rob

      Reply

Leave a Reply

  • (Will Not Be Published)