Led 3.0 Class Library DocumentationLed 3.0 Class Library DocumentationTextImagerTextImager::NoTabletAvailableTextImager::NotFullyInitializedTextImager::SimpleTabStopListTextImager::StandardTabStopListTextImager::TabStopListTextImager::Tablet_AcquirerTrivialImager < TEXTSTORE,IMAGER > The TextImager class is one of central importance in Led. It is the (abstract) class which
does all the imaging - drawing of text to an output device.
TextImager [public]
virtual MarkerOwnerThe TextImager class is one of central importance in Led.
TextImagers are responsable for imaging to a Led_Tablet the
contents of a particular TextStore. A TextImager (except in the degenerate case)
is always associated with one TextStore (though a single TextStore can have
multiple TextImagers displaying its contents). This long-term relationship allows
the TextImagers to keep track of cached data like word-wrapping information etc.
TextStores have a flexable notification mechanism so that TextImagers get notifed
when 'interesting' modications are made to the text (or Markers) in the TextStore
a TextImager is pointing to.
A particular TextImager subclass takes the given text,
and figures out how to compute metrics on it, lay it out, cache layout information, and then
finally display the text. Different subclasses will apply different sorts of rules (and perhaps
keep track of additional information) to render the text differently. For example - a
WordWrappedTextImager will apply word-wrapping rules to display the text differently
than a SimpleTextImager would.
A TextImager has no notion of 'windows' - in the sense of a UI. It has no
notion of user interaction, screen
updates, etc. It has no notion of style runs, paragraph formatting etc.
It is a generic API for getting text (in a TextStore) imaged onto
a some output Led_Tablet.
Interesting subclasses of TextImager include PartitioningTextImager, SimpleTextImager,
StyledTextImager, StandardStyledTextImager, and TextInteractor.
| Member Details | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
By "Tablet" I mean on the mac a grafport, or on windows a CDC ( Sometimes Led is lucky enough to find itself in a position where it is handed a tabet (drawing). But sometimes it isn't so luck. Conisider if someone asks for a row number, and this causes a complex chain of events resulting in an attempt to word-wrap, which, in turn, requires a tablet. We need some API in the Imager to request a tablet. This API MUST return the appropriate tablet for the view, appropriately prepared for drawing/text metric calculations. Calls to For windows, TextImager::AcquireTablet () must return the current PaintDC used in the PaintDC call (if we are in the context of a paint). For Mac, we must not only return the grafPort, but be sure it is prepared. TextImager::AcquireTablet () only fail by throwing - typically NoTabletAvailable (Led 2.1 and earlier didn't allow failure). Calls to TextImager::AcquireTablet ()/TextImager::ReleaseTablet () can be nested. Also, sometimes something happens which causes all text metrics to become invalid (say we are about to image to a print port). In this case, the imager needs to be notified that all its text metrics are invalid. Call TextImager::TabletChangedMetrics () in this case. | |||||||||||||||
|
| |||||||||||||||
|
Measures the distance in pixels from 'from' to 'to'. This function requires that 'from' and 'to' are on the same row. | |||||||||||||||
|
| |||||||||||||||
|
This is a utility methods, very handy for implementing horizontal scrolling. It can (and should be) overriden in certain subclasses for efficiency. But the default implementation will work. | |||||||||||||||
|
| |||||||||||||||
|
Nulls out the given default color attribute, which means See also | |||||||||||||||
|
This routine is used for horizontal scrolling (though not from within this class).
It is mainly called by | |||||||||||||||
|
Override this to specify if any of the given characters should be hidden, removed, or mapped to some other display character. You can change the behavior of this function at runtime (depending on user settings). But when its changed - you should invalidate all cached information, since cached font metrics will we invalid (often with MultiRowTextImager::InvalidateAllCaches ()). Note - this function doesn't REPLACE the given character from the text. Instead -
it merely causes the Note also that this function takes an array of characters as a performance optimization (so it doesn't need to be called too many times, and to avoid copying buffers when nothing need be done). It could have been more logically (though less efficeintly) implemented as bool IsMappedDisplayCharacter (Led_tChar). If you override this - you may find it handy to call | |||||||||||||||
|
Simple implementation of See also | |||||||||||||||
|
Calls the associated | |||||||||||||||
|
Enumerator of different color-table default names used by these routines:
The values are:
| |||||||||||||||
|
This is the API called by the underlying window system (or wrappers) to get the imager to draw its currently displayed window | |||||||||||||||
|
Helper function to access tablet text drawing. This function takes care of setting the background/foreground colors, and setting up a font object to be used in the Led_Tablet_::TabbedTextOut calls (maybe can go away if we do better integrating font code into Led_Tablet/LedGDI and out of TextImager). The 'from' marker position must be legit, since it is used to grab the tabstop list. The 'end' marker position is OK to fake (passing in other text), as it is just used to determine the string length. Note text in 'text' argument need not match the REAL text in the TextStore buffer. See also | |||||||||||||||
|
EraseBackground () is called internally by TextImagers to get arbitrary subsets of the current window being drawn to erased. This erasure must only apply to the argument 'subsetToDraw'. Clipping is not used to gaurantee this. Failure to follow that rule can produce undesirably results where other bits of surrounding text get erased. The erasebackground call is made virtual so that you can use this as a hook to provide some sort of multi-media, picture or whatever as your background. Note that the is called during the draw process as a side-effect. So to have a changing background, you would need to both force periodic updates, and override this routine. NB: the argument 'subsetToDraw' can occasionally be outside of the WindowRect. If so - then DO draw where this function says to draw. This is because you maybe asked to erase window margins/borders outside the Led 'WindowRect' using the same color/algorithm as that used inside the Led WindowRect. By default - this simply calls Note - typically when you override this - you will want to override | |||||||||||||||
|
Return the associated TextStore::FindNextCharacter (). | |||||||||||||||
|
Return the associated | |||||||||||||||
|
Always returns a valid location, though it might not make a lot of since if it is outside the ImageRect. | |||||||||||||||
|
Like | |||||||||||||||
|
Returns the (document relative) pixel location (rectangle) of the character after the given marker position. GetCharLocation () returns the rectangle bounding the character after marker-position 'afterPosition'. The position MUST be a valid one (1..GetLength()+1), but could refer to the end of the buffer - and so there would be no character width in this case. | |||||||||||||||
|
| |||||||||||||||
|
Like NB: if the location is outside of the current window, then the size/origin maybe pinned to some arbitrary value, which is pixelwise above (or beleow according to before or after window start/end) the window. | |||||||||||||||
|
Returns the default font used to image new text. The exact meaning and use of this default font will depend some on the particular TextImager subclass you are using. | |||||||||||||||
|
Returns the value of the given indexed color attribute. These colors values default to NULL,
which means See also | |||||||||||||||
|
Returns either the effective color corresponding to the given See also | |||||||||||||||
|
Return the associated | |||||||||||||||
|
GetEndOfRow () returns the position AFTER the last displayed character in the row.
Note that this can differ from the end of row returned by See also | |||||||||||||||
|
| |||||||||||||||
|
Return the ForceAllRowsShowing flag. If this flag is true, then the TextImager will never allow scrolling so that the last row doesn't reach the end of the buffer. This is useful primarily for printing. Because otherwise, you would probably always want to disable scrolling past the point where the last row is showing. But thats a UI choice we allow you to make if you like (or if you have some other application like printing where it makes sense). Call | |||||||||||||||
|
Returns the horizontal offset the image is scrolled to. If this is zero, then no horizontal scrolling has taken place. Call TextImager::SetHScrollPos () to set where you have horizontally scrolled to. | |||||||||||||||
|
Led already has very little flicker. This is because we are very careful to draw as little as possible, and to draw quickly. But some cases still exist. Like large pictures being drawn are flicker, cuz we must erase the bounds and then draw the picture. Using this gets rid of these few cases of flicker, but at a small performance cost in overall draw speed. This value defaults to true (temporarily defaulting to qUseOffscreenBitmapsToReduceFlicker). See @TextImager::SetImageUsingOffscreenBitmaps'. | |||||||||||||||
|
Similar to | |||||||||||||||
|
Returns the row number of the bottom row visible in the scrolled display window.
This is a generally ineffient routine to call. It is generally much better
to call | |||||||||||||||
|
Return the associated | |||||||||||||||
|
This function returns the marker position of the end of the display window. The display window here refers to the area which is currently visible though scrolling. This doc should be clarified! | |||||||||||||||
|
| |||||||||||||||
|
This function returns the marker position of the start of the display window. The display window here refers to the area which is currently visible though scrolling. This doc should be clarified! | |||||||||||||||
|
GetRealEndOfRow () returns the position AFTER the last character in the row. See
| |||||||||||||||
|
| |||||||||||||||
|
| |||||||||||||||
|
| |||||||||||||||
|
This API is redundent, but can be much more efficient to get at this information than GetCharLocation() - especially in subclasses like MultiRowImager using RowRefernces. | |||||||||||||||
|
Returns the number of tChars within the given row (by row index). This method's use is discouraged when word-wrapping is present, because it forces word-wrapping up to the given row # in the buffer. | |||||||||||||||
|
Returns the number of pixels from the top of the given row, to the baseline. The 'charPosition' is a markerPosition just before any character in the row. | |||||||||||||||
|
OK, this is a little obscure. But - believe me - it does make sense. When doing updates to the text (say typing) the impact if the typing (in terms of visual display) typically only extends over a narrow region of the screen. If we are using a non-word-wrapped text editor, then this is typically a line. If it is a word-wrapped text editor, then it is typically a paragraph (or perhaps something less than that). This routine allows communication from the imager to higher-level interactor software about what areas of the text will need to be redrawn when changes to localized regions of the text occur. | |||||||||||||||
|
Returns the marker position of the start of the row following the row which contains the given marker position. If the given marker position is already in the last row, then it returns the start of that last row. So the result could posibly be less than the initial value. The reason for this apparantly obscure API is that marker positions allow you to name rows in a way which doesn't involve word-wrapping (row numbers would). And yet this code doesn't assume use of MultiRowTextImager, or any of its data structures (so these APIs can be used in things like TextInteractor). | |||||||||||||||
|
Returns the marker position of the start of the row preceeding the row which contains the given marker position, or the beginning of the buffer, if none preceed it. See the docs for | |||||||||||||||
|
GetStartOfRow () returns the position BEFORE the first displayed character in the row. | |||||||||||||||
|
| |||||||||||||||
|
Return the tabstop list ( Override this to provide a different tabstop list. The default is a | |||||||||||||||
|
GetTextBoundingRect () return a Rect which bounds the characters defined by the given marker positions. The will fit nicely around the characters if they all fit in one row, but may have sluff around the left/right sides if the range crosses row boundaries (since the shape wouldn't be a rectangle, but a region - try GetSelectionWindowRegion () for that). This function operates in GLOBAL coordinates (ie not window relative, calling This function operates on CharacterCells. | |||||||||||||||
|
GetTextWindowBoundingRect () return a Rect which bounds the characters defined by the given marker positions. The will fit nicely around the characters if they all fit in one row, but may have sluff around the left/right sides if the range crosses row boundaries (since the shape wouldn't be a rectangle, but a region - try GetSelectionWindowRegion () for that). This function operates on CharacterCells. This function operates in Window coordinates (ie window relative, calling See also | |||||||||||||||
|
Returns the row number of the top row visible in the scrolled display window.
This is a generally ineffient routine to call. It is generally much better
to call | |||||||||||||||
|
| |||||||||||||||
|
Returns the WindowRect associated with this TextImager. The WindowRect is essentially two things. Its origin specifies the offset mapping applied to all coordinate transformations before GDI output (and typically in TextInteractors UI input). And its Size dictate the size of the current window, used for deciding how much to draw, and scrolling operations. You can logically think of this - in Win32 SDK terminology - as the 'client rect'. In MacOS SDK terms, its close to the 'portRect' - its the same if you presume you are already focused, or that your text editor view takes up the entire window. | |||||||||||||||
|
Hilight the given rectangle of the screen, after its been drawn. This is typically done via some sort of pixel or color invesion. The default implemtation uses Led_Tablet_::HilightARectangle_SolidHelper. Override this mostly if you want different hilighting behavior, or if you want your hilighting behavior to remain in sync with other changes to the EraseBackground behavior. | |||||||||||||||
|
Helper function to access tablet text measurement. The 'from' and 'to' marker positions are ignored, except to compute the width. There is no requirement that the 'text' argument refer to the same text as that stored in the TextStore object. See also | |||||||||||||||
|
Override this to specify any characters which should be removed at the last minute for display purposes only. This particular function patches the distanceResults to zero out the removed characters. This can be used to give a (simple to implement) way to hide some special characters. For example, this technique can be used to implement SHIFT-RETURN soft line breaks (as is done in
If you override this - you may find it handy to call | |||||||||||||||
|
Simple implementation of See also | |||||||||||||||
|
Return the | |||||||||||||||
|
Tablet API See | |||||||||||||||
|
Override this to specify any characters which should be removed at the last minute for
display purposes only. This can be used to give a (simple to implement) way to hide some special characters.
For example, this technique can be used to implement SHIFT-RETURN soft line breaks (as is done in
If you override this - you may find it handy to call | |||||||||||||||
|
Simple implementation of See also | |||||||||||||||
|
Override this to specify any characters which should be mapped to different values at the last minute for display purposes only. This can be used to give a (simple to implement) funny display for particular special characters. For example, this technique can be used to make a NEWLINE character display as a special end-of-paragraph marker. If you override this - you may find it handy to call | |||||||||||||||
|
Simple implementation of See also | |||||||||||||||
|
If downBy negative then up OK to ask to scroll further than allowed - return true if any scrolling (not necesarily same amont requested) done | |||||||||||||||
|
If andTryToShowMarkerPos == 0, then just try to show the characters after markerPos. If it is NOT zero, then try to show the characters BETWEEN the two marker positions (note they might not be in ascending order). The (argument) order of the two marker positions determines PREFERENCE. That is - if there is no room to show both, be sure the first is showing. | |||||||||||||||
|
You probably should NOT call this directly. This is a helper to share code in implementing
| |||||||||||||||
|
Sets the given indexed default text color attribute. The effect of this is to override the behavior
of See also | |||||||||||||||
|
| |||||||||||||||
|
| |||||||||||||||
|
| |||||||||||||||
|
Associate this TextImager with the given Note that this will - as a side-effect - call
| |||||||||||||||
|
Call this method when something external, Led cannot detect, has happened to the tablet which would
invalidate any information the |
TextImager::NoTabletAvailable [public]
TextImager::NotFullyInitializedThrown by TextImager::AcquireTablet when no tablet available. See that method docs
for more details.
TextImager::NotFullyInitialized [public]
Led requires a complex of objects to all be setup, and hooked together in order to
perform several operations correctly. E.G. to invalidate part of the screen, it must indirectly
call on code to check the TextStore, or the Partition.
As part of code re-use, during the setup process, and part of the mechanism of providing default objects for many of these peices, we call SetThisOrThat() methods which invoke various InvalidateThisOrThat() methods, which in turn may occasionally try to compute something (like the max# of rows in a line). These sorts of errors are innocuous, but must be handled somehow. We could either write the code to be friendly of such uninitiualized variables/values, or to throw like this. My inclination is that throwing will be a more robust solution, since it will prevent an further use of a guessed value (and maybe prevent its being cached).
TextImager::SimpleTabStopList [public]
TextImager::TabStopListA simple tabstop implementation in which all tabstops are equidistant from each other, and start at position zero. This is commonly used as the default tabstop object.
TextImager::StandardTabStopList [public]
TextImager::TabStopListA simple tabstop implementation in the caller specifies the exact position of each tabstop. This is most directly ananogous to the Win32SDK GetTabbedTextExtent () API apporach.
TextImager::TabStopList [public]
See Led_TabStopList
| Member Details |
|---|
|
Compute where the 'ith' tabstop lies (i >= 0, and can be arbitrarily high).
Note that though tabstop Note - this used to return Led_Distance - but in Led 3.0 - it changed to returning TWIPS (see SPR#0767); |
|
Given a distance from the left margin, find the immediately following tabstops position.
This is what is actaully used in the imagers to compute where to draw text. It can logically
be implemented by walking the tabstoplist and calling Note - this used to take/return Led_Distance - but in Led 3.0 - it changed to take/return TWIPS (see SPR#0767); Now there is an overloaded version using Led_Distance that takes a Led_Tablet as argument. |
TextImager::Tablet_Acquirer [public]
Stack-based resource allocation/deallocation. See TextImager::AcquireTablet.
TrivialImager < TEXTSTORE,IMAGER > [public]
Handy little template, if you want to use the power of Led, but just to wrap a particular imager, in a localized, one-time fasion, say todo printing, or some such. Not for interactors.
Depending on the IMAGER you wish to use, you may want to try TrivialImager_Interactor
or TrivialWordWrappedImager - both of which come with examples of their use.
| Member Details |
|---|
|
Snag font, background color etc, from the currently associated tablet. Since this calls virtual methods of the imager (this) - it must be called in the final CTOR (most specific type). Really it shouldnt need to be THE most specific - just enough specific to get the right vritual methods called. But because of MSVC compiler bugs - its generally best to be THE final CTOR. |
|
Two overloaded versions - one protected, and the other public. The protected one
does NOT call |
Return to Led Page
Return to Led ClassLib Documentation Index
Return to Led Reference Manual Index