add doc for highlight mode

graf2d/gpad/src/TCanvas.cxx

@@ -1531,10 +1531,10 @@ void TCanvas::Picked(TPad *pad, TObject *obj, Int_t event)
 ////////////////////////////////////////////////////////////////////////////////
 /// Emit Highlighted() signal.
 ///
-/// pad is pointer to pad with highlighted histogram or graph
-/// obj is pointer to highlighted histogram or graph
-/// x   is highlighted x bin for 1D histogram or highlighted x-th point for graph
-/// y   is highlighted y bin for 2D histogram (for 1D histogram or graph not in use)
+///  - pad is pointer to pad with highlighted histogram or graph
+///  - obj is pointer to highlighted histogram or graph
+///  - x is highlighted x bin for 1D histogram or highlighted x-th point for graph
+///  - y is highlighted y bin for 2D histogram (for 1D histogram or graph not in use)
 
 void TCanvas::Highlighted(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)
 {
@@ -1549,7 +1549,8 @@ void TCanvas::Highlighted(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// This is helper for function TCanvas::Connect for specific slot.
+/// This is "simplification" for function TCanvas::Connect with Highlighted
+/// signal for specific slot.
 ///
 /// Slot has to be defined "UserFunction(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)"
 /// all parameters of UserFunction are taken from TCanvas::Highlighted

hist/histpainter/src/TGraphPainter.cxx

@@ -60,6 +60,7 @@ ClassImp(TGraphPainter);
 - [Colors automatically picked in palette](#GP05)
 - [Reverse graphs' axis](#GP06)
 - [Graphs in logarithmic scale](#GP07)
+- [Highlight mode for graph](#GP08)
 
 
 ### <a name="GP00"></a> Introduction
@@ -532,6 +533,45 @@ Begin_Macro(source)
 }
 
 End_Macro
+
+#### <a name="GP08"></a> Highlight mode for graph
+
+\since **ROOT version 6.13/04**
+
+\image html hlGraph1.gif "Highlight mode"
+
+Highlight mode is implemented for `TGraph` (and for `TH1`) class. When
+highlight mode is on, mouse movement over the point will be represented
+graphically. Point will be highlighted as "point circle" (presented by
+marker object). Moreover, any highlight (change of point) emits signal
+`TCanvas::Highlighted()` which allows the user to react and call their own
+function. For a better understanding please see also the tutorials
+`$ROOTSYS/tutorials/graphs/hlGraph*.C` files.
+
+Highlight mode is switched on/off by `TGraph::SetHighlight()` function
+or interactively from `TGraph` context menu. `TGraph::IsHighlight()` to verify
+whether the highlight mode enabled or disabled, default it is disabled.
+
+    root [0] .x $ROOTSYS/tutorials/graphs/gerrors2.C
+    root [1] // try SetHighlight() interactively from TGraph context menu
+
+\image html hlgerrors2.gif "Highlight mode for graph"
+
+See how it is used
+<a href="classTHistPainter.html#HP30a">highlight mode and user function</a>
+(is fully equivalent as for histogram).
+
+NOTE all parameters of user function are taken from
+
+    void TCanvas::Highlighted(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)
+
+-  `pad` is pointer to pad with highlighted graph
+-  `obj` is pointer to highlighted graph
+-  `x` is highlighted x-th (i-th) point for graph
+-  `y` not in use (only for 2D histogram)
+
+For more complex demo please see for example `$ROOTSYS/tutorials/math/hlquantiles.C` file.
+
 */
 
 

hist/histpainter/src/THistPainter.cxx

@@ -130,6 +130,8 @@
    - [Box](#HP29n)
    - [Iso](#HP29o)
    - [Parametric plot](#HP29p)
+- [Highlight mode for histogram](#HP30)
+   - [Highlight mode and user function](#HP30a)
 
 
 ## <a name="HP00"></a> Introduction
@@ -2961,6 +2963,97 @@ about 20 color schemes supported ('s' for "scheme"); 'l' or 'L' to
 increase number of polygons ('l' for "level" of details), 'w' or 'W'
 to show outlines ('w' for "wireframe").
 
+#### <a name="HP30"></a> Highlight mode for histogram
+
+\since **ROOT version 6.13/04**
+
+\image html hlHisto3.gif "Highlight mode"
+
+Highlight mode is implemented for `TH1` (and for `TGraph`) class. When
+highlight mode is on, mouse movement over the bin will be represented
+graphically. Bin will be highlighted as "bin box" (presented by box
+object). Moreover, any highlight (change of bin) emits signal
+`TCanvas::Highlighted()` which allows the user to react and call their own
+function. For a better understanding please see also the tutorials
+`$ROOTSYS/tutorials/hist/hlHisto*.C` files.
+
+Highlight mode is switched on/off by `TH1::SetHighlight()` function
+or interactively from `TH1` context menu. `TH1::IsHighlight()` to verify
+whether the highlight mode enabled or disabled, default it is disabled.
+
+    root [0] .x $ROOTSYS/tutorials/hsimple.C
+    root [1] hpx->SetHighlight(kTRUE)   // or interactively from TH1 context menu
+    root [2] hpx->IsHighlight()
+    (bool) true
+
+\image html hlsimple_nofun.gif "Highlight mode for histogram"
+
+#### <a name="HP30a"></a> Highlight mode and user function
+
+The user can use (connect) `TCanvas::Highlighted()` signal, which is always
+emitted if there is a highlight bin and call user function via signal
+and slot communication mechanism. `TCanvas::Highlighted()` is similar
+`TCanvas::Picked()`
+
+-  when selected object (histogram as a whole) is different from previous
+then emit `Picked()` signal
+-  when selected (highlighted) bin from histogram is different from previous
+then emit `Highlighted()` signal
+
+Any user function (or functions) has to be defined
+`UserFunction(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)`.
+In example (see below) has name `PrintInfo()`. All parameters of user
+function are taken from
+
+    void TCanvas::Highlighted(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)
+
+-  `pad` is pointer to pad with highlighted histogram
+-  `obj` is pointer to highlighted histogram
+-  `x` is highlighted x bin for 1D histogram
+-  `y` is highlighted y bin for 2D histogram (for 1D histogram not in use)
+
+Example how to create a connection from any `TCanvas` object to a user
+`UserFunction()` slot (see also `TQObject::Connect()` for additional info)
+
+    TQObject::Connect("TCanvas", "Highlighted(TVirtualPad*,TObject*,Int_t,Int_t)",
+                          0, 0, "UserFunction(TVirtualPad*,TObject*,Int_t,Int_t)");
+
+or use non-static "simplified" function
+`TCanvas::HighlightConnect(const char *slot)`
+
+    c1->HighlightConnect("UserFunction(TVirtualPad*,TObject*,Int_t,Int_t)");
+
+NOTE the signal and slot string must have a form
+"(TVirtualPad*,TObject*,Int_t,Int_t)"
+
+    root [0] .x $ROOTSYS/tutorials/hsimple.C
+    root [1] hpx->SetHighlight(kTRUE)
+    root [2] .x hlprint.C
+
+file `hlprint.C`
+~~~ {.cpp}
+void PrintInfo(TVirtualPad *pad, TObject *obj, Int_t x, Int_t y)
+{
+   TH1F *h = (TH1F *)obj;
+   if (!h->IsHighlight()) // after highlight disabled
+      h->SetTitle("highlight disable");
+   else
+      h->SetTitle(TString::Format("bin[%03d] (%5.2f) content %g", x,
+                                  h->GetBinCenter(x), h->GetBinContent(x)));
+   pad->Update();
+}
+
+void hlprint()
+{
+   if (!gPad) return;
+   gPad->GetCanvas()->HighlightConnect("PrintInfo(TVirtualPad*,TObject*,Int_t,Int_t)");
+}
+~~~
+
+\image html hlsimple.gif "Highlight mode and simple user function"
+
+For more complex demo please see for example `$ROOTSYS/tutorials/tree/temperature.C` file.
+
 */
 
 TH1 *gCurrentHist = 0;