35 PageItemFocus manages switches between page item event handling (PageItemEventHandler) and text event handling (FrameEventHandler).
36 Page items and text selection have different event handlers: i.e. arrow key left moves a page item to the left on the spread if the
37 PageItemEventHandler is active while the same key event moves the caret by one character to the left if the FrameEventHandler is activated.
38 If the user switches from page item selection to text selection or vice versa the corresponding event handler needs to be registered as
39 the current event handler. This is done via KeyFocusHandler::SetCurrentTargetEventHandler in three steps:
40 - calling IEventHandler::GiveUpKeyFocus() on the current event handler.
41 - replacing the current event handler with the new one.
42 - calling IEventHandler::GetKeyFocus() on the new event handler.
43
44 There are several situations that require a change of event handlers and a call to KeyFocusHandler::SetCurrentTargetEventHandler:
45 - Activation of TextSelection after creating a new TextFrame
46 - Deactivation of TextSelection after switching to pointer tool.
47 - Activation of TextSelection after clicking with pointer tool into TextFrame.
48
49 PageItemFocus offers a convenient API for activating and deactivating. PageItemFocus is implemented in PublicLib with kPageItemFocusImpl. It is only used by kStandOffBoss.
50 FrameViewFocus is derived from PageItemFocus and is implemented in TextEditor with kFrameViewFocusImpl. It is only used by kTextEditorBoss:
51 - kStandOffBoss uses kPageItemFocusImpl
52 - kTextEditorBoss uses kFrameViewFocusImpl
53
54 This interface is part of the PageItem widget. It helps to differentiate between
55 several cases of deactivation.
56 Grant/RevokePageItemFocus is called, when the pageitem has the focus (i.e. if the user edits it).
57 The selection would be visible and a TextCaret would blink.
58 Suspend/ResumePageItemFocus is called when the window or the layout control view is deactivated.
59 The selection would be shadowed, but a TextCaret would disappear.
60
61 These are possible cases for Grant/Revoke and Suspend/Resume:
62 1) Deactivate Window => Suspend( kTrue )
63 2) Reactivate Window => Resume
64 3) Change the tool => Suspend( kFalse )
65 4) Change back to the first tool => Resume
66 5) Close Document => Revoke
67 6) Create new PageItem => Grant
68 7) Place a story => Revoke
69 8) Change to an EditBox in a Panel => Suspend( kTrue )
70
71 Call stacks:
72
73 (1) Call stack: Activation of TextSelection after creating a new TextFrame
1.8.3.1 
