mcs/class/Managed.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 #if NET_2_0
  94                 private object tag;
  95 #endif
  96                 #endregion      // Local Variables
  97
  98                 #region Public Constructors
  99                 public HelpProvider() {
 100                         controls = new Hashtable();
 101                         tooltip = new ToolTip.ToolTipWindow();
 102
 103                         HideToolTipHandler = new EventHandler(HideToolTip);
 104                         HideToolTipKeyHandler = new KeyPressEventHandler(HideToolTipKey);
 105                         HideToolTipMouseHandler = new MouseEventHandler(HideToolTipMouse);
 106                         HelpRequestHandler = new HelpEventHandler(HelpRequested);
 107                 }
 108                 #endregion      // Public Constructors
 109
 110                 #region Public Instance Properties
 111                 [DefaultValue(null)]
 112                 [Editor ("System.Windows.Forms.Design.HelpNamespaceEditor, " + Consts.AssemblySystem_Design, "System.Drawing.Design.UITypeEditor, " + Consts.AssemblySystem_Drawing)]
 113                 [Localizable(true)]
 114                 public virtual string HelpNamespace {
 115                         get {
 116                                 return helpnamespace;
 117                         }
 118
 119                         set {
 120                                 helpnamespace = value;
 121                         }
 122                 }
 123
 124 #if NET_2_0
 125                 [Localizable (false)]
 126                 [Bindable (true)]
 127                 [TypeConverter (typeof (StringConverter))]
 128                 [DefaultValue (null)]
 129                 [MWFCategory ("Data")]
 130                 public object Tag
 131                 {
 132                         get { return this.tag; }
 133                         set { this.tag = value; }
 134                 }
 135 #endif
 136                 #endregion      // Public Instance Properties
 137
 138                 #region Public Instance Methods
 139                 public virtual bool CanExtend(object extendee) {
 140                         if (!(extendee is Control)) {
 141                                 return false;
 142                         }
 143
 144                         if ((extendee is Form) || (extendee is ToolBar)) {
 145                                 return false;
 146                         }
 147
 148                         return true;
 149                 }
 150
 151                 [DefaultValue(null)]
 152                 [Localizable(true)]
 153                 public virtual string GetHelpKeyword(Control ctl) {
 154                         return GetHelpProperty(ctl).Keyword;
 155                 }
 156
 157                 [DefaultValue(HelpNavigator.AssociateIndex)]
 158                 [Localizable(true)]
 159                 public virtual HelpNavigator GetHelpNavigator(Control ctl) {
 160                         return GetHelpProperty(ctl).Navigator;
 161                 }
 162
 163                 [DefaultValue(null)]
 164                 [Localizable(true)]
 165                 public virtual string GetHelpString(Control ctl) {
 166                         return GetHelpProperty(ctl).Text;
 167                 }
 168
 169                 [Localizable(true)]
 170                 public virtual bool GetShowHelp(Control ctl) {
 171                         return GetHelpProperty(ctl).Show;
 172                 }
 173
 174                 public virtual void ResetShowHelp(Control ctl) {
 175                         HelpProperty    hp;
 176
 177                         hp = GetHelpProperty(ctl);
 178
 179                         if ((hp.Keyword != null) || (hp.Text != null)) {
 180                                 hp.Show = true;
 181                         } else {
 182                                 hp.Show = false;
 183                         }
 184                 }
 185
 186                 public virtual void SetHelpKeyword(Control ctl, string keyword) {
 187                         GetHelpProperty(ctl).Keyword = keyword;
 188                 }
 189
 190                 public virtual void SetHelpNavigator(Control ctl, HelpNavigator navigator) {
 191                         GetHelpProperty(ctl).Navigator = navigator;
 192                 }
 193
 194                 public virtual void SetHelpString(Control ctl, string helpString) {
 195                         GetHelpProperty(ctl).Text = helpString;
 196                 }
 197
 198                 public virtual void SetShowHelp(Control ctl, bool value) {
 199                         GetHelpProperty(ctl).Show = value;
 200                 }
 201
 202                 public override string ToString() {
 203                         return base.ToString() + ", HelpNameSpace: " + helpnamespace;
 204                 }
 205
 206                 #endregion      // Public Instance Methods
 207
 208                 #region Private Methods
 209                 private HelpProperty GetHelpProperty(Control control) {
 210                         HelpProperty hp;
 211
 212                         hp = (HelpProperty)controls[control];
 213                         if (hp == null) {
 214                                 hp = new HelpProperty(this, control);
 215                                 controls[control] = hp;
 216                         }
 217
 218                         return hp;
 219                 }
 220
 221                 private void HideToolTip(object Sender, EventArgs e) {
 222                         Control control;
 223
 224                         control = (Control)Sender;
 225                         control.LostFocus -= HideToolTipHandler;
 226
 227                         this.tooltip.Visible = false;
 228                 }
 229
 230                 private void HideToolTipKey(object Sender, KeyPressEventArgs e) {
 231                         Control control;
 232
 233                         control = (Control)Sender;
 234                         control.KeyPress -= HideToolTipKeyHandler;
 235
 236                         this.tooltip.Visible = false;
 237                 }
 238
 239                 private void HideToolTipMouse(object Sender, MouseEventArgs e) {
 240                         Control control;
 241
 242                         control = (Control)Sender;
 243                         control.MouseDown -= HideToolTipMouseHandler;
 244
 245                         this.tooltip.Visible = false;
 246                 }
 247
 248
 249                 // This is called when the user does a "what's this" style lookup. It uses the 'text' property
 250                 private void HelpRequested(object sender, HelpEventArgs e) {
 251                         Size    size;
 252                         Point   pt;
 253                         Control control;
 254
 255                         control = (Control)sender;
 256
 257                         if (GetHelpProperty(control).Text == null) {
 258                                 return;
 259                         }
 260
 261                         pt = e.MousePos;
 262
 263                         // Display Tip
 264                         tooltip.Text = GetHelpProperty(control).Text;
 265                         size = ThemeEngine.Current.ToolTipSize(tooltip, tooltip.Text);
 266                         tooltip.Width = size.Width;
 267                         tooltip.Height = size.Height;
 268                         pt.X -= size.Width / 2;
 269
 270                         if (pt.X < 0) {
 271                                 pt.X += size.Width / 2;
 272                         }
 273
 274                         if ((pt.X + size.Width) < SystemInformation.WorkingArea.Width) {
 275                                 tooltip.Left = pt.X;
 276                         } else {
 277                                 tooltip.Left = pt.X - size.Width;
 278                         }
 279
 280                         if ((pt.Y + size.Height) < (SystemInformation.WorkingArea.Height - 16)) {
 281                                 tooltip.Top = pt.Y;
 282                         } else {
 283                                 tooltip.Top = pt.Y - size.Height;
 284                         }
 285
 286
 287                         tooltip.Visible = true;
 288                         control.KeyPress += HideToolTipKeyHandler;
 289                         control.MouseDown += HideToolTipMouseHandler;
 290                         control.LostFocus += HideToolTipHandler;
 291                         e.Handled = true;
 292                 }
 293                 #endregion      // Private Methods
 294         }
 295 }