Documentation: detail ownership of the image data when pasting from an image-containing clipboard.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11714 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 9 insertions, 4 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index b14d57abe..e325a0454 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -899,17 +899,22 @@ int main() {
   time in the future if the clipboard does contain data of the requested type. During processing of this event,
   and if \p type is Fl::clipboard_plain_text, the text data from the specified \p source are in Fl::event_text()
   with UTF-8 encoding, and the number of bytes in Fl::event_length();
-  if \p type is Fl::clipboard_image, Fl::event_clipboard() returns a pointer to the
-  image data, as an Fl_RGB_Image *.
+  if \p type is Fl::clipboard_image, the pointer returned by Fl::event_clipboard() can be safely cast to 
+  type Fl_RGB_Image * to obtain a pointer to the pasted image.
+   
   The receiver
   should be prepared to be called \e directly by this, or for
   it to happen \e later, or possibly <i>not at all</i>.  This
   allows the window system to take as long as necessary to retrieve
   the paste buffer (or even to screw up completely) without complex
   and error-prone synchronization code in FLTK.
+  
+  If an image is being pasted, and if the handle function of \p receiver returns 1,
+  \p receiver gets the ownership of the image which should be deleted after use. Conversely,
+  if it returns 0, the image cannot be used.
    
-  The selection buffer is used for middle-mouse pastes and for 
-  drag-and-drop selections. The clipboard is used for traditional 
+  The selection buffer (\p source is 0) is used for middle-mouse pastes and for
+  drag-and-drop selections. The clipboard (\p source is 1) is used for
   copy/cut/paste operations.
    
    \par Platform details for image data: