.TUTORIAL - Using the [ DIALOG ] and [ HINT ] keywords

It's time to flesh out the editor a bit.  Let's add the standard
Search & Replace dialogs.

The Dialog Editor is a screen painter.  You can open a file by
pressing F3 and adding the ".DLG" file extension.  Or use the menu
command, "RUN|Dialog Editor" or (Alt-D).

This lets you interactively compose dialogs to be used with the
application.  The [ DIALOG ] keyword signals SHAZAM to generate
dialogs (*.DLG) as code (*.SRC) or resources (*.REZ).

You can determine code or resources by using the SETUP|Code dialog,
command-line switches, the [ SWITCH ] keyword or the [ DIALOG ] local
override switch.

The dialogs used in this example and the library (..\DLG) were
created with the Dialog Editor, and have hcXX symbols assigned.
These symbols provide a "link" to Hint Text and Help Text.

*** IMPORTANT ***
[X] When resources are used, the VALUE of an hcXX symbol is written
    to the resource file (*.REZ).

[X] When code is generated, the TEXT for the hcXX symbol is written
    to the source-code file (*.SRC).

When hand-coding, you MUST be aware of this!  A program and its
resources can get "out of sync", such as after you edit & compile
help text.  It can happen to cmXX values too, if you change them.

During the generate process, SHAZAM ensures updated values.  If you
use the Dialog Editor to write a dialog to a resource file, load the
Help Symbol file and use "EDIT|Help context|Update all".

*****************

In a definition, MenuBar and MenuBox elements have hint text on the
same line as the SubMenu or Item, using the double semi-colon.  To
create hints for other views, use the [ HINT ] keyword to name the
hcXX symbol and add text after a double semi-colon.

Note that the hints use a naming convention, the result of which
causes the hcXX symbols to be sorted and assigned a value in sort
order.  This allows for how TCLUSTER assigns "HelpCtx" values; ie:
The initial value is incremented by one for each additional element
after the first (the only element using the directly assigned
value).  See CLUSTER.DEF for a dedicated example of hints & TClusters.

Corresponding Help text is covered in the next example.

@PA - - - - - - - - - - - - - - - - - - - - - - - - - - - -



[ UNIT ]
General /r                                       @@ Use & register

[ DIALOG ]
replace find                                    @@ *.DLG files

[ SUBMENU ] File             ;;file management
%%open f3                    ;;open a file            @@ *.EVT file
save   f2                    ;;save current window    @@ EDITORS.PAS internal

[ SUBMENU ] search           ;;text search-and-replace commands
find...         ^QF          ;;search for text
replace...      ^QA          ;;search for text and replace it with new text
'search again'   Ctrl-L      ;;repeat the last Find or Replace command


[ HINT ]                     @@ "hc" prefix optional.  SHAZAM adds if needed.
OK                           ;;accept the settings in this dialog box
Cancel                       ;;close the dialog box without making any changes
SearchText                   ;;Text to look for
ReplaceText                  ;;Text to use for replace
SearchType1                  ;;whether to consider case during search
SearchType2                  ;;whether to consider partial matches
SearchType3                  ;;whether to prompt before replacing
SearchType4                  ;;whether to scan entire file
