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