Introduction to the AmigaOS 3.5 (V44) Release Notes *************************************************** *PRELIMINARY* - last revised on 5 December 1999 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 . 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. 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. 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 to replace the library altogether instead of patching all 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. `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 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(1). 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. ---------- Footnotes ---------- (1) 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. 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. 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 `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'. 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 )' 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 ...)' Open a Workbench object which can be a disk, a drawer, a trashcan, a tool or a project. `(showwbobject )' This statement scrolls the view of an workbench drawer until the named icon is visible. The drawer has to be opened before. `(closewbobject )' 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 )' Sets the graphical effect that is used for the background. `(showmedia ...)' showmedia opens a datatype and presents it to the user. `(setmedia [parameter])' Using the setmedia statement some action can be performed on the datatype. `(closemedia )' 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. ---------- Footnotes ---------- (1) This feature obsoletes the `LoadV43Module' command which was distributed with earlier V43 `scsi.device' and `FastFileSystem' updates. 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). Library Function Index ********************** * Menu: * (back ): Installer. * (closemedia ): Installer. * (closewbobject ): Installer. * (effect ): Installer. * (openwbobject ...): Installer. * (reboot): Installer. * (retrace): Installer. * (setmedia [parameter]): Installer. * (showmedia ...): Installer. * (showwbobject ): Installer. * (trace): Installer. * AddDataTypes: Shell Commands. * 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. * ConClip: Shell Commands. * CPU: Shell Commands. * Group: Shell Commands. * Info: Shell Commands. * IPrefs: Shell Commands. * Join: Shell Commands. * List: Shell Commands. * LoadWB: Shell Commands. * Mount: Shell Commands. * Owner: Shell Commands. * Protect: Shell Commands. * Status: Shell Commands. * 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. * Type: Shell Commands. * ULONG IconControlA(struct DiskObject *, struct TagItem *): Icon Functions. * Version: Shell Commands. * 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 icons: Changing Icons Look. * CyberGraphX: Picture Datatype. * Datatypes: Picture Datatype. * Directory Opus: Replacing Workbench. * DrawIconsStateA(): Drawing Icons. * DrawIconStateA(): Changing Icons Look. * 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(): Changing Icons Look. * 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(). * Patching the workbench.library: Replacing Workbench. * Picasso 96: Picture Datatype. * picture.datatype: Picture Datatype. * PutIconTagList(): Palette Mapped Icons. * RemLibrary: SetPatch. * Replacing the Workbench: Replacing Workbench. * Requesters: ASL Library. * RTG Bitmaps: Picture Datatype. * Scalos: Replacing Workbench. * 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 <1>: Replacing Workbench. * Workbench enhancers: Changing Icons Look. * Workbench program: Workbench. * Workbench replacements: Replacing Workbench. * workbench.library: Workbench. * workbench.library new functions: Workbench Functions. * WorkbenchControl(): WorkbenchControl().