
-QCOCO-

   Version: 1.01 - 05-12-03; by Wolfgang Uhlig
   Version: 1.53 - 05-01-04; last upgrade by Wolfgang Uhlig
   Version: 1.60 - 16-04-08; upgraded by BSJR
   Version: 1.61 - 23-05-13; upgraded by BSJR

   QCoCo is a tool to configure the System Palette colours.
   It is free and you may give it to anyone who likes it, as long as the
   source code and this text are not changed without my permission.
   This Readme file has been optimised for reading in QD.
   When you hit the 'Label' item, you can jump straight to each chapter.


 ---------------------------------------------------------------------------
1.-SUMMARY of new features
 -------------------------
    Version 1.60
    ------------
    - The background images are no longer taken from _bmp files but are now
      loaded from big sprite files. Consequently the "qlborder" image is now
      also a sprite and included in the program code, so it doesn't need to be
      loaded from the root any more.
    - When changing an item, the current item number and the colour number are
      shown in the selection menu.
    - The Favourite colours can now be loaded and saved from the RGB selection
      menu, therefore a new extension is preferred: "_mfc".
    - Colours can be selected from Favourites as before but now also from
      the QL colours, the PAL colours, the current System Palette colours, the
      Grey shades and even PAL stipples can be made.
    - New buttons '<' or '>' are used to scroll through all the colours.
    - New colours selected for an item will be added to the System colours and
      can thus quickly be picked from there for other items.
    - If on reflection a colour change wasn't the right one, you can always
      pick the old colour again from the System colours.
    - "Load theme" can now read the colours from any of the 4 System Palettes.
    - "Apply" can save the current theme to any of the 4 System Palettes.
    - Doing a "Load theme" or "Apply" will also change the System Palette the
      program is using itself.
    - The new "Reset" button will undo all changes since the last save or load
      and redraw the main window.
    - Minor bugs have been fixed and the menus have been updated in EasyPtr4.
    - All menus have an OK option to confirm the colour changes.
      Escape will undo the most recent changes for that menu.
    - All menus have an escape option.
    - All 57 system items can now be changed individually. Hitting the space
      above the Title item will list them all.
    - When you Hit the QCoCo name in the Info menu, more program info is
      available and you can change the background colour or skin sprite or
      override some configurated defaults.
    - 5 more defaults can be set with (Menu)Config.
    - Some Menu_rext menu calls use the new 'time-out' options introduced in
      version 7.67 (current version 8.02).

    Version 1.61
    ------------
    - When you start the RGB-Mixer from a Favourite colour then this colour is
      the starting colour in the Mixer instead of a default Blue as before.
    - The values for Red, Green & Blue are printed over the colour field.
    - The Hue, Saturation & Brightness values are also shown.
    - A changed colour is also copied in the Favourites menu but is only saved
      if Auto-save is set or you save it yourself.
      This colour is converted to a System RGB value and added to the current
      System Palette colours list until you change the Palette.
    - When the _mfc file is reloaded, changed colours will be reset but stay
      present in the current System Palette and can be selected from there.
    - On Quitting QCoCo you can also save any changed Favourites.
    - A missing background sprite no longer generates a prompt for a new one
      with each reset, the current default colour is used instead.
    - The menu for the colour type now also shows the range for each type.
    - The Buttons menu now uses the same background as the Main window,
      representing a desktop background.
    - From Info (Hit QCoCo name) you can choose a new background colour or
      image but OK there will also do a redraw, with the current background.
    - QCoCo can now be run in mode 4 but with limited functionality.
    - Current directories for backgrounds, themes & _mfc are preserved.
    - Minor changes made to the menus and more informative titles & prompts.
    - The buttons in the sub-menus now also use Extended sprites.
    - All known bugs have been fixed.

 ----------------------------------------------------------------------------
2-INTRODUCTION
 -------------

 In this manual you will find the following items:

 I)    How to configure and start the program

 II)   Which files you find in the archive

 III)  An overview of what you can do with this program

 IV)   System Palettes and how to boot with a resident 'theme'

 V)    What do you see?

 VI)   Features and known problems

 VII)  Hints and tricks

 VIII) A brief overview of colour numbers for GD2 and WMAN2

 IX)   Credits


 ----------------------------------------------------------------------------
