DataGrid: add Custom keyboard navigation topic (#5573)

DevExpress · Sep 18, 2023 · b78dee6 · b78dee6
1 parent 4b08261
commit b78dee6
Show file tree

Hide file tree

Showing 5 changed files with 204 additions and 1 deletion.
diff --git a/concepts/05 UI Components/DataGrid/05 Accessibility/15 Keyboard Navigation.md b/concepts/05 UI Components/DataGrid/05 Accessibility/15 Keyboard Navigation.md
@@ -103,4 +103,4 @@ A user can use the following keys to interact with the DataGrid component:
     </ol>
 </div>
 
-You can override these shortcuts or create your own shortcuts using the [onKeyDown](/api-reference/10%20UI%20Components/dxDataGrid/1%20Configuration/onKeyDown.md '/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#onKeyDown') event handler.
+You can override these shortcuts or create your own. Refer to the following help topic for more information: [Custom Keyboard Navigation](/Documentation/Guide/UI_Components/DataGrid/Custom_Keyboard_Navigation/).
diff --git a/...ponents/DataGrid/70 Custom Keyboard Navigation/00 Custom Keyboard Navigation.md b/...ponents/DataGrid/70 Custom Keyboard Navigation/00 Custom Keyboard Navigation.md
@@ -0,0 +1 @@
+You can use the [keyboardNavigation](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/keyboardNavigation/) property to configure DataGrid [keyboard navigation](/Documentation/Guide/UI_Components/DataGrid/Accessibility/#Keyboard_Navigation). If the default behavior does not meet your requirements, you can change it.
diff --git a/...ts/DataGrid/70 Custom Keyboard Navigation/05 Change the Default Focused Cell.md b/...ts/DataGrid/70 Custom Keyboard Navigation/05 Change the Default Focused Cell.md
@@ -0,0 +1,90 @@
+To specify cell focus order when a user navigates through DataGrid, call the [onFocusedCellChanging](https://js.devexpress.com/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#onFocusedCellChanging) function. The code below uses `newColumnIndex` to set the column index of the next focused cell.
+
+---
+##### jQuery
+
+    <!-- tab: index.js -->
+    $("#dataGridContainer").dxDataGrid({
+        // ...
+        onFocusedCellChanging: function (e) {
+            if (e.columns[e.newColumnIndex].dataField === "myField") { // Checks if the next focused cell is in the 'myField' column
+                e.newColumnIndex++; // Navigates to the next column
+            }
+        }
+    });
+
+##### Angular
+
+    <!-- tab: app.component.html -->
+    <dx-data-grid ...
+        (onFocusedCellChanging)="onFocusedCellChanging($event)">
+    </dx-data-grid>
+
+    <!-- tab: app.component.ts -->
+    import { Component } from '@angular/core';
+
+    @Component({
+        selector: 'app-root',
+        templateUrl: './app.component.html',
+        styleUrls: ['./app.component.css']
+    })
+
+    export class AppComponent {
+        onFocusedCellChanging(e) {
+            if (e.columns[e.newColumnIndex].dataField === "myField") { // Checks if the next focused cell is in the 'myField' column
+                e.newColumnIndex++; // Navigates to the next column
+            }
+        }
+    }
+
+##### Vue
+
+    <!-- tab: App.vue -->
+    <template>
+        <DxDataGrid ...
+            @focused-cell-changing="onFocusedCellChanging">
+        </DxDataGrid>
+    </template>
+
+    <script>
+    import 'devextreme/dist/css/dx.light.css';
+    import DxDataGrid from 'devextreme-vue/data-grid';
+
+    export default {
+        components: {
+            DxDataGrid
+        },
+        // ...
+        methods: {
+            onFocusedCellChanging(e) {
+                if (e.columns[e.newColumnIndex].dataField === "myField") { // Checks if the next focused cell is in the 'myField' column
+                    e.newColumnIndex++; // Navigates to the next column
+                }
+            }
+        }
+    }
+    </script>
+
+##### React
+
+    <!-- tab: App.js -->
+    import React from 'react';
+    import 'devextreme/dist/css/dx.light.css';
+    import DataGrid from 'devextreme-react/data-grid';
+
+    const onFocusedCellChanging = (e) => {
+        if (e.columns[e.newColumnIndex].dataField === "myField") { // Checks if the next focused cell is in the 'myField' column
+            e.newColumnIndex++; // Navigates to the next column
+        }
+    }
+
+    function App() {
+        return (
+            <DataGrid ...
+                onFocusedCellChanging={onFocusedCellChanging}>
+            </DataGrid>
+        );
+    }
+    export default App;
+
+---
diff --git a/...onents/DataGrid/70 Custom Keyboard Navigation/10 Focus Cells Programatically.md b/...onents/DataGrid/70 Custom Keyboard Navigation/10 Focus Cells Programatically.md
@@ -0,0 +1,7 @@
+You can call the following methods to focus a cell:
+
+- [focus](/Documentation/ApiReference/UI_Components/dxDataGrid/Methods/#focuselement)     
+Allows you to move focus to a cell. Call the [getCellElement](/Documentation/ApiReference/UI_Components/dxDataGrid/Methods/#getCellElementrowIndex_dataField) method to obtain a cell container. Then, pass the container to the **focus** method as an argument to focus the target cell.
+
+- [editCell](/Documentation/ApiReference/UI_Components/dxDataGrid/Methods/#editCellrowIndex_dataField)     
+Switches a cell to the edit state and moves focus to this cell.
diff --git a/...omponents/DataGrid/70 Custom Keyboard Navigation/15 Override and Create Keys.md b/...omponents/DataGrid/70 Custom Keyboard Navigation/15 Override and Create Keys.md
@@ -0,0 +1,105 @@
+The [onKeyDown](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#onKeyDown) event handler allows you to track pressed keystrokes while the UI component has focus. You can use the event handler to override the default keyboard shortcuts, implement custom keystrokes, or extend existing ones.
+
+The following example shows how to override the **Space Bar** keystroke so it switches a cell in cell/batch mode to the edit state instead of a current row select operation:
+
+---
+##### jQuery
+
+    <!-- tab: index.js -->
+    $("#dataGridContainer").dxDataGrid({
+        // ...
+        onKeyDown: function (e) {
+            if (e.event.keyCode === 32) { // Checks if the space bar key is pressed
+                e.event.preventDefault(); // Prevents the default behavior
+                const focusedRowIndex = e.component.option("focusedRowIndex");
+                const focusedColumnIndex = e.component.option("focusedColumnIndex");
+                e.component.editCell(focusedRowIndex, focusedColumnIndex);
+            }
+        }
+    })
+
+##### Angular
+
+    <!-- tab: app.component.html -->
+    <dx-data-grid ...
+        (onKeyDown)="onKeyDown($event)">
+    </dx-data-grid>
+
+    <!-- tab: app.component.ts -->
+    import { Component } from '@angular/core';
+
+    @Component({
+        selector: 'app-root',
+        templateUrl: './app.component.html',
+        styleUrls: ['./app.component.css']
+    })
+
+    export class AppComponent {
+        onKeyDown(e) {
+            if (e.event.keyCode === 32) { // Checks if the space bar key is pressed
+                e.event.preventDefault(); // Prevents the default behavior
+                const focusedRowIndex = e.component.option("focusedRowIndex");
+                const focusedColumnIndex = e.component.option("focusedColumnIndex");
+                e.component.editCell(focusedRowIndex, focusedColumnIndex);
+            }
+        }
+    }
+
+##### Vue
+
+    <!-- tab: App.vue -->
+    <template>
+        <DxDataGrid ...
+            @key-down="onKeyDown">
+        </DxDataGrid>
+    </template>
+
+    <script>
+    import 'devextreme/dist/css/dx.light.css';
+    import DxDataGrid from 'devextreme-vue/data-grid';
+
+    export default {
+        components: {
+            DxDataGrid
+        },
+        // ...
+        methods: {
+            onKeyDown(e) {
+                if (e.event.keyCode === 32) { // Checks if the space bar key is pressed
+                    e.event.preventDefault(); // Prevents the default behavior
+                    const focusedRowIndex = e.component.option("focusedRowIndex");
+                    const focusedColumnIndex = e.component.option("focusedColumnIndex");
+                    e.component.editCell(focusedRowIndex, focusedColumnIndex);
+                }
+            }
+        }
+    }
+    </script>
+
+##### React
+
+    <!-- tab: App.js -->
+    import React from 'react';
+    import 'devextreme/dist/css/dx.light.css';
+    import DataGrid from 'devextreme-react/data-grid';
+
+    const onKeyDown = (e) => {
+        if (e.event.keyCode === 32) { // Specifies if the space bar key is pressed
+            e.event.preventDefault(); // Prevents the default behavior
+            const focusedRowIndex = e.component.option("focusedRowIndex");
+            const focusedColumnIndex = e.component.option("focusedColumnIndex");
+            e.component.editCell(focusedRowIndex, focusedColumnIndex);
+        }
+    }
+
+    function App() {
+        return (
+            <DataGrid ...
+                onKeyDown={onKeyDown}>
+            </DataGrid>
+        );
+    }
+
+    export default App;
+
+---