## class Fl_Text_Buffer

### Class Hierarchy

    Fl_Text_Buffer

### Include Files

    #include <FL/Fl_Text_Buffer.H>

### Description

The `Fl_Text_Buffer` class is used by the `Fl_Text_Display` and `Fl_Text_Editor` to manage complex text data and is based upon the excellent NEdit text editor engine - see http://www.nedit.org/.

### Methods

Fl_Text_Buffer ~Fl_Text_Buffer add_modify_callback append appendfile call_modify_callbacks character character_width clear_rectangular copy count_displayed_characters count_lines expand_character findchar_backward findchar_forward findchars_backward findchars_forward highlight highlight_position highlight_rectangular highlight_selection highlight_text insert_column insertfile | insert length line_end line_start line_text loadfile null_substitution_character outputfile overlay_rectangular primary_selection remove_modify_callback remove_rectangular remove remove_secondary_selection remove_selection replace_rectangular replace replace_secondary_selection replace_selection rewind_lines savefile search_backward search_forward | secondary_selection_position secondary_selection secondary_selection_text secondary_select_rectangular secondary_select secondary_unselect selected selection_position selection_text select_rectangular select skip_displayed_characters skip_lines substitute_null_characters tab_distance text_in_rectangle text_range text unhighlight unselect unsubstitute_null_characters word_end word_start

#### Fl_Text_Buffer(int requestedSize = 0);

Creates a new text buffer of the specified initial size.

#### ~Fl_Text_Buffer();

Destroys a text buffer.

#### void add_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);

Adds a callback function that is called whenever the text buffer is modified. The callback function is declared as follows:

    typedef void (*Fl_Text_Modify_Cb)(int pos, int nInserted, int nDeleted,
                                      int nRestyled, const char* deletedText,
                                      void* cbArg);

#### void append(const char* text);

Appends the text string to the end of the buffer.

#### int appendfile(const char *file, int buflen = 128*1024);

Appends the named file to the end of the buffer. Returns 0 on success, non-zero on error (strerror() contains reason). 1 indicates open for read failed (no data loaded). 2 indicates error occurred while reading data (data was partially loaded).

#### void call_modify_callbacks();

Calls all modify callbacks that have been registered using the `add_modify_callback()` method.

#### char character(int pos);

Returns the character at the specified position in the buffer.

#### static int character_width(char c, int indent, int tabDist, char nullSubsChar);

Returns the column width of the specified character. The `indent` argument specifies the current column position, and `tabDist` specifies the number of columns to use for each tab.

The `nullSubsChar` argument specifies the current `nul` character.

#### void clear_rectangular(int start, int end, int rectStart, int rectEnd);

Clears text in the specified area.

#### void copy(Fl_Text_Buffer* fromBuf, int fromStart, int fromEnd, int toPos);

Copies text from one buffer to this one; `fromBuf` may be the same as `this`.

#### int count_displayed_characters(int lineStartPos, int targetPos);

Determines the number of characters that will be displayed between `lineStartPos` and `targetPos`.

#### int count_lines(int startPos, int endPos);

Determines the number of lines between `startPos` and `endPos`.

#### int expand_character(int pos, int indent, char *outStr);
static int expand_character(char c, int indent, char* outStr, int tabDist, char nullSubsChar);

Expands the given character to a displayable format. Tabs and other control characters are given special treatment.

#### int findchar_backward(int startPos, char searchChar, int* foundPos);

Finds the previous occurrence of the specified character.

#### int findchar_forward(int startPos, char searchChar, int* foundPos);

Finds the next occurrence of the specified character.

#### int findchars_backward(int startPos, const char* searchChars, int* foundPos);

Finds the previous occurrence of the specified characters.

#### int findchars_forward(int startPos, const char* searchChars, int* foundPos);

Finds the next occurrence of the specified characters. Search forwards in buffer for characters in searchChars, starting with the character startPos, and returning the result in foundPos returns 1 if found, 0 if not.

#### void highlight(int start, int end);

Highlights the specified text within the buffer.

#### int highlight_position(int* start, int* end, int* isRect, int* rectStart, int* rectEnd);

Returns the current highlight positions.

#### void highlight_rectangular(int start, int end, int rectStart, int rectEnd);

Highlights the specified rectangle of text within the buffer.

#### Fl_Text_Selection* highlight_selection();

Returns the current highlight selection.

#### const char* highlight_text();

Returns the highlighted text. When you are done with the text, free it using the `free()` function.

#### void insert_column(int column, int startPos, const char* text, int* charsInserted, int* charsDeleted);

Inserts a column of text without calling the modify callbacks.

#### int insertfile(const char *file, int pos, int buflen = 128*1024);

Inserts a file at the specified position. Returns 0 on success, non-zero on error (strerror() contains reason). 1 indicates open for read failed (no data loaded). 2 indicates error occurred while reading data (data was partially loaded).

#### void insert(int pos, const char* text);

Inserts text at the specified position.

