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

PRELIMINARY - last revised on

Freely distributable

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

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 AppMessages
---------------------

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 AppMessages 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 AppMessages.

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 AppIcons 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 AppIcons. 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 AppMessages with the AppMessage->am_Class member set to AMCLASSICON_Selected or AMCLASSICON_Unselected, respectively.

Notes for Workbench Replacements
================================

Workbench replacements usually patch some of the vectors in the workbench.library to redirect services which are normally offered by the Workbench (AppIcons, AppWindows and AppMenus) on them. As of V44, the number of vectors to be patched have increased as well as the functionality to be emulated.

It is important for those applications to duplicate ALL of the new Workbench features because V44-aware or V44-only applications will just check what version of the workbench.library is installed and assume that the new functionality is there if it is at least 44. This includes (but is not limited to) drop zones, new AppIcon features and calls such as WorkbenchControl(), OpenWorkbenchObject(). Failing to do so, would break compatibility with many applications that are going to appear in the next future.

Note that OpenWorkbenchObject() fails if it is invoked when the Workbench program is not running. This behaviour prevents using of this function by Workbench replacement applications, which are expected to provide their own code to launch Workbench applications.

To be 100% compatible to the Workbench, the replacement should also provide an ARexx port named "WORKBENCH" which offers the same set of ARexx commands supported by the Workbench.

Now that the workbench.library became a disk-based library, the most sensible way to duplicate its functionality would be replacing the library altogether instead of patching some of its vectors.

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.

BOOL WorkbenchControlA(STRPTR name,struct TagItem *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 *aw, struct AppWindowDropZone *dz)
     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 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(), GetDiskObjectNew() and PutDiskObject() calls are now declared obsolete: they are still supported for backwards compatiblity only and therefore they don't provide a way to access the new palette mapped images (Actually, this is not 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 for AppIcons passed by non-V44-aware applications.).

Applications which manipulate icons should be adapted to use the new GetIconTagList() function. 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 imagery.

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 (In fact, it is strongly discouraged because it installs patches on the icon.library with no support for the new extensions.). 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.

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() (To prevent this from happening, you must explicitly set the ICONGETA_RemapIcon tag to FALSE.). 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.

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 select default icons for icon-less files.

Although patching library vectors is not a recommended practice, further tweaks to the appearance of icons can be easily achieved by patching DrawIconStateA(). This way your code will affect all applications, not just the Workbench. Most important, this approach is much more OS friendly than installing horrible patches in some graphics.library routines. The morale is: don't do that! If you must, at least do it cleanly.

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 DiskObjects and fake DiskObjects created by unfair applications. These hacks will stop working once the compatibility code is dropped for future versions of the icon.library.

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 (This feature obsoletes the LoadV43Module command which was distributed with earlier V43 scsi.device and FastFileSystem updates.). 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.

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

Several updated shell commands are included with OS 3.5. Please see the release notes for a detailed description of all changes. This table only describes relevant new features and compatibility issues.

AddDataTypes
     New LIST/S command line option; several bug fixes.

ConClip
     ConClip V44 also installs a global string gadget editing hook which adds clipboard support. This feature may conflict with third party commodities/patches which provided the same functionality.

CPU
     Bug fixes.

List
Group
Owner
Protect
     File ownership and Envoy network filesystem support. List has a new SORT option.

Info
     Support for >4GB filesystems.

IPrefs
     Several bug fixes; Improvements for RTG bitmaps and palette locking; Obsoletes the programs ClassAct and FastIPrefs.

Join
     Minor fixes.

LoadWB
     New options SKIPWBSTARTUP and SIMPLEGELS.

Mount
     Several bug fixes.

Status
     Minor fixes.

Type
     Small fixes.

Version
     Several bug fixes (including Y2K issues).