Improve the Doxygen documentation for clipboard.h; make the return value of widgetSetClipboardText on OS X mean something.

git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@5893 4a71c877-e1ca-e34f-864e-861f7616d084

lib/betawidget/clipboard.h

@@ -25,7 +25,8 @@
 
 /**
  * Returns a copy of the text in the systems clipboard. Should the clipboard be
- * empty, or populated with non-textual data NULL is returned.
+ * empty, or populated with non-textual data NULL is returned. The character set
+ * of the returned is guaranteed to be UTF-8.
  *
  * It remains the responsibility of the caller to free() the string when finished
  * with it.
@@ -35,8 +36,10 @@
 char *widgetGetClipboardText(void);
 
 /**
- * Attempts to set the contents of the systems clipboard to text.
+ * Attempts to set the contents of the systems clipboard to text. The character
+ * set of text must be UTF-8.
  *
+ * @param text  The UTF-8 text to set the clipboard to.
  * @return True if the contents were successfully set, false otherwise.
  */
 bool widgetSetClipboardText(const char *text);

lib/betawidget/platform/sdl/clipboardOSX.m

@@ -54,7 +54,7 @@ char *widgetGetClipboardText()
 }
 
 bool widgetSetClipboardText(const char *text)
-{
+{	
 	NSPasteboard *pasteboard = [NSPasteboard generalPasteboard];
 	
 	// We are willing to provide an NSString representation only
@@ -63,16 +63,19 @@ bool widgetSetClipboardText(const char *text)
 	// Convert text to an NSString instance
 	NSString *copyText = [[NSString alloc] initWithUTF8String:text];
 	
+	// Return status
+	bool ret;
+	
 	// Register the data types we are willing to provide
 	[pasteboard declareTypes:types owner:nil];
 	
 	// Set the pasteboard text
-	[pasteboard setString:copyText forType:NSStringPboardType];
+	ret = [pasteboard setString:copyText forType:NSStringPboardType];
 	
 	// Clean-up
 	[copyText release];
 	[pasteboard release];
 	[types release];
 	
-	return true;
+	return ret;
 }