FLTK 1.4.0
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. More...
 
int includes (int pos) const
 Returns true if position pos is in the Fl_Text_Selection. More...
 
int length () const
 Returns the size in bytes of the selection. More...
 
int position (int *startpos, int *endpos) const
 Returns the status and the positions of this selection. More...
 
bool selected () const
 Returns true if any text is selected. More...
 
void selected (bool b)
 Modifies the 'selected' flag. More...
 
void set (int startpos, int endpos)
 Sets the selection range. More...
 
int start () const
 Returns the byte offset to the first selected character. More...
 
void update (int pos, int nDeleted, int nInserted)
 Updates a selection after text was modified. More...
 

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()
int end() const
Returns the byte offset to the character after the last selected character.
Definition: Fl_Text_Buffer.H:132
bool selected() const
Returns true if any text is selected.
Definition: Fl_Text_Buffer.H:139
int start() const
Returns the byte offset to the first selected character.
Definition: Fl_Text_Buffer.H:119
int length() const
Returns the size in bytes of the selection.
Definition: Fl_Text_Buffer.H:160

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

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
startposreturn byte offset to first selected character
endposreturn byte offset pointing after last selected character
Returns
whether the selection is active (selected()) or not
Return values
0if not selected
1if selected
See also
selected(), start(), end()

◆ selected() [1/2]

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/2]

void Fl_Text_Selection::selected ( bool  b)
inline

Modifies the 'selected' flag.

Parameters
bnew flag

◆ 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]startposbyte offset to first selected character
[in]endposbyte 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
posbyte offset into text buffer at which the change occurred
nDeletednumber of bytes deleted from the buffer
nInsertednumber of bytes inserted into the buffer

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