I)-HOW-TO-START
 --------------

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

 2) Unzip all files into this directory.

 3) Start MenuConfig_exe or Config_exe and configure the QCoCo _obj:

   1) the directory where QCoCo resides and will look for all needed files
      (see II). The setting when shipped is "win1_QCoCo_".

   2) the background image file for the program (see II).
      These were _bmp files but are now the new big sprites.
      The default when shipped, is "win1_QCoCo_spr_defbackgrd_spr".
      Six more backgrounds are available in the original archive.
      There are more background images to be found on my site.

   3) the directory for the 'theme' files (e.g. "win1_QCoCo_themes_").

   4) the default 'theme' at startup. A full filename is expected.
      If left empty this will cause the program to read your actual system
      colours from palette 0.
      there are some ready made themes in the directory "win1_QCoCo_themes_".

   5) The extension for the "basecolours" file with default RGB colours.
      This was "_inf" but from version 1.60 you can save these Favourites
      to a new file name, therefore I prefer a less general extension: "_mfc".
      For compatibility with an older QCP you could stick with "_inf".

   6) The program background colour that will be used in case the
      background image can't be found.

   7) The "Auto Save _mfc" option can be set to Yes or No. This means
      that whenever you make a new RGB colour with the Mixer, the current
      16 defaults will be saved or not.
      You can also save them by hand from the 'RGB Favourites' menu or when
      quitting the program and colours have been changed.

   8) The "grey factor": this is used to limit the number of steps it takes
      to scroll through shades the grey. A factor of 1 will show all 256,
      a factor of 16 will only show 16 shades. Default is 8 (32 shades).


 4) Start the 'QCoCo_obj' by 'EX'ecuting it.
    Qlib_run and Menu_rext must be present before it can be executed.


 ----------------------------------------------------------------------------
II)-THE-FILES in the archive
 ---------------------------

   ('dev' is your directory)

   dev_Qcc16x_obj	   -  the main QCoCo program
   dev_setconf_bas	   -  to set a theme as your system theme (see IV)
   dev_setconfall_bas	   -  define up to 4 themes for all System Palettes

   these 2 files must be in 'dev':
   -------------------------------
   dev_basecolours_inf	   -  16 predefined RGB colours, old extension
   dev_basecolours_mfc	   -  the same file with the new extension

   these 2 are optional:
   ---------------------
   dev_spr_defbackgrd_spr  -  the default background image
   dev_themes_deftheme_thm -  the default theme to start with

   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

   dev_spr_xxxxx_spr	   -  a number of background files
   dev_themes_xxxxx_thm    -  a number of theme files
   ........

   You may save your files in different places if you configure QCoCo
   accurately, but I recommend placing them all in the same root directory.

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


 ----------------------------------------------------------------------------
III)-WHAT-YOU-CAN-DO with the program
 ------------------------------------

   You can change the colours of paper, ink and border for PE programs that
   are aware of the new WMAN2 colour options. Just click on an item and make a
   selection from the list.
   The first menu will show the official item number and name in the System
   Palette Reference Table and also the current colour for the item.
   Then choose the colour range you want to pick your new colour from.

   You can change any of the 'Favourite' colours in the 16 small windows by
   right-clicking them with the mouse or striking the ENTER-key (DO). A small
   RGB-Mixer will appear where you can define any colour you wish.
   The defined colour can then be saved as one of your 16 standard colours.

   You can also pick colours from the basic QL colours, the predefined PAL
   colours, the current System colours, Grey shades or stipples made with the
   PAL colours (see chapter VIII).

   If you think you have chosen some beautiful colour combinations and
   fantastic 3D-borders, just click on APPLY and see the effect by opening
   a QPAC menu or a new QD or QSpread.

   When you are satisfied with your work, you can SAVE it as a new theme.

   The program will always start with the first System Palette colour
   configuration if no file name is configured. But of course you can LOAD
   another theme and make it the actual configuration by clicking APPLY.


 ----------------------------------------------------------------------------
IV)-SYSTEM-PALETTES and how to make a theme resident
 ---------------------------------------------------

   An APPLY in QCoCo lets you choose the System Palette 0, 1, 2 or 3.
   Thus all applications that are configured to use that colour scheme, are
   now changed by what you did in QCoCo.
   Most modern programs from J-M-S or Dilwyn Jones will be affected but many of
   the Just Words! programs have fixed colours, so won't change their looks.

   If you want to make a theme valid for a System Palette right from the
   startup of your system, you can put the following line in your boot file
   before you set up any buttons:

     EW win1_dev_setconf_bas;"win1_dev_themes_mytheme_thm,0"

     where 'win1_dev_' is the directory where your QCoCo files are located,
     setconf_bas is the small program that came with QCoCo,
     'mytheme_thm' is the theme you want, and '0' (or 1 or 2 or 3) is the
     system-palette to set.

   You can also edit the small program "setconfall_bas" and define your 4
   favourite themes all at once. Then add this line to your boot file:

     EW win1_dev_setconfall_bas


 ----------------------------------------------------------------------------
