Introduce class TKey

Author: magiblot

.gitignore

@@ -9,6 +9,8 @@
 !project/**/
 !source/
 !source/**/
+!test/
+!test/**/
 !.github/
 !.github/**/
 

CMakeLists.txt

@@ -14,6 +14,7 @@
 #   (CMake 3.16 or newer), at the cost of possibly increasing its size.
 # * TV_BUILD_AVSCOLOR (default OFF) to build an AviSynth plugin for testing the
 #   terminal color quantization (Unix only).
+# * TV_BUILD_TESTS (default OFF) to build and run tests.
 
 cmake_minimum_required (VERSION 3.5)
 if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.13.0")
@@ -157,10 +158,16 @@ if (MAY_USE_STATIC_RTL)
     tv_message_mp(STATUS "Link w/static RTL: ${TV_USE_STATIC_RTL}")
 endif()
 
+option(TV_BUILD_TESTS "Build and run tests" OFF)
+
 # Library
 
 add_subdirectory(source)
 
 # Examples
 
 add_subdirectory(examples)
+
+# Test
+
+add_subdirectory(test)

README.md

@@ -395,6 +395,17 @@ The following are new features not available in Borland's release of Turbo Visio
     void printMouseWheelState(ostream &, ushort wheelState);
     void printMouseEventFlags(ostream &, ushort eventFlags);
     ```
+* New class `TKey` which can be used to define new key combinations (e.g. `Shift+Alt+Up`) by specifying a key code and a mask of key modifiers:
+    ```c++
+    auto kbShiftAltUp = TKey(kbUp, kbShift | kbAltShift);
+    assert(kbCtrlA == TKey('A', kbCtrlShift));
+    assert(TKey(kbCtrlTab, kbShift) == TKey(kbTab, kbShift | kbCtrlShift));
+    // Create menu hotkeys.
+    new TMenuItem("~R~estart", cmRestart, TKey(kbDel, kbCtrlShift | kbAltShift), hcNoContext, "Ctrl-Alt-Del")
+    // Examine KeyDown events:
+    if (event.keyDown == TKey(kbEnter, kbShift))
+        doStuff();
+    ```
 
 ## Screenshots
 

include/tvision/menus.h

@@ -44,13 +44,13 @@ class TMenuItem
 
     TMenuItem( TStringView aName,
                ushort aCommand,
-               ushort aKeyCode,
+               TKey aKey,
                ushort aHelpCtx = hcNoContext,
                TStringView p = 0,
                TMenuItem *aNext = 0
              ) noexcept;
     TMenuItem( TStringView aName,
-               ushort aKeyCode,
+               TKey aKey,
                TMenu *aSubMenu,
                ushort aHelpCtx = hcNoContext,
                TMenuItem *aNext = 0
@@ -64,7 +64,7 @@ class TMenuItem
     const char *name;
     ushort command;
     Boolean disabled;
-    ushort keyCode;
+    TKey keyCode;
     ushort helpCtx;
     union
         {
@@ -93,7 +93,7 @@ class TSubMenu : public TMenuItem
 
 public:
 
-    TSubMenu( TStringView nm, ushort key, ushort helpCtx = hcNoContext ) noexcept;
+    TSubMenu( TStringView nm, TKey key, ushort helpCtx = hcNoContext ) noexcept;
 
 };
 
@@ -154,7 +154,7 @@ class TMenuView : public TView
     virtual ushort getHelpCtx();
     virtual TPalette& getPalette() const;
     virtual void handleEvent( TEvent& event );
-    TMenuItem *hotKey( ushort keyCode );
+    TMenuItem *hotKey( TKey key );
     TMenuView *newSubView( const TRect& bounds,
                            TMenu *aMenu,
                            TMenuView *aParentMenu
@@ -179,7 +179,7 @@ class TMenuView : public TView
     TMenuView *topMenu();
     Boolean updateMenu( TMenu *menu );
     void do_a_select( TEvent& );
-    TMenuItem *findHotKey( TMenuItem *p, ushort keyCode );
+    TMenuItem *findHotKey( TMenuItem *p, TKey key );
 
 private:
 
@@ -402,25 +402,25 @@ class TStatusItem
 public:
 
     TStatusItem( TStringView aText,
-                 ushort key,
+                 TKey aKey,
                  ushort cmd,
                  TStatusItem *aNext = 0
                 ) noexcept;
     ~TStatusItem();
 
     TStatusItem *next;
     char *text;
-    ushort keyCode;
+    TKey keyCode;
     ushort command;
 
 };
 
 inline TStatusItem::TStatusItem( TStringView aText,
-                                 ushort key,
+                                 TKey aKey,
                                  ushort cmd,
                                  TStatusItem *aNext
                                 ) noexcept :
-     next( aNext ), text( newStr(aText) ), keyCode( key ), command( cmd )
+     next( aNext ), text( newStr(aText) ), keyCode( aKey ), command( cmd )
 {
 }
 

include/tvision/system.h

@@ -72,7 +72,6 @@ const int meTripleClick = 0x10;
 
 #endif  // __EVENT_CODES
 
-
 #if defined( Uses_TEvent ) && !defined( __TEvent )
 #define __TEvent
 
@@ -203,14 +202,20 @@ struct KeyDownEvent
     char text[4];
     uchar textLength;
 
-    inline TStringView getText() const;
+    TStringView getText() const;
+    operator TKey() const;
 };
 
 inline TStringView KeyDownEvent::getText() const
 {
     return TStringView(text, textLength);
 }
 
+inline KeyDownEvent::operator TKey() const
+{
+    return TKey(keyCode, controlKeyState);
+}
+
 struct MessageEvent
 {
     ushort command;

include/tvision/tkeys.h

@@ -13,20 +13,40 @@
  *
  */
 
-#if !defined( __TKEYS_H )
-#define __TKEYS_H
+#if defined( Uses_TKeys ) && !defined( __TKeys )
+#define __TKeys
 
 #if defined( __FLAT__ ) && !defined( __WINDOWS_H )
 #include <tvision/compat/windows/windows.h>
 #endif
 
+//// Key codes
+//
+// The following constants can be used to define menu hotkeys and to
+// examine the 'keyCode' field of 'evKeyDown' event records.
+//
+// Not all key combinations can be used in all platforms. In particular:
+//
+// * In 16-bit mode, the 'control key' definitions cannot be used to define
+//   menu hotkeys, etc., which require scan codes. They are intended only
+//   to provide mnemonic names for the ASCII control codes.
+//
+// * In 16-bit mode, keystrokes corresponding to the 'additional extended
+//   key codes' are not reported.
+//
+// * Keystrokes corresponding to system shortcuts (e.g. Alt+F4 for 'close
+//   window' in graphical environments) are not reported either.
+//
+// * In Unix, support for key combinations varies among terminal emulators.
+//   Ctrl+H, Ctrl+I, Ctrl+J and Ctrl+M are not likely to work since they
+//   usually represent Backspace, Tab and Enter.
+//
+// These constants do not cover all possible combinations of the Shift, Ctrl
+// and Alt modifiers. For that purpose, see the TKey class below.
+
 const ushort
 
-//  Control keys
-//
-//  NOTE: these Control key definitions are intended only to provide
-//  mnemonic names for the ASCII control codes. In 16-bit mode, they
-//  cannot be used to define menu hotkeys, etc., which require scan codes.
+// Control keys
 
     kbCtrlA     = 0x0001,   kbCtrlB     = 0x0002,   kbCtrlC     = 0x0003,
     kbCtrlD     = 0x0004,   kbCtrlE     = 0x0005,   kbCtrlF     = 0x0006,
@@ -78,7 +98,7 @@ const ushort
     kbAlt0      = 0x8100,   kbAltMinus  = 0x8200,   kbAltEqual  = 0x8300,
     kbCtrlPgUp  = 0x8400,   kbNoKey     = 0x0000,
 
-// Additional extended key codes, usable in 32-bit mode
+// Additional extended key codes
 
     kbAltEsc    = 0x0100,   kbAltBack   = 0x0e00,   kbF11       = 0x8500,
     kbF12       = 0x8600,   kbShiftF11  = 0x8700,   kbShiftF12  = 0x8800,
@@ -90,18 +110,17 @@ const ushort
     kbAltIns    = 0xa200,   kbAltDel    = 0xa300,   kbAltTab    = 0xa500,
     kbAltEnter  = 0xa600,
 
-//  Keyboard state and shift masks
-
-// Changes for this version:
-//   In 32-bit mode, distinguishing between the right and left shift
-//   keys is not supported, and there is an additional new flag,
-//   kbEnhanced, which is set if the key pressed was an enhanced key
-//   (e.g. <insert> or <home>)
+//// Keyboard state and shift masks
+//
+// The following constants can be used when examining the 'controlKeyState'
+// field of an 'evKeyDown' event record.
 //
-//   In 16-bit mode, there are additional flags for the right and left
-//   Control and Alt keys, but this is not supported.  The flags are
-//   there for source compatibility with the 32-bit version which does
-//   support this.
+// Distinguishing between the left and right Shift keys is only supported in
+// 16-bit mode, while distinguishing between the left and right Ctrl and Alt
+// keys is only supported in 32-bit DPMI and on Windows.
+//
+// The kbScrollState, kbNumState, kbCapsState and kbEnhanced flags are only
+// reported on DOS and Windows.
 
 #if !defined( __FLAT__ )
     kbLeftShift   = 0x0001,
@@ -134,4 +153,64 @@ const ushort
     kbInsState    = 0x200;  // Ensure this doesn't overlap above values
 #endif
 
-#endif  // __TKEYS_H
+#endif // __TKeys
+
+#if !defined( __TKey )
+#define __TKey
+
+//// TKey
+//
+// This class provides the ability to define new key combinations by
+// specifying a key code and a mask of key modifiers. These key combinations
+// can then be used to define menu hotkeys and examine 'evKeyDown' event
+// records.
+//
+// The only modifiers taken into account are Shift, Ctrl and Alt, making no
+// distinction between the left and right key on platforms that support it.
+//
+// Given that some key code constants already imply the presence of a key
+// modifier, there are key combinations which can be defined in multiple
+// ways. TKey ensures equality between all of them. For example:
+//
+//     assert(kbCtrlA == TKey('A', kbCtrlShift));
+//     assert(TKey(kbCtrlTab, kbShift) == TKey(kbTab, kbShift | kbCtrlShift));
+//     assert(TKey(kbAltDel, kbCtrlShift) == TKey(kbCtrlDel, kbAltShift));
+
+class TKey
+{
+public:
+
+    constexpr TKey() noexcept;
+    TKey(ushort keyCode, ushort shiftState = 0) noexcept;
+
+    ushort code;
+    ushort mods;
+};
+
+inline constexpr TKey::TKey() noexcept :
+    code(0),
+    mods(0)
+{
+}
+
+inline constexpr Boolean operator==(TKey a, TKey b) noexcept
+{
+    return (a.code | (a.mods << 16)) == (b.code | (b.mods << 16));
+}
+
+inline constexpr Boolean operator!=(TKey a, TKey b) noexcept
+{
+    return !(a == b);
+}
+
+inline ipstream& operator >> ( ipstream& is, TKey& p )
+    { return is >> p.code >> p.mods; }
+inline ipstream& operator >> ( ipstream& is, TKey*& p )
+    { return is >> p->code >> p->mods; }
+
+inline opstream& operator << ( opstream& os, TKey& p )
+    { return os << p.code << p.mods; }
+inline opstream& operator << ( opstream& os, TKey* p )
+    { return os << p->code << p->mods; }
+
+#endif  // __TKey

include/tvision/tv.h

@@ -57,6 +57,7 @@
 
 #define Uses_EventCodes
 #define Uses_ViewCommands
+#define __INC_TKEYS_H
 #define __INC_STDDLG_H
 
 #if defined( Uses_TApplication )

source/tvision/makefile

@@ -208,7 +208,7 @@ TOBJS = pfxCOLORSEL.OBJ pfxDRIVERS.OBJ  pfxDRIVERS2.OBJ pfxEDITSTAT.OBJ \
         pfxTSTATICT.OBJ pfxTSTATUSL.OBJ pfxTSTRCOLL.OBJ pfxTSTRLIST.OBJ \
         pfxTVALIDAT.OBJ pfxTVIEW.OBJ    pfxTVTEXT1.OBJ  pfxTVTEXT2.OBJ  \
         pfxTWINDOW.OBJ  pfxTMENUPOP.OBJ pfxPOPUPMNU.OBJ pfxTSTRVIEW.OBJ \
-        pfxPRNTCNST.OBJ
+        pfxPRNTCNST.OBJ pfxTKEY.OBJ
 
 NOBJS = pfxNMBKGRND.OBJ pfxNMBUTTON.OBJ pfxNMCHDRDL.OBJ pfxNMCHKBOX.OBJ \
         pfxNMCLRSEL.OBJ pfxNMCLUSTR.OBJ pfxNMCOLLCT.OBJ pfxNMDIALOG.OBJ \

source/tvision/menu.cpp

@@ -23,7 +23,7 @@
 #include <string.h>
 #endif  // __STRING_H
 
-TSubMenu::TSubMenu( TStringView nm, ushort key, ushort helpCtx ) noexcept :
+TSubMenu::TSubMenu( TStringView nm, TKey key, ushort helpCtx ) noexcept :
     TMenuItem( nm, key, new TMenu, helpCtx )
 {
 }