OnFocus (NotesUIDocument - LotusScript®)

Occurs when the subwindow displaying the document receives a focus notification.

Note: This event is new with Release 8.0.1

Defined in



OnFocus(Source As Notesuidocument)



NotesUIDocument. Read-only. The current document.


Using any LotusScript® in the onfocus event that changes focus to other views, forms, or subforms will cause the focus events in those subwindows to execute. First, the currently executing onfocus event code will run to completion, then the onblur code in the current subwindow and the onfocus/onblur code in other affected subwindows will execute. All onfocus/onblur events are queued and held until all current code is finished executing. If multiple onfocus/onblur events are queued for the same subwindow, onfocus will only execute once, and onblur will execute once if the subwindow no longer has focus once onfocus is done executing.

In the case of a form with subforms, all onfocus and onblur events are considered to be a single unit. Either all of them are executed, or none of them are executed.

CAUTION: Because of the way that onfocus/onblur events are queued, designers must be careful not to create a situation where focus is passed from subwindow to subwindow in an endless loop. Changing focus to a dialogue box is not an issue, since dialogue boxes do not have onfocus/onblur events. However care must be taken if the focus is changed to another view, form, or subform. Debugging of onblur/onfocus events is especially challenging, since the use of the debugger causes frequent focus changes.