new_tests

Screentest is a CRT/LCD screen testing utility.

WHAT TO DO IF YOU WANT TO ADD A NEW TEST MODE
=============================================

The process of adding new modes to screentest is not very complicated.
Follow these steps (let's assume you want to add a test called "circle").

1. Create the new test's source file, circle_test.c. You should copy
the top of the file with copyright notice and #include statements
from another source file (say text_test.c), so it looks like this:
[...]
  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  */

  #ifdef HAVE_CONFIG_H
  #  include <config.h>
  #endif

  #include <gtk/gtk.h>
  #include <stdio.h>

  #include "callbacks.h"
  #include "interface.h"
  #include "support.h"

2. Add the source file name (circle_test.c) to the screentest_SOURCES
variable in Makefile.am.

3. In circle_test.c you have to define the (non-static!) structure
	struct test_ops circle_ops
This structure, which have four member functions, defines the basic operations
of your test mode. The structure members are:

	void circle_init(GtkWidget *widget);
This function is called when screentest is switched to your "circle" test.
The argument is GtkWidget of type DrawingArea, which covers the whole screen.
This function is optional, you can set it to NULL.

	void circle_draw(GtkWidget *widget, gboolean clear);
This function is called when screentest decides to redraw the screen
(either when mode/fgcolor/bgcolor changes, or the Expose event from
the X server is received). The first argument is the same
DrawingArea as above, the second one is True, when the screentest
wants you to clear the window before you start drawing. This function
is not optional. You must define it (after all, your test wants
to draw something, doesn't it?).

	void circle_cycle(GtkWidget *widget);
Screentest calls this function when user presses the left mouse button.
You can use it to cycle through values of some parameter (let's say,
the circle diameter). You don't need to redraw the screen. The circle_draw()
function will be called afterwards. This function is optional, you can
set the "cycle" member of circle_ops to NULL. The widget argument
is the same as above.

	void circle_close(GtkWidget *widget);
This function is called when screentest wants to switch to another mode
(and is called before the new mode's init() function). You can use it to
deallocate fonts, colors, timers or other resources you have allocated
(for example in circle_init() function).  This function is optional, you can
set the "cycle" member of circle_ops to NULL. The widget argument
is the same as above.

4. You can use the following global variables in the above functions:

	GdkGC *gc, *backgc;
These are two graphic contexts. The first one has the foreground color set to
the current foregronund color (defafult white) and background color to the
current background color (default black). The second one has its foreground
color set to the current background color (default black) and the background
color to the current foreground color (default white). So you can use the
first to draw with the foreground color and the second to draw with the
background color. You can (ab)use these contexts for your own colors,
but remember to set the color back to its original value before your return
from the circle_* function.

	GdkColor fgcolors[COLOR_MAX];
The GdkColor array with preinitialized color values (see the enum test_color
in callbacks.h).

	GdkColor grays[GRAYS_MAX];
The GdkColor array with pixels preinitialized to the shades of gray.
grays[0] is black, grays[GRAYS_MAX-1] is white. Currently the
GRAYS_MAX is #defined to COLOR_MAX, but do not depend on it.

5. Add the circle test to the appropriate structures:

- in callbacks.h, extend the enum test_mode by adding CIRCLE_TEST element.
- in callbacks.h, add the "extern struct test_ops circle_ops;" declaration.
- in callbacks.c, add the new mode to the on_mode_change() function.
- use glade to add the new mode to the menu
  (alternatively, edit interface.c and glade.screentest by hand).

6. Run automake, autoconf, ./configure and make.

7. If you want to distribute the resulting program:
Beware this program is under the GNU General Public License, so if you
distribute the modified version, you have to distribute the source code
of all your modifications. See the file COPYING for details.

You must make the circle_test.c available, but you don't have to send it
to the author of this program. However, author of this program kindly asks
you to contribute any modifications. Please send your modifications
to the author of screentest, Jan "Yenya" Kasprzak <[e-mail]>.
The preferred form of the contribution is an unified diff (see the diff(1)
manual page. To make a unified diff, follow these steps:

- rename your directory with modified sources (for example
	mv screentest-1.0 screentest-1.0-circle).
- run "make distclean" in this directory.
- unpack the clean sources again:
	zcat screentest-1.0.tar.gz | tar xvf -
- create the patch with the following command:
	diff -uNr screentest-1.0 screentest-1.0-circle >screentest-circle.patch
- mail the screentest-circle.patch to the author.

	Thanks,

-Jan "Yenya" Kasprzak <[e-mail]>