FLTK 1.4.5: Fl_Text_Buffer Class Reference

FLTK 1.4.5

Loading...
Searching...
No Matches
Fl_Text_Buffer Class Reference

This class manages Unicode text displayed in one or more Fl_Text_Display widgets. More...

`#include <Fl_Text_Buffer.H>`

## Public Member Functions
void | add_modify_callback (Fl_Text_Modify_Cb bufModifiedCB, void *cbArg)
| Adds a callback function that is called whenever the text buffer is modified.
void | add_predelete_callback (Fl_Text_Predelete_Cb bufPredelCB, void *cbArg)
| Adds a callback routine to be called before text is deleted from the buffer.
char * | address (int pos)
| Convert a byte offset in buffer into a memory address.
const char * | address (int pos) const
| Convert a byte offset in buffer into a memory address.
void | append (const char *t, int addedLength=-1)
| 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.
char | byte_at (int pos) const
| Returns the raw byte at the specified position pos in the buffer.
void | call_modify_callbacks ()
| Calls all modify callbacks that have been registered using the add_modify_callback() method.
void | call_predelete_callbacks ()
| Calls the stored pre-delete callback procedure(s) for this buffer to update the changed area(s) on the screen and any other listeners.
bool | can_redo () const
| Check if undo is enabled and if the last undo action can be redone.
bool | can_undo () const
| Check if undo is enabled and if the last action can be undone.
void | canUndo (char flag=1)
| Enable or disable undo actions for this text buffer.
unsigned int | char_at (int pos) const
| Returns the character at the specified position `pos` in the buffer.
void | copy (Fl_Text_Buffer *fromBuf, int fromStart, int fromEnd, int toPos)
| Copies text from another Fl_Text_Buffer to this one.
int | count_displayed_characters (int lineStartPos, int targetPos) const
| Count the number of displayed characters between buffer position `lineStartPos` and `targetPos`.
int | count_lines (int startPos, int endPos) const
| Counts the number of newlines between `startPos` and `endPos` in buffer.
int | estimate_lines (int startPos, int endPos, int lineLen) const
| Estimate the number of newlines between `startPos` and `endPos` in buffer.
int | findchar_backward (int startPos, unsigned int searchChar, int *foundPos) const
| Search backwards in buffer `buf` for character `searchChar`, starting with the character before `startPos`, returning the result in `foundPos`.
int | findchar_forward (int startPos, unsigned searchChar, int *foundPos) const
| Finds the next occurrence of the specified character.
| Fl_Text_Buffer (int requestedSize=0, int preferredGapSize=1024)
| Create an empty text buffer of a pre-determined size.
int | highlight ()
| Returns a non-zero value if text has been highlighted, 0 otherwise.
void | highlight (int start, int end)
| Highlights the specified text within the buffer.
int | highlight_position (int *start, int *end)
| Highlights the specified text between `start` and `end` within the buffer.
const Fl_Text_Selection * | highlight_selection () const
| Returns the current highlight selection.
char * | highlight_text ()
| Returns the highlighted text.
void | insert (int pos, const char *text, int insertedLength=-1)
| Inserts null-terminated string `text` at position `pos`.
int | insertfile (const char *file, int pos, int buflen=128 *1024)
| Inserts a file at the specified position.
bool | is_word_separator (int pos) const
| Returns whether character at position `pos` is a word separator.
int | length () const
| Returns the number of bytes in the buffer.
int | line_end (int pos) const
| Finds and returns the position of the end of the line containing position `pos` (which is either a pointer to the newline character ending the line or a pointer to one character beyond the end of the buffer).
int | line_start (int pos) const
| Returns the position of the start of the line containing position `pos`.
char * | line_text (int pos) const
| Returns the text from the entire line containing the specified character position.
int | loadfile (const char *file, int buflen=128 *1024)
| Loads a text file into the buffer.
int | next_char (int pos) const
| Returns the index of the next character.
int | next_char_clipped (int pos) const
int | outputfile (const char *file, int start, int end, int buflen=128 *1024)
| Writes the specified portions of the text buffer to a file.
int | prev_char (int pos) const
| Returns the index of the previous character.
int | prev_char_clipped (int pos) const
Fl_Text_Selection * | primary_selection ()
| Returns the primary selection.
const Fl_Text_Selection * | primary_selection () const
| Returns the primary selection.
void | printf (const char *fmt,...)
| Appends printf formatted messages to the end of the buffer.
int | redo (int *cp=0)
| Redo previous undo action.
void | remove (int start, int end)
| Deletes a range of characters in the buffer.
void | remove_modify_callback (Fl_Text_Modify_Cb bufModifiedCB, void *cbArg)
| Removes a modify callback.
void | remove_predelete_callback (Fl_Text_Predelete_Cb predelCB, void *cbArg)
| Removes a callback routine `bufPreDeleteCB` associated with argument `cbArg` to be called before text is deleted from the buffer.
void | remove_secondary_selection ()
| Removes the text from the buffer corresponding to the secondary text selection object.
void | remove_selection ()
| Removes the text in the primary selection.
void | replace (int start, int end, const char *text, int insertedLength=-1)
| Deletes the characters between `start` and `end`, and inserts the null-terminated string `text` in their place in the buffer.
void | replace_secondary_selection (const char *text)
| Replaces the text from the buffer corresponding to the secondary text selection object with the new string `text`.
void | replace_selection (const char *text)
| Replaces the text in the primary selection.
int | rewind_lines (int startPos, int nLines)
| Finds and returns the position of the first character of the line `nLines` backwards from `startPos` (not counting the character pointed to by `startpos` if that is a newline) in the buffer.
int | savefile (const char *file, int buflen=128 *1024)
| Saves a text file from the current buffer.
int | search_backward (int startPos, const char *searchString, int *foundPos, int matchCase=0) const
| Search backwards in buffer for string `searchString`, starting with the character at `startPos`, returning the result in `foundPos`.
int | search_forward (int startPos, const char *searchString, int *foundPos, int matchCase=0) const
| Search forwards in buffer for string `searchString`, starting with the character `startPos`, and returning the result in `foundPos`.
void | secondary_select (int start, int end)
| Selects a range of characters in the secondary selection.
int | secondary_selected ()
| Returns a non-zero value if text has been selected in the secondary text selection, 0 otherwise.
const Fl_Text_Selection * | secondary_selection () const
| Returns the secondary selection.
int | secondary_selection_position (int *start, int *end)
| Returns the current selection in the secondary text selection object.
char * | secondary_selection_text ()
| Returns the text in the secondary selection.
void | secondary_unselect ()
| Clears any selection in the secondary text selection object.
void | select (int start, int end)
| Selects a range of characters in the buffer.
int | selected () const
| Returns a non-zero value if text has been selected, 0 otherwise.
int | selection_position (int *start, int *end)
| Gets the selection position.
char * | selection_text ()
| Returns the currently selected text.
int | skip_displayed_characters (int lineStartPos, int nChars)
| Count forward from buffer position `startPos` in displayed characters.
int | skip_lines (int startPos, int nLines)
| Finds the first character of the line `nLines` forward from `startPos` in the buffer and returns its position.
int | tab_distance () const
| Gets the tab width.
void | tab_distance (int tabDist)
| Set the hardware tab distance (width) used by all displays for this buffer, and used in computing offsets for rectangular selection operations.
char * | text () const
| Get a copy of the entire contents of the text buffer.
void | text (const char *text)
| Replaces the entire contents of the text buffer.
char * | text_range (int start, int end) const
| Get a copy of a part of the text buffer.
int | undo (int *cp=0)
| Undo text modification according to the undo variables or insert text from the undo buffer.
void | unhighlight ()
| Unhighlights text in the buffer.
void | unselect ()
| Cancels any previous selection on the primary text selection object.
int | utf8_align (int) const
| Align an index into the buffer to the current or previous UTF-8 boundary.
void | vprintf (const char *fmt, va_list ap)
| Can be used by subclasses that need their own printf() style functionality.
int | word_end (int pos) const
| Returns the position corresponding to the end of the word.
int | word_start (int pos) const
| Returns the position corresponding to the start of the word.
| ~Fl_Text_Buffer ()
| Frees a text buffer.

