\input amigatexinfo
\input texinfo
@c $VER: V44_Changes.texi 0.1 (20.10.99)

@setfilename V44_Changes.guide
@settitle AmigaOS 3.5 - V44 Release Notes
@setchapternewpage odd
@c @set amiga_convert_nodes <-- this makes node names look like shit!

@titlepage

@title AmigaOS V44 (AKA OS3.5) Release Notes
@subtitle PRELIMINARY - last updated on @today{}
@author by Bernardo Innocenti

Copyright @copyright{} 1999 Amiga Inc., all rights reserved.

@page
@vskip 0pt plus 1filll

@end titlepage


@c ***********************************************************************
@c Top
@c ***********************************************************************

@ifinfo
@node Top, Workbench Version, Concept Index, (dir)
@top
@chapter Introduction to the AmigaOS 3.5 (V44) Release Notes

@strong{PRELIMINARY} - last revised on @today{}

Copyright @copyright{} 1999 Amiga, Inc. All rights reserved.

This document describes the relevant changes and new features
introduced in @w{AmigaOS 3.5} (release V44) since @w{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 @w{AmigaGuide V40} or later. Please send comments, suggestions
and corrections for this text to @w{Bernardo Innocenti} @email{bernie@@cosmos.it}.

@menu
Overview

* Workbench Version::    How to determine the Workbench version

Updated Subsystems

* Workbench::            The Workbench program and @code{workbench.library}
* Icon Library::         The @code{icon.library}
* ASL Library::          The @code{asl.library}
* Picture Datatype::     The @code{picture.datatype}
* Installer::            The @code{Installer} program
* Shell Commands::       Updated shell commands
* SetPatch::             New @code{SetPatch} features

Indices

* Function Index::       Index of library functions
* Tag Index::            Index of tags, structures and definitions
* Concept Index::        Index of all topics by concept

@end menu

@end ifinfo



@c ***********************************************************************
@c Workbench Version
@c ***********************************************************************

@node Workbench Version, Workbench, Top, Top
@chapter Determining the Workbench version
@cindex @code{version.library}
@cindex Version
@cindex Backwards compatibility

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 @code{version.library}, and check its version.
For example:

@example
@group
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
     */
@}
@end group
@end example

@noindent
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
@code{asl.library} that are only present since V44, you must explicitly
check the version of @code{asl.library} before using them. The same goes
for all other system libraries.



@c ***********************************************************************
@c Workbench
@c ***********************************************************************

@node Workbench, Icon Library, Workbench Version, Top
@chapter The Workbench
@cindex Workbench program
@cindex @code{workbench.library}
@cindex AppIcons
@cindex Drop zones
@cindex @code{WBStartup} structure


