dockapps/wmcalc/README

wmcalc
-------------------------------------------------------------
   Code is loosely based on wmppp, wmload, wmtime, wmcp, and asbutton
   Original Author: Edward H. Flora <ehflora@access1.net>
   Current Maintainer: Window Maker Developers Team
                       <wmaker-dev@lists.windowmaker.org>

DESCRIPTION:
------------
wmcalc is a program designed to act as a simple four-function
calculator.  It is different from other calculator programs, however
in that it is designed to take up very little desktop space.  As such,
it can be left running on the desktop at all times.  It is intended to
placed in the WindowMaker dock, or in Wharf under Afterstep, though it
should run as well under any window manager.

LICENSING:
----------
This program is released under the GPL license.  A copy (in case you
don't already have hundreds of them floating around) can be found in
this distribution in the file COPYING.

CONTRIBUTORS:
-------------
Co-Developers:
	      Rick Stuart     <stuart@xnet.com>
	      Philippe Trbich <philippe.trbich@free.fr>
Original Web Page Designs:
              Jon Bruno <bruno@ksu.edu>
Thanks to:
              Ben Cohen <buddog@aztec.asu.edu>
                  original author of wmcp (et al.)
The contributors listed above are not involved with the development of
wmcalc.  I'm listing them here as thanks for helping out, catching
bugs in the code, etc.

INSTALLATION:
-------------
	Compile it:
	 	make clean; make

	As root, install it:
		make install

	Optionally, copy the config file:
		cp wmcalc.conf ~/.wmcalc

	Run it:
		wmcalc &

	Grab the appicon and move it to the dock.
	Change the settings to start with Windowmaker

	Afterstep Wharf 1.6.??: (I don't use Afterstep anymore, so...)
	*Wharf wmcalc -Swallow "wmcalc" wmcalc &

    ***Note***:
	The appicon only has a two pixel border where you can grab
	and move it.  It is easiest to grab along the bottom edge.

	If make doesn't work, you may need to fiddle with the settings in
	the Makefile.

	Tested on: (Well, it runs, I don't know if 'Tested' is quite right...)
		WindowMaker-0.62.1
		X Clients: Red Hat 6.0, Kernel 2.2.8

USAGE:
------
usage: wmcalc [-g geometry] [-d dpy] [-v] [-f configfilename] [-h]

-g  <geometry>   Window Geometry - ie: 64x64+10+10
-d  <display>    Display -  ie: 127.0.0.1:0.0
-v               Verbose Mode.
-h               Help. This message.
-f  <filename>   Full path to configuration file to use.

Buttons are defined as:
 ____________________
|       x00          | 	       where: x = 1 for Left Mouse Button
| 0 1 2 3 4 5 6 7 8 9|                x = 2 for Middle Mouse Button
|--------------------|		      x = 3 for Right Mouse Button
|x01 x02 x03 x04 x05 |
|x06 x07 x08 x09 x10 |	       Note: the numbers 0..9 are the indicators
|x11 x12 x13 x14 x15 |               for memory cells 0..9 respectively
|x16 x17 x18 x19 x20 |
 --------------------

Button Functions:
	100	Reinitialize the calculator, and both Registers
		(Clear All)
	200	Clear all the memory registers (0..10)
	300     Clear the current number being entered only
	x11	Start a program defined by CalcStart variable in config file
	1yy	Perform function shown on button
	2yy	Recall number from memory location [0-9] to display
		for calculation
			if yy = 2,3,4, 7,8,9, 12, 13, 14, 17
		otherwise, can run a user-defined function (not implemented)
	3yy	Store Displayed number in memory location [0-9]
			if yy = 2,3,4, 7,8,9, 12,13,14, 17
		otherwise, can run a user-defined function (not implemented)
	1xx	Hopefully the other functions are obvious from their
	        button graphics.


NOTES:
------
I am sure that there are better ways to do some of the things that are
done in wmcalc.  In fact, wmcalc is basically a series of hacks, but appears
to be stable...

The configuration file (.wmcalc) is written by wmcalc whenever the user
requests to store a number to memory.  As a part of this process, a file
is written to /tmp.  If /tmp is not accessible, it tries in the user's home
directory, as defined by the environment variable HOME.  This file is
erased as soon as it is written over the main configuration file.

Changes made to the configuration file (other than memory stores) will not
take effect until the next time wmcalc is started.

Although one can only "Clear" all unlocked memory locations, one may clear the
display and then "store" a '0' in the memory location, providing the
ability to clear individual cells.

The fonts are stored in charmap.xpm.  This file may be edited to
change colors or fonts, but the app must be recompiled for the changes
to take effect.  The buttons are located in calcbuttons.xpm.  This
file may be edited, though the borders should stay where they are
unless you want to change the button regions that are hard coded.
The background border is defined in backdrop.xpm.

"C code.  C code run.  Run, code, run.
			PLEASE!?!?!?!?!?!?"

CHANGE LOG:
-----------
0.5	Add manpage from Debian.
	Update Makefile.
	Switch #include <XKBlib.h> to #include <X11/XKBlib.h>.
	Fix -Wunused-but-set-variable compiler warnings.
	Fix -Warray-bounds compiler warning.
	Fix -Wunused-result compiler warning.
	Remove trailing whitespace.
	Remove redundant .wmcalc*; essentially the same as wmcalc.conf.
	Update COPYING from http://www.gnu.org/licenses/gpl-2.0.txt.
	Update README.
	Allow installation without root access.
	Fix -Woverflow compiler warnings.
	Remove C++ style comments.
	Maintained by Window Maker Developers Team
		<wmaker-dev@lists.windowmaker.org>

0.4     Added global config file
	Maintained by Gordon Fraser <gordon@debian.org>

0.3     Added "Locked" memory capabilities via config file
        General Code clean-up
	Keyboard Support - may not be platform independent

0.21    Added Display of memory locations containing non-zero data

0.2	First psuedo-major enhancements
	Added Memories, Config File, CalcStart button
	Bug Fix - Squared imaginary number is now negative

0.1	First real version.
	Limited functionality.

0.0	Original version.  Very limited distribution, as it was not a
	functional calculator, but just tested the display.  It was more
	of a proof of concept.

TODO:
-----
These are partially a dream list.  I don't know when they'll get done,
as I'm pretty busy at work.  Anyone want to tackle these??

* Re-implement the register/display design to allow full double precision.

* Add keyboard support (I've tried to do this, with no luck.  Probably a
  'focus' problem.

* Add button press animation.

* Add a log file, either as a paper tape implementation, or a file
  that one can intentionally write data to.  (This could grow to a pipe to
  plotting programs, etc, though this is a bit extreme...)

RPN:
  I have no intention at this time to add in an RPN format, as I
  personally do not like it.  It should be noted that I have NOT used it
  extensively, and I've heard that I would like it.  But, until then...

BUGS:
-----
Remember, they're just undocumented FEATURES!!!

* The display can lose the last digit of a three character exponential
  notation number.

* Due to an implementation fault, at every step of calculations, precision
  is lost, as the number is only as accurate at that displayed.

* Order of operations: 1 + 2 * 5 = 15, not 11, as it should.

* Changing sign when the display is blank results in "-0".  Further entry
  yields "-05...," but this does not affect calculations.

* Changes to the configuration file do not take effect until wmcalc is
  restarted.  (Note that file is written whenever a "store memory
  location" is requested)

Probably many more.  Send comments (preferably with fixes) to
	<ehflora@access1.net>
I will happily include your name in the documentation for the program
if you send me a bug report and the correction.  This can be in the
form of a patch file, or ASCII text to exchange, or an equivalent.
Note, this program is written in C.  Not C++.  I'm not a computer
science person, I don't do objects.  Therefore, bug fixes that convert
this to C++ don't count, since I would no longer be able to support
the program.  Of course, you can modify the code and release a new
application.

Thanks, and Good Luck.