METclk by Josef W. Segur jsegur@westelcom.com Contents: 1. Introduction 2. Installation 3. Event Timer Window 4. The Menu 5. Events Dialog Box 6. Initialization File 7. Multiple Instances 8. Date and Time Details 9. Window Size 10. Speed 11. Credits 12. Time Zones 13. History ****** 1. Introduction ****** METclk puts your choice of digital timers for events on your screen in Windows 95. Each event timer window includes a short event description followed by the days, hours, minutes, and seconds between the current time and the event. I developed METclk (I say "met-clock") to display the time relative to a NASA Space Shuttle launch, known as Mission Elapsed Time (MET) after the launch. METclk allows you to enter a list of up to 49 events from which you can quickly select one for display. Multiple event timer displays can be created by running multiple instances of METclk. The program can be used to show time before or after any event in the years 1971 through 2035. The user-defined event list, font, font size, character color, background color, and window position are saved in an 'ini' file. METclk is freeware. If you decide to use the program, the following applies: This software is offered for use as is, and no warranty is stated or implied. The author is not responsible for any loss of data, damage to hardware nor any resulting loss of time or revenue resulting from the use of this program. Like all software, this program is utilized entirely at the user's risk. This was my first Windows program, and it has only been tested on my personal system (Pentium, original release US English Windows 95). I will appreciate any positive or negative comments, and given enough information I'll try to fix problems. ****** 2. Installation ****** There's no installation routine. Just put METclk.exe in any folder you choose. The first time you run it, METclk.ini will normally be created in the same folder (the name and/or location can be changed; see Section 6 below). You may want to put METclk.txt (the file you're reading) in the same folder for easy reference. Finally, create one or more shortcuts if you want. Uninstallation is just as easy; METclk makes no changes to anything other than its own ini file. Just delete METclk.exe, the ini file(s), METclk.txt, and any shortcuts. ****** 3. Event Timer Window ****** When you first run METclk, its event timer window will appear at the top left corner of the desktop. Blue-green characters in the system font on a black background will show something like: Y2k -761/19:28:37 This is a sample event at the beginning of the year 2000 in the Eastern Time (US & Canada) time zone. 'Y2k' is the title I chose, the minus sign indicates the event is in the future, and 761 is the number of days(*) until the event. The slash is the default date separator character. Then follow the hours, minutes, and seconds with the default time separator character inserted. The seconds field will be counting down. If you change the date or time separator character using the Date/Time Control panel applet your choices will appear instead of the default separators. (*) METclk actually deals with seconds between current time and the event, but divides it out into minutes, hours, and days for ease of reading. The days field only changes at midnight for an event timed to occur at midnight. Even in that case, if the event will occur in daylight time and your current time is standard (or vice versa) there will be a one hour offset. Since the event timer window has no title bar, operations are somewhat nonstandard: --- Any part of the window supports left button drag to move the window. --- Any part of the window supports a right-click to activate the menu. --- At the left end of the window there's an invisible spinner control; once you've added additional events you can left click the top left corner to move up the list or the bottom left corner to move down. The keyboard arrow keys work like the spinner; the up or left arrow moves up the list, while the down or right arrow moves down the list. For these actions the list is treated as circular, and there is automatic repeat if you hold down the mouse button or key. The repeat rate with the mouse is the normal 1 second display update cycle, so it is easy to stop where you want. --- A left double click anyplace to the right of the spinner area in the window will minimize the window. (The spinner width is just half the height of the window.) ****** 4. The Menu ****** METclk uses a single menu with the program functions added to the system functions. The menu can be activated by right clicking either the main window or the icon/text on the task bar, or by keying ALT+Spacebar when the event timer window is active (has the keyboard focus). The following selections are in the menu: Restore (only usable when the window is minimized) Move (only usable when the window is normal size) The standard system menu Move routine is preceded by forcing the window to center on the mouse cursor location. If you happen to lose the window when changing font size or your desktop resolution, Move will bring it back within the desktop area. Minimize (only usable when the window is normal size) Close As usual, ALT+F4 is the keyboard shortcut. Always on Top When this is checked, the window will remain above all non-topmost windows. Events... This activates a dialog where you can add, modify, or remove event list items. See Section 5 for full details. Font... This activates the Windows 95 common dialog for choosing a display font. Character Color... This activates the Windows 95 common dialog for choosing a character color. Background Color... This activates the Windows 95 common dialog for choosing a background color. The two color dialogs share a set of 16 custom colors which is saved in the ini file. About... This activates a message box containing minimal details about the program. ****** 5. Events Dialog ****** The upper portion of the dialog box has a list where you select an event name to work with, and five buttons defining operations with the event name list. Below that is a set of controls where you see, and can modify, the date and time of the selected event. --- As is usual for dialogs, changes don't affect the main program until after you exit the dialog. There are three ways to exit and make the changes effective: 1. Left double click on an event name. 2. Click the 'OK' button (or press the spacebar after Tabbing to OK). 3. Press the 'Enter' key. There are four ways to exit without having the changes take effect: 1. Click the 'Cancel' button (or press the spacebar after Tabbing to Cancel). 2. lick the X close button at the right end of the title bar. 3. Press the 'Esc' key. 4. Press ALT+F4. --- The 'Add' button creates a new event list item with a date/time of Jan. 1, 2006 at 12:00:00 am in your local time zone, and activates a single line edit control where you enter the name of the new event. --- The 'Edit' button activates the single line edit control, preset with the existing name of the selected event. An event name may be up to 50 characters long, though the main window will show at most the first 10 characters. If you want to use a long name but show fewer than 10 characters, a vertical line character (SHIFT+Backslash) marks the end of the display portion. While the edit control is active, most of the other dialog controls are disabled. You must close the edit control by pressing 'Enter' or 'Esc' to reactivate the other controls. 'Enter' puts the edit control contents in the event list, 'Esc' cancels the edit. --- The 'Remove' button deletes an event, but only if the deletion will leave at least one event in the list. --- The 'Move Up' and 'Move Down' buttons reorder the list by moving the selected name in the indicated direction. --- Each of the controls in the date/time area is a single line list box with a 'spinner' to select from a valid range of values. The values are generally arranged so the latest time or date value is at the top of the list. See Section 8 for additional details. ****** 6. Initialization File ****** When METclk is started, it attempts to read an initialization file. If it can't, it creates one with a single sample event. When you make changes using the Events, Font, or Color dialogs, your choices are saved to the initialization file. Your selection of which event to display is updated each time you change it. Finally, when the program closes the window position is saved. The default initialization file is METclk.ini in the program's working directory. To use a different initialization file simply supply the file name as a command line parameter. METclk checks that the command line parameter contains ".ini" (case-insensitive), then appends it to the working directory path to form a fully qualified name. If the result is acceptable to the file system, the file will be read or created. If not, you'll get a message box saying the ini file couldn't be accessed and your preferences won't be saved. METclk will work without problems in this mode. Please note that the program supplies the path. Your command line parameter should only have the file name and extension. Here's an example of a complete command line which I use in the 'Target' field of a shortcut: C:\Programs\Utils\METCLK\METclk.exe METCLK2.INI If you need to change the path to the initialization file, put the path in the 'Start in:' field of the shortcut properties. This changes the working directory, so it's effective with either the default file or a command line parameter. ****** 7. Multiple Instances ****** If you want to display two or more events simultaneously, you'll need to run two or more instances of METclk. This is quite practical since the program doesn't use a large amount of system resources, but there are some initialization file issues to be kept in mind. If you launch multiple instances of METclk using the same initialization file, remember that each instance only reads the file once, at startup. After that each instance operates independently using internal data, but changes to any instance are written to the initialization file. The file could easily have the event list from one instance and the font from another, for example. If you want to make the file reflect the full state of a particular instance, just call up each of the dialogs from that instance and click OK (or press ENTER). With separate initialization files, the only problem is remembering what's in which file. Carefully chosen shortcut names should help. ****** 8. Date and Time Details ****** An unreal month and day combination is treated as reaching into the next month, for example Feb 30 is equivalent to Mar 1 in a leap year or Mar 2 in a normal year. The program internally uses the 24 hour format (hours 00 through 23). The a/p control is ignored except for these cases: 12 am is converted to hour 00. 01 pm through 11 pm are converted to hours 13 through 23. The Time Zone list is based on time zone descriptions supplied with the original release of Windows 95, but has been updated in 1999 with information from ftp://elsie.nci.nih.gov/pub datasets. You'll probably use your local zone most often, but if the time of an event is specified in a different zone you can select that zone. As noted above, when you add an event the program tries to preset your local time zone. The Win32 GetTimeZoneInformation function is used to retrieve the registry data for this purpose. If that function fails (the registry data is incomplete), then the control preset will be my time zone: (GMT-05:00) Eastern Time (US & Canada) If GetTimeZoneInformation succeeds, METclk compares the offset from GMT, date and time of transition from standard to daylight time, and date and time of transition from daylight to standard time to its internal data for the listed time zones, and selects the first match as the preset. If there's no exact match, a new zone name is added to the list and becomes the preset. The name is "Local", followed by the basic offset from GMT. If I make a minor change to my time zone, for instance, the selection shows: Local (GMT-05:00) For time zones which use daylight savings during the summer, the program does treat event times as daylight or standard according to the defined transition date/times. There are some minor difficulties with event times close to the transitions. The spring transition to daylight time involves a forward jump of one hour in local time; METclk treats an event time selection in the non-existant hour as standard time. The autumn transition is more difficult, since it involves a repeat hour. To avoid adding a special dialog, the program just treats entries in that hour as daylight time. To enter standard time, you simply choose an alternate time zone which does not use daylight time. In most cases a standard only zone already existed, but the following zones were added: (GMT+03:30) std (GMT+01:00) std (GMT-01:00) std (GMT-02:00) std (GMT-03:30) std (GMT-08:00) std (GMT-09:00) std (GMT-12:00) std All the time zones are listed with their transition date/times in Section 12. ****** 9. Window Size ****** The program's window is sized at startup, when you change the font, displayed event, or time separator character, and when the days count for the displayed event changes. The size is figured with one blank before the event name, one blank before the date/time, and one or two blanks at the end (one for regular fonts, two for italic fonts). Also, the width is set for the widest numerical characters in the hours, minutes, and seconds field; a font with narrow 1's will have a lot of extra space at the right end at 11:11:11. ****** 10. Speed ****** The contents of the window are completely rewritten when you make any change, and also when the minutes field changes. Between minute changes, only the seconds field is updated. This significantly reduces the average amount of processor time needed for display updating, though the time saved is probably negligible except when you're using an extra large font. The limited update also nearly eliminates a flickering problem with large fonts. Unfortunately, it also shows a minor defect with some italic fonts. When you drag another window over a METclk window, you may lose the top right corner of an italic character until the next minute change; Windows apparently uses the position of the bottom of the character to determine where to begin its update. The update region I use for the seconds field actually extends 1 pixel back into the base region of the preceding time separator character to avoid clipping that character. It's a very small defect but in case someone finds it obnoxious, the program can be forced to do a complete window rewrite each second by adding the following line in the initialization file's [Choice] section: Slow=1 For reference, here are some processor time usage figures running METclk on my 120 MHz Pentium system with a Diamond Stealth 2MB DRAM display adaptor. When minimized, the program releases its timer and uses no processor time. With METclk active but covered by another window, it uses about 0.16% of the processor time. A visible display using the Arial font at 16 point size uses about 0.18% of the processor time. At 60 point size, the same display uses about 0.4% of the processor time normally, but with the Slow=1 initialization, it uses about 1.5% of the processor time. ****** 11. Credits ****** METclk is programmed in the C language and uses functions from Micosoft's C runtime and Win 32 SDK. It was compiled with Microsoft Visual C++ version 4.0, standard edition. Large portions of the program are adapted from code on the CD-ROM accompanying "Programming Windows 95" (c) 1996 by Charles Petzold. I greatly appreciate his explicit permission on page 24 of the book to use the CD-ROM code in this fashion. In addition, the book's clear exposition of the Windows API has been invaluable. ****** 12. Time Zones ****** dlt to std std to dlt Description mon week day h mon week day h ---------------------------------------------- --- ---- --- - --- ---- --- - (GMT+12:00) Kamchatka, Marshall Is. standard only (GMT+12:00) Wellington, Auckland Mar 3rd Sun 2 Oct 1st Sun 2 (GMT+11:00) Magadan, Solomon Is., New Caledonia standard only (GMT+10:00) Guam, Port Moresby, Vladivostok standard only (GMT+10:00) Hobart Mar last Sun 2 Oct 1st Sun 2 (GMT+10:00) Brisbane, Melbourne, Sydney Mar last Sun 2 Oct last Sun 2 (GMT+09:30) Darwin standard only (GMT+09:30) Adelaide Mar last Sun 2 Oct last Sun 2 (GMT+09:00) Tokyo, Osaka, Sapporo, Seoul, Yakutsk standard only (GMT+08:00) China, Perth, Singapore, Taipei standard only (GMT+07:00) Bangkok, Jakarta, Hanoi standard only (GMT+06:00) Almaty, Dhaka standard only (GMT+05:30) Bombay, Calcutta, Madras, New Delhi... standard only (GMT+05:00) Islamabad, Karachi, Ekaterinburg... standard only (GMT+04:30) Kabul standard only (GMT+04:00) Abu Dhabi, Muscat, Tbilisi, Kaz... standard only (GMT+03:30) std standard only (GMT+03:00) Baghdad, Kuwait, Nairobi, Riyadh standard only (GMT+03:00) Moscow, St. Petersburg Oct last Sun 2 Mar last Sun 2 (GMT+02:00) Harare, Pretoria standard only (GMT+02:00) Cairo Sep last Thu 23 Apr 4th Fri 0 (GMT+02:00) Eastern Europe, Istanbul Oct last Sun 1 Mar last Sun 1 (GMT+01:00) std standard only (GMT+01:00) Europe Oct last Sun 1 Mar last Sun 1 (GMT) Monrovia, Casablanca standard only (GMT) Greenwich Mean Time; Dublin, Edin... Oct last Sun 1 Mar last Sun 1 (GMT-01:00) std standard only (GMT-01:00) Azores, Cape Verde Is. Oct last Sun 1 Mar last Sun 1 (GMT-02:00) std standard only (GMT-02:00) Mid-Atlantic Oct last Sun 1 Mar last Sun 1 (GMT-03:00) Buenos Aires, Georgetown standard only (GMT-03:00) Brasilia Feb 2nd Sun 0 Oct 2nd Sun 0 (GMT-03:30) std standard only (GMT-03:30) Newfoundland Oct last Sun 2 Apr 1st Sun 2 (GMT-04:00) Caracas, La Paz standard only (GMT-04:00) Atlantic Time (Canada) Oct last Sun 2 Apr 1st Sun 2 (GMT-05:00) Bogota, Lima, Indiana (East) standard only (GMT-05:00) Eastern Time (US & Canada) Oct last Sun 2 Apr 1st Sun 2 (GMT-06:00) Saskatchewan standard only (GMT-06:00) Central Time (North America) Oct last Sun 2 Apr 1st Sun 2 (GMT-07:00) Arizona standard only (GMT-07:00) Mountain Time (North America) Oct last Sun 2 Apr 1st Sun 2 (GMT-08:00) std standard only (GMT-08:00) Pacific Time (North America) Oct last Sun 2 Apr 1st Sun 2 (GMT-09:00) std standard only (GMT-09:00) Alaska Oct last Sun 2 Apr 1st Sun 2 (GMT-10:00) Hawaii standard only (GMT-11:00) Midway Island, Samoa standard only (GMT-12:00) std standard only ****** 13. History ****** METclk 1.1 3 July, 2006 Increased size of the date and time setting controls on the Events dialog to allow for larger scroll bar size settings than I use. Changed new event creation from 1998 to 2006 so less adjustment is needed. METclk 1.0 13 September, 1999 Fixed: The date and time setting controls on the Events dialog were not showing when some unusual Windows desktop settings were used. METclk 0.9 25 June, 1999 Updated the time zone information based on ftp://elsie.nci.nih.gov/pub datasets. Revised the menu handling code to recognize changes made to METclk's window state by 3rd party utilities. METclk 0.8 25 December, 1997 First public release.