InfoConnect 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. 

    If you prefer to run macros in pre-configured sessions instead of creating your own sessions, you can download the VBA Sample Sessions and open the following sessions:
    change-keyboard-mapping.rd3x (IBM)
    change-keyboard-mapping-for-specific-screens.rd3x (IBM)
    change-keyboard-mapping.rdox (Open Systems)
    change-keyboard-mapping-when-certain-strings-are-received.rdox (Open Systems)

    The download package contains everything you need to run the macros in these files. See Download the VBA Sample Sessions.

     

    This walkthrough shows several ways to change keyboard maps.

    This article contains tabbed content that is specific to each terminal type. Be sure the tab for your Which Terminal Type are you Using? is selected.

    Change a Key Mapping

    This example maps the Ctrl+B key to a simple macro that gets text from the screen and displays it in a message box.

    To run this sample

    1. In a terminal session, open the Visual Basic Editor and under the session project folder, create a new module and name it ChangeKeyBoardMap.
      This module name is case sensitive.
    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, 1, 60)
          MsgBox 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)
          MsgBox  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 displayed in a message box.

    Change a Key Mapping for a Session

    Instead of manually running a macro to map a key, 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. In an IBM session, open the Settings window and click Manage Keyboard Maps. Then select Modify the currently selected keyboard map file and remove the Ctrl+B key combination if it is not mapped.
    2. Set up the MapKeyToMacro subroutine as shown in Change a Key Mapping but do not run the macro.
    3. 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
      

       

    4. In the session window, press Ctrl+B to verify that this key combination is not mapped.
    5. Disconnect the session and then reconnect.
    6. In the session window, press Ctrl+B.
      The data gathered by the CopyData macro is displayed in a message box.

    Change a Key Mapping for Specific Screens or Strings

    You can use events to programmatically map a key when specific screens open (IBM) or when certain strings are received (Open Systems). This sample runs the MapKeyToMacro subroutine shown in  Change a Key Mapping to assign an action to a key when a specific screen opens (for IBM sessions) or when a specific string is received (for Open Systems sessions).

    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 second screen, enter Kayak.
    3. On the INTERNATIONAL KAYAK ENTERPRISES screen, press Ctrl+B. 

    The data gathered by the CopyData macro is displayed in a message box.

    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 session window, press Ctrl+B. 
      The data gathered by the CopyData macro is displayed in a message box.

    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 InfoConnect 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