---

How to Override the Standard Button Bar (11/22/96)

Q: What's the proper way to override the button bar, especially to cover up the buttons on the Newton OS 2.1 devices?

A: We don't recommend that typical applications obscure, cover up, or otherwise modify the standard button bar. From a user interface standpoint, it's a bad idea, because it can make the unit look unfamiliar or (in extreme cases) unusable. Some applications, typically those created for vertical markets, are designed to "take over" the interface, in which case it may be permissible to cover or disable the button bar.

GetRoot().buttons.soft will be non-nil if there is a "soft" button bar, that is, the button bar is located on the drawable screen. GetRoot():LocalBox() returns the rectangle that encloses the screen and the tablet. GetAppParams() returns information about the useful area of the screen, excluding the soft or hard button bar. Used together, this information will allow you to implement any combination of button bar disabling and/or button bar obscuring.

(There is also an Newton 2.1 OS function called KillStdButtonBar. That API is designed for use when you want to actually remove the button bar so you can replace it - probably with a floating slip. It is a fairly expensive call and does a lot of things you don't need if all you want to do is take over the screen. We recommend avoiding that call if possible.)

If the goal is simply to maximize the visible area of the base view, then the button bar should be obscured only for devices with a soft button bar (for instance, a MessagePad 2000). On devices with a "hard" button bar (for instance, a MessagePad 130), the root view encompasses a larger area than the LCD display because the input tablet is larger to account for the "hard" button bar. Drawing is limited to the screen so applications wouldn't increase their visible area by covering the "hard" button bar.

The "soft" button bar can simply be covered by your application's base view. The only trick is properly detecting if there is a soft button bar, and finding out where on the screen it happens to be. This code will give you the largest drawable application box, covering any soft button bar but not covering any hard buttons.

    local params := GetAppParams();
    if GetRoot().Buttons.soft then
        self.viewBounds := OffsetRect(UnionRect(params.appArea, params.buttonBarBounds),
            -params.appAreaGlobalLeft, -params.appAreaGlobalTop)
    else
        self.viewBounds := params.appArea;

If the goal is to to prevent users from accessing the buttons, then the button bar should be obscured regardless of whether or not it is on the LCD screen. On units with a hard button bar, you must take into account the fact that part of the base view will be off-screen. (For instance, don't place your close box under the silk-screened buttons.) A simple way to accomplish this is by having a child view whose bounds are the appArea and locating the rest of the application within that child.

Note that on some Newton devices (for instance, the eMate 300), the buttons are not located in a view at all. On these devices, covering the entire tablet does not prevent the user from accessing the buttons (for instance, opening up the Extras Drawer).

Below is some sample code you can add to your base view's viewSetupFormScript to cover the entire tablet:

    local params := GetAppParams();
    self.viewBounds := GetRoot():LocalBox();
    if params.appAreaGlobalLeft then
        self.viewBounds := OffsetRect(self.viewBounds, -params.appAreaGlobalLeft, -params.appAreaGlobalTop);