V)-WHAT-DO-YOU-SEE?
 ------------------

   All current 57 menu items can be changed. To see the whole list Hit the 3
   dashes above the Title item.
   Ink_1 is the same as "foreground", ink_2 stands for "middleground".

   The main window at the left will show an Outline with a Title item and the
   Loose item statuses, an Application window and it's menu item statuses.
   The big buttons to the right open sub-menus for all the other menu items.

   QCoCo will show all changes in its own menus but uses mostly Information
   Windows mimicking Loose Items and Application Windows, so small differences
   with other applications can happen.
   Also not all changes may be visible in other programs because they do not
   use all menu items or combine some colour settings.
   The colour selection menu and the RBG-Mixer of QCoCo don't change their
   colours either because they use fixed colours.

   If you don't see any change or an old colour still shines through, you
   can do a "Save theme", followed by a "Reset" to redraw the QCoCo window.

   Some colours in other, already open, applications have to be redrawn, which
   should happen when you buttonise and wake the application otherwise you may
   have to restart it.

   The best applications to see changes are:

   QPAC2 menus: Files, Jobs, Channels etc.
     for nearly all changes.
   QD and Menu_Rext menus
     for information windows, tooltips and separator lines.
   QSPREAD
     for the indexes.
   SuQcess2
     which also uses most of the Menu_rext menus and lets you change its
     palette from within the program.


 ----------------------------------------------------------------------------
VI)-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.

 - QCoCo should be run in High Colour mode which is obvious.
   It will run in Low Colour mode 4 but then has limited functionality.
   No skin image can be set, some colour options and 3D-borders are blocked.
   But it can be used to interactively edit and save the default SMSQ/E
   Palettes which I think is easier than using MenuConfig on SMSQ/E itself.

 - The bmp skin option of version 1.5 didn't work on the Aurora. That's why I
   changed that to use the new big sprites in version 1.60+. Some solid sprites
   didn't work as expected on my own QXL, although QCoCo itself worked OK.
   This bug has been fixed for the QXL in SMSQ/E 3.15, so please update.

 - Aurora has a limited colour range, so RGB changes made there may look
   slightly different when viewed on QPC2, QXL or Qx0.

 - You cannot create RGB colours from scratch. A "basecolour_mfc" file as
   provided with the program must be loaded first (check Configuration).

 - Be careful with these 3D-borders: 1092,1093,1156,1157,1220,1221.
   They use at least 8 pixels of the width of the item window. That is why
   these can't be chosen for the Bar-Section, the fixed size is too small.
   Also other sub windows can be to small to use these and may then fail to
   show all the text in them. Especially the Buttons and Hint window may become
   unreadable.
   So always check with you applications if they are usable for that item.


 - Problem: The buttons of QPAC2 won't take the colours I want them to.
   Answer : If you have defined a Files menu like the following:

	    EXEP "Files";'\b 3 \n WIN1 \I win1_'
			  ----
	    then the parameter '\b 3' stands for the 'old' colour scheme.
	    Delete this parameter and everything should be fine.

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

	    NOTE: If at any other moment you get a Qlib error with the
	    C)ontinue option, you can key S)ave next, to save the current theme
	    and then key R)eset to redraw the main window.
	    You can also hit the Info item and then the QCoCo logo, instead of
	    selecting a new background hitting OK will redraw the main window.
	    Please report any other errors to me.


 ----------------------------------------------------------------------------
VII)-HINTS-AND-TRICKS
 --------------------

 - Always try different menus after having applied a change.
   Start a QPAC2 menu, click on the Files or the menu items. Have a look at
   the Jobs-, Rjobs-, SysDef menus etc. Open a new QD. This is the best
   way to get an impression of what has really changed.

 - Changing the looks of the QPAC2 buttons may not have an immediate effect.
   You have to click on them in order to see a new colour or a new 3D-border.
   You may even have to restart your QL with the option described in III.

 - Numbers are shown in the selection menus on the sixteen colours, as well as
   in the 3D-borders menu. These are the values you may use when configuring
   applications or when writing your own BASIC programs and make use of the new
   "WM_XXX" commands. For example you could give a window a dark pink colour,
   white ink and a 2 pixels wide 3D-border by writing:

     WINDOW 200,100,0,0: WM_PAPER 53462: WM_INK 65535: WM_BORDER 2,1024

   Especially the new 3D-borders will literally give your BASIC windows a
   completely - at least for the QL - new dimension.

   NOTE: The numbers shown in the RGB-Favourites menu are already converted to
   15-bit WMAN2 colours but the numbers shown in the RGB-Mixer are true 24-bit
   values. The _mfc file also stores these 24-bit values.


 ----------------------------------------------------------------------------
