Change interface to system colours to allow reporting of errors

Allow system colour interface to report errors instead of silently
failing and propogate the errors. This also fixes teh system colour
documentation.

1 files changed, 100 insertions, 53 deletions

diff --git a/desktop/textarea.h b/desktop/textarea.h
index 65e2594c7..898609730 100644
--- a/desktop/textarea.h
+++ b/desktop/textarea.h
@@ -1,6 +1,6 @@
 /*
  * Copyright 2006 John-Mark Bell <jmb@netsurf-browser.org>
- * Copyright 2009 Paul Blokus <paul_pl@users.sourceforge.net> 
+ * Copyright 2009 Paul Blokus <paul_pl@users.sourceforge.net>
  *
  * This file is part of NetSurf, http://www.netsurf-browser.org/
  *
@@ -17,12 +17,13 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file
- * Single/Multi-line UTF-8 text area (interface)
+/**
+ * \file
+ * Single/Multi-line UTF-8 text area interface
  */
 
-#ifndef _NETSURF_DESKTOP_TEXTAREA_H_
-#define _NETSURF_DESKTOP_TEXTAREA_H_
+#ifndef NETSURF_DESKTOP_TEXTAREA_H
+#define NETSURF_DESKTOP_TEXTAREA_H
 
 #include <stdint.h>
 #include <stdbool.h>
@@ -33,21 +34,31 @@
 struct textarea;
 struct redraw_context;
 
-/* Text area flags */
+/**
+ * Text area flags
+ */
 typedef enum {
-	TEXTAREA_DEFAULT		= (1 << 0),	/**< Standard input */
-	TEXTAREA_MULTILINE		= (1 << 1),	/**< Multiline area */
-	TEXTAREA_READONLY		= (1 << 2),	/**< Non-editable */
-	TEXTAREA_INTERNAL_CARET		= (1 << 3),	/**< Render own caret */
-	TEXTAREA_PASSWORD		= (1 << 4)	/**< Obscured display */
+	TEXTAREA_DEFAULT	= (1 << 0),	/**< Standard input */
+	TEXTAREA_MULTILINE	= (1 << 1),	/**< Multiline area */
+	TEXTAREA_READONLY	= (1 << 2),	/**< Non-editable */
+	TEXTAREA_INTERNAL_CARET	= (1 << 3),	/**< Render own caret */
+	TEXTAREA_PASSWORD	= (1 << 4)	/**< Obscured display */
 } textarea_flags;
 
+
+/**
+ * Textarea drag status
+ */
 typedef enum {
 	TEXTAREA_DRAG_NONE,
 	TEXTAREA_DRAG_SCROLLBAR,
 	TEXTAREA_DRAG_SELECTION
-} textarea_drag_type;			/**< Textarea drag status */
+} textarea_drag_type;
+
 
