Clipboard I/O

Transferring data to / from clipboard


[1]
strX.toClip({#s / #d} {,#localeID} ) string to Clipboard
  Returns strX / <err>
  #s Transfer only SDS data
  #d Transfer only DDS data
  localeID Integer localeID. / 0: don’t set locale / -1 use glbCP's locale <-- check this.
     
  Description Transfers the contents of strX to the clipboard.
Unless #s or #d is passed as the first argument, the Xtra will fill the clipboard with both SDS (CF_TEXT) and DDS (CF_UNICODETEXT) data, by performing any internal conversion required.
It will also set the clipboards to localeID (CF_LOCALE), to localeID, or automatically, according to the string's CP.

The localeID is, in short, a Windows value specifying a country-language pair. By examining the localeID, a Windows app can decide which CodePage to use for SDS, or other country/place dependant data.
If no localeID is passed, the Xtra will use the first localeID that is known to be compatible with the strX.
Otherwise, it will set localeID as the clipboard's localeID.
If the function succeeds, the original strX will be returned. Otherwise, an <err>.
     
  Examples _s("αβγ", 1253).toClip() --transfer Greek characters to the clipboard
_s("αβγ", 1251).toClip() --transfer Cyrillic characters to the clipboard

_d("αβγ", 1253).app("αβγ", 1251).toClip() --transfer a unicode string, containing both Greek and Cyrillic characters to the clipboard.

put _d("αβγ", 1251).toS().toClip(#s) --transfer SDS only Cyrillic text. An application has to use the localeID that is automatically added to the clipboard to properly use the SDS data.
     
  Notes strDs are CP, and therefore localeID independent.
strSs are localeID dependant, but the Xtra will automatically identify a compatible one.
However, even if the localeID is set correctly, certain applications may not examine it in order to identify the correct CP to apply to any SDS data contained in the clipboard. Such applications (Director falls in this category) usually use the Ansi-1252 CP for all text copied from the clipboard.

Windows automatically create the CF_UNICODETEXT when only CF_TEXT data is transferred to the clipboard, and vice versa.

[2]
strX.fromClip() string from Clipboard
  Returns strX / <err>
     
  Description Transfers the contents of strX to the clipboard.
Unless #s or #d is passed as the first argument, the Xtra will fill the clipboard with both SDS (CF_TEXT) and DDS (CF_UNICODETEXT) data, by performing any internal conversion required.
It will also set the clipboards to localeID (CF_LOCALE), to localeID, or automatically, according to the string's CP.

The localeID is, in short, a Windows value specifying a country-language pair. By examining the localeID, a Windows app can decide which CodePage to use for SDS, or other country/place dependant data.
If no localeID is passed, the Xtra will use the first localeID that is known to be compatible with the strX.
Otherwise, it will set localeID as the clipboard's localeID.
If the function succeeds, the original strX will be returned. Otherwise, an <err>.
     
  Examples _sc("834C", 932).toClip(#s) --create the Japanese character '?' and copy it to the clipboard as SDS
s = _s().fromClip()         --now retrieve the SDS data. DDS data will be also available (windows)
put s.pop(), s.cp           --check the result - the popup window should contain the '?' character.
-- ƒL 932                   --result as displayed on a Greek System.

put _s().fromClip()        
-- <xErr 66623 InvalidData>--no compatible data in clipboard. E.g. clipboard containing image data.
     
  Notes  

Non-Xtra related Director clipboard issues

1. A quick test to Director's copy / paste functions:
-- Welcome to Director --
-- αβγ           -- << select and copy (ctrl+c).
s=_s().fromClip()--now import the clipboard data
put s
-- αβγ            --seems ok, doesn't it?
put s.cp 
-- 1252           --but it isn't. The locale isn't set correctly (1252:Western, instead of 1253:Greek).

_s("αβγ").toClip()  --let's try this again, using a xStr.
s=_s().fromClip()
put s, s.cp()
-- αβγ 1253         --yep. that's how it should be.


In the above example, the first string looks ok in Director, but if transferred to an external unicode aware app, it will read as ' áâã'
Why is this happening:
Director transfers simple text to the clipboard, but doesn't set the appropriate locale (always 1252, instead of the system's locale).
Soon as text data is transferred to the clipboard, Windows will create a unicode version of the text, based on the transferred locale.
The locale of the clipboard will be 1252, so, all characters will be treated as Western, and the string will be displayed using characters from the 1252 code page. So, 'αβγ' or 'бвг' will become "áâã". Note that all three string, when stored as a data:codePage pair have identical data values.
So, why Director displays the string correctly?
Simply because it ignores the locale both in and out.
Meaning that if you copy any of the  'αβγ' , 'бвг' or "áâã" strings as plain text from a program that also ignores the locale and paste it to e.g. Director's message window, they will all be displayed as 'αβγ' (for a Greek system).
Since such applications don't really exist (unicode apps transfer unicode text, and non-unicode apps don't support multiple languages) you can try:

-- Welcome to Director --
_s("αβγ", 1251).toClip(#s).pop() --- Transfer Cyrillic text to the clipboard. The .pop() is added just for preview.
αβγ --<< result of pasting the data to the message window ( pressing ctrl+V). Pasting the data to a unicode app will reveal the correct display: бвг

_s("αβγ", 1253).toClip(#s).pop() --Transfer Greek text to the clipboard.
αβγ --<< result of pasting the data to the message window ( pressing ctrl+V )


2. Copying rtf data (e.g. a text member's contents) and pasting it to an app that can read rtf data:
When copying a text member's contents, besides text, Director copies rtf data to the clipboard - non-unicode rtf data.
Pasting the data to a word processor, and long as the font remains unchanged, the text will appear correctly.
By changing the font however, the app will recreate the rtf data, by examining the rtf's contents, and deciding the best font to use for each character. Since the rtf data Director transferred are not unicode, its characters will be treated as Ansi-1252 characters, and any non-Latin characters of the text will be mapped incorrectly.
To fix this, for single language (e.g. Greek, Cyrillic) text you can:
_s(member("myMember").text, myCodePage).toClip() --or:...
_s().fromClip().cp(correctCodePage).toClip()     --...if the text is already copied to the clipboard