#### int length();

Returns the number of characters in the buffer.

#### int line_end(int pos);

Returns the end position of the line.

#### int line_start(int pos);

Returns the start position of the line.

#### const char* line_text(int pos);

Returns the text for the line containing the specified character position. When you are done with the text, free it using the `free()` function.

#### int loadfile(const char *file, int buflen = 128*1024);

Replaces the current buffer with the contents of a file. Returns 0 on success, non-zero on error (strerror() contains reason). 1 indicates open for read failed (no data loaded). 2 indicates error occurred while reading data (data was partially loaded).

#### char null_substitution_character();

Returns the current `nul` substitution character.

#### int outputfile(const char *file, int start, int end, int buflen = 128*1024);

Writes the specified portions of the file to a file. Returns 0 on success, non-zero on error (strerror() contains reason). 1 indicates open for write failed (no data saved). 2 indicates error occurred while writing data (data was partially saved).

#### void overlay_rectangular(int startPos, int rectStart, int rectEnd, const char* text, int* charsInserted, int* charsDeleted);

Replaces a rectangular region of text with the given text.

#### Fl_Text_Selection* primary_selection();

Returns the primary selection.

#### void remove_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);

Removes a modify callback.

#### void remove_rectangular(int start, int end, int rectStart, int rectEnd);

Deletes a rectangular area of text in the buffer.

#### void remove(int start, int end);

Deletes a range of characters in the buffer.

#### void remove_secondary_selection();

Removes the text in the secondary selection.

#### void remove_selection();

Removes the text in the primary selection.

#### void replace_rectangular(int start, int end, int rectStart, int rectEnd, const char* text);

Replaces the text in a rectangular area.

#### void replace(int start, int end, const char *text);

Replaces the text in the specified range of characters in the buffer.

#### void replace_secondary_selection(const char* text);

Replaces the text in the secondary selection.

#### void replace_selection(const char* text);

Replaces the text in the primary selection.

#### int rewind_lines(int startPos, int nLines);

Returns the buffer position for the Nth previous line.

#### int savefile(const char *file, int buflen = 128*1024);

Saves the entire buffer to a file. Returns 0 on success, non-zero on error (strerror() contains reason). 1 indicates open for write failed (no data saved). 2 indicates error occurred while writing data (data was partially saved).

#### int search_backward(int startPos, const char* searchString, int* foundPos, int matchCase = 0);

Searches backwards for the specified string.

#### int search_forward(int startPos, const char* searchString, int* foundPos, int matchCase = 0);

Searches forwards for the specified string.

#### int secondary_selection_position(int* start, int* end, int* isRect, int* rectStart, int* rectEnd);

#### Fl_Text_Selection* secondary_selection();

Returns the secondary selection.

#### const char* secondary_selection_text();

Returns the text in the secondary selection. When you are done with the text, free it using the `free()` function.

#### void secondary_select_rectangular(int start, int end, int rectStart, int rectEnd);

Selects a rectangle of characters in the secondary selection.

#### void secondary_select(int start, int end);

Selects a range of characters in the secondary selection.

#### void secondary_unselect();

Turns the secondary selection off.

#### int selected();

Returns a non-zero number if any text has been selected, or 0 if no text is selected.

#### int selection_position(int* start, int* end);
int selection_position(int* start, int* end, int* isRect, int* rectStart, int* rectEnd);

Returns the current selection.

#### const char* selection_text();

Returns the currently selected text. When you are done with the text, free it using the `free()` function.

#### void select_rectangular(int start, int end, int rectStart, int rectEnd);

Selects a rectangle of characters in the buffer.

#### void select(int start, int end);

Selects a range of characters in the buffer.

#### int skip_displayed_characters(int lineStartPos, int nChars);

Skips forward the indicated number of characters in the buffer from the start position.

#### int skip_lines(int startPos, int nLines);

Returns the buffer position for the Nth line after the start position.

#### int substitute_null_characters(char* string, int length);

Replaces `nul` characters in the given string with the `nul` substitution character.

#### int tab_distance();
void tab_distance(int tabDist);

Gets or sets the tab width.

#### const char* text_in_rectangle(int start, int end, int rectStart, int rectEnd);

Returns the text from the given rectangle. When you are done with the text, free it using the `free()` function.

#### const char* text_range(int start, int end);

Returns the text from the range of characters. When you are done with the text, free it using the `free()` function.

#### const char* text();
void text(const char* text);

Gets or sets the text in the buffer. The first form returns a copy of the text in the buffer which you must later `free()` when done using it. The second form sets the text in the buffer, making an internal copy of the string that is automatically managed.

#### void unhighlight();

Unhighlights text in the buffer.

#### void unselect();

Unselects text in the buffer.

#### void unsubstitute_null_characters(char* string);

Replaces the `nul` substitution characters in the provided string with the `nul` character.

#### int word_end(int pos);

Returns the position for the end of the word.

#### int word_start(int pos);

Returns the position for the start of the word.