VIII)-BRIEF-QL-COLOUR-THEORY
 ---------------------------

   The colour you see after a PAPER command depends on the colour mode your
   SMSQ/E program is using at that moment.

      COLOUR_QL    : PAPER 15 : REM >>> a yellow dot on white

   This produces the colours (0-255) as we know them from the original QL.
   You can change the basic 8 colours with new RGB values using the
   PALETTE_QL command.

      COLOUR_PAL   : PAPER 15 : REM >>> a light green

   These are reference numbers (0-255) to predefined colours as used for
   Aurora's mode 16 but you can change the colour for each number with a new
   RGB value using the PALETTE_8 command.

      COLOUR_NATIVE: PAPER 15 : REM >>> a dark blue

   (0-65535) 16-bit RGB values for QPC2, QXL & SMSQmulator (mode 32).
     On Qx0 (mode 33) other values may produce very different colours.
   (0-255) 8-bit RGB values for mode 16, 15 is purple (Plum) on Aurora and some
     other SMSQ/E platforms but it doesn't work well prior to version 3.16, so
     update asap.

      COLOUR_24    : PAPER 15 : REM >>> a very very dark blue

   A 24-bit RGB value that will be translated internally to a native value for
   any High Colour hardware it's running on (red *65536 + green *256 + blue).

   QCP makes 24-bit RGB colours, stored in the "basecolours_mfc" file.
   QCoCo uses the same "basecolours" format and new RGB colours can be made
   with the RGB-Mixer option (DO on a 'Favourite' colour).

   THEMES
   The theme files created by QCoCo contain a list of colours as 16-bit hex
   values, that can be used by the WM_XXX commands of WMAN2.
   There are seven types that should give the same result with WM_PAPER on any
   system:

   1.	  0 -	255, $0    - FF  : give the original QL colours
   2.	256 -	511, $100  - 1FF : give the PAL colours as defined for Aurora
   3.	512 -	767, $200  - 2FF : are reference numbers to the System Palette
   4.	768 -  1023, $300  - 3FF : give 256 shades of grey
   5.  1024 -  1279, $400  - 4FF : the new 3D-borders, but only 28 are used!
   6. 16384 - 32767, $4000 - 7FFF: stipple two of the first 64 PAL colours
   7. 32768 - 65535, $8000 - FFFF: RGB, where 5 bits are used for each colour

   Currently 57 menu items are defined for the System Palettes (512-568).
   When you Hit the dashes above the Title item in QCoCo you can see the whole
   list with the current colour numbers.

   QCoCo 1.60+ lets you choose from the 'Favourites' (7) and the ranges 1 to 6.

   For the System option (3) you do not select from reference numbers but from
   the actual colours associated with them in the current active theme. New
   colours picked from other ranges are added to this internal System list.

   NOTE: Many programmers use the range-3 numbers for most of their menu items.
   That's why these programs are able to adapt to the colours from the themes.
   You could even use these reference numbers in a _thm file but you must be
   sure that those numbers point to an item for which an actual colour is set.
   For example: if the main window background is set to a colour, the Info
   window can be given the same background by setting it to $0201.
   You cannot set these 'shortcuts' in QCoCo but if a loaded theme uses such
   settings, these will only be changed if you change the colour for that item.
   As the theme colours are saved as hex values you could edit a _thm file in
   an ascii editor if you know what you're doing.

   For the stipple option (6) you have to choose a type and then pick a PAL
   colour as for option 2, twice.

   'RGB-Favourites' colours are converted to the range in 7, check the colour
   numbers as printed over the colours themselves in this menu.


 ----------------------------------------------------------------------------
VIII)-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 help and support intensively.
   He also provided the HSV routines used in the Mixers of QCP and QCoCo 1.61.
   Many, many thanks, Marcel!

   Wolfgang Lenerz made the bitmap-extensions that were used in QColour, the
   predecessor of QCP and early versions of QCoCo. It added a new dimension to
   QL programming.
   Although the BMP options have now been replaced by sprites in version 1.60,
   the principle of using skins remains the same.
   Also his articles in QL Today about the new GD2 and WMAN2 possibilities were
   of great help.

   Also thanks to:
   Thierry Godefroy, for finding some bugs.
   Dilwyn Jones, for the sorting routine.
   Franois van Emelen, for testing.

   Comments and ideas for improvements are always welcome:
   szx83@upcmail.nl

   Look for the System Palette Reference Table and possible updates at:
   http://members.upc.nl/b.spelten/ql/

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

   Wolfgang Uhlig, Bob Spelten jr
   23.05.13
