From 912d3f7690525e4c2124f03c5f8d129d17c33001 Mon Sep 17 00:00:00 2001 From: Michael Drake Date: Sat, 5 Jan 2013 15:15:23 +0000 Subject: Put exported function comments in header. --- desktop/textarea.c | 113 ++++++++--------------------------------------------- desktop/textarea.h | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 97 deletions(-) (limited to 'desktop') diff --git a/desktop/textarea.c b/desktop/textarea.c index 8743c85d7..92fb02c9e 100644 --- a/desktop/textarea.c +++ b/desktop/textarea.c @@ -125,20 +125,8 @@ static bool textarea_select_fragment(struct textarea *ta); static void textarea_normalise_text(struct textarea *ta, unsigned int b_start, unsigned int b_len); -/** - * Create a text area - * - * \param x X coordinate of left border - * \param y Y coordinate of top border - * \param width width of the text area - * \param height width of the text area - * \param flags text area flags - * \param style font style - * \param redraw_start_callback will be called when textarea wants to redraw - * \param redraw_end_callback will be called when textarea finisjes redrawing - * \param data user specified data which will be passed to redraw callbacks - * \return Opaque handle for textarea or 0 on error - */ + +/* exported interface, documented in textarea.h */ struct textarea *textarea_create(int width, int height, textarea_flags flags, const plot_font_style_t *style, textarea_redraw_request_callback redraw_request, void *data) @@ -194,11 +182,8 @@ struct textarea *textarea_create(int width, int height, } -/** - * Destroy a text area - * - * \param ta Text area to destroy - */ + +/* exported interface, documented in textarea.h */ void textarea_destroy(struct textarea *ta) { free(ta->text); @@ -207,13 +192,7 @@ void textarea_destroy(struct textarea *ta) } -/** - * Set the text in a text area, discarding any current text - * - * \param ta Text area - * \param text UTF-8 text to set text area's contents to - * \return true on success, false on memory exhaustion - */ +/* exported interface, documented in textarea.h */ bool textarea_set_text(struct textarea *ta, const char *text) { unsigned int len = strlen(text) + 1; @@ -238,15 +217,7 @@ bool textarea_set_text(struct textarea *ta, const char *text) } -/** - * Extract the text from a text area - * - * \param ta Text area - * \param buf Pointer to buffer to receive data, or NULL - * to read length required - * \param len Length (bytes) of buffer pointed to by buf, or 0 to read length - * \return Length (bytes) written/required or -1 on error - */ +/* exported interface, documented in textarea.h */ int textarea_get_text(struct textarea *ta, char *buf, unsigned int len) { if (buf == NULL && len == 0) { @@ -391,14 +362,7 @@ bool textarea_replace_text(struct textarea *ta, unsigned int start, } -/** - * Set the caret's position - * - * \param ta Text area - * \param caret 0-based character index to place caret at, -1 removes - * the caret - * \return true on success false otherwise - */ +/* exported interface, documented in textarea.h */ bool textarea_set_caret(struct textarea *ta, int caret) { unsigned int c_len; @@ -605,12 +569,7 @@ bool textarea_set_caret_xy(struct textarea *ta, int x, int y) } -/** - * Get the caret's position - * - * \param ta Text area - * \return 0-based character index of caret location, or -1 on error - */ +/* exported interface, documented in textarea.h */ int textarea_get_caret(struct textarea *ta) { unsigned int c_off = 0, b_off; @@ -730,16 +689,7 @@ bool textarea_reflow(struct textarea *ta, unsigned int line) } -/** - * Handle redraw requests for text areas - * - * \param redraw Redraw request block - * \param x0 left X coordinate of redraw area - * \param y0 top Y coordinate of redraw area - * \param x1 right X coordinate of redraw area - * \param y1 bottom Y coordinate of redraw area - * \param ctx current redraw context - */ +/* exported interface, documented in textarea.h */ void textarea_redraw(struct textarea *ta, int x, int y, const struct rect *clip, const struct redraw_context *ctx) { @@ -927,13 +877,8 @@ void textarea_redraw(struct textarea *ta, int x, int y, } } -/** - * 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. - */ + +/* exported interface, documented in textarea.h */ bool textarea_keypress(struct textarea *ta, uint32_t key) { char utf8[6]; @@ -1311,15 +1256,7 @@ bool textarea_scroll_visible(struct textarea *ta) } -/** - * Handles all kinds of mouse action - * - * \param ta Text area - * \param mouse the mouse state at action moment - * \param x X coordinate - * \param y Y coordinate - * \return true if action was handled false otherwise - */ +/* exported interface, documented in textarea.h */ bool textarea_mouse_action(struct textarea *ta, browser_mouse_state mouse, int x, int y) { @@ -1358,15 +1295,7 @@ bool textarea_mouse_action(struct textarea *ta, browser_mouse_state mouse, } -/** - * Handles the end of a drag operation - * - * \param ta Text area - * \param mouse the mouse state at drag end moment - * \param x X coordinate - * \param y Y coordinate - * \return true if drag end was handled false otherwise - */ +/* exported interface, documented in textarea.h */ bool textarea_drag_end(struct textarea *ta, browser_mouse_state mouse, int x, int y) { @@ -1504,12 +1433,7 @@ void textarea_normalise_text(struct textarea *ta, } -/** - * Gets the dimensions of a textarea - * - * \param width if not NULL, gets updated to the width of the textarea - * \param height if not NULL, gets updated to the height of the textarea - */ +/* exported interface, documented in textarea.h */ void textarea_get_dimensions(struct textarea *ta, int *width, int *height) { if (width != NULL) @@ -1518,13 +1442,8 @@ void textarea_get_dimensions(struct textarea *ta, int *width, int *height) *height = ta->vis_height; } -/** - * Set the dimensions of a textarea, causing a reflow and - * emitting a redraw request. - * - * \param width the new width of the textarea - * \param height the new height of the textarea - */ + +/* exported interface, documented in textarea.h */ void textarea_set_dimensions(struct textarea *ta, int width, int height) { ta->vis_width = width; diff --git a/desktop/textarea.h b/desktop/textarea.h index 275acdc4f..b24c20fb4 100644 --- a/desktop/textarea.h +++ b/desktop/textarea.h @@ -42,22 +42,130 @@ struct textarea; typedef void(*textarea_redraw_request_callback)(void *data, int x, int y, int width, int height); +/** + * Create a text area + * + * \param x X coordinate of left border + * \param y Y coordinate of top border + * \param width width of the text area + * \param height width of the text area + * \param flags text area flags + * \param style font style + * \param redraw_start_callback will be called when textarea wants to redraw + * \param redraw_end_callback will be called when textarea finisjes redrawing + * \param data user specified data which will be passed to redraw callbacks + * \return Opaque handle for textarea or 0 on error + */ struct textarea *textarea_create(int width, int height, textarea_flags flags, const plot_font_style_t *style, textarea_redraw_request_callback redraw_request, void *data); + +/** + * Destroy a text area + * + * \param ta Text area to destroy + */ void textarea_destroy(struct textarea *ta); + +/** + * Set the text in a text area, discarding any current text + * + * \param ta Text area + * \param text UTF-8 text to set text area's contents to + * \return true on success, false on memory exhaustion + */ bool textarea_set_text(struct textarea *ta, const char *text); + +/** + * Extract the text from a text area + * + * \param ta Text area + * \param buf Pointer to buffer to receive data, or NULL + * to read length required + * \param len Length (bytes) of buffer pointed to by buf, or 0 to read length + * \return Length (bytes) written/required or -1 on error + */ 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 + * \return true on success false otherwise + */ bool textarea_set_caret(struct textarea *ta, int caret); + +/** + * Get the caret's position + * + * \param ta Text area + * \return 0-based character index of caret location, or -1 on error + */ int textarea_get_caret(struct textarea *ta); + +/** + * Handle redraw requests for text areas + * + * \param redraw Redraw request block + * \param x0 left X coordinate of redraw area + * \param y0 top Y coordinate of redraw area + * \param x1 right X coordinate of redraw area + * \param y1 bottom Y coordinate of redraw area + * \param ctx current redraw context + */ void textarea_redraw(struct textarea *ta, int x, int y, 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. + */ bool textarea_keypress(struct textarea *ta, uint32_t key); + +/** + * Handles all kinds of mouse action + * + * \param ta Text area + * \param mouse the mouse state at action moment + * \param x X coordinate + * \param y Y coordinate + * \return true if action was handled false otherwise + */ bool textarea_mouse_action(struct textarea *ta, browser_mouse_state mouse, int x, int y); + +/** + * Handles the end of a drag operation + * + * \param ta Text area + * \param mouse the mouse state at drag end moment + * \param x X coordinate + * \param y Y coordinate + * \return true if drag end was handled false otherwise + */ bool textarea_drag_end(struct textarea *ta, browser_mouse_state mouse, int x, int y); + +/** + * Gets the dimensions of a textarea + * + * \param width if not NULL, gets updated to the width of the textarea + * \param height if not NULL, gets updated to the height of the textarea + */ void textarea_get_dimensions(struct textarea *ta, int *width, int *height); + +/** + * Set the dimensions of a textarea, causing a reflow and + * emitting a redraw request. + * + * \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); #endif -- cgit v1.2.3