Led 3.0 Class Library DocumentationLed 3.0 Class Library DocumentationTextInteractorTextInteractor::BadUserInputTextInteractor::CommandNamesTextInteractor::TemporarilySetUpdateModeTextInteractor::UndoableContextHelperTextInteractor::UpdateModeTextInteractorCommandHelper_DefaultCmdInfoTextInteractorCommonCommandHelper < BASECLASS,CMD_INFO,CMD_ENABLER > TrivialImager_Interactor < TEXTSTORE,IMAGER > qBackwardCompatTextInteractorCmdNamesqBackwardCompatUndoHelpersqSupportEnterIdleCallbackqUseGDIScrollbitsForScrollingThis module defines the TextInteractor class, which subclasses from TextImager
and introduces user-interaction
behavior - such as keyclicks, mouse tracking, and the notion of TextInteractor::UpdateMode s.
TextInteractor [public]
virtual TextImagerTextInteractors are special TextImagers which respond to events
(such as keyclicks), handle mouse tracking,
and are designed to work with some sort of windowing system. They have a
concept of Update events, and having their content data out of sync with
that which is displayed in the window (inval/validate region). They also
provide support for things like a selection, and cursoring through the
selection, and word selection, etc.
Note that TextInteractors are still abstract classes, and know nothing
about particular windowing systems, or class libraries. They do what can
be done genericly, without having yet made a choice about these things.
TextInteractor mainly serves to collect common code/functionality which
can be shared accross (for example) MFC/OpenDoc/TCL/PowerPlant/PowerPlant, etc.
See Led_PPView, Led_MacOS_Helper, Led_MFC, Led_Win32_Helper
Led_Gtk_Helper, etc for more information on class-library-specific
integration.
| Member Details |
|---|
|
This callback can be used to implement various optimizations, were we don't need to actually fix something (like sbar position) til the last minute, when were done with some big operation (e.g. lots of text changes), and were about to display. We define an API method - CallEnterIdleCallback () which must be called by some other
service - by default it is expected the Led_ Override OnEnterIdleCallback() to handle your specific bit of on-enter-callback code. This is cooperative - so when you override, be sure to call all the other registered callbacks (OnEnterIdleCallback_) |
|
Helper to implemented best feeling UI for double click detection. See also |
|
Helper routine for handling cursoring done by user. |
|
Use the associated externalizer (see |
|
Use the associated externalizer (see |
|
Given an empty selection, it seems pretty obvious where to place the caret - right? NOT!!! Remember that a selection position falls BETWEEN two characters. One plausible definition is to use the RIGHT edge of the preceeding character. Yet - ANOTHER plausible definition is to use the LEFT edge of the following character. For some particular positions (notable the beginning and ends of the text) or or the other of these definitions might not quite make sense. But there are obvious definitions to take care of these special cases. And - luckily - for the most part - these definitions coincide. But there is at least one place which comes up (in normal editor usage - more in fancy Led subclasses like LVEJ's side-by-side mode). In particular, when the preceeding and following characters fall on different rows. In this case, a hint is helpful in deciding which of the two approaches to use. Many editors simply pick one approach or the other. Led did this for a while. It always picked the leading edge of the following character. But now Led has a option. When users change the selection by clicking, this option is is automaticly set. And similarly when they use the arrow keys, or do other editing operations. The set-method for this field is virtual, so subclassers who prefer one definition over the other can override the set method to simply force a particular value. If GetCaretShownAfterPos is true, use the use the LHS of following character, and if false, then the RHS of the preceeding character. So the after refers to which character to use - the one before or after the given marker POS. The side of the charater is the opposite of this value. |
|
Just like |
|
OBSOLETE. |
|
TextInteractor's have associated an optional |
|
Returns command name for each of the user-visible commands produced by this module. This name is used used in the constructed Undo command name, as in, "Undo Paste". You can replace this name with whatever you like.You change this value with WordProcessor::SetCommandNames. The point of this is to allow for different UI-language localizations, without having to change Led itself. See also |
|
Used to keep track of the number of clicks the user has done very recently. Used for determining double and triple clicks. If the user clicks, and then clicks a long time later - it wont be considered a double click - and so this value will remain one. |
|
OBSOLETE. |
|
TextInteractor's have an associated default UpdateMode. This is the update mode which is used by methods which used the eDefaultUpdateMode argument (most default UpdateMode args in Led are this value). This value should not be set directly. Instead, instantiate a
|
|
|
|
|
|
OBSOLETE. |
|
See also 'TextInteractor::SetScrollBarType' |
|
TextInteractor's support a UI feature called "smart cut & paste". Basicly, Led tries to guess what a user 'really meant todo' with surrounding whitespace when dragging, and cutting and pasting text. This can sometimes be extremely helpful. Othertimes, it can be extremely anoying. You decide. Thats why its an option. And see |
|
OBSOLETE. |
|
Called by |
|
Called by |
|
See also |
|
Hook function called AFTER the This happens, for example, with StandardStyledTextInteractor::InteractiveReplaceEarlyPostReplaceHook where we want to set the font of the newly typed character according to the 'fEmptySelection' style. See spr#0604 for more details. |
|
|
|
Mark the contents of the scrollbars as invalid. Someone, sometime later soon will call
|
|
Sometimes we can go through alot of computation to see just what minimal area of the window needs to be updated. Sometimes this can be quite helpful, and allow things to run quickly. But other times, like when we are making many changes to the text before ever showing anything, it would be just faster to mark the whole screen as dirty, and to avoid the computation about what region needs updating. Thats what these APIs here are about. You can tell the We override the Draw (const Led_Rect& subsetToDraw, bool printing) method to call
Led supports a redraw optimization, whereby complex calculations about what region of the screen needs to be invalidated can be avoided, if we keep track of, and cache the notion that the whole screen is already fully invalidated. This method is called internally to avoid complex calculations. You may rarely want to call it as well, if profiling yields a hot-spot in your code, in a calculation of something that need not be done if the screen has already been marked as invalid. |
|
This probably should not be called directly. It is called to check whether the given bit of text appears like it should be 'smart pasted' at the current selection point. The logic if this routine is questionable - and subject to change (LGP990329). In fact - as of 2001-09-19 - it HAS changed. Its now simper ;-). May need to revisit this again (SPR#1031). |
|
Make a FlavorPackageExternalize which is appropriate for this text interactor. Override this to make a different subclass, which supports different style and file formats from the (simple) default. By default, this creates a |
|
Make a By default, this creates a |
|
See |
|
See Called internally by Led. Only call this with extreme caution. Should very rarely be appropriate, outside of class library wrappers. |
|
Called by If you override, don't forget to call inherited, or |
|
Called by |
|
Command to implement the "Select All" UI. Trivial implementation, but nearly all UI's want it, so why write it each time? |
|
High level handling that does basically all of the portable support for a typed character. This is typically what you would call (the class library integration classes call this directly) to handle keyboard input. You might also plausibly override this method to provide special handling for particular key sequences (e.g. LedLineIt! overrides this to map shift-tab when there is a selection to an indent command rather than an insertion of text). |
|
See The way in which which we handle smart cut-and-paste is twofold. We have sometimes add extra spaces
(which is done in this routine), and sometimes we must delete extra spaces
(which is done in We must be careful todo our space insertion in such a way that it is friendly to the UNDO system (doesn't appear as a separate undo event etc). Note - this routine is called after the update has taken place. And it looks at the text at the LHS of where the insertion was done, and at the RHS of where it finihsed. The RHS of where it finished is always assumed to be the result of a call to TextImager::GetSelectionEnd. And the start is given by the 'selStart' argument. |
|
|
|
Helper to implemented best feeling UI for double click detection. See also |
|
OBSOLETE - 2000-08-19. |
|
OBSOLETE - 2000-08-19. |
|
This routine is called after a user action has taken place which is to be recorded for UNDOing. The 'startOfInsert' / 'endOfInsert' passed here refer to the region of text which must be preserved. The actaul selection saved will be the currently selected text at the time this method is called. Note - the startOfInsert/endOfInsert can differ from the selection region because things like SmartCutAndPaste can expand the affected area of text to BEYOND what was actaully selected by the user. This method operatates by calling an overloaded method of the same name. |
|
This routine is called after a user action has taken place which is to be recorded for UNDOing.
The routine simply posts an This method is frequently called by an overloaded method of the same name. |
|
OBSOLETE - 2000-08-19. |
|
This is called early on - before any change happens - to preserve the contents of a region about to be updated - so that the region can be restored upon an UNDO command. The argument selStart/selEnd are NOT the actual selection regions - but rather the region (which maybe slightly larger) that needs to be preserved (perhaps the arg names should change?). Note - this can differ from the selection region because of SmartCutAndPaste - where we expand the selection slightly for a command to do funky stuff with whitespace. Note that the handed in selStart/selEnd arguments can be modified by this routine (due to a call to TextInteractor::PreInteractiveUndoHelperHook). We then preserve the ACTUAL selection at the time this was called in the restuing 'beforeRep' object. |
|
Bad name. Basicly does a small portion of the click handling code. Vectored out not only for code sharing, but to provide a hook we can use in the StyledTextInteractor code to handle embeddings (without massive cut/n/paste duplication of code). What this does is to convert the click (or double or tripple click into an appropriate selection. The anchor only has meaning for double clicks with exteneded selection on. This routine uses the existing selection, and just adjusts that selection. This routine returns true if all went well, and you should continue with interpretting click. It returns false if you should assume something clicked on swallowed up the click. This is not a GREAT line to have drawn for the API boundary. But its a start. LGP 960303 |
|
TextInteractor's have an associated default UpdateMode. This utility method takes an arbitrary UpdateMode, and returns either its argument, or if it was eDefaultUpdateMode, it returns the current value of the default update mode. |
|
Scroll the current window, so that the selection is showing. Calls TextInteractor::ScrollSoShowing (). Since TextInteractor::ScrollSoShowing () requires two marker-positions to try to show, we use the instance variable fLeftSideOfSelectionInteresting to guess which side of the selection the user is probably most interested in. This routine also pays attention to TextImager::GetCaretShownAfterPos so that it shows the right part of the screen in ambiguous cases. See TextImager::ScrollSoShowing for more details. But basicly this tries to show the entire selection, if possible. And uses the flag to pick which side of the selection to use if only part of it can be made visible in the current window at once. |
|
See |
|
OBSOLETE. |
|
|
|
|
|
See also |
|
OBSOLETE. |
|
TextInteractor's have an associated default UpdateMode. This is the update mode which is used by methods which used the eDefaultUpdateMode argument (most default UpdateMode args in Led are this value). This should not be set directly. Instead, instantiate a |
|
Calls |
|
Calls |
|
OBSOLETE. |
|
Specify whether or not the interactor will display / manage scrollbars. This really is handled in OS/ClassLib specific subclasses. But the API is here to keep it uniform across the platforms. The default settings for each direction (v/h) are 'TextInteractor::eScrollBarNever'. On windows I recall that it USED to be standard that an edit text would suddenly spawn a scrollbar when needed. This doesn't appear to be the case any longer. I always hated this behavior, but since I didn't know better, I implemented it. Even though this behavior is no longer particularly standared or common, it is sometimes desired, and so supported. NB: You need not turn on the WS_V/HSCROLL styles to make the scrollbars appear/disapear. When this is on, it is handled automagically. NB: This USED to be controlled by a compile-time variable qMakeWindowsScrollbarAppearOnlyIfNeeded, which is now obsolete. See also 'TextInteractor::GetScrollBarType' and |
|
See TextInteractor::GetSelection. |
|
See TextInteractor::GetSelectionShown. Typically this method isn't called directly by user code, but from within the class library wrappers (e.g. Led_MFC) on gain/lose focus events. |
|
Set the 'smart cut and paste' mode. See TextInteractor::GetSmartCutAndPasteMode for more details. |
|
OBSOLETE. |
|
Helper to implemented best feeling UI for double click detection. |
|
Override this to handle any update of the scrollbars you may need to. Something has happened to
invalidate what they now display (new text added, scrolled, or whatever - someone called |
|
Helper to share code among implementations. Call this while mouse is down to handle autoscrolling, and selection updating. |
|
Override this to provide (typically modal) override of the selection behavior during tracking. For example, if you want to only allow selection of whole lines when the caps-lock key is down (OK, silly, but its an example), you could check for that state in this routine, and assure selStart and selEnd are adjusted to meet those criteria. By default this does nothing (at least for now...LGP 970322 - whole idea immature, and needs work) The various _ForXXX versions are sample implementations you can call from your WhileTrackingConstrainSelection () override (typically checking some external state variable as I said before). These basicly just allow us to share a bit of code accross Led_MFC, Led_PP, etc implementations. See also, |
|
|
|
|
TextInteractor::BadUserInput [public]
See TextInteractor::OnBadUserInput.
TextInteractor::CommandNames [public]
Command names for each of the user-visible commands produced by the TextInteractor module.
This name is used used in the constructed Undo command name, as
in, "Undo Paste". You can replace this name with whatever you like.
You change this value with TextInteractor::SetCommandNames.
The point of this is to allow for different UI-language localizations, without having to change Led itself.
See also TextInteractor::GetCommandNames.
See also WordProcessor::CommandNames.
TextInteractor::TemporarilySetUpdateMode [public]
See TextInteractor::GetDefaultUpdateMode.
TextInteractor::UndoableContextHelper [public]
Use this helper class in a context where you are creating/doing an undoable
command. This class is a simpler wrapper/helper for TextInteractor::PreInteractiveUndoHelper
and TextInteractor::PostInteractiveUndoHelper.
A simple example usage would be:
UndoableContextHelper undoContext (*this, GetCommandNames ().fClearCommandName, true);
//Actual command guts
InteractiveReplace_ (undoContext.GetSelStart (), undoContext.GetSelEnd (), LED_TCHAR_OF (""), 0);
undoContext.CommandComplete ();
Note - the 'allowSmartCNPExpansion' should generally be true if the undoable action could have invoked smartcutandpaste space additions/removealls. Specifing true expands the region we capture to take this possability into account.
TextInteractor::UpdateMode [public]
Support for controlling how/when the window is updated. This is a key difference between
a TextImager and a TextInteractor. A TextInteractor introduces the concept of a real GUI
window that can get out of data, and needs to be updated. These updateModes control
the basic updating/timing strategies for redrawing portions of the textimager.
TextInteractorCommandHelper_DefaultCmdInfo [public]
See TextInteractorCommonCommandHelper
TextInteractorCommonCommandHelper < BASECLASS,CMD_INFO,CMD_ENABLER > [public]
BASECLASSSee TextInteractorCommandHelper_DefaultCmdInfo.
The class CMD_ENABLER must look roughly like this and have these methods:
class TmpCmdUpdater {
public:
typedef unsigned int CommandNumber;
public:
nonvirtual CommandNumber GetCmdID ();
nonvirtual void SetEnabled (bool enabled); // enable the command
nonvirtual void SetChecked (bool checked); // check the menu item
nonvirtual void SetText (const Led_SDK_Char* text);
};
You may be able to find one of these in your class library wrappers module. For example, using MFC, you can
use Led_MFC_TmpCmdUpdater.
The class CMD_INFO must look roughly like this and have these methods:
class MyCommandInfo : public TextInteractorCommandHelper_DefaultCmdInfo {
public:
typedef unsigned int CommandNumber;
typedef Led_FontSpecification::FontNameSpecifier FontNameSpecifier;
public:
enum {
kBaseFontSize_CmdID = YOUSPECIFY,
...
kShowHideSpaceGlyphs_CmdID = YOUSPECIFY,
};
};
This CMD_INFO class you must provide yourself, based on information about your program. You may want
to look at the LedItMFC sample application for an example of this.
The main thing you do with the MyCommandInfo class is to override the default specifications of the command numbers
(all kNoCommand_CmdID by default) with the command numbers you've specified in your resource
file (and mapped to menus etc).
See also WordProcessorCommonCommandHelper.
TrivialImager_Interactor < 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.
The usuage can be as simple as:
void SomeAppDrawCall (Led_Tablet t, const Led_Rect& r)
{
TrivialImager_Interactor
See also TrivialImager, and TrivialWordWrappedImager
qBackwardCompatTextInteractorCmdNames [public]
OBSOLETE (as of Led 3.0b2, 2000-08-17).
qBackwardCompatUndoHelpers [public]
OBSOLETE (as of Led 3.0b2, 2000-08-19).
qSupportEnterIdleCallback [public]
This callback can be used to implement various optimizations, were we don't need to actually fix something (like sbar position) til the last minute, when were done with some big operation (lots of text changes), and were about to display
We define an API method - TextInteractor::OnEnterIdleCallback () which must be called by some other
service - by default it is expected the Led_<CLASSLIB> code will call this. But someone
outside TextInteractor must call it, as appropriate.
qUseGDIScrollbitsForScrolling [public]
OBSOLETE (as of Led 3.0d3, 991228). Instead - use TextInteractor::SetUseBitmapScrollingOptimization
Return to Led Page
Return to Led ClassLib Documentation Index
Return to Led Reference Manual Index