using System;
using mshtml;
namespace Pajocomo.Windows.Forms
{
/// <summary>
/// Represents the <see cref="IWebBrowserObject">WebBrowser Object</see> property accessor.
/// </summary>
public interface IWebBrowserObjectPropertyAccessor : IDisposable
{
/// <summary>
/// Gets or sets of a property associated with the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <value>The value of the property</value>
/// <param name="propertyName">The property name.</param>
object this[string propertyName] { get; set; }
}
/// <summary>
/// Represents a WebBrowser object.
/// </summary>
public interface IWebBrowserObject : IDisposable, ICloneable
{
#region Properties
/// <summary>
/// Gets the property accessor to the properties of the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <value>The property accessor.</value>
IWebBrowserObjectPropertyAccessor Property { get; }
#region Behavior
/// <summary>
/// Gets or sets a value that indicates whether the <see cref="IWebBrowserObject">WebBrowser Object</see> is registered as a drop target for navigation.
/// </summary>
/// <value>
/// <see langword="true"/> if the <see cref="IWebBrowserObject">WebBrowser Object</see> is registered as a drop target for navigation; otherwise, <see langword="false"/>.
/// </value>
/// <remarks>
/// A drop target is an <see cref="IWebBrowserObject">WebBrowser Object</see> that has been registered to accept data from a drag-and-drop operation.
/// </remarks>
bool AllowDrop { get; set; }
/// <summary>
/// Gets or sets whether the <see cref="IWebBrowserObject">WebBrowser Object</see> is currently engaged in a navigation or downloading operation.
/// </summary>
/// <value>
/// <see langword="true"/> indicates that the <see cref="IWebBrowserObject">WebBrowser Object</see> is currently engaged in a navigation or downloading operation.
/// <see langword="false"/> indicates otherwise.
/// </value>
/// <remarks>
/// If the control is busy, you can use the <see cref="Stop"/> method to cancel the navigation or download operation before it is completed.
/// </remarks>
bool Busy { get; }
/// <summary>
/// Gets the active document.
/// </summary>
/// <value>
/// A reference to the active document.
/// </value>
/// <remarks>
/// <para>
/// When the active document is an HTML page, this property provides access to the contents of the HTML Document Object Model (DOM).
/// Specifically, it returns an IDispatch interface pointer to the HTMLDocument component object class (coclass).
/// The HTMLDocument coclass is functionally equivalent to the Dynamic HTML (DHTML) document object used in HTML script.
/// It supports all the properties and methods necessary to access the entire contents of the active HTML document.
/// </para>
/// <para>
/// When other document types are active, such as a Microsoft Word document, this property returns the default IDispatch dispatch interface (dispinterface) pointer for the hosted document object.
/// For Word documents, this would be functionally equivalent to the Document object in the Word object model.
/// </para>
/// </remarks>
object Document { get; }
/// <summary>
/// Gets the name of the resource that <see cref="IWebBrowserObject">WebBrowser Object</see> is currently displaying.
/// </summary>
/// <value>
/// The name of the resource that <see cref="IWebBrowserObject">WebBrowser Object</see> is currently displaying.
/// </value>
/// <remarks>
/// If the resource is an HTML page on the World Wide Web, the name is the title of that page.
/// If the resource is a folder or file on the network or local computer, the name is the full path of the folder or file in Universal Naming Convention (UNC) format.
/// </remarks>
string LocationName { get; }
/// <summary>
/// Gets the URL of the resource that <see cref="IWebBrowserObject">WebBrowser Object</see> is currently displaying.
/// </summary>
/// <value>
/// The URL of the resource that <see cref="IWebBrowserObject">WebBrowser Object</see> is currently displaying.
/// </value>
/// <remarks>
/// If the resource is a folder or file on the network or local computer, the name is the full path of the folder or file in the Universal Naming Convention (UNC) format.
/// </remarks>
string LocationUrl { get; }
/// <summary>
/// Gets or sets whether the <see cref="IWebBrowserObject">WebBrowser Object</see> control is currently operating in offline mode.
/// </summary>
/// <value>
/// <see langword="true"/> if the <see cref="IWebBrowserObject">WebBrowser Object</see> control is operating ofline; otherwise, <see langword="false"/>. The default is <see langword="false"/>.
/// </value>
/// <remarks>
/// In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.
/// </remarks>
bool Offline { get; set; }
/// <summary>
/// Gets the current state of the <see cref="IWebBrowserObject">WebBrowser Object</see> control.
/// </summary>
/// <value>
/// The current state of the <see cref="IWebBrowserObject">WebBrowser Object</see> control.
/// </value>
WebBrowserReadyStates ReadyState { get; }
/// <summary>
/// Gets or sets whether the <see cref="IWebBrowserObject">WebBrowser Object</see> can show dialog boxes.
/// </summary>
/// <value>
/// <see langword="true"/> if the object can display dialog boxes; otherwise, <see langword="false"/>. The default is <see langword="true"/>.
/// <list type="definition">
/// <item>
/// <term><see langword="true" /></term>
/// <description>Dialog boxes and messages can be displayed. Critical errors and security alerts are not supressed.</description>
/// </item>
/// <item>
/// <term><see langword="false" /></term>
/// <description>Dialog boxes are not displayed.</description>
/// </item>
/// </list>
/// </value>
bool Silent { get; set; }
/// <summary>
/// Gets a value that indicates whether the object is a top-level container.
/// </summary>
/// <value>
/// <see langword="true"/> if value that indicates whether the object is a top-level container; otherwise, <see langword="false"/>.
/// </value>
/// <remarks>
/// The <see cref="IWebBrowserObject">WebBrowser Object</see> returns <see langword="false"/> if it is in a frame.
/// </remarks>
bool TopLevelContainer { get; }
#endregion
#region mshtml
/// <summary>
/// Gets the <see cref="HTMLBodyClass"/> of the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <value></value>
/// <value>The HTML body.</value>
HTMLBodyClass HtmlBody { get; }
/// <summary>
/// Gets the <see cref="HTMLDocumentClass"/> of the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <value></value>
/// <value>The HTML document.</value>
HTMLDocumentClass HtmlDocument { get; }
/// <summary>
/// Gets the <see cref="HTMLWindow2Class"/> of the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <value></value>
/// <value>The HTML window.</value>
HTMLWindow2Class HtmlWindow { get; }
#endregion
#endregion
#region Methods
/// <summary>
/// Navigates backward one item in the history list.
/// </summary>
/// <returns>
/// <see langword="true"/> if the navigation succeds; <see langword="false"/> if the previous page in the navigation is not available.
/// </returns>
/// <remarks>
/// <para>
/// During a browsing session, the <see cref="IWebBrowserObject">WebBrowser Object</see> maintains a history list of all Web sites visited during a session (unless you specify the <see cref="WebBrowserNavigateFlags.NoHistory"/> flag when using the <see cref="Navigate"/> method).
/// Use the <see cref="WebBrowserControl.CommandStateChanged"/> event to check the enabled state of backward navigation.
/// If the event's <see cref="WebBrowserCommandStateChangeFlags.NavigateBack"/> command is disabled, the beginning of the history list has been reached and the <see cref="GoBack"/> method should not be used.
/// </para>
/// <seealso cref="GoForward">GoForward</seealso>
/// <seealso cref="GoHome">GoHome</seealso>
/// <seealso cref="GoSearch">GoSearch</seealso>
/// <seealso cref="Navigate">Navigate</seealso>
/// <seealso cref="WebBrowserControl.CommandStateChanged">WebBrowserControl.CommandStateChanged</seealso>
/// </remarks>
bool GoBack();
/// <summary>
/// Navigates forward one item in the history list.
/// </summary>
/// <remarks>
/// <para>
/// During a browsing session, the <see cref="IWebBrowserObject">WebBrowser Object</see> maintains a history list of all Web sites visited during a session (unless you specify the <see cref="WebBrowserNavigateFlags.NoHistory"/> flag when using the <see cref="Navigate"/> method).
/// Use the <see cref="WebBrowserControl.CommandStateChanged"/> event to check the enabled state of backward navigation.
/// If the event's <see cref="WebBrowserCommandStateChangeFlags.NavigateForward"/> command is disabled, the beginning of the history list has been reached and the <see cref="GoForward"/> method should not be used.
/// </para>
/// <seealso cref="GoBack">GoBack</seealso>
/// <seealso cref="GoHome">GoHome</seealso>
/// <seealso cref="GoSearch">GoSearch</seealso>
/// <seealso cref="Navigate">Navigate</seealso>
/// <seealso cref="WebBrowserControl.CommandStateChanged">WebBrowserControl.CommandStateChanged</seealso>
/// </remarks>
bool GoForward();
/// <summary>
/// Navigates to the current home or start page.
/// </summary>
/// <remarks>
/// The user can indicate the URL to use for the home or start page either from Internet Options in Microsoft Internet Explorer or from Internet Properties in Control Panel.
/// <seealso cref="GoBack">GoBack</seealso>
/// <seealso cref="GoForward">GoForward</seealso>
/// <seealso cref="GoSearch">GoSearch</seealso>
/// <seealso cref="Navigate">Navigate</seealso>
/// </remarks>
void GoHome();
/// <summary>
/// Navigates to the current search page.
/// </summary>
/// <remarks>
/// The user can indicate the URL to use for the search page either from Internet Options in Microsoft Internet Explorer or from Internet Properties in Control Panel.
/// <seealso cref="GoBack">GoBack</seealso>
/// <seealso cref="GoForward">GoForward</seealso>
/// <seealso cref="GoHome">GoHome</seealso>
/// <seealso cref="Navigate">Navigate</seealso>
/// </remarks>
void GoSearch();
/// <summary>
/// Loads the document at the specified Uniform Resource Identifier (URI) <see cref="string"/> into the <see cref="IWebBrowserObject">WebBrowser Object</see>,
/// requesting it using the specified HTTP data and replacing the contents of the Web page frame with the specified name.
/// </summary>
/// <param name="url">
/// A Uniform Resource Identifier (URI) <see cref="string"/> specification.
/// </param>
/// <param name="flags">
/// A <see cref="WebBrowserNavigateFlags"/> combination of values.
/// </param>
/// <param name="targetFrameName">
/// <para>
/// A case-sensitive string that contains the name of the frame in which to display the resource.
/// </para>
/// The possible values for this parameter are.
/// <list type="definition">
/// <item>
/// <term><c>_blank</c></term>
/// <description>Load the link into a new unnamed window.</description>
/// </item>
/// <item>
/// <term><c>_parent</c></term>
/// <description>Load the link into the immediate parent of the document the link is in.</description>
/// </item>
/// <item>
/// <term><c>_self</c></term>
/// <description>Load the link into the same window the link was clicked in.</description>
/// </item>
/// <item>
/// <term><c>_top</c></term>
/// <description>Load the link into the full body of the current window.</description>
/// </item>
/// <item>
/// <term>WindowName</term>
/// <description>A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.</description>
/// </item>
/// </list>
/// </param>
/// <param name="postData">
/// The data that is sent to the server as part of a HTTP POST transaction.
/// A POST transaction is typically used to send data gathered by an HTML form.
/// If this parameter does not specify any post data, this method issues an HTTP GET transaction.
/// This parameter is ignored if the URL is not an HTTP URL.
/// </param>
/// <param name="headers">
/// The additional HTTP headers to send to the server.
/// These headers are added to the default Microsoft Internet Explorer headers.
/// For example, headers can specify the action required of the server, the type of data being passed to the server, or a status code.
/// This parameter is ignored if the URL is not an HTTP URL.
/// </param>
/// <remarks>
/// <para>
/// The <see cref="IWebBrowserObject">WebBrowser Object</see> can browse to any location in the local file system, on the network, or on the World Wide Web.
/// </para>
/// <para>
/// In Internet Explorer 6 or later, you can navigate through code only within the same domain as the application hosting
/// the <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// Otherwise, this method is disabled.
/// </para>
/// <para>
/// In Windows Internet Explorer 7, when you specify the navOpenInNewTab flag or the navOpenInBackgroundTab flag, do not combine them
/// with other parameters (<paramref name="TargetFrameName" />, <paramref name="PostData" />, <paramref name="Headers" />)
/// or with other <see cref="WebBrowserNavigateFlags" /> flags.
/// If tabbed browsing is disabled, or if a tab cannot be created, the call will fail.
/// If this happens, choose another navigation method, such as <see cref="WebBrowserNavigateFlags.OpenInNewWindow"/>.
/// </para>
/// </remarks>
void Navigate(string url, WebBrowserNavigateFlags flags, string targetFrameName, byte[] postData,string headers);
/// <summary>
/// Loads the document at the specified Uniform Resource Identifier (URI) <see cref="string"/> into the WebBrowser object, replacing the previous document.
/// </summary>
/// <param name="url">
/// A Uniform Resource Identifier (URI) <see cref="string"/> specification.
/// </param>
void Navigate(string url);
/// <summary>
/// Prints the document currently displayed in the <see cref="IWebBrowserObject">WebBrowser Object</see> using the current print and page settings.
/// </summary>
/// <remarks>
/// You can use this method to implement a Print button similar to the one in Internet Explorer.
/// This method prints the current document without requiring further user input.
/// To display the Print dialog box prior to printing, use the ShowPrintDialog method.
/// To display the Page Setup dialog box, which lets your users specify header and footer values and other page settings, use the <see cref="ShowPageSetupDialog"/> method.
/// To display the Print Preview dialog box, use the <see cref="ShowPrintPreviewDialog"/> method.
/// <seealso cref="ShowPageSetupDialog">ShowPageSetupDialog</seealso>
/// <seealso cref="ShowPrintDialog">ShowPrintDialog</seealso>
/// <seealso cref="ShowPrintPreviewDialog">ShowPrintPreviewDialog</seealso>
/// </remarks>
void Print();
/// <summary>
/// Reloads the document currently displayed in the <see cref="IWebBrowserObject">WebBrowser Object</see> by checking the server for an updated version.
/// </summary>
/// <remarks>
/// <para>
/// This method is the same as clicking the <b>Refresh</b> button or pressing <b>F5</b> in Microsoft Internet Explorer.
/// </para>
/// <para>
/// To save time and network bandwidth, the <see cref="IWebBrowserObject">WebBrowser Object</see>
/// and InternetExplorer application store pages from recently visited sites in cached memory on the user's hard disk.
/// When you revisit a Web site, the page is reloaded from the local disk instead of being downloaded again from the server.
/// To ensure that you are viewing the most current version of the page, you can force a fresh download by using
/// the <see cref="IWebBrowserObject.Refresh" /> method.
/// This method adds the "Pragma: No-cache" HTTP header to the request.
/// </para>
/// <para>
/// Alternatively, you can temporarily disable the cache by using the <see cref="WebBrowserNavigateFlags.NoReadFromCache" /> flag
/// and the <see cref="WebBrowserNavigateFlags.NoWriteToCache" /> flag when you call the <see cref="Navigate" /> method.
/// </para>
/// </remarks>
/// <seealso cref="Refresh(WebBrowserRefreshLevel)" />
void Refresh();
/// <summary>
/// Reloads the document currently displayed in the WebBrowser object using the specified refresh level.
/// </summary>
/// <param name="level">
/// One of the <see cref="WebBrowserRefreshLevel"/> values.
/// </param>
/// <remarks>
/// The "pragma:nocache" header tells the server not to return a cached copy.
/// This ensures that the information is as fresh as possible.
/// Browsers typically send this header when the user selects refresh, but the header can cause problems for some servers.
/// </remarks>
/// <seealso cref="Refresh()" />
void Refresh(WebBrowserRefreshLevel level);
/// <summary>
/// Verifies that the Page Setup dialog box can be opened.
/// </summary>
/// <returns>
/// <see langword="true"/> if the Page Setup dialog box can be opened; otherwise, <see langword="false"/>.
/// </returns>
bool CanShowPageSetupDialog();
/// <summary>
/// Opens the Internet Explorer Page Setup dialog box.
/// </summary>
/// <returns><see langword="true" /> if </returns>
/// <remarks>
/// You can use this method to implement a Page Setup menu item similar to the one on the Internet Explorer File menu.
/// This method displays the Page Setup dialog box, which lets your users specify header and footer values and other page settings prior to printing.
/// To print the current document, use the Print method or the <see cref="ShowPrintDialog"/> method.
/// To display the Print Preview dialog box, use the <see cref="ShowPrintPreviewDialog"/> method.
/// <seealso cref="ShowPrintDialog">ShowPrintDialog</seealso>
/// <seealso cref="ShowPrintPreviewDialog">ShowPrintPreviewDialog</seealso>
/// </remarks>
void ShowPageSetupDialog();
/// <summary>
/// Verifies that the Print dialog box can be opened.
/// </summary>
/// <returns>
/// <see langword="true"/> if the Print dialog box can be opened; otherwise, <see langword="false"/>.
/// </returns>
bool CanShowPrintDialog();
/// <summary>
/// Opens the Internet Explorer Print dialog without setting header and footer values.
/// </summary>
/// <remarks>
/// You can use this method to implement a Print menu item similar to the one on the Internet Explorer File menu.
/// This method displays the Print dialog box, letting your users modify print settings prior to printing.
/// To let your users specify page settings prior to printing, use the <see cref="ShowPageSetupDialog"/> method.
/// To display the Print Preview dialog box, use the <see cref="ShowPrintPreviewDialog"/> method.
/// <seealso cref="ShowPageSetupDialog">ShowPageSetupDialog</seealso>
/// <seealso cref="ShowPrintPreviewDialog">ShowPrintPreviewDialog</seealso>
/// </remarks>
void ShowPrintDialog();
/// <summary>
/// Opens the Internet Explorer Print dialog box, setting the header and footer text to the specified values.
/// </summary>
/// <param name="header">
/// The text used for the page headers.
/// </param>
/// <param name="footer">
/// The text used for the page footers.
/// </param>
/// <remarks>
/// Use this method to specify header and footer values and display the Print dialog box, letting your users modify print settings prior to printing.
/// To let your users specify their own header and footer values and other page settings prior to printing, use the <see cref="ShowPageSetupDialog"/> method.
/// When you provide access to the Page Setup dialog box, use the <see cref="ShowPrintDialog"/> method to avoid overwriting the user-specified header and footer values.
/// To display the Print Preview dialog box, use the <see cref="ShowPrintPreviewDialog"/> method.
/// <seealso cref="ShowPageSetupDialog">ShowPageSetupDialog</seealso>
/// <seealso cref="ShowPrintPreviewDialog">ShowPrintPreviewDialog</seealso>
/// </remarks>
void ShowPrintDialog(string header, string footer);
/// <summary>
/// Verifies that the Print Preview dialog box can be opened.
/// </summary>
/// <returns>
/// <see langword="true"/> if the Print Preview dialog box can be opened; otherwise, <see langword="false"/>.
/// </returns>
bool CanShowPrintPreviewDialog();
/// <summary>
/// Opens the Internet Explorer Print Preview dialog box.
/// </summary>
/// <remarks>
/// You can use this method to implement a Print Preview menu item similar to the one on the Internet Explorer File menu.
/// This method displays the Print Preview dialog box, letting your users see how the current document will appear if it is printed.
/// To let your users specify page settings prior to printing, use the <see cref="ShowPageSetupDialog"/> method.
/// To print the current document, use the Print method or the <see cref="ShowPrintDialog"/> method.
/// <seealso cref="ShowPageSetupDialog">ShowPageSetupDialog</seealso>
/// <seealso cref="ShowPrintDialog">ShowPrintDialog</seealso>
/// </remarks>
void ShowPrintPreviewDialog();
/// <summary>
/// Verifies that the Properties dialog box can be opened.
/// </summary>
/// <returns>
/// <see langword="true"/> if the Properties dialog box can be opened; otherwise, <see langword="false"/>.
/// </returns>
bool CanShowPropertiesDialog();
/// <summary>
/// Opens the Internet Explorer Properties dialog box for the current document.
/// </summary>
/// <remarks>
/// You can use this method to implement a Properties menu option similar to the one on the Internet Explorer File menu.
/// This method displays the Properties dialog box, which contains information about the current document such as its type, URL, size, and dates of creation and modification.
/// </remarks>
void ShowPropertiesDialog();
/// <summary>
/// Verifies that the Save Web Page dialog box can be opened.
/// </summary>
/// <returns>
/// <see langword="true"/> if the Save Web Page dialog box can be opened; otherwise, <see langword="false"/>.
/// </returns>
bool CanShowSaveAsDialog();
/// <summary>
/// Opens the Internet Explorer Save Web Page dialog box or the save dialog box of the hosted document if it is not an HTML page.
/// </summary>
/// <remarks>
/// You can use this method to implement a Save As menu item similar to the one on the Internet Explorer File menu.
/// The dialog box that appears when this method is called depends on the document type currently loaded.
/// </remarks>
void ShowSaveAsDialog();
/// <summary>
/// Cancels any pending navigation and stops any dynamic page elements, such as background sounds and animations.
/// </summary>
/// <seealso cref="Busy">Busy</seealso>
/// <seealso cref="WebBrowserControl.Navigating">WebBrowserControl.Navigating</seealso>
/// <seealso cref="WebBrowserControl.Downloading">WebBrowserControl.Downloading</seealso>
/// <seealso cref="WebBrowserControl.ProgressChanged">WebBrowserControl.ProgressChanged</seealso>
void Stop();
/// <summary>
/// Creates a new <see cref="IWebBrowserObject">WebBrowser Object</see> that is a copy of the current <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </summary>
/// <returns>
/// A new <see cref="IWebBrowserObject">WebBrowser Object</see> that is a copy of the current <see cref="IWebBrowserObject">WebBrowser Object</see>.
/// </returns>
new IWebBrowserObject Clone();
/// <summary>
/// Verifies that the <see cref="IWebBrowserObject">WebBrowser Object</see> can execute the specified command.
/// </summary>
/// <param name="command">The commando execute.</param>
/// <returns>
/// <see langword="true"/> if the command can be executed; otherwise, <see langword="false"/>.
/// </returns>
bool CanExecuteCommand(WebBrowserCommand command);
/// <summary>
/// Executes a command.
/// </summary>
/// <param name="command">The command to execute.</param>
/// <returns>The output of the command execution.</returns>
/// <exception cref="T:COMException">
/// When an error occurs.
/// </exception>
object ExecuteCommand(WebBrowserCommand command);
/// <summary>
/// Executes a command.
/// </summary>
/// <param name="command">The command to execute.</param>
/// <param name="options">The command execution options.</param>
/// <returns>The output of the command execution.</returns>
/// <exception cref="T:COMException">
/// When an error occurs.
/// </exception>
object ExecuteCommand(WebBrowserCommand command, WebBrowserCommandExecutionOptions options);
/// <summary>
/// Executes a command.
/// </summary>
/// <param name="command">The command to execute.</param>
/// <param name="input">The input of the command.</param>
/// <returns>The output of the command execution.</returns>
/// <exception cref="T:COMException">
/// When an error occurs.
/// </exception>
object ExecuteCommand(WebBrowserCommand command, object input);
/// <summary>
/// Executes a command.
/// </summary>
/// <param name="command">The command to execute.</param>
/// <param name="options">The command execution options.</param>
/// <param name="input">The input of the command.</param>
/// <returns>The output of the command execution.</returns>
/// <exception cref="T:COMException">
/// When an error occurs.
/// </exception>
object ExecuteCommand(WebBrowserCommand command, WebBrowserCommandExecutionOptions options, object input);
/// <summary>
/// Queries the <see cref="IWebBrowserObject">WebBrowser Object</see> for the status of commands.
/// </summary>
/// <param name="command">The command for which the caller needs status information.</param>
/// <returns>A <see cref="WebBrowserCommandStatus"/> value with the status of the command.</returns>
WebBrowserCommandStatus QueryCommandStatus(WebBrowserCommand command);
#endregion
}
}
Submit an article or tip