---------- Pundit ---------- -- INTRODUCTION -- Pundit is a Microsoft Windows 3.0 program that pops up a Window to display a quotation, fortune, or other basically useless (but hopefully entertaining) saying. The Window remains on the screen for a given amount of time then disappears, to return with a new quote later. The amount of time that the Window remains on the screen and the amount of time that it stays hidden may both be set by the user. This program has two purposes: 1) to be a (mildly) amusing diversion and excuse for why you couldn't get that Excel spreadsheet done on time 2) to provide budding Windows programmers with an example of some of the things that can be done with Windows 3.0 This program is "shareware"; it is copyrighted, but is being made available to the outside world by the author. Feel free to distribute this program to your friends, but please stay within the following restrictions: 1) No charge may be made for distribution of this program beyond the nominal fees charged by organizations that are in the "business" of distributing "shareware". 2) The entire package (executable, source, icon, documentation, etc.) MUST be distributed together. It is not fair for you to benefit from having the source code if you won't share it. 3) No modifications may be made to the distributed program (especially the copyright notice). You may make changes in your own copy (such as changing the quotations) so long as you DO NOT change the copyright notice and you distribute the original in exactly the same condition in which you received it. If you like this program, a donation of $5 (five dollars) would be appreciated --- this will not make me rich, but it will encourage me to release more programs (with source). Send any donations to: Jeff Bienstadt 18092 Muirwoods Court Fountain Valley, CA 92708 If you have any questions or comments about this program, I would love to hear from you (this includes Windows Wizards with comments about how to improve it). I can be reached at the above address or on CompuServe at 72200,3477. -- Files in the Distribution -- The distribution contains the following files: PUNDIT.EXE The executable program PUNDIT.TXT This file PUNDIT.H Header file containing important constants PUNDIT.C The C source code PUNDIT.RC The resource file (the quotations are here) PUNDIT.ICO The Icon PUNDIT.MAK The make file (for NMAKE) PUNDIT.DEF The Linker Definition File Please be sure that you have all of these files in your distribution -- USER'S GUIDE -- Pundit is very easy to use. Run it by any of the "normal" Windows methods of launching a program. When Pundit starts up, it will place a Window near the upper-left corner of your screen, and display a quotation in the Window. After about 5 seconds, the Window will vanish. About 20 seconds later, the Window will reappear, displaying a new quotation, and the cycle will start over again. Pundit may not be minimized or maximized; you may move the Window around the screen, and you may resize it, but you cannot make an icon of it. While the Window is displayed it may be resized and/or moved, and the Menu is available. -- The Menu -- Besides the "system" menu (for sizing, etc.) Pundit contains one menu. From this menu you may change the settings that Pundit uses, see an "About" box, or exit Pundit. Once the menu is activated, Pundit will suspend counting seconds, and will stay active while you work. (It would be somewhat disconcerting to have the Window disappear while you are deciding what to do.) - Settings... - Choosing the "Settings..." memu item brings up a dialog box which will allow you to change the amount of time that the Window is displayed and hidden. There are two horizontal scroll bars -- one for each of the two time settings -- and the current time setting for each is displayed in a box to the right of the scroll bar. Moving the scroll bar to the right will increase the amount of time, moving it to the left will decrease the amount of time. The amount of time that the Window is visible ranges from 1 second to 60 seconds (1 minute). The amount of time that the Window is hidden ranges from 1 second to 3600 seconds (1 hour). There are also three buttons -- "OK", "CANCEL", and "Save Settings" -- that determine what happens to the settings you change. Pressing the "OK" button will make Pundit act on your changes for now, but will NOT save them; the next time you run Pundit the settings will revert to what they were before you changed the settings. Pressing the "CANCEL" button will ignore the changes you make and Pundit will continue on as before. Pressing the "Save Settings" button will save your settings choices in the WIN.INI file. You will also be asked if you want to save the current position and size of the Window (in case you moved or resized it). Pressing the "Yes" button will save the current size/position as well as the new timer values. Pressing the "No" button will save the new timer values, but not the size/position. Pressing the "Save Settings" button will NOT exit the dialog box; you will need to press the "OK" or "CANCEL" buttons to return Pundit to its normal operation. - About Pundit... - Choosing the "About Pundit..." menu item will bring up a basic "About" dialog box which just tells you what program it is and contains my copyright notice. - Exit - Choosing the "Exit" menu item will terminate Pundit. -- The WIN.INI Entry -- When you change settings and save them (from the "Save Settings" dialog box), Pundit creates (or modifies) an entry in your WIN.INI file. The heading for this section is [jkbPundit] (it seemed like a reasonably unique name). There are six entries under this section: InSecs=n number of seconds the Window is shown OutSecs=n number of seconds the Window is hidden X=n the X position (column) of the Window Y=n the Y position (row) of the Window Width=n the width of the Window Height=n the height of the Window (in the above, n represents a number) Deleting any of these item will cause Pundit to revert to its "default" behavior for that item. -- Caveats -- 1) Pundit does NOT know what is happening with any other Window, so when Pundit pops up it may disrupt what you are doing. This includes making the menus on other Windows go away, and canceling the "Switch to..." dialog box. Also, any keyboard operations you may be performing will suddenly stop when Pundit pops up, unless you re-activate the Window you were working in. Control of the window you were working in will be restored when Pundit hides its Window. 2) If you are blazing fast and furious with the mouse in some Windows application (such as Solitiare), you may notice that your application froze for a moment and is suddenly being repainted. Don't panic! All that happened is that Pundit popped up on top of that application (temporarily de-activating that application's Window) and you clicked the mouse somewhere within the application Windows' client area that was not covered by Pundit, and your original application was brought back up to the fore and the client are was repainted. This is sometimes annoying, but not fatal. 3) A few of the quotations in Pundit were formatted to use multiple lines (such as a poem or cheer). The default size of the Window is really not big enough to display these quotations correctly, so they may wrap strangely at the right edge of the Window or may be clipped at the bottom edge. When these quotations are displayed, you have two choices: a) Resize the window to give more room for the quotation, or b) Ignore the quotation altogether 4) Pundit uses the rand() function in the Microsoft C 6.0 library. This is a fairly good random-number system, but it is NOT perfect, so it is possible that some quotations may repeat themselves while others may not show up at all. To be fair, when Pundit starts up, I call the srand() function, passing it part of the current system time. This is probably NOT the best way to seed the random-number generator, but it is one of the most convenient, so I will accept part of the blame for repeated text. -- PROGRAMMER'S INFORMATION -- Pundit is distributed with the complete source code, heavily commented. In some places the comments tend to severely clutter up the listing, so if you want to remove some of the comments to improve readability, please do so (remembering that you may not distribute it that way). It is not my intention to fully explain how each aspect of the code works -- you can look up most of it in the Windows SDK documentation -- but I do want to make a few points about some of the interesting(?) things this program makes use of. Among these are the use of the STRINGTABLE resource, private messages, and an error in the Windows SDK documentation. When reading the source code, beware of where the commas are. For some of the internal strings, I have used the C language's string constant concatenation feature to "improve" readability of the string constants. -- The STRINGTABLE -- All of the quotations used by this program are contained within a STRINGTABLE resource in Pundit.rc. Some of these strings are made up of more than one line. If you look at the quotes in Pundit.rc, you will see that some of them contain the substring \012. This is an octal (base 8) contant that represents a LineFeed, and tells Windows to break the line at that point. I have indented each new line by two spaces in order to help visually separate "real" line breaks from line breaks that Windows has produced. You may also notice an occasional substring of \042. This allows the use of the double-quote character (") within a string. The primary advantage to the STRINGTABLE resource is that Windows loads the strings into memory ONLY WHEN IT NEEDS TO, rather than having them taking up precious memory for the entire time Pundit is running. Also, it makes it easier to modify (or add or delete) quotations -- only the resource needs to be recompiled and linked rather than the C source file. NOTE: In the Pundit.h file, there is a #define'd constant MAX_STRING. This should be set to the ID value of the last quotation in the STRINGTABLE. If you add or delete quotation from the STRINGTABLE, you MUST change the value of this constant or Pundit will behave badly. NOTE: Some of the entries in the STRINGTABLE are lines that exceed 200 characters. If your editor imposes a maximum line length (such as Brief) you may need to either use a different editor (The Norton Editor will handle very long lines), or reconfigure your editor to accept a longer line (you can do this for Brief in the "setup" program). -- Private Messages -- Windows Programs are not limited to the Messages described in Windows.h -- you may Send, Post, and process your own messages if you wish. Pundit uses two private messages, WM_jkb_START and WM_jkb_PAUSE (which are used to inform Pundit to start and suspend the timer). These private messages are given values higher than that of WM_USER in order to ensure that they do not conflict with the standard Windows Messages. -- Knowing About the Menu -- One important consideration when designing a program like this is that you do not want the Window to vanish when a menu is up and the user is deciding what he/she wants to do. Also, if the user decides to cancel the menu (with the ESC key or clicking outside the menu area), the program needs to return to normal operation. Fortunately, Windows provides a couple of Messages to help in this situation, namely WM_INITMENU and WM_MENUSELECT. Unfortunately, the documentation for WM_MENUSELECT is incomplete and slightly incorrect (at least in my copy of the SDK). When the user activates a menu, Windows sends a WM_INITMENU Message to the application. This is great, since it allows us to know that a menu was activated and gives us the opportunity to shut down the timer while the menu is up, thus preventing our Window from vanishing for a while. Windows also sends a WM_MENUSELECT message each an item is selected (highlighted) on that menu, and the wParam and lParam values contain information about what was selected. But here's where the problems come in: the documentation for the WM_MENUSELECT message says: If the low-order word of the lParam parameter contains -1 and the high-order word of the wParam parameter contains 0, Windows has closed the menu because the user pressed ESC or clicked outside the menu. First of all, there is what appears to be a typographical error in this description: what need to be checked for 0 is the high-order word of lParam, not wParam (wParam does not have a high-order and low-order word -- it is just one word). That's the slightly incorrect part; the incomplete part is that what they don't tell you is that the conditions of wParam and lParam apply whenever Windows closes the menu EVEN IF THE USER CHOSE A MENU ITEM! (Run the Windows SDK "Spy" utility on an application and choose a menu item -- you'll see the Message). Because of this situation, we have to shut down the timer for Pundit when we enter a dialog box (unless we want the main Window to vanish while a dialog box is active). This is done by processing the WM_INITDIALOG Message and shutting down the timer in each of the two dialog boxes in Pundit. This is by no means as bad a situation as it sound here. It was just a little annoying, since it was not documented correctly, and it took a little time to track down (thank Microsoft for "Spy"!) I hope that those of you who are newer to programming for Windows than I am will benefit from all this, and that those of you who are more experienced will point out any errors or improvements. Jeff Bienstadt