GPR_$SET_OBSCURED_OPT             GPR Calls              GPR_$SET_OBSCURED_OPT


NAME
     gpr_$set_obscured_opt - establishes the action to be taken when a window
     to be acquired is obscured.

FORMAT
     gpr_$set_obscured_opt (if_obscured, status)

DESCRIPTION
     This routine establishes the action to be taken when a window to be
     acquired is obscured.

   Input Parameters
     if_obscured
          If the window to be acquired by gpr_$acquire_display is obscured,
          this argument specifies, in gpr_$obscured_opt_t format, the action
          to be taken.  This is a 2-byte integer.  Specify only one of the
          following values:

          gpr_$pop_if_obs
               pop the window.

          gpr_$error_if_obs
               return an error and do not acquire the display.

          gpr_$block_if_obs
               block display acquisition until the window is popped.

          gpr_$ok_if_obs
               acquire the display even though the window is obscured.

          gpr_$input_ok_if_obs
               blocks display acquisitions, but allows input into the window
               even if the window is obscured.

   Output Parameters
     status
          Completion status, in status_$t format.

SEE ALSO
     gpr_$inq_vis_list.

NOTES
     If this routine is not  called,  the  action  to  be  taken  defaults  to
     gpr_$err_if_obs.

     These  options  apply  whenever  the  display  is  acquired,  either   by
     gpr_$acquire_display or implicitly by gpr_$event_wait.

     If the program specifies the option gpr_$err_if_obs, it  must  check  the
     status  code returned from gpr_$acquire_display or gpr_$event_wait before
     calling any drawing routines.

     When a program specifies gpr_$ok_if_obs, the  output  is  performed  even
     when  the  window is obscured. To avoid overwriting other Display Manager
     windows,  the  program  must  inquire  the  visible  areas   by   calling
     gpr_$inq_vis_list and set clipping windows accordingly.

     When a program specifies gpr_$input_ok_if_obs,  the  input  is  performed
     even when the window is obscured.

     The cursor state (cursor pattern and whether the cursor is active) is  in
     effect  at  all  times,  even  when  the  display is not acquired.  Three
     exceptions are when the window is an icon, when the  window  is  in  hold
     mode,  and when the window is obscured and gpr_$set_obscured_opt does not
     specify gpr_$input_ok_if_obs.

     Setting if_obscured to gpr_$block_if_obs or gpr_$ok_if_obs has an  effect
     on the refresh procedure specified by gpr_$set_refresh_entry.

     Setting if_obscured to gpr_$block_if_obs causes only the  hidden  display
     memory refresh routine to be called.

     Setting if_obscured to gpr_$ok_if_obs  causes  both  the  hidden  display
     memory and display memory refresh routines to be called.