$Id: README,v 1.1.1.1 2001/08/13 02:21:06 sise15 Exp $

COPYRIGHT

(c) 2000 Keith Brown

LICENSE

This software is distributed and may be redistributed under the terms of the Q
Public license as defined by Troll Tech AS of Norway and appearing in the file
LICENSE.QPL included in the packaging of this file.

DESCRIPTION

JFCStyle implements the look of the Java Foundation Classes "Metal" style GUI
in Qt using the QStyle interface.

USE

At the minimum, you must include jfcstyle.h in your source where you
initialize the application style, and you must compile and link jfcstyle.cpp
with your project.  To set the style to JFC style, pass a pointer to a newly
created instance of JFCStyle to QApplication::setStyle(). For example, in your
main() function, where you create your QApplication instance, you would do:

#include "jfcstyle.h"
.
.
int main( int argc, char** argv )
{
	QApplication myApp( argc, argv );
	myApp.setStyle( new JFCStyle );
.
.
}

That's it. Run it and enjoy the cool new look! Oh, if you want to play with
color themes, there is a support class, JFCScheme, that maps JFC color schemes
to Qt palettes. Either pass an instance of JFCScheme to the JFCStyle
constructor, or to change at anytime, call the static member
JFCStyle::setScheme(). This is a bit of a hack, but it seems to work
well. There are three built-in schemes provided as static members, all based
on samples in the Java Look and Feel guidelines: the default purple and gray
metal (JFCScheme::Default), a green scheme (JFCScheme::Jade) and a high
contrast black and white scheme (JFCScheme::HiContrast).

NOTES

This class works with Qt 2.0 or greater. I have only personally tested it with
Qt 2.0.3, but I have several reports now that it works with the 2.1 series. It
should no doubt work on all Qt X11 platforms without a problem, but at this
point, I can't guarantee whether it will work right on Windows.

Qt styles, by Troll Tech's own admission, are hacked together and quite kludgy
right now. They may rewrite it eventually, but it isn't a priority.  With this
in mind, there are some things that can't be done or are buggy. Here are a few
that I can think of off the top of my head:

1. There are a couple of problems with switching from one style to another at
runtime. One example is tabs will be drawn using metrics from the style that
was in use when the tabs were created, thus causing them to be drawn
incorrectly if the metrics are not correct for the new style. This is one bug
that I was able to track down and report to Troll Tech, but there seem to be
others. All of these quirks seem to disappear if the application style is set
at startup.

2. JFC Metal uses small check boxes and radio buttons in menu items, so items
that are checkable, but unchecked, will display the empty box or radio
button. Qt menu items don't work this way: there is no way to specify that an
item is checkable, but not checked. I compromise and just draw the whole
checked box when the item is checked, or nothing at all when it is
unchecked. An alternative would be just to draw a JFC style check mark alone,
without the checkbox. If you have an opinion on which is better, let me know.

3. JFC Metal fills the active item in the menubar with the menu highlight
color (Primary 2), but there is no way to do this with Qt styles and if there
is any way at all, it's likely to be an ugly hack.

4. Custom styles must be inherited from one of the built-in styles otherwise,
ugly hacks or Qt code changes are required. In addition, the built-in styles
impose their own look and feel in a few places creating problems for style
designers. I had to inherit from QWindowsStyle because QMofifStyle insists on
drawing the motif "arrow head" gadgets on combo boxes, which of course does
not work at all with JFC style. Therefore, choosing the lesser of two evils, I
had to inherit from QWindowsStyle, which draws a "segmented" progress bar, and
also, does its own thing when drawing toolbars, so these two items are not
true to the Java Look and Feel guidelines. In addition, each built-in style
imposes its own method of indicating keyboard focus: with QWindowsStyle, this
amounts to drawing a dotted rectangle around the label of the tab. Not only is
this not consistent with the JFC Metal style, but it's ugly as well. Sorry,
but I can't really find a way around this.

5. I'm sure there are others, I just can't think of them now.