Workbench got rewritten for @w{OS 3.5}. The @code{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 @code{icon.library}. @ref{Icon Library}.


@menu
Workbench Topics

* OpenWorkbenchObject():: Launching Workbench applications and opening drawers
* WorkbenchControl()::    Getting/setting several Workbench parameters
* Drop Zones::            AppWindow icon drop zones
* AppIcons::              New features for AppIcons
* Workbench Functions::   Summary of new workbench.library functions
@end menu



@c ***********************************************************************
@c OpenWorkbenchObject()
@c ***********************************************************************

@node OpenWorkbenchObject(), WorkbenchControl(), , Workbench
@section Launching Workbench applications
@cindex OpenWorkbenchObject()

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.

@cindex WBStartup structure
Before V44, a similar functionality was made available by third-party
tools such as the @code{wbstart.library} and the @code{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 @code{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 @strong{WILL STOP WORKING}.

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

Note that @code{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.


@c ***********************************************************************
@c WorkbenchControl()
@c ***********************************************************************

@node WorkbenchControl(), Drop Zones, OpenWorkbenchObject(), Workbench
@section Controlling the Workbench
@cindex WorkbenchControl()

Another new function useful for commodities that extend the basic
Workbench functionality is @code{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.


@c ***********************************************************************
@c Drop Zones
@c ***********************************************************************

@node Drop Zones, AppIcons, WorkbenchControl(), Workbench
@section AppWindow icon drop zones
@cindex @code{AddAppWindowDropZoneA()}
@cindex Drop Zones
@cindex @code{AppWindow}
@cindex @code{AppMessage}
@cindex @code{AMTYPE_APPWINDOWZONE}
@cindex @code{AppWindowDropZoneMsg}

@subsection Adding drop zones

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

@subsection Drop zone @code{AppMessage}s

Once an @code{AppWindow} has a drop zone installed, Workbench will send
a new type of @code{AppMessage} to your port if icons are dropped on
a drop zone. Instead of @code{AMTYPE_APPWINDOW} type messages you
will receive @code{AMTYPE_APPWINDOWZONE} messages. In fact, you will
no longer hear any @code{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
@code{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.

@subsection Drop zones priority

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

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

@subsection Drop zone hooks

Using the @code{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:

@example

@group
result = hookFunc(hook,reserved,arm)
  D0               A0     A2     A1

LONG hookFunc(struct Hook *hook, APTR reserved,
              struct AppWindowDropZoneMsg *adzm);
@end group

@group
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)
@end group

@end example

The @cite{reserved} parameter will be set to @code{NULL}.
For future enhancement, make sure that your hook function
always returns @code{NULL}.

The drop zone message contents are as follows:

@table @code

@item adzm_RastPort
A pointer to the @code{RastPort} to render into. Typically, this
is the @code{RastPort} of the window the drop zone is attached to.

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

@item adzm_ID
@itemx adzm_UserData
These two come straight from the values you passed as the @cite{id}
and @cite{userData} parameters to @code{AddAppWindowDropZoneA()}.

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

@end table

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 @code{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 @code{graphics.library};
if you do anything complex that involves Intuition locking and unlocking
the display, such as refreshing gadgets or locking @code{IntuitionBase},
you will deadlock the operating system. You have been warned!


@subsection Removing drop zones

Use @code{RemoveAppWindowDropZone()} to remove a drop zone previously
added with @code{AddAppWindowDropZone()}. Due to the asynchronous
nature of Workbench/user interaction, you may receive @code{AppIcon}
drop zone messages for zones that you have just removed. These messages
may arrive in the time between your code calling @code{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 @code{AppMessage}s.

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


@c ***********************************************************************
@c AppIcons
@c ***********************************************************************

@node AppIcons, Workbench Functions, Drop Zones, Workbench
@section New AppIcon functionality
@cindex AppIcon new features

@subsection Responding to menu commands
@cindex AppIcon Menu commands

As of Workbench V44, it is possible to invoke menu actions for
@code{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 @code{AddAppIconA()}. When one of the supported
menu items is invoked, you will receive an @code{AppMessage} with
the @code{am_Class} entry set to a value out of
@w{@code{AMCLASSICON_Open}..@code{AMCLASSICON_EmptyTrash}}, corresponding
to the menu item used.

The following @code{BOOL} tags are provided by @code{AddAppIconA()} to
control which menu commands are supported by an @code{AppIcon}:

@vtable @code

@item WBAPPICONA_SupportsOpen
@item WBAPPICONA_SupportsCopy
@item WBAPPICONA_SupportsRename
@item WBAPPICONA_SupportsInformation
@item WBAPPICONA_SupportsSnapshot
@item WBAPPICONA_SupportsUnSnapshot
@item WBAPPICONA_SupportsLeaveOut
@item WBAPPICONA_SupportsPutAway
@item WBAPPICONA_SupportsDelete
@item WBAPPICONA_SupportsFormatDisk
@item WBAPPICONA_SupportsEmptyTrash

@end vtable


@subsection Custom AppIcon rendering hook
@cindex AppIcon custom rendering hook

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

@example

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;
@};

@end example

@noindent
The @cite{reserved} parameter will be set to @code{NULL}. The render
message contents are as follows:

@table @code
@item arm_RastPort
A pointer to the RastPort to render into.

@item arm_Icon
A pointer to the Icon to be rendered.

@item arm_Label
A pointer to the label text to be printed
below the icon.

@item arm_Tags
Further control tags which you should pass on
to @code{icon.library/DrawIconStateA()}, should you
call this routine.

@item arm_Left
@itemx arm_Top
Rendering origin; note that these coordinates DO NOT take the
embossing border sizes into account.

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

@item arm_State
An icon drawing state, such as used by @code{icon.library/DrawIconStateA()}.

@end table

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

If your hook code returns @code{TRUE}, the @code{AppIcon}'s regular
image will be drawn. If your code returns @code{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.


@subsection AppIcon positioning

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

@subsection AppIcon selection

The new tag @code{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 @code{AppMessage}s with the @code{AppMessage->am_Class}
member set to @code{AMCLASSICON_Selected} or @code{AMCLASSICON_Unselected},
respectively.


@c ***********************************************************************
@c Workbench Functions
@c ***********************************************************************

@node Workbench Functions, , AppIcons, Workbench
@section Summary of new functions in workbench.library
@cindex @code{workbench.library} new functions

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

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

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

@item struct AppWindowDropZone * AddAppWindowDropZoneA(struct AppWindow *aw, ULONG id, ULONG userData, struct TagItem * tags)
Designate an @code{AppWindow} area as suitable for dropping icons on.

@item BOOL RemoveAppWindowDropZone(struct AppWindow *, struct AppWindowDropZone *)
Attempt to remove a drop zone from an @code{AppWindow}.

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

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

@end ftable



@c ***********************************************************************
@c Icon Library
@c ***********************************************************************

@node Icon Library, ASL Library, Workbench, Top
@chapter The Icon Library
@cindex @code{icon.library}
@cindex Icons


The @code{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.

@menu
icon.library Topics

* Palette Mapped Icons::   The new color icon system
* Workbench Replacements:: Support to enhance or replace the Workbench
* About NewIcons::         newicon.library compatibility issues
* Drawing Icons::          Support for drawing icons in applications
* Icon Functions::         Summary of new functions in icon.library
@end menu


@c ***********************************************************************
@c Palette Mapped Icons
@c ***********************************************************************

@node Palette Mapped Icons, Workbench Replacements, , Icon Library
@section The New Palette Mapped Icons
@cindex @code{GetDiskObject()}
@cindex @code{GetDiskObjectNew()}
@cindex @code{GetIconTagList()}
@cindex @code{DupDiskObject()}
@cindex @code{GetIconTagList()}
@cindex @code{PutIconTagList()}

The @code{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 @code{GetDiskObject()} and @code{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@footnote{Actually, this isn't completely true: the
@code{struct DiskObject} really contains the new images in its
private data. The only way to retrieve it is by calling @code{DupDiskObject()}
and passing the tag @code{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.}.

Applications which manipulate icons should be adapted to use
the new @code{GetIconTagList()}. This new function is a superset of
@code{GetDiskObject()}: it still returns a pointer to a pointer
to a @code{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 @code{ICONGETA_Screen}
tag specifies which Screen the icon is to be displayed on.
See the @code{GetIconTagList()} AutoDoc for more information.

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


@c ***********************************************************************
@c Workbench Replacements
@c ***********************************************************************

@node Workbench Replacements, About NewIcons, Palette Mapped Icons, Icon Library
@section Support for Workbench enhancers and replacements
@cindex @code{IconControlA()}
@cindex Workbench replacements
@cindex Workbench enhancers
@cindex Commodities, enhancing the Workbench

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

This new functionality obsoletes most of the Workbench patches that
have been around before @w{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 @code{NewDiskObject()} function provides a way to create and
initialize a @code{DiskObject} structure. The old official way to do this
was to to get a default icon with @code{GetDiskObjectNew()} or even
create the structure manually. The latter method is now considered
@strong{OBSOLETE} and @code{VERY SYSTEM UNFRIENDLY}. The V44 @code{icon.library}
contains compatibility code to distinguish between real @code{DiskObject}s
and fake @code{DiskObject}s created by unfair applications. These hacks will
stop working once the compatibility code is dropped for future versions
of the @code{icon.library}.



@c ***********************************************************************
@c About NewIcons
@c ***********************************************************************

@node About NewIcons, Drawing Icons, Workbench Replacements, Icon Library
@section About NewIcons
@cindex NewIcons
@cindex @code{newicon.library}

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 @code{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 @code{newicon.library}, therefore it is no longer necessary to
start the @file{C:NewIcon} program from the @file{Startup-Sequence}
@footnote{In fact, it is strongly discouraged because it installs
patches on the @code{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 @code{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 @code{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 @code{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 @code{icon.library} API as soon as possible.


@c ***********************************************************************
@c Drawing Icons
@c ***********************************************************************

@node Drawing Icons, Icon Functions, About NewIcons, Icon Library
@section Drawing icons in applications
@cindex Icons, drawing

@subsection @code{DrawIconStateA()}
@cindex @code{DrawIconsStateA()}

The V44 @code{icon.library} provides functions to support applications
which need to display icons in their own GUI. These include icon editors,
@code{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 @code{icon.library/DrawIconStateA()} function provides the same
functionality in a straightforward way. Shall the icon appearance be
changed with future extensions of the @code{icon.library}, your application
will pick them up automatically.

@subsection @code{LayoutIconA()}
@cindex @code{LayoutIconA()}
@cindex @code{ICONGETA_RemapIcon}

The @code{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 @code{LayoutIconA()}.

@code{LayoutIconA()} is called implicitly by @code{GetIconTagList()}
@footnote{To prevent this from happening, you must explicitly set the
@code{ICONGETA_RemapIcon} tag to FALSE.}. The icons are automatically
remapped for display on the screen selected using @code{IconControlA()}.
This could be undesiderable when your application wants to display the
icon on another screen.

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



@c ***********************************************************************
@c Icon Functions
@c ***********************************************************************

@node Icon Functions, , Drawing Icons, Icon Library
@section Summary of new functions in icon.library
@cindex @code{icon.library} new functions

@ftable @code

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

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

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

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

@item struct DiskObject *NewDiskObject(LONG type)
create an @emph{empty} @code{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.

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

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

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

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

@end ftable



@c ***********************************************************************
@c ASL Library
@c ***********************************************************************

@node ASL Library, Picture Datatype, Icon Library, Top
@chapter The ASL Library
@cindex @code{asl.library}
@cindex Application Support Library
@cindex File Requester
@cindex Requesters


The @code{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.

@section New Functions

@ftable @code

@item VOID ActivateAslRequest(APTR requester)
Activate a modal requester from a different task context.

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

@end ftable


@section New Tags

@vtable @code

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

@item ASLFR_SetSortBy (ULONG)
@itemx ASLFR_GetSortBy (ULONG *)
Criteria for sorting the file list. This must be one of:

@itemize @bullet{}
@item @code{ASLFRSORTBY_Name} @minus{} sort by name (default)
@item @code{ASLFRSORTBY_Date} @minus{} sort by date
@item @code{ASLFRSORTBY_Size} @minus{} sort by size
@end itemize

If @code{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.

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

@itemize @bullet{}
@item @code{ASLFRSORTDRAWERS_First} @minus{} drawers appear before all other files (default)
@item @code{ASLFRSORTDRAWERS_Mix} @minus{} drawers are sorted along with the the other files
@item @code{ASLFRSORTDRAWERS_Last} @minus{} drawers appear after all other files
@end itemize

If @code{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.

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

@itemize @bullet{}
@item @code{ASLFRSORTORDER_Ascend} @minus{} smallest/oldest files first, largest/newest files last (default)
@item @code{ASLFRSORTORDER_Descend} @minus{} largest/newest files first, smallest/oldest files last
@end itemize

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

@item ASLFR_PopToFront (BOOL)
@itemx ASLFO_PopToFront (BOOL)
@itemx 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).

@end vtable



@c ***********************************************************************
@c Picture Datatype
@c ***********************************************************************

@node Picture Datatype, Installer, ASL Library, Top
@chapter The Picture Datatype
@cindex @code{picture.datatype}
@cindex Datatypes
@cindex RTG Bitmaps
@cindex True Color bitmaps
@cindex High Color bitmaps
@cindex Picasso 96
@cindex CyberGraphX


The V40 @code{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.

@w{OS 3.5} integrates a rewritten @code{picture.datatype} whose API tries
to be as compatible as possible to these unofficial versions.

The V44 @code{picture.datatype} works transparently with both
@cite{CyberGraphX} and @cite{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.


@section General concepts

@table @code

@item 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).

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

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

@item 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 @code{graphics.library} or by the RTG system.

@end table


@section Backwards compatibility

For backwards compatibility, the unofficial V43 @code{picture.datatype}
implementations which were distributed with @cite{CyberGraphX} and
@cite{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 @code{picture.datatype}:

@table @code

@item picture.datatype V40/V42 (OS 3.1)
PDTA_DestMode is ignored.

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

@item picture.datatype V43 (Picasso 96)
PDTA_DestMode defaults to @code{PMODE_V42}. However, the returned
bitmap is @strong{NOT} native.

@item picture.datatype V44 (OS 3.5)
PDTA_DestMode defaults to @code{PMODE_V43}. It can be explicitly
forced to @code{PMODE_V42}.

@end table

The V42 mode is retained in @code{picture.datatype} V44 for backwards
compatibility only. Use of the V42 mode in new applications is
@strong{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.



@section New methods in unofficial V43 @code{picture.datatype}

@vtable @code
@item PDTM_WRITEPIXELARRAY
Transfer pixel data to the picture object in the specified format

@item PDTM_READPIXELARRAY
Transfer pixel data from the picture object in the specified format
@end vtable

@section New tags in unofficial V43 @code{picture.datatype}

@vtable @code
@item PDTA_SourceMode
Set the sub datatype interface mode

@item PDTA_DestMode
Set the app datatype interface mode

@item PDTA_UseFriendBitMap
Allocates the resulting bitmap as a friend bitmap

@item PDTA_MaskPlane
NULL or mask plane for use with BltMaskBitMapRastPort()
@end vtable

@section New tags in V44

@vtable @code

@item PDTA_WhichPicture
Index number of the picture to load

@item PDTA_GetNumPictures
Get the number of pictures stored in the file

@item PDTA_MaxDitherPens
Maximum number of colours to use for dithering

@item PDTA_DitherQuality
Quality of the dithering algorithm to be used during color quantization

@item PDTA_AllocatedPens
Pointer to the allocated pen table

@end vtable


@c ***********************************************************************
@c Installer
@c ***********************************************************************

@node Installer, SetPatch, Picture Datatype, Top
@chapter The Installer program
@cindex @code{Installer}

The latest pre-V44 release of the @code{Installer} was V43.2, distributed on
the Amiga Technologies FTP site.

@section Checking the Installer version
@vindex @code{@@installer-version}

If your installation script uses new features not available in earlier
versions of the @code{Installer}, it is important to check the
variable @var{@@installer-version} before using these new
features. This variable will default to 0 with old versions
of @code{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.

@section Backtracing

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

@ftable @code

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

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

@item (back <code>)
If the user press the @code{Back} button the code is executed.
Typically this code will contain a @code{(retrace)} statement the
last statement.

@end ftable

@noindent
Please see the @file{Installer.guide} for a detailed description of
these commands.


@section Interaction with the Workbench

The V44 @code{Installer} provides a way for installation scripts
to interact with the Workbench. The following commands are new
in V44:

@ftable @code

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

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

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

@end ftable


@section Multimedia support

The V44 @code{Installer} provides support for displaying text
and pictures and playing sounds during the installation. It is
also possible to have the @code{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 @code{Installer}:

@ftable @code

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

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

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

@item (closemedia <media>)
Closes a media file and removes it from memory.

@end ftable

@noindent
Please see the @file{Installer.guide} for a detailed description of
these commands.

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

@ftable @code

@item (reboot)
This commands reboots the Amiga.

@end ftable



@c ***********************************************************************
@c SetPatch
@c ***********************************************************************

@node SetPatch, Shell Commands, Installer, Top
@chapter The SetPatch command
@cindex @code{SetPatch}
@cindex @code{LoadV43Module}
@cindex @code{RemLibrary}
@cindex @file{Amiga ROM Update}
@cindex @code{scsi.device}
@cindex @code{FastFileSystem}


The @code{SetPatch} program has been extended in V44 to perform
some additional functions required by @w{OS 3.5}.

@itemize @minus

@item
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
@code{icon.library} and @code{workbench.library} automatically. This can be
overridden with the @code{DISABLEROMMODULES} command line parameter.
This feature obsoletes the @code{RemLibrary} command which was used
in earlier @w{OS 3.5} beta releases.

@item
Load resident modules from @file{Devs:Amiga ROM Update} and add them
to Exec's residents list@footnote{This feature obsoletes the @code{LoadV43Module}
command which was distributed with earlier V43 @code{scsi.device} and
@code{FastFileSystem} updates.}. The updated versions will then be
initialized by Exec at bootstrap time. @code{SetPatch} uses this
feature to replace the ROM versions of the @code{scsi.device} and
the @code{FastFileSystem} with the updated V44 versions. @code{SetPatch}
determines which modules need to be replaced automatically, but this can
also be overridden by the command line parameters.

@end itemize

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

The @file{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]


@c ***********************************************************************
@c Shell Commands
@c ***********************************************************************

@node Shell Commands, Function Index, SetPatch, Top
@chapter Shell commands
@cindex @code{Shell commands}

The following updated shell commands are included with @w{OS 3.5}:

@itemize @minus{} @code

@item AddDataTypes
@item ConClip
@item CPU
@item Group
@item Info
@item IPrefs
@item Join
@item List
@item LoadWB
@item Mount
@item Owner
@item Protect
@item Status
@item Type
@item Version

@end itemize

 [TODO]


@c ***********************************************************************
@c Function Index
@c ***********************************************************************

@node Function Index, Tag Index, Shell Commands, Top
@unnumbered Library Function Index

@printindex fn

@c ***********************************************************************
@c Tag Index
@c ***********************************************************************

@node Tag Index, Concept Index, Function Index, Top
@unnumbered Tags, Structures and Parameters Index

@printindex vr

@c ***********************************************************************
@c Concept Index
@c ***********************************************************************

@node Concept Index, Top, Tag Index, Top
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye
