R3 Developers Release Notes

About this Document

This document lists major (or at least interesting) changes in the following areas:

• Warnings and Bugs
• Installing and the MBR
• Building an Application
• Documentation
• Tracker and Deskbar
• File Panels
• MIME and FileTypes
• Graphics and the App Server
• Scripting
• Printing
• The App Kit and Messaging
• The Storage Kit
• The Interface Kit (Except for BWindows)
• BWindow
• The Game Kit
• The Midi Kit (and MIDI apps)
• The Device Kit
• The Translation Kit
• The Support Kit
• Tools and Apps
• Kernel and Drivers
• Miscellaneous

Warnings and Bugs

		HFS+ (Mac OS Extended format) disks aren't supported by BeOS R3 (you can't mount them). No harm will come to any HFS+ disks connected to your computer.
		When a Maxtor IDE drive, model 85250D6, is connected as a slave with either an IBM Model DCAA 34330 or an IBM Model DAQA 33240 as the master, the Maxtor drive may not be recognized. If you run into this bug, launch DriveSetup and rescan the IDE bus; this usually works.
		The third button on a serial mouse doesn't work. This has been true for a long time.

Building an Application

• STL is now available (in the library libmslcpp_2_2.a).

• For more information on building an app, see "Moving from PR2 to R3: Development Layout".

Documentation

The BeBook on this CD is the most recent on-line version; it's identical to the version on the Be Web site (as of the April 1, 1998 Web site BeBook update). Note that the BeBook on this CD is newer and more complete than the BeBook on the Intel R3 CD.

Tracker and Deskbar

Open With. Tracker windows now let you choose which application you want to use when opening a selected file. The "File" menu includes an "Open With" item, as does the context sensitive menu that you get when you mouse-and-hold on a file. The list of candidate applications is based on the file's type: All applications that recognize the type are listed in the "Open With" choices.

The Open With... panel sorts the candidate apps according to their "relation" to the file you're trying to open. There are four relationships:

• The app is the declared "Preferred App" for that file.
• The app can handle the file's full type (e.g. "text/plain")
• The app can handle the file's supertype ("text/...")
• The app can handle any file type (".../...")

You can see this phenomenon by opening an Open With... panel, or by popping open the context menu for a file.

Workspace-specific windows. The Tracker now remembers the correspondence between windows and workspaces such that when you reboot your machine, your restored windows are placed in the correct workspaces.

Opening an open folder. When you open a folder (window) that's already open in some other workspace, the folder window is brought to the workspace that you're in (and removed from its present workspace). Previously, opening an open folder would switch you to the workspace of the open window.

More "Find..." options. The "More Options" checkbox in the Find panel lets you name your query (the name appears as the title of the query result window), and lets you optionally search through the Trash. Also, you can start a query "by Name", or "by Attribute" and then switch to "by Formula" without losing information.

Busy Tracker window feedback. Busy Tracker windows now display an animated "sideways barber pole" in the lower left corner. If the barber pole is spinning, the Tracker window is thinking.

Smarter current selection. The Tracker's notion of the current selection has improved. For example, if you send the current selection to the Trash, the next entry in the window is selected. This is particularly convenient when you're reading (and trashing) your mail.

Option key parent dismissal. In PR2, you could dismiss a parent folder window by option-clicking a subfolder. Now, the option dismissal trick has been extended to keyboard navigation (option+command+down-arrow, for example), and can be used to dismiss a child (option+command+up-arrow). You can even launch an app and dismiss a Tracker window at the same time (option+double-click the app).

Clipped text on the desktop. You can now drag a text selection from a document and drop it on the desktop; a file is automatically created to contain the "clipped" text. If you then drag the clipped text file and drop it on an open document, the text is automatically pasted at the insertion point.

Smart app launching. Dragging a file icon over an app icon (as if to drop) asks the app if it can handle the file's type. If it can't, the app isn't highlighted and so won't be launched if the icon is dropped.

