

Introduction to the AmigaOS 3.5 (V44) Release Notes
***************************************************

   *PRELIMINARY* - last revised on 24 October 1999

   Copyright (C) 1999 Amiga, Inc. All rights reserved.

   This document describes the relevant changes and new features
introduced in AmigaOS 3.5 (release V44) since AmigaOS 3.1 (release V40).
Developers are invited to read this guide carefully and check their
products against the issues hereby discussed.

   This AmigaGuide file is generated by Makeinfo-1.68. It is formatted
for viewing with AmigaGuide V40 or later. Please send comments,
suggestions and corrections for this text to Bernardo Innocenti
<bernie@cosmos.it>.

Determining the Workbench version
*********************************

   An important point to mention is how to determine if a system is
running V44 instead of V40 or an earlier Workbench release. The
recommended approach is to open `version.library', and check its
version.  For example:

     struct Library *VersionBase;
     
     if (VersionBase = OpenLibrary("version.library", 0))
     {
         if (VersionBase->lib_Version >= 44)
         {
             /* user is running at least V44 Workbench */
         }
         else
         {
             /* user is running at most V37 Workbench */
         }
     }
     else
     {
         /* can't tell what the user is running, assume the minimum version
          * that your application supports
          */
     }

The above technique lets you determine which general version is in use
for the disk-based software.  Never assume this is a reflection of
every other library in the system.  For example, if you need features
of the `asl.library' that are only present since V44, you must
explicitly check the version of `asl.library' before using them. The
same goes for all other system libraries.

The Workbench
*************

   Workbench got rewritten for OS 3.5. The `workbench.library' API has
been extended with several new vectors to provide greater interaction
with Workbench-aware applications. There are now official (and clean)
ways for third party Workbench enhancers to gather information on the
current Workbench status, start programs in "Workench mode" and even
control some aspects of the Workbench user interface from other
applications.

   Of course the Workbench supports the new color mapped icons and other
features provided by the new `icon.library'. *Note Icon Library::..

Launching Workbench applications
================================

   The new OpenWorkbenchObject() can be used to execute a program as if
the user had double-clicked on its icon. This is expecially useful for
commodities that put up toolbars or menus to start other applications.

   Before V44, a similar functionality was made available by third-party
tools such as the `wbstart.library' and the `WBStart-Handler'.

   While third-party Workbench launchers are still supported in V44,
applications should be updated as soon as possible to use
OpenWorkbenchObject() when they detect a `workbench.library' whose
version is greater or equal to V44.

   Future versions of the Workbench may extend the WBStartup structure
to add new functionality. Then, the hack of sending faked WBStartup
messages to process's pr_MsgPort *WILL STOP WORKING*.

   OpenWorkbenchObject() can also open drawers. This feature can be
useful in some Workbench enhancer commodities.

   Note that `OpenWorkbenchObject()' fails if it is invoked while the
Workbench program is not running. This behaviour prevents usage of this
function by Workbench replacement applications. Workbench replacements
should launch applications autonomously. After all, the cleanest way to
duplicate Workbench functionality is providing a compatible replacement
of the workbench.library instead of patching most of its vectors.

Controlling the Workbench
=========================

   Another new function useful for commodities that extend the basic
Workbench functionality is `WorkbenchControl()'. This function provides
several tags to query or modify global Workbench parameters or local
icon options. Consult the autodocs for a detailed description of the
available tags.

AppWindow icon drop zones
=========================

Adding drop zones
-----------------

   Once it is created, Workbench will allow the user to drop an icon
anywhere inside an `AppWindow', regardless of whether the icon was
dropped on an area designated for dropping icons on or not. With
`AddAppWindowDropZoneA()' you can tell Workbench which `AppWindow'
areas are suitable for dropping icons on.

Drop zone `AppMessage's
-----------------------

   Once an `AppWindow' has a drop zone installed, Workbench will send a
new type of `AppMessage' to your port if icons are dropped on a drop
zone. Instead of `AMTYPE_APPWINDOW' type messages you will receive
`AMTYPE_APPWINDOWZONE' messages. In fact, you will no longer hear any
`AMTYPE_APPWINDOW' type messages since Workbench will allow users to
drop icons only on drop zones.  Be prepared to handle this.

   Adding a drop zone to an AppWindow does not guarantee that only
`AMTYPE_APPWINDOWZONE' type messages will arrive at your message port.
In fact, the user may be able to drop an icon on the window before the
first drop zone is installed. Be prepared to handle this.

Drop zones priority
-------------------

   Workbench checks drop zones in the order in which they were added to
the `AppWindow'. Thus, if two zones overlap, the zone that was added
first will be reported as hit.

   An `AppWindow' starts out with its entire area available for
dropping icons on. Thus, you may receive `AppMessage's for icons
dropped upon your `AppWindow' before you have added the first drop zone
to it. Be prepared to handle this.

Drop zone hooks
---------------

   Using the `WBDZA_Hook' tag, you can set a hook that will be invoked
whenever the mouse enters or leaves your drop zone area. Your hook will
be called with the following parameters:


     result = hookFunc(hook,reserved,arm)
       D0               A0     A2     A1
     
     LONG hookFunc(struct Hook *hook, APTR reserved,
                   struct AppWindowDropZoneMsg *adzm);
     
     struct AppWindowDropZoneMsg
     {
         struct RastPort * adzm_RastPort;    /* RastPort to render into. */
         struct IBox       adzm_DropZoneBox; /* Limit your rendering to this area. */
         ULONG             adzm_ID;          /* \ These come from straight */
         ULONG             adzm_UserData;    /* / from AddAppWindowDropZoneA(). */
         LONG              adzm_Action;      /* See below for a list of actions. */
     };
     
     #define ADZMACTION_Enter (0)
     #define ADZMACTION_Leave (1)

   The `reserved' parameter will be set to `NULL'.  For future
enhancement, make sure that your hook function always returns `NULL'.

   The drop zone message contents are as follows:

`adzm_RastPort'
     A pointer to the `RastPort' to render into. Typically, this is the
     `RastPort' of the window the drop zone is attached to.

`adzm_DropZoneBox'
     This member describes the position and size of the drop zone.  The
     zone is guaranteed to be a valid area, i.e. the Width and Height
     will both be greater than 0 and the Left/Top will be well within
     the bounds of the window containing the drop zone.

`adzm_ID'
`adzm_UserData'
     These two come straight from the values you passed as the `id' and
     `userData' parameters to `AddAppWindowDropZoneA()'.

`adzm_Action'
     Depending upon whether the mouse has just entered or left the drop
     zone area, this variable will be set to `ADZMACTION_Enter' or to
     `ADZMACTION_Leave'. Any other values for `adzm_Action' should be
     ignored.

   When the mouse enters the drop zone, do your drop zone area
highlighting. When the mouse leaves the drop zone, remove any
highlighting done in the previous `ADZMACTION_Enter' pass.

   Note that the mouse leaving your drop zone box does not imply that
no icons will be dropped on it. You may still receive a notification
lateron, telling you that your drop zone had icons dropped on it.  The
hook function is solely for highlighting and unhighlighting the drop
zone area.

   A final word of warning: when your hook code is called, you must
limit your rendering to simple drawing operations from
`graphics.library'; if you do anything complex that involves Intuition
locking and unlocking the display, such as refreshing gadgets or
locking `IntuitionBase', you will deadlock the operating system. You
have been warned!

Removing drop zones
-------------------

   Use `RemoveAppWindowDropZone()' to remove a drop zone previously
added with `AddAppWindowDropZone()'. Due to the asynchronous nature of
Workbench/user interaction, you may receive `AppIcon' drop zone
messages for zones that you have just removed. These messages may
arrive in the time between your code calling `RemoveAppWindowDropZone()'
and Workbench responding to the drop zone removal request. Be prepared
to handle this. Once a drop zone is removed, it will generate no new
`AppMessage's.

   Before the `AppWindow' is removed, all its drop zones will be removed
first. There is no need for you to call `RemoveAppWindowDropZone()' for
every single one.

New AppIcon functionality
=========================

Responding to menu commands
---------------------------

   As of Workbench V44, it is possible to invoke menu actions for
`AppIcon's just like they were normal icons. You have to tell Workbench
which menu items your icon responds to using the tag item list you
provide to `AddAppIconA()'. When one of the supported menu items is
invoked, you will receive an `AppMessage' with the `am_Class' entry set
to a value out of `AMCLASSICON_Open'..`AMCLASSICON_EmptyTrash',
corresponding to the menu item used.

   The following `BOOL' tags are provided by `AddAppIconA()' to control
which menu commands are supported by an `AppIcon':

`WBAPPICONA_SupportsOpen'

`WBAPPICONA_SupportsCopy'

`WBAPPICONA_SupportsRename'

`WBAPPICONA_SupportsInformation'

`WBAPPICONA_SupportsSnapshot'

`WBAPPICONA_SupportsUnSnapshot'

`WBAPPICONA_SupportsLeaveOut'

`WBAPPICONA_SupportsPutAway'

`WBAPPICONA_SupportsDelete'

`WBAPPICONA_SupportsFormatDisk'

`WBAPPICONA_SupportsEmptyTrash'
Custom AppIcon rendering hook
-----------------------------

   The new tag `WBAPPICONA_RenderHook' takes a pointer to a `struct
Hook' that will be invoked when rendering your AppIcon. With this hook
and `WorkbenchControlA()' you can create dynamic or animated
`AppIcon's. Your hook will be called with the following parameters and
has to return a result value:


     result = hookFunc(hook, reserved, arm)
       D0               A0     A2      A1
     
     LONG hookFunc(struct Hook *hook, APTR reserved,
                   struct AppIconRenderMsg *arm);
     
     struct AppIconRenderMsg
     {
         struct RastPort *   arm_RastPort;
         struct DiskObject * arm_Icon;
         STRPTR              arm_Label;
         struct TagItem *    arm_Tags;
         WORD  arm_Left;
         WORD  arm_Top;
         WORD  arm_Width;
         WORD  arm_Height;
         ULONG  arm_State;
     };

The `reserved' parameter will be set to `NULL'. The render message
contents are as follows:

`arm_RastPort'
     A pointer to the RastPort to render into.

`arm_Icon'
     A pointer to the Icon to be rendered.

`arm_Label'
     A pointer to the label text to be printed below the icon.

`arm_Tags'
     Further control tags which you should pass on to
     `icon.library/DrawIconStateA()', should you call this routine.

`arm_Left'
`arm_Top'
     Rendering origin; note that these coordinates DO NOT take the
     embossing border sizes into account.

`arm_Width'
`arm_Height'
     Size of the Icon's image area; you should limit your drawing to
     this area.

`arm_State'
     An icon drawing state, such as used by
     `icon.library/DrawIconStateA()'.

   Note that all the data in the render message is read-only.

   If your hook code returns `TRUE', the `AppIcon''s regular image will
be drawn. If your code returns `FALSE', the regular image will not be
drawn; this allows you to do all the icon's on-screen rendering with
the exception of the icon image used when dragging the icon on the
screen.

AppIcon positioning
-------------------

   The new `WBAPPICONA_PropagatePosition' tag allows the AppIcon's
position to be propagated back to the original `DiskObject' you passed
to `AddAppIconA()'. By default, Workbench will make a copy of that
`DiskObject''s icon imagery, allowing the application to free the it.
But if you specify `WBAPPICONA_PropagatePosition,TRUE', Workbench will
assume that you will not free the `DiskObject' and that the `AppIcon''s
current position should be stored in its `do_CurrentX/do_CurrentY'
members.

AppIcon selection
-----------------

   The new tag `WBAPPICONA_NotifySelectState' causes the application to
be be notified whenever the AppIcon becomes selected or unselected.
You will hear only state transitions, i.e. changes from selected to
unselected state and the other way round. On a state transition you
will receive `AppMessage's with the `AppMessage->am_Class' member set
to `AMCLASSICON_Selected' or `AMCLASSICON_Unselected', respectively.

Summary of new functions in workbench.library
=============================================

`BOOL OpenWorkbenchObjectA(STRPTR name,struct TagItem *tags)'
     Open a drawer or launch a program as if the user had
     double-clicked on its icon.

`BOOL CloseWorkbenchObjectA(STRPTR name,struct TagItem *tags)'
     Close a drawer as if the user had clicked on the window close
     gadget.

`WorkbenchControlA(name,tags)'
     Query or modify global Workbench parameters or local icon options.

`struct AppWindowDropZone * AddAppWindowDropZoneA(struct AppWindow *aw, ULONG id, ULONG userData, struct TagItem * tags)'
     Designate an `AppWindow' area as suitable for dropping icons on.

`BOOL RemoveAppWindowDropZone(struct AppWindow *, struct AppWindowDropZone *)'
     Attempt to remove a drop zone from an `AppWindow'.

`BOOL ChangeWorkbenchSelectionA(STRPTR name,struct Hook *hook, struct TagItem *tags);'
     Change the selection states of icons displayed by Workbench.

`BOOL MakeWorkbenchObjectVisibleA(STRPTR name,struct TagItem *tags)'
     Change a Workbench window in such a way as to make a particular
     icon visible.

The Icon Library
****************

   The `icon.library' has been enhanced to support palette mapped
icons. The icon file format has been extended in a backwards compatible
way to support palette mapped images as well as old-style images. This
means that V44 icons can contain TWO image sets: the old-style planar
images (for normal and selected states) and the new style palette
mapped images.

The New Palette Mapped Icons
============================

   The `icon.library' has been enhanced to support palette mapped
icons. The icon file format has been extended in a backwards compatible
way to support palette mapped images as well as old-style images. This
means that V44 icons can contain TWO image sets: the old-style planar
images (for normal and selected states) and the new style palette
mapped images.

   New API calls are provided to retrieve the V44 image data.  The
`GetDiskObject()' and `GetDiskObjectNew()' calls are now declared
obsolete: they are still supported only for backwards compatiblity,
therefore they don't provide a way to access the new palette mapped
images(1).

   Applications which manipulate icons should be adapted to use the new
`GetIconTagList()'. This new function is a superset of
`GetDiskObject()': it still returns a pointer to a pointer to a `struct
DiskObject', but it provides greater control by means of several
taglist parameters.

   The defaults are to load and automatically remap the new style
images embedded into the icon. The `ICONGETA_Screen' tag specifies
which Screen the icon is to be displayed on.  See the
`GetIconTagList()' AutoDoc for more information.

   The new `icon.library/IconControlA()' call allows the applications
to retrieve and change any of the extended icon attributes including
the palette and the imagery.

   ---------- Footnotes ----------

   (1) Actually, this isn't completely true: the `struct DiskObject'
really contains the new images in its private data. The only way to
retrieve it is by calling `DupDiskObject()' and passing the tag
`ICONDUPA_ActivateImageData'. This trick is used by the Workbench as a
workaround to display the new style image in AppIcons provided by
non-V44-aware applications.

Support for Workbench enhancers and replacements
================================================

   The new `icon.library/IconControlA()' call provides a way for
applications to change the default parameters used by the
`icon.library' when reading, remapping, drawing and saving icons.

   This new functionality obsoletes most of the Workbench patches that
have been around before OS 3.5. There are now documented (and clean)
ways to disable icon borders and to install a hook to choose default
icons for icon-less files.

   For icon editors and other applications that need to create fresh new
icons, the `NewDiskObject()' function provides a way to create and
initialize a `DiskObject' structure. The old official way to do this
was to to get a default icon with `GetDiskObjectNew()' or even create
the structure manually. The latter method is now considered *OBSOLETE*
and `VERY SYSTEM UNFRIENDLY'. The V44 `icon.library' contains
compatibility code to distinguish between real `DiskObject's and fake
`DiskObject's created by unfair applications. These hacks will stop
working once the compatibility code is dropped for future versions of
the `icon.library'.

About NewIcons
==============

   This extended icon format introduced in OS 3.5 duplicates and
obsoletes the features previously provided by the third party NewIcons
patch. Unlike NewIcons, the V44 color mapped icons do not encode the
image data in the icon tooltypes, so the new icon format is both faster
and more compact.  The `newicon.library' V40 can still load V44 icons
and decode the NewIcon images encoded in the tooltypes, but it can't
access the new V44 palette mapped images.

   The V44 Workbench has compatibility code to decode NewIcons using
the `newicon.library', therefore it is no longer necessary to start the
`C:NewIcon' program from the `Startup-Sequence' (1). This feature is
active by default, but it can be switched off using the Workbench
preferences editor.

   Once the migration to the new color mapped icon format will be
complete, future versions of the Workbench will drop NewIcon
compatibility.  A future version of `newicon.library' could be enhanced
to read the V44 image data as well as the original NewIcons format to
support old applications that have not been updated to the new V44 API.
As of this writing, such version of the `newicon.library' is not yet
available.

   The choice of using a different scheme for palette mapped images
instead of conforming to the de-facto standard set by NewIcons was
necessary because the `newicon.library' API had a number of limitations
and inconsistencies which couldn't be worked around straightforwardly.
Programmers are therefore urged to adapt their applications to the new
`icon.library' API as soon as possible.

   ---------- Footnotes ----------

   (1) In fact, it is strongly discouraged because it installs patches
on the `icon.library' with no support for the new extensions.

Drawing icons in applications
=============================

`DrawIconStateA()'
------------------

   The V44 `icon.library' provides functions to support applications
which need to display icons in their own GUI. These include icon
editors, `WBInfo()' patches and full Workbench replacements. The
pre-V44 method to draw an icon inside a window was to manipulate the
images embedded into the icon directly. As of V44, this technique is
strongly discouraged.

   The new `icon.library/DrawIconStateA()' function provides the same
functionality in a straightforward way. Shall the icon appearance be
changed with future extensions of the `icon.library', your application
will pick them up automatically.

`LayoutIconA()'
---------------

   The `icon.library' supports drawing icons on any screen (not just on
the Workbench screen). For these reason, icon imagery can be loaded into
memory and then remapped at a later time by calling `LayoutIconA()'.

   `LayoutIconA()' is called implicitly by `GetIconTagList()' (1). The
icons are automatically remapped for display on the screen selected
using `IconControlA()'.  This could be undesiderable when your
application wants to display the icon on another screen.

   Note that `LayoutIconA()' allocates shared pens from the passed
screen using the `graphics.library/ObtainBestPen()' function.  These
pens will be released when the icon is disposed (with
`FreeDiskObject()') or when the icon is remapped again by
`LayoutIcon()'. It is *VERY IMPORTANT* that your custom or public
screen is not closed until there are still icon objects remapped for
it. See the `LayoutIconA()' AutoDoc for possible workarounds.

   ---------- Footnotes ----------

   (1) To prevent this from happening, you must explicitly set the
`ICONGETA_RemapIcon' tag to FALSE.

Summary of new functions in icon.library
========================================

`struct DiskObject *DupDiskObjectA(struct DiskObject *icon, struct TagItem *tags)'
     Create a duplicate of a `DiskObject' in memory. It can also be
     used to create an extended (`native') `DiskObject' data structure
     from an existing, traditional format `DiskObject'.

`ULONG IconControlA(struct DiskObject *, struct TagItem *)'
     Modify and query icon and icon.library options.

`VOID DrawIconStateA(struct RastPort *rp, struct DiskObject *icon, STRPTR label, LONG leftEdge, LONG topEdge, ULONG state,struct TagItem *tags)'
     Draw an icon as if it were an image; if a label is provided, it
     will be printed below it.

`BOOL GetIconRectangleA(struct RastPort *rp, struct DiskObject *icon, STRPTR label, struct Rectangle *rectangle, struct TagItem *tags)'
     Calculate the size of the area icon rendering would affect.

`struct DiskObject *NewDiskObject(LONG type)'
     create an *empty* `DiskObject' structure, which has no image data
     associated with it. Still, all the necessary structures are in
     place, you just have to fill them in.

`struct DiskObject *GetIconTagList(STRPTR name, struct TagItem *tags)'
     Retrieve an icon that can belong to a file/drawer/volume or it can
     be a default icon.

`BOOL PutIconTagList(STRPTR name,struct DiskObject *icon, struct TagItem *tags)'
     Store an icon; which can belong to a file/drawer/volume or it can
     be a default icon.

`BOOL LayoutIconA(struct DiskObject *icon,struct Screen *screen, struct TagItem *tags)'
     prepare an icon for display, either on a specific screen or using
     a default colour palette. It is useful only for palette mapped
     icons.

`VOID ChangeToSelectedIconColor(struct ColorRegister *cr)'
     change the provided RGB colour value to make it suitable for use
     in an icon's select image.  This may involve darkening or toning
     the colour.

The ASL Library
***************

   The `asl.library' has been improved in V44 to address a number of
localization, efficiency and GUI layout issues as well as fixing bugs.
For developers, there are also some new API extensions.

New Functions
=============

`VOID ActivateAslRequest(APTR requester)'
     Activate a modal requester from a different task context.

`VOID AbortAslRequest(APTR requester)'
     Attempt to tell the modal ASL requester provided to shut down and
     perform as if the user had clicked on the requester's window close
     gadget.

New Tags
========

`ASLFR_InitialShowVolumes (BOOL)'
     When opening the file requester, read the list of active volumes,
     do not read the contents of the specified drawer.

`ASLFR_SetSortBy (ULONG)'
`ASLFR_GetSortBy (ULONG *)'
     Criteria for sorting the file list. This must be one of:

        * `ASLFRSORTBY_Name' - sort by name (default)

        * `ASLFRSORTBY_Date' - sort by date

        * `ASLFRSORTBY_Size' - sort by size

     If `ASLFR_GetSortBy' is passed to AslRequest(), the file requester
     will store its current sort criteria in the ULONG pointed to by
     the tag before leaving.

`ASLFR_SetSortDrawers (ULONG)'
`ASLFR_GetSortDrawers (ULONG *)'
     Determines where drawers are placed in the sorted list; this must
     be one of:

        * `ASLFRSORTDRAWERS_First' - drawers appear before all other
          files (default)

        * `ASLFRSORTDRAWERS_Mix' - drawers are sorted along with the
          the other files

        * `ASLFRSORTDRAWERS_Last' - drawers appear after all other files

     If `ASLFR_GetSortDrawers' is passed to AslRequest(), the file
     requester will store its current sort drawer list placement in the
     ULONG pointed to by this tag.

`ASLFR_SetSortOrder (ULONG)'
`ASLFR_GetSortOrder (ULONG *)'
     Selects the order in which the list is sorted; this must be one of:

        * `ASLFRSORTORDER_Ascend' - smallest/oldest files first,
          largest/newest files last (default)

        * `ASLFRSORTORDER_Descend' - largest/newest files first,
          smallest/oldest files last

     If `ASLFR_GetSortOrder' is passed to AslRequest(), the file
     requester will store its current sort order in the ULONG pointed
     to by this tag.

`ASLFR_PopToFront (BOOL)'
`ASLFO_PopToFront (BOOL)'
`ASLSM_PopToFront (BOOL)'
     When set to TRUE, this tells ASL to bring the screen to the front
     the requester has opened on. (Default is TRUE).

The Picture Datatype
********************

   The V40 `picture.datatype' distributed with OS 3.1 had several weak
points and missing features which made it inadequate when the first RTG
systems with true-color support became available.  For this reason,
nowadays the original V40/V42 version has been obsoleted by third party
replacements featuring true-color support and other useful extensions.

   OS 3.5 integrates a rewritten `picture.datatype' whose API tries to
be as compatible as possible to these unofficial versions.

   The V44 `picture.datatype' works transparently with both
`CyberGraphX' and `Picasso 96'. It also integrates color reduction
algorithms to convert high/true-color pictures to palette-mapped
bitmaps. The API allows the programmer to choose among several
quantization and dithering techniques to get better quality or faster
conversion.

General concepts
================

* `palette-mapped'
     a picture, bitmap or screen is said to be palette-mapped when the
     color of its pixels must be determined by looking up a color
     palette containing the RGB triplets associated with an index
     value. The palette is also called CLUT (Color Look-Up Table).

* `direct-mapped'
     a picture, bitmap or screen whose pixels directly contain an RGB
     triplet. Direct-mapped pictures do not need a palette.

* `native bitmap'
     a bitmap in which the image data is represented by bitplanes in
     the native format of the Amiga chipset (OCS/ECS/AGA).

* `RTG bitmap'
     a bitmap with a custom pixel format which may not be accessed
     directly. Drawing into the bitmap must be performed through the
     functions provided by the `graphics.library' or by the RTG system.

Backwards compatibility
=======================

   For backwards compatibility, the unofficial V43 `picture.datatype'
implementations which were distributed with `CyberGraphX' and `Picasso
96' behaved just like the V42 and eariler implementations by default.
The picture returned to the application was stored in a native planar
bitmap, up to 8 bitplanes deep.

   In order to let the datatype allocate custom bitmaps (chunky 8bpp or
hi/truecolor), the application should set the PDTA_DestMode attribute
to PMODE_V43.

   This has changed as of V44. PMODE_V43 is now active by default.
Applications should never expect to get a native bitmap from the
picture.datatype unless they explicitly ask for PMODE_V42.

   The following summary shows the different behaviour kept by all the
known implementations of the `picture.datatype':

* `picture.datatype V40/V42 (OS 3.1)'
     PDTA_DestMode is ignored

* `picture.datatype V43 (CyberGraphX)'
     PDTA_DestMode defaults to PMODE_V42. The returned bitmap is always
     a planar one, with up to 8 bitplanes.

* `picture.datatype V43 (Picasso 96)'
     PDTA_DestMode defaults to `PMODE_V42'. However, the returned
     bitmap is *NOT* native.

* `picture.datatype V44 (OS 3.5)'
     PDTA_DestMode defaults to `PMODE_V43'. It can be explicitly forced
     to `PMODE_V42'.

   The V42 mode is retained in `picture.datatype' V44 for backwards
compatibility only. Use of the V42 mode in new applications is
*STRONGLY DISCOURAGED*. The V43 mode provides better performance for
both the internal operations carried out by the datatype and for most
bitmap to screen blitting operations.

New methods in unofficial V43 `picture.datatype'
================================================

`PDTM_WRITEPIXELARRAY'
     Transfer pixel data to the picture object in the specified format

`PDTM_READPIXELARRAY'
     Transfer pixel data from the picture object in the specified format

New tags in unofficial V43 `picture.datatype'
=============================================

`PDTA_SourceMode'
     Set the sub datatype interface mode

`PDTA_DestMode'
     Set the app datatype interface mode

`PDTA_UseFriendBitMap'
     Allocates the resulting bitmap as a friend bitmap

`PDTA_MaskPlane'
     NULL or mask plane for use with BltMaskBitMapRastPort()

New tags in V44
===============

`PDTA_WhichPicture'
     Index number of the picture to load

`PDTA_GetNumPictures'
     Get the number of pictures stored in the file

`PDTA_MaxDitherPens'
     Maximum number of colours to use for dithering

`PDTA_DitherQuality'
     Quality of the dithering algorithm to be used during color
     quantization

`PDTA_AllocatedPens'
     Pointer to the allocated pen table

The Installer program
*********************

   The latest pre-V44 release of the `Installer' was V43.2, distributed
on the Amiga Technologies FTP site.

Checking the Installer version
==============================

   If your installation script uses new features not available in
earlier versions of the `Installer', it is important to check the
variable @INSTALLER-VERSION before using these new features. This
variable will default to 0 with old versions of `Installer' like V1.24,
so it is safe and easy to check.  Please do not do an exact equality
check. Check for a minimum revision, just like with libraries.

Backtracing
===========

   Starting with V44 the `Installer' allows backtracing in your script.
If you use this mechanism the `Abort Install' button is replaced with a
`Back' button in most cases. You should define a `(back)' parameter for
all statements and functions with user interaction that presents the
`Back' button. If you don't the `Back' button is disabled which may
frustrate the user. The following new commands support backtracing:

`(trace)'
     The trace statement sets an backtrace position. A retrace will
     continue on that position in the script.

`(retrace)'
     The retrace initiates the backtrace mechanism. It skips the last
     backtrace position and searchs for the previous one.

`(back <code>)'
     If the user press the `Back' button the code is executed.
     Typically this code will contain a `(retrace)' statement the last
     statement.

Please see the `Installer.guide' for a detailed description of these
commands.

Interaction with the Workbench
==============================

   The V44 `Installer' provides a way for installation scripts to
interact with the Workbench. The following commands are new in V44:

`(openwbobject <argument> ...)'
     Open a Workbench object which can be a disk, a drawer, a trashcan,
     a tool or a project.

`(showwbobject <argument>)'
     This statement scrolls the view of an workbench drawer until the
     named icon is visible. The drawer has to be opened before.

`(closewbobject <argument>)'
     This statement closes the named workbench object. Currently only
     disks, trashcans and drawers can be closed.

Multimedia support
==================

   The V44 `Installer' provides support for displaying text and
pictures and playing sounds during the installation. It is also
possible to have the `Installer' open on its own screen to provide a
full screen backdrop for the installation. The OS 3.5 installer script
makes use of these new features to provide an eye pleasing installation
procedure as well as showing the user license in a separate window.
Before V44, some later installation scripts from third party
applications already made use of external programs to obtain similar
results. It is recommended that you adapt your existing scripts to use
the new mechanisms built into the Installer for increased consistency
between different products.

   The following multimedia commands are provided by the V44
`Installer':

`(effect <position> <effect> <color 1> <color 2>)'
     Sets the graphical effect that is used for the background.

`(showmedia <medianame> <filename> <position> <size> <borderflag> ...)'
     showmedia opens a datatype and presents it to the user.

`(setmedia <media> <action> [parameter])'
     Using the setmedia statement some action can be performed on the
     datatype.

