KEY Phrase

KEY {IS} key-letter
    {= }

1. The KEY phrase assigns a key letter to the control. The user can activate the control by typing its key letter in combination with some other special key. Under Microsoft Windows, key letters are typed in conjunction with the Alt key. The first character in key-letter becomes the control's key letter. The key letter can be given in lower- or upper-case.
2. If the KEY phrase is omitted, the control's key letter is derived from its title. (See the TITLE phrase for details.) If a key letter is not indicated in the title, the control does not have a key letter. If a key letter is designated in both the title and the KEY phrase, the KEY phrase takes precedence. If the letter specified in the KEY phrase is not the same as the letter indicated in the title, the letter indicated in the title is highlighted and the letter specified in the KEY phrase is the key letter (this could be confusing to the user).
3. The activation technique for key letters is shared with the menu bar handler on most systems. You should avoid assigning duplicate key letters in any one floating window, or assigning key letters that conflict with key letters used by the window's menu bar.
4. Controls that cannot be activated, such as a label, may have key letters (see the example that follows). In this case, the runtime system uses the following rules to determine which control to activate when the key letter is typed:
   1. if another control has the same key letter, then the first control created with that key letter is activated when that key letter is pressed; otherwise,
   2. the next control that can be activated (in the same floating window) is activated. The runtime uses the order in which the controls were created to determine which control is next.

   In practice, these rules mean that you can usually assign a key letter in the title of a label and use rule b) to associate that key letter with a corresponding entry field. In this case, you do not need to use the KEY phrase. If rule (b) does not give you the effect you desire, you can use the KEY phrase and rule (a) to explicitly state the effect you want.

   For example, the following Screen Section segment:

      03 LABEL "&Customer: ".
      03 ENTRY-FIELD USING CUST-NO, COLUMN + 2."

   would assign a key letter of "C" to the label (using the implied key letter assignment from the label's title). Since labels cannot be activated, typing Alt-C would activate the CUST-NO entry field because it is the next control that can be activated.

   Note: If you use "&" in the control title, the letter that directly follows it becomes the accelerator key for this control, indicated by an underline. If you use the KEY IS construct to specify the accelerator key, that letter is not underlined in the control's title.
5. A control's key letter is assigned when the control is created. It cannot be changed.