FLTK 1.3.2

- Main Page
- Related Pages
- Modules
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends
Fl_Text_Display Class Reference

Rich text display widget. More...

`#include <Fl_Text_Display.H>`

Inheritance diagram for Fl_Text_Display:

List of all members.

## Classes
struct | Style_Table_Entry
| This structure associates the color, font, andsize of a string to draw with an attribute mask matching attr. More...
## Public Types
enum | { NORMAL_CURSOR, CARET_CURSOR, DIM_CURSOR, BLOCK_CURSOR, HEAVY_CURSOR, SIMPLE_CURSOR }
| text display cursor shapes enumeration More...
enum | { CURSOR_POS, CHARACTER_POS }
| the character position is the left edge of a character, whereas the cursor is thought to be between the centers of two consecutive characters.
enum | { DRAG_NONE = -2, DRAG_START_DND = -1, DRAG_CHAR = 0, DRAG_WORD = 1, DRAG_LINE = 2 }
| drag types - they match Fl::event_clicks() so that single clicking to start a collection selects by character, double clicking selects by word and triple clicking selects by line.
enum | { WRAP_NONE, WRAP_AT_COLUMN, WRAP_AT_PIXEL, WRAP_AT_BOUNDS }
| wrap types - used in wrap_mode() More...
typedef void(* | Unfinished_Style_Cb )(int, void *)
## Public Member Functions
void | buffer (Fl_Text_Buffer *buf)
| Attach a text buffer to display, replacing the current buffer (if any)
void | buffer (Fl_Text_Buffer &buf)
| Sets the current text buffer associated with the text widget.
Fl_Text_Buffer * | buffer () const
| Gets the current text buffer associated with the text widget.
double | col_to_x (double col) const
| Convert a column number into an x pixel position.
int | count_lines (int start, int end, bool start_pos_is_line_start) const
| Count the number of lines between two positions.
Fl_Color | cursor_color () const
| Gets the text cursor color.
void | cursor_color (Fl_Color n)
| Sets the text cursor color.
void | cursor_style (int style)
| Sets the text cursor style.
| Fl_Text_Display (int X, int Y, int W, int H, const char *l=0)
| Creates a new text display widget.
virtual int | handle (int e)
| Event handling.
void | hide_cursor ()
| Hides the text cursor.
void | highlight_data (Fl_Text_Buffer *styleBuffer, const Style_Table_Entry *styleTable, int nStyles, char unfinishedStyle, Unfinished_Style_Cb unfinishedHighlightCB, void *cbArg)
| Attach (or remove) highlight information in text display and redisplay.
int | in_selection (int x, int y) const
| Check if a pixel position is within the primary selection.
void | insert (const char *text)
| Inserts "text" at the current cursor location.
void | insert_position (int newPos)
| Sets the position of the text insertion cursor for text display.
int | insert_position () const
| Gets the position of the text insertion cursor for text display.
int | line_end (int startPos, bool startPosIsLineStart) const
| Returns the end of a line.
int | line_start (int pos) const
| Return the beginning of a line.
int | move_down ()
| Moves the current insert position down one line.
int | move_left ()
| Moves the current insert position left one character.
int | move_right ()
| Moves the current insert position right one character.
int | move_up ()
| Moves the current insert position up one line.
void | next_word (void)
| Moves the current insert position right one word.
void | overstrike (const char *text)
| Replaces text at the current insert position.
int | position_style (int lineStartPos, int lineLen, int lineIndex) const
| Find the correct style for a character.
int | position_to_xy (int pos, int *x, int *y) const
| Convert a character index into a pixel position.
void | previous_word (void)
| Moves the current insert position left one word.
void | redisplay_range (int start, int end)
| Marks text from start to end as needing a redraw.
virtual void | resize (int X, int Y, int W, int H)
| Change the size of the displayed text area.
int | rewind_lines (int startPos, int nLines)
| Skip a number of lines back.
void | scroll (int topLineNum, int horizOffset)
| Scrolls the current buffer to start at the specified line and column.
Fl_Align | scrollbar_align () const
| Gets the scrollbar alignment type.
void | scrollbar_align (Fl_Align a)
| Sets the scrollbar alignment type.
int | scrollbar_width () const
| Gets the width/height of the scrollbars.
void | scrollbar_width (int W)
| Sets the width/height of the scrollbars.
int | shortcut () const
void | shortcut (int s)
void | show_cursor (int b=1)
| Shows the text cursor.
void | show_insert_position ()
| Scrolls the text buffer to show the current insert position.
int | skip_lines (int startPos, int nLines, bool startPosIsLineStart)
| Skip a number of lines forward.
Fl_Color | textcolor () const
| Gets the default color of text in the widget.
void | textcolor (Fl_Color n)
| Sets the default color of text in the widget.
Fl_Font | textfont () const
| Gets the default font used when drawing text in the widget.
void | textfont (Fl_Font s)
| Sets the default font used when drawing text in the widget.
Fl_Fontsize | textsize () const
| Gets the default size of text in the widget.
void | textsize (Fl_Fontsize s)
| Sets the default size of text in the widget.
int | word_end (int pos) const
| Moves the insert position to the end of the current word.
int | word_start (int pos) const
| Moves the insert position to the beginning of the current word.
void | wrap_mode (int wrap, int wrap_margin)
| Set the new text wrap mode.
int | wrapped_column (int row, int column) const
| Nobody knows what this function does.
int | wrapped_row (int row) const
| Nobody knows what this function does.
double | x_to_col (double x) const
| Convert an x pixel position into a column number.
| ~Fl_Text_Display ()
| Free a text display and release its associated memory.
## Protected Types
enum | { DRAW_LINE, FIND_INDEX, FIND_INDEX_FROM_ZERO, GET_WIDTH }
## Protected Member Functions
void | absolute_top_line_number (int oldFirstChar)
| Line numbering stuff, currently unused.
void | calc_last_char ()
| Update last display character index.
void | calc_line_starts (int startLine, int endLine)
| Update the line start arrays.
void | clear_rect (int style, int x, int y, int width, int height) const
| Clear a rectangle with the appropriate background color for `style`.
void | display_insert ()
| Scroll the display to bring insertion cursor into view.
virtual void | draw ()
| Draw the widget.
void | draw_cursor (int, int)
| Draw a cursor with top center at `X`, `Y`.
void | draw_line_numbers (bool clearAll)
| Refresh the line number area.
void | draw_range (int start, int end)
| Draw a range of text.
void | draw_string (int style, int x, int y, int toX, const char *string, int nChars) const
| Draw a text segment in a single style.
void | draw_text (int X, int Y, int W, int H)
| Refresh a rectangle of the text display.
void | draw_vline (int visLineNum, int leftClip, int rightClip, int leftCharIndex, int rightCharIndex)
| Draw a single line of text.
int | empty_vlines () const
| Return true if there are lines visible with no corresponding buffer text.
void | extend_range_for_styles (int *start, int *end)
| I don't know what this does!
void | find_line_end (int pos, bool start_pos_is_line_start, int *lineEnd, int *nextLineStart) const
| Finds both the end of the current line and the start of the next line.
void | find_wrap_range (const char *deletedText, int pos, int nInserted, int nDeleted, int *modRangeStart, int *modRangeEnd, int *linesInserted, int *linesDeleted)
| Wrapping calculations.
int | find_x (const char *s, int len, int style, int x) const
| Find the index of the character that lies at the given x position.
int | get_absolute_top_line_number () const
| Line numbering stuff, currently unused.
int | handle_vline (int mode, int lineStart, int lineLen, int leftChar, int rightChar, int topClip, int bottomClip, int leftClip, int rightClip) const
| Universal pixel machine.
int | longest_vline () const
| Find the longest line of all visible lines.
void | maintain_absolute_top_line_number (int state)
| Line numbering stuff, currently unused.
int | maintaining_absolute_top_line_number () const
| Line numbering stuff, currently unused.
void | measure_deleted_lines (int pos, int nDeleted)
| Wrapping calculations.
double | measure_proportional_character (const char *s, int colNum, int pos) const
| Wrapping calculations.
int | measure_vline (int visLineNum) const
| Returns the width in pixels of the displayed line pointed to by "visLineNum".
void | offset_line_starts (int newTopLineNum)
| Offset line start counters for a new vertical scroll position.
int | position_to_line (int pos, int *lineNum) const
| Convert a position index into a line number offset.
int | position_to_linecol (int pos, int *lineNum, int *column) const
| Find the line and column number of position `pos`.
void | reset_absolute_top_line_number ()
| Line numbering stuff, probably unused.
int | scroll_ (int topLineNum, int horizOffset)
| Scrolls the current buffer to start at the specified line and column.
double | string_width (const char *string, int length, int style) const
| Find the width of a string in the font of a particular style.
void | update_h_scrollbar ()
| Update vertical scrollbar.
void | update_line_starts (int pos, int charsInserted, int charsDeleted, int linesInserted, int linesDeleted, int *scrolled)
| Update line start arrays and variables.
void | update_v_scrollbar ()
| Update vertical scrollbar.
int | vline_length (int visLineNum) const
| Count number of bytes in a visible line.
int | wrap_uses_character (int lineEndPos) const
| Check if the line break is caused by a \n or by line wrapping.
void | wrapped_line_counter (Fl_Text_Buffer *buf, int startPos, int maxPos, int maxLines, bool startPosIsLineStart, int styleBufOffset, int *retPos, int *retLines, int *retLineStart, int *retLineEnd, bool countLastLineMissingNewLine=true) const
| Wrapping calculations.
int | xy_to_position (int x, int y, int PosType=CHARACTER_POS) const
| Translate a pixel position into a character index.
void | xy_to_rowcol (int x, int y, int *row, int *column, int PosType=CHARACTER_POS) const
| Translate pixel coordinates into row and column.
## Static Protected Member Functions
static void | buffer_modified_cb (int pos, int nInserted, int nDeleted, int nRestyled, const char *deletedText, void *cbArg)
| This is called whenever the buffer is modified.
static void | buffer_predelete_cb (int pos, int nDeleted, void *cbArg)
| This is called before any characters are deleted.
static void | h_scrollbar_cb (Fl_Scrollbar *w, Fl_Text_Display *d)
| Callbacks for drag or valueChanged on scrollbars.
static void | scroll_timer_cb (void *)
| Timer callback for scroll events.
static void | v_scrollbar_cb (Fl_Scrollbar *w, Fl_Text_Display *d)
| Callbacks for drag or valueChanged on scrollbars.
## Protected Attributes
int | damage_range1_end
int | damage_range1_start
int | damage_range2_end
int | damage_range2_start
int | display_insert_position_hint
int | dragging
int | dragPos
int | dragType
int | mAbsTopLineNum
Fl_Text_Buffer * | mBuffer
double | mColumnScale
int | mContinuousWrap
Fl_Color | mCursor_color
int | mCursorOldY
int | mCursorOn
int | mCursorPos
int | mCursorPreferredXPos
int | mCursorStyle
int | mCursorToHint
int | mFirstChar
void * | mHighlightCBArg
int | mHorizOffset
int | mHorizOffsetHint
Fl_Scrollbar * | mHScrollBar
int | mLastChar
int | mLineNumLeft
int | mLineNumWidth
int * | mLineStarts
int | mMaxsize
int | mModifyingTabDistance
int | mNBufferLines
int | mNeedAbsTopLineNum
int | mNLinesDeleted
int | mNStyles
int | mNVisibleLines
Fl_Text_Buffer * | mStyleBuffer
const Style_Table_Entry * | mStyleTable
int | mSuppressResync
int | mTopLineNum
int | mTopLineNumHint
Unfinished_Style_Cb | mUnfinishedHighlightCB
char | mUnfinishedStyle
Fl_Scrollbar * | mVScrollBar
int | mWrapMarginPix
Fl_Align | scrollbar_align_
int | scrollbar_width_
int | shortcut_
struct {
int h
int w
int x
int y
} | text_area
Fl_Color | textcolor_
Fl_Font | textfont_
Fl_Fontsize | textsize_
## Friends
void | fl_text_drag_me (int pos, Fl_Text_Display *d)

