I did a bit of drafting, of what this may look like later on. The code sample is by far not set in stone; TBH I didn't even try to compile it. It's just provided as a possible reference of what this might look/feel like.

Note, that one part, which this approach currently does not handle is discoverability, i.e. it does not provide for an intuitive way for users to discover this functionality. Well, it doesn't provide any integration at all yet. This would be part of a full-blown PR for this feature.

Furthermore note, that the changes to the existing code base should best be kept to a minimum. And even with this approach there will be the need to touch every single function that somehow handles keyboard/mouse input. Hopefully with the idea for the API this should be manageable, but keep in mind that this is one of several places where things might spiral out of control pretty quick.

Okay, here's the sample I hinted to:

KeyMapper.h

#ifndef HEADER_KeyMapper
#define HEADER_KeyMapper
/*
htop - KeyMapper.h
(C) 2025 htop dev team
Released under the GNU GPLv2+, see the COPYING file
in the source distribution for its full text.
*/

#include <stdarg.h>
#include <stdbool.h>
#include <wchar.h>

#include "Hashtable.h"
#include "ProvideCurses.h"
#include "XUtils.h"

typedef struct KeyMapper_ KeyMapper;

KeyMapper* KeyMapper_new(void);

void KeyMapper_delete(KeyMapper* this);

bool KeyMapper_defineKey(KeyMapper* this, const char* name, const char* sequence, int keyCode);

bool KeyMapper_mapKeys(KeyMapper* this, const char* actionName, const int* keyCodes, size_t nKeyCodes);

bool KeyMapper_loadConfig(KeyMapper* this, const char* filename);

bool KeyMapper_isKeyAction_impl(KeyMapper* this, int ch, const char* actionName, ...);

#define KeyMapper_isKeyAction(this, ch, action, ...) KeyMapper_isKeyAction_impl(this, ch, action, __VA_ARGS__, 0)

#endif /* HEADER_KeyMapper */

KeyMapper.c

/*
htop - KeyMapper.c
(C) 2025 htop dev team
Released under the GNU GPLv2+, see the COPYING file
in the source distribution for its full text.
*/

#include "config.h" // IWYU pragma: keep

#include "KeyMapper.h"

#include <ctype.h>
#include <errno.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>


// Key definition - maps terminal sequences to key codes
typedef struct KeyDefinition_ {
   char* name;      // Name of the key (e.g., "F15")
   char* sequence;  // Terminal escape sequence
   int keyCode;     // Numeric key code
} KeyDefinition;

// Key mapping - maps action names to key codes
typedef struct KeyMapping_ {
   char* actionName;  // Name of the action (e.g., "EXAMPLE")
   int* keyCodes;     // Array of key codes
   size_t nKeyCodes;  // Number of key codes
} KeyMapping;

// The KeyMapper object
struct KeyMapper_ {
   Hashtable* keyDefinitions;  // Maps key names to KeyDefinition objects
   Hashtable* keyMappings;     // Maps action names to KeyMapping objects
};

// Helper functions

static ht_key_t KeyMapper_hashString(const char* str) {
   ht_key_t hash = 0;
   for (const char* p = str; *p; p++)
      hash = (hash * 31) + *p;
   return hash;
}

static void KeyDefinition_delete(KeyDefinition* def) {
   if (def) {
      free(def->name);
      free(def->sequence);
      free(def);
   }
}

static void KeyMapping_delete(KeyMapping* mapping) {
   if (mapping) {
      free(mapping->actionName);
      free(mapping->keyCodes);
      free(mapping);
   }
}

static void KeyMapper_freeDefinition(ht_key_t key, void* value, void* userdata) {
   KeyDefinition* def = (KeyDefinition*)value;
   KeyDefinition_delete(def);
}

static void KeyMapper_freeMapping(ht_key_t key, void* value, void* userdata) {
   KeyMapping* mapping = (KeyMapping*)value;
   KeyMapping_delete(mapping);
}

