Fl_Text_Buffer Class Reference

This class manages unicode 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. More...
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.
const char * | address (int pos) const
| Convert a byte offset in buffer into a memory address. More...
char * | address (int pos)
| Convert a byte offset in buffer into a memory address. More...
void | append (const char *t)
| Appends the text string to the end of the buffer. More...
int | appendfile (const char *file, int buflen=128 *1024)
| Appends the named file to the end of the buffer. More...
char | byte_at (int pos) const
| Returns the raw byte at the specified position pos in the buffer. More...
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.
void | canUndo (char flag=1)
| Lets the undo system know if we can undo changes.
unsigned int | char_at (int pos) const
| Returns the character at the specified position pos in the buffer. More...
void | copy (Fl_Text_Buffer *fromBuf, int fromStart, int fromEnd, int toPos)
| Copies text from one buffer to this one. More...
int | count_displayed_characters (int lineStartPos, int targetPos) const
| Count the number of displayed characters between buffer position `lineStartPos` and `targetPos`. More...
int | count_lines (int startPos, int endPos) const
| Counts the number of newlines between `startPos` and `endPos` in buffer. More...
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` returns 1 if found, 0 if not. More...
int | findchar_forward (int startPos, unsigned searchChar, int *foundPos) const
| Finds the next occurrence of the specified character. More...
| Fl_Text_Buffer (int requestedSize=0, int preferredGapSize=1024)
| Create an empty text buffer of a pre-determined size. More...
void | highlight (int start, int end)
| Highlights the specified text within the buffer.
int | highlight ()
| Returns the highlighted text. More...
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. More...
void | insert (int pos, const char *text)
| Inserts null-terminated string `text` at position `pos`. More...
int | insertfile (const char *file, int pos, int buflen=128 *1024)
| Inserts a file at the specified position. More...
int | length () const
| Returns the number of bytes in the buffer. More...
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) More...
int | line_start (int pos) const
| Returns the position of the start of the line containing position `pos`. More...
char * | line_text (int pos) const
| Returns the text from the entire line containing the specified character position. More...
int | loadfile (const char *file, int buflen=128 *1024)
| Loads a text file into the buffer. More...
int | next_char (int ix) const
| Returns the index of the next character. More...
int | next_char_clipped (int ix) const
int | outputfile (const char *file, int start, int end, int buflen=128 *1024)
| Writes the specified portions of the file to a file. More...
int | prev_char (int ix) const
| Returns the index of the previous character. More...
int | prev_char_clipped (int ix) const
const Fl_Text_Selection * | primary_selection () const
| Returns the primary selection.
Fl_Text_Selection * | primary_selection ()
| Returns the primary selection.
void | remove (int start, int end)
| Deletes a range of characters in the buffer. More...
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)
| Deletes the characters between `start` and `end`, and inserts the null-terminated string `text` in their place in the buffer. More...
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. More...
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 searchCharssearchString, starting with the character BEFORE `startPos`, returning the result in `foundPos` returns 1 if found, 0 if not. More...
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` returns 1 if found, 0 if not. More...
void | secondary_select (int start, int end)
| Selects a range of characters in the secondary selection.
int | secondary_selected ()
| Returns a non 0 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. More...
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 0 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. More...
int | 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) More...
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. More...
void | text (const char *text)
| Replaces the entire contents of the text buffer. More...
char * | text_range (int start, int end) const
| Get a copy of a part of the text buffer. More...
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 utf8 boundary.
int | word_end (int pos) const
| Returns the position corresponding to the end of the word. More...
int | word_start (int pos) const
| Returns the position corresponding to the start of the word. More...
| ~Fl_Text_Buffer ()
| Frees a text buffer.

## Public Attributes

int | input_file_was_transcoded
| true iff 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. More...

## 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. More...

## Protected Member Functions

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)
| Internal (non-redisplaying) version of BufInsert. More...
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 BufRemove. More...
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 char 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. More...

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_Selection | mSecondary
| highlighted areas
int | mTabDist
| equiv. More...

## Detailed Description

This class manages unicode displayed in one or more Fl_Text_Display widgets.

All text in Fl_Text_Buffermust 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 unsiged 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 http://www.nedit.org/.

## Constructor & Destructor Documentation

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 chars)

## Member Function Documentation

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);

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

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

void Fl_Text_Buffer::append | ( | const char * | t | ) |

inline

Appends the text string to the end of the buffer.

Parameters

  t | utf-8 encoded and nul terminated text

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().

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

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 acharacter boundary

Returns
  Unicode UCS-4 encoded character

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

Copies text from one 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

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)

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.

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 BufSearchBackward 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

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 BufSearchForward 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

int Fl_Text_Buffer::highlight | ( |  | ) |

inline

Returns the highlighted text.

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

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

Returns the highlighted text.

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

void Fl_Text_Buffer::insert | ( | int | pos,
|  | const char * | text
| ) |  |

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 and nul terminated text

int Fl_Text_Buffer::insert_ | ( | int | pos,
|  | const char * | text
| ) |  |

protected

Internal (non-redisplaying) version of BufInsert.

Returns the length of text inserted (this is just strlen(`text`), 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

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 UTF-8-transcoded data. 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.

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

inline

Returns the number of bytes in the buffer.

Returns
  size of text in bytes

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

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

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 utf8 text, must be free'd

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

inline

Loads a text file into the buffer.

See also insertfile().

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

Returns the index of the next character.

Parameters

  ix | index to the current char

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

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

Returns the index of the previous character.

Parameters

  ix | index to the current char

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 charcatre after last character to be removed

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

protected

Internal (non-redisplaying) version of BufRemove.

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

void Fl_Text_Buffer::replace | ( | int | start,
|  | int | end,
|  | const char * | text
| ) |  |

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 charcatre after last character to be removed
  text | utf-8 encoded and nul terminated text

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

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

Search backwards in buffer for string searchCharssearchString, starting with the character BEFORE `startPos`, returning the result in `foundPos` returns 1 if found, 0 if not.

Parameters

  startPos | byte offset to start position
  searchString | utf8 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

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 | utf8 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

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.

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

Returns the currently selected text.

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

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

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 utf8

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

Replaces the entire contents of the text buffer.

Parameters

  text | Text must be valid utf8. if null an empty string is substituted.

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 utf8

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

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

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.

Fl_Text_Predelete_Cb* Fl_Text_Buffer::mPredeleteProcs

protected

               procedure to call before text is deleted

from the buffer; at most one is supported.

int Fl_Text_Buffer::mTabDist

protected

equiv.

number of characters in a tab

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

- © 1998-2012 by Bill Spitzak and others.