Tracker Scripting. Tracker now supports a scripting suite that lets applications have tighter integration with Tracker windows. See the documentation in the "Playing with Tracker" chapter of the BeBook.

More files. We increased the size of the node monitor database, and increased the maximum number of file descriptors available to the Tracker by four times; this allows copying of deeply-nested folders and more copy tasks at a time.

Deskbar. Cosmetic improvements:

• The clock is now right-justified.
• Replicants in the Deskbar are now centered vertically.

File Panels

Double-clicking on a file in a save file panel now adds the directory and name to the message (this applies to all FilePanels).

Alt-Esc now sets the keyboard navigation focus to the menu bar in file panels, and Esc closes the file panel.

Tabbing through file panels now proceeds forward instead of backward.

Scripting

In addition to the Tracker scripting, described elsewhere, R3 includes new scripting for...

• BControl. The "Enabled" property is now a standard for BControl objects. You can use the property to get or set the control's enabled state.

• BWindow. New "MenuBar" property for BWindows passes the command to the window's key menu bar.

• BMenus and BMenuItems. The "Menu" and "MenuItem" properties allow submenu and menu item creation/deletion, and the "Enabled", "Label", and "Mark" properties allow the named states to be set and retrieved.

The BPropertyInfo class has also been added. This class makes it easier to create and maintain lists of the commands supported by a property, and can be used by an application to describe its scripting interface to people that call GetSupportedSuites() as well as to aid in responding to a ResolveSpecifier() request.

MIME and FileTypes

MIME strings are now case-insensitive.

The FileTypes preferences app allows icon editing. Double click in the icon well in the upper right corner of the FileTypes window to get to the icon editor.

The FileTypes app alphabetically sorts the contents at each level of the file type list (the outline list view at the top of the window).

FileTypes now only shows the "desirable" types in its top list view. In particular, it filters out file types that were generated to simulate Mac types, and ignores application signatures. If you want to see all file types in the database, toggle the Settings/Show internal types menu item.

Folders can have preferred apps (Tracker, by default).

Several MIME types used in previous versions of BeOS were invalid; these have been corrected.

Graphics and the App Server

The app server saw a number of bug fixes and added conveniences; for example, if you double-click the app icon of a running app, the app's existing windows are brought to the front.

Endianism part I. In the graphics science world, there is an endian situation you should be aware of when handling offscreen bitmaps. With this release, the official offscreen 32-bit bitmap byte sex is little endian. To wit:

• Byte 0 : Blue
• Byte 1 : Green
• Byte 2 : Red
• Byte 3 : Alpha

Little endian bitmaps have always been the norm, so this isn't news. However, the way you might be accessing your bitmap data may be nonportable Do you use a uint32 pointer to look at your buffer? If your code looks something like the following, then it's going to break in the little-endian world:

   int32    i;
   uint32 color;
   uint32 *buffer; 
   
   color = 'BGRA';
   buffer = (uint32*)my_bitmap->Bits();
   for (i=0; i<10000; i++)
      *buffer++ = color;

Rewrite your code as shown below; it will work on any platform:

   union {
      uint8   bytes[4];
      uint32 word;
   } color;
   
   color.bytes[0] = 'B';
   color.bytes[1] = 'G';
   color.bytes[2] = 'R';
   color.bytes[3] = 'A';
   buffer = (uint32*)my_bitmap->Bits();
   for (i=0; i<10000; i++)
      *buffer++ = color.word;

More color spaces. New color_space enum values (interface/GraphicsDefs.h). Color space names are in a more concise format, and the list of color spaces has been expanded. An excerpt:

   B_RGB32    /* was B_RGB_32_BIT */
   B_RGB32_BIG    /* was B_BIG_RGB_32_BIT */ 
   B_GRAY8           /* was B_GRAYSCALE_8_BIT */
   B_YUV422         /* new */

The old constants are still supported, but their use is discouraged.

Miscellaneous. A handful of improvements and refinements:

• The app server now supports 15- and 16-bit color.

• 1152x900 is now a supported screen resolution.

