Differences

This shows you the differences between two versions of the page.

--- manual:chapter6:flags:cmd_asnkey [2023/05/20 08:23]
claudio
+++ manual:chapter6:flags:cmd_asnkey [2023/05/20 09:20] (current)
claudio
@@ Line 42: / Line 42: @@
       - **{ Command }**: A list with a single command will execute the command following the same rules as the soft menu keys for commands. While the user is in the stack, the command will be executed. When the user is in the editor the command will do different things depending on the cursor mode. In direct mode (**D**) it will close the editor and execute the command, in algebraic input mode **A** it will insert the command name in the editor, and finally in programming mode (**P**) it will insert the command with spaces as if writing an RPL program.
   * **Level 2 - Key name**: This is a string that defines the key press that will trigger the action. The string has to follow a very specific format in order to be a valid key press, is composed of one or more sections separated by a period as in ''"KEY.SHIFT.MODIFIER"''. The first section is mandatory, the next two are optional but cannot be empty, so a modifier cannot be added without specifying a shift first. The first part is the ken name, and can be **"A thru Z, 0 thru 9, * - + . or UP/DN/LF/RT, BK for backspace, EN for enter**. The modifier indicates the shift mode of the key press and can be **L,LH, R,RH, A,AH, OH (for example L=left shift, LH=left shift hold, A=Alpha, OH=On-hold, etc.)**. Finally, the modifier refers to a specific key event, and it can be one of **P,R,L (P=key down, R=key released, L=long press)**. When not specifying the modifier, the standard key press event will activate the action. Whenever a key doesn't have a long press definition, the action is executed when the key is pressed. However, if the key does have a long press definition, then the action will be delayed until the user releases the key in order to decide whether the normal key or the long press action is triggered.
-  * **Level 1 - Context**: This is an integer that defines the context in which the key will be active. The lowest 5 bits are a sub-context number (0-31), the upper bits are the context number. The context changes when the user is interacting with the user interface. So far there's 2 different contexts defined in newRPL: Context 0 is the normal user interface, and Context 32 (#20h) is active when the UI is in Forms mode (not yet implemented as of this writing). The sub-context bits define which part of the interface the user in currently interacting, and can be one of the following:
+  * **Level 1 - Context**: This is an integer that defines the context in which the key will be active. The lowest 5 bits are a sub-context number (0-31), the upper bits are the context number, so the context integer to use with ''ASNKEY'' needs to be calculated as **Context*32+Subcontext**. The context changes when the user is interacting with the user interface. So far there's 2 different contexts defined in newRPL: Context 0 is the normal user interface, and Context 1 (which means a context number of 32 or #20h) is active when the UI is in Forms mode (not yet implemented as of this writing). The sub-context bits define which part of the interface the user in currently interacting, and can be one of the following:
       - **0** = Match any sub-context
       - **1** = The user is using the editor
@@ Line 49: / Line 49: @@
       - **8** = The user is using the interactive function plot (not yet implemented)
       - **16** = The using is using the interactive picture mode (not yet implemented)
+The subcontexts are bits, and get set whenever a context gets activated. For example, a custom user interface (let's say for example the UI of an equation solver) would have main context of an arbitrary number (chosen by the application designer, let's use 23 for this example) and a subcontext of zero initially at their main screen (whatever that screen is). Any custom keys defined to be active during the application main screen only would need to use a context number for ''ASNKEY'' of **23*32+0**.  If the user wants to type the equation to solve, the UI would activate the editor and the context would become 1 (only the editor is open, within a custom UI). Now if the UI has the 'Calc' soft menu key to enable the use of the stack within the application, then the subcontext would become 2. If the user wants to enter something in this stack, the subcontext would become 3 (2+1 = using the editor while using the stack while inside the application). If the user entered the interactive stack from this stack, the subcontext would become 6 (4+2 = using the interactive stack while using the stack while inside the application). When there's no application running, the system has a main context of zero, and the subcontext is typically 2, since the stack is almost always open. Entering the editor switches to subcontext 3 (in the editor while in the main stack). In this example, to create a user definition that only activates whenever the user is using that specific application (context 23) and only when the user uses the editor within the 'Calc' stack, it would use a context number for ''ASNKEY'' of **23*32+3**. When the user is not running any application (just the system stack), then the context number to use would be **0*32+3** for a custom key active only within the editor (3 because the editor is always open within the stack). Using a subcontext of zero means the key is active on all subcontexts. Similarly, using the main context number of zero makes the key active on all contexts. Notice that since the system is assigned the main Context of zero, any key active in the main system context is also active on **all other application contexts** as well. This is by design, so that system-wide key customizations become active for all applications.
 Whenever a key is assigned with ''ASNKEY'', it is added first to the list of handlers for that key. If there was a previous definition for that key, it will still be present in the list, so a key can have multiple custom defined actions for different or even the same key, shift and modifiers. Whenever the key is pressed, the system will search for a matching key/shift/modifier group and execute the action. The list is traversed in order, so the last assignment done with ''ASNKEY'' will be checked first, therefore can override any previous assignments. Removing a key definition with ''DELKEY'' will only remove the last definition that was added, and any previously stored definition will be active. Once the system finds a match, it will execute its action and stop the search unless [[manual:appendix:flags#flag-45]] is set. The program can set this flag on purpose to make the system continue the search for other custom key handlers (for example, a program might decide to "pass" on handling the key press, letting other handlers process it). In a similar way, a handler might set [[manual:appendix:flags#flag-46]] to cause the default action to be executed. Using both flags lets the system know it needs to search for another custom definition, and if there isn't one, the default action will be taken.
@@ Line 56: / Line 57: @@
 <callout type="danger" icon="true" title="Compatibility">
 ----
-''→∡°'' is specific to **newRPL** and has no direct equivalent in **userRPL**.
+''ASNKEY'' is specific to **newRPL** and has no direct equivalent in **userRPL**. It replaces functionality present in **userRPL** and in third party libraries that allowed redefining the keyboard but it is not compatible with any of them.
 </callout>
 <callout type="info" icon="true" title="Usage">
 ----
-**__Input__**
+**__Example 1: Spell out the number 2.__**
 <code>
 :
-:
+:                             { "two" }
-:
+:                                   "2"
-:                                    45
+:                                     0
 …………………………………………………………………………………………………………
-→∡°
+ASNKEY
 </code>
+**__Effect__**: Pressing number 2 will type the word ''two'' instead. Remove by using ''"2"'' ''DELKEY''. Notice that when in **Alpha** mode, you can still type the number 2, as the override was only for the key 2 without any shift mode.
 \\
-**__Output__**
+\\
+\\
+**__Example 2: Spell out the number 2, but only within the text editor.__**
 <code>
 :
-:
+:                             { "two" }
-:
+:                                   "2"
-:                                  ∡45°
+:                                     3
 …………………………………………………………………………………………………………
+ASNKEY
 </code>
+**__Effect__**: Pressing number 2 while in the stack should do the default action, which is to open the editor and type the number 2. However, any subsequent key presses while the editor is open will type the word ''two'' instead. Remove by using ''"2"'' ''DELKEY''.
 </callout>