|
Class: ActiveHelp
Object
|
+--EventListener
|
+--ActiveHelp
|
+--FlyByHelp
- Package:
- stx:libview2
- Category:
- Interface-Help
- Version:
- rev:
1.107
date: 2019/06/28 06:49:48
- user: cg
- file: ActiveHelp.st directory: libview2
- module: stx stc-classLibrary: libview2
- Author:
- Claus Gittinger
The active help (tooltip) listener.
The one and only instance of myself intercepts incoming mouse & keyboard
events for the display device, being especially interested in view-enter/
leave events. When such an event arrives, it asks the corresponding view
or its model for a help message and displays it via an ActiveHelpView.
Actually, the view is first asked if it would like to display it itself
- for example, in some information-view at the bottom of its main window.
The query for the helpText is repeated along the view's superView chain,
until any model or view returns a nonNil answer for the
#helpTextFor:<aSubView> at:<position> or #helpTextFor:<aSubView> message.
All I need for automatic help is some model/view/applicationModel along
the superview chain of the entered component, which responds to the
#helpTextFor: message with a non-nil (string-) answer.
I close down the help view after a while, if a key is pressed or the mouse
moved to another view.
Who should provide the helpText:
the best place is the application object (an instance of ApplicationModel)
or the topView, if it's a derived class of StandardSystemView.
This should know about its components and return the string
when asked via #helpTextFor:<aSubView>.
See examples in FileBrowser, Launcher etc.
Be aware, that for applicationModels, there must be a link from the
topView to this applicationModel
(set via: aTopView application:anApplicationModel)
otherwise, the helpManager has no means of finding the application which
corresponds to a view.
Who should display the helpText:
by default, the helpListener opens a little popup view, which displays the
returned help message. However, a nice trick which can be used by applications
is to create an infoLabel as a subview of the topFrame (a la windows)
and display the text right in the #helpTextFor: method. To cheat the
help listener, this method should then return nil, to keep it silent.
Usage:
If help is to be shown for all views (as enabled by the launchers help menu),
use 'ActiveHelp start' and 'ActiveHelp stop'.
Individual apps may enable/disable active help for themself by:
'ActiveHelp startFor:app' or 'ActiveHelp stopFor:app', passing either
the topView or the topViews application as argument.
This is usually done by applications which want to show contextHelp in
some infoView.
Late note: thsi is no longer recommended - one such mouse watcher process is
good enough for all views.
ActiveHelpView
WindowGroup
WindowEvent
ApplicationModel
StandardSystemView
accessing
-
debugging
-
-
debugging: aBoolean
-
self debugging:true
self debugging:false
-
debuggingHelpText
-
-
debuggingHelpText: aBoolean
-
self debuggingHelpText:true
self debuggingHelpText:false
-
singleton
-
initialization
-
initialize
-
(comment from inherited method)
called only once - initialize signals
queries
-
currentHelpListener
-
return the activeHelp listener if activeHelp is turned on, nil otherwise
usage example(s):
ActiveHelp currentHelpListener
FlyByHelp currentHelpListener
|
-
delayTime
-
-
isActive
-
return true, if activeHelp is turned on
usage example(s):
-
showTime
-
set the number of seconds, a help messages is to be shown.
The default is 45 seconds.
0 means: show forever (i.e. until mouse is moved)
start & stop
-
initiateHelp
-
determine where the mouse pointer is located,
and start showing a tooltip for it.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)
-
start
-
start activeHelp for all apps
usage example(s):
ActiveHelp start
FlyByHelp start
|
-
startFor: anApplicationOrTopView
-
start activeHelp for a single app
-
stop
-
stop activeHelp for all (except for individual apps)
usage example(s):
ActiveHelp stop
FlyByHelp stop
|
-
stopFor: anAppOrTopView
-
stop activeHelp for a single app
times
-
delayTime: numberOfSeconds
-
set the delay (the time, the cursor has to be in the view
before help is shown). The default is 2 seconds.
usage example(s):
ActiveHelp delayTime:0.5
ActiveHelp delayTime:2
ActiveHelp delayTime:10
|
-
showTime: numberOfSeconds
-
set the number of seconds, a help messages is to be shown.
The default is 30 seconds.
0 means: show forever (i.e. until mouse is moved)
usage example(s):
ActiveHelp showTime:10
ActiveHelp showTime:99999
ActiveHelp showTime:30
|
event handling
-
buttonMotion: buttonAndModifierState x: x y: y view: aView
-
handle motion events - prepare to show help
-
handleMouseIn: aView x: x y: y
-
handle motion events - if the mousepointer left the
previous helped view, hide the help
-
keyPress: key x: x y: y view: view
-
unconditionally hide the help view
-
keyRelease: key x: x y: y view: view
-
unconditionally hide the help view
-
pointerEnter: state x: x y: y view: aView
-
handle pointer entering a view; prepare to show help
-
pointerLeave: state view: aView
-
handle pointer leaving a view; hide help text
-
processEvent: ev
-
DebuggingEvents := true
help texts
-
basicHelpTextFor: aView at: aDevicePointOrNil
-
retrieve helptext for aView as a string;
walk along the view's superView chain,
asking models and views encountered while walking.
The first one who understands and returns a nonNil answer to the
#helpTextFor:at: or #helpTextFor: message ends this search and the
returned string is returned.
-
helpTextFor: aView at: aDevicePointOrNil
-
retrieve helptext for aView as a string;
walk along the view's superView chain,
asking models and views encountered while walking.
The first one who understands and returns a nonNil answer to the
#helpTextFor:at: or #helpTextFor: message ends this search and the
returned string is returned.
-
helpTextFromModel: aModelOrTopView view: aView at: aPointOrNil
-
helper: ask aModel for its helpText.
-
helpTextFromView: aView at: aPointOrNil
-
helper: ask aView for its helpText.
private
-
hideIfPointerLeft: aView
-
hide help, if the pointer is not in aView
-
interestedIn: aView
-
return true, if I am interested in aView (either listeningForAll,
or in my list of apps)
-
targetViewInitiatesHelpViaSensor
-
true if the target view is asked to show the help via the sensor;
false, if I do it myself synchronously.
queries
-
delayTime
-
-
showTime
-
how long shall the help be shown;
0 means: forever (until user moves the mouse);
>0 means that number of seconds
show & hide help
-
hideHelp
-
hide the help text - nothing done here
-
hideHelpIgnoringErrors
-
hide the help text
-
initiateHelp
-
determine where the mouse pointer is located,
and start showing a tooltip for it right now.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)
-
initiateHelpFor: aView
-
start showing a tooltip for aView right now.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)
-
initiateHelpFor: aView at: aPointOrNil
-
ask aView for helpText, passing x/y coordinates;
start a timeout process to display this helpText after some delay;
Normally used internally, but can also be used by widgets to force
re-negotiation of the displayed helpText
(for example in a menu, when the selection changes)
-
initiateHelpFor: aView at: aPointOrNil now: showItNow
-
ask aView for helpText, passing x/y coordinates;
start a timeout process to display this helpText after some delay;
Normally used internally, but can also be used by widgets to force
re-negotiation of the displayed helpText
(for example in a menu, when the selection changes)
-
stopHelpDisplayProcess
-
start & stop
-
listenFor: anAppOrTopView
-
start listening
-
listenForAll
-
start listening
-
start
-
-
stop
-
-
unlistenAll
-
stop listening
-
unlistenFor: anApp
-
stop listening for an app
ActiveHelp start
ActiveHelp stop
Active Help for a single view
or app (whatever the global settings are):
Can be initiated by an app when its opened.
|app top myAppClass|
Class withoutUpdatingChangesDo:[
myAppClass := ApplicationModel
subclass:#'Demos::DemoApp'
instanceVariableNames:''
classVariableNames:''
poolDictionaries:''
category:'demos'.
myAppClass
compile:'helpTextFor:aView Transcript showCR:''hello''. ^ ''this is some helpText'''.
].
app := myAppClass new.
top := StandardSystemView new.
top extent:300@100.
top application:app.
top open.
ActiveHelp startFor:app.
Class withoutUpdatingChangesDo:[
myAppClass removeFromSystem
]
|
Active Help (for all views):
(make certain that activeHelp is turned on ...
... otherwise, you will see nothing)
the following example uses a Plug as a model replacement.
In concrete application, you would create a method to implement the helpText
query message.
|app top button1 button2|
app := Plug new.
app respondTo:#helpTextFor:
with:[:view |
view == button1 ifTrue:[
'this is button1'
] ifFalse:[
view == button2 ifTrue:[
'some help for button2'
] ifFalse:[
nil
]
]
].
top := StandardSystemView new.
top extent:300@100.
button1 := Button label:'b1' in:top.
button1 origin:0.0@0.0 corner:0.5@30.
button2 := Button label:'b2' in:top.
button2 origin:0.5@0.0 corner:1.0@30.
top model:app. '<-- normally this would be: top application:app'.
top open
|
(make certain that activeHelp is turned on ...
... otherwise, you will see nothing)
alternatively, display of the helpMessage in a local, private view:
|app top button1 button2 infoView|
app := Plug new.
app respondTo:#helpTextFor:
with:[:view | infoView label:'info ...'.
view == button1 ifTrue:[
infoView label:'this is button1'
].
view == button2 ifTrue:[
infoView label:'some help for button2'
].
nil
].
top := StandardSystemView new.
top extent:300@100.
button1 := Button label:'b1' in:top.
button1 origin:0.0@0.0 corner:0.5@30.
button2 := Button label:'b2' in:top.
button2 origin:0.5@0.0 corner:1.0@30.
infoView := Label label:'info ...' in:top.
infoView level:-1; origin:0.0@1.0 corner:1.0@1.0.
infoView topInset:(infoView preferredExtent y negated - 3);
leftInset:3;
rightInset:3;
bottomInset:3;
adjust:#left.
top model:app. '<-- normally this would be: top application:app'.
top open
|
|