Annotated text gadget class. More...

#include <ilviews/annotext/annotext.h>

Inheritance diagram for IlvAnnoText:

Public Member Functions
	IlvAnnoText (IlvDisplay display, const IlvRect &rect, IlvATPalette tpalette, IlUShort thickness=IlvDefaultGadgetThickness)
	Constructor. More...

void	addAccelerator (IlvATAction action, IlvEventType type, IlUShort data=0, IlUShort modifiers=0, IlAny userArg=0, IlUShort modifiersToIgnore=0)
	Adds an accelerator. More...

virtual IlBoolean	check (IlUShort c)
	Handles a character coming from a keyboard event. More...

void	computeDraw (IlvPort dst=0, const IlvTransformer t=0, const IlvRegion clip=0, IlvATCursor from=0, IlvATCursor *to=0)
	Recomputes and redraws between the specified cursor locations. More...

void	computeLines ()
	Recomputes the layout. More...

void	deleteText (IlvATCursor start, IlvATCursor end)
	Deletes the text within the specified boundaries. More...

void	emptySelection (IlBoolean redraw) const
	Empties the selection. More...

void	emptyText ()
	Deletes all the text and all the zones. More...

IlBoolean	ensureVisible (IlvATCursor *cursor)
	Scrolls the annotated text to make the specified cursor visible. More...

IlvATInsertionCursor *	getInsertionCursor () const
	Returns the insertion cursor. More...

const char const	getLines (IlUInt &count)
	Gets the text lines. More...

IlvDim	getMinWrapWidth () const
	Returns the minimum dimension used for line wrapping. More...

IlBoolean	getSelection (IlvATCursor start, IlvATCursor end) const
	Gets the selection boundaries. More...

IlBoolean	getText (IlvATCursor start, IlvATCursor end, char *buffer, IlUInt length, IlBoolean stopAtNewLine=IlFalse) const
	Gets the text contained between the specified cursor locations. More...

IlvATPalette *	getTextPalette () const
	Returns the default `IlvATPalette`. More...

void	hideInsertionCursor (IlBoolean drawAround=IlTrue)
	Hides the insertion cursor. More...

void	insertBreak (IlvATCursor *where, IlvPosition gravity=IlvLeft)
	Inserts a break terminator at the specified cursor location. More...

void	insertGraphic (IlvATCursor where, IlvGraphic obj, IlBoolean owner=IlFalse, IlvPosition gravity=IlvLeft)
	Inserts a graphic object at the specified cursor location. More...

void	insertParagraph (IlvATCursor *where, IlvPosition gravity=IlvLeft)
	Inserts a paragraph terminator at the specified cursor location. More...

void	insertSeparator (IlvATCursor *where, IlvDim size=2, IlFloat width=1, IlvPosition gravity=IlvLeft)
	Inserts a horizontal separator at the specified cursor location. More...

void	insertTabulation (IlvATCursor *where, IlvPosition gravity=IlvLeft)
	Inserts a tabulation at the specified cursor location. More...

void	insertText (IlvATCursor where, const char text, IlvATPos len=1, IlvPosition gravity=IlvLeft)
	Inserts text at the specified cursor location. More...

IlvATZone *	insertZone (IlvATCursor start, IlvATCursor end=0)
	Creates a new `IlvATZone` at the specified boundaries. More...

IlBoolean	isEditable () const
	Indicates whether the annotated text is editable. More...

IlBoolean	isSelectionEmpty () const
	Indicates whether the selection is empty. More...

IlBoolean	moveInsertionCursorToPoint (const IlvPoint &point, const IlvTransformer *t=0)
	Moves the insertion cursor. More...

void	printContents (IlvPort *dst, const IlvTransformer &trans, const IlvRect &printRect)
	Prints the contents of the `IlvAnnoText`. More...

void	refreshZone (IlvATZone zone, IlvPort dst=0, const IlvTransformer t=0, const IlvRegion clip=0) const
	Redraws the specified zone. More...

void	removeAccelerator (IlvEventType type, IlUShort data=0, IlUShort modifiers=0)
	Removes the accelerator matching the event description. More...

void	removeAccelerator (IlvATAccelerator *accel)
	Removes the specified accelerator. More...

virtual void	removeSelection ()
	Removes the selected area. More...

IlBoolean	scrollDown (IlvDim pos)
	Scrolls up by the specified amount of pixels. More...

IlBoolean	scrollDownLines (IlUShort lines)
	Scrolls down by the specified amount of lines. More...

