--- a/ActiveHelp.st	Sat Apr 27 19:59:33 1996 +0200
+++ b/ActiveHelp.st	Mon Apr 29 10:13:30 1996 +0200
@@ -78,14 +78,21 @@
     [author:]
         Claus Gittinger
 
+    [start with:]
+        ActiveHelp start
+        ActiveHelp stop
+
     [See also:]
-        ActiveHelp
+        ActiveHelpView
+        WindowGroup WindowEvent
+        ApplicationModel StandardSystemView
 "
 !
 
 examples
 "
-    (make certain that activeHelp is turned on ...)
+    (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
@@ -117,8 +124,10 @@
         top open
                                                                         [exEnd]
 
+    (make certain that activeHelp is turned on ...
+     ... otherwise, you will see nothing)
+
     alternatively, display of the helpMessage in a local, private view:
-
                                                                         [exBegin]
         |app top button1 button2 infoView|
 
@@ -156,40 +165,56 @@
 !ActiveHelp class methodsFor:'initialization'!
 
 initialize
+    "set default delay & help-display times"
+
     ShowTime := 15.
     DelayTime := 2.
 
     "
      ActiveHelp initialize
     "
+
+    "Modified: 27.4.1996 / 15:07:27 / cg"
 ! !
 
 !ActiveHelp class methodsFor:'startup'!
 
-isActive 
+isActive
+    "return true, if activeHelp is turned on"
+
     ^ TheOneAndOnlyHelpListener notNil
+
+    "Modified: 27.4.1996 / 15:07:57 / cg"
 !
 
 start
+    "start activeHelp"
+
     TheOneAndOnlyHelpListener isNil ifTrue:[
-	TheOneAndOnlyHelpListener := self new.
+        TheOneAndOnlyHelpListener := self new.
     ].
     TheOneAndOnlyHelpListener listen
 
     "
      ActiveHelp start
     "
+
+    "Modified: 27.4.1996 / 15:08:05 / cg"
 !
 
 stop
+    "stop activeHelp"
+
     TheOneAndOnlyHelpListener notNil ifTrue:[
-	TheOneAndOnlyHelpListener unlisten.
+        TheOneAndOnlyHelpListener unlisten.
     ].
     TheOneAndOnlyHelpListener := nil
 
     "
      ActiveHelp stop
     "
+
+    "Modified: 27.4.1996 / 15:08:11 / cg"
 ! !
 
 !ActiveHelp class methodsFor:'times'!
@@ -223,130 +248,154 @@
 !ActiveHelp methodsFor:'listening'!
 
 buttonMotion:state x:x y:y view:view
+    "handle motion events - if the mousepointer left the 
+     previous helped view, hide the help"
+
     self hideIfPointerLeft:view.
     ^ false
+
+    "Modified: 27.4.1996 / 15:09:48 / cg"
 !
 
 buttonPress:state x:x y:y view:view
+    "handle button press - unconditionally hide the help"
+
     self hideHelp.
     ^ false
+
+    "Modified: 27.4.1996 / 15:09:45 / cg"
 !
 
 keyPress:state x:x y:y view:view
+    "handle key press - unconditionally hide the help"
+
     self hideHelp.
     ^ false
+
+    "Modified: 27.4.1996 / 15:09:57 / cg"
 !
 
 pointerEnter:state x:x y:y view:aView
+    "handle pointer entering a view; setup timeOut to show help"
+
     |text p|
 
     showProcess notNil ifTrue:[
-	p := showProcess. showProcess := nil.
-	p terminate.
+        p := showProcess. showProcess := nil.
+        p terminate.
     ].
     self hideIfPointerLeft:aView.
     aView topView == currentHelpView ifTrue:[
-	^ true
+        ^ true
     ].
 
     self initiateHelpFor:aView atX:x y:y.
     ^ false
+
+    "Modified: 27.4.1996 / 15:10:27 / cg"
 !
 
 pointerLeave:state view:view
+    "handle pointer leaving a view; hide help text"
+
     self hideIfPointerLeft:view.
     ^ false
+
+    "Modified: 27.4.1996 / 15:10:41 / cg"
 ! !
 
 !ActiveHelp methodsFor:'private'!
 
 helpTextFor:aView atX:x y:y
-    "pointer entered aView; 
+    "retrieve helptext for aView as a string; 
      walk along the views 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 walk and the
+     #helpTextFor:at: or #helpTextFor: message ends this search and the
      returned string is returned."
 
     |model text view org found v sv|
 
     view := aView.
     (model := aView model) notNil ifTrue:[
-	(model respondsTo:#helpTextFor:at:) ifTrue:[
-	    text := model helpTextFor:aView at:x@y.
-	    text notNil ifTrue:[^ text].
-	].
-	(model respondsTo:#helpTextFor:) ifTrue:[
-	    text := model helpTextFor:aView.
-	    text notNil ifTrue:[^ text].
-	]
+        (model respondsTo:#helpTextFor:at:) ifTrue:[
+            text := model helpTextFor:aView at:x@y.
+            text notNil ifTrue:[^ text].
+        ].
+        (model respondsTo:#helpTextFor:) ifTrue:[
+            text := model helpTextFor:aView.
+            text notNil ifTrue:[^ text].
+        ]
     ].
 
     (aView respondsTo:#helpText) ifTrue:[
-	text := aView helpText.
-	text notNil ifTrue:[^ text].
+        text := aView helpText.
+        text notNil ifTrue:[^ text].
     ].
 
     "walk up the chain - maybe someone knows about its subview ..."
     v := aView.
 
     [(sv := v superView) notNil] whileTrue:[
-	(model := sv model) notNil ifTrue:[
-	    (model respondsTo:#helpTextFor:at:) ifTrue:[
-		text := model helpTextFor:aView at:x@y.
-		text notNil ifTrue:[^ text].
-	    ].
-	    (model respondsTo:#helpTextFor:) ifTrue:[
-		text := model helpTextFor:aView.
-		text notNil ifTrue:[^ text].
-	    ]
-	].
+        (model := sv model) notNil ifTrue:[
+            (model respondsTo:#helpTextFor:at:) ifTrue:[
+                text := model helpTextFor:aView at:x@y.
+                text notNil ifTrue:[^ text].
+            ].
+            (model respondsTo:#helpTextFor:) ifTrue:[
+                text := model helpTextFor:aView.
+                text notNil ifTrue:[^ text].
+            ]
+        ].
 
-	(sv respondsTo:#helpTextFor:) ifTrue:[
-	    text := sv helpTextFor:aView.
-	    text notNil ifTrue:[^ text].
-	    text := sv helpTextFor:v.
-	    text notNil ifTrue:[^ text].
-	 ].
-	 v := sv.
+        (sv respondsTo:#helpTextFor:) ifTrue:[
+            text := sv helpTextFor:aView.
+            text notNil ifTrue:[^ text].
+            text := sv helpTextFor:v.
+            text notNil ifTrue:[^ text].
+         ].
+         v := sv.
     ].
 
     (v notNil and:[v respondsTo:#application]) ifTrue:[
-	(model := v application) notNil ifTrue:[
-	    (model respondsTo:#helpTextFor:at:) ifTrue:[
-		text := model helpTextFor:aView at:x@y.
-		text notNil ifTrue:[^ text].
-	    ].
-	    (model respondsTo:#helpTextFor:) ifTrue:[
-		text := model helpTextFor:aView.
-		text notNil ifTrue:[^ text].
-	    ]
-	]
+        (model := v application) notNil ifTrue:[
+            (model respondsTo:#helpTextFor:at:) ifTrue:[
+                text := model helpTextFor:aView at:x@y.
+                text notNil ifTrue:[^ text].
+            ].
+            (model respondsTo:#helpTextFor:) ifTrue:[
+                text := model helpTextFor:aView.
+                text notNil ifTrue:[^ text].
+            ]
+        ]
     ].
     (v notNil and:[v respondsTo:#model]) ifTrue:[
-	(model := v model) notNil ifTrue:[
-	    (model respondsTo:#helpTextFor:at:) ifTrue:[
-		text := model helpTextFor:aView at:x@y.
-		text notNil ifTrue:[^ text].
-	    ].
-	    (model respondsTo:#helpTextFor:) ifTrue:[
-		text := model helpTextFor:aView.
-		text notNil ifTrue:[^ text].
-	    ]
-	]
+        (model := v model) notNil ifTrue:[
+            (model respondsTo:#helpTextFor:at:) ifTrue:[
+                text := model helpTextFor:aView at:x@y.
+                text notNil ifTrue:[^ text].
+            ].
+            (model respondsTo:#helpTextFor:) ifTrue:[
+                text := model helpTextFor:aView.
+                text notNil ifTrue:[^ text].
+            ]
+        ]
     ].
 
     (view class respondsTo:#helpText) ifTrue:[
-	text := view class helpText.
-	text notNil ifTrue:[^ text].
+        text := view class helpText.
+        text notNil ifTrue:[^ text].
     ].
 
     ^ nil
 
     "Modified: 31.8.1995 / 20:38:00 / claus"
+    "Modified: 27.4.1996 / 15:11:22 / cg"
 !
 
 hideIfPointerLeft:aView
+    "hide help, if the pointer is not in aView"
+
     |whereOnScreen p|
 
 "/    showProcess notNil ifTrue:[
@@ -358,67 +407,79 @@
 
     (currentFrame notNil
     and:[(currentFrame insetBy:1@1) containsPoint:whereOnScreen]) ifFalse:[
-	self hideHelp.
-	currentView := nil
+        self hideHelp.
+        currentView := nil
     ].
+
+    "Modified: 27.4.1996 / 15:11:35 / cg"
 !
 
 initiateHelpFor:aView atX:x y:y
+    "start a timeout process to display help for aView after some delay"
+
     |text p|
 
     text := self helpTextFor:aView atX:x y:y.
 
     text notNil ifTrue:[
-	DelayTime > 0 ifTrue:[
-	    showProcess notNil ifTrue:[
-		p := showProcess. showProcess := nil.
-		p terminate.
-	    ].
-	    showProcess := [
-		    (Delay forSeconds:DelayTime) wait.
-		    showProcess := nil.
-		    self showHelp:text for:aView
-	    ] forkAt:(Processor userSchedulingPriority + 1).
-	] ifFalse:[
-	    self showHelp:text for:aView
-	]
+        DelayTime > 0 ifTrue:[
+            showProcess notNil ifTrue:[
+                p := showProcess. showProcess := nil.
+                p terminate.
+            ].
+            showProcess := [
+                    (Delay forSeconds:DelayTime) wait.
+                    showProcess := nil.
+                    self showHelp:text for:aView
+            ] forkAt:(Processor userSchedulingPriority + 1).
+        ] ifFalse:[
+            self showHelp:text for:aView
+        ]
     ].
+
+    "Modified: 27.4.1996 / 15:12:03 / cg"
 ! !
 
 !ActiveHelp methodsFor:'show / hide help'!
 
 hideHelp
+    "hide the help text"
+
     |p|
 
     showProcess notNil ifTrue:[
-	p := showProcess. showProcess := nil.
-	p terminate.
+        p := showProcess. showProcess := nil.
+        p terminate.
     ].
     currentHelpView notNil ifTrue:[
-	[
-	    currentHelpView destroy.
-	    currentHelpView := nil.
-	    currentView := nil.
-	] valueUninterruptably
+        [
+            currentHelpView destroy.
+            currentHelpView := nil.
+            currentView := nil.
+        ] valueUninterruptably
     ].
     currentFrame := nil.
     closeProcess notNil ifTrue:[
-	p := closeProcess. closeProcess := nil.
-	p terminate.
+        p := closeProcess. closeProcess := nil.
+        p terminate.
     ]
+
+    "Modified: 27.4.1996 / 15:12:13 / cg"
 !
 
 showHelp:aHelpText for:view
+    "show the help text for aView"
+
     |org p v|
 
     view == currentView ifTrue:[^ self].
 
     closeProcess notNil ifTrue:[
-	p := closeProcess. closeProcess := nil.
-	p terminate.
+        p := closeProcess. closeProcess := nil.
+        p terminate.
     ].
     currentHelpView notNil ifTrue:[
-	self hideHelp
+        self hideHelp
     ].
 
     org := view originRelativeTo:nil.
@@ -430,10 +491,10 @@
     org := view device pointerPosition.
     org := org + (10@10).
     (org x + v width) > view device width ifTrue:[
-	org := (org x - v width) @ org y
+        org := (org x - v width) @ org y
     ].
     (org y + v height) > view device height ifTrue:[
-	org := org x @ (org y - v height).
+        org := org x @ (org y - v height).
     ].
 
     v origin:org.
@@ -445,25 +506,26 @@
 
     currentView := view.
     closeProcess := [
-	Process terminateSignal handle:[:ex |
-	    closeProcess := nil.
-	] do:[
-	    (Delay forSeconds:ShowTime) wait.
-	    [
-		currentHelpView notNil ifTrue:[
-		    currentHelpView destroy.
-		    currentHelpView := nil.
-		]
-	    ] valueUninterruptably
-	].
+        Process terminateSignal handle:[:ex |
+            closeProcess := nil.
+        ] do:[
+            (Delay forSeconds:ShowTime) wait.
+            [
+                currentHelpView notNil ifTrue:[
+                    currentHelpView destroy.
+                    currentHelpView := nil.
+                ]
+            ] valueUninterruptably
+        ].
     ] forkAt:(Processor userSchedulingPriority + 1).
 
     "Modified: 31.8.1995 / 19:20:45 / claus"
+    "Modified: 27.4.1996 / 15:12:25 / cg"
 ! !
 
 !ActiveHelp class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libview2/ActiveHelp.st,v 1.11 1996-04-27 12:42:52 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libview2/ActiveHelp.st,v 1.12 1996-04-29 08:13:19 cg Exp $'
 ! !
 ActiveHelp initialize!