## Public Attributes
int | input_file_was_transcoded
| true if the loaded file has been transcoded to UTF-8.
void(*) | transcoding_warning_action (Fl_Text_Buffer *)
| Pointer to a function called after reading a non UTF-8 encoded file.

## Static Public Attributes
static const char * | file_encoding_warning_message
| This message may be displayed using the fl_alert() function when a file which was not UTF-8 encoded is input.

## Protected Member Functions
int | apply_undo (Fl_Text_Undo_Action *action, int *cursorPos)
| Apply the current undo/redo operation, called from undo() or redo().
void | call_modify_callbacks (int pos, int nDeleted, int nInserted, int nRestyled, const char *deletedText) const
| Calls the stored modify callback procedure(s) for this buffer to update the changed area(s) on the screen and any other listeners.
void | call_predelete_callbacks (int pos, int nDeleted) const
| Calls the stored pre-delete callback procedure(s) for this buffer to update the changed area(s) on the screen and any other listeners.
int | insert_ (int pos, const char *text, int insertedLength=-1)
| Internal (non-redisplaying) version of insert().
void | move_gap (int pos)
| Move the gap to start at a new position.
void | reallocate_with_gap (int newGapStart, int newGapLen)
| Reallocates the text storage in the buffer to have a gap starting at `newGapStart` and a gap size of `newGapLen`, preserving the buffer's current contents.
void | redisplay_selection (Fl_Text_Selection *oldSelection, Fl_Text_Selection *newSelection) const
| Calls the stored redisplay procedure(s) for this buffer to update the screen for a change in a selection.
void | remove_ (int start, int end)
| Internal (non-redisplaying) version of remove().
void | remove_selection_ (Fl_Text_Selection *sel)
| Removes the text from the buffer corresponding to `sel`.
void | replace_selection_ (Fl_Text_Selection *sel, const char *text)
| Replaces the `text` in selection `sel`.
char * | selection_text_ (Fl_Text_Selection *sel) const
void | update_selections (int pos, int nDeleted, int nInserted)
| Updates all of the selections in the buffer for changes in the buffer's text.