## Detailed Description

Rich text display widget.

This is the FLTK text display widget. It allows the user to view multiple lines of text and supports highlighting and scrolling. The buffer that is displayed in the widget is managed by the Fl_Text_Buffer class. A single Text Buffer can be displayed by multiple Text Displays.

## Member Enumeration Documentation

anonymous enum

text display cursor shapes enumeration

Enumerator:

  NORMAL_CURSOR | I-beam.
  CARET_CURSOR | caret under the text
  DIM_CURSOR | dim I-beam
  BLOCK_CURSOR | unfille box under the current character
  HEAVY_CURSOR | thick I-beam
  SIMPLE_CURSOR | as cursor as Fl_Input cursor

anonymous enum

wrap types - used in wrap_mode()

Enumerator:

  WRAP_NONE | don't wrap text at all
  WRAP_AT_COLUMN | wrap text at the given text column
  WRAP_AT_PIXEL | wrap text at a pixel position
  WRAP_AT_BOUNDS | wrap text so that it fits into the widget width

## Constructor & Destructor Documentation

Fl_Text_Display::Fl_Text_Display | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | const char * | l = `0`
| ) |  |

Creates a new text display widget.

Parameters:

  X,Y,W,H | position and size of widget
  l | label text, defaults to none

Fl_Text_Display::~Fl_Text_Display | ( |  | ) |

