Accessing the current document in LotusScript® classes
You can access the back-end document that is currently open through the NotesUIWorkspace and NotesUIDocument classes. Using the NotesUIView class, you can access the back-end documents in the view with the Documents property.
NotesUIDocument is a "front end" object, concerned with what the user sees on screen. The NotesUIDocument.Document property returns the corresponding "back end" NotesDocument object, which shows what is stored on disk when the document is saved. If you make changes to fields in this NotesDocument object, a special NotesDocument that has a relationship with the NotesUIDocument, those changes are immediately reflected on screen. This NotesDocument is very useful for writing buttons and actions that work on the document being edited. While using this, consider the following:
Do not call NotesDocument.Save on a document you got from a NotesUIDocument. The UI does not realize the document has been saved, and if the user then saves the document in the front-end also (for example, by using menu File > Save), Notes® detects that as a save conflict.
If you must do a back-end save, it's best to then immediately close the NotesUIDocument to prevent the user causing a save conflict. If the document is in edit mode, you can set the field SaveOptions = "0" to close the document without the user being prompted to save.
The NotesUIDocument only knows about text in a field. If a field is a number or date-time type, the NotesUIDocument.FieldGetText method will return the characters that are visible on screen. If you ask for the value from the NotesDocument, however, for example by using GetItemValue, you will get the number or date/time value, if the field contains a valid value of this type.
The NotesDocument is especially useful for multi-valued fields, because it lets you get the field value as an array instead of a delimited string. This lets you write code that won't break if the form design changes and different delimiter characters are being used than before.
If keyword fields have synonym values ("Yes | 1", "No | 0"), the NotesUIDocument works with the user-display values ("Yes" or "No") while the NotesDocument knows only about the stored values ("1" or "0"). This is useful because it lets you write code to operate on the stored values via the back end, and that code will not break if someone changes the user-display values corresponding to those stored values or if there are multiple versions of the user strings, for example, in a multilingual application.
Rich text fields are special and difficult. The contents of a NotesRichTextItem are not up to date with what's on the screen unless you call NotesUIDocument.Refresh(True). If you use the methods of NotesRichTextItem to make changes to rich text, there is no way to get those changes to appear on screen short of closing and reopening the document.
If you do use NotesRichTextItem to change some rich text, though the changes do not appear on the screen, they will still be saved when the user saves the document through the UI. This works unless the user also makes manual changes to the same rich text field; such changes would override your back-end changes. So, this technique is most often useful with "computed" rich text fields which the user cannot edit, or in cases where it's practical to immediately close the document and reopen it to show the updated rich text.
If you do need to redisplay some rich text, or if while in edit mode you need to refresh other information that normally only shows on open, it is possible to do this by closing and reopening the document without saving it. See Closing and reopening a document without saving.
The NotesUIDocument class has the following properties:
| Property |
Data type |
Description |
|---|---|---|
| AutoReload |
Boolean |
(Read-write) True to automatically reload the current document any time there is a change. |
| CurrentField |
String |
(Read-only) The name of the current field if the document is in Edit mode. |
| DialogBoxCanceled |
Boolean |
(Read-only) Indicates if a user cancels a dialog. |
| Document |
NotesDocument |
(Read-only) A reference to the NotesDocument object associated with this document window, giving you access to the back-end properties and methods. If you modify and save an item using the NotesDocument object, the item is automatically updated in the workspace, except for rich text items. |
| EditMode |
Boolean |
(Read-write) True for Edit mode. |
| FieldHelp |
Boolean |
(Read-write) True to display field help. |
| HorzScrollBar |
Boolean |
(Read-write) True if the horizontal scroll bar is visible. |
| HiddenChars |
Boolean |
(Read-write) True to display hidden characters. |
| InPreviewPane |
Boolean |
(Read-only) True if the document is being accessed from the preview pane. |
| IsNewDoc |
Boolean |
(Read-only) True if the document is not yet saved. |
| PreviewParentDoc |
Boolean |
(Read-write) True if the pane containing the parent document is displayed. |
| PreviewDocLink |
Boolean |
(Read-write) True if the pane containing the linked document is displayed. |
| Ruler |
Boolean |
(Read-write) True if the ruler is visible. |
| WindowTitle |
String |
(Read-only) The name of the window title. |
The NotesUIDocument class has the following methods:
| Method |
Description |
|---|---|
| Categorize |
Categorizes the current document. |
| Clear |
Clears the selected text. |
| Close |
Closes the current document. |
| CollapseAllSections |
Collapses all sections in the document. |
| Copy |
Copies the selected text to the Clipboard. |
| CreateObject |
Creates an object in a rich text item. |
| Cut |
Cuts the selected text and places it on the Clipboard. |
| DeleteDocument |
Marks the current document for deletion and closes it. The NotesUIDocument object is no longer available once you call this method. |
| DeselectAll |
Deselects the entire contents of the current field. |
| ExpandAllSection |
Expands all sections in the document. |
| FieldAppendText |
Appends the specified text to the specified or current field. |
| FieldClear |
Clears the contents of the specified or current field. |
| FieldContains |
Returns True if the specified or current field contains the specified case-sensitive text. |
| FieldGetText |
Gets the text of the specified or current field. |
| FieldSetText |
Sets the specified or current field to the specified text. |
| FindFreeTimeDialog |
Brings up the Find Free Time box. |
| FindFreeTimeDialogEx |
Brings up the Find Free Time box to allow searches for available meeting times. |
| FindString |
Finds the text in a given field. |
| Forward |
Creates a new mail document and prompts for recipients. |
| GetObject |
Gets a specified object. |
| GetSchedulerObject |
Gets an embedded scheduler. |
| GetSelectedText |
Gets the selected text in a UI document. |
| GotoTop |
Goes to the first field or scrolls to the beginning of the document. |
| GotoBottom |
Goes to the last field or scrolls to the end of the document. |
| GotoField |
Given a field name, puts the cursor in the specified field in a document. |
| GotoNextField |
Goes to the next field or scrolls so that it is visible. |
| GotoPrevField |
Goes to the previous field or scrolls so that it is visible. |
| GotoTop |
Places the cursor in the first editable field or the first button in a document. |
| Import |
Imports a file to the document. |
| InsertText |
Inserts the specified text at the current cursor position. |
| NavBarSetText |
Sets the URL navigation bar text. |
| NavBarSpinnerStart |
Starts the URL navigation bar spinner. |
| NavBarSpinnerStop |
Stops the URL navigation bar spinner. |
| Paste |
Pastes the Clipboard text to the current cursor position. |
| |
Prints the current document. |
| Refresh |
Refreshes the document. |
| RefreshHideFormulas |
Recalculates the hide-when formulas for the current document; this is an expensive operation. |
| Reload |
Refreshes the current document with any changes made to the stored document. |
| Save |
Saves the current document. |
| SaveNewVersion |
Saves the current document as a new version. |
| SelectAll |
Selects the entire contents of the current field. |
| Send |
Mails the current document and closes it. |
| SpellCheck |
Checks the spelling in a document. |
The NotesUIView class has the following properties:
| Property |
Data type |
Description |
|---|---|---|
| CalendarDateTime |
Variant of type DATE |
(Read-only) The date and time of the current region in a calendar view. |
| CaretCategory |
Variant |
(Read-only) Returns the current category in the view for the current document. |
| Documents |
NotesDocumentCollection |
(Read-only) All the documents that the current NotesUIView event is working on. |
| View |
NotesView |
(Read-only) The back-end view that corresponds to the currently open view. |
The NotesUIView class has the following methods:
| Method |
Description |
|---|---|
| |
Implements the @Command([FilePrint]). Prints the currently open or selected document(s), or the current view. |
| SelectDocument |
Selects the specified document in a view. |
For a list of events in NotesUIView, see "Event Descriptions" in the "Programming Overview" chapter.