FLTK 1.4.5: Fl_Text_Selection Class Reference

FLTK 1.4.5

Loading...
Searching...
No Matches
Fl_Text_Selection Class Reference

This is an internal class for Fl_Text_Buffer to manage text selections. More...

`#include <Fl_Text_Buffer.H>`

## Public Member Functions
int | end () const
| Returns the byte offset to the character after the last selected character.
int | includes (int pos) const
| Returns true if position `pos` is in the Fl_Text_Selection.
int | length () const
| Returns the size in bytes of the selection.
int | position (int *startpos, int *endpos) const
bool | selected () const
| Returns true if any text is selected.
void | selected (bool b)
| Modifies the 'selected' flag.
int | selected (int *startpos, int *endpos) const
| Returns the status and the positions of this selection.
void | set (int startpos, int endpos)
| Sets the selection range.
int | start () const
| Returns the byte offset to the first selected character.
void | update (int pos, int nDeleted, int nInserted)
| Updates a selection after text was modified.

## Protected Attributes
int | mEnd
| byte offset to the character after the last selected character
bool | mSelected
| this flag is set if any text is selected
int | mStart
| byte offset to the first selected character

## Friends
class | Fl_Text_Buffer

## Detailed Description

This is an internal class for Fl_Text_Buffer to manage text selections.

All methods use byte (not UTF-8 character) offsets and start at 0. This class works correctly with UTF-8 strings assuming that the parameters for all calls are on character boundaries.

If the selection is inactive (not currently used), then selected() returns `false` and start() and end() return 0 (zero).

The stored offsets are in ascending order, hence the following conditions are true (pseudo code):

if ( !selected() ) : (start() == 0) && (end() == 0) && (start() == end())
if ( selected() ) : start() < end()
always : 0 <= start() <= end()
always : length() == end() - start()
Fl_Text_Selection::end
int end() const
Returns the byte offset to the character after the last selected character.
Definition Fl_Text_Buffer.H:135
Fl_Text_Selection::selected
bool selected() const
Returns true if any text is selected.
Definition Fl_Text_Buffer.H:142
Fl_Text_Selection::start
int start() const
Returns the byte offset to the first selected character.
Definition Fl_Text_Buffer.H:122
Fl_Text_Selection::length
int length() const
Returns the size in bytes of the selection.
Definition Fl_Text_Buffer.H:163

The selection size in bytes can always (unconditionally) be computed by

int size = sel->end() - sel->start();

See also
  length()

Note
  The protected member variables `mStart` and `mEnd` are not necessarily 0 (zero) if mSelected == `false` because they are not cleared when `selected(false)` is called (as of Jul 2017). This may be changed in the future.

## Member Function Documentation

## ◆ end()

int Fl_Text_Selection::end | ( |  | ) | const
| inline

Returns the byte offset to the character after the last selected character.

The returned offset is only valid if selected() returns true (non-zero). The offset is 0 if no text is selected (since FLTK 1.4.0).

Note
  In FLTK 1.3.x the returned offset could be non-zero even if selected() would have returned 0.

Returns
  byte offset or 0 if not selected.

## ◆ includes()

int Fl_Text_Selection::includes | ( | int | pos | ) | const

Returns true if position `pos` is in the Fl_Text_Selection.

`pos` must be at a character boundary.

## ◆ length()

int Fl_Text_Selection::length | ( |  | ) | const
| inline

Returns the size in bytes of the selection.

This is a convenience method. It always returns the same as

end() - start()

and it returns 0 if selected() == false.

Returns
  size in bytes or 0 if not selected.

Since
  FLTK 1.4.0

## ◆ position()

int Fl_Text_Selection::position | ( | int * | startpos,
|  | int * | endpos ) const
| inline

Deprecated
  "since 1.4.0 - use selected(startpos, endpos) instead"

## ◆ selected() [1/3]

bool Fl_Text_Selection::selected | ( |  | ) | const
| inline

Returns true if any text is selected.

Returns
  `true` if any text has been selected, or `false` if no text is selected.

## ◆ selected() [2/3]

void Fl_Text_Selection::selected | ( | bool | b | ) |
| inline

Modifies the 'selected' flag.

Parameters

  b | new flag

## ◆ selected() [3/3]

int Fl_Text_Selection::selected | ( | int * | startpos,
|  | int * | endpos ) const

Returns the status and the positions of this selection.

This method returns the same as `selected()` as an `int` (0 or 1) in its return value and the offsets to the start of the selection in `startpos` and to the byte after the last selected character in `endpos`, if selected() is `true`.

If selected() is `false`, both offsets are set to 0.

Note
  In FLTK 1.3.x `startpos` and `endpos` were not modified if selected() was false.

Parameters

  startpos | return byte offset to first selected character
  endpos | return byte offset pointing after last selected character

Returns
  whether the selection is active (selected()) or not

Return values

  0 | if not selected
  1 | if selected

See also
  selected(), start(), end()

## ◆ set()

void Fl_Text_Selection::set | ( | int | startpos,
|  | int | endpos )

Sets the selection range.

`startpos` and `endpos` must be at a character boundary.

If `startpos` != `endpos` selected() is set to true, else to false.

If `startpos` is greater than `endpos` they are swapped so that `startpos` <= `endpos`.

Parameters

  [in] | startpos | byte offset to first selected character
  [in] | endpos | byte offset pointing after last selected character

## ◆ start()

int Fl_Text_Selection::start | ( |  | ) | const
| inline

Returns the byte offset to the first selected character.

The returned offset is only valid if selected() returns true. If the selection is not valid the returned offset is 0 since FLTK 1.4.0.

Note
  In FLTK 1.3.x the returned offset could be non-zero even if selected() would have returned 0.

Returns
  byte offset or 0 if not selected.

## ◆ update()

void Fl_Text_Selection::update | ( | int | pos,
|  | int | nDeleted,
|  | int | nInserted )

Updates a selection after text was modified.

Updates an individual selection for changes in the corresponding text.

Parameters

  pos | byte offset into text buffer at which the change occurred
  nDeleted | number of bytes deleted from the buffer
  nInserted | number of bytes inserted into the buffer

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

- Fl_Text_Buffer.H
- Fl_Text_Buffer.cxx