Better Windows, Better Works/CDRM93801.bin/winutil/util42/pundit.txt

Text File | 1991-11-20 | 20KB | 536 lines

-----------
Pundit v1.1
-----------


                     -- 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
                13305 NE 171st Street  #D130
                   Woodinville, WA  98072

(For those of you who have Version 1.0, please note the
change of address).

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 for the main program
    SETTINGS.C    The C source for the Settings dialog, etc.
    EXTRAS.C      The C source for some Windows extras
    EXTRAS.H      Header file for EXTRAS
    PUNDIT.RC     The resource file
    STRINGS.TBL   The string table with the quotations
    PUNDIT.ICO    The Icon
    PUNDIT        The Make file (for NMAKE)
    PUNDIT.DEF    The Linker Definition File
    PUNDIT.HLP    The Help File
    PUNDIT.RTF    The source for the Help File
    PUNDIT.HPJ    The Help Project File (for HC)

Please be sure that you have all of these files in your distribution



 -- Changes from Version 1.0 --

Several things about Pundit have changed since version 1.0.
Among them are:

    Pundit now maintains its own .INI file.
    Version 1.0 save its settings in the WIN.INI file, which
    cluttered up that file, and slowed down the saving and
    retrieving of settings.  Settings are now saved in PUNDIT.INI.

    Quote categories.
    You may now choose from several different catgegories of quotes
    for Pundit to display, or you may have Pundit choose a category.
    Also, there are more quotes to play with.

    Hide mode choices.
    Version 1.0 simply hid the window when Pundit was "out".  Now you
    may choose between hiding the window or making it an icon.

    Clipboard Support.
    The quote currently displayed in the Pundit window may now be
    copied to the Windows Clipboard.

    Help.
    Pundit 1.1 now provides help.



                     -- 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.



 -- The Menu --

Besides the "system" menu (for sizing, etc.) Pundit
contains three selections on the main menu.

    Choices     Control whap Pundit does
    Edit        Copy the quote to the clipboard
    Help        Get help


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.)

Following is a description of the Pundit menu selections:


    Choices Menu

    The Choices menu contains four items:

        Categories Menu

        This selection brings up a sub-menu with categories
        of quotes.  You may choose from:

            Quotes  Quotations from various people
            Laws    Murphy's laws and other laws
            Snigs   "Sniglets"* -- Definitions of unreal words
            Misc    Odd little "sayings"
            Random  Pundit will choose from one of the above
                    catetories.

            When one of these items is selected, Pundit will
            choose a new quote from the new category and display
            it.

            When Pundit exits, the current category choice will be
            saved, and that will be the category used the next time
            Pundit is run.


        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, and the foreground and
        background colors of the text window.

        Change the time that the Pundit window is visible or hidden
        with the two scroll bars labeled "Seconds In" (the number of
        seconds that the window is visible) and "Seconds Out" (the
        number of seconds that the window is hidden).

        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).

        Use the three scroll bars labeled "Red", "Green" and "Blue"
        to control the color for the Pundit text window.  You may
        select colors for the foreground and background by selecting
        one of the radio buttons labeled "Foreground" and "Background".

        As you change the color values, a text box will display an
        example of what the text will look like using that color
        combination.

        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.


        NoShow

        The NoShow menu item brings up a sub-menu which allows you
        to control what happens to the Pundit window when it is not
        displaying a quote.

            Hide        Causes the window to vanish when not active.
                        When the window is "out", there will be no
                        trace of the window (even on the Task List).
            Iconize     Causes the window to become an icon when not
                        active. The window will display an icon along
                        with any other inactive applications you may
                        have.


        Exit

        The Exit selections terminates Pundit.  The current settings
        for the Categories and NoShow menu selections are saved.


    Edit Menu

    The Edit menu contains one selection, Copy, which copies the
    current quote into the Windows Clipboard.  Once in the clipboard,
    the quote may be copied into another application.


    Help Menu

    The Help menu contains these menu items:

        Index

        Brings up the Windows Help system, starting with the index
        for Pundit's help text.


        Using Help

        Brings up the Windows Help system, starting with help text
        describing how to use the Help system.


        About...

        Displays an "About Box" describing Pundit.



 -- PUNDIT.INI --

The information about Pundit's settings are saved in a file called
PUNDIT.INI.  This file is an ASCII text files containing a line for
each of the items

    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
    Back=n n n  the Red, Green, and Blue color values for the background
    Fore=n n n  the Red, Green, and Blue color values for the foreground
    Category=n  the quote category
    Hide=n      the hide mode

    (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.
        This is true for the Windows Help system as well as
        any other window.  If you activate Help from Pundit,
        the Pundit window may "go away" while you are in Help.
        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.

Having the quotations contained within the .EXE file as a
resource does make for a fairly large .EXE file, but there
is one very important point to remember:  in Windows programs,
the size of the .EXE file often has very little to do with
the amount of memory actually required to run the program.
Since a good part of the PUNDIT.EXE is resources, and these
resources are loaded ONLY WHEN REQUIRED, Pundit really does
not eat that much memory.

NOTE:
    In the PUNDIT.H file, there are #define'd constants
    that determine that starting position and number of
    strings for each category in the STRINGTABLE. If you
    change the STRINGTABLE, these contants MUST change
    to reflect your changes 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 three private messages,
PM_START, PM_PAUSE (which are used to inform Pundit to start
and suspend the timer), and PM_DLGPAINT (which is used to help
in painting the color example in the settings dialog box.  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"!)



 -- Suggested Enhancements --

The source code to Pundit is provided both as an example of some
Windows code and so that you may change the program to suit you.
Just remember not to incorporate your changes into the distribution
files.
Some things that you might want to do are:

    Alter the ranges for Time In and Time Out.  The ranges that I
    initially programmed in are pretty arbritrary.

    Add more quotes or even more categories.

    Allow Pundit to remain "on hold" when Help is activated.
        Hint:   You might try getting the window handle
                for the Help window, and fetching the caption.



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.


Thank you ---

                Jeff Bienstadt