• Support for more than 4 MB of VRAM is now provided.

• The color map has been revised so that inverting colors is much more reasonable now. Also, alpha is now 255 by default.

• The cursor tracking for changing from one cursor to another when passing from one view to another has been improved.

• Calls to draw round rectangles, ellipses, and arcs are ignored when the're too big. This prevents a crash or an unacceptably long block.

The App Kit and Messaging

Endianism part II. Flattened BMessages are now endian-savvy for all data types defined in support/TypeConstants.h except for the following:

• B_RAW_TYPE
• B_OBJECT_TYPE
• B_ANY_TYPE

BMessage doesn't know how to swap these three types, nor any custom types that you define. But for everything else, simply flatten a BMessage, send it to a byte-reversed machine, unflatten, and you're back in business.

New old BMessage function. There's a new version of BMessage::GetInfo() that provides "fixed size" info:

   status_t GetInfo(const char *name, 
                    type_code *type, 
                    bool *is_fixed_size) const;

The is_fixed_size value is that which was recorded by the AddData() call that added the data to the message.

The Storage Kit

New and improved BMimeType functions:

      bool BMimeType::Contains(const BMimeType *other) const

• New Contains() compares itself to an argument MIME string and returns true if A) the MIME type of 'this' exactly matches 'other' or B) 'this' is a supertype, and it's the supertype of 'other'. Otherwise, it returns false.

      static status_t BMimeType::GetWildcardApps(BMessage *signatures)

• New static GetWildcardApps() function finds the applications that support all file types, and returns their signatures in the argument's "applications" field:

• Improved GetSupportingApps() now returns more information, allowing the caller to determine which apps support a specific MIME type, and which apps claim to support all subtypes of a given supertype.

New and improved BAppFileInfo functions:

      bool BAppFileInfo::Supports(BMimeType *mt) const

• New Supports() function returns true if the app knows how to handle the given type, as set through SetSupportedTypes().

      void BAppFileInfo::SetInfoLocation(info_location loc);
      
      enum info_location {
            B_USE_ATTRIBUTES = 0x1,
            B_USE_RESOURCES = 0x2,
            B_USE_BOTH_LOCATIONS = 0x3
      };

• You can now control whether a BAppFileInfo object will read and write its info as attributes or resources. You set the "info location" by passing an info_location constant to the new SetInfoLocation() function:

The Node Monitor now sends a message ('opcode' == B_ATTR_CHANGED) when an attribute is removed from a monitored file.

BNode has a new Sync() function that immediately performs any pending disk transactions for the file.

The Support Kit

Archiving. All implementations of BArchivable's Archive() protocol function must now return a (BArchivable *) instead of a pointer to an instance of the class that's being archived.

Endianism part III. The new ByteOrder.h header file contains native sex-cognizant byte-swapping functions. The central function is:

      status_t swap_data(type_code type, 
                  void *data, 
                  size_t length,
                  swap_action action);

Pass in a type (B_INT32_TYPE, B_STRING_TYPE, etc), a buffer and length, and a "swap action," and the function swaps data in-place. The swap actions are

      typedef enum {
         B_SWAP_HOST_TO_LENDIAN,
         B_SWAP_HOST_TO_BENDIAN,
         B_SWAP_LENDIAN_TO_HOST,
         B_SWAP_BENDIAN_TO_HOST,
         B_SWAP_ALWAYS
      } swap_action;

For single-element swapping, use the type-specific macros such as...

      B_HOST_TO_LENDIAN_INT32(arg)

There's also a new is_type_swapped() function:

      static status_t is_type_swapped(type_code type);

This function returns true if the specified type can be swapped by swap_data(); otherwise it returns false.

The ByteOrder.h functions and macros replace the old read_16_swap()-style functions defined in SupportDefs.h.. The old functions are still supported on the PowerPC BeOS, but you shouldn't use them in new code.

New BMemoryIO function. The BMemoryIO class has a new SetSize() function that lets you set the allocated memory to a size that's no greater than the original allocation.