## Protected Attributes
char * | mBuf
| allocated memory where the text is stored
char | mCanUndo
| if this buffer is used for attributes, it must not do any undo calls
void ** | mCbArgs
| caller arguments for modifyProcs above
int | mCursorPosHint
| hint for reasonable cursor position after a buffer modification operation
int | mGapEnd
| points to the first character after the gap
int | mGapStart
| points to the first character of the gap
Fl_Text_Selection | mHighlight
| highlighted areas
int | mLength
| length of the text in the buffer (the length of the buffer itself must be calculated: gapEnd - gapStart + length)
Fl_Text_Modify_Cb * | mModifyProcs
| procedures to call when buffer is modified to redisplay contents
int | mNModifyProcs
| number of modify-redisplay procs attached
int | mNPredeleteProcs
| number of pre-delete procs attached
void ** | mPredeleteCbArgs
| caller argument for pre-delete proc above
Fl_Text_Predelete_Cb * | mPredeleteProcs
| procedure to call before text is deleted from the buffer; at most one is supported.
int | mPreferredGapSize
| the default allocation for the text gap is 1024 bytes and should only be increased if frequent and large changes in buffer size are expected
Fl_Text_Selection | mPrimary
| highlighted areas
Fl_Text_Undo_Action_List * | mRedoList
| List of redo event.
Fl_Text_Selection | mSecondary
| highlighted areas
int | mTabDist
| equiv.
Fl_Text_Undo_Action * | mUndo
| local undo event
Fl_Text_Undo_Action_List * | mUndoList
| List of undo event.

## Detailed Description

This class manages Unicode text displayed in one or more Fl_Text_Display widgets.

All text in Fl_Text_Buffer must be encoded in UTF-8. All indices used in the function calls must be aligned to the start of a UTF-8 sequence. All indices and pointers returned will be aligned. All functions that return a single character will return that in an unsigned int in UCS-4 encoding.

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 https://sourceforge.net/projects/nedit/.

## Constructor & Destructor Documentation

## ◆ Fl_Text_Buffer()

Fl_Text_Buffer::Fl_Text_Buffer | ( | int | requestedSize = 0,
|  | int | preferredGapSize = 1024 )

Create an empty text buffer of a pre-determined size.

Parameters

  requestedSize | use this to avoid unnecessary re-allocation if you know exactly how much the buffer will need to hold
  preferredGapSize | Initial size for the buffer gap (empty space in the buffer where text might be inserted if the user is typing sequential characters)

## Member Function Documentation

## ◆ add_modify_callback()

void Fl_Text_Buffer::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);

## ◆ address() [1/2]

