Project JEDI Knowledgebase Article (original) (raw)

Often, when a user starts using your new program, he needs assistance to step him through "how-to" do different operations. As experience grows, less structured help is required. Quick and appropriate information can be helpful. So - where can this information be stored, and how is it displayed?

As a Delphi programmer, you are in luck. Most visual controls, being descendants of TControl, have a Hint property, that can be set to display a little "balloon" of brief help to inform or remind your user about the control.

To implement a control's Hint property, select the control, press F11 for the Object Inspector, select the Hint property and type in the text. Repeat this step until all desired controls have hints assigned.

One last thing is required. Select the form, go to ShowHint property in the Object Inspector and set it to True. Now fire up the application, position the mouse over each control to see the hint assigned to it.

Notice that hints display for only a short time. You can change the length of time hints display in your application, by setting a new value for the global HintHidePause property:

Application.HintHidePause := 10000;

The example above shows all hints for approximately ten seconds, much longer than the half second default timeout.

Another Hint about Hints

Besides showing hints over controls, you can show them in another location, such as a StatusBar. Simply enter the hint as before but add a pipe symbol:

Button1.Hint := 'This is shown over the button|This is redirected to a status-bar';

NOTE: The text on the left of the pipe symbol is referred to as ShortHint and to the right of the pipe symbol is called LongHint.

Steps to display LongHint

(nothing changes for ShortHint)

  1. Add a StatusBar to the main form.
  2. Manually add the following code to the private section of the form's interface:
    procedure AppOnHint(Sender: TObject);
  3. Double click the form, and place this code in the OnCreate event:
    StatusBar1.SimplePanel := True;
    // but set this False if you want to use panels.
    Application.OnHint := AppOnHint; // specifies an event to trigger
    when OnHint is fired.
  4. Add the following procedure to your code:
    procedure
    TfrmMain.AppOnHint;
    begin
    Statusbar1.SimpleText := Application.Hint;
    end;
    This code takes the LongHint and places it into the StatusBar. Most of the time this works fine, but it has limitations which we will examine shortly.
  5. As the mouse cursor moves over any controls which have long hints assigned to them, you should see hints. (Note: short hints will not display unless you set the form's property ShowHint to True.)

Hints on Child Forms

Now that you understand how to show hints for the main form of a project, lets move onto showing hints on child forms. I feel it is rude to make users look for long hints in the main forms status-bar while on a child form. To rectify this, a few code additions are needed to the original code for the main form and we need to add status bars to each child form.

First, change the code for the procedure AppOnHintto read:

TStatusBar(Screen.ActiveForm.FindComponent('Statusbar1')).SimpleText:= Application.Hint;

When the application's OnHint event fires, it triggers AppOnHint. The code within AppOnHint locates StatusBar1 using FindComponent, then typecasts it as TStatusBar. Next the current control's long hint is assigned to StatusBar1's SimpleText property, on the current form.

Next, add a StatusBar to each form, setting SimplePanel to True. Run the application and you will see hints displayed on the status-bar of any form that is current.

Caveat

This code works 99% of the time. An error will occur if you forget to include a statusbar on a form or you are using a third-party message box which is actually a descendant of TCustomForm. Probably a GPF will occur and you will blame that third party control.

In fact, it is the code for showing hints that is the culprit here, but you can prevent the access violation very simply by testing for the presence of the statusbar. Change the code to:

procedure TfrmMain.AppOnHint; var T: TComponent;

begin T := Screen.ActiveForm.FindComponent('Statusbar1'); if T <> nil then TStatusBar(T).SimpleText := Application.Hint; end; end

Now, when the active form has no component named StatusBar1, no GPF!

A Couple of Tips

Tip 1: Menu items can display hints as described above, i.e. in a StatusBar

Tip 2: Short hints can be displayed in multi-line format. For example

Button1.Hint := 'Pretty cool'#13'You can have multi-line hints|Of course not long hints';

The above example would show a short hint with two (2) lines of text in a Hint balloon, while the long hint remains a one-liner.

Well, that should be enough to get you started - have fun!

Demo projects to download

Using Hints Main Demo

DBGrid Hints Demo

Kevin S. Gallagher is a full time systems analyst at Oregon Department Of Revenue where he uses Delphi, Visual Basic and Clipper to create Property Tax Systems.