Reflection Desktop VBA Guide
HowTos / Change Keyboard Mapping on-the-fly
In This Topic
    Change Keyboard Mapping on-the-fly
    In This Topic

    You can programmatically map macros or other actions to keys or key combinations. This allows you to modify how a key is mapped without replacing a user's customized keyboard map. 

    This article contains tabbed content that is specific to each terminal type. Be sure the tab for your terminal type is selected.

    Change a Key Mapping

    This example maps the Ctrl+B key to a simple macro that gets text from the screen and prints it to the Immediate window.

    To run this sample

    1. In an IBM session, open the Visual Basic Editor and under the session project folder, create a new module and name it ChangeKeyBoardMap.
    2. Copy this code into the module code window.
      Map a key to a macro
      Copy Code 
      Public Sub MapKeyToMacro()
    Dim kbmapping As KeyboardMapping
    Dim sequence As InputMapActionSequence
    Dim action As InputMapAction
 
    Set kbmapping = New KeyboardMapping
    Set sequence = New InputMapActionSequence
    Set action = New InputMapAction
                         
    'Set up the action to run a recorded macro named CopyData
    action.ActionId = InputMapActionID_RunMacroAction
    action.AddParameter "ChangeKeyBoardMap.CopyData"
 
    'Look for the macro in this Session project
    action.AddParameterAsInteger MacroEnumerationOption.MacroEnumerationOption_Document
 
    'Don't ask for any input at runtime
    action.AddParameterAsBoolean False
 
    'Add the action to the action sequence
    sequence.Add action
    'Assign the Ctrl+B key combination to the new action
     kbmapping.key = Keys_Control + Keys_B
 
    'Map the key assigned  to the keyboard mapping to the sequence
    Set kbmapping.mapping = sequence
 
    'Add the new mapping to the session keyboard map
    ThisIbmTerminal.KeyboardMapper.AddMapping kbmapping
                          
End Sub

Sub CopyData()
    Dim data As String
    data = "The first line contains " & ThisIbmScreen.GetText(1, 2, 20)
    Debug.Print data
End Sub
                                             
      Map a key to a macro
      Copy Code 
      Public Sub MapKeyToMacro()
    Dim kbmapping As KeyboardMapping
    Dim sequence As InputMapActionSequence
    Dim action As InputMapAction
 
    Set action = New InputMapAction
    Set sequence = New InputMapActionSequence
    Set kbmapping = New KeyboardMapping
                       
    'Set up the action to run a recorded macro named CopyData
    action.ActionId = InputMapActionID_RunMacroAction
    action.AddParameter "ChangeKeyBoardMap.CopyData"
 
    'Look for the macro in this Session project
    action.AddParameterAsInteger MacroEnumerationOption.MacroEnumerationOption_Document
 
    'Don't ask for any input at runtime
    action.AddParameterAsBoolean False
 
    'Add the action to the action sequence
    sequence.Add action
    'Assign the key to assign the new action to
     kbmapping.key = Keys_Control + Keys_B
 
    'Map the key assigned  to the keyboard mapping to the sequence
    Set kbmapping.Mapping = sequence
 
    'Add the new mapping to the session keyboard map
    ThisTerminal.KeyboardMapper.AddMapping kbmapping
  
End Sub
Sub CopyData()
    Dim Data As String
    Data = "The upper left region of the screen contains " & ThisScreen.GetText2(1, 1, 30, 30)
    Debug.Print Data
End Sub
    3. Press F5 to run the macro.
    4. In the session window, press Ctrl+B.
      The data gathered by the CopyData macro is printed to the Immediate window.

    Change a Key Mapping for a Session

    You can use events to programmatically map a key when a session starts. This sample runs the MapKeyToMacro subroutine (shown in Change a Key Mapping) as the session connects.

    To run this sample

    1. Set up the MapKeyToMacro subroutine as shown in Change a Key Mapping.
    2. Copy this sample into the ThisIbmTerminal (for IBM) or ThisTerminal (for Open Systems) code window.
      Map a Key for a Session
      Copy Code 
      Private Sub IbmTerminal_BeforeConnect(ByVal sender As Variant)
    ChangeKeyBoardMap.MapKeyToMacro
End Sub
                                     
      Map a Key for a Session
      Copy Code 
      Private Function Terminal_Connecting(ByVal sender As Variant, ByVal ConnectionID As Long, ByVal connnectionType As Attachmate_Reflection_Objects_Emulation_OpenSystems.ConnectionTypeOption, ByVal connectionSettings As Variant) As Boolean
    ChangeKeyBoardMap.MapKeyToMacro
    Terminal_Connecting = True
