Almost everyone has used the MFC AppWizard to create a CHtmlView-based application at least once. Many of us also have written programs which are totally based upon CHtmlView and hence on the WebBrowser control. When you use the MFC AppWizard to create the project, you'll get a relatively nice and functional web browser right away. You can simply implement standard commands of a web browser like Back, Forward, Home, Refresh, etc. by means of methods provided by CHtmlView. Nothing could be easier than this! But, what if you want to implement the View Source command for example? Or, let's say, you need to have Add to Favorites command, or show the Properties dialog for the page. Any of these requires writing the code yourself, which involves doing a research to find out how what you want to do should be done, trying to implement it, debug the code, etc. This article's goal is to demonstrate the implementation of common commands applicable to the WebBrowser control, with use of CHtmlView.
I introduce a C++ class, derived from CHtmlView, named CHtmlView2 in this article. It has numerous member functions for performing different things that is available in the Internet Explorer itself. Some of those member functions are simply a one-line call to a CHtmlView function to do a specific job, and some of them consist of lots of COM code to deal with the details of the WebBrowser control. This class was evolved from one of my own projects which was centered around the WebBrowser control. I was wondering how can I perform different things, like for example invoking the Find dialog box (which is an HTML dialog by the way); and this class is the result of my work.
Here I provide an alphabetically sorted list of the member functions important to the user of the class. To see how these functions can be used, see the sample application. Under the Command menu of the sample application, all the features that my class is providing is shown. You can simply play with it, and also view the source code for each message handler function inside the sample's CCommonCommandsView class. Of course nearly all of these functions are as easy-to-use as possible, most of them don't receive any parameters, and they simply return bool, or void, so using them must be easy to everyone!
bool AddToFavorites( );
This function shows the standard Add to Favorites dialog which allows the user to add the current HTML document being displayed to the Favorites folder. It acts like IE's Add to Favorites menu command.
void Copy( );
This function copies the selected parts of the document, if any, to the Clip Board. It acts like the standard IE's Copy command.
bool CreateShortcut( );
This function creates a shortcut file (with .url extension) to the current document inside a user-selected folder. This function shows a dialog which allows the user to select (or create) a directory, and then it saves the shortcut file inside that directory. If the title of the current page is TITLE, the file name would be “Shortcut to TITLE.url”.
void Cut( );
This function cuts the selected parts of the document, if any, to the Clip Board. When using this function, note that it actually * cuts* the selection, not simply copy it. It means that if you select a picture, and invoke the Cut( ) function, the picture itself will disappear from the page being displayed! Exactly as it would happen when using an HTML editor. To prevent this odd and non-user-friendly behavior, you should use another function, UpdateCutHelper( ), as I'll describe later in this article.
BOOL FontSizeLargestUpdateHelper( );
This function, like the other update helper functions you'll see later, is useful inside ON_UPDATE_COMMAND_UI handlers. You usually call a CCmdUI function passing the return value from one of the update handler functions to it, and everything is taken care of automatically. The CHtmlView2 provides the facility of changing the text size, as IE does using its View | Text Size menu items. Five possible font sizes can be selected: Smallest, Small, Medium, Large, Largest. This function returns TRUE if the font size is set to Largest, and FALSE otherwise. Usually (as in the sample application) its return value is passed to CCmdUI::SetRadio( ).
BOOL FontSizeLargeUpdateHelper( );
This update handler function returns TRUE if the font size is set to Large, and FALSE otherwise.
BOOL FontSizeMediumUpdateHelper( );
This update handler function returns TRUE id the font size is set to Medium, and FALSE otherwise.
BOOL FontSizeSmallestUpdateHelper( );
This update handler function returns TRUE id the font size is set to Smallest, and FALSE otherwise.
BOOL FontSizeSmallUpdateHelper( );
This update handler function returns TRUE id the font size is set to Small, and FALSE otherwise.
CString GetActiveElement( );
This function returns a CString object which contains the HTML tag name of the currently selected element on the page. For example, it might be “IMG” if the user has selected a picture, or “P” if she has selected a text paragraph. If a text input element is active, the return value will be “INPUT-TEXT”. If a file selection input element is selected, the return value will be “INPUT-FILE”. If a password input field is active, the return value will be “INPUT-PASSWORD”. If an error occurs, the return value is “". The return value is always an upper case string.
bool GetActiveElement( IHTMLElement * ppActiveElement );
This function returns a pointer to the document's active element, in form of an IHTMLElement interface. If this function succeeds, * ppActiveElement is set to point to the active element's IHTMLElement, and the function returns true. If the function fails, the return value is false, and * ppActiveElement is not changed.
enum CHtmlView2::FontSize GetCurrentFontSize( );
This function returns the current font size in form of the CHtmlView2::FontSize enum.
CString GetDocumentSelection( );
This function returns the HTML code of the selected document parts in form of a CString object. If this function fails, or no part is selected, the return value is an empty string.
bool InvokeFind( );
This function shows the IE's default Find dialog which can be used for finding pieces of text inside the page.
bool InvokeInternetOptions( );
This function shows the Internet Options dialog which is accessible from Control Panel, as well as IE's Tools menu.
bool InvokeViewSource( );
This function shows the HTML source of the current page inside the default program for showing text files. This function is similar to the View Source function in IE.
bool IsGlobalOffline( );
This function returns true if the global connected setting is offline, and false if the global connected setting is online, or an error occurs. You can check the value of GetLastError( ) if you receive false from this function to figure out whether the status is online, or an error has occurred.
bool OrganizeFavorites( );
This function shows IE's default Organize Favorites dialog, which allows the user to manipulate the Favorites folder, and items inside it.
void Paste( );
This function pastes the contents of the clipboard into the current page. Take care when using this function, because it actually pastes the clipboard contents into the page, possibly changing how it looks like. For a more smart version of this function, use PasteSmart( ) instead.
void PasteSmart( );
This function pastes the contents of the clipboard only if a text edit field is active, so that it behaves like the normal IE's Paste command. To handle the Paste command for normal applications, use this function instead of Paste( ).
void Properties( );
This function shows IE's Properties dialog (which is an HTML dialog by the way) for the active item. If the active element is a picture, the Properties dialog for the picture is shown; if it's a link, the Properties dialog for the link is shown. Otherwise, the Properties dialog for the page itself will be shown. This function behaves exactly like IE's File | Properties menu item.
bool SaveInternetShortcut( LPCTSTR pszFileName, LPCTSTR pszURL, LPCTSTR pszDescription, LPCTSTR pszIconFile, int nIndex );
This function saves an internet shortcut file (with .url extension). The file name is specified by the pszFileName parameter; the URL of the item you want the shortcut to point to is specified by pszURL; the description for the shortcut is specified by pszDescription; the location of the icon file (with .ico extension) is specified by pszIconFile; and nIndex specifies the index for the icon if the icon file consists of more than one icon. The last three parameters are optional, if you pass NULL for pszDescription and pszIconFile, it means that the shortcut file will not have any description or icon file, if you pass -1 for nIndex, it means that the icon file's index is not required.
bool SavePage( );
This function shows the default file save dialog box, allows the user to choose a location/file name, and saves the current page (plus any of its dependency files, if any) in that location. Its behavior is exactly like the File | Save As menu item in IE.
void SelectAll( );
This function selects all the HTML document being displayed. Its behavior is just like IE's Edit | Select All menu item.
bool SetAsDesktopItem( IHTMLElement * pElement );
This function sets the item specified by pElement as an Active Desktop item, just like you right click the item in IE and choose Set As Desktop Item context menu command.
bool SetAsDesktopItem( );
This function sets the active element as an Active Desktop item.
void SetFontSizeLarge( );
This function sets the current font size to Large.
void SetFontSizeLargest( );
This function sets the current font size to Largest.
void SetFontSizeMedium( );
This function sets the current font size to Medium.
void SetFontSizeSmall( );
This function sets the current font size to Small.
void SetFontSizeSmallest( );
This function sets the current font size to Smallest.
static bool StartWebBrowser( );
This function starts the default web browser with an empty window.
void ToggleWorkOffline( );
This function toggles the connected state for the WebBrowser control from Online to Offline and vice versa. Its behavior is exactly like the File | Work Offline menu command in IE.
void Undo( );
This function undoes the last action, which is likely editing the text inside an input field.
BOOL UpdateCopyHelper( );
This update handler function returns TRUE when there is something to copy to the clipboard (in other words, something is being selected) and FALSE otherwise.
BOOL UpdateCutHelper( );
This update handler function returns TRUE when there is something to cut to the clipboard (in other words, some part of the text inside an input field is selected) and FALSE otherwise. Note that unlike UpdateCopyHelper( ), it does not return TRUE when anything is selected. This provides an easy way for preventing the user from cutting off pieces of the page unexpectedly by Cut( ). This function should be used inside the ON_UPDATE_COMMAND_UI handler for the Cut menu command, so that it disables the menu item when something other than the text inside an input field is selected. See the sample application to see how it's used with the Cut menu item.
BOOL UpdatePasteHelper( );
This update handler function returns TRUE when something appropriate for pasting into the document is available on the clipboard, and FALSE otherwise. It returns FALSE even when something appropriate to paste is available, but some part of the document other than an input field is selected. This prevents the odd behavior of replacing page contents with the clipboard contents as an HTML editor would do.
BOOL WorkOfflineUpdateHelper( );
This update handler function returns TRUE is the WebBrowser is in offline mode, and FALSE otherwise.
A note about using this class. Using this class is simply a matter of copying HtmlView2.h and HtmlView2.cpp files from the sample application to your application's directory, and deriving your view class from CHtmlView2 instead of CHtmlView. This involves replacing all the occurrences of CHtmlView with CHtmlView2 everywhere inside your view's .h and .cpp files.
Hope this class helps you during the development of your applications!
Bug Fixes:
10/24/2003 - Neville Franks (the author of ED for Windows, see http://www.getsoft.com) kindly reported a bug in the code which caused a crash on the occasions that the user selected a large portion of the document's text and right clicked on it. Actually he tracked the bug, and showed me how to fix it. So the whole credit of reporting and fixing the bug shall go to him.
Download source code for the article
This article originally appeared on BeginThread.com. It's been republished here, and may contain modifications from the original article.