In the previous installment of this series, Exploring the TypingBuddy Application (Part 9), you discovered how the Notification Area menu works in Typing Buddy. The main purpose of this menu is to control the timer used to determine when it’s time to stop typing. Given the purpose of TypingBuddy, keeping you from working so long as to cause repetitive stress injuries, the most important code is that used by the timer to display the stop message.
The TypeTimer control relies on the Timer_Tick() event handler to respond to Tick events once each second. The Timer_Tick() method must accomplish the following tasks:
- Update the counter.
- Check for an end of typing time condition.
- Choose a message.
- Ensure the message falls within the required parameters for display.
- Display the message on screen.
With these criteria in mind, it’s time to look at the method code. The following code shows how the Timer_Tick() method performs its assigned tasks.
Let’s start with the simple decision. Most of the time, the code will decrement TimeLeft and find that it still isn’t 0. When this condition occurs, the code updates the Time Left (in Seconds) field of frmMain to display the new typing time left value. In addition, you might remember that the the user can also see the amount of time left by hovering the mouse over the icon in the Notification Area. In order to accomplish this task, the code updates the ThisNotifyIcon.Text property value.
Of course, the alternative to updating the timer is to display a message. The Selection variable contains the number of the message to display. It begins with a value of -1 to indicate there is no message to display. When the user has configured custom messages, the code chooses a random message number from that collection and places it in Selection. However, the selection process must consider whether the selected message is only usable on a specific date. When this occurs, the code calls VerifySelection() with the list of available messages and the current selection from that list. Don’t worry about the inner workings of this method for now; you’ll see it in operation later.
When the user hasn’t configured any custom messages, Selection remains at -1 and the application displays the standard message that’s provided as part of the frmMessage configuration. The only decision left to make at this point is which constructor to call. When the user wants to display an icon, the code passes the value of chkShowIcon.Checked to the constructor. Otherwise, all it passes is the amount of resting time that the message should use.
Creating the message box when working with custom messages becomes a little more complex because the code must now decide whether the user wants the message title displayed or not (along with the decision about displaying an icon). When the user wants to display both the title and a custom message, the code uses constructors that pass along Settings.MessageList[Selection].Title and Settings.MessageList[Selection].MessageText; otherwise, the code simply passes the message text to the constructor.
Now that the application has a message box ready to display, it’s time to reset the count and stop the timer. The user may want to hear a sound when the message displays. To accommodate this need, the code looks at chkPlaySound.Checked. When this property is true, it then checks for a standard or custom message and plays the appropriate sound. Note that when the custom message has TBMessages.SystemSoundList.None selected, the application doesn’t play a sound even when chkPlaySound.Checked is true.
Everything is ready to display the message to the end user. The user either waits for the rest time counter to count down or clicks Quit to exit TypingBuddy. When the user waits for the rest period to end and clicks Continue, the code restarts the timer, which starts a new typing cycle. Otherwise, the application ends.
These are the basics of how the timer handling works. However, there is another issue to consider, verifying that the message is within the correct date span. The VerifySelection() method handles this requirement as shown here.
The code begins by verifying that the date is within correct time span. However, you don’t want to compare years, just the month and day, so the code relies on a special method, DateCompare(), to perform this task. You’ll see how DateCompare() works in a few moments, so don’t worry about it for now. All you really need to know is that DateCompare() returns -1 when the date supplied as part of the custom message is less than the current date, 0 when the month and day are precisely the same as the current date, and 1 when the custom message date is greater than the current date. When the selected message dates fall within the current date, then the code returns the current selection.
There are going to be times when the custom message dates won’t include the current date. When that happens, the application begins with the current message and looks at each message in the list until it gets to the end of the list looking for a message that either doesn’t have the dates set (which means that the reader would like to see the message at any time) or the current date falls within the message date. The application uses a simple for loop to perform the task.
It could happen that none of the custom messages starting with the current message to the end of the list are useable. In this case, the code starts looking for a useable message from the beginning of the list to the original selected message location. The criteria are the same—the code looks for a message that has no dates set or one that has a range that includes the current date.
The application has reviewed the entire list of custom messages at this point. It could happen that the application gets to the end of the list and still doesn’t find a useable message. When that situation occurs, VerifySelection() returns -1. If you review the Timer_Tick() code, you’ll see that this condition automatically selects the default message, even if the user has created custom messages.
The .NET Framework doesn’t provide an easy method for comparing just the month and the day of two dates. You usually compare the entire date or a specific date element. In order to perform the correct level of comparison, the example uses the DateCompare() method shown here.
As you can see, this method first compares the month values. When the two months are precisely equal, it then compares the day values. When the two days are also equal, the method returns a value of 0. Otherwise, the method returns either -1 or 1 depending on whether the custom message date is greater or less than the current date.
Now you have the code for the entire application except for the event handlers in frmMain itself. Next week you’ll receive this last bit of code. In the meantime, let me know if you have any questions at John@JohnMuellerBooks.com. You can see the next post in this series at Exploring the TypingBuddy Application (Part 11).