Do you want to add keyboard support in a Mashup? In this blog I’ll show how to get a keyboard key to invoke an event and how to user keyboard shortcuts to switch beteen tabs. I’ll talk about focus and how to user accelerator keys to jump to an input field and some other nice to know topics for Mashup and feature development.

Focus and accelerator keys

Pressing tab in a form will move the keyboard focus to the next control. In WPF there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus.

There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope.

You set a focus scope in XAML by using the FocusManager.IsFocusScope=”True”.

<StackPanel Name="focusScope1" 
            FocusManager.IsFocusScope="True"
            Height="200" Width="200">
  <Button Name="button1" Height="50" Width="50"/>
  <Button Name="button2" Height="50" Width="50"/>
</StackPanel>

Let’s look at the M3 Example List and edit customer. When the Mashup is loaded keyboard focus is… nowhere. Pressing tab once puts the focus in the first TextBox and then the default order is as follows:

First I want to change so that the detail area below the list is one focus scope and I want the focus to move from Name to your reference and then Save because that is most common. First I set FocusManager.IsFocusScope=”True” on the MIPanel and then I set KeyboardNavigation.TabNavigation=”Cycle”. Then I set TabIndex=”1″, then 2, 3. I leave the rest blank beucase I don’t need to set all nor do they have to be en absolute order.

When the Mashup starts I want the focus to be in the search field. So I modify the start-up event on the List and set the Activate property.

Keybinding to a button

When it comes to buttons and you only have one save button you can set IsDefault=”true” on the button and it will be click upon enter. But in my example that would not work becuase I have the search button to consider as well. So I use the Activate property on the Startup Event on the list.

<StackPanel Orientation="Horizontal" Margin="8,16,8,8">
  <StackPanel.InputBindings>
    <KeyBinding Key="Enter" Command="mashup:MashupInstance.MashupCommand">
      <KeyBinding.CommandParameter>
        <mashup:Events>
          <mashup:Event Activate="CustomerList" TargetName="CustomerList" TargetEventName="List">
            <mashup:Parameter TargetKey="CUNO" Value="{Binding ElementName=SearchCustomerTextBox, Path=Text}" />
          </mashup:Event>
        </mashup:Events>
      </KeyBinding.CommandParameter>
    </KeyBinding>
  </StackPanel.InputBindings>
  <TextBox Name="SearchCustomerTextBox" Width="200" Margin="0" />
  <Button Content="{mashup:Constant Key=Search,File=Mango.UI}" Width="100" VerticalAlignment="Center" Margin="8,0,5,0">
      <Button.CommandParameter>
        <mashup:Events>
          <mashup:Event SourceEventName="Click" TargetName="CustomerList" TargetEventName="List">
            <mashup:Parameter TargetKey="CUNO" Value="{Binding ElementName=SearchCustomerTextBox, Path=Text}" />
          </mashup:Event>
        </mashup:Events>
      </Button.CommandParameter>
    </Button>
  </StackPanel>

I’ve added an Activate to put the focus in the list as well but that does not get applied. Probably because of the fact that focus will not be set when the list gets reloaded. So how should I move focus to the list? I can keep the focus in the textbox and tab to get the to the list or I need to try and use another event on the list. I tried to use the Running event on the list. When the Mashup is started the Startup event is mapped to the List Event. After the list received the List event it will change and trigger the Running event as it gets the list so the Running event can be used to manually clear other controls that have loaded dependent information from the list. Running is a standard event that will be set on controls as they are busy. Let’s see if it will work to set focus a bit later. Nope that did not work. I did not find a way to put focus to the list once it was loaded. Perhaps if I had a ListCompleted event. Perhaps something that can be enhanced 🙂

I like Ctrl + S to invoke the save command.
Since I want the keyboard shortcut to be available in the entire Mashup I add the key binding to the top Grid. As it requires a modifier and not a single Key I need to set Gesture=”CTRL+S” and not the Key.

There is another potential issue with adding this Save command. All bindings in the Detail area are two-way bindings that will be updated once the Keyboard focus leaves the input button. That means that if I change the Customer name and press Ctrl+S before tabbing to another textbox the value in the data behind the control is not changed yet. So when you introduce a shortcut key to save a form that you can edit you need to change the default behaviour of the UpdateSourceTrigger for the binding in the TextBox. The default value for most dependency properties is PropertyChanged, while the Text property has a default value of LostFocus.

So I have to set the UpdateSourceTrigger to Property changed on all TextBoxes.

<TextBox Name="itemNameTextBox"
         Text="{Binding [CUNM],UpdateSourceTrigger=PropertyChanged}" />

Access Keys (a.k.a. mnemonics).

To improve keyboard support we can add the use of mnemonics. Mnemonics is the ability to navigate to a control using a key stroke combination. Access keys allow you to hit Alt + SomeKey to quickly interact with a control in the UI, such as hitting Alt + O to click an “OK” button. Labels supports access keys. You can associate a Label with another control, such as a TextBox, ComboBox, and allow the user to type an access key defined by the Label to set focus to the other control. You define the access key by writing _ in the text. Pressing down Alt will display all access keys in the UI. I’ll change the Customer name to Customer _name and _Your reference. Then I have to set Target on the label to my TextBox.

