BrowserInterface
The BrowserInterface object represents a web browser that is displayed on a new form created by the addon system. The BrowserInterface provides a large assortment of methods that can be used to interact with the web browser and the documents it displays.
The BrowserInterface object is considered to be obsolete. While the current version of the addon system is backwards compatible with the BrowserInterface object, it should no longer be used in addons. Instead, use the FormInterface.CreateBrowser object to create an instance of the new Browsercontrol.
Properties
- Browser: Returns the .NET WebBrowser object being operated on by the BrowserInterface. It can be used for more fine-tuned control over browser document manipulation, and for things that are already well handled by the WebBrowser object, such as retrieving elements by tag name. Because this property returns a .NET object and not a wrapper class, it is recommended that this property is used with caution as incorrect usage could result in loss of performance or an inoperable addon.
Methods
CheckHandlerQueue()
Forces an immediate check of the page handler queue. This is primarily used when javascript and ajax enabled pages perform updates that do not require an actual page change in the browser, but need to be detected and checked by the browser.
ClickObject(string objectId)
Searches for an element on the page whose ID matches the objectId provided and attempts to invoke the object's Click member. If no elements are found using an ID, a search will be done based on element names, rather than ID. In this case, the object will only be considered a match if it is the only object with the given name.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | objectId | The ID of the element to be clicked |
This is equivalent to calling ClickObjectInFrame with a nil frameName.
ClickObjectByReference(HtmlElement clickableObject)
Attempts to invoke the provided object's "Click" member.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | clickableObject | An HtmlElement object that contains a "Click" member. |
The object does not need to be a button - most elements will have a click member.
ClickObjectInFrame(string objectId, string frameName)
Searches for an element with an id matching objectId that is contained in a frame with a name matching frameName. If the frame cannot be found or if frameName is nil, it will attempt to use the current page's primary frame. Once a matching element is found, the element's "click" member is invoked.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | objectId | The ID of the element to be clicked |
Input | frameName | The name of the frame in which to search for the element |
CreateButton(string name, Image icon, string clickHandler, string groupName)
Creates a browser specific button and adds it to the ribbon page associated with the browser.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | name | The name of the button, which is also used as the button text |
Input | icon | The icon to display on the button |
Input | clickHandler | The name of the Lua method that should be called when the button is clicked |
Input | groupName | The name of the ribbon page group the button should be placed in |
GetButton(string name)
Attempts to retrieve a button with a name matching the name provided and that was created via the current instance of the browser object.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | name | The name of the button to retrieve |
Output |
GetElementByCollectionIndex(HtmlElementCollection collection, int index)
Returns the HtmlElement that is assigned to the provided index of the provided collection. This method is no longer necessary as the system now supports the get_Item syntax for retrieving indexed items - collection:get_Item(0) is the same as GetElementByCollectionIndex(collection, 0)
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | collection | The HtmlElementCollection in which to search |
Input | index | The index of the element to return |
Output | HtmlElement |
GetElementByWindowIndex(HtmlWindow window, int index)
Returns the HtmlElement that is assigned to the provided index of the given window's collection of HtmlElements. This collection of elements contains ALL valid html elements in the frame.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | window | The window in which to search |
Input | index | The index of the element to return |
Output | HtmlElement |
GetElementInFrame(string frameName, string elementId)
Attempts to located an element with the specified ID in the frame whose name matches the specified frame name.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | frameName | The name of the frame to search in |
Input | elementId | The id of the element to search for |
Output | HtmlElement |
GetForm(HtmlWindow window, string formNameId)
Attempts to locate the specific form element in the specified HtmlWindow by looking for forms whose name or id match the value specified. If window is nil, the search will begin in the base frame and search accessible frames recursively until a match is found.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | window | The HtmlWindow in which to search |
Input | formNameId | The id or name of the form to look for |
Output | HtmlElement |
GetFormElementFromForm(HtmlElement form, string fieldName)
Attempts to locate a field whose name or id matches the field name provided that is contained in the form provided.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | form | The form to searchfieldName - the name of the field to search for |
Output | HtmlElement |
GetFormElementFromFormName(string formName, string fieldName)
Attempts to locate a form whose name matches the form name provided, and if successful attempts to located and return the element inside that form whose name matches the field name provided.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | formName | The name of the form in which to search |
Input | fieldName | The name of the field to search for |
Output | HtmlElement |
GetFrameByName(HtmlWindow window, string frameName)
Attempts to locate a frame whose name matches the frameName provided. If window is nil, the search will begin in the page's base frame. If the frame cannot be found in the starting frame, a recursive search will be done on all of the frames contained in the starting frame.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | window | The window in which to begin the search |
Input | frameName | The name of the frame to search for |
Output | HtmlWindow |
GetFrameByWindowIndex(HtmlWindow window, int index)
Returns the HtmlWindow assigned to the specified index of the collection of frames belonging to the provided HtmlWindow.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | window | The window in which to search |
Input | index | The index of the frame to return |
Output | HtmlWindow |
GetParentElement(HtmlElement source)
Returns the element that is currently the parent of the HtmlElement provided.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | source | The element for which the parent is to be retrieved |
Output | HtmlElement |
Navigate(string url)
Attempts to load the specified url into the browser.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | url | The url to navigate to |
RegisterPageHandler(string idType, string id, string handlerName, bool critical)
Registers a new page handler for use in detecting when pages that have automated actions associated with them are loaded and alerting the user script to respond to the page load.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | idType | The type of matching that should be done against the given id |
Input | id | The id to match against |
Input | handlerName | The name of the Lua method that should be called when the page handler is invoked |
Input | critical | Whether or not the page handler is considered a critical page handler, which should exist outside of the normal queue and should be checked every time the the system checks for a page match |
A detailed description of the page handler types and how each works is listed in the Page Handlers section.
SetFormValue(object form, string fieldName, string value)
Attempts to locate the specified field in the provided form and set the field's value to the value provided.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | form | An HtmlElement representing the form, or a string containing the name of the form, whose field should be set |
Input | fieldName | The name of the field that should be set |
Input | value | The new value the field should be set to |
Show()
Causes the BrowserInterface to add all associated user interface elements to the current form.
This method must be called AFTER all calls to BrowserInterface:CreateButton, and no buttons may be added to the browser after it is shown.
StartPageWatcher(double checkInterval, double maxWatchTime)
Starts the page watcher, which will check the page handler queue (and critical page handlers) at an interval defined by checkInterval. If no match is found when the maxWatchTime is reached, the handler will stop. This is primarily used on pages that use Ajax or other similar methods to make dynamic changes to the page content without actually changing pages. In these cases, a page watcher can be started before performing an action that will cause a page update so that the new page state can be checked.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | checkInterval | The interval, in milliseconds, that the page handler queue should be checked |
Input | maxWatchTime | The maximum amount of time,in milliseconds, the page watcher should run before stopping |
If the page has a feature that allows detection of update completion, it may be slightly more efficient to check for that and call CheckHandlerQueue when the update is complete; thought the page handler is still quite efficient and often easier.
StopPageWatcher()
Stops the page watcher so that it will not perform any more checks on the page handler queue.
SubmitForm(string formName)
Attempts to find the form and invoke the form's "submit" member.
Parameter Direction | Parameter Name | Parameter Description |
|---|---|---|
Input | formName | The name or id of the form to submit |