
-QCP_1.61 The QL-Colour-Picker
 -----------------------------
   Version 1.2	- 22-03-05;  Wolfgang Uhlig
   Version 1.55 - 10-04-06; by Wolfgang Uhlig, but was never released
   Version 1.60 - 14-06-08; upgrade by BSJR, finishing the 1.55 concepts
   Version 1.61 - 31-05-13; update by BSJR

   Integrated HSVprocs are  Marcel Kilgus 2003
   minor bugfixes and adaptation to QDT by J.D.Hunkins 2005

   QCP is a tool to create RGB colours for your Favourite Colours file.
   It will also show the colour numbers which you can send to the Stuffer
   buffer.

   QCP is freeware. You may give it to anyone, provided that you don't change
   the source code or ask any reward whatsoever for it (except for copying
   fees or shipping costs) and give this unchanged README file along with it.


 ---------------------------------------------------------------------------
I-SUMMARY of new features
 ------------------------
    Version 1.60
    ------------
    - System Colours can now be stuffed as hexadecimal and decimal values.
    - Also Native values are calculated and can be stuffed.
    - 3D-border values can be picked from a scroll down window.
    - Favourite colours can be loaded or saved under another name.
    - Numbers can be edited or input and the colour will be shown.
    - The chosen colour field has a black & white block at the top for
      contrast comparison.
    - 3 defaults need to be set with (Menu)Config.
    - The "_inf" extension can be changed to "_mfc", as in the new QCoCo 1.60.
    - The Menus have been updated with EasyPTR4.
    - All loose items now have a selection key.
    - Some Menu_rext calls use the new 'time-out' options of version 7.67.
      (current version 8.02)

    Version 1.61
    ------------
    - Made compatible with SMSQmulator.
    - Some colour options were dependent on the hardware or emulator, now the
      current mode is used instead.
    - The Native colours option is now available for mode 16 too.
    - New option to change the System Palette QCP is using.
    - If present the HOME directory is used if the configured root is invalid.
    - The black & white top in the colour field can be switched off.
    - A Statistics option was added to the Info menu.
    - Improved Load & Save options for the basecolours file.
    - Minor bugs were fixed.


 ----------------------------------------------------------------------------
II)-HOW-TO-START
 ---------------

 QCP needs SMSQ/E 3.04 or later to run. The current version is 3.16.
 It also needs Qlib_run and the Menu_rext extensions to be resident. These are
 not included but can be found with most PE programs.

 1) Make a new directory on your hard disk, for example "win1_QCP_".

 2) Unzip the files into this directory.

 3) Start MenuConfig_exe or Config_exe and configure QCP:

    1) the directory where QCP resides and will look at for loading or saving
       the Favourite colours file.
       The setting when shipped is "win1_QCP_".

    2) The name of the Favourite colours file to use at startup.
       The setting when shipped is "win1_QCP_basecolours_mfc".

    3) The extension for the "basecolours" file with default RGB colours.
       This was "_inf" but from version 1.60 you can save the default colours
       to any filename, therefore I prefer the less general extension "_mfc"
       which I introduced with QCoCo version 1.60.

       If you also use QCoCo from us, both programs can share the same
       "basecolours_mfc" (or "_inf") file.

       For compatibility with the old QCoCo you can stick with "_inf", or stay
       with "_inf" in config item 2 but use "_mfc" for a new save in item 3.

 4) Start "QCPxxx_obj" by 'EX'ecuting it.

    NOTE 1: QCP may complain when not configured properly but will probably
    start up and not crash. Just take the proper action when prompted.

    NOTE 2: If no _mfc file is loaded (all white) you cannot ADD colours.
    A file must be loaded before you can attach colours to an active cell.


 ----------------------------------------------------------------------------
III)-THE-FILES in the archive
 ----------------------------

   ('dev' is your directory)

   dev_QCPxxx_obj	   -  the main program
   dev_basecolours_inf	   -  16 predefinded RGB colours, old extension
   dev_basecolours_mfc	   -  the same with the new extension

   these are of interest:
   ----------------------
   dev_README_txt	   -  this file, optimised for reading in QD,
			      select chapters with CF6 (Label)
   dev_whatsnew_txt	   -  the changelog, if any


 ----------------------------------------------------------------------------