IlBoolean	scrollUp (IlvDim pos)
	Scrolls up by the specified amount of pixels. More...

IlBoolean	scrollUpLines (IlUShort lines)
	Scrolls up by the specified amount of lines. More...

void	setEditable (IlBoolean value)
	Sets the annotated text to be editable or not. More...

void	setMinWrapWidth (IlvDim wrapwidth)
	Sets the minimum dimension used for line wrapping. More...

IlBoolean	setSelection (IlvATCursor c1, IlvATCursor c2, IlBoolean redraw=IlFalse)
	Sets the selection. More...

void	showInsertionCursor (IlBoolean drawAround=IlTrue)
	Draws the insertion cursor. More...

IlvATZone *	whichZone (const IlvPoint &point, const IlvTransformer *t=0, IlBoolean inside=IlTrue) const
	Returns the zone containing or close to a given point. More...

Detailed Description

Annotated text gadget class.

Library: ilvatext
This class describes a gadget that displays text and graphics (including gadgets) in various fonts and colors, using formatting annotations on parts of the contents (as various left and right margin values for different paragraphs of the text) and allowing specific interactors of the class IlvATInteractor to be set on parts of the text.

There is a notion of selection in the IlvAnnoText. The selection is a part of the object that is drawn inverting the corresponding palettes; it is used for copy/paste implementation.

See also: IlvAccelerator, IlvATAccelerator, IlvATCursor, IlvATInsertionCursor, IlvATInteractor, IlvATPalette, IlvATZone.

Constructor & Destructor Documentation

§ IlvAnnoText()

IlvAnnoText::IlvAnnoText	(	IlvDisplay *	display,
		const IlvRect &	rect,
		IlvATPalette *	tpalette,
		IlUShort	thickness = `IlvDefaultGadgetThickness`
	)

Constructor.

Initializes a new instance of the IlvAnnoText class and gives it the specified geometry.

Parameters

display	Specifies the display.
rect	Specifies the geometry (size and position).
tpalette	Specifies the Text Palette to use.
thickness	Specifies the shadow thickness.

Member Function Documentation

§ addAccelerator()

void IlvAnnoText::addAccelerator	(	IlvATAction	action,
		IlvEventType	type,
		IlUShort	data = `0`,
		IlUShort	modifiers = `0`,
		IlAny	userArg = `0`,
		IlUShort	modifiersToIgnore = `0`
	)

Adds an accelerator.

Creates an IlvATAccelerator using the same arguments and adds it to the IlvAnnoText (see the constructor for argument descriptions). If the accelerator already matches an action in the annotated text accelerator watch list (see IlvAccelerator::match()), then the action in the list is replaced by the action described in the function parameters. IlvAnnoText accelerators take precedence over other event handling routines. It means that, when receiving an event, IlvAnnoText will first check its accelerator list. If an appropriate accelerator is found (see IlvAccelerator::trigger()), it is activated and the event is not dispatched any further; otherwise, the IlvAnnoText dispatches the event to its components.

Note: An accelerator manages a single user event that occurs in the IlvAnnoText. It is a direct connection from this single user event to a function call. You can declare a given function to be called if an appropriate event occurs. If the appropriate event occurs, the accelerator triggers its action.

§ check()

virtual IlBoolean IlvAnnoText::check ( IlUShort c )

virtual

Handles a character coming from a keyboard event.

Called by handleEvent() for each IlvKeyDown event that corresponds to a regular character providing the event has not been handled before by the zone located at the event point. The ASCII code of the character is available in c. The default implementation inserts the character in the text therefore the call to IlvAnnoText::check(c) should be after the customized code.

Parameters

c	The character to handle.

§ computeDraw()

void IlvAnnoText::computeDraw	(	IlvPort *	dst = `0`,
		const IlvTransformer *	t = `0`,
		const IlvRegion *	clip = `0`,
		IlvATCursor *	from = `0`,
		IlvATCursor *	to = `0`
	)

Recomputes and redraws between the specified cursor locations.

Recomputes the layout and redraw from the IlvATCursor pointed to by from to the IlvATCursor pointed to by to. All the arguments are optional; if to is omitted, the text is recomputed to the end. If from is omitted, the text is computed from the beginning. If t or dst are omitted, the draw will be done based on the information found in the gadget holder which holds the annotated text.

Parameters

dst	The destination port.
t	The transformer.
clip	The clipping region.
from	Specifies the start boundary.
to	Specifies the end boundary.