char * Fl_Text_Buffer::address | ( | int | pos | ) |
| inline

Convert a byte offset in buffer into a memory address.

Parameters

  pos | byte offset into buffer

Returns
  byte offset converted to a memory address

## ◆ address() [2/2]

const char * Fl_Text_Buffer::address | ( | int | pos | ) | const
| inline

Convert a byte offset in buffer into a memory address.

Parameters

  pos | byte offset into buffer

Returns
  byte offset converted to a memory address

## ◆ append()

void Fl_Text_Buffer::append | ( | const char * | t,
|  | int | addedLength = -1 )
| inline

Appends the text string to the end of the buffer.

Parameters

  t | UTF-8 encoded text
  addedLength | number of bytes to append, or -1 to indicate `t` is null-terminated

## ◆ appendfile()

int Fl_Text_Buffer::appendfile | ( | const char * | file,
|  | int | buflen = 128*1024 )
| inline

Appends the named file to the end of the buffer.

See also insertfile().

## ◆ byte_at()

char Fl_Text_Buffer::byte_at | ( | int | pos | ) | const

Returns the raw byte at the specified position pos in the buffer.

Positions start at 0.

Parameters

  pos | byte offset into buffer

Returns
  unencoded raw byte

## ◆ can_redo()

bool Fl_Text_Buffer::can_redo | ( |  | ) | const

Check if undo is enabled and if the last undo action can be redone.

Check if undo is anabled and if the last undo action can be redone.

See also
  canUndo()

## ◆ can_undo()

bool Fl_Text_Buffer::can_undo | ( |  | ) | const

Check if undo is enabled and if the last action can be undone.

See also
  canUndo()

## ◆ canUndo()

void Fl_Text_Buffer::canUndo | ( | char | flag = 1 | ) |

Enable or disable undo actions for this text buffer.

Undo actions are enable for text buffer by default. If used as a style buffer in Fl_Text_Display, undo actions are disabled as they are handled by the text buffer.

See also
  can_undo()

## ◆ char_at()

unsigned int Fl_Text_Buffer::char_at | ( | int | pos | ) | const

Returns the character at the specified position `pos` in the buffer.

Positions start at 0.

Parameters

  pos | byte offset into buffer, `pos` must be at a UTF-8 character boundary

Returns
  Unicode UCS-4 encoded character

## ◆ copy()

void Fl_Text_Buffer::copy | ( | Fl_Text_Buffer * | fromBuf,
|  | int | fromStart,
|  | int | fromEnd,
|  | int | toPos )

Copies text from another Fl_Text_Buffer to this one.

Parameters

  fromBuf | source text buffer, may be the same as this
  fromStart | byte offset into buffer
  fromEnd | byte offset into buffer
  toPos | destination byte offset into buffer

## ◆ count_displayed_characters()

int Fl_Text_Buffer::count_displayed_characters | ( | int | lineStartPos,
|  | int | targetPos ) const

Count the number of displayed characters between buffer position `lineStartPos` and `targetPos`.

Displayed characters are the characters shown on the screen to represent characters in the buffer, where tabs and control characters are expanded.

## ◆ count_lines()

int Fl_Text_Buffer::count_lines | ( | int | startPos,
|  | int | endPos ) const

Counts the number of newlines between `startPos` and `endPos` in buffer.

The character at position `endPos` is not counted.

## ◆ estimate_lines()

int Fl_Text_Buffer::estimate_lines | ( | int | startPos,
|  | int | endPos,
|  | int | lineLen ) const

Estimate the number of newlines between `startPos` and `endPos` in buffer.

This call takes line wrapping into account. It assumes a line break at every lineLen characters after the beginning of a line.

## ◆ findchar_backward()

int Fl_Text_Buffer::findchar_backward | ( | int | startPos,
|  | unsigned int | searchChar,
|  | int * | foundPos ) const

Search backwards in buffer `buf` for character `searchChar`, starting with the character before `startPos`, returning the result in `foundPos`.

Returns 1 if found, 0 if not. The difference between this and search_backward() is that it's optimized for single characters. The overall performance of the text widget is dependent on its ability to count lines quickly, hence searching for a single character: newline.

Parameters

  startPos | byte offset to start position
  searchChar | UCS-4 character that we want to find
  foundPos | byte offset where the character was found

Returns
  1 if found, 0 if not

## ◆ findchar_forward()

