Application Interrupt Handling

A device application can receive an application interrupt event in the following ways:

  1. A user gesture (tap, swipe, drag, etc.) that puts the application into Card mode.
  2. An alert pops up on-screen. For example: an incoming phone call.

Note:

This section and PDL calls do not apply to desktop development.

Noted application interrupt events

When an application interrupt occurs, there are two SDL_ACTIVEEVENT events your application needs to handle depending on the value of event.active.gain:

  1. SDL_APPACTIVE

    • event.active.gain == 0 -- The application is no longer active and should be considered paused. At this point, your app should suspend play.

      In pause mode, the application's drawing is capped at 1 FPS (Frames Per Second). While paused, an application does not have to draw, but must do a repaint (update the screen) in response to a SDL_VIDEOEXPOSE event.

      When inactive, your app should reduce CPU usage; this is essential for extended battery life. To do this, your app should wait longer to check for events and stop any complex screen animation. For example, it could switch from using SDL_PollEvent, or other event checking mechanism, to using SDL_WaitEvent. This causes the app to sleep if there are no pending events, though it gets awaken quickly when reactivated. An SDL_ACTIVEEVENT is generated when the user returns.

      To check your app's CPU use, you can use the "top" command on the device. If usage is above 10% when inactive, your app has a problem that should be fixed before submission to the Palm app catalog.

    • event.active.gain == 1 -- The application has just become active.

  2. SDL_APPINPUTFOCUS

    • event.active.gain == 0 -- The application is not fullscreen.
    • event.active.gain == 1 -- The application has just become fullscreen.

Palm Development Library calls for handling application interrupts

There are three PDL calls your application can use to handle specific interrupt types:

  1. PDL_BannerMessagesEnable -- Enables or disables banner messages.
  2. PDL_CustomPauseUIEnable -- Enables or disables the system UI for handling app reactivation.
  3. PDL_SetOrientation -- Sets the orientation for pop-up alerts and banner messages.