Additional description of TN3270 (#3047)

* Extended description of TN3270 Signed-off-by: Martin Zeithaml <[email protected]> * Update mvd-3270.md Signed-off-by: Martin Zeithaml <[email protected]> * Requested changes done Signed-off-by: Martin Zeithaml <[email protected]> --------- Signed-off-by: Martin Zeithaml <[email protected]> Signed-off-by: Martin Zeithaml <[email protected]> Co-authored-by: Andrew Jandacek <[email protected]>
zowe · Jan 18, 2024 · a2a25fe · a2a25fe
1 parent 5b3be45
commit a2a25fe
Show file tree

Hide file tree

Showing 2 changed files with 120 additions and 7 deletions.
diff --git a/docs/user-guide/mvd-3270.md b/docs/user-guide/mvd-3270.md
@@ -0,0 +1,120 @@
+# 3270 Terminal
+The 3270 Terminal Display Emulator plug-in provides a user interface that emulates the basic functions of IBM 3270 family terminals. On the back end, the plug-in and the Zowe Application Server connect to any standard TN3270/E server.
+
+This terminal display emulator operates as a three tier program. Due to web browsers being unable to supply TCP networking that terminals require, this terminal display emulator does not connect directly to your TN3270 server. Instead, the Zowe Application Server acts as a bridge, and uses websockets between it and the browser for terminal communication. As a result, terminal connections only work when the stack of network programs supports websockets and the TN3270 server destination is visible to the Zowe Application Server.
+
+The terminal connection can be customized per user and saved for future sessions using the connection toolbar of the application. The preferences are stored within [the configuration dataservice storage](../extend/extend-desktop/mvd-configdataservice), which can also be used to set instance-wide defaults for multiple users.
+
+## Keyboard shortcuts
+The terminal bundle that is used by tn3270-ng2 has several keyboard shortcuts to execute common TN3270 emulator functionality. Below is the current list of what function is mapped to which key combination. 
+
+Be aware that some browsers intercept key combinations that are common to browsers, such as `ctrl`+`R` or `ctrl`+`T`, and that the operating system may also intercept certain combinations such as `Windows`+`R` or `alt`+`F4`. 
+
+Also be aware that the key combinations listed will only be handled by the terminal if the terminal has focus, which you can know by if the terminal's cursor is visible and blinking or not. To gain focus on the terminal, it is sufficient to click on the terminal's contents. The difference between focus and not focus may be the difference between `F5` being interpreted as terminal `PF5`, or the browser reloading the page.
+
+
+Action | Keyboard Shortcut | Note
+-------|-------------------|------
+Back Tab | Shift+Tab |
+Backspace | Backspace |
+Clear | Ctrl+Shift+z |
+Cursor Down | ArrowDown, NumpadArrowDown |
+Cursor Left| ArrowLeft, NumpadArrowLeft |
+Cursor Right| ArrowRight, NumpadArrowRight |
+Cursor Up| ArrowUp, NumpadArrowUp |
+Delete | Delete, NumpadDelete |
+End | End, NumpadEnd |
+Enter | Enter, NumpadEnter |
+Erase End of Field (EOF) | Ctrl+e | Erases from cursor position to end of field
+Erase Field | Ctrl+l | Erases entire field
+Erase Input | | Erases contents of all input fields
+Erase Word | | Erases until next word, including whitespace
+Home | Home, NumpadHome |
+Insert | Insert, NumpadInsert | Toggles insert text mode
+New Line | Shift+Enter, Shift+NumpadEnter | Moves cursor to field on next row
+PA1 | Alt+1 |
+PA2 | Alt+2 |
+PA3 | Alt+3 |
+PF01 | F1 | 
+PF02 | F2 | 
+PF03 | F3 | 
+PF04 | F4 | 
+PF05 | F5 | 
+PF06 | F6 | 
+PF07 | F7 | 
+PF08 | F8 | 
+PF09 | F9 | 
+PF10 | F10 | 
+PF11 | F11 | 
+PF12 | F12 | 
+PF13 | Shift+F1 | 
+PF14 | Shift+F2 | 
+PF15 | Shift+F3 | 
+PF16 | Shift+F4 | 
+PF17 | Shift+F5 | 
+PF18 | Shift+F6 | 
+PF19 | Shift+F7 | 
+PF20 | Shift+F8 | 
+PF21 | Shift+F9 | 
+PF22 | Shift+F10 | 
+PF23 | Shift+F11 | 
+PF24 | Shift+F12 | 
+Reset | Alt+r | Terminal doesn't lock on bad input, just rejects and auto resets. No use for reset button currently.
+Tab | Tab
+
+## Key sequences
+Key sequences allows user to define their own key sequences. Each key sequence is a recorded set of keys with the possibility of using the key modifiers (Ctrl, Alt, Shift), function keys (F1, F2, ...) and the combinations (such as Ctrl+E or Shift+F1). The definition is stored in the `_keySequences.json` file.
+
+### Default key sequences
+* There is a set of predefined key sequences
+* Key sequences are accesible via top right menu:
+
+![image](https://github.com/Martin-Zeithaml/docs-site/assets/66114686/0052f8d2-92d3-4313-9087-65ab53ea41a3)
+
+
+
+### Syntax of the JSON
+* All key sequences can be redefined by the user
+* Following syntax is required:
+  * `keySequences` is an array of individual key sequences
+  * `title` displayed in the key sequences menu
+  * `description` is hover help for each item in the key sequences menu
+  * `keys` is an array of the key strokes
+    * `normal` for the "typewriter" keys
+    * `special` for the function, modifiers and other special keys
+      * The value corresponds to the javascript key code
+    * `prompt` is used for user input and this input is pasted on the current cursor position
+   * `ctrl`, `alt` and `shift` are key modifiers
+  * If you combine `normal`, `special` or `prompt` in one array item, only one action will be made in the order of `normal`, `special` and `prompt`
+
+### Example
+Let's demostrate this on the two simple key sequences: 
+* **Hello, world**
+  * Types `Hello, world` only
+* **ISPF command SWAP NEXT**
+  * Presses `Home` to get on the command line/input field
+  * `Ctrl+E` deletes the input field
+    * `Ctrl+E` is predefined in the TN3270 as "EOF - Erase end of field"
+  * Types `SWAP NEXT`
+  * Hits `Enter`
+
+Then the file `_keySequences.json` is:
+
+```
+{ "keySequences":
+  [
+    { "title": "Hello, world",
+      "description": "Types Hello, world",
+       "keys": [ { "normal":  "Hello, world" } ]
+    },
+    { "title": "SWAP NEXT",
+      "description": "ISPF: Swap next command",
+       "keys": [ { "special": "Home" },
+                 { "normal":  "E", "ctrl": "true" },
+                 { "normal":  "SWAP NEXT" },
+                 { "special": "Enter" } 
+               ]
+    }
+  ]
+}
+```
diff --git a/docs/user-guide/mvd-using.md b/docs/user-guide/mvd-using.md
@@ -123,13 +123,6 @@ Additional plugins can be added to the Desktop, and are packaged and installed a
 
 Developers can create application plug-ins to put into extensions, and developers should [read the extending guide for more information](../extend/extend-desktop/mvd-extendingzlux).
 
-### 3270 Terminal
-The 3270 Terminal Display Emulator plugin provides a user interface that emulates the basic functions of IBM 3270 family terminals. On the "back end," the plugin and the Zowe Application Server connect to any standard TN3270/E server.
-
-This terminal display emulator operates as a "Three-Tier" program. Due to web browsers being unable to supply TCP networking that terminals require, this terminal display emulator does not connect directly to your TN3270 server. Instead, the Zowe Application Server acts as a bridge, and uses websockets between it and the browser for terminal communication. As a result, terminal connections only work when the stack of network programs supports websockets and the TN3270 server destination is visible to the Zowe Application Server.
-
-The terminal connection can be customized per-user and saved for future sessions using the connection toolbar of the application. The preferences are stored within [the configuration dataservice storage](../extend/extend-desktop/mvd-configdataservice), which can also be used to set instance-wide defaults for multiple users.
-
 ### VT Terminal 
 The VT Terminal plugin provides a user interface that emulates the basic functions of DEC VT family terminals. On the "back end," the plugin and the Zowe Application Server connect to VT compatible hosts, such as z/OS UNIX System Services (USS), using SSH or Telnet.