Attach to the specified instance of Internet Explorer where the search string sub-string matches (based on the selected mode)
#include <IE.au3>
_IEAttach ( $sString [, $sMode = "title" [, $iInstance = 1]] )
| $sString | String to search for (for "embedded" or "dialogbox", use Title sub-string or HWND of window) |
| $sMode | [optional] specifies search mode "title" = (Default) sub-string of main document title "windowtitle" = sub-string of full window title (instead of document title) "url" = sub-string or url of the current page "text" = sub-string in text from the body of the current page "html" = sub-string in html from the body of the current page "hwnd" = hwnd of the browser window "embedded" = title sub-string or hwnd of the window embedding the control "dialogbox" = title sub-string or hwnd of modal/modeless dialogbox "instance" = $sString is ignored, one browser reference returned (by matching instance number) from all available browser instances |
| $iInstance | [optional] 1-based index into group of browsers or embedded browsers matching $sString and $sMode. See Remarks. |
| Success: | an object variable pointing to the InternetExplorer Object for all but Embedded and DislogBox modes which return a Window Object. |
| Failure: | sets the @error flag to non-zero. |
| @error: | 5 ($_IEStatus_InvalidValue) - Invalid Value 7 ($_IEStatus_NoMatch) - No Match |
| @extended: | Contains invalid parameter number |
_IEAttach() provides the "dialogbox" parameter to attach to modal and modeless dialogs created by the browser.
It is important to note that not all dialogs created through browser interaction can be attached to and controlled in this way.
Many of these dialogs are actually standard windows and can be controlled through the traditional AutoIt window functions. A reliable way to tell the difference between these types of windows is to use the "AutoIt Window Info" tool to examine it -- if the window contains a control called "Internet Explorer_Server" then you can attach to it with this function, if it does not it is a standard window and traditional AutoIt windows functions must be used to control it.
HyperTextApplication (.hta) windows may be attached to using the "embedded" option.
The advanced Window Title selection syntax available to the standard Win* functions may be used in place of a title sub-string for the modes "dialogbox" and "embedded".
Use of $iInstance with the "embedded" mode: used to return a reference to a specific instance of a WebBrowser and is particularly useful when more than one exists in a particular window.
If you pass a window title in $sString using embedded mode, only the first window matching that title will be used.
If the WebBrowser control you desire is in another window you must pass the HWnd of that window rather than the title, or use the advanced Window Title selection syntax available to the standard Win* functions.
Use of $iInstance with all modes other than "embedded": used to return a browser reference from a groups of all windows that match the criteria from $sString and $sMode.
Instance order for "dialogbox" mode determined by the order returned by WinList() matching the title.
For all other modes the Instance order is determined by the Shell.Windows collection.
$iInstance values > 1 are set to 1 and a warning message is displayed when used with "hwnd" mode or with "dialogbox" mode when an HWnd is passed in $sString.
"dialogbox" and "embedded" modes can be used to attach to standard browser windows, but the object returned is that if the top level Window in the browser and not the InternetExplorer object.
Window objects do not offer access to all of the attributes of the InternetExplorer object (e.g. status text, address bar etc.).
As well, if you attempt to use a function like _IENavigate() on such an object you may receive COM errors due to the way that IE7 has implemented Tabs.
It may be useful to find browser instances in this way, but it is recommended that you immediately use _IEAttach() using one of the other modes and using information that you may have obtained from the Window object in order to get a reference to the associated InternetExplorer object.
_IECreate, _IECreateEmbedded, _IEQuit
; Attach to a browser with "AutoIt" in its title, display the URL
#include <IE.au3>
#include <MsgBoxConstants.au3>
Local $oIE = _IECreate("www.autoitscript.com")
Local $oIE1 = _IECreate("www.google.com")
$oIE = _IEAttach("AutoIt")
MsgBox($MB_SYSTEMMODAL, "The URL", _IEPropertyGet($oIE, "locationurl"))
_IEQuit($oIE)
_IEQuit($oIE1)
; Attach to a browser with "simple HTML page"
; in the text of it's top-level document
#include <IE.au3>
Local $oIE_basic = _IE_Example("basic")
Local $oIE = _IEAttach("simple HTML page", "text")
ConsoleWrite('@@ Debug(' & @ScriptLineNumber & ') : $oIE = ' & $oIE & @CRLF & '>Error code: ' & @error & ' Extended code: 0x' & Hex(@extended) & @CRLF) ;### Debug Console
; Create an array of object references to all current browser instances
; The first array element will contain the number of instances found
#include <IE.au3>
#include <MsgBoxConstants.au3>
Local $aIE[1]
$aIE[0] = 0
Local $i = 1, $oIE
While 1
$oIE = _IEAttach("", "instance", $i)
If @error = $_IEStatus_NoMatch Then ExitLoop
ReDim $aIE[$i + 1]
$aIE[$i] = $oIE
$aIE[0] = $i
$i += 1
WEnd
MsgBox($MB_SYSTEMMODAL, "Browsers Found", "Number of browser instances in the array: " & $aIE[0])