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 #if NET_2_0
 104                         //UIA Framework: Event used to indicate that ToolTip is shown
 105                         tooltip.VisibleChanged += delegate (object sender, EventArgs args) {
 106                                 if (tooltip.Visible == true)
 107                                         OnUIAHelpRequested (this, new ControlEventArgs (UIAControl));
 108                                 else
 109                                         OnUIAHelpUnRequested (this, new ControlEventArgs (UIAControl));
 110                         };
 111 #endif
 112
 113                         HideToolTipHandler = new EventHandler(HideToolTip);
 114                         HideToolTipKeyHandler = new KeyPressEventHandler(HideToolTipKey);
 115                         HideToolTipMouseHandler = new MouseEventHandler(HideToolTipMouse);
 116                         HelpRequestHandler = new HelpEventHandler(HelpRequested);
 117                 }
 118                 #endregion      // Public Constructors
 119
 120                 #region Public Instance Properties
 121                 [DefaultValue(null)]
 122                 [Editor ("System.Windows.Forms.Design.HelpNamespaceEditor, " + Consts.AssemblySystem_Design, "System.Drawing.Design.UITypeEditor, " + Consts.AssemblySystem_Drawing)]
 123                 [Localizable(true)]
 124                 public virtual string HelpNamespace {
 125                         get {
 126                                 return helpnamespace;
 127                         }
 128
 129                         set {
 130                                 helpnamespace = value;
 131                         }
 132                 }
 133
 134 #if NET_2_0
 135                 [Localizable (false)]
 136                 [Bindable (true)]
 137                 [TypeConverter (typeof (StringConverter))]
 138                 [DefaultValue (null)]
 139                 [MWFCategory ("Data")]
 140                 public object Tag
 141                 {
 142                         get { return this.tag; }
 143                         set { this.tag = value; }
 144                 }
 145 #endif
 146                 #endregion      // Public Instance Properties
 147
 148                 #region Public Instance Methods
 149                 public virtual bool CanExtend(object target) {
 150                         if (!(target is Control)) {
 151                                 return false;
 152                         }
 153
 154                         if ((target is Form) || (target is ToolBar)) {
 155                                 return false;
 156                         }
 157
 158                         return true;
 159                 }
 160
 161                 [DefaultValue(null)]
 162                 [Localizable(true)]
 163                 public virtual string GetHelpKeyword(Control ctl) {
 164                         return GetHelpProperty(ctl).Keyword;
 165                 }
 166
 167                 [DefaultValue(HelpNavigator.AssociateIndex)]
 168                 [Localizable(true)]
 169                 public virtual HelpNavigator GetHelpNavigator(Control ctl) {
 170                         return GetHelpProperty(ctl).Navigator;
 171                 }
 172
 173                 [DefaultValue(null)]
 174                 [Localizable(true)]
 175                 public virtual string GetHelpString(Control ctl) {
 176                         return GetHelpProperty(ctl).Text;
 177                 }
 178
 179                 [Localizable(true)]
 180                 public virtual bool GetShowHelp(Control ctl) {
 181                         return GetHelpProperty(ctl).Show;
 182                 }
 183
 184                 public virtual void ResetShowHelp(Control ctl) {
 185                         HelpProperty    hp;
 186
 187                         hp = GetHelpProperty(ctl);
 188
 189                         if ((hp.Keyword != null) || (hp.Text != null)) {
 190                                 hp.Show = true;
 191                         } else {
 192                                 hp.Show = false;
 193                         }
 194                 }
 195
 196                 public virtual void SetHelpKeyword(Control ctl, string keyword) {
 197                         GetHelpProperty(ctl).Keyword = keyword;
 198                 }
 199
 200                 public virtual void SetHelpNavigator(Control ctl, HelpNavigator navigator) {
 201                         GetHelpProperty(ctl).Navigator = navigator;
 202                 }
 203
 204                 public virtual void SetHelpString(Control ctl, string helpString) {
 205                         GetHelpProperty(ctl).Text = helpString;
 206                 }
 207
 208                 public virtual void SetShowHelp(Control ctl, bool value) {
 209                         GetHelpProperty(ctl).Show = value;
 210                 }
 211
 212                 public override string ToString() {
 213                         return base.ToString() + ", HelpNameSpace: " + helpnamespace;
 214                 }
 215
 216                 #endregion      // Public Instance Methods
 217
 218                 #region Private Methods
 219                 private HelpProperty GetHelpProperty(Control control) {
 220                         HelpProperty hp;
 221
 222                         hp = (HelpProperty)controls[control];
 223                         if (hp == null) {
 224                                 hp = new HelpProperty(this, control);
 225                                 controls[control] = hp;
 226                         }
 227
 228                         return hp;
 229                 }
 230
 231                 private void HideToolTip(object Sender, EventArgs e) {
 232                         Control control;
 233
 234                         control = (Control)Sender;
 235                         control.LostFocus -= HideToolTipHandler;
 236
 237                         this.tooltip.Visible = false;
 238                 }
 239
 240                 private void HideToolTipKey(object Sender, KeyPressEventArgs e) {
 241                         Control control;
 242
 243                         control = (Control)Sender;
 244                         control.KeyPress -= HideToolTipKeyHandler;
 245
 246                         this.tooltip.Visible = false;
 247                 }
 248
 249                 private void HideToolTipMouse(object Sender, MouseEventArgs e) {
 250                         Control control;
 251
 252                         control = (Control)Sender;
 253                         control.MouseDown -= HideToolTipMouseHandler;
 254
 255                         this.tooltip.Visible = false;
 256                 }
 257
 258
 259                 // This is called when the user does a "what's this" style lookup. It uses the 'text' property
 260                 private void HelpRequested(object sender, HelpEventArgs e) {
 261                         Size    size;
 262                         Point   pt;
 263                         Control control;
 264
 265                         control = (Control)sender;
 266
 267 #if NET_2_0
 268                         //UIA Framework: Associates requested control with internal variable to generate event
 269                         UIAControl = control;
 270 #endif
 271
 272                         if (GetHelpProperty(control).Text == null) {
 273                                 return;
 274                         }
 275
 276                         pt = e.MousePos;
 277
 278                         // Display Tip
 279                         tooltip.Text = GetHelpProperty(control).Text;
 280                         size = ThemeEngine.Current.ToolTipSize(tooltip, tooltip.Text);
 281                         tooltip.Width = size.Width;
 282                         tooltip.Height = size.Height;
 283                         pt.X -= size.Width / 2;
 284
 285                         if (pt.X < 0) {
 286                                 pt.X += size.Width / 2;
 287                         }
 288
 289                         if ((pt.X + size.Width) < SystemInformation.WorkingArea.Width) {
 290                                 tooltip.Left = pt.X;
 291                         } else {
 292                                 tooltip.Left = pt.X - size.Width;
 293                         }
 294
 295                         if ((pt.Y + size.Height) < (SystemInformation.WorkingArea.Height - 16)) {
 296                                 tooltip.Top = pt.Y;
 297                         } else {
 298                                 tooltip.Top = pt.Y - size.Height;
 299                         }
 300
 301
 302                         tooltip.Visible = true;
 303                         control.KeyPress += HideToolTipKeyHandler;
 304                         control.MouseDown += HideToolTipMouseHandler;
 305                         control.LostFocus += HideToolTipHandler;
 306                         e.Handled = true;
 307                 }
 308                 #endregion      // Private Methods
 309
 310                 #region UIA Framework: Events, Delegates and Methods
 311 #if NET_2_0
 312                 private Control uia_control;
 313
 314                 private Control UIAControl {
 315                         get { return uia_control; }
 316                         set { uia_control = value; }
 317                 }
 318
 319                 internal static event ControlEventHandler UIAHelpRequested;
 320                 internal static event ControlEventHandler UIAHelpUnRequested;
 321
 322                 internal Rectangle UIAToolTipRectangle {
 323                         get { return tooltip.Bounds; }
 324                 }
 325
 326                 internal static void OnUIAHelpRequested (HelpProvider provider, ControlEventArgs args)
 327                 {
 328                         if (UIAHelpRequested != null)
 329                                 UIAHelpRequested (provider, args);
 330                 }
 331
 332                 internal static void OnUIAHelpUnRequested (HelpProvider provider, ControlEventArgs args)
 333                 {
 334                         if (UIAHelpUnRequested != null)
 335                                 UIAHelpUnRequested (provider, args);
 336                 }
 337
 338 #endif
 339                 #endregion
 340         }
 341 }