mcs/class/System.Windows.Forms/System.Windows.Forms/HelpProvider.cs

   1 // Permission is hereby granted, free of charge, to any person obtaining
   2 // a copy of this software and associated documentation files (the
   3 // "Software"), to deal in the Software without restriction, including
   4 // without limitation the rights to use, copy, modify, merge, publish,
   5 // distribute, sublicense, and/or sell copies of the Software, and to
   6 // permit persons to whom the Software is furnished to do so, subject to
   7 // the following conditions:
   8 //
   9 // The above copyright notice and this permission notice shall be
  10 // included in all copies or substantial portions of the Software.
  11 //
  12 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  13 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  14 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  15 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  16 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  17 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  18 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  19 //
  20 // Copyright (c) 2005 Novell, Inc. (http://www.novell.com)
  21 //
  22 // Authors:
  23 //      Peter Bartok    (pbartok@novell.com)
  24 //
  25 //
  26
  27 // NOT COMPLETE
  28 // Still missing: Tie-in to HTML help when the user presses F1 on the control
  29
  30 using System;
  31 using System.Collections;
  32 using System.ComponentModel;
  33 using System.Drawing;
  34
  35 namespace System.Windows.Forms {
  36         [ToolboxItemFilter("System.Windows.Forms")]
  37         [ProvideProperty("ShowHelp", "System.Windows.Forms.Control, " + Consts.AssemblySystem_Windows_Forms)]
  38         [ProvideProperty("HelpNavigator", "System.Windows.Forms.Control, " + Consts.AssemblySystem_Windows_Forms)]
  39         [ProvideProperty("HelpKeyword", "System.Windows.Forms.Control, " + Consts.AssemblySystem_Windows_Forms)]
  40         [ProvideProperty("HelpString", "System.Windows.Forms.Control, " + Consts.AssemblySystem_Windows_Forms)]
  41         public class HelpProvider : Component, IExtenderProvider {
  42                 #region HelpProperty Class
  43                 private class HelpProperty {
  44                         internal string         keyword;
  45                         internal HelpNavigator  navigator;
  46                         internal string         text;
  47                         internal bool           show;
  48                         internal Control        control;
  49                         internal HelpProvider   hp;
  50
  51                         public HelpProperty(HelpProvider hp, Control control) {
  52                                 this.control = control;
  53                                 this.hp = hp;
  54
  55                                 keyword = null;
  56                                 navigator = HelpNavigator.AssociateIndex;
  57                                 text = null;
  58                                 show = false;
  59
  60                                 control.HelpRequested += hp.HelpRequestHandler;
  61                         }
  62
  63                         public string Keyword {
  64                                 get { return keyword; }
  65                                 set { keyword = value; }
  66                         }
  67
  68                         public HelpNavigator Navigator {
  69                                 get { return navigator; }
  70                                 set { navigator = value; }
  71                         }
  72
  73                         public string Text {
  74                                 get { return text; }
  75                                 set { text = value; }
  76                         }
  77
  78                         public bool Show {
  79                                 get { return show; }
  80                                 set { show = value; }
  81                         }
  82                 }
  83                 #endregion      // HelpProperty Class
  84
  85                 #region Local Variables
  86                 private string                  helpnamespace;
  87                 private Hashtable               controls;
  88                 private ToolTip.ToolTipWindow   tooltip;
  89                 private EventHandler            HideToolTipHandler;
  90                 private KeyPressEventHandler    HideToolTipKeyHandler;
  91                 private MouseEventHandler       HideToolTipMouseHandler;
  92                 private HelpEventHandler        HelpRequestHandler;
  93                 private object tag;
  94                 #endregion      // Local Variables
  95
  96                 #region Public Constructors
  97                 public HelpProvider() {
  98                         controls = new Hashtable();
  99                         tooltip = new ToolTip.ToolTipWindow();
 100
 101                         //UIA Framework: Event used to indicate that ToolTip is shown
 102                         tooltip.VisibleChanged += delegate (object sender, EventArgs args) {
 103                                 if (tooltip.Visible == true)
 104                                         OnUIAHelpRequested (this, new ControlEventArgs (UIAControl));
 105                                 else
 106                                         OnUIAHelpUnRequested (this, new ControlEventArgs (UIAControl));
 107                         };
 108
 109                         HideToolTipHandler = new EventHandler(HideToolTip);
 110                         HideToolTipKeyHandler = new KeyPressEventHandler(HideToolTipKey);
 111                         HideToolTipMouseHandler = new MouseEventHandler(HideToolTipMouse);
 112                         HelpRequestHandler = new HelpEventHandler(HelpRequested);
 113                 }
 114                 #endregion      // Public Constructors
 115
 116                 #region Public Instance Properties
 117                 [DefaultValue(null)]
 118                 [Editor ("System.Windows.Forms.Design.HelpNamespaceEditor, " + Consts.AssemblySystem_Design, "System.Drawing.Design.UITypeEditor, " + Consts.AssemblySystem_Drawing)]
 119                 [Localizable(true)]
 120                 public virtual string HelpNamespace {
 121                         get {
 122                                 return helpnamespace;
 123                         }
 124
 125                         set {
 126                                 helpnamespace = value;
 127                         }
 128                 }
 129
 130                 [Localizable (false)]
 131                 [Bindable (true)]
 132                 [TypeConverter (typeof (StringConverter))]
 133                 [DefaultValue (null)]
 134                 [MWFCategory ("Data")]
 135                 public object Tag
 136                 {
 137                         get { return this.tag; }
 138                         set { this.tag = value; }
 139                 }
 140                 #endregion      // Public Instance Properties
 141
 142                 #region Public Instance Methods
 143                 public virtual bool CanExtend(object target) {
 144                         if (!(target is Control)) {
 145                                 return false;
 146                         }
 147
 148                         if ((target is Form) || (target is ToolBar)) {
 149                                 return false;
 150                         }
 151
 152                         return true;
 153                 }
 154
 155                 [DefaultValue(null)]
 156                 [Localizable(true)]
 157                 public virtual string GetHelpKeyword(Control ctl) {
 158                         return GetHelpProperty(ctl).Keyword;
 159                 }
 160
 161                 [DefaultValue(HelpNavigator.AssociateIndex)]
 162                 [Localizable(true)]
 163                 public virtual HelpNavigator GetHelpNavigator(Control ctl) {
 164                         return GetHelpProperty(ctl).Navigator;
 165                 }
 166
 167                 [DefaultValue(null)]
 168                 [Localizable(true)]
 169                 public virtual string GetHelpString(Control ctl) {
 170                         return GetHelpProperty(ctl).Text;
 171                 }
 172
 173                 [Localizable(true)]
 174                 public virtual bool GetShowHelp(Control ctl) {
 175                         return GetHelpProperty(ctl).Show;
 176                 }
 177
 178                 public virtual void ResetShowHelp(Control ctl) {
 179                         HelpProperty    hp;
 180
 181                         hp = GetHelpProperty(ctl);
 182
 183                         if ((hp.Keyword != null) || (hp.Text != null)) {
 184                                 hp.Show = true;
 185                         } else {
 186                                 hp.Show = false;
 187                         }
 188                 }
 189
 190                 public virtual void SetHelpKeyword(Control ctl, string keyword) {
 191                         GetHelpProperty(ctl).Keyword = keyword;
 192                 }
 193
 194                 public virtual void SetHelpNavigator(Control ctl, HelpNavigator navigator) {
 195                         GetHelpProperty(ctl).Navigator = navigator;
 196                 }
 197
 198                 public virtual void SetHelpString(Control ctl, string helpString) {
 199                         GetHelpProperty(ctl).Text = helpString;
 200                 }
 201
 202                 public virtual void SetShowHelp(Control ctl, bool value) {
 203                         GetHelpProperty(ctl).Show = value;
 204                 }
 205
 206                 public override string ToString() {
 207                         return base.ToString() + ", HelpNameSpace: " + helpnamespace;
 208                 }
 209
 210                 #endregion      // Public Instance Methods
 211
 212                 #region Private Methods
 213                 private HelpProperty GetHelpProperty(Control control) {
 214                         HelpProperty hp;
 215
 216                         hp = (HelpProperty)controls[control];
 217                         if (hp == null) {
 218                                 hp = new HelpProperty(this, control);
 219                                 controls[control] = hp;
 220                         }
 221
 222                         return hp;
 223                 }
 224
 225                 private void HideToolTip(object Sender, EventArgs e) {
 226                         Control control;
 227
 228                         control = (Control)Sender;
 229                         control.LostFocus -= HideToolTipHandler;
 230
 231                         this.tooltip.Visible = false;
 232                 }
 233
 234                 private void HideToolTipKey(object Sender, KeyPressEventArgs e) {
 235                         Control control;
 236
 237                         control = (Control)Sender;
 238                         control.KeyPress -= HideToolTipKeyHandler;
 239
 240                         this.tooltip.Visible = false;
 241                 }
 242
 243                 private void HideToolTipMouse(object Sender, MouseEventArgs e) {
 244                         Control control;
 245
 246                         control = (Control)Sender;
 247                         control.MouseDown -= HideToolTipMouseHandler;
 248
 249                         this.tooltip.Visible = false;
 250                 }
 251
 252
 253                 // This is called when the user does a "what's this" style lookup. It uses the 'text' property
 254                 private void HelpRequested(object sender, HelpEventArgs e) {
 255                         Size    size;
 256                         Point   pt;
 257                         Control control;
 258
 259                         control = (Control)sender;
 260
 261                         //UIA Framework: Associates requested control with internal variable to generate event
 262                         UIAControl = control;
 263
 264                         if (GetHelpProperty(control).Text == null) {
 265                                 return;
 266                         }
 267
 268                         pt = e.MousePos;
 269
 270                         // Display Tip
 271                         tooltip.Text = GetHelpProperty(control).Text;
 272                         size = ThemeEngine.Current.ToolTipSize(tooltip, tooltip.Text);
 273                         tooltip.Width = size.Width;
 274                         tooltip.Height = size.Height;
 275                         pt.X -= size.Width / 2;
 276
 277                         if (pt.X < 0) {
 278                                 pt.X += size.Width / 2;
 279                         }
 280
 281                         if ((pt.X + size.Width) < SystemInformation.WorkingArea.Width) {
 282                                 tooltip.Left = pt.X;
 283                         } else {
 284                                 tooltip.Left = pt.X - size.Width;
 285                         }
 286
 287                         if ((pt.Y + size.Height) < (SystemInformation.WorkingArea.Height - 16)) {
 288                                 tooltip.Top = pt.Y;
 289                         } else {
 290                                 tooltip.Top = pt.Y - size.Height;
 291                         }
 292
 293
 294                         tooltip.Visible = true;
 295                         control.KeyPress += HideToolTipKeyHandler;
 296                         control.MouseDown += HideToolTipMouseHandler;
 297                         control.LostFocus += HideToolTipHandler;
 298                         e.Handled = true;
 299                 }
 300                 #endregion      // Private Methods
 301
 302                 #region UIA Framework: Events, Delegates and Methods
 303                 private Control uia_control;
 304
 305                 private Control UIAControl {
 306                         get { return uia_control; }
 307                         set { uia_control = value; }
 308                 }
 309
 310                 internal static event ControlEventHandler UIAHelpRequested;
 311                 internal static event ControlEventHandler UIAHelpUnRequested;
 312
 313                 internal Rectangle UIAToolTipRectangle {
 314                         get { return tooltip.Bounds; }
 315                 }
 316
 317                 internal static void OnUIAHelpRequested (HelpProvider provider, ControlEventArgs args)
 318                 {
 319                         if (UIAHelpRequested != null)
 320                                 UIAHelpRequested (provider, args);
 321                 }
 322
 323                 internal static void OnUIAHelpUnRequested (HelpProvider provider, ControlEventArgs args)
 324                 {
 325                         if (UIAHelpUnRequested != null)
 326                                 UIAHelpUnRequested (provider, args);
 327                 }
 328                 #endregion
 329         }
 330 }