int Fl_Text_Buffer::findchar_forward | ( | int | startPos,
|  | unsigned | searchChar,
|  | int * | foundPos ) const

Finds the next occurrence of the specified character.

Search forwards in buffer for character `searchChar`, starting with the character `startPos`, and returning the result in `foundPos`. Returns 1 if found, 0 if not. The difference between this and search_forward() is that it's optimized for single characters. The overall performance of the text widget is dependent on its ability to count lines quickly, hence searching for a single character: newline.

Parameters

  startPos | byte offset to start position
  searchChar | UCS-4 character that we want to find
  foundPos | byte offset where the character was found

Returns
  1 if found, 0 if not

## ◆ highlight_text()

char * Fl_Text_Buffer::highlight_text | ( |  | ) |

Returns the highlighted text.

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

## ◆ insert()

void Fl_Text_Buffer::insert | ( | int | pos,
|  | const char * | text,
|  | int | insertedLength = -1 )

Inserts null-terminated string `text` at position `pos`.

Parameters

  pos | insertion position as byte offset (must be UTF-8 character aligned)
  text | UTF-8 encoded text
  insertedLength | number of bytes to insert, or -1 to indicate `text` is null-terminated

## ◆ insert_()

int Fl_Text_Buffer::insert_ | ( | int | pos,
|  | const char * | text,
|  | int | insertedLength = -1 )
| protected

Internal (non-redisplaying) version of insert().

Returns the length of text inserted (this is just strlen(`text`) if `insertedLength` == -1, however this calculation can be expensive and the length will be required by any caller who will continue on to call redisplay). `pos` must be contiguous with the existing text in the buffer (i.e. not past the end).

Returns
  the number of bytes inserted

## ◆ insertfile()

int Fl_Text_Buffer::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)

File can be UTF-8 or CP1252 encoded. If the input file is not UTF-8 encoded, the Fl_Text_Buffer widget will contain data transcoded to UTF-8. By default, the message Fl_Text_Buffer::file_encoding_warning_message will warn the user about this.

See also
  input_file_was_transcoded and transcoding_warning_action.

## ◆ is_word_separator()

bool Fl_Text_Buffer::is_word_separator | ( | int | pos | ) | const

Returns whether character at position `pos` is a word separator.

Pos must be at a character boundary.

## ◆ length()

int Fl_Text_Buffer::length | ( |  | ) | const
| inline

Returns the number of bytes in the buffer.

Returns
  size of text in bytes

## ◆ line_end()

int Fl_Text_Buffer::line_end | ( | int | pos | ) | const

Finds and returns the position of the end of the line containing position `pos` (which is either a pointer to the newline character ending the line or a pointer to one character beyond the end of the buffer).

Parameters

  pos | byte index into buffer

Returns
  byte offset to line end

## ◆ line_start()

int Fl_Text_Buffer::line_start | ( | int | pos | ) | const

Returns the position of the start of the line containing position `pos`.

Parameters

  pos | byte index into buffer

Returns
  byte offset to line start

## ◆ line_text()

char * Fl_Text_Buffer::line_text | ( | int | pos | ) | const

Returns the text from the entire line containing the specified character position.

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

Parameters

  pos | byte index into buffer

Returns
  copy of UTF-8 text, must be free'd

## ◆ loadfile()

int Fl_Text_Buffer::loadfile | ( | const char * | file,
|  | int | buflen = 128*1024 )
| inline

Loads a text file into the buffer.

See also insertfile().

## ◆ next_char()

int Fl_Text_Buffer::next_char | ( | int | pos | ) | const

Returns the index of the next character.

This function processes an emoji sequence (see fl_utf8_next_composed_char) as a single character. Returns length() if the end of the buffer is reached.

Parameters

  [in] | pos | index to the current character

## ◆ outputfile()

int Fl_Text_Buffer::outputfile | ( | const char * | file,
|  | int | start,
|  | int | end,
|  | int | buflen = 128*1024 )

Writes the specified portions of the text 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)

See also
  savefile(const char *file, int buflen)

## ◆ prev_char()

int Fl_Text_Buffer::prev_char | ( | int | pos | ) | const

Returns the index of the previous character.

This function processes an emoji sequence (see fl_utf8_next_composed_char) as a single character.

Parameters

  [in] | pos | index of the current character

Returns
  index of the previous character