static char* KeyMapper_parseEscapeSequence(const char* input) {
   if (!input || !*input)
      return NULL;

   // Allocate based on input length - will never need more than this
   char* output = xMalloc(strlen(input) + 1);
   char* out = output;
   bool error = false;
   
   for (const char* p = input; *p && !error; p++) {
      if (*p == '\\' && *(p + 1)) {
         switch (*(p + 1)) {
            case 'a': 
               *out++ = '\a'; 
               p++; 
               break;  // Bell (alert)
            case 'b': 
               *out++ = '\b'; 
               p++; 
               break;  // Backspace
            case 'e': 
            case 'E': 
               *out++ = '\033'; 
               p++; 
               break; // Escape
            case 'f': 
               *out++ = '\f'; 
               p++; 
               break;  // Form feed
            case 'n': 
               *out++ = '\n'; 
               p++; 
               break;  // Newline
            case 'r': 
               *out++ = '\r'; 
               p++; 
               break;  // Carriage return
            case 't': 
               *out++ = '\t'; 
               p++; 
               break;  // Horizontal tab
            case 'v': 
               *out++ = '\v'; 
               p++; 
               break;  // Vertical tab
            case '\\': 
               *out++ = '\\'; 
               p++; 
               break; // Backslash
            case '\'': 
               *out++ = '\''; 
               p++; 
               break; // Single quote
            case '\"': 
               *out++ = '\"'; 
               p++; 
               break; // Double quote
            case '?': 
               *out++ = '\?'; 
               p++; 
               break;  // Question mark
            
            // Octal escape: \nnn (1-3 octal digits)
            case '0': 
            case '1': 
            case '2': 
            case '3': 
            case '4': 
            case '5': 
            case '6': 
            case '7': {
               int value = *(p + 1) - '0';
               p++;
               
               // Get up to 2 more octal digits
               if (*(p + 1) >= '0' && *(p + 1) <= '7') {
                  value = (value << 3) + (*(p + 1) - '0');
                  p++;
                  
                  if (*(p + 1) >= '0' && *(p + 1) <= '7') {
                     value = (value << 3) + (*(p + 1) - '0');
                     p++;
                  }
               }
               
               // Check for NUL byte - treat as failure
               if (value == 0) {
                  error = true;
                  break;
               }
               
               *out++ = (char)value;
               break;
            }
            
            // Hex escape: \xhh (variable number of hex digits)
            case 'x': {
               p++; // Skip 'x'
               
               // Must have at least one hex digit
               if (!isxdigit((unsigned char)*(p + 1))) {
                  // Not a valid hex sequence, use literal 'x'
                  *out++ = 'x';
               } else {
                  int value = 0;
                  
                  // Read all consecutive hex digits
                  while (isxdigit((unsigned char)*(p + 1))) {
                     p++;
                     if (isdigit((unsigned char)*p)) {
                        value = (value << 4) + (*p - '0');
                     } else {
                        value = (value << 4) + (tolower((unsigned char)*p) - 'a' + 10);
                     }
                  }
                  
                  // Check for NUL byte - treat as failure
                  if (value == 0) {
                     error = true;
                     break;
                  }
                  
                  *out++ = (char)value;
               }
               break;
            }
            
            default:
               // Unknown escape - just output the character after the backslash
               *out++ = *(p + 1);
               p++;
         }
      } else {
         // Normal character
         *out++ = *p;
      }
   }
   
   if (error) {
      free(output);
      return NULL;
   }
   
   *out = '\0';
   return output;
}

static int KeyMapper_parseKeyCode(KeyMapper* this, const char* keyName) {
   // Check if it's a numeric value
   char* endptr;
   long keyCode = strtol(keyName, &endptr, 0);
   if (*endptr == '\0')
      return (int)keyCode;
   
   // Check if it's a special key name
   if (String_eq(keyName, "HOME")) 
      return KEY_HOME;
   if (String_eq(keyName, "END")) 
      return KEY_END;
   if (String_eq(keyName, "PGUP") || String_eq(keyName, "PPAGE")) 
      return KEY_PPAGE;
   if (String_eq(keyName, "PGDN") || String_eq(keyName, "NPAGE")) 
      return KEY_NPAGE;
   if (String_eq(keyName, "INS") || String_eq(keyName, "INSERT")) 
      return KEY_IC;
   if (String_eq(keyName, "DEL") || String_eq(keyName, "DELETE")) 
      return KEY_DC;
   if (String_eq(keyName, "BACKSPACE")) 
      return KEY_BACKSPACE;
   if (String_eq(keyName, "TAB")) 
      return KEY_TAB;
   if (String_eq(keyName, "ENTER") || String_eq(keyName, "RETURN")) 
      return KEY_ENTER;
   if (String_eq(keyName, "ESCAPE") || String_eq(keyName, "ESC")) 
      return 27;
   if (String_eq(keyName, "SPACE")) 
      return ' ';
   if (String_eq(keyName, "SHIFT_TAB")) 
      return KEY_SHIFT_TAB;
   if (String_eq(keyName, "UP")) 
      return KEY_UP;
   if (String_eq(keyName, "DOWN")) 
      return KEY_DOWN;
   if (String_eq(keyName, "LEFT")) 
      return KEY_LEFT;
   if (String_eq(keyName, "RIGHT")) 
      return KEY_RIGHT;

   // Check for function keys (F1-F63)
   if (keyName[0] == 'F' && isdigit((unsigned char)keyName[1])) {
      int fnum = atoi(keyName + 1);
      if (fnum >= 1 && fnum <= 63)
         return KEY_F(fnum);
   }
   
   // Check if it's a defined key in our definitions
   ht_key_t key = KeyMapper_hashString(keyName);
   KeyDefinition* def = Hashtable_get(this->keyDefinitions, key);
   if (def)
      return def->keyCode;
   
   // Assume it's a character
   if (keyName[0] && !keyName[1])
      return (int)(unsigned char)keyName[0];
   
   return ERR; // Key not recognized
}

KeyMapper* KeyMapper_new(void) {
   KeyMapper* this = xCalloc(1, sizeof(KeyMapper));
   this->keyDefinitions = Hashtable_new(64, true);
   this->keyMappings = Hashtable_new(64, true);
   return this;
}

void KeyMapper_delete(KeyMapper* this) {
   if (!this)
      return;
   
   Hashtable_foreach(this->keyDefinitions, KeyMapper_freeDefinition, NULL);
   Hashtable_foreach(this->keyMappings, KeyMapper_freeMapping, NULL);
   
   Hashtable_delete(this->keyDefinitions);
   Hashtable_delete(this->keyMappings);
   
   free(this);
}

bool KeyMapper_defineKey(KeyMapper* this, const char* name, const char* sequence, int keyCode) {
   if (!this || !name || !sequence)
      return false;
   
   ht_key_t hash = KeyMapper_hashString(name);
   
   // Check if this key is already defined
   KeyDefinition* existingDef = Hashtable_get(this->keyDefinitions, hash);
   if (existingDef) {
      free(existingDef->sequence);
      existingDef->sequence = xStrdup(sequence);
      existingDef->keyCode = keyCode;
      
      // Register with ncurses
      define_key(sequence, keyCode);
      return true;
   }
   
   // Create a new definition
   KeyDefinition* def = xCalloc(1, sizeof(KeyDefinition));
   def->name = xStrdup(name);
   def->sequence = xStrdup(sequence);
   def->keyCode = keyCode;
   
   Hashtable_put(this->keyDefinitions, hash, def);
   
   // Register with ncurses
   define_key(sequence, keyCode);
   
   return true;
}

bool KeyMapper_mapKeys(KeyMapper* this, const char* actionName, const int* keyCodes, size_t nKeyCodes) {
   if (!this || !actionName || !keyCodes || nKeyCodes == 0)
      return false;
   
   ht_key_t hash = KeyMapper_hashString(actionName);
   
   // Check if this action is already mapped
   KeyMapping* existingMapping = Hashtable_get(this->keyMappings, hash);
   if (existingMapping) {
      free(existingMapping->keyCodes);
      existingMapping->keyCodes = xMallocArray(nKeyCodes, sizeof(int));
      memcpy(existingMapping->keyCodes, keyCodes, nKeyCodes * sizeof(int));
      existingMapping->nKeyCodes = nKeyCodes;
      return true;
   }
   
   // Create a new mapping
   KeyMapping* mapping = xCalloc(1, sizeof(KeyMapping));
   mapping->actionName = xStrdup(actionName);
   mapping->keyCodes = xMallocArray(nKeyCodes, sizeof(int));
   memcpy(mapping->keyCodes, keyCodes, nKeyCodes * sizeof(int));
   mapping->nKeyCodes = nKeyCodes;
   
   Hashtable_put(this->keyMappings, hash, mapping);
   
   return true;
}

bool KeyMapper_isKeyAction_impl(KeyMapper* this, int ch, const char* actionName, ...) {
   if (!this || !actionName)
      return false;
   
   // First check custom mappings
   ht_key_t hash = KeyMapper_hashString(actionName);
   KeyMapping* mapping = Hashtable_get(this->keyMappings, hash);
   
   if (mapping) {
      for (size_t i = 0; i < mapping->nKeyCodes; i++) {
         if (mapping->keyCodes[i] == ch) {
            return true;
         }
      }
   }
   
   // No custom mapping or no match, check default keys
   va_list args;
   va_start(args, actionName);
   
   int defaultKey;
   while ((defaultKey = va_arg(args, int)) != 0) {
      if (ch == defaultKey) {
         va_end(args);
         return true;
      }
   }
   
   va_end(args);
   return false;
}

bool KeyMapper_loadConfig(KeyMapper* this, const char* filename) {
   FILE* file = fopen(filename, "r");
   if (!file)
      return false;
   
   char line[1024];
   while (fgets(line, sizeof(line), file)) {
      // Remove comments and trailing whitespace
      char* comment = strchr(line, '#');
      if (comment)
         *comment = '\0';
      
      // Trim right
      char* end = line + strlen(line) - 1;
      while (end >= line && isspace((unsigned char)*end))
         *end-- = '\0';
      
      // Skip empty lines
      if (line[0] == '\0')
         continue;
      
      // Parse command
      char* cmd = strtok(line, " \t");
      if (!cmd)
         continue;
      
      if (String_eq(cmd, "DefKey")) {
         char* keyName = strtok(NULL, " \t");
         char* sequence = strtok(NULL, "");
         
         if (!keyName || !sequence)
            continue;
         
         // Trim leading whitespace from sequence
         while (isspace((unsigned char)*sequence))
            sequence++;
         
         // Remove quotes if present
         if (sequence[0] == '"' && sequence[strlen(sequence) - 1] == '"') {
            sequence[strlen(sequence) - 1] = '\0';
            sequence++;
         }
         
         char* parsedSeq = KeyMapper_parseEscapeSequence(sequence);
         if (!parsedSeq)
            continue;
         
         int keyCode = KEY_F(0); // Use a default
         
         // Check if keyName is FXX - assign proper key code
         if (keyName[0] == 'F' && isdigit((unsigned char)keyName[1])) {
            int fnum = atoi(keyName + 1);
            if (fnum >= 1 && fnum <= 63)
               keyCode = KEY_F(fnum);
         }
         
         KeyMapper_defineKey(this, keyName, parsedSeq, keyCode);
         free(parsedSeq);
      }
      else if (String_eq(cmd, "Map")) {
         char* actionName = strtok(NULL, " \t");
         if (!actionName)
            continue;
         
         // Collect key codes
         int keyCodes[64];
         size_t count = 0;
         
         char* keyName;
         while ((keyName = strtok(NULL, " \t,")) && count < 64) {
            // Trim spaces
            while (isspace((unsigned char)*keyName))
               keyName++;
               
            char* end = keyName + strlen(keyName) - 1;
            while (end > keyName && isspace((unsigned char)*end))
               *end-- = '\0';
               
            int keyCode = KeyMapper_parseKeyCode(this, keyName);
            if (keyCode != ERR) {
               keyCodes[count++] = keyCode;
            }
         }
         
         if (count > 0) {
            KeyMapper_mapKeys(this, actionName, keyCodes, count);
         }
      }
   }
   
   fclose(file);
   return true;
}

I think a sensible way to implement this later on could be to provide a set of example keymaps, where the user could copy the desired map into the config directory of htop to activate it. But as mentioned: A more "discoverable" approach would be much preferred. With that suggested implementation a key map might look like this:

Example of a keymap file

# Key definitions (terminal escape sequences)
# Format: DefKey NAME "ESCAPE_SEQUENCE"

# Function keys
DefKey F1 "\033OP"
DefKey F2 "\033OQ"
DefKey F3 "\033OR"
DefKey F4 "\033OS"
DefKey F5 "\033[15~"
DefKey F6 "\033[17~"
DefKey F7 "\033[18~"
DefKey F8 "\033[19~"
DefKey F9 "\033[20~"
DefKey F10 "\033[21~"
DefKey F11 "\033[23~"
DefKey F12 "\033[24~"
DefKey F15 "\033O2R"

# Movement keys
DefKey HOME "\033[H"
DefKey END "\033[F"
DefKey PGUP "\033[5~"
DefKey PGDN "\033[6~"
DefKey SHIFT_TAB "\033[Z"

# Arrow keys with Alt modifier
DefKey ALT_UP "\033\033[A"
DefKey ALT_DOWN "\033\033[B"
DefKey ALT_RIGHT "\033\033[C"
DefKey ALT_LEFT "\033\033[D"

# Custom key sequences
DefKey CTRL_A "\001"
DefKey CTRL_E "\005"
DefKey CTRL_F "\006"
DefKey CTRL_B "\002"
DefKey CTRL_N "\016"
DefKey CTRL_P "\020"
DefKey CTRL_L "\014"
DefKey WHEEL_UP "\033[65;3~"
DefKey WHEEL_DOWN "\033[66;3~"

# Action mappings
# Format: Map ACTION KEY1, KEY2, KEY3...

# Main screen actions
Map HELP F1, h, ?
Map SETUP F2, S
Map SEARCH F3, /
Map FILTER F4, \
Map TREE F5, t
Map SORTBY F6
Map NICE_DEC F7, ]
Map NICE_INC F8, [
Map KILL F9, k
Map QUIT F10, q, ESC

# Process navigation and manipulation
Map TOGGLE_TREE SPACE
Map TAG_PROCESS SPACE
Map TAG_CHILDREN c
Map UNTAG_ALL U
Map SORT_BY_PID N
Map SORT_BY_MEM M
Map SORT_BY_CPU P
Map SORT_BY_TIME T
Map FOLLOW_PROCESS F
Map HIDE_KERNEL_THREADS K
Map HIDE_USERLAND_THREADS H
Map HIDE_CONTAINER_PROCESSES O
Map SHOW_PATH p
Map PAUSE_UPDATES Z
Map EXPAND_COLLAPSE_ALL *
Map EXPAND_COLLAPSE +, -
Map SET_AFFINITY a
Map LIST_OPEN_FILES l
Map STRACE s
Map SHOW_COMMAND_LINE w
Map SHOW_LOCKS x

# Panel navigation
Map UP_ITEM UP, CTRL_P
Map DOWN_ITEM DOWN, CTRL_N
Map LEFT_COLUMN LEFT, CTRL_B
Map RIGHT_COLUMN RIGHT, CTRL_F
Map PAGE_UP PGUP
Map PAGE_DOWN PGDN
Map GO_HOME HOME, CTRL_A
Map GO_END END, CTRL_E
Map SCROLL_WHEEL_UP WHEEL_UP
Map SCROLL_WHEEL_DOWN WHEEL_DOWN

# Meters panel actions
Map METER_CHANGE_STYLE SPACE
Map METER_TOGGLE_LOCK ENTER
Map METER_MOVE_UP UP, F7
Map METER_MOVE_DOWN DOWN, F8
Map METER_MOVE_LEFT LEFT
Map METER_MOVE_RIGHT RIGHT
Map METER_REMOVE DEL, F9

# InfoScreen actions
Map REFRESH_SCREEN F5, CTRL_L
Map AUTO_SCROLL F8

# Display options
Map TOGGLE_HIDE_METERS #
Map TOGGLE_PROCESSES_MERGE m
Map USER_FILTER u
Map REDRAW CTRL_L

# Screen tabs navigation
Map NEXT_SCREEN TAB
Map PREV_SCREEN SHIFT_TAB

As mentioned: Nothing of this is tested and solely serves as a possible starting point.

This is no endorsement of a particular implementation or even that a full PR in this direction will land. This is just an idea, what things COULD look like.

Uh oh!

Ability to remap keys or enable Vim-mode #638

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions