The OyezAutomation Interface

Application level

.maximize()

Maximise and give focus to application. It is recommended that you call this immediately after creating a link to OyezForms.

.minimize()

Minimise OyezForms to task bar.

.executablepath()

Returns the path of the folder containing the executable file for the running copy of OyezForms. The path includes a terminating ’\’.

.library

Returns the name of the currently selected library. Either "Master", "Custom", or "User". Sets the library to be used to either "Master", "Custom", or "User".
Sets the library to be used to either "Master", "Custom", or "User". Sets "Master" if library name not valid.
note: If you are automating via the .tlb file, use the .getlibrary() method instead.

.selectlibrary()

Sets the library to be used: input either "Master", "Custom", or "User".
Sets "Master" if library name not valid.

.exit()

Causes Oyezforms to terminate when the client destroys its automation object

.error

Returns any error message generated by the last call to any of the methods.
Set: Clears the error.
note: If you are automating via the .tlb file, use the.geterror() method instead.

Form manipulation

.newform()

<name> BSTR The name of the legal form which is to be created.
BOOL True if form created successfully.
Creates a new form using the forms name. The latest revision of the form template is always selected. Use throwaway or discard before attempting to create or open another form

.loadform()

<FormID> long The 3 digit Oyez allocated ID for the form.
<CatID> long The 2 digit Oyez allocated ID for the category which contains the form
<Revision> long The 8 digit revision reference or date code (yyyymmdd) of the form.
<Library> BSTR Name of library to use. BOOL True if form created successfully.
Opens a unique form by specifying its Form ID, Category ID, revision and the library in which it is contained. The revision may be set to zero to select the latest version of the form. The IDs and revision can be obtain by viewing the form’s property dialogue.

.throwaway()

Discards the form from screen. Prompts if form changed.

.discard()

Discards the form from screen without prompting, regardless of form state.

.store()

<fullpath> BSTR Full path including name and extension
BOOL True if form stored successfully.
Saves the form to the file specified in full path. Any existing file is overwritten.

.load()

<fullpath> BSTR Full path including name and extension.
BOOL True if form loaded successfully
Use throwaway or discard before attempting to create or open another form

.form

Returns the name of currently displayed form, else "<blank>".
set: Ignored
note: If you are automating via the .tlb file, use the .getform() method instead.

.getolfpath()

Returns the path of the currently active form, if saved. Returns empty string is not saved.

.pathtotemplate()

<form name> BSTR the title of the form who's template path is to be returned
Returns the full path of the specified form if it is a Word template, and empty string if it is not.
see technical discussion

.gettemplatepath()

<FormID> long The 3 digit Oyez allocated ID for the form.
<CatID> long The 2 digit Oyez allocated ID for the category which contains the form
<Revision> long The 8 digit revision reference or date code (yyyymmdd) of the form.
Returns the full path of the specified form if it is a Word template, and empty string if it is not. Allows specific revisions to be targetted.
see technical discussion

.selectdocument()

<docGUID>is the GUID of the document to select. Which you would have aquired/stored previously via getdocumentGUID().
Version 11.01F+. Selects a form for filling from input of its windows-assigned GUID. Returns the GUID as a string. Document must be open in order to be selected. If return value is different from value inputted, then a problem has occured.

Version 10.00e+, only via.ocx control:

.copypage()

<page> long. The page to copy
<insert_after> long.
The page the copy will be inserted after Creates a duplicate of the page, after the poistion indicated by the second parameter. field contents are also copied. Pages will be renumbered after copy.

.removepage()

<page> long.
The page to remove Pages will be renumbered after deletion.

.clearpage()

<page> long.
The page to clear Removes all fill-in text from page.

Locking forms as read-only

.SetDocumentLock ()

<enable> Long. 1 = set document as 'locked' (read-only to user); 0 = unlock document (editable).
OyezForms can 'lock' any form and prevent user alterations. This can only be done via this external command , or via application-level macros. The locked state only persists for the current editing session. It is not stored in the form file when saved.

.GetDocumentLock()

Returns the state of the current document lock. 0 signifies no lock, 1 signifies the document is locked.

Identifying / tagging a form

.setuserpropertybeta(string)

Version 11.01F+. Sets the current form's UserPropertyBeta string property. This value is stored permanently within the olf/x file, and can subsequently be read via this COM interface, or via application-level macros. The UserPropertyAlpha cannot be set or retrived via the external COM interface.

.getuserpropertybeta()

Version 11.01F+. Returns a string of the current form's UserPropertyBeta property. This may have been set via this COM interfacte, or via application-level macros>. The UserPropertyAlpha cannot be set or retrived via the external COM interface.

.getdocumentGUID()

Version 11.01F+. Returns a string of the current form's windows-assigned GUID property. This is not available on XP systems. This value is permanent, constant, and read-only.

Field filling/manipulation

Selecting a page

.pages

Returns the number of pages in the current form. Returns 0 if no form loaded.
set: Ignored
note: If you are automating via the .tlb file, use the .getpages() method instead.

.page

Returns the current page number being used by DDE. This is not necessarily the same as the displayed page.
Returns 0 if no form loaded.Sets the page on the form to which field IDs apply. Alternative to selectpage method
note: If you are automating via the .tlb file, use the .getpage() method instead.

.selectpage()

<page> long
The number of the page Sets the page on the form to which field IDs apply. Alternative way to set the page property.

Retrieving available fields

.fieldlist

Returns a list of the field IDs for the current page, separated by commas. IDs are in tabbing order. Suppressed fields are not included unless the “Enable suppressed fields” tools menu option in checked.
set: Ignored
note: If you are automating via the .tlb file, use the.getfieldlist() method instead.

.labellist()

Returns a list of the field labels for the current page, separated by commas.

.extendedlabellist()

Returns a label list including duplicate labels

.getlabel()

<fieldID> long
Returns the field label corresponding to the given fieldID Can be used to compare field lists and label lists

.fields

Returns the number of fields on the current DDE selected page.
set: Ignored
note: If you are automating via the .tlb file, use the.getfields() method instead.

Filling data into fields

.fill()

<fieldLabel> BSTR label associated with the field or fields to be filled.
<text> BSTR The data to be written.
Fills text into the labelled field or fields identified by descriptive label.
No action if a label not found.

.fillfield()

<fieldID> long The ID of the field into which the text is to be written .
<text> The string to be written.
Fills text into the field identified by its numeric ID

.finishfilling()

<action> long Non-zero causes printing.
Updates the display prior to printing. Data is not guaranteed to be displayed on the Oyez form until a finishfilling command has been sent.

User interaction with fields

.fillat()

<page> long
<fieldID> long
Positions filling in point for the user to enter data. Does not fill data.

.field

Returns the contents of the currently active field as set by the user or “FILLAT” command.
set: Ignored
note: If you are automating via the .tlb file, use the .getfield() method instead.

.GetCurrentFieldID()

Returns numeric ID of the currently selected field
If no field is selected, returns -1

.GetCurrentPageNumber()

Returns the number of the current page displayed in OyezForms
If no field is selected, returns -1

PDF exporting

You should call .finishfilling(), above, before exporting to PDF. The command setpagestoprint(), below, will allow specific pages/sections of a form to be outputted.

.exporttopdf()

<fullpath> Full path, including file extension, of PDF's location
Generates a flattened PDF of the current form to the given path. Should be used with ActionsComplete.

Returns:
0 the export was successful.
-1 previous export still in progress.
-2 PDF printing not enabled.
-3 no legal form.
-4 general PDF printer failure.

.actionscomplete()

Returns TRUE when the exporttoPDF process has completed
Should be used to test for OyezForms completing generating a PDF (which occurs asynchronously)

.setpdfoptionlong()

Used to set options in the OyezForms PDF export engine: novaPDF. See nova documentation for details.

<option name> The name of the option to be set
<value>The value the option is to be set to. Returns: none

.setpdfoptionlong()

Printing

You should call .finishfilling(), above, before printing.