QDocumentLine Class Reference
[Document related classes]

A reference to line objects. More...

List of all members.

Public Types
enum	State {   None = 0, Hidden = 1, CollapsedBlockStart = 2, CollapsedBlockEnd = 4,   LayoutDirty = 16, FormatsApplied = 32 }
Public Member Functions
	Q_DECLARE_FLAGS (States, State)
bool	operator== (const QDocumentLineHandle *h) const
bool	operator!= (const QDocumentLineHandle *h) const
QString	indentation () const
bool	isHidden () const
QDocumentLineHandle *	handle () const
	QDocumentLine (QDocument *doc)
	QDocumentLine (const QDocumentLine &line)
	QDocumentLine (QDocumentLineHandle *h=0)
bool	isNull () const
bool	isValid () const
bool	operator== (const QDocumentLine &l) const
	Comparision operator.
bool	operator!= (const QDocumentLine &l) const
	Comparision operator.
bool	operator< (const QDocumentLine &l) const
	Comparision operator.
bool	operator>= (const QDocumentLine &l) const
	Comparision operator.
bool	operator> (const QDocumentLine &l) const
	Comparision operator.
bool	operator<= (const QDocumentLine &l) const
	Comparision operator.
QDocumentLine &	operator++ ()
	Iterate forward over the document.
QDocumentLine &	operator-- ()
	Iterate backward over the document.
void	operator++ (int)
	Iterate forward over the document.
void	operator-- (int)
	Iterate backward over the document.
QDocumentLine &	operator= (const QDocumentLine &l)
	copy operator
int	lineNumber () const
int	position () const
QString	text () const
int	length () const
int	lineSpan () const
int	firstChar () const
	Returns the position of the first non-whitespace character.
int	lastChar () const
	Returns the position of the last non-whitespace character.
int	nextNonSpaceChar (int pos) const
int	previousNonSpaceChar (int pos) const
	Find the position of the previous char that is not a space.
bool	hasFlag (State s) const
	Check whether a given flag is set to the line.
void	setFlag (State s, bool y=true)
	Set a flag of the line.
QDocumentLine	next () const
QDocumentLine	previous () const
QDocument *	document () const
int	xToCursor (int x) const
	Converts a document position (unconstrained viewport) to a cursor position (column).
int	cursorToX (int cpos) const
	Converts a cursor position (column) to a document position (unconstrained viewport).
int	wrappedLineForCursor (int cpos) const
int	documentOffsetToCursor (int x, int y) const
	Converts a document offset (viewport) to a cursor position (character / text column).
void	cursorToDocumentOffset (int cpos, int &x, int &y) const
	Converts a cursor position (character / text column) to a document offset (viewport).
QPoint	cursorToDocumentOffset (int cpos) const
void	addMark (int id)
	Toggle a mark on the line.
void	removeMark (int id)
	Remove a mark from the line.
void	toggleMark (int id)
	Toggle a mark on the line.
QList< int >	marks () const
bool	hasMark (int id) const
void	clearOverlays ()
	Clear all overlays applied to the line.
void	addOverlay (const QFormatRange &over)
	Add an overlay to the line.
void	removeOverlay (const QFormatRange &over)
	Remove an overlay from the line.
void	setFormats (const QVector< int > &formats)
	Set the formatting of the line.
const QVector< QParenthesis > &	parentheses () const
void	setParentheses (const QVector< QParenthesis > &parentheses)
	Set the parentheses present on that line.
QNFAMatchContext *	matchContext ()
Friends
class	QDocumentLineHandle
class	QDocumentCursorHandle

---

Detailed Description

A reference to line objects.

In QCodeEdit, documents are stored as a list of lines. A QDocumentLine holds a pointer to the data of one line and gives access to its content.

It is not meant to be used to iterate over the document, though it is possible for conveneience and compatibility reasons. Indeed, QDocumentLine does not now where in the document it is located. It can obtain that information but this is a O(n) operation. Navigation within the document is one of the task devoted to QDocumentCursor which can move around in O(1) (or amortized O(1) in some rare cases).

Lines can be given formatting in various way : "regular" formatting used for highlighting, overlays used mainly to display search matches and similar informations and marks.

---

Member Function Documentation

void QDocumentLine::addOverlay

(

const QFormatRange &

over

)

