textarea.h

Go to the documentation of this file.

/*
 * Copyright 2006 John-Mark Bell <jmb@netsurf-browser.org>
 * Copyright 2009 Paul Blokus <paul_pl@users.sourceforge.net>
 *
 * This file is part of NetSurf, http://www.netsurf-browser.org/
 *
 * NetSurf is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2 of the License.
 *
 * NetSurf is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
/**
 * \file
 * Single/Multi-line UTF-8 text area interface
 */
 
#ifndef NETSURF_DESKTOP_TEXTAREA_H
#define NETSURF_DESKTOP_TEXTAREA_H
 
#include <stdint.h>
#include <stdbool.h>
 
#include "netsurf/plot_style.h"
#include "netsurf/mouse.h"
 
struct textarea;
struct redraw_context;
 
/**
 * 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_flags;
 
 
/**
 * Textarea drag status
 */
typedef enum {
        TEXTAREA_DRAG_NONE,
        TEXTAREA_DRAG_SCROLLBAR,
        TEXTAREA_DRAG_SELECTION
} 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 */
        TEXTAREA_MSG_REDRAW_REQUEST,    /**< Textarea redraw request */
        TEXTAREA_MSG_CARET_UPDATE,      /**< Textarea caret */
        TEXTAREA_MSG_TEXT_MODIFIED      /**< Textarea text modified */
} textarea_msg_type;
 
 
/**
 * textarea message
 */
struct textarea_msg {
        struct textarea *ta;            /**< The textarea widget */
 
        textarea_msg_type type;         /**< Indicates message data type */
        union {
                textarea_drag_type drag;        /**< With _DRAG_REPORT */
                struct {
                        bool have_selection;    /**< Selection exists */
                        bool read_only;         /**< Selection can't be cut */
                } selection;                    /**< With _SELECTION_REPORT */
                struct rect redraw;             /**< With _REDRAW_REQUEST */
                struct {
                        enum {
                                TEXTAREA_CARET_SET_POS, /**< Set coord/height */
                                TEXTAREA_CARET_HIDE     /**< Hide */
                        } type;
                        struct {
                                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 {
                        const char *text;       /**< UTF8 text */
                        unsigned int len;       /**< Byte length of text */
                } modified;                     /**< With _TEXT_MODIFIED */
        } data;                         /**< Depends on msg type */
};
 
 
/**
 * textarea setup parameters
 */
typedef struct textarea_setup {
        int width;              /**< Textarea width */
        int height;             /**< Textarea height */
 
        int pad_top;            /**< Textarea top padding */
        int pad_right;          /**< Textarea right padding */
        int pad_bottom;         /**< Textarea bottom padding */
        int pad_left;           /**< Textarea left padding */
 
        int border_width;       /**< Textarea border width */
        colour border_col;      /**< Textarea border colour */
 
        colour selected_text;   /**< Textarea selected text colour */
        colour selected_bg;     /**< Textarea selection background colour */
        plot_font_style_t text; /**< Textarea background colour and font */
 
} 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 msg textarea message data
 */
typedef void(*textarea_client_callback)(void *data, struct textarea_msg *msg);
 
 
/**
 * Create a text area.
 *
 * \param flags flags controlling the text area creation
 * \param setup textarea settings and style
 * \param callback will be called when textarea wants to redraw
 * \param data  user specified data which will be passed to callbacks
 * \return Opaque handle for textarea or 0 on error
 */
struct textarea *textarea_create(const textarea_flags flags,
                const textarea_setup *setup,
                textarea_client_callback callback, 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);
 
 
/**
 * Insert the text in a text area at the caret, replacing any selection.
 *
 * \param ta Text area
 * \param text UTF-8 text to set text area's contents to
 * \param text_length length of text.
 * \return true on success, false on memory exhaustion or if ta lacks caret
 */
bool textarea_drop_text(struct textarea *ta, const char *text,
                size_t text_length);
 
 
/**
 * 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 (includes trailing '\0')
 * \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);
 
 
/**
 * Access text data in a text area
 *
 * \param[in]  ta   Text area
 * \param[out] len  Returns byte length of returned text, if passed non-NULL.
 * \return textarea string data.
 */
const char * textarea_data(struct textarea *ta, 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);
 
 
/**
 * Handle redraw requests for text areas
 *
 * \param ta    textarea to render
 * \param x     x coordinate of textarea top
 * \param y     y coordinate of textarea left
 * \param bg    background colour under textarea
 * \param scale scale to render at
 * \param clip  clip rectangle
 * \param ctx   current redraw context
 */
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.
 */
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 the textarea mouse status
 */
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
 * \return true if there was a selection to clear, false otherwise
 */
bool textarea_clear_selection(struct textarea *ta);
 
 
/**
 * Get selected text.
 *
 * ownership of the returned string is passed to caller which needs to
 *  free it.
 *
 * \param ta Textarea widget
 * \return Selected text, or NULL if none.
 */
char *textarea_get_selection(struct textarea *ta);
 
 
/**
 * Gets the dimensions of a textarea
 *
 * \param ta            textarea widget
 * \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.
 *
 * 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 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.
 *
 * 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 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
 * \param bottom        the new bottom padding of the textarea
 * \param left          the new left padding of the textarea
 */
void textarea_set_layout(
                struct textarea *ta,
                const plot_font_style_t *fstyle,
                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.
 *
 * \param ta    textarea widget
 * \param scrx  number of px try to scroll in x direction
 * \param scry  number of px try to scroll in y direction
 * \return true iff the textarea was scrolled
 */
bool textarea_scroll(struct textarea *ta, int scrx, int scry);
 
#endif