+/**
+ * textarea message types
+ */
 typedef enum {
 	TEXTAREA_MSG_DRAG_REPORT,	/**< Textarea drag start/end report */
 	TEXTAREA_MSG_SELECTION_REPORT,	/**< Textarea text selection presence */
@@ -56,6 +67,10 @@ typedef enum {
 	TEXTAREA_MSG_TEXT_MODIFIED	/**< Textarea text modified */
 } textarea_msg_type;
 
+
+/**
+ * textarea message
+ */
 struct textarea_msg {
 	struct textarea *ta;		/**< The textarea widget */
 
@@ -73,10 +88,10 @@ struct textarea_msg {
 				TEXTAREA_CARET_HIDE	/**< Hide */
 			} type;
 			struct {
-				int x;			/**< Carret x-coord */
-				int y;			/**< Carret y-coord */
-				int height;		/**< Carret height */
-				struct rect *clip;	/**< Carret clip rect */
+				int x;			/**< Caret x-coord */
+				int y;			/**< Caret y-coord */
+				int height;		/**< Caret height */
+				struct rect *clip;	/**< Caret clip rect */
 			} pos;			/**< With _CARET_SET_POS */
 		} caret;			/**< With _CARET_UPDATE */
 		struct {
@@ -86,6 +101,10 @@ struct textarea_msg {
 	} data;				/**< Depends on msg type */
 };
 
+
+/**
+ * textarea setup parameters
+ */
 typedef struct textarea_setup {
 	int width;		/**< Textarea width */
 	int height;		/**< Textarea height */
@@ -104,14 +123,39 @@ typedef struct textarea_setup {
 
 } textarea_setup;
 
+
+/**
+ * Text area mouse input status flags
+ */
+typedef enum {
+	TEXTAREA_MOUSE_NONE	= 0,		/**< Not relevant */
+	TEXTAREA_MOUSE_USED	= (1 <<  0),	/**< Took action with input */
+	TEXTAREA_MOUSE_EDITOR	= (1 <<  1),	/**< Hover: caret pointer */
+	TEXTAREA_MOUSE_SELECTION= (1 <<  2),	/**< Hover: selection */
+	TEXTAREA_MOUSE_SCR_USED	= (1 <<  3),	/**< Scrollbar action */
+	TEXTAREA_MOUSE_SCR_BOTH	= (1 <<  4),	/**< Scrolling both bars */
+	TEXTAREA_MOUSE_SCR_UP	= (1 <<  5),	/**< Hover: scroll up */
+	TEXTAREA_MOUSE_SCR_PUP	= (1 <<  6),	/**< Hover: scroll page up */
+	TEXTAREA_MOUSE_SCR_VRT	= (1 <<  7),	/**< Hover: vert. drag bar */
+	TEXTAREA_MOUSE_SCR_PDWN	= (1 <<  8),	/**< Hover: scroll page down */
+	TEXTAREA_MOUSE_SCR_DWN	= (1 <<  9),	/**< Hover: scroll down */
+	TEXTAREA_MOUSE_SCR_LFT	= (1 << 10),	/**< Hover: scroll left */
+	TEXTAREA_MOUSE_SCR_PLFT	= (1 << 11),	/**< Hover: scroll page left */
+	TEXTAREA_MOUSE_SCR_HRZ	= (1 << 12),	/**< Hover: horiz. drag bar */
+	TEXTAREA_MOUSE_SCR_PRGT	= (1 << 13),	/**< Hover: scroll page right */
+	TEXTAREA_MOUSE_SCR_RGT	= (1 << 14)	/**< Hover: scroll right */
+} textarea_mouse_status;
+
+
 /**
  * Client callback for the textarea
  *
- * \param data		user data passed at textarea creation
- * \param textarea_msg	textarea message data
+ * \param data user data passed at textarea creation
+ * \param msg textarea message data
  */
 typedef void(*textarea_client_callback)(void *data, struct textarea_msg *msg);
 
+
 /**
  * Create a text area.
  *
@@ -125,6 +169,7 @@ struct textarea *textarea_create(const textarea_flags flags,
 		const textarea_setup *setup,
 		textarea_client_callback callback, void *data);
 
+
 /**
  * Destroy a text area
  *
@@ -132,6 +177,7 @@ struct textarea *textarea_create(const textarea_flags flags,
  */
 void textarea_destroy(struct textarea *ta);
 
+
 /**
  * Set the text in a text area, discarding any current text
  *
@@ -141,6 +187,7 @@ void textarea_destroy(struct textarea *ta);
  */
 bool textarea_set_text(struct textarea *ta, const char *text);
 
+
 /**
  * Insert the text in a text area at the caret, replacing any selection.
  *
@@ -152,6 +199,7 @@ bool textarea_set_text(struct textarea *ta, const char *text);
 bool textarea_drop_text(struct textarea *ta, const char *text,
 		size_t text_length);
 
+
 /**
  * Extract the text from a text area
  *
@@ -163,16 +211,18 @@ bool textarea_drop_text(struct textarea *ta, const char *text,
  */
 int textarea_get_text(struct textarea *ta, char *buf, unsigned int len);
 
+
 /**
  * Set the caret's position
  *
- * \param ta 		Text area
- * \param caret 	0-based character index to place caret at, -1 removes
- * 			the caret
+ * \param ta	Text area
+ * \param caret 0-based character index to place caret at, -1 removes
+ *		  the caret
  * \return true on success false otherwise
  */
 bool textarea_set_caret(struct textarea *ta, int caret);
 
+
 /**
  * Handle redraw requests for text areas
  *
@@ -187,34 +237,16 @@ bool textarea_set_caret(struct textarea *ta, int caret);
 void textarea_redraw(struct textarea *ta, int x, int y, colour bg, float scale,
 		const struct rect *clip, const struct redraw_context *ctx);
 
+
 /**
  * Key press handling for text areas.
  *
  * \param ta	The text area which got the keypress
  * \param key	The ucs4 character codepoint
- * \return     	true if the keypress is dealt with, false otherwise.
+ * \return	true if the keypress is dealt with, false otherwise.
  */
 bool textarea_keypress(struct textarea *ta, uint32_t key);
 
-/* Text area mouse input status flags */
-typedef enum {
-	TEXTAREA_MOUSE_NONE	= 0,		/**< Not relevant */
-	TEXTAREA_MOUSE_USED	= (1 <<  0),	/**< Took action with input */
-	TEXTAREA_MOUSE_EDITOR	= (1 <<  1),	/**< Hover: caret pointer */
-	TEXTAREA_MOUSE_SELECTION= (1 <<  2),	/**< Hover: selection */
-	TEXTAREA_MOUSE_SCR_USED	= (1 <<  3),	/**< Scrollbar action */
-	TEXTAREA_MOUSE_SCR_BOTH	= (1 <<  4),	/**< Scrolling both bars */
-	TEXTAREA_MOUSE_SCR_UP	= (1 <<  5),	/**< Hover: scroll up */
-	TEXTAREA_MOUSE_SCR_PUP	= (1 <<  6),	/**< Hover: scroll page up */
-	TEXTAREA_MOUSE_SCR_VRT	= (1 <<  7),	/**< Hover: vert. drag bar */
-	TEXTAREA_MOUSE_SCR_PDWN	= (1 <<  8),	/**< Hover: scroll page down */
-	TEXTAREA_MOUSE_SCR_DWN	= (1 <<  9),	/**< Hover: scroll down */
-	TEXTAREA_MOUSE_SCR_LFT	= (1 << 10),	/**< Hover: scroll left */
-	TEXTAREA_MOUSE_SCR_PLFT	= (1 << 11),	/**< Hover: scroll page left */
-	TEXTAREA_MOUSE_SCR_HRZ	= (1 << 12),	/**< Hover: horiz. drag bar */
-	TEXTAREA_MOUSE_SCR_PRGT	= (1 << 13),	/**< Hover: scroll page right */
-	TEXTAREA_MOUSE_SCR_RGT	= (1 << 14)	/**< Hover: scroll right */
-} textarea_mouse_status;
 
 /**
  * Handles all kinds of mouse action
@@ -228,22 +260,28 @@ typedef enum {
 textarea_mouse_status textarea_mouse_action(struct textarea *ta,
 		browser_mouse_state mouse, int x, int y);
 
+
 /**
  * Clear any selection in the textarea.
  *
- * \param ta	textarea widget
+ * \param ta textarea widget
  * \return true if there was a selection to clear, false otherwise
  */
 bool textarea_clear_selection(struct textarea *ta);
 
+
 /**
- * Get selected text, ownership passed to caller, which needs to free() it.
+ * Get selected text.
+ *
+ * ownership of the returned string is passed to caller which needs to
+ *  free it.
  *
- * \param ta  Textarea widget
+ * \param ta Textarea widget
  * \return Selected text, or NULL if none.
  */
 char *textarea_get_selection(struct textarea *ta);
 
+
 /**
  * Gets the dimensions of a textarea
  *
@@ -253,22 +291,28 @@ char *textarea_get_selection(struct textarea *ta);
  */
 void textarea_get_dimensions(struct textarea *ta, int *width, int *height);
 
+
 /**
- * Set the dimensions of a textarea, causing a reflow and
- * Does not emit a redraw request.  Up to client to call textarea_redraw.
+ * Set the dimensions of a textarea.
+ *
+ * This causes a reflow of the text and does not emit a redraw
+ * request.  Up to client to call textarea_redraw.
  *
  * \param ta		textarea widget
- * \param width 	the new width of the textarea
+ * \param width		the new width of the textarea
  * \param height	the new height of the textarea
  */
 void textarea_set_dimensions(struct textarea *ta, int width, int height);
 
+
 /**
- * Set the dimensions and padding of a textarea, causing a reflow.
- * Does not emit a redraw request.  Up to client to call textarea_redraw.
+ * Set the dimensions and padding of a textarea.
+ *
+ * This causes a reflow of the text. Does not emit a redraw request.
+ * Up to client to call textarea_redraw.
  *
  * \param ta		textarea widget
- * \param width 	the new width of the textarea
+ * \param width		the new width of the textarea
  * \param height	the new height of the textarea
  * \param top		the new top padding of the textarea
  * \param right		the new right padding of the textarea
@@ -278,9 +322,12 @@ void textarea_set_dimensions(struct textarea *ta, int width, int height);
 void textarea_set_layout(struct textarea *ta, int width, int height,
 		int top, int right, int bottom, int left);
 
+
 /**
- * Scroll a textarea by an amount.  Only does anything if multi-line textarea
- * has scrollbars.  If it scrolls, it will emit a redraw request.
+ * Scroll a textarea by an amount.
+ *
+ * Only does anything if multi-line textarea has scrollbars.  If it
+ * scrolls, it will emit a redraw request.
  *
  * \param ta	textarea widget
  * \param scrx	number of px try to scroll in x direction
@@ -288,5 +335,5 @@ void textarea_set_layout(struct textarea *ta, int width, int height,
  * \return true iff the textarea was scrolled
  */
 bool textarea_scroll(struct textarea *ta, int scrx, int scry);
-#endif
 
+#endif