                       The Online Help file for

                                 COPS

                             Version 1.0
                          23. September 1996

                                  by

                  Thomas Much, Sven & Wilfried Behne


Contents
========

 1  Introduction

 2  Licence Conditions

 3  Legal Notice

 4  Installation

 5  Operation
    5.1  CPX Popup
    5.2  COPS Popup
         5.2.1  Settings

 6  Configuration Examples

 7  Common problems

 8  History

Appendix
========

 A  Questions

 B  For Programmers



1  Introduction
***************

COPS is a server for control panel extensions (CPX) found with many
recent Atari applications. COPS is a replacement for the original
XCONTROL.ACC which is included in more recent TOS versions.

COPS has the following features:

    You can simultaneously display as many CPX modules as there are.

    COPS remembers the position of each individual CPX module.

    CPX modules can have larger windows - COPS adjusts window sizes
     to suit the resource.

    COPS supports long file names: CPX modules can, for example, be
     loaded from a folder named "Control Panels". Spaces can be used
     in folder and file names ("MagiC configuration.cpx"). (*)

    Low Memory requirements.

    COPS runs on 68040 processors (with copyback cache switched on)
     or on any processors with relatively large code and data caches
     (e.g. 68k emulation on PowerPC computers).

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

(*) Please note that standard or alternative desktops may not support
space characters in file names ( MAGXDESK does, EASE doesn't).



2  Licence Conditions
*********************

COPS is Freeware. The program may only be copied and passed on freely
if it is left unchanged and contains all relevant files. Commercial
sale of COPS is strictly prohibited.

The COPS package contains:

    COPS.ACC (Program)

    COPS.HYP (Hypertext)

    COPS.REF (Reference to the Hypertext)

    COPSICN.RSC (Colour and B/W icons for COPS)

    WDIALOG.PRG (System extension)

    COPS.HTM (Hypertext in HTML format)

Copyright  1996 by Behne & Behne Systemsoftware GbR. All rights
reserved. Translation by Howard Scarr.

Behne & Behne Systemsoftware GbR
Lindenkamp 2a
31515 Wunstorf

Tel/Fax: +49-(0)5031-8629



3  Legal Notice
***************

Despite careful development and comprehensive testing, we do not
guarantee that this software will always run without any errors
whatsoever. We do not accept liabiblity for immediate or subsequent
damage. Use COPS at your own risk!

Many products mentioned in this Hypertext are registered trademarks
of the respective companies. The fact that these are printed without
special reference to the manufacturers does not imply that the
products are free of third-party rights.

This Online Help was generated using UDO5 and ST-Guide.



4  Installation
***************

    Copy COPS into the root directory of your boot partition/drive.

    If you set the environment variable HOME, the INF file will be
     saved in this directory, otherwise it will be saved in the
     directory from which COPS has been loaded.

    If neither MagiC 4 (or higher), MagiCMac 1.2.7 (or higher) or
     MagiC-PC is installed in your system, you should copy the file
     WDIALOG.PRG into your AUTO folder.

    If your desktop program is able to send VA_START messages you
     should register COPS for the file type "*.CPX".

    Copy COPS.HYP and COPS.REF into the ST-Guide "GUIDES" folder.

    If you use MagiC, MagiCMac or MagiC-PC you can start COPS at any
     time by double clicking on the icon (COPS then registers itself
     in the ACC list). If this doesn't work you will have to reboot
     the system.

COPS expects CPX files to be in the path "C:\CPX\" by default.
However, you can designate a different path (e.g. "Control Panels")
from within the COPS Popup.

Note:

    COPS can be started as a normal program. You will find several
    practical examples in the section "Configuration Examples" -
    these illustrate how to configure COPS for your requirements.



5  Operation
************

If you are running COPS as an accessory, you will see the words
"Control Panels" in the accessory list. Clicking on this opens the
COPS window containing icons which represent all the CPX modules
which are currently available. Operation with the mouse:

    Single click left on an icon: Select the icon (also with Shift)

    Rubber band (also with Shift)

    Single click right on an icon: CPX Popup

    Single click right within the window: COPS Popup

    The current positions of windows and icons are saved on exit..

Note:

    If your desktop can send the VA_START message and COPS has been
    registered as application for "*.CPX" modules, you can start any
    CPX modules directly from the desktop by double-clicking on the
    icons.


5.1  CPX Popup
==============

Clicking right on an icon within the COPS window opens a popup menu
containing the following:

    Open: Opens and "tops" the corresponding control panel.

    Deactivate: Changes the extension of the file to CPZ.

    Activate: Changes CPZ files back to CPX.

    Info: Displays the file name, ID, version and configuration
     flags of modules.


5.2  COPS Popup
===============

Clicking right within the (white area of the) COPS window opens a
popup containing the following:

    About COPS: Version and copyright information.

    Settings: Used for setting the CPX path and other options.

    Reload: Searches the designated folder for CPX modules and
     redraws the COPS window accordingly.

    Tidy Up: Sorts all the icons in the COPS window.

    Select All Selects all icons in the COPS window.

    Help: Opens this online help.


5.2.1  Settings
---------------

    CPX Path: Pressing this button opens a file selector with which
     you can find the path where you keep all your CPX modules.

    Iconify at start: Causes COPS to appear only as an icon on the
     desktop after it is loaded. Double clicking on this icon opens
     the usual COPS window.

    Double click activates CPZ: Deactivated modules (those with the
     extension "CPZ") will be activated by double clicking on the
     icon. The extension will change to "CPX" and the module will be
     loaded.

    Terminate after xx minutes: COPS starts modules (e.g. for the
     colours or the serial port settings) and terminates according to
     your specifications. This option is only useful within a
     multitasking environment - MagiC users copy COPS.APP itself or
     create a symbolic link (not possible with EASE) in the APPS or
     START folder.



6  Configuration Examples
*************************

Here is a list of tips on how to configure COPS sensibly under
different conditions:

COPS under TOS with standard ATARI desktops:

    Run COPS as an accessory (".ACC"). You will need to install the
     system extension WDIALOG.PRG.

COPS under TOS with desktops which are able to send the VA_START
message (Gemini, Thing, ...):

    Run COPS as an accessory (".ACC"). As above, WDIALOG.PRG must be
     installed. Register COPS for files with the extension "*.CPX".
     You can now start modules from the desktop by double clicking on
     them.

COPS under MagiC / MagiCMac / MagiC-PC:

    If your system is short of memory you should rename the file
     COPS.ACC as COPS.APP and copy it into the APPS or START
     directory. Start COPS, call the COPS popup and select the entry
     "Terminate after xx minutes" from the Settings dialog. Quit
     COPS.

     Register COPS as application for "*.CPX" files and confirm that
     COPS recognizes the VA_START message. You can now assign an icon
     for each module in MAGXDESK.

     COPS will be loaded every time the system loads, CPX modules are
     started (which can carry out the required initialisation
     routines) and terminated according to your specifications. You
     can start any CPX files directly from the desktop by simply
     double clicking on the icons.

    If you want to run COPS as an accessory you should register it
     for "*.CPX" files in the desktop and also confirm that COPS can
     handle the VA_START message.

     Again, control panels can be assigned icons which allows you to
     start modules from the desktop.



7  Common problems
******************

    Selected icons don't look very nice because the icon mask is
     missing in the CPX modules (Atari thought they would be
     unnecessary?).

     Alternative:

         You can assign a (colour) icon in MagiC, MagiCMac or MagiC-
         PC for each CPX module and start the control panels from the
         desktop. See also "Configuration Examples" above.

    The AUTO folder application ALICE sometimes causes the system to
     crash. If ALICE is installed and COPS (or other programs such as
     FONTNAME or MAKEPRN) crash, you should deactivate ALICE.

    If you are running an older TOS version then you should close
     all modules before you start a new program or terminate a
     program. For the technically-minded: An error in TOS prevents
     COPS from being able to deallocate some structures, which in the
     long run is a sure candidate for crashes.

     Solution:

         Use MagiC, MagiCMac or MagiC-PC!

    Clicking on a scroll arrow in the COPS window (running as an
     accessory under TOS 3.06) doesn't do anything. This is a well-
     known bug in TOS 3.06..

    If you have a Falcon and run TOS 4.01, you will see that the
     size of the sliders in the COPS window is wrong. This is a well-
     known bug in TOS 4.01.

    If you are running TOS 4.01 on your Falcon you shouldn't attempt
     to open more than seven windows at the same time, otherwise TOS
     destroys some internal structures without comment. (**)

     Solution:

         Use MagiC 4 or 5 as operating system.

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

(**) It is not yet known whether this fault is restricted to TOS
version 4.xx!



8  History
**********

Version 0.10 - 0.11  (08.02.96 - 10.02.96)

    Idea and Conception (Thomas)

Version 0.12 - 0.75  (22.08.96 - 12.09.96)

    "It should only take about a week" - Sven gets down to
     business...

Version 0.80 - 0.99  (13.09.96 - 15.09.96)

    Adjusted to restrictions and faults in TOS

Version 1.00  (16.09.96)

    First version let loose on the general public.

Version 1.02  (19.09.96)

    Release of english COPS version.

Version 1.03  (23.09.96)

    Increased stack size to avoid problems with the Mac file system
     (esp. on Power Macs).




A  Questions
************

 What does "CPX" stand for?

     "CPX" is short for Control Panel eXtension. Activated control
     panels have the extension "CPX" and deactivated ones "CPZ".

 Why is COPS called "COPS"?

     "COPS" is short for COntrol Panel Server.

 What is this "VA_START" message?

     The operating system and other programs communicate via
     "messages": If, for instance, you called this page with a mouse-
     click, the operating system has sent a message to the display
     program, informing it that "the left mouse button has been
     pressed".

     A program already in memory can be requested via "VA_START" to
     load a file. If you are interested, you can read more about this
     message and the AV_Protocol in the GEMINI (alternative) desktop
     manual.

 What does "WDIALOG.PRG" do?

     WDIALOG is a compact system extension which, apart from window
     dialogs, popups and listboxes, also contains a comprehensive
     selection of fonts. These functions are integrated into the
     multitasking system MagiC since version 4.

     WDIALOG allows users of older operating systems access to these
     features. COPS isn't the only program which uses WDIALOG - the
     NVDI tools "FONTNAME" and "MAKEPRN", the spreadsheet program
     "Texel" and also "ArtWorx" make use of WDIALOG functions.



B  For Programmers
******************

 How do I recognize COPS?

     If you define cpx_init() as

        CPX_INFO * cdecl cpx_init( XCPB *xcpb, LONG magic, LONG version );

     you can determine whether the CPX is running under COPS or
     XCONTROL by way of the parameters <magic> und <version>:

     WORD is_COPS( LONG magic, LONG version )
     {
        if (( magic == 'COPS' ) && ( version >= 0x10000L )) /* COPS? */
           return( 1 );
     
        return( 0 );                                     /* XCONTROL */
     }

     If COPS has been recognized, the CPX can draw a 512 * 384 pixel
     object tree and send it to Xform_do().

     Also, you have the following extension for cpx_call():

        WORD cdecl cpx_call( GRECT *work, DIALOG *dialog );

     <dialog> is a pointer to the window dialog structure. The window
     dialog is opened by COPS after cpx_init() with wdlg_create() and
     wdlg_open(). The GRECT <work> and the object tree are outside
     the visible area of the screen until the first call to
     Xform_do() or until returning from cpx_call().