Return values

  -1 | if the beginning of the buffer is reached.

## ◆ printf()

void Fl_Text_Buffer::printf | ( | const char * | fmt,
|  |  | ... )

Appends printf formatted messages to the end of the buffer.

Example:

#include <FL/Fl_Text_Display.H>
int main(..) {
:
// Create a text display widget and assign it a text buffer
Fl_Text_Display *tdsp = new Fl_Text_Display(..);
Fl_Text_Buffer *tbuf = new Fl_Text_Buffer();
tdsp->buffer(tbuf);
:
// Append three lines of formatted text to the buffer
tbuf->printf("The current date is: %s.\nThe time is: %s\n", date_str, time_str);
tbuf->printf("The current PID is %ld.\n", (long)getpid());
:
Fl_Text_Buffer::Fl_Text_Buffer
Fl_Text_Buffer(int requestedSize=0, int preferredGapSize=1024)
Create an empty text buffer of a pre-determined size.
Definition Fl_Text_Buffer.cxx:207
Fl_Text_Buffer::printf
void printf(const char *fmt,...)
Appends printf formatted messages to the end of the buffer.
Definition Fl_Text_Buffer.cxx:445
Fl_Text_Display
Rich text display widget.
Definition Fl_Text_Display.H:78
Fl_Text_Display::buffer
void buffer(Fl_Text_Buffer *buf)
Attach a text buffer to display, replacing the current buffer (if any).
Definition Fl_Text_Display.cxx:369
Fl_Text_Display::Fl_Text_Display
Fl_Text_Display(int X, int Y, int W, int H, const char *l=0)
Creates a new text display widget.
Definition Fl_Text_Display.cxx:106

Note
  The expanded string is currently limited to 1024 characters.

Parameters

  [in] | fmt | is a printf format string for the message text.

## ◆ remove()

void Fl_Text_Buffer::remove | ( | int | start,
|  | int | end )

Deletes a range of characters in the buffer.

Parameters

  start | byte offset to first character to be removed
  end | byte offset to character after last character to be removed

## ◆ remove_()

void Fl_Text_Buffer::remove_ | ( | int | start,
|  | int | end )
| protected

Internal (non-redisplaying) version of remove().

Removes the contents of the buffer between `start` and `end` (and moves the gap to the site of the delete).

## ◆ replace()

void Fl_Text_Buffer::replace | ( | int | start,
|  | int | end,
|  | const char * | text,
|  | int | insertedLength = -1 )

Deletes the characters between `start` and `end`, and inserts the null-terminated string `text` in their place in the buffer.

Parameters

  start | byte offset to first character to be removed and new insert position
  end | byte offset to character after last character to be removed
  text | UTF-8 encoded text
  insertedLength | number of bytes to insert, or -1 to indicate `text` is null-terminated

## ◆ rewind_lines()

int Fl_Text_Buffer::rewind_lines | ( | int | startPos,
|  | int | nLines )

Finds and returns the position of the first character of the line `nLines` backwards from `startPos` (not counting the character pointed to by `startpos` if that is a newline) in the buffer.

`nLines` == 0 means find the beginning of the line.

## ◆ savefile()

int Fl_Text_Buffer::savefile | ( | const char * | file,
|  | int | buflen = 128*1024 )
| inline

Saves a text file from the current buffer.

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)

See also
  outputfile(const char *file, int start, int end, int buflen)

## ◆ search_backward()

int Fl_Text_Buffer::search_backward | ( | int | startPos,
|  | const char * | searchString,
|  | int * | foundPos,
|  | int | matchCase = 0 ) const

Search backwards in buffer for string `searchString`, starting with the character at `startPos`, returning the result in `foundPos`.

Returns 1 if found, 0 if not.

Parameters

  startPos | byte offset to start position
  searchString | UTF-8 string that we want to find
  foundPos | byte offset where the string was found
  matchCase | if set, match character case

Returns
  1 if found, 0 if not

## ◆ search_forward()

int Fl_Text_Buffer::search_forward | ( | int | startPos,
|  | const char * | searchString,
|  | int * | foundPos,
|  | int | matchCase = 0 ) const

Search forwards in buffer for string `searchString`, starting with the character `startPos`, and returning the result in `foundPos`.

Returns 1 if found, 0 if not.

Parameters

  startPos | byte offset to start position
  searchString | UTF-8 string that we want to find
  foundPos | byte offset where the string was found
  matchCase | if set, match character case

