FLTK 1.3.4
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. 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 another Fl_Text_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. 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_Selectionhighlight_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 text buffer 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_Selectionprimary_selection () const
 Returns the primary selection.
 
Fl_Text_Selectionprimary_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. More...
 
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. 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. More...
 
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_Selectionsecondary_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-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. More...
 
int skip_displayed_characters (int lineStartPos, int nChars)
 Count forward from buffer position startPos in displayed characters. 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. More...
 
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 UTF-8 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 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. 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 insert(). 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 remove(). 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 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. 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 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 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
requestedSizeuse this to avoid unnecessary re-allocation if you know exactly how much the buffer will need to hold
preferredGapSizeInitial 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

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
posbyte 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
posbyte 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
tUTF-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
posbyte 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
posbyte offset into buffer, pos must be at a UTF-8 character 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 another Fl_Text_Buffer to this one.

Parameters
fromBufsource text buffer, may be the same as this
fromStartbyte offset into buffer
fromEndbyte offset into buffer
toPosdestination 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 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
startPosbyte offset to start position
searchCharUCS-4 character that we want to find
foundPosbyte 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 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
startPosbyte offset to start position
searchCharUCS-4 character that we want to find
foundPosbyte 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
posinsertion position as byte offset (must be UTF-8 character aligned)
textUTF-8 encoded and nul terminated text
int Fl_Text_Buffer::insert_ ( int  pos,
const char *  text 
)
protected

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

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 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.
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
posbyte 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
posbyte 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
posbyte index into buffer
Returns
copy of UTF-8 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
ixindex to the current character
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)
int Fl_Text_Buffer::prev_char ( int  ix) const

Returns the index of the previous character.

Parameters
ixindex to the current character
void Fl_Text_Buffer::remove ( int  start,
int  end 
)

Deletes a range of characters in the buffer.

Parameters
startbyte offset to first character to be removed
endbyte offset to character after last character to be removed
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).

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
startbyte offset to first character to be removed and new insert position
endbyte offset to character after last character to be removed
textUTF-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::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)
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
startPosbyte offset to start position
searchStringUTF-8 string that we want to find
foundPosbyte offset where the string was found
matchCaseif 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
startPosbyte offset to start position
searchStringUTF-8 string that we want to find
foundPosbyte offset where the string was found
matchCaseif 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
lineStartPosbyte offset into buffer
nCharsnumber of bytes that are sent to the display
Returns
byte offset in input after all output bytes are sent
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.

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
void Fl_Text_Buffer::text ( const char *  text)

Replaces the entire contents of the text buffer.

Parameters
textText must be valid UTF-8. 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
startbyte offset to first character
endbyte offset after last character in range
Returns
newly allocated text buffer - must be free'd, text is UTF-8
int Fl_Text_Buffer::word_end ( int  pos) const

Returns the position corresponding to the end of the word.

Parameters
posbyte 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
posbyte 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: