Improved names related to timed events

README.md

@@ -416,7 +416,7 @@ The following are new features not available in Borland's release of Turbo Visio
     if (event.keyDown == TKey(kbEnter, kbShift))
         doStuff();
     ```
-* New methods which allow the usage of timed events:
+* New methods which allow using timed events:
     ```c++
     TTimerId TView::setTimer(uint timeoutMs, int periodMs = -1);
     void TView::killTimer(TTimerId id);
@@ -425,9 +425,9 @@ The following are new features not available in Borland's release of Turbo Visio
 
     If `periodMs` is negative, the timer only times out a single time and is cleaned up automatically. Otherwise, it will keep timing out periodically until `killTimer` is invoked.
 
-    When a timer times out, an `evBroadcast` event with the command `cmTimeout` is emitted, and `message.infoPtr` is set to the id of the timed-out timer.
+    When a timer times out, an `evBroadcast` event with the command `cmTimerExpired` is emitted, and `message.infoPtr` is set to the `TTimerId` of the expired timer.
 
-    Timeout events are generated in `TProgram::idle()`, that is, only if there are no keyboard or mouse events available.
+    Timeout events are generated in `TProgram::idle()`. Therefore, they are only processed when no keyboard or mouse events are available.
 
 ## Screenshots
 
@@ -855,7 +855,7 @@ Colors can be specified using any of the following formats:
 * `xterm-256color` palette indices (8-bit).
 * The *terminal default* color. This is the color used by terminal emulators when no display attributes (bold, color...) are enabled (usually white for foreground and black for background).
 
-Although Turbo Vision applications are likely to be ran in a terminal emulator, the API makes no assumptions about the display device. That is, the complexity of dealing with terminal emulators is hidden from the programmer and managed by Turbo Vision itself.
+Although Turbo Vision applications are likely to be ran in a terminal emulator, the API makes no assumptions about the display device. That is to say, the complexity of dealing with terminal emulators is hidden from the programmer and managed by Turbo Vision itself.
 
 For example: color support varies among terminals. If the programmer uses a color format not supported by the terminal emulator, Turbo Vision will quantize it to what the terminal can display. The following images represent the quantization of a 24-bit RGB picture to 256, 16 and 8 color palettes:
 
@@ -1180,7 +1180,7 @@ The types defined previously represent concepts that are also important when dev
 | Color | A 4-bit number. | `struct TColorDesired`. |
 | Attribute Pair | `ushort`. An attribute in each byte. | `struct TAttrPair`. |
 
-One of this project's key principles is that the API should be used in the same way both in Borland C++ and modern platforms, that is, without the need for `#ifdef`s. Another principle is that legacy code should compile out-of-the-box, and adapting it to the new features should increase complexity as little as possible.
+One of this project's key principles is that the API should be used in the same way both in Borland C++ and modern platforms, that is to say, without the need for `#ifdef`s. Another principle is that legacy code should compile out-of-the-box, and adapting it to the new features should increase complexity as little as possible.
 
 Backward-compatibility is accomplished in the following way:
 
@@ -1233,4 +1233,4 @@ The code above still works just like it did originally. It's only non-BIOS color
 +    TAttrPair cFrame, cTitle;
 ```
 
-Nothing prevents you from using different variables for palette indices and color attributes, which is what should actually be done. The point of backward-compatibility is the ability to support new features without changing the program's logic, that is, minimizing the risk of increasing code complexity or introducing bugs.
+Nothing prevents you from using different variables for palette indices and color attributes, which is what should actually be done. The point of backward-compatibility is the ability to support new features without changing the program's logic, that is to say, minimizing the risk of increasing code complexity or introducing bugs.

include/tvision/dialogs.h

@@ -300,7 +300,7 @@ class TButton : public TView
     void pressButton( TEvent& );
     TRect getActiveRect();
 
-    enum { animationDuration = 100 };
+    enum { animationDurationMs = 100 };
     TTimerId animationTimer;
 
     static const char * _NEAR shadows;

include/tvision/system.h

@@ -362,8 +362,8 @@ class TTimerQueue
 
     TTimerId setTimer(uint32_t timeoutMs, int32_t periodMs = -1);
     void killTimer(TTimerId id);
-    void collectTimeouts(void (&func)(TTimerId, void *), void *args);
-    int32_t timeUntilTimeout();
+    void collectExpiredTimers(void (&func)(TTimerId, void *), void *args);
+    int32_t timeUntilNextTimeout();
 
 private:
 

include/tvision/views.h

@@ -175,7 +175,7 @@ const ushort
     cmReceivedFocus     = 50,
     cmReleasedFocus     = 51,
     cmCommandSetChanged = 52,
-    cmTimeout           = 58,
+    cmTimerExpired      = 58,
 
 // TScrollBar messages
 

source/tvision/tbutton.cpp

@@ -228,7 +228,7 @@ void TButton::handleEvent( TEvent& event )
                 drawState( True );
                 if( animationTimer != 0 )
                     press();
-                animationTimer = setTimer( animationDuration );
+                animationTimer = setTimer( animationDurationMs );
                 clearEvent( event );
                 }
             break;
@@ -258,7 +258,7 @@ void TButton::handleEvent( TEvent& event )
                     drawView();
                     break;
 
-                case cmTimeout:
+                case cmTimerExpired:
                     if( animationTimer != 0 && event.message.infoPtr == animationTimer )
                         {
                         animationTimer = 0;

source/tvision/tprogram.cpp

@@ -100,7 +100,7 @@ Boolean TProgram::canMoveFocus()
 
 int TProgram::eventWaitTimeout()
 {
-    int timerTimeoutMs = min(timerQueue.timeUntilTimeout(), (int32_t) INT_MAX);
+    int timerTimeoutMs = min(timerQueue.timeUntilNextTimeout(), (int32_t) INT_MAX);
     if (timerTimeoutMs < 0)
         return eventTimeoutMs;
     return min(eventTimeoutMs, timerTimeoutMs);
@@ -207,9 +207,9 @@ void TProgram::handleEvent( TEvent& event )
         }
 }
 
-static void doHandleTimeout( TTimerId id, void *self )
+static void handleTimeout( TTimerId id, void *self )
 {
-    message( (TProgram *) self, evBroadcast, cmTimeout, id );
+    message( (TProgram *) self, evBroadcast, cmTimerExpired, id );
 }
 
 void TProgram::idle()
@@ -223,7 +223,7 @@ void TProgram::idle()
         commandSetChanged = False;
         }
 
-    timerQueue.collectTimeouts(doHandleTimeout, this);
+    timerQueue.collectExpiredTimers( handleTimeout, this );
 }
 
 TDeskTop *TProgram::initDeskTop( TRect r )

source/tvision/ttimerqu.cpp

@@ -82,7 +82,7 @@ static TTimePoint calcNextExpiresAt(TTimePoint expiresAt, TTimePoint now, int32_
     return (1 + (now - expiresAt + period)/period)*period + expiresAt - period;
 }
 
-void TTimerQueue::collectTimeouts(void (&func)(TTimerId, void *), void *args)
+void TTimerQueue::collectExpiredTimers(void (&func)(TTimerId, void *), void *args)
 {
     if (first == 0)
         return;
@@ -123,7 +123,7 @@ void TTimerQueue::collectTimeouts(void (&func)(TTimerId, void *), void *args)
     }
 }
 
-int32_t TTimerQueue::timeUntilTimeout()
+int32_t TTimerQueue::timeUntilNextTimeout()
 {
     if (first == 0)
         return -1;

test/tvision/ttimerqu.test.cpp

@@ -17,20 +17,20 @@ static void handleTimeout(TTimerId, void *)
     ++timeouts;
 }
 
-TEST(TTimerQueue, EmptyQueueShouldReturnNoTimeouts)
+TEST(TTimerQueue, EmptyQueueShouldReturnNoExpiredTimers)
 {
     currentTime = 0;
     TTimerQueue timerQueue(mockCurrentTime);
 
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, -1);
 
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 0);
 }
 
-TEST(TTimerQueue, ShouldCollectExpiredTimeout)
+TEST(TTimerQueue, ShouldCollectExpiredTimers)
 {
     currentTime = 0;
     TTimerQueue timerQueue(mockCurrentTime);
@@ -39,7 +39,7 @@ TEST(TTimerQueue, ShouldCollectExpiredTimeout)
 
     currentTime = 1000;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 1);
 }
 
@@ -51,11 +51,11 @@ TEST(TTimerQueue, ShouldMeasureNextTimeoutProperly)
     timerQueue.setTimer(1000);
 
     currentTime = 1;
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 999);
 
     currentTime = 1001;
-    nextTimeout = timerQueue.timeUntilTimeout();
+    nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 0);
 }
 
@@ -68,9 +68,9 @@ TEST(TTimerQueue, ShouldUnqueueSingleShotTimer)
 
     currentTime = 1000;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
 
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, -1);
 }
 
@@ -81,24 +81,24 @@ TEST(TTimerQueue, ShouldRequeuePeriodicTimer)
 
     timerQueue.setTimer(1000, 500);
 
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 1000);
 
     currentTime = 1000;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 1);
 
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 0);
 
-    nextTimeout = timerQueue.timeUntilTimeout();
+    nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 500);
 
     currentTime = 1500;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 1);
 }
 
@@ -112,10 +112,10 @@ TEST(TTimerQueue, ShouldCollectOnlyExpiredTimeouts)
 
     currentTime = 1000;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 1);
 
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 500);
 }
 
@@ -128,7 +128,7 @@ TEST(TTimerQueue, ShouldMeasureNextTimeoutProperlyWithSeveralTimers)
     timerQueue.setTimer(1000);
 
     currentTime = 1;
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 999);
 }
 
@@ -142,7 +142,7 @@ TEST(TTimerQueue, ShouldCollectSeveralExpiredTimers)
 
     currentTime = 1500;
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 2);
 }
 
@@ -157,7 +157,7 @@ TEST(TTimerQueue, ShouldRemoveTimer)
     timerQueue.killTimer(id2);
 
     currentTime = 1;
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 1499);
 }
 
@@ -175,7 +175,7 @@ TEST(TTimerQueue, RemovingInvalidTimersShouldNotProduceErrors)
     timerQueue.killTimer((TTimerId) 3);
 
     currentTime = 1;
-    int32_t nextTimeout = timerQueue.timeUntilTimeout();
+    int32_t nextTimeout = timerQueue.timeUntilNextTimeout();
     EXPECT_EQ(nextTimeout, 1499);
 }
 
@@ -189,19 +189,19 @@ TEST(TTimerQueue, ShouldHandleZeroTimedTimersProperly)
     timerQueue.setTimer(0, 0);
 
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 3);
 
     timeouts = 0;
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
     EXPECT_EQ(timeouts, 3);
 }
 
 static void nestedHandleTimeout(TTimerId, void *args)
 {
     ++timeouts;
     currentTime = 1500;
-    (*(TTimerQueue *) args).collectTimeouts(handleTimeout, nullptr);
+    (*(TTimerQueue *) args).collectExpiredTimers(handleTimeout, nullptr);
 }
 
 TEST(TTimerQueue, ShouldCollectTimeoutsWithNestedInvocation)
@@ -214,7 +214,7 @@ TEST(TTimerQueue, ShouldCollectTimeoutsWithNestedInvocation)
 
     currentTime = 1000;
     timeouts = 0;
-    timerQueue.collectTimeouts(nestedHandleTimeout, &timerQueue);
+    timerQueue.collectExpiredTimers(nestedHandleTimeout, &timerQueue);
     EXPECT_EQ(timeouts, 3);
 }
 
@@ -223,7 +223,7 @@ TEST(TTimerQueue, ShouldNotRequestCurrentTimeIfThereAreNoTimers)
     currentTimeRequests = 0;
 
     TTimerQueue timerQueue(mockCurrentTime);
-    timerQueue.collectTimeouts(handleTimeout, nullptr);
+    timerQueue.collectExpiredTimers(handleTimeout, nullptr);
 
     EXPECT_EQ(currentTimeRequests, 0);
 }