Free a text display and release its associated memory.

Note, the text BUFFER that the text display displays is a separate entity and is not freed, nor are the style buffer or style table.

## Member Function Documentation

void Fl_Text_Display::absolute_top_line_number | ( | int | oldFirstChar | ) | `[protected]`

Line numbering stuff, currently unused.

Re-calculate absolute top line number for a change in scroll position.

void Fl_Text_Display::buffer | ( | Fl_Text_Buffer * | buf | ) |

Attach a text buffer to display, replacing the current buffer (if any)

Parameters:

  buf | attach this text buffer

void Fl_Text_Display::buffer | ( | Fl_Text_Buffer & | buf | ) | `[inline]`

Sets the current text buffer associated with the text widget.

Multiple text widgets can be associated with the same text buffer.

Parameters:

  buf | new text buffer

Fl_Text_Buffer* Fl_Text_Display::buffer | ( |  | ) | const`[inline]`

Gets the current text buffer associated with the text widget.

Multiple text widgets can be associated with the same text buffer.

Returns:
  current text buffer

void Fl_Text_Display::buffer_modified_cb | ( | int | pos,
|  | int | nInserted,
|  | int | nDeleted,
|  | int | nRestyled,
|  | const char * | deletedText,
|  | void * | cbArg
| ) |  | `[static, protected]`

This is called whenever the buffer is modified.

Callback attached to the text buffer to receive modification information

This callback can be used to adjust the display or update other setting. It is not advisable to change any buffers or text in this callback, or line counting may get out of sync.

Parameters:

  pos | starting index of modification
  nInserted | number of bytes we inserted (must be UTF-8 aligned!)
  nDeleted | number of bytes deleted (must be UTF-8 aligned!)
  nRestyled | ??
  deletedText | this is what was removed, must not be NULL if nDeleted is set
  cbArg | "this" pointer for static callback function

void Fl_Text_Display::buffer_predelete_cb | ( | int | pos,
|  | int | nDeleted,
|  | void * | cbArg
| ) |  | `[static, protected]`

This is called before any characters are deleted.

Callback attached to the text buffer to receive delete information before the modifications are actually made.

This callback can be used to adjust the display or update other setting. It is not advisable to change any buffers or text in this callback, or line counting may get out of sync.

Parameters:

  pos | starting index of deletion
  nDeleted | number of bytes we will delete (must be UTF-8 aligned!)
  cbArg | "this" pointer for static callback function

void Fl_Text_Display::calc_last_char | ( |  | ) | `[protected]`

Update last display character index.

Given a Fl_Text_Display with a complete, up-to-date lineStarts array, update the lastChar entry to point to the last buffer position displayed.

void Fl_Text_Display::calc_line_starts | ( | int | startLine,
|  | int | endLine
| ) |  | `[protected]`

Update the line start arrays.

Scan through the text in the "textD"'s buffer and recalculate the line starts array values beginning at index "startLine" and continuing through (including) "endLine". It assumes that the line starts entry preceding "startLine" (or mFirstChar if startLine is 0) is good, and re-counts newlines to fill in the requested entries. Out of range values for "startLine" and "endLine" are acceptable.

Parameters:

  startLine,endLine | range of lines to scan as line numbers

void Fl_Text_Display::clear_rect | ( | int | style,
|  | int | X,
|  | int | Y,
|  | int | width,
|  | int | height
| ) |  | const`[protected]`

Clear a rectangle with the appropriate background color for `style`.

Parameters:

  style | index into style table
  X,Y,width,height | size and position of background area

double Fl_Text_Display::col_to_x | ( | double | col | ) | const

Convert a column number into an x pixel position.

Parameters:

  col | an approximate column number based on the main font

Returns:
  number of pixels from the left margin to the left of an average sized character

int Fl_Text_Display::count_lines | ( | int | startPos,
|  | int | endPos,
|  | bool | startPosIsLineStart
| ) |  | const

Count the number of lines between two positions.

Same as BufCountLines, but takes into account wrapping if wrapping is turned on. If the caller knows that `startPos` is at a line start, it can pass `startPosIsLineStart` as True to make the call more efficient by avoiding the additional step of scanning back to the last newline.

Parameters:

  startPos | index to first character
  endPos | index after last character
  startPosIsLineStart | avoid scanning back to the line start

Returns:
  number of lines

Fl_Color Fl_Text_Display::cursor_color | ( |  | ) | const`[inline]`

Gets the text cursor color.

Returns:
  cursor color

void Fl_Text_Display::cursor_color | ( | Fl_Color | n | ) | `[inline]`

Sets the text cursor color.

Parameters:

  n | new cursor color

void Fl_Text_Display::cursor_style | ( | int | style | ) |

Sets the text cursor style.

Sets the text cursor style to one of the following:

- Fl_Text_Display::NORMAL_CURSOR - Shows an I beam.
- Fl_Text_Display::CARET_CURSOR - Shows a caret under the text.
- Fl_Text_Display::DIM_CURSOR - Shows a dimmed I beam.
- Fl_Text_Display::BLOCK_CURSOR - Shows an unfilled box around the current character.
- Fl_Text_Display::HEAVY_CURSOR - Shows a thick I beam.

This call also switches the cursor on and may trigger a redraw.

Parameters:

  style | new cursor style

void Fl_Text_Display::display_insert | ( |  | ) | `[protected]`

Scroll the display to bring insertion cursor into view.

Note: it would be nice to be able to do this without counting lines twice (scroll_() counts them too) and/or to count from the most efficient starting point, but the efficiency of this routine is not as important to the overall performance of the text display.

Todo:
  Unicode?

void Fl_Text_Display::draw | ( | void |  | ) | `[protected, virtual]`

Draw the widget.

This function tries to limit drawing to smaller areas if possible.

Reimplemented from Fl_Group.

void Fl_Text_Display::draw_cursor | ( | int | X,
|  | int | Y
| ) |  | `[protected]`

Draw a cursor with top center at `X`, `Y`.

Parameters:

  X,Y | cursor position in pixels

void Fl_Text_Display::draw_line_numbers | ( | bool | clearAll | ) | `[protected]`

Refresh the line number area.

If clearAll is False, writes only over the character cell areas. Setting clearAll to True will clear out any stray marks outside of the character cell area, which might have been left from before a resize or font change.

This function is not used.

void Fl_Text_Display::draw_range | ( | int | startpos,
|  | int | endpos
| ) |  | `[protected]`

Draw a range of text.

Refresh all of the text between buffer positions `startpos` and `endpos` not including the character at the position `endpos`.

If `endpos` points beyond the end of the buffer, refresh the whole display after `startpos`, including blank lines which are not technically part of any range of characters.

Parameters:

  startpos | index of first character to draw
  endpos | index after last character to draw

void Fl_Text_Display::draw_string | ( | int | style,
|  | int | X,
|  | int | Y,
|  | int | toX,
|  | const char * | string,
|  | int | nChars
| ) |  | const`[protected]`

Draw a text segment in a single style.

Draw a string or blank area according to parameter `style`, using the appropriate colors and drawing method for that style, with top left corner at `X`, `Y`. If style says to draw text, use `string` as source of characters, and draw `nChars`, if style is FILL, erase rectangle where text would have drawn from `X` to `toX` and from `Y` to the maximum y extent of the current font(s).

Parameters:

  style | index into style lookup table
  X,Y | drawing origin
  toX | rightmost position if this is a fill operation
  string | text if this is a drawing operation
  nChars | number of characters to draw

void Fl_Text_Display::draw_text | ( | int | left,
|  | int | top,
|  | int | width,
|  | int | height
| ) |  | `[protected]`

Refresh a rectangle of the text display.

Parameters:

  left,top | are in coordinates of the text drawing window.
  width,height | size in pixels

void Fl_Text_Display::draw_vline | ( | int | visLineNum,
|  | int | leftClip,
|  | int | rightClip,
|  | int | leftCharIndex,
|  | int | rightCharIndex
| ) |  | `[protected]`

Draw a single line of text.

Draw the text on a single line represented by `visLineNum` (the number of lines down from the top of the display), limited by `leftClip` and `rightClip` window coordinates and `leftCharIndex` and `rightCharIndex` character positions (not including the character at position `rightCharIndex`).

Parameters:

  visLineNum | index of line in the visible line number lookup
  leftClip,rightClip | pixel position of clipped area
  leftCharIndex,rightCharIndex | index into line of segment that we want to draw

int Fl_Text_Display::empty_vlines | ( |  | ) | const`[protected]`

Return true if there are lines visible with no corresponding buffer text.

Returns:
  1 if there are empty lines

void Fl_Text_Display::extend_range_for_styles | ( | int * | startpos,
|  | int * | endpos
| ) |  | `[protected]`

I don't know what this does!

Extend the range of a redraw request (from *start to *end) with additional redraw requests resulting from changes to the attached style buffer (which contains auxiliary information for coloring or styling text).

Parameters:

  startpos | ??
  endpos | ??

Todo:
  Unicode?

void Fl_Text_Display::find_line_end | ( | int | startPos,
|  | bool | startPosIsLineStart,
|  | int * | lineEnd,
|  | int * | nextLineStart
| ) |  | const`[protected]`

Finds both the end of the current line and the start of the next line.

Why? In continuous wrap mode, if you need to know both, figuring out one from the other can be expensive or error prone. The problem comes when there's a trailing space or tab just before the end of the buffer. To translate an end of line value to or from the next lines start value, you need to know whether the trailing space or tab is being used as a line break or just a normal character, and to find that out would otherwise require counting all the way back to the beginning of the line.

Parameters:

  | startPos |
  | startPosIsLineStart |
  [out] | lineEnd |
  [out] | nextLineStart |

void Fl_Text_Display::find_wrap_range | ( | const char * | deletedText,
|  | int | pos,
|  | int | nInserted,
|  | int | nDeleted,
|  | int * | modRangeStart,
|  | int * | modRangeEnd,
|  | int * | linesInserted,
|  | int * | linesDeleted
| ) |  | `[protected]`

Wrapping calculations.

When continuous wrap is on, and the user inserts or deletes characters, wrapping can happen before and beyond the changed position. This routine finds the extent of the changes, and counts the deleted and inserted lines over that range. It also attempts to minimize the size of the range to what has to be counted and re-displayed, so the results can be useful both for delimiting where the line starts need to be recalculated, and for deciding what part of the text to redisplay.

Parameters:

  deletedText |
  pos |
  nInserted |
  nDeleted |
  modRangeStart |
  modRangeEnd |
  linesInserted |
  linesDeleted |

int Fl_Text_Display::find_x | ( | const char * | s,
|  | int | len,
|  | int | style,
|  | int | x
| ) |  | const`[protected]`

Find the index of the character that lies at the given x position.

Parameters:

  s | UTF-8 text string
  len | length of string
  style | index into style lookup table
  x | position in pixels

Returns:
  index into buffer

int Fl_Text_Display::get_absolute_top_line_number | ( |  | ) | const`[protected]`

Line numbering stuff, currently unused.

Returns the absolute (non-wrapped) line number of the first line displayed. Returns 0 if the absolute top line number is not being maintained.

int Fl_Text_Display::handle_vline | ( | int | mode,
|  | int | lineStartPos,
|  | int | lineLen,
|  | int | leftChar,
|  | int | rightChar,
|  | int | Y,
|  | int | bottomClip,
|  | int | leftClip,
|  | int | rightClip
| ) |  | const`[protected]`

Universal pixel machine.

We use a single function that handles all line layout, measuring, and drawing

- draw a text range
- return the width of a text range in pixels
- return the index of a character that is at a pixel position

Parameters:

  [in] | mode | DRAW_LINE, GET_WIDTH, FIND_INDEX
  [in] | lineStartPos | index of first character
  [in] | lineLen | size of string in bytes
  [in] | leftChar,rightChar |
  [in] | Y | drawing position
  [in] | bottomClip,leftClip,rightClip | stop work when we reach the clipped area. rightClip is the X position that we search in FIND_INDEX.

Return values:

  DRAW_LINE | index of last drawn character
  GET_WIDTH | width in pixels of text segment if we would draw it
  FIND_INDEX | index of character at given x position in window coordinates
  FIND_INDEX_FROM_ZERO | index of character at given x position without scrolling and widget offsets

Todo:

  we need to handle hidden hyphens and tabs here!

  we handle all styles and selections

  we must provide code to get pixel positions of the middle of a character as well

void Fl_Text_Display::highlight_data | ( | Fl_Text_Buffer * | styleBuffer,
|  | const Style_Table_Entry * | styleTable,
|  | int | nStyles,
|  | char | unfinishedStyle,
|  | Unfinished_Style_Cb | unfinishedHighlightCB,
|  | void * | cbArg
| ) |  |

Attach (or remove) highlight information in text display and redisplay.

Highlighting information consists of a style buffer which parallels the normal text buffer, but codes font and color information for the display; a style table which translates style buffer codes (indexed by buffer character - 'A') into fonts and colors; and a callback mechanism for as-needed highlighting, triggered by a style buffer entry of "unfinishedStyle". Style buffer can trigger additional redisplay during a normal buffer modification if the buffer contains a primary Fl_Text_Selection (see extendRangeForStyleMods for more information on this protocol).

Style buffers, tables and their associated memory are managed by the caller.

Styles are ranged from 65 ('A') to 126.

Parameters:

  styleBuffer | this buffer works in parallel to the text buffer. For every character in the text buffer, the stye buffer has a byte at the same offset that contains an index into an array of possible styles.
  styleTable | a list of styles indexed by the style buffer
  nStyles | number of styles in the style table
  unfinishedStyle | if this style is found, the callback below is called
  unfinishedHighlightCB | if a character with an unfinished style is found, this callback will be called
  cbArg | and optional argument for the callback above, usually a pointer to the Text Display.

int Fl_Text_Display::in_selection | ( | int | X,
|  | int | Y
| ) |  | const

Check if a pixel position is within the primary selection.

Parameters:

  X,Y | pixel position to test

Returns:
  1 if position (X, Y) is inside of the primary Fl_Text_Selection

void Fl_Text_Display::insert | ( | const char * | text | ) |

Inserts "text" at the current cursor location.

This has the same effect as inserting the text into the buffer using BufInsert and then moving the insert position after the newly inserted text, except that it's optimized to do less redrawing.

Parameters:

  text | new text in UTF-8 encoding.

void Fl_Text_Display::insert_position | ( | int | newPos | ) |

Sets the position of the text insertion cursor for text display.

Move the insertion cursor in front of the character at `newPos`. This function may trigger a redraw.

Parameters:

  newPos | new caret position

int Fl_Text_Display::insert_position | ( |  | ) | const`[inline]`

Gets the position of the text insertion cursor for text display.

Returns:
  insert position index into text buffer

int Fl_Text_Display::line_end | ( | int | startPos,
|  | bool | startPosIsLineStart
| ) |  | const

Returns the end of a line.

Same as BufEndOfLine, but takes into account line breaks when wrapping is turned on. If the caller knows that `startPos` is at a line start, it can pass "startPosIsLineStart" as True to make the call more efficient by avoiding the additional step of scanning back to the last newline.

Note that the definition of the end of a line is less clear when continuous wrap is on. With continuous wrap off, it's just a pointer to the newline that ends the line. When it's on, it's the character beyond the last displayable character on the line, where a whitespace character which has been "converted" to a newline for wrapping is not considered displayable. Also note that a line can be wrapped at a non-whitespace character if the line had no whitespace. In this case, this routine returns a pointer to the start of the next line. This is also consistent with the model used by visLineLength.

Parameters:

  startPos | index to starting character
  startPosIsLineStart | avoid scanning back to the line start

Returns:
  new position as index

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

Return the beginning of a line.

Same as BufStartOfLine, but returns the character after last wrap point rather than the last newline.

Parameters:

  pos | index to starting character

Returns:
  new position as index

int Fl_Text_Display::longest_vline | ( |  | ) | const`[protected]`

Find the longest line of all visible lines.

Returns:
  the width of the longest visible line in pixels

void Fl_Text_Display::maintain_absolute_top_line_number | ( | int | state | ) | `[protected]`

Line numbering stuff, currently unused.

In continuous wrap mode, internal line numbers are calculated after wrapping. A separate non-wrapped line count is maintained when line numbering is turned on. There is some performance cost to maintaining this line count, so normally absolute line numbers are not tracked if line numbering is off. This routine allows callers to specify that they still want this line count maintained (for use via TextDPosToLineAndCol). More specifically, this allows the line number reported in the statistics line to be calibrated in absolute lines, rather than post-wrapped lines.

int Fl_Text_Display::maintaining_absolute_top_line_number | ( |  | ) | const`[protected]`

Line numbering stuff, currently unused.

Return true if a separate absolute top line number is being maintained (for displaying line numbers or showing in the statistics line).

void Fl_Text_Display::measure_deleted_lines | ( | int | pos,
|  | int | nDeleted
| ) |  | `[protected]`

Wrapping calculations.

This is a stripped-down version of the findWrapRange() function above, intended to be used to calculate the number of "deleted" lines during a buffer modification. It is called _before_ the modification takes place.

This function should only be called in continuous wrap mode with a non-fixed font width. In that case, it is impossible to calculate the number of deleted lines, because the necessary style information is no longer available _after_ the modification. In other cases, we can still perform the calculation afterwards (possibly even more efficiently).

Parameters:

  pos |
  nDeleted |

double Fl_Text_Display::measure_proportional_character | ( | const char * | s,
|  | int | xPix,
|  | int | pos
| ) |  | const`[protected]`

Wrapping calculations.

Measure the width in pixels of the first character of string "s" at a particular column "colNum" and buffer position "pos". This is for measuring characters in proportional or mixed-width highlighting fonts.

A note about proportional and mixed-width fonts: the mixed width and proportional font code in nedit does not get much use in general editing, because nedit doesn't allow per-language-mode fonts, and editing programs in a proportional font is usually a bad idea, so very few users would choose a proportional font as a default. There are still probably mixed- width syntax highlighting cases where things don't redraw properly for insertion/deletion, though static display and wrapping and resizing should now be solid because they are now used for online help display.

Parameters:

  s | text string
  xPix | x pixel position needed for calculating tab widths
  pos | offset within string

Returns:
  width of character in pixels

int Fl_Text_Display::measure_vline | ( | int | visLineNum | ) | const`[protected]`

Returns the width in pixels of the displayed line pointed to by "visLineNum".

Parameters:

  visLineNum | index into visible lines array

Returns:
  width of line in pixels

int Fl_Text_Display::move_down | ( |  | ) |

Moves the current insert position down one line.

Returns:
  1 if the cursor moved, 0 if the beginning of the text was reached

int Fl_Text_Display::move_left | ( |  | ) |

Moves the current insert position left one character.

Returns:
  1 if the cursor moved, 0 if the beginning of the text was reached

int Fl_Text_Display::move_right | ( |  | ) |

Moves the current insert position right one character.

Returns:
  1 if the cursor moved, 0 if the end of the text was reached

int Fl_Text_Display::move_up | ( |  | ) |

Moves the current insert position up one line.

Returns:
  1 if the cursor moved, 0 if the beginning of the text was reached

void Fl_Text_Display::offset_line_starts | ( | int | newTopLineNum | ) | `[protected]`

Offset line start counters for a new vertical scroll position.

Offset the line starts array, mTopLineNum, mFirstChar and lastChar, for a new vertical scroll position given by newTopLineNum. If any currently displayed lines will still be visible, salvage the line starts values, otherwise, count lines from the nearest known line start (start or end of buffer, or the closest value in the mLineStarts array)

Parameters:

  newTopLineNum | index into buffer

void Fl_Text_Display::overstrike | ( | const char * | text | ) |

Replaces text at the current insert position.

Parameters:

  text | new text in UTF-8 encoding

Todo:
  Unicode? Find out exactly what we do here and simplify.

int Fl_Text_Display::position_style | ( | int | lineStartPos,
|  | int | lineLen,
|  | int | lineIndex
| ) |  | const

Find the correct style for a character.

Determine the drawing method to use to draw a specific character from "buf". `lineStartPos` gives the character index where the line begins, `lineIndex`, the number of characters past the beginning of the line, and `lineIndex` the number of displayed characters past the beginning of the line. Passing `lineStartPos` of -1 returns the drawing style for "no text".

Why not just: position_style(pos)? Because style applies to blank areas of the window beyond the text boundaries, and because this routine must also decide whether a position is inside of a rectangular Fl_Text_Selection, and do so efficiently, without re-counting character positions from the start of the line.

Note that style is a somewhat incorrect name, drawing method would be more appropriate.

Parameters:

  lineStartPos | beginning of this line
  lineLen | number of bytes in line
  lineIndex | position of character within line

Returns:
  style for the given character

int Fl_Text_Display::position_to_line | ( | int | pos,
|  | int * | lineNum
| ) |  | const`[protected]`

Convert a position index into a line number offset.

Find the line number of position `pos` relative to the first line of displayed text. Returns 0 if the line is not displayed.

Parameters:

  | pos | ??
  [out] | lineNum | ??

Returns:
  ??

Todo:
  What does this do?

int Fl_Text_Display::position_to_linecol | ( | int | pos,
|  | int * | lineNum,
|  | int * | column
| ) |  | const`[protected]`

Find the line and column number of position `pos`.

This only works for displayed lines. If the line is not displayed, the function returns 0 (without the mLineStarts array it could turn in to very long calculation involving scanning large amounts of text in the buffer). If continuous wrap mode is on, returns the absolute line number (as opposed to the wrapped line number which is used for scrolling).

Parameters:

  | pos | character index
  [out] | lineNum | absolute (unwrapped) line number
  [out] | column | character offset to the beginning of the line

Returns:
  0 if `pos` is off screen, line number otherwise

Todo:
  a column number makes little sense in the UTF-8/variable font width environment. We will have to further define what exactly we want to return. Please check the functions that call this particular function.

int Fl_Text_Display::position_to_xy | ( | int | pos,
|  | int * | X,
|  | int * | Y
| ) |  | const

Convert a character index into a pixel position.

Translate a buffer text position to the XY location where the top left of the cursor would be positioned to point to that character. Returns 0 if the position is not displayed because it is vertically out of view. If the position is horizontally out of view, returns the X coordinate where the position would be if it were visible.

Parameters:

  | pos | character index
  [out] | X,Y | pixel position of character on screen

Returns:
  0 if character vertically out of view, X & Y positions otherwise

void Fl_Text_Display::redisplay_range | ( | int | startpos,
|  | int | endpos
| ) |  |

Marks text from start to end as needing a redraw.

This function will trigger a damage event and later a redraw of parts of the widget.

Parameters:

  startpos | index of first character needing redraw
  endpos | index after last character needing redraw

void Fl_Text_Display::reset_absolute_top_line_number | ( |  | ) | `[protected]`

Line numbering stuff, probably unused.

Count lines from the beginning of the buffer to reestablish the absolute (non-wrapped) top line number. If mode is not continuous wrap, or the number is not being maintained, does nothing.

void Fl_Text_Display::resize | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H
| ) |  | `[virtual]`

Change the size of the displayed text area.

Calling this function will trigger a recalculation of all lines visible and of all scrollbar sizes.

Parameters:

  X,Y,W,H | new position and size of this widget

Reimplemented from Fl_Group.

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

Skip a number of lines back.

Same as BufCountBackwardNLines, but takes into account line breaks when wrapping is turned on.