The Midi Kit (and MIDI apps)

The BMidiPort class recognizes F5 ("Output Cable Protocol") messages; the message is represented by the new B_CABLE_MESSAGE constant (MidiDefs.h). This message lets you talk to a MIDI cable multiplexer.

simple-midi has been renamed SimpleMidi.

Midi is now marked as single-launch, since it's not multiply-launchable. Also, it no longer crashes if you do a Close All from the Deskbar.

The MIDI drivers /dev/midi1 and /dev/midi2 have been moved to /dev/midi/midi1 and /dev/midi/midi2.

The Device Kit

The new GetDeviceName() and CountDevices() API lets you query the system for device names, freeing you from the evils of hard-coded strings. The functions are implemented by BJoystick, BSerialPort, and BMidiPort.

The Translation Kit

The Translation Kit (nee the Datatypes Library) has been added to the OS. See the Translation Kit chapter of the BeBook.

The Game Kit

New BDirectWindow class provides enhanced direct access to the frame buffer in both full-screen and "window" modes.

Some switching-out-of-full-screen-mode bugs were fixed (the color map is now properly restored; Deskbar is no longer perverted by full screen mode).

Printing

PostScript printing is working better now, and a number of bugs have been fixed. Look for drastic improvements in R4.

Note that the PPD directory has moved to /beos/etc (B_BEOS_ETC_DIRECTORY).

The Interface Kit (Except for BWindows)

New BSlider class. BSlider draws a couple of styles of horizontal slider; the styles are exemplified by the Mouse and Keyboard preferences. The class also lets you mix and match thumbs, hash marks, watermark colors, and gives you hooks so you can draw your own elements.

New BTabView and BTab classes. BTabView and BTab work together to create a "tabbed" selection device. Look at the Fonts preference for an example. The BTabView class provides the framework by coordinating a group of BTab objects, each of which represents (and draws) a particular tab.

BAlert::Go(). The synchronous version of the Go() function now returns -1 if the BAlert is sent a B_QUIT_REQUESTED while it's on-screen (it used to return 0). The asynchronous version hasn't changed.

New BListView and BOutlineListView functions. BListView has some new functions that let you manipulate items in the list:

      bool    SwapItems(int32 a, int32 b);
      bool    MoveItem(int32 from, int32 to);
      bool    ReplaceItem(int32 index, BListItem * item);

BOutlineListView adds some sorting and invocation functions of its own:

      void    FullListSortItems(int (*compareFunc)(const BListItem *,
                     const BListItem *));
      
      void   SortItemsUnder(BListItem *start, bool oneLevelOnly,
                     int (*compareFunc)(const BListItem *, const BListItem *));
      
      int32    CountItemsUnder(BListItem *start, bool oneLevelOnly) const;
      
      BListItem     *EachItemUnder(BListItem *start, bool oneLevelOnly,
                     BListItem *(*eachFunc)(BListItem *, void *), void *);
      
      BListItem    * ItemUnderAt(BListItem *underItem, bool oneLevelOnly,
                     int32 index) const;

BMenuField. The down and right arrow keys will now pop open a menufield item.

BPicture. The picture format has changed but is currently private. In the meantime, don't use these functions:

      BPicture(const void *data, int32 size);
            const void *Data() const;
            int32    DataSize() const;

Also, the new Play() function (which is publically declared) shouldn't be used yet.

BTextView. Triple-clicking now selects paragraphs instead of lines. Also, the BTextView class defines an "undo" mechanism. See the BTextView class documentation.

BView. The new AppendToPicture() function, an alternative to BeginPicture(), lets you extend the picture given by the argument. It must be balanced by an EndPicture() call.

      void AppendToPicture(BPicture *a_picture);

BView's new StrokeBezier() and FillBezier() functions let you draw bezier curves.

BView's new PushState() and PopState() functions let you preserve and restore a view's graphics state.

A new BView flag, B_SUBPIXEL_PRECISE, tells the view to retain the fractional part of all coordinate measurements.

