321 GAMES/321GAMES.iso/misc/pundit/pundit.txt

Text File | 1990-11-29 | 14.6 KB | 397 lines

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