Returns
  1 if found, 0 if not

## ◆ secondary_selection_text()

char * Fl_Text_Buffer::secondary_selection_text | ( |  | ) |

Returns the text in the secondary selection.

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

## ◆ selection_text()

char * Fl_Text_Buffer::selection_text | ( |  | ) |

Returns the currently selected text.

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

## ◆ skip_displayed_characters()

int Fl_Text_Buffer::skip_displayed_characters | ( | int | lineStartPos,
|  | int | nChars )

Count forward from buffer position `startPos` in displayed characters.

Displayed characters are the characters shown on the screen to represent characters in the buffer, where tabs and control characters are expanded.

Parameters

  lineStartPos | byte offset into buffer
  nChars | number of bytes that are sent to the display

Returns
  byte offset in input after all output bytes are sent

## ◆ tab_distance()

int Fl_Text_Buffer::tab_distance | ( |  | ) | const
| inline

Gets the tab width.

The tab width is measured in characters. The pixel position is calculated using an average character width.

## ◆ text() [1/2]

char * Fl_Text_Buffer::text | ( |  | ) | const

Get a copy of the entire contents of the text buffer.

Memory is allocated to contain the returned string, which the caller must free.

Returns
  newly allocated text buffer - must be free'd, text is UTF-8

## ◆ text() [2/2]

void Fl_Text_Buffer::text | ( | const char * | text | ) |

Replaces the entire contents of the text buffer.

Parameters

  text | Text must be valid UTF-8. If null, an empty string is substituted.

## ◆ text_range()

char * Fl_Text_Buffer::text_range | ( | int | start,
|  | int | end ) const

Get a copy of a part of the text buffer.

Return a copy of the text between `start` and `end` character positions from text buffer `buf`. Positions start at 0, and the range does not include the character pointed to by `end`. When you are done with the text, free it using the free() function.

Parameters

  start | byte offset to first character
  end | byte offset after last character in range

Returns
  newly allocated text buffer - must be free'd, text is UTF-8

## ◆ undo()

int Fl_Text_Buffer::undo | ( | int * | cursorPos = 0 | ) |

Undo text modification according to the undo variables or insert text from the undo buffer.

Take the previous changes and undo them.

Return the previous cursor position in cursorPos. Returns 1 if the undo was applied. CursorPos will be at a character boundary.

## ◆ vprintf()

void Fl_Text_Buffer::vprintf | ( | const char * | fmt,
|  | va_list | ap )

Can be used by subclasses that need their own printf() style functionality.

Note
  The expanded string is currently limited to 1024 characters.

Parameters

  [in] | fmt | is a printf format string for the message text.
  [in] | ap | is a va_list created by va_start() and closed with va_end(), which the caller is responsible for handling.

## ◆ word_end()

int Fl_Text_Buffer::word_end | ( | int | pos | ) | const

Returns the position corresponding to the end of the word.

Parameters

  pos | byte index into buffer

Returns
  byte offset to word end

## ◆ word_start()

int Fl_Text_Buffer::word_start | ( | int | pos | ) | const

Returns the position corresponding to the start of the word.

Parameters

  pos | byte index into buffer

Returns
  byte offset to word start

## Member Data Documentation

## ◆ file_encoding_warning_message

const char * Fl_Text_Buffer::file_encoding_warning_message
| static

Initial value:
=
"Displayed text contains the UTF-8 transcoding\n"
"of the input file which was not UTF-8 encoded.\n"
"Some changes may have occurred."

This message may be displayed using the fl_alert() function when a file which was not UTF-8 encoded is input.

## ◆ mTabDist

int Fl_Text_Buffer::mTabDist
| protected

equiv.

number of characters in a tab

## ◆ transcoding_warning_action

void(*) Fl_Text_Buffer::transcoding_warning_action(Fl_Text_Buffer *)

Pointer to a function called after reading a non UTF-8 encoded file.

This function is called after reading a file if the file content was transcoded to UTF-8. Its default implementation calls fl_alert() with the text of file_encoding_warning_message. No warning message is displayed if this pointer is set to NULL. Use input_file_was_transcoded to be informed if file input required transcoding to UTF-8.

The documentation for this class was generated from the following files:

- Fl_Text_Buffer.H
- Fl_Text_Buffer.cxx