Keyboard Navigation

You can get access to Gantt and its elements via keys or keys' combinations. This article will give you all the necessary information on the peculiarities of keyboard navigation with Gantt, including focus behavior, usage of ready shortcuts and creation of custom ones.

Enabling the functionality

In order to use keyboard navigation in the Gantt chart, you need to include the ext/dhtmlxgantt_keyboard_navigation.js extension on the page.

<script src="../../codebase/ext/dhtmlxgantt_keyboard_navigation.js" 
    type="text/javascript" charset="UTF-8"></script>

The API of the gantt.ext.keyboardNavigation object is given in the article Keyboard Navigation Extension.

There are two variants of keyboard navigation available:

  • navigation by task rows

To enable it, set the keyboard_navigation property to true.

  • navigation by task cells

To use this type of navigation, set the keyboard_navigation_cells property to true.

Focus behavior during keyboard navigation

Focus on Gantt

When the Tab key is pressed, Gantt gets focus the same as any usual element. After that to navigate Gantt, you can use the arrow keys and other ones.

When the Tab key is pressed for the second time, the focus leaves Gantt and is moved to some other place on the page.

Focus on a modal window

When a modal window (a lightbox, a confirm window) opens, the focus moves from Gantt to this window and navigation happens inside of it as in a simple form. When the window is closed, focus goes back to Gantt.

To return focus back to Gantt, you need to use the focus method. When Gantt gets focus again, it places the focus on the active element inside, or on the first row, or on the latest selected element.

The default navigation actions in a modal window are as follows:

  • Enter - confirm and close
  • Escape - close without any changes

If the focus is set on some button of the form, pressing Space or Enter will call pressing the button under focus and not the action.

Scopes

An action called on a key click depends on the context. It means that different actions can be attached to different elements (scopes). There are the following context elements (scopes) in the Gantt chart:

  • "gantt" - The whole gantt
  • "taskRow" - A row with a task
  • "taskCell" - A cell of the row with a task
  • "headerCell" - A cell of the header

If one and the same shortcut is attached to several scopes, the more specific shortcut will trigger. It means that if the same shortcut is attached to Gantt and to its element, the shortcut attached to an element will be called rather than the shortcut attached to the whole Gantt.

Adding a shortcut

To create a new keyboard shortcut, you need to use the addShortcut method and pass three parameters to it:

  • shortcut - (string) a new shortcut key or keys' combination name
  • handler - (function) a handler function that will be called on the shortcut call
  • scope - (string) the name of the context element to attach the handler function to
gantt.addShortcut("shift+w", function(e){ 
    var task = gantt.locate(e); 
    if(task) 
        gantt.showQuickInfo(task)
},"taskRow");

Removing a shortcut

To remove a shortcut from the scope, you need to use the removeShortcut method. The method takes two parameters:

  • shortcut - (string) the name of the key or the keys' combination for shortcut
  • scope - (string) the name of the context element to which the shortcut is attached
gantt.removeShortcut("shift+w","taskRow");

Getting a shortcut handler

You can get the handler of the keyboard shorcut with the help of the method getShortcutHandler. It takes two parameters:

  • shortcut - (string) the name of the key or the keys' combination for shortcut
  • scope - (string) the name of the context element to which the shortcut is attached
var shortcut_handler = gantt.getShortcutHandler("shift+w","taskRow");

The method returns a function, which presents the handler of the shortcut call.

Shortcut syntax

A keyboard shortcut can consist of the following keys or key combinations:

  • a modifier key + a character key ("ctrl+a");
  • a modifier key + a non-character key ("ctrl+space");
  • a character key ("a");
  • a non-character key ("space")

There can be several key combinations for one action. In this case, all the combinations are listed with comma delimiter: "ctrl+a, ctrl+space".

The list of supported keys to use in shortcuts

  • modifier keys: shift, alt, ctrl, meta;
  • non-character keys: backspace, tab, enter, esc, space, up, down, left, right, home, end, pageup, pagedown, delete, insert, plus, f1-f12.

Existing shortcuts

There is a set of ready shortcuts that you can use to navigate the Gantt chart:

General keyboard shortcuts:

  • Tab - set focus on Gantt
  • Alt+Up/Down - scroll Gantt vertically
  • Alt+Left/Right - scroll Gantt horizontally
  • Ctrl+Enter - create a new task
  • Ctrl+Z - undo the action
  • Ctrl+R - redo the action

Shortcuts for Header Cells

  • Left/Right Arrow Keys - navigate over header cells
  • Home/End - navigate to the first/last column
  • Down - move to the rows with tasks
  • Space/Enter - click on the header (for example, for sorting)

Shortcuts for Task Rows

  • Up/Down - navigate through rows
  • PageDown/PageUp - navigate to the first/last task
  • Space - select a task
  • Ctrl+Enter - create a new task
  • Delete - remove the selected task
  • Enter - open the lightbox
  • Ctrl+Left/Right - expand/collapse the tree
  • Shift+Left/Right - indent/outdent task
  • Shift+Down/Up - expand/collapse branch

Related sample:  Keyboard Navigation

Shortcuts for Task Cells

  • Up/Down/Left/Right Arrow Keys - navigate over Task cells
  • PageDown/PageUp - navigate to the first/last cell in a column
  • Home/End - navigate to the first/last cell in a column
  • Space - select a task
  • Ctrl+Enter - create a new task
  • Delete - remove the selected task
  • Enter - open the lightbox
  • Ctrl+Left/Right - expand/collapse the tree

Related sample:  Keyboard Navigation - navigate cells

Built-in Shortcut for Horizontal Timeline Scrolling

Starting from the version 4.2, the Gantt chart provides a possibility to scroll the timeline horizontally by using the following combination:

-> Shift key + mouse wheel movement.

From version 6.3 you can either set the Alt or Meta key in the combination with mouse wheel instead of default Shift key via the horizontal_scroll_key property:

gantt.config.horizontal_scroll_key = "altKey";

or disable the horizontal scroll by setting the horizontal_scroll_key property to false:

gantt.config.horizontal_scroll_key = false;
Back to top