Add an overlay to the line.

Overlays are format range that get applied on top of regular formatting.

They are typically used to display search matches, matching braces, ...

References QDocumentLineHandle::addOverlay().

QPoint QDocumentLine::cursorToDocumentOffset

(

int

cpos

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References QDocumentLineHandle::cursorToDocumentOffset().

void QDocumentLine::cursorToDocumentOffset	(	int	cpos,
		int &	x,
		int &	y
	)			const

Converts a cursor position (character / text column) to a document offset (viewport).

The (x, y) coordinates given by this function are relative to the absolute position of the line, which can be obtained from the document.

References QDocumentLineHandle::cursorToDocumentOffset().

int QDocumentLine::cursorToX

(

int

cpos

)

const

Converts a cursor position (column) to a document position (unconstrained viewport).

Deprecated:

Use cursorToDocOffset() instead

This function is kept for compatribility only. It dates back to the time before line wrapping was implemented. Due to the limitation of its design (i.e signature) it works in a somewhat awkard way : the x position returned is that the cursor would have in an unconstrained viewport, even when the line is wrapped so it does not map to an actual viewport coordinate, unless of course no wrapping is used.

References QDocumentLineHandle::cursorToX().

QDocument * QDocumentLine::document

(

)

const

Returns:

the document to which that line belongs

References QDocumentLineHandle::document().

Referenced by addMark(), marks(), removeMark(), and toggleMark().

int QDocumentLine::documentOffsetToCursor	(	int	x,
		int	y
	)			const

Converts a document offset (viewport) to a cursor position (character / text column).

The (x, y) coordinates given by this function are relative to the absolute position of the line, which can be obtained from the document.

References QDocumentLineHandle::documentOffsetToCursor().

int QDocumentLine::firstChar

(

)

const

Returns the position of the first non-whitespace character.

Returns:

position of first non-whitespace char or -1 if there is none

References nextNonSpaceChar().

Referenced by QEditor::unindentSelection().

bool QDocumentLine::hasMark

(

int

id

)

const

Returns:

Whether a given mark has been set on the line

References marks().

bool QDocumentLine::isNull

(

)

const

Returns:

whether the line object is null (i.e invalid)

References QDocumentLineHandle::document().

bool QDocumentLine::isValid

(

)

const

Returns:

whether the line object is valid

References QDocumentLineHandle::document().

Referenced by QLineMarksInfoCenter::addLineMark(), QDocumentCursor::isNull(), QDocumentCursor::isValid(), QLineMarksInfoCenter::removeLineMark(), and QLineMarksInfoCenter::toggleLineMark().

int QDocumentLine::lastChar

(

)

const

Returns the position of the last non-whitespace character.

Returns:

position of last non-whitespace char or -1 if there is none

References length(), and previousNonSpaceChar().

int QDocumentLine::length

(

)

const

Returns:

The length of the line, in characters

References QDocumentLineHandle::text().

Referenced by lastChar(), QDocumentInsertCommand::QDocumentInsertCommand(), and QDocumentCommand::updateTarget().

int QDocumentLine::lineNumber

(

)

const

Returns:

the line number of the line within the document

Starts at 0, -1 for invalid lines.

Note:

Avoid whenever possible : O(n) complexity, n being document size in lines Prefer cursors over lines if you need to navigate within the document

References QDocumentLineHandle::line().

Referenced by QDocumentCursor::moveTo(), operator<(), operator<=(), operator>(), operator>=(), and QDocument::y().

int QDocumentLine::lineSpan

(

)

const

Returns:

the number of visual lines occupied by the line

This is NOT set to zero when the line is hidden (e.g due to folding).

References QDocumentLineHandle::document(), and QDocumentLineHandle::m_frontiers.

QList< int > QDocumentLine::marks

(

)

const

Returns:

the list of marks set on this line

References document(), and QDocument::impl().

Referenced by hasMark().

QNFAMatchContext * QDocumentLine::matchContext

(

)

Reserved to syntax engines. do not mess with this unless you know what you are doing.

References QDocumentLineHandle::m_context.

QDocumentLine QDocumentLine::next

(

)

const

Returns:

The previous line

Note:

Avoid using this function whenever possible, especially inside loops or time-consuming processing : it is SLOW for big documents as determination of the line number is O(n), n being the total number of lines in the document

References QDocumentLineHandle::next().

Referenced by operator++().

int QDocumentLine::nextNonSpaceChar

(

int

pos

)

const

Find the position of the next char that is not a space.

Parameters:

pos

Column of the character which is examined first.

Returns:

True if the specified or a following character is not a space Otherwise false.

References QDocumentLineHandle::nextNonSpaceChar().

Referenced by firstChar().

bool QDocumentLine::operator<

(

const QDocumentLine &

l

)

const

Comparision operator.

Note:

Line number based : avoid whenever possible

References lineNumber().

bool QDocumentLine::operator<=

(

const QDocumentLine &

l

)

const

Comparision operator.

Note:

Line number based : avoid whenever possible

References lineNumber().

QDocumentLine & QDocumentLine::operator=

(

const QDocumentLine &

l

)

copy operator

QDocumentLine objects are just wrappers around the "real" line data. Copies of a QDocumentLine all points to the same underlying data and modifying one affect them all (no implicit sharing).

References QDocumentLineHandle::deref(), m_handle, and QDocumentLineHandle::ref().

Referenced by operator++(), and operator--().

bool QDocumentLine::operator>

(

const QDocumentLine &

l

)

const

Comparision operator.

Note:

Line number based : avoid whenever possible

References lineNumber().

bool QDocumentLine::operator>=

(

const QDocumentLine &

l

)

const

Comparision operator.

Note:

Line number based : avoid whenever possible

References lineNumber().

const QVector< QParenthesis > & QDocumentLine::parentheses

(

)

const

Returns:

the list of parentheses present on the line

Note:

This is language dependent.

References QDocumentLineHandle::m_parens.

int QDocumentLine::position

(

)

const

Returns:

the position of the line within the document

Note:

This function is there for compatibility with QTextDocument & co Avoid it whenever possible, it is ridiculously slow.

References QDocumentLineHandle::position().

QDocumentLine QDocumentLine::previous

(

)

const

Returns:

The next line

Note:

Avoid using this function whenever possible, especially inside loops or time-consuming processing : it is SLOW for big documents as determination of the line number is O(n), n being the total number of lines in the document

References QDocumentLineHandle::previous().

Referenced by operator--().

int QDocumentLine::previousNonSpaceChar

(

int

pos

)

const

Find the position of the previous char that is not a space.

Parameters:

pos

Column of the character which is examined first.

Returns:

The position of the first non-whitespace character preceding pos, or -1 if none is found.

References QDocumentLineHandle::previousNonSpaceChar().

Referenced by lastChar().

void QDocumentLine::setFlag	(	State	s,
		bool	y = true
	)

Set a flag of the line.

Warning:

Do not mess with flags unless you know what you are doing

References QDocumentLineHandle::setFlag().

void QDocumentLine::setFormats

(

const QVector< int > &

formats

)

Set the formatting of the line.

Note:

this method is made available for syntax engine use. If you want to apply extra formatting on a line use overlays instead

See also:

addOverlay()

References QDocumentLineHandle::setFormats().

void QDocumentLine::setParentheses

(

const QVector< QParenthesis > &

parentheses

)

Set the parentheses present on that line.

Note:

this should only be used by syntax engines

References QDocumentLineHandle::m_parens.

QString QDocumentLine::text

(

)

const

Returns:

the text of the line

References QDocumentLineHandle::text().

Referenced by QEditor::insertText(), QDocumentSearch::next(), QDocumentInsertCommand::QDocumentInsertCommand(), and QEditor::text().

int QDocumentLine::wrappedLineForCursor

(

int

cpos

)

const

Returns:

The wrapped line (i.e "subline") to which a given cursor position resides

Parameters:

cpos

cursor position, as a text column

References QDocumentLineHandle::wrappedLineForCursor().

Referenced by QDocumentCursor::anchorWrappedLineOffset(), and QDocumentCursor::wrappedLineOffset().

int QDocumentLine::xToCursor

(

int

xpos

)

const

Converts a document position (unconstrained viewport) to a cursor position (column).

Deprecated:

Use cursorToDocOffset() instead

See also:

cursorToX() for more informations about this function

References QDocumentLineHandle::xToCursor().

---

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

• lib/document/qdocumentline.h
• lib/document/qdocumentline.cpp