End Function
    3. Disconnect the session and then reconnect.
    4. In the session window, press Ctrl+B. 
      The data gathered by the CopyData macro is printed to the Immediate window.

    Change a Key Mapping for Specific Screens

    You can use events to programmatically map a key for specific screens. This sample runs the MapKeyToMacro subroutine shown in Change a Key Mapping to assign an action to a key when a specific screen opens.

    To run this sample

    1. Create an IBM 3270 terminal session and enter demo:ibm3270.sim in the Host /IP Address box.
    2. Set up the MapKeyToMacro subroutine as shown in Change a Key Mapping.
    3. Copy this sample into the ThisIbmScreen code window.
    Change a Key Mapping for a Specific Screen
    Copy Code 
    Private Sub IbmScreen_NewScreenReady(ByVal sender As Variant)
   Dim screenID As String
   'Get the text to identify the screen
   screenID = Trim(ThisIbmScreen.GetText(1, 25, 13))
 
   'When the appropriate screen is ready, make the control visible
   If screenID = "INTERNATIONAL" Then
      ChangeKeyBoardMap.MapKeyToMacro
   End If
End Sub
    1. On the log in screen, enter any credentials.
    2. On the next screen, press Ctrl+B to verify that this key combination is not assigned to the macro yet.
    3. On the second screen, enter Kayak.
    4. In the sesssion window, press Ctrl+B. 

    The data gathered by the CopyData macro is printed to the Immediate window.

    To run this sample

    1. Create an Open Systems terminal session and enter demo:unix in the Host /IP Address box.
    2. Set up the MapKeyToMacro subroutine as shown in Change a Key Mapping.
    3. Copy this sample into the ThisScreen code window.
      Change a Key Mapping When a String is Found
      Copy Code 
      Private Sub Screen_ControlKeySent(ByVal sender As Variant, ByVal Key As Attachmate_Reflection_Objects_Emulation_OpenSystems.ControlKeyCode)  
    Dim rCode As ReturnCode
    
    'Wait for the string returned on the screen that has the data, with a timeout of 3000 ms.
    'This string is from the recorded macro code.
    rCode = ThisScreen.WaitForString2("Command> ", 3000)
    
    'Show or hide the control
    If rCode = 1 Then
        ChangeKeyBoardMap.MapKeyToMacro
    End If    
End Sub
    4. On the log in screen, enter any credentials.
    5. On the next screen, press Ctrl+B to verify that this key combination is not assigned to the macro yet.
    6. At the command prompt, enter demodata.
    7. In the sesssion window, press Ctrl+B. 
      The data gathered by the CopyData macro is printed to the Immediate window.

    Concepts

    To map a keyboard combination, you'll need to:

    Set up the Action

    To set up the action, we need to define the action and then add it to an action sequence so we can map it to a key.

    First, you define the action you want to map by creating an InputMapAction object and defining its properties. The InputMapActionID enum defines a number of actions that you can assign to input maps (keyboard or mouse maps). Some of these actions, like the RunMacroAction, require specific parameters. You can get information about which parameters are required and how to set them in the Help description for each enum item. You'll need to set these parameters in the order in which they are listed in the Help.

    In our example, the Help for the RunMacroAction enum indicates we need to add three parameters to the InputMap Action object:

    From the Help for the RunMacroAction enum...
    Runs a macro, if the required parameters are provided. This action requires three parameters with an optional fourth parameter:
    • The macro name of type string (for example, "Module1.TestMacro"). Include the VBA project namespace in the name, if necessary.The
    • VBA project location where the macro is located (type MacroEnumerationOption). Specify MacroEnumerationOption_CommonProject if the macro is located in the Common project, or MacroEnumerationOption_Document if it's located in the current document's VBA project.
    • A boolean value that determines whether the user is prompted for a macro to run at runtime. The first two parameters are ignored if this value is true.
    • Optional macro data (type string) to be passed to the macro at runtime. If no macro data is needed, do not add this to the parameter list.

    In our example, we set these parameters in the order in which they are listed in the enum description, using the three methods for adding parameters on the InputMapAction object: AddParameter, AddParameterAsInteger, and AddParameterAsBoolean.

    After we have defined the action, we need to add it to an action sequence so we can map it to the key we want to use. We do this by creating an InputMapActionSequence object and adding the InputMapAction that we created to this object.    

    Set up a Keyboard Shortcut and Map it to the Action

    To set up a keyboard shortcut, we need to create a new KeyBoardMapping object and add it to the session keyboard map.

    The KeyBoardMapping object has properties that we can use to set the key associated with the keyboard mapping and set the action sequence associated with the keyboard mapping.

    First, we set the Key property to items defined in the Reflection Keys enumeration. Then we set the Mapping property to the sequence we created for the action. Finally, we add the new mapping to the session keyboard map.

    You can use this same approach to map any action to your keyboard.

    See Also

    Concepts

    Using Reflection Events
    Navigating Sessions
    Controlling Macro Execution