§ computeLines()

void IlvAnnoText::computeLines ( )

Recomputes the layout.

Recomputes the layout (without drawing) of the IlvAnnoText.

§ deleteText()

void IlvAnnoText::deleteText	(	IlvATCursor *	start,
		IlvATCursor *	end
	)

Deletes the text within the specified boundaries.

Deletes all the characters between start and end.

Parameters

start	Specifies the location where the text deletion must start.
end	Specifies the location where the text deletion must end.

§ emptySelection()

void IlvAnnoText::emptySelection ( IlBoolean redraw ) const

Empties the selection.

Resets the selection so that it contains nothing.

Parameters

redraw If set to IlTrue, the annotated text is redrawn.

§ emptyText()

void IlvAnnoText::emptyText ( )

Deletes all the text and all the zones.

Deletes all the characters and zones of the annotated text.

§ ensureVisible()

IlBoolean IlvAnnoText::ensureVisible ( IlvATCursor * cursor )

Scrolls the annotated text to make the specified cursor visible.

Returns: IlTrue if scrolling has taken place, and IlFalse if the cursor was already visible.

§ getInsertionCursor()

IlvATInsertionCursor* IlvAnnoText::getInsertionCursor ( ) const

Returns the insertion cursor.

Returns: The insertion cursor. It should not be deleted or modified. It is only to be used in move member functions (for example, moveInsertionCursorToPoint()).

§ getLines()

const char* const* IlvAnnoText::getLines ( IlUInt & count )

Gets the text lines.

Returns: The text contents of the annotated text in an array of string, each string being a line of the annotated text. This array and its elements should be neither modified nor deleted.

Parameters

count Used to return the number of lines in the array.

§ getMinWrapWidth()

IlvDim IlvAnnoText::getMinWrapWidth ( ) const

Returns the minimum dimension used for line wrapping.

Returns: The minimum width used for line wrapping. The annotated text tries to perform line wrapping on text lines that are wider than this value.

§ getSelection()

IlBoolean IlvAnnoText::getSelection	(	IlvATCursor *	start,
		IlvATCursor *	end
	)		const

Gets the selection boundaries.

Returns: IlFalse if the selection is empty.

Parameters

start	Used to return the start of the selection.
end	Used to return the end of the selection.

§ getText()

IlBoolean IlvAnnoText::getText	(	IlvATCursor *	start,
		IlvATCursor *	end,
		char *	buffer,
		IlUInt	length,
		IlBoolean	stopAtNewLine = `IlFalse`
	)		const

Gets the text contained between the specified cursor locations.

Copies the text from the cursor start to the cursor end into buffer. If all the text has been copied the function returns IlTrue and start is moved to just before end, otherwise, if there is more than length characters to copy, IlFalse is returned and the cursor start is moved to just after the last position copied, so that the function can be called repeatedly to get all the text. Paragraph and break marks copy a carriage return character.

Parameters

start	Specifies the beginning of the text to copy.
end	Specifies the end of the text to copy.
buffer	Specifies a buffer of length characters allocated by the caller.
length	Specifies the length of buffer.
stopAtNewLine	If set to `IlTrue`, the paragraph and break marks stop copying the text. Otherwise they copy a carriage return character.

§ getTextPalette()

IlvATPalette* IlvAnnoText::getTextPalette ( ) const

Returns the default IlvATPalette.

Returns: A pointer to the default IlvATPalette of the IlvAnnoText object.

§ hideInsertionCursor()

void IlvAnnoText::hideInsertionCursor ( IlBoolean drawAround = IlTrue )

Hides the insertion cursor.

Parameters

drawAround If IlTrue is specified, the redrawing pertains to the area in the immediate vicinity of the insertion cursor. This is particularly true if the cursor is displayed between two characters. If IlFalse is specified, only the vertical line representing the cursor is redrawn using the XOR mode of the palette.

§ insertBreak()

