Index of /xtras/clipboard_xtra/win

Icon  Name                         Last modified      Size  Description
[PARENTDIR] Parent Directory                                  -   
[   ] clipboard_xtra_win_v0.10.zip 2017-04-15 23:46  2.1M  
[TXT] readme.txt                   2017-04-14 21:48  8.2K  

-- xtra Clipboard
-- v0.10 (c) 2017 Valentin Schmidt

Clipboard Xtra is a cross-platform scripting xtra for director that allows to
access the system's clipboard. It provides more opportunities than director's own
copyToClipBoard/pasteClipBoardInto commands.

Here some examples of what it can be used for (see demo.dir):

- check the formats available in clipboard
- paste formatted text from other applications (word, browser, ...) to
  projectors.
- copy formatted text from projectors to other applications (Word, browser, ...)
- copy shapes from Illustrator, Freehand, Fireworks, Photoshop or After Effects
  and paste them to Director as Vector Shape-members
- export Vector Shapes from Director as Flash movies (SWF files):
- save binary data copied from other applications as files (eg. WAV, BMP, PNG,
  EPS, ...)
- export director text content as Unicode or OEM text-files
  (this can be done by taking advantage of the fact that for all ANSI text
  copied to the clipboard windows automatically adds a OEM and a Unicode-representation.)
- exchange data with Excel:
  - receive data copied from Excel as CSV or XML,
  - copy data from a projector that can directly be pasted to an Excel-sheet


****************************************
METHOD OVERVIEW
****************************************

new object me

-- Formats
clipGetFormatName object me, integer formatNumber
clipGetStandardFormat object me, string standardFormatName  -- win-only
clipRegisterFormatName object me, string formatName -- win-only

-- Current Clipboard
clipGetFormatsInClipboard object me
clipEmptyClipboard object me
clipGetData object me, any intOrStringFormat
clipSetData object me, any intOrStringFormat, any stringOrByteArrayData, *
clipAddData object me, any intOrStringFormat, any stringOrByteArrayData

-- Callback
clipSetCallback object me, symbol cbHandler, *cbTarget  -- win-only
clipStopCallback object me  -- win-only


****************************************
METHODS IN DETAIL
****************************************

########################################
# Formats
########################################

----------------------------------------
clipGetFormatName object me, integer formatNumber -> string|VOID
----------------------------------------

Description:
============
Returns the name of a clipboard format with given format number. For predefined
clipboard Formats (defined in WinUser.h, see list at bottom) the name of the
corresponding constant is returned (eg. "CF_TEXT"), for custom formats the
format string (e.g. "Rich Text Format").
If the format doesn't exist, the function returns VOID.

Example usage:
==============
Use the following code to find the names for all formats currently available in
the clipboard:

  formatList = gCX.clipGetFormats()
  repeat with formatNumber in formatList
    put gCX.clipGetFormatName(formatNumber)
  end repeat


----------------------------------------
clipGetStandardFormat object me, string standardFormatName  -> integer (win-only)
----------------------------------------

Description:
============
Returns the format number for a pre-defined Clipboard format name.
Return value 0 means that an error occured.

Example usage:
==============

  CF_TEXT = gCX.clipGetStandardFormat("CF_TEXT")


----------------------------------------
clipRegisterFormatName object me, string formatName -> integer (win-only)
----------------------------------------

Description:
============
Registers a custom format in the system and returns its format number.
This format number can then be used insstead of the format name in all
get/set/add functions.
If the the format is already registered, its existing format number is returned.
Return value 0 means that an error occured.

Example usage:
==============

  myFormat = gCX.clipRegisterFormatName("Rich Text Format")


########################################
# Current Clipboard
########################################

----------------------------------------
clipGetFormatsInClipboard object me -> list
----------------------------------------

Description:
============
Returns a list of formats currently available in clipboard. The formats are
specified as format numbers which can directly be used for the clipGetData()
method. Use clipGetFormatName() to find the name for a certain format-number.

Example usage:
==============

  formatList = clipGetFormats()


---------------------------------------------------------------
clipEmptyClipboard object me
---------------------------------------------------------------

Description:
============
Empties the clipboard.


---------------------------------------------------------------
clipGetData object me, any intOrStringFormat -> string|bytearray|VOID
---------------------------------------------------------------

Description:
============
Returns content with specified format from clipboard, where format can be either
a format number (integer) or a format name (string) string. If the format is not
available, VOID is returned, else either a string (Director 10-) or a bytearray
(Director 11.5+).

Example usage:
==============

  data = gCX.clipGetData(1) -- get text from clipboard as ANSI text

  CF_TEXT = gCX.clipGetStandardFormat("CF_TEXT")
  data = gCX.clipGetData(CF_TEXT) -- same as clipGetData(1)

  data = gCX.clipGetData("Rich Text Format")


---------------------------------------------------------------
clipSetData object me, any intOrStringFormat, any stringOrByteArrayData, * -> integer
---------------------------------------------------------------

Description:
============
Replaces the contents of the clipboard with the specified data.
You can add multiple formats at once, by passing alternately a format and the
corresponding data.
Format can either either be a format number (integer) or a format name (string).
Data can either be a string or a bytearray.
It's the lingo programmer's responsibility that the format and the data fit
together.
The function returns the number of format/data pairs that were successfully
added to the clipboard.

Example usage:
==============

  -- copy ASCII text as CF_TEXT
  res = gCX.clipSetData(1, member(1).text)

  -- copy formatted text as custom format "Rich Text Format"
  res = gCX.clipSetData("Rich Text Format", member(1).rtf)

  -- copy formatted text both as RTF and HTML to clipboard
  res = gCX.clipSetData("Rich Text Format", member(2).rtf, "HTML Format", member(2).html)


---------------------------------------------------------------
clipAddData object me, any intOrStringFormat, any stringOrByteArrayData -> bool success
---------------------------------------------------------------

Description:
============
Like clipSetData(), but instead of replacing, it adds another format to the
clipboard, keeping its previous contents.

Example usage:
==============

  -- add formatted text as custom format "Rich Text Format"
  res = gCX.clipAddData("Rich Text Format", member(1).rtf)


########################################
# Callback
########################################

---------------------------------------------------------------
clipSetCallback object me, symbol cbHandler, *cbTarget -> bool success (win-only)
---------------------------------------------------------------

Description:
============
Registers a handler as callback for clipboard-change notifications. If no object
is specified as callbackTraget, the handler is expected in a movie script.


---------------------------------------------------------------
clipStopCallback object me (win-only)
---------------------------------------------------------------

Description:
============
Stops the clipboard-change notifications and removes the callback.


***************************************************************
Predefined Clipboard Formats in Windows (defined in WinUser.h)
***************************************************************
1  CF_TEXT
2  CF_BITMAP
3  CF_METAFILEPICT
4  CF_SYLK
5  CF_DIF
6  CF_TIFF
7  CF_OEMTEXT
8  CF_DIB
9  CF_PALETTE
10 CF_PENDATA
11 CF_RIFF
12 CF_WAVE
13 CF_UNICODETEXT
14 CF_ENHMETAFILE
15 CF_HDROP
16 CF_LOCALE
17 CF_DIBV5
18 CF_MAX