`(closemedia <media>)'
     Closes a media file and removes it from memory.

Please see the `Installer.guide' for a detailed description of these
commands.

Rebooting the System
====================

   One new command allows to reboot the system automatically once the
installation has finished. This command should be used with extreme
caution: forced reboots are extremely annoying to most users.

`(reboot)'
     This commands reboots the Amiga.

The SetPatch command
********************

   The `SetPatch' program has been extended in V44 to perform some
additional functions required by OS 3.5.

   - Remove ROM based libraries from Exec's library list before they
     have been opened by applications, so that a disk-based replacement
     can be subsequently loaded by ramlib. SetPatch defaults to remove
     `icon.library' and `workbench.library' automatically. This can be
     overridden with the `DISABLEROMMODULES' command line parameter.
     This feature obsoletes the `RemLibrary' command which was used in
     earlier OS 3.5 beta releases.

   - Load resident modules from `Devs:Amiga ROM Update' and add them to
     Exec's residents list(1). The updated versions will then be
     initialized by Exec at bootstrap time. `SetPatch' uses this
     feature to replace the ROM versions of the `scsi.device' and the
     `FastFileSystem' with the updated V44 versions. `SetPatch'
     determines which modules need to be replaced automatically, but
     this can also be overridden by the command line parameters.

   The V44 `SetPatch' command is designed to work with any Kickstart
since V37, altrough it has been tested extensively only on V40. *NOTE
WELL:* The replacement modules included in `Amiga ROM Update' are to be
used on Kickstart V40 *ONLY* so they won't work with earlier Kickstart
versions.

   The `CheckSetPatch.c' code fragment included in the NDK may help
some software developers to internally turn off workarounds for OS bugs
conditionally.

    [TODO: describe command line template]

   ---------- Footnotes ----------

   (1) This feature obsoletes the `LoadV43Module' command which was
distributed with earlier V43 `scsi.device' and `FastFileSystem' updates.