Parameters:

  startPos | index to starting character
  nLines | number of lines to skip back

Returns:
  new position as index

void Fl_Text_Display::scroll | ( | int | topLineNum,
|  | int | horizOffset
| ) |  |

Scrolls the current buffer to start at the specified line and column.

Parameters:

  topLineNum | top line number
  horizOffset | column number

Todo:
  Column numbers make little sense here.

int Fl_Text_Display::scroll_ | ( | int | topLineNum,
|  | int | horizOffset
| ) |  | `[protected]`

Scrolls the current buffer to start at the specified line and column.

Parameters:

  topLineNum | top line number
  horizOffset | in pixels

Returns:
  0 if nothing changed, 1 if we scrolled

void Fl_Text_Display::scroll_timer_cb | ( | void * | user_data | ) | `[static, protected]`

Timer callback for scroll events.

This timer event scrolls the text view proportionally to how far the mouse pointer has left the text area. This allows for smooth scrolling without "wiggeling" the mouse.

Fl_Align Fl_Text_Display::scrollbar_align | ( |  | ) | const`[inline]`

Gets the scrollbar alignment type.

Returns:
  scrollbar alignment

void Fl_Text_Display::scrollbar_align | ( | Fl_Align | a | ) | `[inline]`

Sets the scrollbar alignment type.

Parameters:

  a | new scrollbar alignment

int Fl_Text_Display::scrollbar_width | ( |  | ) | const`[inline]`

Gets the width/height of the scrollbars.

/return width of scrollbars

void Fl_Text_Display::scrollbar_width | ( | int | W | ) | `[inline]`

Sets the width/height of the scrollbars.

Parameters:

  W | width of scrollbars

int Fl_Text_Display::shortcut | ( |  | ) | const`[inline]`

Todo:
  FIXME : get set methods pointing on shortcut_ have no effects as shortcut_ is unused in this class and derived!

Returns:
  the current shortcut key

void Fl_Text_Display::shortcut | ( | int | s | ) | `[inline]`

Todo:
  FIXME : get set methods pointing on shortcut_ have no effects as shortcut_ is unused in this class and derived!

Parameters:

  s | the new shortcut key

void Fl_Text_Display::show_cursor | ( | int | b = `1` | ) |

Shows the text cursor.

This function may trigger a redraw.

Parameters:

  b | show(1) or hide(0) the text cursor (caret).

void Fl_Text_Display::show_insert_position | ( |  | ) |

Scrolls the text buffer to show the current insert position.

This function triggers a complete recalculation, ending in a call to Fl_Text_Display::display_insert()

int Fl_Text_Display::skip_lines | ( | int | startPos,
|  | int | nLines,
|  | bool | startPosIsLineStart
| ) |  |

Skip a number of lines forward.

Same as BufCountForwardNLines, but takes into account line breaks when wrapping is turned on. If the caller knows that startPos is at a line start, it can pass "startPosIsLineStart" as True to make the call more efficient by avoiding the additional step of scanning back to the last newline.

Parameters:

  startPos | index to starting character
  nLines | number of lines to skip ahead
  startPosIsLineStart | avoid scanning back to the line start

Returns:
  new position as index

double Fl_Text_Display::string_width | ( | const char * | string,
|  | int | length,
|  | int | style
| ) |  | const`[protected]`

Find the width of a string in the font of a particular style.

Parameters:

  string | the text
  length | number of bytes in string
  style | index into style table

Returns:
  width of text segment in pixels

Fl_Color Fl_Text_Display::textcolor | ( |  | ) | const`[inline]`

Gets the default color of text in the widget.

Returns:
  text color unless overridden by a style

void Fl_Text_Display::textcolor | ( | Fl_Color | n | ) | `[inline]`

Sets the default color of text in the widget.

Parameters:

  n | new text color

Fl_Font Fl_Text_Display::textfont | ( |  | ) | const`[inline]`

Gets the default font used when drawing text in the widget.

Returns:
  current text font face unless overridden by a style

void Fl_Text_Display::textfont | ( | Fl_Font | s | ) | `[inline]`

Sets the default font used when drawing text in the widget.

Parameters:

  s | default text font face

Fl_Fontsize Fl_Text_Display::textsize | ( |  | ) | const`[inline]`

Gets the default size of text in the widget.

Returns:
  current text height unless overridden by a style

void Fl_Text_Display::textsize | ( | Fl_Fontsize | s | ) | `[inline]`

Sets the default size of text in the widget.

Parameters:

  s | new text size

void Fl_Text_Display::update_h_scrollbar | ( |  | ) | `[protected]`

Update vertical scrollbar.

Update the minimum, maximum, slider size, page increment, and value for the horizontal scrollbar.

void Fl_Text_Display::update_line_starts | ( | int | pos,
|  | int | charsInserted,
|  | int | charsDeleted,
|  | int | linesInserted,
|  | int | linesDeleted,
|  | int * | scrolled
| ) |  | `[protected]`

Update line start arrays and variables.

Update the line starts array, mTopLineNum, mFirstChar and lastChar for this text display after a modification to the text buffer, given by the position `pos` where the change began, and the numbers of characters and lines inserted and deleted.

Parameters:

  | pos | index into buffer of recent changes
  | charsInserted | number of bytes(!) inserted
  | charsDeleted | number of bytes(!) deleted
  | linesInserted | number of lines
  | linesDeleted | number of lines
  [out] | scrolled | set to 1 if the text display needs to be scrolled

void Fl_Text_Display::update_v_scrollbar | ( |  | ) | `[protected]`

Update vertical scrollbar.

Update the minimum, maximum, slider size, page increment, and value for vertical scrollbar.

int Fl_Text_Display::vline_length | ( | int | visLineNum | ) | const`[protected]`

Count number of bytes in a visible line.

Return the length of a line (number of bytes) by examining entries in the line starts array rather than by scanning for newlines.

Parameters:

  visLineNum | index of line in visible line array

Returns:
  number of bytes in this line

int Fl_Text_Display::word_end | ( | int | pos | ) | const`[inline]`

Moves the insert position to the end of the current word.

Parameters:

  pos | start calculation at this index

Returns:
  index of first character after the end of the word

