trigger getFocus (Entity)

Trigger of an entity that handles the processing that should occur after an occurrence gets focus.

Declaration: trigger getFocus
Applies to: Entity ocurrence
Activation: Activated as a result of user actions or structure editor functions, printing, or the setocc ProcScript command. For details, see Trigger Activation
Default behavior: None
Behavior upon completion: When printing, if $status is less than zero, the occurrence will not be printed. In other cases, the value of $status

Description

This trigger is often used for data validation and for initializing occurrence data. It is very useful when producing a report.

If the new occurrence could not be made active, the getFocus trigger for the current occurrence is reactivated. For example, if the currently active occurrence is the last occurrence in the hitlist, and the ^NEXT_OCC structure editor function is activated, the getFocus trigger for the current occurrence is reactivated. This also occurs if the create trigger contains ProcScript that cannot create a new occurrence.

Using setocc causes the getFocus trigger to be activated once, when the trigger containing the setocc completes.

The getFocus should not be used to change the current occurrence, so you should not use ProcScript instructions that do so, such as setocc, retrieve, or clear.

Caution: The getFocus trigger is not intended for I/O operations. Avoid using ProcScript statements here which cause data modification or I/O operations, if these actions involve the current field or the occurrence to which it belongs (such as clear/e). In some circumstances, these can cause Uniface to loop infinitely.

Trigger Activation

The getFocus trigger can be activated in several ways:

  • The user positions the cursor in an occurrence that does not currently have focus, with a mouse click or a structure editor function such as ^NEXT_OCC or ^PREV_FIELD.
  • During printing
  • By the setocc ProcScript statement.

The trigger is not activated by the user positioning the pointer on white space or background text.

This trigger is not activated by ProcScript statements such as read or delete

Preventing an Occurrence From Being Printed

To prevent an occurrence being printed, you must use the getFocus trigger. The leavePrinted trigger cannot be used in this case, because it is activated after the occurrence has been printed. For example:

trigger getFocus ; of entity INVOICE

if (INVAMOUNT = 0) ;don’t print this occurrence
   return -1
endif

end; getFocus

Highlighting the Current Occurrence

In the following example, ProcScript is used to highlight the current occurrence. Usually, the curoccvideo instruction makes this kind of code unnecessary, but the example still illustrates how the getFocus trigger can be used.

The form has definitions for component variables $ATTR$, $OCC_NUM$, $OCC_NUM2$, and $START_PROC$.

The exec operation of the form contains the following ProcScript. This ensures that the initial underlining of the first occurrence is done correctly: 

operation exec
   $START_PROC$ = 1
   retrieve
   edit/nowander
end; exec

The getFocus trigger for the entity to be highlighted contains the following code: 

trigger getFocus
if ($START_PROC$ = 1) ;first time this trigger used
  $ATTR$ = "und" ;set properties 
  call SET_VIDEO ;call ProcScript to set all fields
  $START_PROC$ = 0 ;make sure this "if" not used again
  $OCC_NUM$ = $curocc ;save current occurrence
  return 0 ;return
endif
if ($OCC_NUM$ != $curocc) ;new occurrence
  if ($OCC_NUM2$ != $curocc)
    $ATTR$ = "und"
    call SET_VIDEO
    $OCC_NUM2$ = $curocc ;save current occurrence
    setocc $entname,$OCC_NUM$ ;set to previous occurrence
                             ;to allow resetting of properties
  endif
else
  if ($OCC_NUM2$ != $curocc)
    $OCC_NUM$ = $OCC_NUM2$ ;old occurrence
    $ATTR$ = "def"
    call SET_VIDEO
    setocc $entname,$OCC_NUM2$ ;setocc to new occurrence
   endif
endif

end; getFocus

A form has the following entry: 

; Use: Set video for all the fields in the entity
entry SET_VIDEO
  fieldvideo V_NUM, $ATTR$ ;set to value in $ATTR$
  fieldvideo V_START, $ATTR$
  fieldvideo V_END, $ATTR$
  fieldvideo V_TITLE_1, $ATTR$
  fieldvideo V_TITLE_2, $ATTR$
done

Related Topics