TextArea Gadget API ------------------- The TextArea gadget has a boxed display area in which a block of text is displayed and, if the appropriate flag is set, edited by the user. The contents of the gadget can be set and read using the TextArea_SetText and TextArea_GetText methods. The contents can be modified by inserting and replacing text with the TextArea_InsertText and TextArea_ReplaceText methods. If wordwrapping is enabled, text is wrapped onto the next line when the edge of the window is reached, the text being broken at a space or a tab. If wordwrapping is off, line ends are determined by a newline character and the work area extent grows/contracts to match the length of the longest line. Text is selected by dragging with the SELECT or ADJUST mouse button. The mouse click to start the selection moves the insertion point. Moving the insertion point (by clicking with the mouse or by using the arrow keys) when a text region is selected deselects the text. This is different to the usual RISC OS manner. Text can also be selected using shift + arrow keys. The text for all gadgets are held in RAM in a single dynamic area. This is managed as a shifting heap of memory blocks, one for each textArea. Each block has an area of free space to enable text areas to grow and shrink efficiently. A line table and an insertion gap is also maintained which enables small text editing operations (e.g. interactive typing and cut/paste) to be accomplished with minimal overhead. Bits in the flags word for a text area have the following meaning: Bit Meaning when set 0 gadget has a vertical scrollbar 1 gadget has a horizontal scrollbar 2 gadget has wordwrapping enabled The TextArea gadget requires the Window module, version 1.32 or greater. Text area methods ================= TextArea_GetState ----------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id On exit R0 = state bit 0 set means gadget has a vertical scrollbar bit 1 set means gadget has a horizontal scrollbar bit 2 set means gadget has wordwrapping enabled C veneer extern _kernel_oserror *textarea_get_state(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int *state); TextArea_SetState ----------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = state bit 0 set means gadget has a vertical scrollbar bit 1 set means gadget has a horizontal scrollbar bit 2 set means gadget has wordwrapping enabled On exit R1-R9 preserved This enables the state of the textArea to be changed dymanically. C veneer extern _kernel_oserror *textarea_set_state(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int state); TextArea_SetText ---------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = text On exit R1-R9 preserved C veneer extern _kernel_oserror *textarea_set_text(unsigned int flags, ObjectId object_id, ComponentId component_id, const char *text); TextArea_GetText ---------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = pointer to buffer R5 = size of buffer On exit R5 = size of buffer required to hold text (if R4 was 0) else buffer pointed at by R4 holds text R5 holds number of bytes written to buffer C veneer extern _kernel_oserror *textarea_get_text(unsigned int flags, ObjectId object_id, ComponentId component_id, char *buffer, int buff_size, int *nbytes); TextArea_InsertText ------------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = index into text R5 = pointer to buffer On exit R1-R9 preserved C veneer extern _kernel_oserror *textarea_insert_text(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int index, const char *text); TextArea_ReplaceText -------------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = replace start R5 = replace end R6 = pointer to buffer On exit R1-R9 preserved The end position is exclusive, i.e. the text is replaced upto but not including the end character. To specify no replacement, the start and the end are the same. C veneer extern _kernel_oserror *textarea_replace_text(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int index_start, unsigned int index_end, const char *text); TextArea_GetSelection --------------------- On entry R0 = flags bit 0 set means return text rather than indexes R1 = Window object id R2 = ??? R3 = Gadget component id R4 = pointer to buffer (only if bit 0 of R0 set) R5 = size of buffer (only if bit 0 of R0 set) On exit R4 = index to start of selection (if bit 0 in R0 was set) R5 = index to end of selection (if bit 0 in R0 was set) else R5 = size of buffer required to hold selected text (if R4 was 0) else buffer pointed at by R4 holds selected text R5 holds number of bytes written to buffer The end position is exclusive, i.e. the selection is upto but not including the end character. If there is no selection, the start and end indexes will be the same. The selection start is defined by the cursor position, therefore, the start may be greater than the selection end. This means this function can also be used to get the cursor position. C veneers extern _kernel_oserror *textarea_get_selection_text(unsigned int flags, ObjectId object_id, ComponentId component_id, char *buffer, int size, unsigned int *nbytes); extern _kernel_oserror *textarea_get_selection_points(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int *index_start, unsigned int *index_end); TextArea_SetSelection --------------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = index to start of selection R5 = index to end of selection On exit R1-R9 preserved The end position is exclusive, i.e. the selection is upto but not including the end character. If the start and end indexes are the same, the cursor is set to the specified position. C veneer extern _kernel_oserror *textarea_set_selection(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int index_start, unsigned int index_end); TextArea_SetFont ---------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = pointer to font name to use R5 = width in 16th of a point R6 = height in 16th of a point On exit R1-R9 preserved Use This method makes the text area use the specified anti-aliased font. C veneer extern _kernel_oserror *textarea_set_font(unsigned int flags, ObjectId object_id, ComponentId component_id, const char *font, unsigned int width, unsigned int height); TextArea_SetColour ------------------ On entry R0 = flags bit 0 set means use desktop colours rather than real colours (in the form &BBRRGG00) R1 = Window object id R2 = ??? R3 = Gadget component id R4 = Colour value for foreground text (in the form &BBRRGG00, unless bit 0 of R0 is set) R5 = Colour value for background (in the form &BBRRGG00, unless bit 0 of R0 is set) On exit R1-R9 preserved C veneer extern _kernel_oserror *textarea_set_colour(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int foreground, unsigned int background); TextArea_GetColour ------------------ On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id On exit R0 = Colour value (in the form &BBRRGG00) of foreground R1 = Colour value (in the form &BBRRGG00) of background C veneer extern _kernel_oserror *textarea_get_colour(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int *foreground, unsigned int *background); TextArea_SetTextBorder ---------------------- On entry R0 = flags R1 = Window object id R2 = ??? R3 = Gadget component id R4 = Border size in OS units On exit R1-R9 preserved C veneer extern _kernel_oserror *textarea_set_text_border(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int border_size);