int Fl_Text_Display::word_start | ( | int | pos | ) | const`[inline]`

Moves the insert position to the beginning of the current word.

Parameters:

  pos | start calculation at this index

Returns:
  beginning of the words

void Fl_Text_Display::wrap_mode | ( | int | wrap,
|  | int | wrapMargin
| ) |  |

Set the new text wrap mode.

If `wrap` mode is not zero, this call enables automatic word wrapping at column `wrapMargin`. Word-wrapping does not change the text buffer itself, only the way the text is displayed. Different Text Displays can have different wrap modes, even if they share the same Text Buffer.

Parameters:

  wrap | new wrap mode is WRAP_NONE (don't wrap text at all), WRAP_AT_COLUMN (wrap text at the given text column), WRAP_AT_PIXEL (wrap text at a pixel position), or WRAP_AT_BOUNDS (wrap text so that it fits into the widget width)
  wrapMargin | in WRAP_AT_COLUMN mode, text will wrap at the n'th character. For variable width fonts, an average character width is calculated. The column width is calculated using the current textfont or the first style when this function is called. If the font size changes, this function must be called again. In WRAP_AT_PIXEL mode, this is the pixel position.

Todo:
  we need new wrap modes to wrap at the window edge and based on pixel width or average character width.

int Fl_Text_Display::wrap_uses_character | ( | int | lineEndPos | ) | const`[protected]`

Check if the line break is caused by a \n or by line wrapping.

Line breaks in continuous wrap mode usually happen at newlines or whitespace. This line-terminating character is not included in line width measurements and has a special status as a non-visible character. However, lines with no whitespace are wrapped without the benefit of a line terminating character, and this distinction causes endless trouble with all of the text display code which was originally written without continuous wrap mode and always expects to wrap at a newline character.

Given the position of the end of the line, as returned by TextDEndOfLine or BufEndOfLine, this returns true if there is a line terminating character, and false if there's not. On the last character in the buffer, this function can't tell for certain whether a trailing space was used as a wrap point, and just guesses that it wasn't. So if an exact accounting is necessary, don't use this function.

Parameters:

  lineEndPos | index of character where the line wraps

Returns:
  1 if a \n character causes the line wrap

int Fl_Text_Display::wrapped_column | ( | int | row,
|  | int | column
| ) |  | const

Nobody knows what this function does.

Correct a column number based on an unconstrained position (as returned by TextDXYToUnconstrainedPosition) to be relative to the last actual newline in the buffer before the row and column position given, rather than the last line start created by line wrapping. This is an adapter for rectangular selections and code written before continuous wrap mode, which thinks that the unconstrained column is the number of characters from the last newline. Obviously this is time consuming, because it invloves character re-counting.

Parameters:

  row |
  column |

Returns:
  something unknown

Todo:
  What does this do and how is it useful? Column numbers mean little in this context. Which functions depend on this one?

Todo:
  Unicode?

void Fl_Text_Display::wrapped_line_counter | ( | Fl_Text_Buffer * | buf,
|  | int | startPos,
|  | int | maxPos,
|  | int | maxLines,
|  | bool | startPosIsLineStart,
|  | int | styleBufOffset,
|  | int * | retPos,
|  | int * | retLines,
|  | int * | retLineStart,
|  | int * | retLineEnd,
|  | bool | countLastLineMissingNewLine = `true`
| ) |  | const`[protected]`

Wrapping calculations.

Count forward from startPos to either maxPos or maxLines (whichever is reached first), and return all relevant positions and line count. The provided textBuffer may differ from the actual text buffer of the widget. In that case it must be a (partial) copy of the actual text buffer and the styleBufOffset argument must indicate the starting position of the copy, to take into account the correct style information.

Parameters:

  | buf |
  | startPos |
  | maxPos |
  | maxLines |
  | startPosIsLineStart |
  | styleBufOffset |
  [out] | retPos | Position where counting ended. When counting lines, the position returned is the start of the line "maxLines" lines beyond "startPos".
  [out] | retLines | Number of line breaks counted
  [out] | retLineStart | Start of the line where counting ended
  [out] | retLineEnd | End position of the last line traversed
  [out] | countLastLineMissingNewLine |

int Fl_Text_Display::wrapped_row | ( | int | row | ) | const

Nobody knows what this function does.

Correct a row number from an unconstrained position (as returned by TextDXYToUnconstrainedPosition) to a straight number of newlines from the top line of the display. Because rectangular selections are based on newlines, rather than display wrapping, and anywhere a rectangular selection needs a row, it needs it in terms of un-wrapped lines.

Parameters:

  row |

Returns:
  something unknown

Todo:
  What does this do and how is it useful? Column numbers mean little in this context. Which functions depend on this one?

double Fl_Text_Display::x_to_col | ( | double | x | ) | const

Convert an x pixel position into a column number.

Parameters:

  x | number of pixels from the left margin

Returns:
  an approximate column number based on the main font

int Fl_Text_Display::xy_to_position | ( | int | X,
|  | int | Y,
|  | int | posType = `CHARACTER_POS`
| ) |  | const`[protected]`

Translate a pixel position into a character index.

Translate window coordinates to the nearest (insert cursor or character cell) text position. The parameter `posType` specifies how to interpret the position: CURSOR_POS means translate the coordinates to the nearest cursor position, and CHARACTER_POS means return the position of the character closest to (`X`, `Y`).

Parameters:

  X,Y | pixel position
  posType | CURSOR_POS or CHARACTER_POS

Returns:
  index into text buffer

void Fl_Text_Display::xy_to_rowcol | ( | int | X,
|  | int | Y,
|  | int * | row,
|  | int * | column,
|  | int | posType = `CHARACTER_POS`
| ) |  | const`[protected]`

Translate pixel coordinates into row and column.

Translate window coordinates to the nearest row and column number for positioning the cursor. This, of course, makes no sense when the font is proportional, since there are no absolute columns. The parameter posType specifies how to interpret the position: CURSOR_POS means translate the coordinates to the nearest position between characters, and CHARACTER_POS means translate the position to the nearest character cell.

Parameters:

  | X,Y | pixel coordinates
  [out] | row,column | neares row and column
  | posType | CURSOR_POS or CHARACTER_POS

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

- Fl_Text_Display.H
- Fl_Text_Display.cxx