Rogue Wave Views
Annotated Text Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions
IlvAnnoText Class Reference

Annotated text gadget class. More...

#include <ilviews/annotext/annotext.h>

Inheritance diagram for IlvAnnoText:
IlvScrolledGadget IlvGadget IlvSimpleGraphic IlvStylable IlvGraphic IlvValueInterface

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...
 
IlvATInsertionCursorgetInsertionCursor () 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...
 
IlvATPalettegetTextPalette () 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...
 
IlvATZoneinsertZone (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...
 
IlvATZonewhichZone (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
displaySpecifies the display.
rectSpecifies the geometry (size and position).
tpaletteSpecifies the Text Palette to use.
thicknessSpecifies 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
cThe 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
dstThe destination port.
tThe transformer.
clipThe clipping region.
fromSpecifies the start boundary.
toSpecifies 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
startSpecifies the location where the text deletion must start.
endSpecifies 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
redrawIf 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
countUsed 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
startUsed to return the start of the selection.
endUsed 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
startSpecifies the beginning of the text to copy.
endSpecifies the end of the text to copy.
bufferSpecifies a buffer of length characters allocated by the caller.
lengthSpecifies the length of buffer.
stopAtNewLineIf 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
drawAroundIf 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
whereThe location where the insertion takes place.
gravityIndicates 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
whereThe location where the insertion takes place.
objThe graphic object.
ownerIf 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().
gravityIndicates 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
whereThe location where the insertion takes place.
gravityIndicates 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
whereThe location where the insertion takes place.
sizeThe height of the IlvReliefLine.
widthValue comprised between 0 and 1 and used to compute the IlvReliefLine dimension.
gravityIndicates 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
whereThe location where the insertion takes place.
gravityIndicates 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
whereThe location where the insertion takes place.
textThe character string.
lenThe number of characters to insert.
gravityIndicates 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
startSpecifies the beginning of the zone.
endSpecifies 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
pointThe point.
tThe 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
dstThe destination port.
transThe transformer to apply when drawing.
printRectThe 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
zoneSpecifies the zone.
dstThe destination port where the drawing is performed.
tSpecifies the transformer to apply.
clipThe clipping region.

§ removeAccelerator() [1/2]

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

Removes the accelerator matching the event description.

Parameters
typeThe accelerator event type.
dataThe accelerator event data.
modifiersThe accelerator mandatory event modifiers.

§ removeAccelerator() [2/2]

void IlvAnnoText::removeAccelerator ( IlvATAccelerator accel)

Removes the specified accelerator.

Parameters
accelThe accelerator to remove.

§ removeSelection()

virtual void IlvAnnoText::removeSelection ( )
virtual

Removes the selected area.

Removes the selected area.

§ scrollDown()

IlBoolean IlvAnnoText::scrollDown ( IlvDim  pos)

Scrolls up by the specified amount of pixels.

Parameters
posThe number of pixels.

§ scrollDownLines()

IlBoolean IlvAnnoText::scrollDownLines ( IlUShort  lines)

Scrolls down by the specified amount of lines.

Parameters
linesThe number of lines.

§ scrollUp()

IlBoolean IlvAnnoText::scrollUp ( IlvDim  pos)

Scrolls up by the specified amount of pixels.

Parameters
posThe number of pixels.

§ scrollUpLines()

IlBoolean IlvAnnoText::scrollUpLines ( IlUShort  lines)

Scrolls up by the specified amount of lines.

Parameters
linesThe 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
valueIf 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
c1The start of the selection.
c2The end of the selection.
redrawIlTrue, the IlvAnnoText is locally redrawn.

§ showInsertionCursor()

void IlvAnnoText::showInsertionCursor ( IlBoolean  drawAround = IlTrue)

Draws the insertion cursor.

Parameters
drawAroundIf 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
pointThe point.
tThe transformer.
insideIf 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.

© Copyright 2018, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.