void IlvAnnoText::insertBreak	(	IlvATCursor *	where,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts a break terminator at the specified cursor location.

Breaks are similar to paragraphs, except that the attributes first line offset, space before and space after of the IlvATPalette are not applied at break points.

Parameters

where	The location where the insertion takes place.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertGraphic()

void IlvAnnoText::insertGraphic	(	IlvATCursor *	where,
		IlvGraphic *	obj,
		IlBoolean	owner = `IlFalse`,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts a graphic object at the specified cursor location.

Parameters

where	The location where the insertion takes place.
obj	The graphic object.
owner	If set to `IlFalse`, the `IlvAnnoText` is not considered as owner of the graphic object and will not deleted it in its member functions. Otherwise, the graphic object will be deleted by member functions such as `emptyText()` or `deleteText()`.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertParagraph()

void IlvAnnoText::insertParagraph	(	IlvATCursor *	where,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts a paragraph terminator at the specified cursor location.

Parameters

where	The location where the insertion takes place.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertSeparator()

void IlvAnnoText::insertSeparator	(	IlvATCursor *	where,
		IlvDim	size = `2`,
		IlFloat	width = `1`,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts a horizontal separator at the specified cursor location.

The horizontal separator is represented by an IlvReliefLine centered and taking an amount of space equal to the total available (after deducing margins) multiplied by width.

Parameters

where	The location where the insertion takes place.
size	The height of the `IlvReliefLine`.
width	Value comprised between `0` and `1` and used to compute the `IlvReliefLine` dimension.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertTabulation()

void IlvAnnoText::insertTabulation	(	IlvATCursor *	where,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts a tabulation at the specified cursor location.

The space skipped by the tabulation depends on the position of the tabulation marks of the IlvATPalette.

Parameters

where	The location where the insertion takes place.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertText()

void IlvAnnoText::insertText	(	IlvATCursor *	where,
		const char *	text,
		IlvATPos	len = `1`,
		IlvPosition	gravity = `IlvLeft`
	)

Inserts text at the specified cursor location.

Inserts the len first characters of the string text into the IlvAnnoText. The text is inserted at the location the specified by the cursor where.

Parameters

where	The location where the insertion takes place.
text	The character string.
len	The number of characters to insert.
gravity	Indicates whether the insertion must be done just before (`IlvLeft`) or just after (`IlvRight`) the cursor where.

§ insertZone()

IlvATZone* IlvAnnoText::insertZone	(	IlvATCursor *	start,
		IlvATCursor *	end = `0`
	)

Creates a new IlvATZone at the specified boundaries.

Due to the hierarchical structure of nesting zones, the two cursors specifying the boundaries of the new zone must be inside the same IlvATZone (smaller IlvATZone instances may be nested between); otherwise, the function does nothing and returns 0.

Returns: A pointer to the zone created, or 0.

Parameters

start	Specifies the beginning of the zone.
end	Specifies the end of the zone. If set to `0`, the new zone is created around the cursor start.

§ isEditable()

IlBoolean IlvAnnoText::isEditable ( ) const

Indicates whether the annotated text is editable.

Returns: IlTrue if the IlvAnnoText is in editable mode, which means that the interactor lets you type text. If the object is in read-only mode, the function returns IlFalse.

§ isSelectionEmpty()

IlBoolean IlvAnnoText::isSelectionEmpty ( ) const

Indicates whether the selection is empty.

Returns: IlTrue if the selection of the IlvAnnoText contains nothing (for example, the selection has never been defined, or emptySelection() has been called, or the entire IlvAnnoText has been cleared using IlvAnnoText::emptyText()), IlFalse otherwise.

§ moveInsertionCursorToPoint()

IlBoolean IlvAnnoText::moveInsertionCursorToPoint	(	const IlvPoint &	point,
		const IlvTransformer *	t = `0`
	)

Moves the insertion cursor.

Moves the insertion cursor of the text to the position displayed through the optional transformer t, nearest to point.

Parameters

point	The point.
t	The transformer.

§ printContents()

void IlvAnnoText::printContents	(	IlvPort *	dst,
		const IlvTransformer &	trans,
		const IlvRect &	printRect
	)

Prints the contents of the IlvAnnoText.

Prints the contents of the annotated text on the specified port. An example of how to use this method can be found in $ILVHOME/tools/htmlview/src/htmlview.cpp.

Parameters

dst	The destination port.
trans	The transformer to apply when drawing.
printRect	The size of the printed content pages.

§ refreshZone()

void IlvAnnoText::refreshZone	(	IlvATZone *	zone,
		IlvPort *	dst = `0`,
		const IlvTransformer *	t = `0`,
		const IlvRegion *	clip = `0`
	)		const

Redraws the specified zone.

Redraws the specified zone without recomputing the layout; this supposes that the contents of zone keep the same geometry.

Parameters

zone	Specifies the zone.
dst	The destination port where the drawing is performed.
t	Specifies the transformer to apply.
clip	The clipping region.

§ removeAccelerator() [1/2]

void IlvAnnoText::removeAccelerator	(	IlvEventType	type,
		IlUShort	data = `0`,
		IlUShort	modifiers = `0`
	)

Removes the accelerator matching the event description.

Parameters

type	The accelerator event type.
data	The accelerator event data.
modifiers	The accelerator mandatory event modifiers.

§ removeAccelerator() [2/2]

void IlvAnnoText::removeAccelerator ( IlvATAccelerator * accel )

Removes the specified accelerator.

Parameters

accel The accelerator to remove.

§ removeSelection()

virtual void IlvAnnoText::removeSelection ( )

virtual

Removes the selected area.

§ scrollDown()

IlBoolean IlvAnnoText::scrollDown ( IlvDim pos )

Scrolls up by the specified amount of pixels.

Parameters

pos	The number of pixels.

§ scrollDownLines()

IlBoolean IlvAnnoText::scrollDownLines ( IlUShort lines )

Scrolls down by the specified amount of lines.

Parameters

lines The number of lines.

§ scrollUp()

IlBoolean IlvAnnoText::scrollUp ( IlvDim pos )

Scrolls up by the specified amount of pixels.

Parameters

pos	The number of pixels.

§ scrollUpLines()

IlBoolean IlvAnnoText::scrollUpLines ( IlUShort lines )

Scrolls up by the specified amount of lines.

Parameters

lines The number of lines.

§ setEditable()

void IlvAnnoText::setEditable ( IlBoolean value )

Sets the annotated text to be editable or not.

Turns the editable mode on or off.

Parameters

value If IlTrue, the annotated text is set in editable mode, otherwise it is set in read-only mode.

§ setMinWrapWidth()

void IlvAnnoText::setMinWrapWidth ( IlvDim wrapwidth )

Sets the minimum dimension used for line wrapping.

Normally, the lines are wrapped-around, that is, cut to fit in the width of the IlvAnnoText (margins subtracted), but if getMinWrapWidth() is greater than the width of the IlvAnnoText, the lines are clipped so as to fit in getMinWrapWidth() pixels, and a horizontal scroll bar appears to allow the viewing of all the IlvAnnoText contents. The default value is 0.

§ setSelection()

IlBoolean IlvAnnoText::setSelection	(	IlvATCursor *	c1,
		IlvATCursor *	c2,
		IlBoolean	redraw = `IlFalse`
	)

Sets the selection.

Defines the boundaries of the selection.

Parameters

c1	The start of the selection.
c2	The end of the selection.
redraw	`IlTrue`, the `IlvAnnoText` is locally redrawn.

§ showInsertionCursor()

void IlvAnnoText::showInsertionCursor ( IlBoolean drawAround = IlTrue )

Draws the insertion cursor.

Parameters

drawAround If IlTrue is specified, the redrawing pertains to the area in the immediate vicinity of the insertion cursor. This is particularly true if the cursor is displayed between two characters. If set to IlFalse, only the vertical line representing the cursor is drawn.

§ whichZone()

IlvATZone* IlvAnnoText::whichZone	(	const IlvPoint &	point,
		const IlvTransformer *	t = `0`,
		IlBoolean	inside = `IlTrue`
	)		const

Returns the zone containing or close to a given point.

Returns: The IlvATZone at the specified point.

Parameters

point	The point.
t	The transformer.
inside	If `IlFalse` is specified, the function returns the zone which is the closest to the point. Otherwise, it is mandatory that the zone returned contains the point and if no such zone is found, `0` is returned.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ IlvAnnoText()

Member Function Documentation

§ addAccelerator()

§ check()

§ computeDraw()

§ computeLines()

§ deleteText()

§ emptySelection()

§ emptyText()

§ ensureVisible()

§ getInsertionCursor()

§ getLines()

§ getMinWrapWidth()

§ getSelection()

§ getText()

§ getTextPalette()

§ hideInsertionCursor()

§ insertBreak()

§ insertGraphic()

§ insertParagraph()

§ insertSeparator()

§ insertTabulation()

§ insertText()

§ insertZone()

§ isEditable()

§ isSelectionEmpty()

§ moveInsertionCursorToPoint()

§ printContents()

§ refreshZone()

§ removeAccelerator() [1/2]

§ removeAccelerator() [2/2]

§ removeSelection()

§ scrollDown()

§ scrollDownLines()

§ scrollUp()

§ scrollUpLines()

§ setEditable()

§ setMinWrapWidth()

§ setSelection()

§ showInsertionCursor()

§ whichZone()