Shell commands
**************

   The following updated shell commands are included with OS 3.5:

   - `' AddDataTypes

   - `' ConClip

   - `' CPU

   - `' Group

   - `' Info

   - `' IPrefs

   - `' Join

   - `' List

   - `' LoadWB

   - `' Mount

   - `' Owner

   - `' Protect

   - `' Status

   - `' Type

   - `' Version

    [TODO]

Library Function Index
**********************

* Menu:

* (back <code>):                         Installer.
* (closemedia <media>):                  Installer.
* (closewbobject <argument>):            Installer.
* (effect <position> <effect> <color 1> <color 2>): Installer.
* (openwbobject <argument> ...):         Installer.
* (reboot):                              Installer.
* (retrace):                             Installer.
* (setmedia <media> <action> [parameter]): Installer.
* (showmedia <medianame> <filename> <position> <size> <borderflag> ...): Installer.
* (showwbobject <argument>):             Installer.
* (trace):                               Installer.
* BOOL ChangeWorkbenchSelectionA(STRPTR name,struct Hook *hook, struct TagItem *tags);: Workbench Functions.
* BOOL CloseWorkbenchObjectA(STRPTR name,struct TagItem *tags): Workbench Functions.
* BOOL GetIconRectangleA(struct RastPort *rp, struct DiskObject *icon, STRPTR label, struct Rectangle *rectangle, struct TagItem *tags): Icon Functions.
* BOOL LayoutIconA(struct DiskObject *icon,struct Screen *screen, struct TagItem *tags): Icon Functions.
* BOOL MakeWorkbenchObjectVisibleA(STRPTR name,struct TagItem *tags): Workbench Functions.
* BOOL OpenWorkbenchObjectA(STRPTR name,struct TagItem *tags): Workbench Functions.
* BOOL PutIconTagList(STRPTR name,struct DiskObject *icon, struct TagItem *tags): Icon Functions.
* BOOL RemoveAppWindowDropZone(struct AppWindow *, struct AppWindowDropZone *): Workbench Functions.
* struct AppWindowDropZone * AddAppWindowDropZoneA(struct AppWindow *aw, ULONG id, ULONG userData, struct TagItem * tags): Workbench Functions.
* struct DiskObject *DupDiskObjectA(struct DiskObject *icon, struct TagItem *tags): Icon Functions.
* struct DiskObject *GetIconTagList(STRPTR name, struct TagItem *tags): Icon Functions.
* struct DiskObject *NewDiskObject(LONG type): Icon Functions.
* ULONG IconControlA(struct DiskObject *, struct TagItem *): Icon Functions.
* VOID AbortAslRequest(APTR requester):  ASL Library.
* VOID ActivateAslRequest(APTR requester): ASL Library.
* VOID ChangeToSelectedIconColor(struct ColorRegister *cr): Icon Functions.
* VOID DrawIconStateA(struct RastPort *rp, struct DiskObject *icon, STRPTR label, LONG leftEdge, LONG topEdge, ULONG state,struct TagItem *tags): Icon Functions.
* WorkbenchControlA(name,tags):          Workbench Functions.

Tags, Structures and Parameters Index
*************************************

* Menu:

* @installer-version:                    Installer.
* ASLFO_PopToFront (BOOL):               ASL Library.
* ASLFR_GetSortBy (ULONG *):             ASL Library.
* ASLFR_GetSortDrawers (ULONG *):        ASL Library.
* ASLFR_GetSortOrder (ULONG *):          ASL Library.
* ASLFR_InitialShowVolumes (BOOL):       ASL Library.
* ASLFR_PopToFront (BOOL):               ASL Library.
* ASLFR_SetSortBy (ULONG):               ASL Library.
* ASLFR_SetSortDrawers (ULONG):          ASL Library.
* ASLFR_SetSortOrder (ULONG):            ASL Library.
* ASLSM_PopToFront (BOOL):               ASL Library.
* PDTA_AllocatedPens:                    Picture Datatype.
* PDTA_DestMode:                         Picture Datatype.
* PDTA_DitherQuality:                    Picture Datatype.
* PDTA_GetNumPictures:                   Picture Datatype.
* PDTA_MaskPlane:                        Picture Datatype.
* PDTA_MaxDitherPens:                    Picture Datatype.
* PDTA_SourceMode:                       Picture Datatype.
* PDTA_UseFriendBitMap:                  Picture Datatype.
* PDTA_WhichPicture:                     Picture Datatype.
* PDTM_READPIXELARRAY:                   Picture Datatype.
* PDTM_WRITEPIXELARRAY:                  Picture Datatype.
* WBAPPICONA_SupportsCopy:               AppIcons.
* WBAPPICONA_SupportsDelete:             AppIcons.
* WBAPPICONA_SupportsEmptyTrash:         AppIcons.
* WBAPPICONA_SupportsFormatDisk:         AppIcons.
* WBAPPICONA_SupportsInformation:        AppIcons.
* WBAPPICONA_SupportsLeaveOut:           AppIcons.
* WBAPPICONA_SupportsOpen:               AppIcons.
* WBAPPICONA_SupportsPutAway:            AppIcons.
* WBAPPICONA_SupportsRename:             AppIcons.
* WBAPPICONA_SupportsSnapshot:           AppIcons.
* WBAPPICONA_SupportsUnSnapshot:         AppIcons.

Concept Index
*************

* Menu:

* AddAppWindowDropZoneA():               Drop Zones.
* Amiga ROM Update:                      SetPatch.
* AMTYPE_APPWINDOWZONE:                  Drop Zones.
* AppIcon custom rendering hook:         AppIcons.
* AppIcon Menu commands:                 AppIcons.
* AppIcon new features:                  AppIcons.
* AppIcons:                              Workbench.
* Application Support Library:           ASL Library.
* AppMessage:                            Drop Zones.
* AppWindow:                             Drop Zones.
* AppWindowDropZoneMsg:                  Drop Zones.
* asl.library:                           ASL Library.
* Backwards compatibility:               Workbench Version.
* Commodities, enhancing the Workbench:  Workbench Replacements.
* CyberGraphX:                           Picture Datatype.
* Datatypes:                             Picture Datatype.
* DrawIconsStateA():                     Drawing Icons.
* Drop Zones:                            Drop Zones.
* Drop zones:                            Workbench.
* DupDiskObject():                       Palette Mapped Icons.
* FastFileSystem:                        SetPatch.
* File Requester:                        ASL Library.
* GetDiskObject():                       Palette Mapped Icons.
* GetDiskObjectNew():                    Palette Mapped Icons.
* GetIconTagList():                      Palette Mapped Icons.
* High Color bitmaps:                    Picture Datatype.
* icon.library:                          Icon Library.
* icon.library new functions:            Icon Functions.
* IconControlA():                        Workbench Replacements.
* ICONGETA_RemapIcon:                    Drawing Icons.
* Icons:                                 Icon Library.
* Icons, drawing:                        Drawing Icons.
* Installer:                             Installer.
* LayoutIconA():                         Drawing Icons.
* LoadV43Module:                         SetPatch.
* newicon.library:                       About NewIcons.
* NewIcons:                              About NewIcons.
* OpenWorkbenchObject():                 OpenWorkbenchObject().
* Picasso 96:                            Picture Datatype.
* picture.datatype:                      Picture Datatype.
* PutIconTagList():                      Palette Mapped Icons.
* RemLibrary:                            SetPatch.
* Requesters:                            ASL Library.
* RTG Bitmaps:                           Picture Datatype.
* scsi.device:                           SetPatch.
* SetPatch:                              SetPatch.
* Shell commands:                        Shell Commands.
* True Color bitmaps:                    Picture Datatype.
* Version:                               Workbench Version.
* version.library:                       Workbench Version.
* WBStartup structure <1>:               OpenWorkbenchObject().
* WBStartup structure:                   Workbench.
* Workbench enhancers:                   Workbench Replacements.
* Workbench program:                     Workbench.
* Workbench replacements:                Workbench Replacements.
* workbench.library:                     Workbench.
* workbench.library new functions:       Workbench Functions.
* WorkbenchControl():                    WorkbenchControl().