BWindow

New window types. BWindow defines some new window types constants:

• B_UNTYPED_WINDOW
B_FLOATING_WINDOW

The interesting one is the floating window type. The "untyped" constant is provided to support the new look and feel constants (described next).

Look and feel. New "look" and "feel" characteristics have been defined for windows. The window_look constants describe the graphic part of a window:

      enum window_look {
         B_BORDERED_WINDOW_LOOK,
         B_TITLED_WINDOW_LOOK,   
         B_DOCUMENT_WINDOW_LOOK,
         B_MODAL_WINDOW_LOOK,
         B_FLOATING_WINDOW_LOOK
      };

Note that, for example, the B_MODAL_WINDOW_LOOK doesn't make the window modal, it simply makes the window "look" modal (it will lack a title tab). The way a window behaves is controlled by its feel, as set through a window_feel constant:

      enum window_feel {
         B_NORMAL_WINDOW_FEEL,         
         B_MODAL_SUBSET_WINDOW_FEEL,
         B_MODAL_APP_WINDOW_FEEL,
         B_MODAL_ALL_WINDOW_FEEL,
         B_FLOATING_SUBSET_WINDOW_FEEL,
         B_FLOATING_APP_WINDOW_FEEL,
         B_FLOATING_ALL_WINDOW_FEEL
      };

• Normal feel means the window will behave like a normal window (non-floating, non-modal) regardless of how it looks.

• Subset feel means that the window will be modal with regard to or will float above all other windows in that window's subset (see below).

• App feel means the window will be modal/float above all other windows in the app.

• All feel means the window will be modal/float above all other windows on the screen.

Window subsets. The new "subset" functions...

      status_t AddToSubset(BWindow *subwindow);
      status_t RemoveFromSubset(BWindow *subwindow);

.. let you add the 'subwindow' to this window's subset. The subset is only meaningful if 'this' window has a "subset window feel", as described above.

The old window flag B_WILL_FLOAT has been removed. You now create floating windows through the look and feel constants.

New window flags:

• B_AVOID_FRONT
B_AVOID_FOCUS
B_NO_WORKSPACE_ACTIVATION

The first two are reasonably obvious: When made active, the window doesn't come to front, or doesn't take focus. B_NO_WORKSPACE_ACTIVATION means that when the window is activated, the desktop won't switch to the window's workspace. This is useful in the (rare) case where an app wants to create windows that are spread out across many workspaces, but doesn't want the desktop to switch as each is created.

There's new SendBehind() function that tells a window to hide behind some other window:

      status_t SendBehind(const BWindow *window);

A new Sync() function that blocks until pending window operations are complete. This function should very rarely be needed--it can really bog down responsiveness, so use it sparingly.

      void Sync() const;

New LastMouseMovedView() function returns the BView that most recently received a MouseMoved() in that window.

New Get/SetWindowAlignment() functions let you declare how you want your window's content area to be aligned with regard to the screen or the frame buffer. See the BWindow documentation.

The ScreenChanged() function has been fixed to return the correct colorspace mode.

Tools and Apps

Installer changes:

      $ sysinfo -platform       
      BeBox

      $ query 'name=foo && size > 170000'

      uint8         read_io_8(int mapped_io_addr);
      void          write_io_8(int mapped_io_addr, uint8 value);
      uint16        read_io_16(int mapped_io_addr);
      void          write_io_16(int mapped_io_addr, uint16 value);
      uint32        read_io_32(int mapped_io_addr);
      void          write_io_32(int mapped_io_addr, uint32 value);

      long install_io_interrupt_handler(long interrupt_number,
                     interrupt_handler handler,
                     void *data,
                     ulong flags);
      
      long remove_io_interrupt_handler(long interrupt_number,
                           interrupt_handler handler); 

      set_isa_interrupt_handler()
      enable_isa_interrupt_handler()
      disable_isa_interrupt_handler()
      
      set_io_interrupt_handler()
      enable_io_interrupt_handler()
      disable_io_interrupt_handler()