FLTK 1.3.8
|
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. | |
char * | address (int pos) |
Convert a byte offset in buffer into a memory address. More... | |
const char * | address (int pos) const |
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... | |
int | highlight () |
Returns the highlighted text. More... | |
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. 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 |
Fl_Text_Selection * | primary_selection () |
Returns the primary selection. | |
const Fl_Text_Selection * | primary_selection () const |
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_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-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. | |
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... | |
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/.
Fl_Text_Buffer::Fl_Text_Buffer | ( | int | requestedSize = 0 , |
int | preferredGapSize = 1024 |
||
) |
Create an empty text buffer of a pre-determined size.
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) |
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:
|
inline |
Convert a byte offset in buffer into a memory address.
pos | byte offset into buffer |
|
inline |
Convert a byte offset in buffer into a memory address.
pos | byte offset into buffer |
|
inline |
Appends the text string to the end of the buffer.
t | UTF-8 encoded and nul terminated text |
|
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.
pos | byte offset into buffer |
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.
pos | byte offset into buffer, pos must be at a UTF-8 character boundary |
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.
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.
startPos | byte offset to start position |
searchChar | UCS-4 character that we want to find |
foundPos | byte offset where the character was found |
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.
startPos | byte offset to start position |
searchChar | UCS-4 character that we want to find |
foundPos | byte offset where the character was found |
|
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
.
pos | insertion position as byte offset (must be UTF-8 character aligned) |
text | UTF-8 encoded and nul terminated 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).
int Fl_Text_Buffer::insertfile | ( | const char * | file, |
int | pos, | ||
int | buflen = 128*1024 |
||
) |
Inserts a file at the specified position.
Returns
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.
|
inline |
Returns the number of bytes in the buffer.
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).
pos | byte index into buffer |
int Fl_Text_Buffer::line_start | ( | int | pos | ) | const |
Returns the position of the start of the line containing position pos
.
pos | byte index into buffer |
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.
pos | byte index into buffer |
|
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.
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
int Fl_Text_Buffer::prev_char | ( | int | ix | ) | const |
Returns the index of the previous character.
ix | index to the current character |
void Fl_Text_Buffer::remove | ( | int | start, |
int | end | ||
) |
Deletes a range of characters in the buffer.
start | byte offset to first character to be removed |
end | byte offset to character after last character to be removed |
|
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.
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.
|
inline |
Saves a text file from the current buffer.
Returns
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.
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 |
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.
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 |
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.
lineStartPos | byte offset into buffer |
nChars | number of bytes that are sent to the display |
|
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.
void Fl_Text_Buffer::text | ( | const char * | text | ) |
Replaces the entire contents of the text buffer.
text | Text 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.
start | byte offset to first character |
end | byte offset after last character in range |
int Fl_Text_Buffer::word_end | ( | int | pos | ) | const |
Returns the position corresponding to the end of the word.
pos | byte index into buffer |
int Fl_Text_Buffer::word_start | ( | int | pos | ) | const |
Returns the position corresponding to the start of the word.
pos | byte index into buffer |
|
static |
This message may be displayed using the fl_alert() function when a file which was not UTF-8 encoded is input.
|
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.