<Label Content="Customer _name:" Target="{Binding ElementName=nameTextBox}" Grid.Row="1" Grid.Column="0" HorizontalAlignment="Left" VerticalAlignment="Center" />
<TextBox MaxLength="36" TabIndex="1" Name="nameTextBox" Text="{Binding [CUNM]}" Grid.Row="1" Grid.Column="2" HorizontalAlignment="Stretch" VerticalAlignment="Center" />

The final result

Here is the final result after all modifications.

<Grid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:ui="clr-namespace:Mango.UI.Controls;assembly=Mango.UI" xmlns:mashup="clr-namespace:Mango.UI.Services.Mashup;assembly=Mango.UI" xmlns:m3="clr-namespace:MForms.Mashup;assembly=MForms">
  <Grid.Resources>
  </Grid.Resources>

  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
  </Grid.ColumnDefinitions>
  <Grid.RowDefinitions>
     <RowDefinition Height="Auto" />
    <RowDefinition Height="*" />
    <RowDefinition Height="Auto" />
    <RowDefinition Height="Auto" />
  </Grid.RowDefinitions>
  <Grid.InputBindings>
    <KeyBinding Gesture="CTRL+S" Command="mashup:MashupInstance.MashupCommand">
      <KeyBinding.CommandParameter>
        <mashup:Events>
          <mashup:Event TargetName="CustomerDetail" TargetEventName="Update" Activate="SearchCustomerTextBox">
          </mashup:Event>
        </mashup:Events>
      </KeyBinding.CommandParameter>
    </KeyBinding>
  </Grid.InputBindings>
  <StackPanel Orientation="Horizontal" Margin="8,16,8,8">
  <StackPanel.InputBindings>
    <KeyBinding Key="Enter" Command="mashup:MashupInstance.MashupCommand">
      <KeyBinding.CommandParameter>
        <mashup:Events>
          <mashup:Event TargetName="CustomerList" TargetEventName="List">
            <mashup:Parameter TargetKey="CUNO" Value="{Binding ElementName=SearchCustomerTextBox, Path=Text}" />
          </mashup:Event>
        </mashup:Events>
      </KeyBinding.CommandParameter>
    </KeyBinding>
  </StackPanel.InputBindings>
  <TextBox Name="SearchCustomerTextBox" Width="200" Margin="0" />
  <Button Content="{mashup:Constant Key=Search,File=Mango.UI}" Width="100" VerticalAlignment="Center" Margin="8,0,5,0">
      <Button.CommandParameter>
        <mashup:Events>
          <mashup:Event SourceEventName="Click" TargetName="CustomerList" TargetEventName="List">
            <mashup:Parameter TargetKey="CUNO" Value="{Binding ElementName=SearchCustomerTextBox, Path=Text}" />
          </mashup:Event>
        </mashup:Events>
      </Button.CommandParameter>
    </Button>
  </StackPanel>
  
  <m3:MIListPanel Name="CustomerList" Margin="8" Grid.Row="1">
    <m3:MIListPanel.Events>
      <mashup:Events>
        <mashup:Event SourceEventName="Startup" TargetEventName="List" Activate="SearchCustomerTextBox" SourceName="CustomerList" />
        <mashup:Event SourceName="CustomerDetail" TargetName="CustomerList" SourceEventName="UpdateComplete" TargetEventName="List">
          <mashup:Parameter SourceKey="CUNO" TargetKey="CUNO" />
        </mashup:Event>
      </mashup:Events>
    </m3:MIListPanel.Events>
    <m3:MIListPanel.DataSource>
      <m3:MIDataSource Program="CRS610MI" Transaction="LstByNumber" Type="List" InputFields="CUNO" OutputFields="CUNO,CUNM,CUA1,CUA2" MaxReturnedRecords="200" />
    </m3:MIListPanel.DataSource>
    <ListView ItemsSource="{Binding Items}" Style="{DynamicResource styleListView}" ItemContainerStyle="{DynamicResource styleListViewItem}">
      <ListView.View>
        <GridView ColumnHeaderContainerStyle="{DynamicResource styleGridViewColumnHeader}">
          <GridView.Columns>
            <GridViewColumn Header="Customer number" DisplayMemberBinding="{Binding [CUNO]}" />
            <GridViewColumn Header="Customer name" DisplayMemberBinding="{Binding [CUNM]}" />
            <GridViewColumn Header="Customer address 1" DisplayMemberBinding="{Binding [CUA1]}" />
            <GridViewColumn Header="Customer address 2" DisplayMemberBinding="{Binding [CUA2]}" />
          </GridView.Columns>
        </GridView>
      </ListView.View>
    </ListView>
  </m3:MIListPanel>
  <m3:MIPanel Name="CustomerDetail" FocusManager.IsFocusScope="True" KeyboardNavigation.TabNavigation="Cycle" Grid.Row="2" Margin="8,16,8,8">
    <m3:MIPanel.Events>
      <mashup:Events>
        <mashup:Event SourceName="CustomerList" TargetName="CustomerDetail" SourceEventName="CurrentItemChanged" TargetEventName="Get">
          <mashup:Parameter SourceKey="CUNO" TargetKey="CUNO" />
        </mashup:Event>
      </mashup:Events>
    </m3:MIPanel.Events>
    <m3:MIPanel.DataSources>
      <m3:MIDataSourceList>
        <m3:MIDataSource Program="CRS610MI" Transaction="GetBasicData" Type="Get" InputFields="CUNO" OutputFields="CUNM,CUNO,CUA1,CUA2,CUA3,CUA4,YREF,CSCD" />
        <m3:MIDataSource Program="CRS610MI" Transaction="ChgBasicData" Type="Update" InputFields="CUNO,CUA1,CUA2,CUA3,CUNM,CUA4,YREF,CSCD" MandatoryInputFields="CUNO" />
      </m3:MIDataSourceList>
    </m3:MIPanel.DataSources>
    <Grid>
      <Grid.ColumnDefinitions>
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition Width="8" />
        <ColumnDefinition Width="200" />
        <ColumnDefinition Width="16" />
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition Width="8" />
        <ColumnDefinition Width="200" />
        <ColumnDefinition Width="16" />
        <ColumnDefinition Width="*" />
      </Grid.ColumnDefinitions>
      <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="Auto" />
        <RowDefinition Height="Auto" />
        <RowDefinition Height="Auto" />
        <RowDefinition Height="Auto" />
      </Grid.RowDefinitions>
      <Label Content="Customer number:" Grid.Row="0" Grid.Column="0" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="10" Text="{Binding [CUNO]}" Grid.Row="0" Grid.Column="2" HorizontalAlignment="Stretch" VerticalAlignment="Center" IsEnabled="False" />
      <Label Content="Customer _name:" Target="{Binding ElementName=nameTextBox}" Grid.Row="1" Grid.Column="0" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="36" TabIndex="1" Name="nameTextBox" Text="{Binding [CUNM], UpdateSourceTrigger=PropertyChanged}" Grid.Row="1" Grid.Column="2" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="Customer address 1:" Grid.Row="2" Grid.Column="0" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="36" Text="{Binding [CUA1], UpdateSourceTrigger=PropertyChanged}" Grid.Row="2" Grid.Column="2" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="Customer address 2:" TabIndex="3" Grid.Row="3" Grid.Column="0" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="36" Text="{Binding [CUA2], UpdateSourceTrigger=PropertyChanged}" Grid.Row="3" Grid.Column="2" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="Customer address 3:" Grid.Row="0" Grid.Column="4" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="36" Text="{Binding [CUA3], UpdateSourceTrigger=PropertyChanged}" Grid.Row="0" Grid.Column="6" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="Customer address 4:" Grid.Row="1" Grid.Column="4" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="36" Text="{Binding [CUA4], UpdateSourceTrigger=PropertyChanged}" Grid.Row="1" Grid.Column="6" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="_Your reference 1:" Target="{Binding ElementName=referenceTextBox}" Grid.Row="2" Grid.Column="4" HorizontalAlignment="Left" VerticalAlignment="Center" />
      <TextBox MaxLength="30" TabIndex="2" Name="referenceTextBox" Text="{Binding [YREF], UpdateSourceTrigger=PropertyChanged}" Grid.Row="2" Grid.Column="6" HorizontalAlignment="Stretch" VerticalAlignment="Center" />
      <Label Content="Country code:" Grid.Row="3" Grid.Column="4" HorizontalAlignment="Left" VerticalAlignment="Center" />
    
    <m3:MIComboBox Grid.Row="3" Grid.Column="6" HorizontalAlignment="Left" VerticalAlignment="Center" Margin="5" Width="190" SelectedValuePath="[STKY]" SelectedValue="{Binding [GetBasicData.CSCD], UpdateSourceTrigger=PropertyChanged}" SortField="TX15" InputValue1="CSCD" InputName1="STCO" DisplayMemberPath="[TX15]">
         <m3:MIComboBox.DataSource>
           <m3:MIDataSource Program="CRS175MI" Transaction="LstGeneralCode" IsCacheable="True" MaxReturnedRecords="0" />
         </m3:MIComboBox.DataSource>
      </m3:MIComboBox>
      <StackPanel Grid.Row="4" Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,16,0,0" Grid.ColumnSpan="7">
        <Button Content="{mashup:Constant Key=Save,File=Mango.UI}" Width="150" VerticalAlignment="Center" Margin="8,0,5,0">
          <Button.CommandParameter>
            <mashup:Events>
              <mashup:Event TargetEventName="Update" TargetName="CustomerDetail" />
            </mashup:Events>
          </Button.CommandParameter>
        </Button>
      </StackPanel>
    </Grid>
  </m3:MIPanel>
  <ui:StatusBar Name="StatusBar" Grid.Row="3" Grid.Column="0" />
</Grid>

Additional resources

Focus overview on MSDN
AccessKeys
MSDN Update Source trigger

For an example of Tab navigation and more stuff you can do check out the Tab Control (Common Examples) under the Help menu in the Mashup Designer.