StudioTips - HTMLControl

HTMLControl

Documentation on the HTML Control is available in the F1 Help by searching for Document Viewer. (not HTML Control as I discovered.) Some of the information in this section is copied directly from the F1 Help.

The Document Viewer is an external component for viewing HTML files in a window class. The Document Viewer is used extensively in Omnis, specifically in the Welcome application to display the Omnis help and tutorial HTML files.

When placed on a window you can change the properties of the HTML component under the Custom tab in the Property Manager. The component does not have a $dataname property, instead you specify the path to an HTML text file in the $filename property. You can set the $filename in design mode or set it dynamically at runtime.

The HTML control can display HTML files stored locally. Unfortunately, the HTML control can not display files or images on the internet.

Use the openURL object class available in the downloads section of the studiotips.net to open the client's default web to a URL which you specify.

The section explains the special properties and methods for the HTML control.

Click the Run Demo button in the StudioTips Browser to test the various properties and methods of an HTML Control component.

The first time you run this demo, you must click the Set an HTML File button and point the control to a valid HTML file on your computer.

$event

The HTML component reports many different events and you can write event handlers in the object's $event method to handle them. When you create the HTML component from the Component Store a template $event method is inserted to handle the basic events in the object at runtime. Note all the events for the HTML component return the $ident of the field as the first event parameter.

The HTML component receives the following event messages:

evAnimateScrollEnd - sent when the HTML component is finished scrolling; returns the parameters pEventCode, pCtrlIdent
evEventTag - sent when an embedded custom Html tag is read; returns the parameters pEventCode, pCtrlIdent, pName, pValue
evExecTag - sent when an embedded custom Html tag is executed; returns the parameters pEventCode, pCtrlIdent, pTagName, pTagValues
evHyperlink - sent when a hyperlink is clicked; returns the parameters
pEventCode, pCtrlIdent, pHRef, pName, pTarget, pTitle
evImagePluginCreate - sent when an embedded image plugin is invoked, such as an embedded JPEG object; returns the parameters pEventCode, pCtrlIdent, pType, pProperties, pWindowRef, pWidthRef, pHeightRef
evPluginDestroy
sent when an embedded plugin is destroyed; returns the parameters pEventCode, pCtrlIdent
evSetTitle
sent when the Html document is read; returns the parameters
pEventCode, pCtrlIdent, pTitle
evXCompPluginCreate
sent when an embedded external component is invoked; returns the parameters pEventCode, pCtrlIdent, pComponentLib, pComponentCtrl, pProperties, pWindowRef, pWidthRef, pHeightRef

The sample code below was pasted from the $event method of the HTML Control in the Component Store.

On evAnimateScrollEnd
;

On evSetTitle
Calculate $cwind.$title as pTitle

On evHyperlink
If pos(".lbs",pHRef)
   Calculate lOmnisLibPath as pHRef
   Do $cobj.$pathtoapi(lOmnisLibPath)
   Open library (Do not close others) {[lOmnisLibPath]}
Else
   Do method $setUrl (pHRef)
End If

On evEventTag
; deal with custom html events

On evExecTag
; deal with the following html tags (pTagValues contains list of propertie names and values)
; <BGSOUND loop=value src=url>

On evImagePluginCreate
Switch pType
   Case 'JPEG'
      Set reference lObjRef to $cinst.$objs.$add(kComponent,"JPEG Library","JPEG Control",-100,-100,10,10,kFalse,kFalse)
   Case 'GIF'
      Set reference lObjRef to $cinst.$objs.$add(kComponent,"Gif Library","Gif Control",-200,-200,10,10,kFalse,kFalse)
   Case 'PCX'
      Set reference lObjRef to $cinst.$objs.$add(kComponent,"PCX Library","PCX Control",-200,-200,10,10,kFalse,kFalse)
End Switch
Do lObjRef.$visible.$assign(kFalse)
Do method AssignProperties (lObjRef,pProperties)
Calculate as eval('pWindowRef.$assign(lObjRef.$framehwnd)')
If not(pWidthRef)
   Calculate as eval('pWidthRef.$assign(lObjRef.$imagewidth)')
End If
If not(pHeightRef)
   Calculate as eval('pHeightRef.$assign(lObjRef.$imageheight)')
End If
Do __HtmlCtrlObjsList.$add(pCtrlIdent,lObjRef.$ident)

On evXCompPluginCreate
If pComponentLib="internal"
   Set reference lObjRef to $cinst.$objs.$add(eval(pComponentCtrl),-pWidthRef,-pHeightRef,pWidthRef,pHeightRef,kFalse,kFalse)
Else
   Set reference lObjRef to $cinst.$objs.$add(kComponent,pComponentLib,pComponentCtrl,-pWidthRef,-pHeightRef,pWidthRef,pHeightRef,kFalse,kFalse)
   If pComponentCtrl=$cobj.$componentctrl
      Calculate lObjRef.$eventhwnd as $cobj.$framehwnd
   End If
End If
Do method AssignProperties (lObjRef,pProperties)
Calculate as eval('pWindowRef.$assign(lObjRef.$framehwnd)')
Do __HtmlCtrlObjsList.$add(pCtrlIdent,lObjRef.$ident)

On evPluginDestroy
Do __HtmlCtrlObjsList.$search(__HtmlCtrlident=pCtrlIdent,kTrue,kFalse,kTrue,kTrue)
Do __HtmlCtrlObjsList.$first(kTrue,kTrue) Returns lSearchRef
While len(lSearchRef)
   Do __HtmlCtrlObjsList.$loadcols()
   Set reference lObjRef to $cinst.$objs.$findident(__HtmlCtrlObjIdent) ;; get reference to plugin object
   Do $cinst.$objs.$remove(lObjRef) ;; remove plugin object from window
   Do __HtmlCtrlObjsList.$remove(__HtmlCtrlObjsList) ;; remove object from list
   Do __HtmlCtrlObjsList.$first(kTrue,kTrue) Returns lSearchRef
End While

$filename

The HTML control will display the HTML file specified in the $filename property.

The file made be a valid HTML file on the local machine or local network.

Do HTMLControlRef.$filename.$assign(FilePath)

$fontsizeadj

A numeric adjustment between -3 and 3 to apply to the font size

; Increase font size
If HTMLControlRef.$fontsizeadj<3
Do HTMLControlRef.$fontsizeadj.$assign(HTMLControlRef.$fontsizeadj+1)
End If

; Decrease font size
If HTMLControlRef.$fontsizeadj>-3
Do HTMLControlRef.$fontsizeadj.$assign(HTMLControlRef.$fontsizeadj-1)
End If

$getselectedtext

Do HTMLControlRef.$getselectedtext(cText)

Sets cText to the text which is currently selected in the document.

Text that is selected by $searchwords is ignored by this method.

$pathtoapi

Converts cPath from the HTML syntax to the syntax for the current platform, and sets cPath to the result.

Do HTMLControlRef.$pathtoapi(cPath)

I haven't figured out where or how I would use this method.

$pathtohtml

Converts cPath from the syntax for the current platform to the HTML syntax, and sets cPath to the result.

Do HTMLControlRef.$pathtothml(cPath)

I haven't figured out where or how I would use this method.

$printdocument

Prints the document

Do HTMLControlRef.$printdocument()

$searchwords

A space separated list of up to five words which will be highlighted in the displayed document when the document is opened.

The $searchwords property must be set before setting the $filename property, so after you set the $seachwords property you will need to reset the $filename property.

Do HTMLControlRef.$searchwords.$assign(cSearchString)
Do HTMLControlRef.$filename.$assign(irHTMLCtrl.$filename)

$startanimatescroll

Starts scrolling the document once every iInterval milliseconds by the specified units

Do HTMLControlRef.$startanimatescroll(iHorzScrollUnits,iVertScrollUnits,iInterval)

Do HTMLControlRef.$startanimatescroll(0,1,100)

$stopanimatescroll

Stops automatic scrolling of the document

Do HTMLControlRef.$stopanimatescroll()

Lining up Hyperlinks

If you want to overlay a multi-line entry field with an hmtl view of the same thing with hyperlinks added you run into a problem with the margins shifting. While that xcomp doesn't have any margin control properties, you can compensate in the HTML itself, adding to the opening body tag:

You will need to adjust the values for the font and size you use in order to shift the text to align with the scrolling entry field behind the html overlay. Once added you can make the hyperlinks come and go without any shifty glitches.

This tip has been provided by Kelly Burgess and Michael Monschau.