IV)-HOW-TO-USE the program
 -------------------------

 CHANGE FAVOURITES
 -----------------
   Click one of the 16 coloured windows to make it active.

   Then simply Hit anywhere in the big coloured window to pick a new base
   colour and its saturation; high at the top and low at the bottom.
   Then click on the vertical coloured bar or drag the arrow to set the
   brightness level. The resulting numbers will show to the right and the
   colour itself above them.

   "A" - ADD will replace the 'favourite' colour with the new selection.


 SEND TO THE STUFFER BUFFER
 --------------------------
   Decide which type will be the new value for the Stuffer buffer.
   "T" - for the hexadecimal True Colour
   "C" - for the hexadecimal System Colour
   "D" - for the decimal System Colour
   "N" - for the hexadecimal Native Colour
   "E" - for the decimal Native Colour

   "S" - will SEND the value of the highlighted type to the Stuffer buffer.
   Use your Stuffer buffer Hotkey to drop the value in your text (def. Alt-SP).


 EDIT THE NUMBERS
 ----------------
   A DO on any of the numbers lets you edit them or input a new value.
   The colour will be shown and the values for the other types are calculated.
   Invalid entries are ignored.

	      $000000/FFFFFF : for True Colours
       $0000/FFFF or 0/65535 : for Native Colours in mode 32 or 33
	     $00/FF or 0/255 : for Native Colours in mode 16

   The full range of System Colours can be used:
	     $00/FF or 0/255 : QL Colours and Stipples
	 $100/1FF or 256/511 : Aurora's predefined PAL Colours
	 $200/238 or 512/568 : System Palette Reference
	$300/3FF or 768/1023 : Grey Colours
       $400/4C5 or 1024/1221 : 3D-borders, only 28 of which are valid
   $4000/7FFF or 16384/32767 : PAL Stipple Colours
   $8000/FFFF or 32768/65535 : RGB System Colours

   - For some of these no True or Native values can be calculated so their
     numbers will be blanked out.
   - If the number is shown inverse, this means that it's a reference to an RGB
     value and then the System value will appear if you DO the number again.
   - If the colour is a stipple, the type and the 2 colours are shown on top.

   For the System Palette numbers the colour value in the current theme will
   be read and shown. This in itself can be any of the above values.
   You can Hit the PAL button to select another of the 4 System Palettes.

     NOTE 1: If the theme colour is a QL, PAL or Grey colour or a 3D-border,
     the decimal value is shown in the colour field.
     If the theme item points to another theme item, then that one is read but
     if this again points to another item, that is considered to be an error.

     NOTE 2: You may encounter, as I have, themes with invalid values.
     A default stipple is shown instead and an 'Invalid' warning given.

     NOTE 3: The System Palette colours are read only once at startup so if
     the current palette is changed later, by QCoCo for instance, you need to
     reload the theme by hitting the PAL button or restart QCP.


 3D-BORDERS
 ----------
   "B" - Or hitting the bar at the bottom - will unroll a 3D-borders picture
	 below the RGB colours.
	 Hit one of the options in the picture, a bigger example will show and
	 the numbers are set up to be SEND. Of course True or Native will not.
	 Hit the icon again to remove the 3D-borders menu.

 OTHER KEY FUNCTIONS
 -------------------
   "I" - Will open the Info window.

       - With a Hit on the website line you can open my site directly from
	 inside QPC2 only.

       - A DO on the logo in the Info window shows more statistics and lets
	 you save the 16 Favourite colours to the current or a new file.
	 An OK there will also refresh the Main window.

   A DO on one of the 16 RGB colour windows will Load a new file.
   You should use this option if the configured filename cannot be found.

   A Hit on the colour field with the black & white bar on top will remove it.
   Some people disliked it. I like it so another Hit will add it again.

   The usual keys can be used for the other buttons:
   CF4 - Move the window.
   CF1 - Put the program to sleep.
   ESC - Quit, if the 'Favourites' have been changed you can save them with
	 the current or a new name.


 ----------------------------------------------------------------------------
V)-FEATURES and known problems
 -----------------------------

 - The program tests the SMSQ/E version at startup. Be sure to have at least
   version 3.04, otherwise you get a warning or it refuses to start.

 - QCP will not function when your system is not started in High Colour Mode
   which is obvious. QCP quits with a warning.

 - If the basecolours file is not a valid _inf or _mfc file, QCP will start
   with all 16 favourites set to white.

 - If you want to save the current basecolours unchanged under a new name,
   then hit one of the 16 colours, next click ADD. This will act as a change
   so when you hit the Esc button you can save the colours.
   Or use the new save option from the Info window described above.

 - QCP also works on the Aurora and other SMSQ/E implementations that support
   mode 16 but then the range of visible colours is limited.
   Native colours ar now also possible in mode 16.
   On my QXL the program works fine too but some buttons may not display as
   expected. This bug has been fixed in SMSQ/E v3.16.
   It should also work on Qx0 which I could not test myself.
   Please let me know your experiences.

 - Because of the event handling of EasyPtr it is possible that you get two
   or more small circles in the saturation field.
   If that happens, a single mouse click on the last spot in this field will
   delete them and set a single one.
   To avoid this behaviour, just click once and then move the mouse.

 - As the current SMSQ/E platforms use a limited colour range, a maximum of 5
   or 6 bits per Red, Green or Blue sample, the True colour derived from that
   may never reach the full value ($FF) as the lowest bits are simply ignored.
   Full range upscaling can be switched on by putting %S% in the command
   string. ( e.g. ex dev_QCP161_obj;'%S%' )
   Remember you will only see the difference in the True colour number that
   can then also be Stuffed or Added to your Favourites.


 - Problem: I cannot read the values that are printed over the colour field.
    Answer: The 'Hint' colours are used for this except for a theme 3D-border,
	    then the 'AW middleground' is used. So you may need to change these
	    to get a better contrast between background and foreground.
	    QCoCo is the ideal tool for this.

 - Problem: When I opened the website from the Info menu, I got a Qlib error:
	    'QPC_EXEC not found'
   Answer : This error only occurs, sometimes, on QPC2 systems. It seems to
	    happen when the default browser is not found or not quick enough.
	    There is a good chance that the site will be opened anyway.
	    Key C)ontinue in the Qlib error window and all will be fine.

	    NOTE: If at any other moment you get a Qlib error with the
	    C)ontinue option, you can try the B)orders key next which will
	    redraw the menu.
	    You can also Hit Info ("I") and then DO the logo. An OK there will
	    also refresh the Main window.
	    Please report any other errors to the email address below.


 ----------------------------------------------------------------------------
VI)-CREDITS
 ----------

   One thing is beyond any doubt: without Marcel Kilgus this program would not
   have been possible! Not only did he create the basis from which we all can
   benefit, but he also did provide us with the HSVprocs routines to allow
   the interactive creation of new colours.
   Many, many thanks, Marcel!

   We thank QL Today and its many authors, for publishing all the articles on
   the subject of High Colour.


 ----------------------------------------------------------------------------

   Enjoy your QL-Colours

   Wolfgang Uhlig, Bob Spelten jr
   contact: szx83@upcmail.nl
   02.06.13
