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>

List of all members.

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)
 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.
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.
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 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 the highlighted text.
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_Selectionhighlight_selection () const
 Returns the current highlight selection.
char * highlight_text ()
 Returns the highlighted text.
void insert (int pos, const char *text)
 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.
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 ix) const
 Returns the index of the next character.
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.
int prev_char (int ix) const
 Returns the index of the previous character.
int prev_char_clipped (int ix) const
Fl_Text_Selectionprimary_selection ()
 Returns the primary selection.
const Fl_Text_Selectionprimary_selection () const
 Returns the primary selection.
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)
 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_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.
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.
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.
int tab_distance () const
 Gets the tab width.
void text (const char *text)
 Replaces the entire contents of the text buffer.
char * text () const
 Get a copy of 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.
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

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

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

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);
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
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
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 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:
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 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
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
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 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:
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 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:
ix index 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:
ix index to the current character
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
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:
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 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:
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
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
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
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.

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

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

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: