CapeSoft.Com
Clarion Accessories
ChromeExplorer
Documentation
Download Latest Version Index FAQ History Templates Classes
CapeSoft Logo

CapeSoft Chrome Explorer
Documentation

Installed Version Latest Version

Introduction

ChromeExplorer requires StringTheory 3 or later.

ChromeExplorer allows you to include a Chromium based browser control in your application. You use a control template to simply place an HTML control on your window.

An HTML Editor class is also included (based on the CKEditor 4 control.) This allows your user to edit HTML in a WYSIWYG way.

Webinars

First Release Webinar on ClarionLive is at https://www.clarionlive.com/BrowseEpisodes/ww!553 (Start at 19:40 because there is a long introduction of other things)

Another Webinar (https://www.clarionlive.com/BrowseEpisodes/ww!615) after the 1.30 release discusses the embed code in the example in detail, and looks at new features like the ACE Code editor, using the ACE editor with the CK editor, and calling JavaScript.

Interacting with web pages, and web sites can become complicated because of String Encoding issues. If you are not familiar with the notion of string encoding, then the webinar #583 is strongly recommended. https://www.clarionlive.com/BrowseEpisodes/ww!583

For a practical look at how String Encoding affects Chrome Explorer see https://www.clarionlive.com/BrowseEpisodes/ww!584

Requirements

To compile, ChromeExplorer requires StringTheory 3 or later.

If you are using Resize And Split then make sure you are on build 5.03 or later of that. Failure to do this will result in your program disappearing when the ChromeExplorer window is opened (and other explained "funnies".)

To run, ChromeExplorer requires Windows Vista or later. ChromeExplorer may work, but is not supported on Windows XP.

The Chrome browser does not need to be installed on the computer. If the Chrome browser is installed on the computer, it does not affect your program.

Features

Support

Your questions, comments and suggestions are welcome. Check our web page (https://www.capesoft.com/accessories/downloads.htm) for new versions. You can also contact us in one of the following ways.

CapeSoft Support
Email
Telephone +27 87 828 0123
(087) 828 0123

Installing Chrome Explorer

IMPORTANT

1. Open the \clarion\accessory\ChromeExplorerProcess\ChromeExplorerProcess.Sln solution and compile it. See ChromeExplorerProcess.

RED File Requirements

The Clarion REDirection file system allows for a lot of possible RED file locations. The Installer will make the following changes to the default RED file, however you may need to make these changes manually to the RED file your application is using.

*.pak=%ROOT%\Accessory\bin
*.bin=%ROOT%\Accessory\bin
*.dat=%ROOT%\Accessory\bin
*.json=%ROOT%\Accessory\bin    ! NEW

 

Converting From CapeSoft File Explorer

Because of the intrinsic differences between the File Explorer OCX approach and the separate-process approach used by Chromium, it is not practical to create a "simple" upgrade from File Explorer to Chrome Explorer.

Fortunately most applications do not use lots of File Explorer controls, so converting from FileExplorer is simply a case of removing the File Explorer control, and adding the Chrome Explorer control to the window.

Acknowledgements

On the Clarion side, all the hard work in this product has been developed by Dries Driessen. It is thanks to his skill and tenacity that this product exists.

The Chromium Embedded Framework is Copyright (c) 2008-2020 Marshall A. Greenblatt. Portions Copyright (c) 2006-2009 Google Inc. All rights reserved. It is included here under the terms of the license (https://bitbucket.org/chromiumembedded/cef/src/master/LICENSE.txt)
Please take a moment to read this license as it may affect your own product documentation requirements.

The CKEditor 4 is Copyright 2003-2022 by CKSource and Frederico Knabben. It is included in this product under the terms of their license options at https://ckeditor.com/legal/ckeditor-oss-license/ . If you are using the CKEditor you should be aware of their Terms of Use - https://ckeditor.com/legal/terms-of-use/
You can create a custom version of the editor, using your own choice of features and plugins at https://ckeditor.com/cke4/builder .

The ACE Code Editor  is Copyright (c) 2010 by Ajax.org B.V. It is included here under the terms of the BSD license.

License & Copyright

The template and classes in this product are Copyright 2023 by CapeSoft Software.

Each developer needs his own license to use Chrome Explorer. (Need to buy more licenses?)

The ChromeExplorerProcess Exe is copyright 2023 by CapeSoft Software. It can be distributed without restriction with any program that uses the Chrome Explorer classes.

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software CC, their employees, contractors, contributors or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

CKEditor 4 is Copyright 2003-2022 by CKSource and Frederico Knabben. It is included in this product under the terms of their license options at https://ckeditor.com/legal/ckeditor-oss-license/ . If you are using the CKEditor you should be aware of their Terms of Use - https://ckeditor.com/legal/terms-of-use/

The CEF Engine is  Copyright (c) 2008-2022 Marshall A. Greenblatt. Portions Copyright (c)  2006-2009 Google Inc. All rights reserved.

The ACE Code Editor  is Copyright (c) 2010 by Ajax.org B.V.

Chromium Embedded Framework

The Chromium Embedded Framework 3 (CEF) is based on open-source code which is the code that underlies many of today's browsers including Chrome, Opera and Edge.

The files shipped with Chrome Explorer are self-contained. The user does not need to have the Chrome browser installed, and if they do have the Chrome browser installed then this behaves separately to that.

Because the Chromium engine is updated on an almost continuous basis it is expected that regular Chrome Explorer updates will happen as well. In order for your application to use the latest Chromium engine you should plan to update your Chrome Explorer version more or less every quarter. Of course older engines will continue to function, probably for a long period of time, but staying more-or-less up to date can limit surprises with sites that require the most modern browser features.

The full text of the CEF License is available at https://bitbucket.org/chromiumembedded/cef/src/master/LICENSE.txt

The important parts to know are;

The CEF Engine is  Copyright (c) 2008-2021 Marshall A. Greenblatt. Portions Copyright (c)  2006-2009 Google Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are  met:

Support for Audio and Video

The Chromium engine does not ship with support for licensed video and audio formats because it does not have a license to do so.
This means that audio formats, like MP3 and video formats, like MP4, will not be playable in a Chrome Explorer window. Open formats, such as ogg and webm are supported.

However most web sites are now providing video in open formats, so sites like youtube.com and vimeo.com are working.

ChromeExplorerProcess Exe

The CEF code runs in a separate process, using the supplied utility (ChromeExplorerProcess.Exe). This means that even if the Chromium engine code should crash for some reason, your application will not.

After installing ChromeExplorer you should compile the ChromeExplorerProcess program. To do this;
  1. Open the IDE
  2. Load \Clarion\Accessory\ChromeExplorerProcess\ChromeExplorerProcess.Sln
  3. You can see the solution has loaded if you look in the Solutions pad
  4. Click on the "Build Solution" button
  5. You can see the solution compiled successfully in the output pad. You'll see that the result (ChromeExplorerProcess.Exe) was copied to your \clarion\accessory\bin folder. When your app compiles it (and all the other files CE uses) will be copied to your Exe folder.
  6. Close the Solution.


CK Editor

To provide HTML editing functionality the CK Editor, version 4, is included with Chrome Explorer. The latest version of the editor can be downloaded from https://ckeditor.com/ckeditor-4/download/.

Important: The editor contains an enormous slew of functions, probably more than you expect or imagine. It is worth taking the time to see what features are available, so you can best decide which features to include in the control in your application. Advanced features like View/Edit the HTML source directly as well as Paste-From-Word and Paste-From-Excel can easily be included, or excluded from the editor.

The editor is available in 3 versions - the difference being the complexity of the toolbar that the user will see. Chrome Explorer ships with all three versions, so you can choose which one(s) to use in your application. The Control template lets you select which one will be used.

You can also create, and download, one or more Custom versions of the editor from the downloads link. The control template supports you selecting your preferred version, or your custom version.

The ones shipping with Chrome Explorer are as follows;

Each editor folder contains a build-config.js file. This can be uploaded to the Builder site to repeat the configuration in that folder.

You can read more at HTML Editor .

Note 1
The Chrome Explorer shipping folders (\clarion\accessory\bin\...) with the CKEditor component contain all the languages, and all the skins supported by the editor. You can reduce the size of the install by limiting the languages and skins you ship. If you do not use the HTML Editor in your program you do not need to ship these files at all.

Note 2
The CKEditor version 4 is chosen over version 5 because of the license restrictions of version 5. If you wish to use version5, and have a license to do so, then it is fairly straight-forward to construct your CkEditor5.Htm file, and ship it with the CK Editor 5.

Spell Checking

Spell checking in the HTML editor is somewhat complicated, depending on your goals, and the way you are using the control.
CK Editor Documentation: A good starting point is https://ckeditor.com/docs/ckeditor4/latest/features/spellcheck.html .

The native browse spell checking may be sufficient for your needs. Contrary to the CKEditor downloads, in the ChromeExplorer shipping config.js files, the browser spell checking has been enabled by default. This is done with ;

    config.disableNativeSpellChecker = false; // capesoft

towards the bottom of the file. If you download a custom editor from the CKEditor download site, you may want to re-instate this line.

The other mechanisms that CKEditor offers for spell checking are online. This makes them unsuitable for use by the local ckeditor.htm file because the browser does not allow web access when the page being loaded is loaded off the local hard drive.

As noted in the CKDocumentation, if you have any widgets that are trapping the right-mouse click, then you may need to control-mouse-click to see the browser-based spell checking.

ACE Code Editor

Chrome Explorer provides code editing using the ACE Code editor.the latest version of this editor can be downloaded from https://ace.c9.io/

The ACE editor is a full-featured source editor which supports over 35 themes, and over  160 programming languages (and no, Clarion is not one of them.)
While the vast majority of languages won't be terribly useful in a Clarion program, supported languages include Ascii, INI, Text, Markdown, XML, JSON, HTML, CSS, JavaScript, PHP, Powershell, SQL, SQL Server, MySQL, pgSQL, and Powershell all of which could easily be useful in a program.

Apart from the theme and language (what ACE calls the mode) there are also many other features and options, way too many to detail here. For a "kitchen sink" example of the editor where you can see every possible option, and experiment with it, see https://ace.c9.io/build/kitchen-sink.html .

ACE can be updated from the github page (https://github.com/ajaxorg/ace-builds) - the src-noconflict folder is the one used by Chrome Explorer.

You can read more at HTML Editor .

Note 1
The Chrome Explorer shipping folder (\clarion\accessory\bin\ace\src-noconflict) contains mode files for all the supported programming languages, and theme files for all supported themes. If you do not need all these in your application then you can reduce the size of your install by removing files that are not needed.

Shipping / Distribution

As mentioned earlier, the CEF engine is a completely self-contained browser. Because of this there are a fair number of items that need to be included in the install file you create for your program. Note some files are new per build 1.34.

Web Browser Control

These files should be copied to your app folder when you compile. They need to be distributed with your Exe.

The program will create a GPUCache folder when it runs, this folder does not need to be distributed.

NOTE: The above files add up to a substantial size, and can bloat your program install. If you like all the above files (except 1) can be included in a separate install file, which only needs to be updated when the Chromium Engine in Chrome Explorer is updated.

The one exception is the ChromeExplorerProcess.Exe program. That contains the CEF Classes, so should be included with your program install. But this Exe is very small.

Web Editor Control

If your program is using the Web Editor control then you will need to ship all the files mentioned in the Web Browser section above. You will also need to ship one, or more, of the editor folders. These folders will be copied to your application directory when your app compiles. If you have created a custom ckeditor folder then you will need to ship that as well.

Browser Settings

The following Browser settings are set when the program starts. These settings are made on the Chrome Explorer extension template, on the Settings tab. Although you can use expressions here (ie variables) instead of fixed values, these expressions are used once, on program startup, so any variables used would need to be primed early, before these variables are used. An embed point Before Chrome Explorer Settings is provided for this purpose.

Note that in Multi-DLL setups, if ABC, then these settings, and code, go in the Data DLL. If a Legacy app then it goes into the Exe app.

Cache Path

Chrome Explorer allows you to set the path to use for the browser cache. If this is not set the the browser is effectively running in an Incognito mode, and nothing is persisted to disk [1].

If this is set then the Chromium engine will use this location as a location for caching cookies, files and so on.

Note 1
In incognito mode a folder called GPUCache is still created. In the absence of a cache location being set, this folder will be created in the application folder.

Ignore Certificate Errors

If the global settings is on, and settings for the local control have been set, then you will be able to browse to some sites that contain a certificate error. (Certificate Expired, Certificate not Trusted, Wrong Certificate Name).

Use this option with care as it exposes the user to man-in-the-middle attacks, and greatly reduces the security of the browser. Typically only used in cases where browsing is to a LAN address where trusted certificates are hard to create.

This setting, by itself, does nothing. It still requires that the Insecure settings for the specific control be set as well.

Locale

The locale string that will be used. If not set then the default en-US is used. Valid local names match the file names in the applications Locales folder. If the locales folder is missing from the distribution then right-clicking on the control can lead to a blank popup to appear.

Log File

The location of the log file. If left blank then a file debug.log will be created in the exe directory. The items added to the log file are determined by the log severity, as set below.

Log Severity

Different levels of Log Severity determine the amount of information recorded in the log file. The global template option allows you to select from a drop-down. Severities include; Verbose , Debug, Info, Warning, Error and Fatal. Set this option to disable to turn off logging completely.

User Agent

The User Agent is a string sent to the web server, as a header in the HTTP request, when the browser makes a request. By default the "normal" Chrome user agent will be used.

If you wish the browser to send a custom User Agent header, then you can specify this on the Global Extension, Settings tab.

Adding Chrome Explorer to Your Application

Global Extension

Add the Chrome Explorer Global Extension Template to your application. To do this;
  1. Load your application in the Clarion IDE
  2. Click the Global button
  3. Click the Extensions button
  4. Click the Insert button
  5. Select the ActivateChromeExplorer template from the Select Extensions list that appears.
  6. Select the Select button and the Chrome Explorer Global Extension's prompts appear on the right-hand portion of the Extension and Control Templates window.
  7. Leave all the template options as they appear. The default's are fine for now. You can always come back and change them later...
  8. Make sure you have the StringTheory Global Extension added in the same way.
  9. Click OK a couple times until you're back in your app, then compile... That's it!!!

Global Properties - Legacy (Clarion) Templates

  1. From the Global Properties / Actions
  2. Classes Tab
  3. Tick ON the option to Enable the use of ABC Classes. [1]

Note 1
ChromeExplorer makes use of the CriticalSection class, which makes use of the ABC Conditional Compiles. So it's necessary to have this option on.

Web Browser Control Template

The Web Browser Control Template is the primary control you can place on a window. This control is where the web page, or file, will be displayed. You populate the control template on the window just as you would any control template, from the control templates pad.

The Browser control includes a URL Address entry field (and lookup button) but these can be deleted if you don't need them.

Navigation Buttons Control Template

A second control template, which is only available once the Web Browser Control Template has been added is the Navigation Buttons control template. This adds common browser navigation controls to the window.

Back, Forward, Stop, Refresh and Print are the buttons added. You can delete individual buttons from the window if you don't need them.

Search Control Template

Another control template, which is only available once the Web Browser Control Template has been added is the Search control template. This adds a seach control to the window.

HTML Editor Control Template

The HTML Editor Control template allows you to add a control to the window which allows the user to do WYSIWYG editing on the window. You can prime this control with text, and also extract the user text from the control.

String Encoding

For a primer on string encoding, and why it matters, see webinar #583 https://www.clarionlive.com/BrowseEpisodes/ww!583

It is not uncommon for web sites to include characters that are non-ASCII characters on the page, or in entry fields. When you programmatically interact with these pages, those characters have to be encoded so that your program can understand them.

For example;

GetHTMLSource let's you get the source code for the page currently being displayed. That source code may contain, say, Spanish characters. Once the source code ends up in a string in your program, the encoding of the string will matter.

For this reason, methods that interact with the raw text of the page have optional parameters which let you specify the encoding, and if necessary, the code page you wish to use.

There are three primary encodings supported. UTF-8 and UTF-16 are Unicode encodings. As at the time of writing this (Clarion 11), Clarion does not have native support for strings encoded as UTF-8 or UTF-16. That said, you can work with these strings, using StringTheory or similar.

To display the data on a Clarion screen, or report, you will need to convert it to ANSI. This could result in some data loss because ANSI makes use of code pages to encode the string. So if the web site was say in Spanish, then you would use the Spanish Code Page in your Clarion program.

You can store UTF-8 data in STRING or CSTRING variables. (You can't display it, but you can store it.) UTF-16 data can be stored in a STRING, but it CAN NOT be stored in a CSTRING variable.

When calling the various methods you can determine which encoding you prefer. You are then free of course to further convert this encoding on your own if you wish to do so. Once the Clarion USTRING data type becomes available, you may choose to keep the data encoded as UTF-16.

The following methods in the CEF_Class all have support for specifying the encoding. In all cases the default encoding is ANSI, with the code page that matches the System{prop:Charset} of your application.
The following methods in the CEF_EditorClass have support for specifying the encoding; The HTML Editor Control Template contains template settings for setting the encoding, and code page, of the data for the control.

You can specify the Code Page to use. Any Windows code page number is valid, for a subset see StringTheory.Inc
The most commonly used ones are;
st:CP_WINDOWS_1250  ! Central / Eastern Europe
st:CP_WINDOWS_1251  ! Cyrillic
st:CP_WINDOWS_1252  ! Western Europe / Scandinavia
st:CP_WINDOWS_1253  ! Greek
st:CP_WINDOWS_1254  ! Turkish
st:CP_WINDOWS_1255  ! Hebrew
st:CP_WINDOWS_1256  ! Arabic
st:CP_WINDOWS_1257  ! Baltic
st:CP_WINDOWS_1258  ! Vietnamese
st:CP_WINDOWS_874   ! Thai
st:CP_Big5          ! ANSI/OEM Traditional Chinese (Taiwan; Hong Kong SAR, PRC); Chinese Traditional (Big5)
st:CP_WINDOWS_936   ! NSI/OEM Simplified Chinese (PRC, Singapore); Chinese Simplified (GB2312)

JavaScript

Running JavaScript on the Page

The Script method provides the ability to run JavaScript on the page.
The script will execute, but no feedback will be returned to the program. If the script has a return value it will be ignored, and discarded.
For a more interactive way to run scripts see Calling a JavaScript Function with a Return Value.

Example

CEF.Script('whateverJavaScriptGoesHere();')

Calling a JavaScript Function with a Return Value

The CallScript method provides the ability to run a JavaScript function on the page, and get a return value.
The call is asynchronous, so it returns a unique ID, which can then be used later on to determine which call is being responded to.
The response will appear in either OnScriptResponse or OnScriptFailure. Both methods pass, as the first parameter the ID of the call to CallScript.

Note that the V8 JavaScript engine has to initialize before calls to CallScript can be made. This is done automatically. When the engine is ready the OnScriptReady method is called, and the ScriptReady property is set to true.

Example

someID = CEF.CallScript('someJavaScriptFunctionCallGoesHere(with,"some",parameters)')
if someId = 0
! call failed, see ErrorTrap
end

OnScriptResponse

If the call to the script is successful, then a CEF_ScriptResponseClass is passed into the method. You can use the methods of this object to determine the result from the call. to get the result, as a String use the GetValue method. Or you can use GetValueType to get the exact type, and then a matching GetValue method to get a specific value type.
ValueType Clarion Type Method to call
CEF:SCRIPTVALUETYPE:BOOL Long p_Response.GetBoolValue(long)
CEF:SCRIPTVALUETYPE:INT Long p_Response.GetIntValue(long)
CEF:SCRIPTVALUETYPE:UINT ULong p_Response.GetUIntValue(ulong)
CEF:SCRIPTVALUETYPE:DOUBLE Real p_Response.GetDoubleValue(real)
CEF:SCRIPTVALUETYPE:DATE
Dates are not currently supported. Tweak (or wrap) the JavaScript so it returns an Int or String instead.
CEF:SCRIPTVALUETYPE:STRING StringTheory p_Response.GetStringValue(st)
CEF:SCRIPTVALUETYPE:NULL
There is no value to fetch. The function returned either null or undefined. These values don't have direct equivalents in Clarion so you can process these as you desire - typically with a 0 value or blank string.
CEF:SCRIPTVALUETYPE:UNDEFINED
CEF:SCRIPTVALUETYPE:OBJECT
Objects are not currently supported. Tweak (or wrap) the JavaScript so it returns a String instead.JSON.Stringify may work well in this situation. Objects are likely to be supported ina future version.
CEF:SCRIPTVALUETYPE:FUNCTION
Functions being returned are not currently supported.


Arrays are not currently supported, but support is expected in a future release.
Example

CEF1.OnScriptResponse PROCEDURE (LONG p_CallbackID, CEF_ScriptResponseClass p_Response)
x Long
u Ulong
r Real
st StringTheory
code
PARENT.OnScriptResponse (p_CallbackID,p_Response)
if p_CallbackID = someID
case p_Response.GetValueType()
of CEF:SCRIPTVALUETYPE:BOOL
p_Response.GetBoolValue(x)
of CEF:SCRIPTVALUETYPE:DATE
p_Response.GetDateValue(r)
of CEF:SCRIPTVALUETYPE:Int
p_Response.GetIntValue(x)
of CEF:SCRIPTVALUETYPE:UINT
p_Response.GetUIntValue(u)
of CEF:SCRIPTVALUETYPE:DOUBLE
p_Response.GetDoubleValue(r)
of CEF:SCRIPTVALUETYPE:STRING
p_Response.GetStringValue(st)
end
end

OnScriptFailure

If the script fails to execute for some reason, then an errorcode, errormessage and a CEF_ScriptResponseClass object is passed into the method. You can use p_response.GetExceptionLineNumber() to return the line number that failed.

JavaScript calling Clarion

The above sections deal with Clarion code calling into JavaScript which is on the page. This section deals with the reverse, JavaScript code which calls back into the Clarion hosting procedure.

The magic is provided by a JavaScript command, called window.CEQuery. This call can take as many parameters as you like. The parameters can be strings, integers, reals, booleans, or objects. The last two optional parameters can be functions. These functions will be called when the Clarion program responds.
The CEQuery function only exists when the page has been loaded into a Chrome Explorer control, so you you make use of this function you should test for that.
(Remember that JavaScript is case sensitive.)

Example

In this example, the code checks to see if the function exists. If it does then it calls it with a single parameter ('user') and no reply is expected.

  if (typeof window.CEQuery !== "function"){
    console.log('This can only be called from a ChromeExplorer control');
    return
}
window.CEQuery('user')

In the following example two parameters are passed, a string ('Search') and a variable called customer. In addition two functions are set to receive either a success, or fail message, from Clarion. Note that these functions would be called asynchronously.


var customer = '123'
window.CEQuery('Search', customer,
                    function onsuccss(result){
                        // code goes here           
                    }
                    function onfail(error){
                        // code goes here                       
                    }           
               );

In the next example, customer is set as an object, before being passed to CEQuery. Objects are limited to lists of name value pairs, and only a limited number of types (string, int, double, boolean) can be used.

var customer =  { id: "91",
                  firstName: "Fred",
                  lastName: "Savage"
                }
window.CEQuery('Search', customer, // call continues with two inline functions
                    function onsuccess(result){
                        // code goes here           
                    }
                    function onfail(error){
                        // code goes here                       
                    }           
                );

On the Clarion side, these calls appear in the OnCEQuery method. Before this call the ParseCEParameters method will parse the parameters into a queue for you.  So you can embed code before or after the parent call, and make use of the queue. If you wish to prevent the parsing you can embed code in ParseCEParameters, before the parent call, and do a RETURN before the parent call.

The parameter queue consists of 5 fields;

CEParametersQueueType  Queue,Type
Position                 Long
SubPosition              Long
Type                     Long
Name                     String(255)
Value                    &StringTheory
                       End

The POSITION field contains the parameter number. If the parameter is a JavaScript Object then the SUBPOSITION acts as an index into the queue, however you should note that fields inside JavaScript objects will arrive in alphabetical order, not the order they are declared in the JavaScript.

The TYPE is one of Cef:String, Cef:Long, Cef:Real, Cef:Bool.

If the parameter came from inside an object, then the name of the parameter is in the NAME field.

The value of the parameter is in the VALUE field which is in a StringTheory object so it can be of variable length.

Example

In this example, code is added to the OnCEQuery method, to list all the parameters, and send them to DebugView.

!----------------------------------------------------
CEF1.OnCEQuery   PROCEDURE (CEF_EA_CEQueryEventArgsClass p_Args)
ReturnValue   long
x  long
  CODE
  self.trace('Number of Parameters: ' & records(self.parameters))
  loop x = 1 to records(self.parameters)
    get(self.parameters,x)
    self.trace('[' & self.parameters.position & '][' & self.parameters.subposition & '][' & self.parameters.type & '][' & clip(self.parameters.name) & ']' & self.parameters.value.GetValue())
  end
  return cef:ok

Using the above code a JavaScript function can be written to send any number of parameters to the Clarion code. Equally useful though is the ability of the clarion code to return one or more responses to the JavaScript. These responses could go to one of two functions, either the onsuccess or onfail functions. The JavaScript does not need to include either of these in the call, and it can also choose to include just one instead of both.

The Clarion side consists of two parts, still included inside the OnCEQuery method. In the first part the reply will be constructed, and then the method return one of cef:ok or cef:notok. If cef:ok is used, and the caller had an onsuccess function, then this will be called with the return values. If the return value is cef:notok and the caller had an onfail function then that will be called.

Aside: Unlike Clarion, JavaScript functions do not need to be prototyped. Any function can accept any number of parameters. Here is an example of a JavaScript function interrogating the parameters list;

function onsuccess(){
    console.log('OnSuccess - number of parameters = ' + arguments.length)
    for(var d = 0; d < arguments.length; d++){
        console.log('OnSuccess parameter: ' + d + ' == ' + arguments[d])
    }
}

Return "parameters", or return "values" (whatever you prefer to call them) are added using the AddReturn method. This method can take a value and (optionally) a type. The type is one of one of Cef:String, Cef:Long, Cef:Real, Cef:Real , Cef:Bool. If it is omitted it is assumed to be a string. For example;

self.addReturn('hello',Cef:String)
self.addReturn('world')
self.addReturn(123,Cef:Long)
self.addReturn(99.999,Cef:Real)

It also supports passing in a Queue, or a Group. (No type is needed in this case.) For example;

self.AddReturn(SomeQueue)
self.AddReturn(SomeGroup)

Once the return values have all been added to the reply then do the appropriate return, either cef:ok or cef:notok.


Common Techniques

Loading Something into the Control

There are a number of methods you can use to load a document, or page into the control. Which one you call will depend on the nature of what you are loading;
Method Description
Load This method takes a URL, and instructs the control to load from that URL. Any URL which regular Chrome accepts should be fine here, including http://whatever, https://whatever and file://c:\temp\whatever
LoadFromBlob This takes the contents of the blob (presumably HTML text) and displays it in the control.
LoadFromDisk This takes the name of a file on the disk. You can also specify the location of this file, or load it from the program directory, or load it from the current path.
LoadFromString This takes the contents of a String (presumably HTML text) and displays in in the control.
Example

CEF.Load('https://www.capesoft.com')
CEF.LoadFromBlob(Products.Description)
CEF.LoadFromDisk('ckeditor4basic/ckeditor4.htm',CEF:ProgramPath)
CEF:LoadFromString(Customer.Address)

Binding a String or Blob to a Control

"Binding" a String or Blob field to a control means that you can update the control, when the field changes, simply by posting an event Event:CEFUpdate. An alternative to posting the event is to call the UpdateHTML method.

The string can be encoded in either ANSI (with a code page), UTF-8 or UTF-16. See String Encoding for more background information on encodings.

Example

CEF.BindSource(Products.Description)
Post(Event:CEFUpdate)

Retrieving the Contents of the HTML Page

Retrieving the contents of the page is Asynchronous. In other words you call one method (GetHTMLSource) to get the contents, but the contents have not arrived by the time the next line of code runs. When the contents arrive they will arrive in the Done method.

Example

command Long
str     StringTheory

Call the following from anywhere

command = CEF.GetHtmlSource()

Then in the Done method

CEF1.Done PROCEDURE (CEF_EA_VisitEventArgsClass p_Args)
  code
  if p_Args.GetCallbackID() = command
    p_Args.GetBuffer(str) ! the result is now in str
  End

Navigation

The most common browser navigation functions are provided by the Back, Forward, Stop, Reload methods.

Example

CEF.Back()

Printing

The PrintPage method allows the control to print the current contents of the control. This prints the control that is on the window. Printing in a report is not possible.

Example

CEF.PrintPage()

Print to PDF

Related to the Print method is the PrintPDF method. This method allws you to print directly to a PDF file. The PrintPDF method takes some parameters, including the filename - if the passed in filename is blank then the FileDialog window will automatically open and ask the user for a filename.

Resizing

If the control is resized then the Resize method needs to be called. This method is automatically called on Event:Sized, so it should work smoothly with Resizing Templates. If you adjust the size of the control manually, you will also need to manually call this method.

Example

SetPosition(?CefControl,x,y,w,h)
CEF.Resize()

Hide and Unhide

The Hide and Unhide methods allow you to hide and unhide the control.

Example

CEF.Hide()
Cef.Unhide()

Prevent Navigation to a URL

Before the HTML Control navigates to a page (entered in the address control, or by clicking on a link on an existing page) the OnBeforeBrowse method is called. In this method it is possible to intercept the request, and prevent it from navigating to the new URL. For example;

CEF1.OnBeforeBrowse PROCEDURE (CEF_EA_BeforeBrowseEventArgsClass p_Args)
ReturnValue LONG
str StringTheory
  CODE
  p_Args.Request.Get_Url(str)
  If str.Instring('google',,,,true)
    Return cef:stop ! prevent going to any url containing the word "google".
  End
  Return cef:go

Redirect Navigation to a Different URL

Extending the idea of preventing navigation (as described above), it's possible to redirect to a different URL simply by doing a call to LOAD. For example;

CEF1.OnBeforeBrowse PROCEDURE (CEF_EA_BeforeBrowseEventArgsClass p_Args)
ReturnValue LONG
str StringTheory
  CODE
  p_Args.Request.Get_Url(str)
  If str.Instring('google',,,,true)
    self.load('https://www.capesoft.com') ! redirect any url with "google" to capesoft.
    Return cef:stop
  End
  Return cef:go

Inspecting Request Data

Before making a request to a server, the browser will call the OnBeforeResouceLoad method. This allows you to inspect the resource (URL and Data), and, if you like, to prevent the request from completing.

For Example - Logging all requests to a queue;

RequestsQueue   QUEUE,PRE(rq) 
Method            STRING(10) 
RequestURL        STRING(255) 
RequestHeaders    STRING(16000) 
RequestData       STRING(32000) 
                END 

CEF1.OnBeforeResourceLoad PROCEDURE (CEF_EA_BeforeResourceLoadEventArgsClass p_Args)
Request   &CEF_RequestClass
Method    StringTheory
Url       StringTheory
Headers   StringTheory
PostData  StringTheory
CODE
  Request &= p_Args.GetRequest()
  If not Request &= Null
    Request.get_method(Method)
    rq:Method = Method.GetValue()

    Request.get_url(Url)
    rq:RequestURL = Url.GetValue()

    Request.get_headers(Headers)
    rq:RequestHeaders = Headers.GetValue()

    Request.get_post_data(PostData)
    rq:RequestData = PostData.GetValue()
  End
  Add(RequestsQueue,1)

If you wish to prevent a resource from being requested from the server then you can abort the request by calling (before the parent call)

  p_Args.ContinueRequest(false) ! this will prevent the request from executing
  Return ! The parent call will allow the request so if you want to cancel,
         ! you'll have to prevent the parent call from being executed.

Click an Element on the Page

You may encounter a situation where the user is browsing a page, and you want to click on an element in the page on their behalf. This is possible using the Click method.

The Click method takes one, or possibly two parameters. The first parameter is the selector and the second is the index. To help locate the correct item(s) on the page a Selector is used. For more information on Selector syntax see Selectors. For example

CEF1.Click('#FieldId')

CEF1.Click('[name="ViewCart"]')

CEF1.Click('.nt-locate-button')

Set the value of an Element on the Page

The SetValue method takes two, or possibly three parameters. The first parameter is the selector (and possibly the index) and the value. To help locate the correct item(s) on the page a Selector is used. For more information on Selector syntax see Selectors.

Example

CEF1.SetValue('#locator1productssearchlist','chrome')

The SetValue method can also take encoding, and codepage properties if the text being passed is not encoded as ASCII, or is not using the ASCII code page. For example;

CEF.SetValue('#name','Eva Perón',st:EncodeAnsi,st:CP_Windows_1252)

On plain HTML pages just setting the value of the element is sufficient. However on more modern pages there is often JavaScript attached to one, or more, events that can be triggered by the control. In these cases it is not enough to set the value, you must also trigger the events that the page is waiting for. The two most common events that are typically watched for are change and blur. 

CEF1.PostEvent('#name','change')

Send an Event to an Element on the Page

The PostEvent method allows you to post an event to a field on the page. This method allows any JavaScript event to be sent to any elements on the page.

CEF1.PostEvent('#name','change')

Drag and Drop onto the Control

The control has the ability to receive Drag And Drop events from the windows File Explorer. In other words users can simply drag a file from any Windows Explorer window, and drop the file in the Chrome Explorer control. While this is a very cool effect it could lead to possible security problems if you are using the control in a way where general navigation is not expected. So, as from build 1.14, this feature defaults to off.

This feature can be turned on, for a specific control, by turning on the option on the Local Extension template for the control.

Right-Click Popup Menu

The control will (by default) offer you the normal browse right-click menu when you click on a page.

There are however two methods which allow you to control whether the menu appears, and what it does. The first important method is the OnBeforeContextMenu method. This is called when the user right-clicks on the control, but before the popup menu is displayed. Making a call to p_Args.PreventContextMenu(true) at this point prevents the browser popup menu from appearing. (You can of course also include other, regular Clarion code here, including the POPUP command, to insert your own popup at this point.

A template option has been added to the control template so that enabling, or suppressing the menu, is available as a checkbox on the template. The option is on by default.

Hint: If you forget to distribute the Locales folder, then the default popup menu will appear, but all the entries will be blank.

Keyboard Navigation

Navigating around the program window, using the keyboard, can become tricky because both the Clarion code, and the Chromium code will see the navigation, and process the keystroke. Typically the control "with the focus" gets the keys. However in a specific case it's not clear which control has the focus.

The case in question is when you have a clarion control (such as a Browse control) and you are updating the Chromium control when the list selection changes. In this situation a record is selected (so the list has the focus) but then (automatically) the Chromium control updates, which then transfers focus to the control, away from the list. So pressing say the DownKey results in that key going to the Chromium control, not the list control.

A similar effect occurs when the user presses Tab. Tabbing into the Chromium control then "traps" the tab order inside there, and you can't Tab (or shift tab) back to the Clarion controls.

A third case where this keyboard trapping is evident is in the use of the Esc key. Typically Clarion windows will close when Esc is pressed, but the Chromium control sees this keystroke first, and "swallows" it.
In all three cases template options exist to let you override this behaviour. You can se the Esc key to close the window, to allow Tab keys to step between controls as normal, and to allow navigation keys (up,down, pageup, pagedown, home, end) to be passed to the "most recent accepted Clarion control" rather than be swallowed by the Chromium control. (However then those keys have no effect in the Chromium control).

Keyboard Characters

It may be desirable to prevent certain characters from being type-able into the browser window. For example suppressing the Ctrl-C character (along with suppressing the popup menu as described above) assists in preventing data from the page being copied off the page. This can be useful in some circumstances (although of course a simple screen-shot, or photo of the screen, would still work.)

When a key on the keyboard is pressed there are three physical effects, keydown, character generated and keyup.

So, all keystrokes sent to the browser pass through the OnPreKeyEvent and OnKeyEvent methods multiple times. Returning CEF:SuppressKey from these methods (if done soon enough) suppresses the keystroke, returning CEF:ProcessKey accepts it. Each call to OnPreKeyEvent and OnKeyEvent is for a different part of the process, and you can determine which part you are in by calling p_Args.GetType(). This returns one of Cef:KeyDown, CEF:KeyUp or Cef:KeyChar.

The key itself is obtainable via either p_Args.Keycode() and p_Args.KeyState() (both of which conform to using Clarion keys as declared in keycodes.clw, and as used in Keycode() and Keystate() - or via p_Args.WindowsKeyCode() and p_Args.WindowsKeyState() which return the windows values (which are different to the Clarion ones.) Windows codes are explained in more detail in CEF_KeyboardHandlerClass.inc .

You can suppress a key by suppressing it early in the process. For example in OnPreKeyEvent;

If p_Args.GetType() = Cef:KeyDown and p_Args.Keycode() = CtrlC
  Return CEF:SuppressKey
End

ProxyServers

In some situations a proxy server is in play, and the user has to authorize with the proxy server in order to make use of the HTML client. A method in the CEF class allows you to pass the username and password to the proxy server.

Template Settings

The Global Extension, Settings tab, has options for the ProxyUser and ProxyPassword settings. These can be fixed values or (more likely) variables which your program allows the user to set somewhere. These settings (if set) cascade to the ChromeExplorer control on all the windows. It can be overriden in the procedure using embed code (after the global setting is used.)

Hand Code

If you do not make use of the template settings, you can also embed the code directly into the GetAuthCredentials method. See Supplying User Authentication to a Page.

PDF Command Line

If you are opening a PDF then you can add parameters to the PDF URL which will control how the PDF viewer behaves. The parameters are separated from the URL using the # character (not the ? character). For example;

file:///C:/temp/b.pdf#toolbar=0&zoom=25

Command Description
page=n Jump to the specific page
toolbar=0/1 Suppress/Include the top PDF toolbar (Rotate, Print, Save-As, Download etc) but not the zoom buttons (bottom right)
view=Fit/FitH/FitV Fir the PDF to either whole-page, height, or width.
zoom=n Set the zoom factor to the specific value

Developer Tools

If you have been developing for the web you are probably used to the Chrome Developer Tools which you see when pressing F12 in the browser. these tools allow you to do view the console, inspect elements in the DOM, monitor network traffic, see cookies and so much more.

In Chrome Explorer these tools are now available using the OpenDeveloperTools method. The tools will open in a separate window.

In order to use developer tools the devtools_resources.pak file must be in the application folder. You do not need to distribute this file unless you intend for your customers to use Developer Tools as well.

The tools can be closed by using the X button on the window itself, or by calling the CloseDeveloperTools method.

Displaying, or Tracking Status Messages

When the mouse moves around a page, and it hovers over a link, then (typically) the cursor changes to a hand. In a web browser, like Chrome or Edge, a message is also displayed. This alerts the user to the URL under the link, so they can see where they would go if they click on the link. This message is known as a status message.

From ChromeExplorer 2, the HTML Browser control template populates a field called CefStatus on the window. This is automatically populated with the status message. If you don't want to see the status message then you can remove the string control from the window.

Status messages are handled inside the OnStatusMessage method. You can access the message using p_Args.GetStatusMessage(). If you wish to do more things with the message then this is the embed to embed into. Note that when the user moves away from the link, the method is also called, and the GetStatusMessage method returns a blank string.

Supplying User Authentication to a Page

If a page requires Basic, or Digest authentication, and you have the credentials in your program already, then you can supply them along with the request.
This is done in the GetAuthCredentials method, BEFORE the parent call by calling self.SetCredentials. As in;

CEF1.GetAuthCredentials   PROCEDURE (CEF_EA_GetAuthCredentialsEventArgsClass p_Args)
ReturnValue   long
  CODE
  self.SetCredentials('CE','iscool')   
  ReturnValue = PARENT.GetAuthCredentials (p_Args)

The GetAuthCredentials method is only called when a page has set the HTTP header. For example;

WWW-Authenticate: Basic realm="Mordor"

This header tells the browser that a specific form of authentication is required. You can read more about the header at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate - although that is not important. From the client perspective, if the header exists then the GetAuthCredentials method is called.

If you have the credentials, then you can simply supply them, as in the above example.

If you don't call SetCredentials, then a window will appear asking the user for their login and password. The source for this window is in CEF_Class.Clw, in the GetCredentialsWindow method.

If you do not wish to see this internal window, you can create your own login window, and present it to the user BEFORE the parent call. For example;

CEF1.GetAuthCredentials   PROCEDURE (CEF_EA_GetAuthCredentialsEventArgsClass p_Args)
ReturnValue   long
stUser        StringTheory
stPwd         StringTheory

  CODE
  Login(stUser, stPwd)
  If GlobalResponse = RequestCompleted
    self.SetCredentials(stUser, stPwd)
  Else  
    Return false !user cancelled, stop navigation
  End 
  ReturnValue = PARENT.GetAuthCredentials (p_Args)
  Return ReturnValue

In the above example the Login procedure is a simple window in the application that fills out the contents of the two StringTheory parameters.

The demo example has an example of such a window. This approach is useful in that you can make the window look like the rest of your app, and window-tools like AnyFont and AnyText would apply to that window.

If the credentials are successful then they will be "remembered" by the browser. If the browser is in incognito mode (see Cache Path) then it will remember as long as the Exe is open. If it has a cache folder set, then it will remember "forever".

Custom Protocols and Resources

The most common uses of the Browser are for either displaying document or browsing the web. Documents can be laoded from the local disk, or from Ram.

However there is a complication when a collection of files, or "sources" are needed. Chromium (as all browsers do) have a one-source policy. If you fetch a resource from the internet (a page, a PNG, a PDF, whatever) then those resouces cannot access your local disk. Equally if you load a HTML file from memory, then you can't load a resource into that (say an image) from the disk. If you do load a file from the disk, then there are even more limitations, for example XML files can't load XSL files, and so on.

This mixed-source limitation basically falls on the Protocol part of the URL you are using. For example HTTP:// reads from the internet, FILE:// reads from the disk and so on. Chrome Explorer overcomes this limitation by implementing something called Custom Resources.

Custom Protocols

Custom Resources are accessed by using a Custom Protocol. So instead of prefixing the URL with HTTP:// or FILE:// you can access it using a custom protocol name. This name could be anything you like; the default is CELOCAL, but this is an equate you can override. If you do override it you need to recompile ChromeExplorerProcess.Exe.

In addition to CELOCAL Chrome Explorer also implements two other custom protocols for you, named MEM:// and DISK://
MEM://
The MEM protocol behaves just as you might expect. The name of the required resource is passed into a method. You parse that name, make some decisions, and populate a StringTheory object with the Content. You also set the MimeType (so the browser knows how to display the content.)
This Protocol is completely flexible, and under your control. You get the names, and process the contents.
DISK://
The DISK protocol is similar to the MEM protocol, but does some work for you to pre-load the file off the disk. It will pass you the filename requested, and the content of that file, and then you will need to sign-off that it's ok to serve that file. Some care should be taken here to make sure that only suitable files, from suitable locations are served. You can alter the filename, change the content, and so on. This protocol is "less safe" than using the MEM:// or custom protocol, because it includes code to read the disk.
CELOCAL://
The third protocol is the custom one, which you can name whatever you like. The default value is CELOCAL, but you can change this by editing an equate in CEF_BaseClass.Inc. If you do change it you will need to recompile ChromeExplorerProcess.Exe as well.  This functions exactly the same as the MEM:// protocol, but allows you to use a different name to MEM. This name applies across the whole application, and can not be set on a per-object basis.

Custom Resources

When a custom protocol is encountered, then Chrome Explorer calls an associated GetCustomResource method. You add embed code to this method to populate the resource (ie the string of data) that the browser is asking for.

There are three methods provided to do this; GetCustomResourceDisk, GetCustomResourceMem and GetCustomResource.

It is worth repeating that you HAVE to add code to these methods for these protocols to work. By default they will not serve anything, so existing browse controls are not compromised in any way.
GetCustomResourceMem
This method takes in two parameters, p_URL and p_Request as input, and then you need to populate two StringTheory objects, p_Content and p_MimeType as output. In addition to this output, if you want to serve the resource then you must

RETURN TRUE

from the method itself. If you

RETURN FALSE

then the resource will not be returned to the browser engine, and nothing will be displayed.

How you get from the p_URL to the output is up to you. You might generate the p_Content from a formula. You might read a BLOB from the database. You might load a file off the disk. You may make an outside call to a web server, how you get there doesn't matter as long as you get there.

In addition to the p_Content you also need to set the p_MimeType. This is a string which the browser uses to understand what the content is, and from this decides how to display it. An HTML document, for example, is displayed differently to a PNG or a PDF. Chrome Explorer makes setting the correct content type easier by providing a method called GetContentType. This method takes a string parameter (either a file name, or common file extension) and returns the mimeType for that extension. So, for example, if you are generating XML, then you could call;

p_MimeType.SetValue(self.GetContentType('xml'))
GetCustomResource
GetCustomResource behaves exactly the same as GetCustomResourceMem, but is called when the user uses the custom protocol name (CELOCAL or whatever you change it to) instead of MEM://
GetCustomResourceDisk
GetCustomResourceDisk ultimately behaves the same as GetCustomResourceMem, however it assumes that the resource that will be loaded is a file from the disk, and so goes ahead and does some work for you. It passes in the disk file name as a parameter, and preloads that file into the p_Content object, and also sets the p_MimeType for you.

You will still need to embed code in the GetCustomResourceDisk method though. You should embed code to inspect the p_Filename parameter, perhaps limiting your filename support to specific folders or whatever. Once you are happy with the content in the p_Content parameter, then you must

RETURN TRUE

If you

RETURN FALSE

then the content is suppressed.

Hint

StringTheory has methods for breaking a URL apart into it's component pieces. See https://www.capesoft.com/docs/StringTheory3/StringTheory.htm#stUrlHostOnly and associated methods.



Downloads

Downloads on a Chrome Explorer Control are set to OFF by default. To allow downloads set the Allow Downloads checkbox on the control actions (Downloads tab.)

You can specify the download location, or you can allow the user to choose the location. This is also done via the template settings.

Methods are supplied which allow you to oversee the files being downloaded, and to take action after the file has been downloaded; StartDownload, OnBeforeDownload, OnDownloadUpdated, OnDownloadComplete and onDownloadCancel.

The Control template now has a Progress Control which automatically unhides, and progresses, as a download occurs.

POST, GET, PUT, DELETE

This section discusses making an arbitrary request from the browser control. It is not about intercepting requests. For details on that see....

Using Chrome Explorer it is possible to make an explicit request from the control, even if the page currently being viewed does not specifically contain a button, or link to make this request. There are four methods, which correspond to the four most common HTTP request verbs; Post, Get, Put and Delete .

The result of the request will appear in the control on the window.

NOTE: Although the page being viewed does not need to include a link to the server you wish to talk to, a valid page MUST be loaded into the control before this request can be made. Setting the URL to about:blank will load a valid (blank) page if you are not currently on a page..

Note: Requests are asynchronous . So each request needs to wait until the response is received before another request can be made. If requests are simply made after each other, then only the final request will actually execute.

A request consists of up to 5 parts;
 

Form Field Data

This data can be set using the SetFieldValue method. Call this method multiple times, once for each data field you wish to send. You do not need to encode the name, or the value, that will be done for you by the class.

For example

Cef1.SetFieldValue('FromDate','2020/06/1')
Cef1.SetFieldValue('ProductName','Chrome Explorer')

If the request is a POST or PUT then this data will automatically be encoded and added to the Post Data section of the request. If the request is a GET or DELETE then the data will automatically be encoded and added to the URL section of the request.

This approach works for data that is either sent form-encoded, or multi-part-form-encoded. In some cases the data being sent is a single XML or JSON blob. If that is the case then you can pass the data to the request method directly, you would not call the SetFieldValue method.

Specific Headers

You can set specific headers using the SetHeader method.

For example;

Cef1.SetHeader('x-chrome-explorer','amazing')

If you are sending XML or JSON data then it is very common, and in most cases required, to set the Accept header and the Content-Type header. the Accept header if for the format you wish to get back, the content-type header describes the format of the data being sent.

Cef1.SetHeader('Accept','application/xml')
Cef1.SetHeader('Content-Type','application/xml')

Cookies

If you need to you can set specific cookies to go with the request using the SetCookie method.

For example;

Cef1.SetCookie('state','Locked')
Cef1.SetCookie('color','Blue')

URL

The URL is the address of the server, and the endpoint on the server, that you want to send the request to. For example;
https://www.capesoft.com/Api?GetVersions

Method

The Method (sometimes called the HTTP VERB) can give the server additional information about what you want to do. The most common methods are POST and GET, but some API systems also make use of PUT and DELETE. Chrome Explorer has methods to match all these verbs. 

The methods can be called with an additional data parameter. This is used when the data cannot be set using the SetFieldValue method.

Examples

A simple call to the CapeSoft API, getting back XML

cef1.SetHeader('accept','application/xml')
cef1.SetFieldValue('fromdate','2020/06/01')
cef1.SetFieldValue('productname','Chrome Explorer')
cef1.Post('https://www.capesoft.com/GetVersions')

A call to the CapeSoft API using JSON, getting back JSON

str  StringTheory

net.SetHeader('Content-Type','application/json')
net.SetHeader('Accept','application/json')
str.SetValue('{{"fromdate" : "2020/06/01", "productname" : "Chrome Explorer" }')
net.Post('https://www.capesoft.com/GetVersions',str)


HTML Editor

The HTML Editor functionality makes use of the CEF_EditorClass, and the ChromeEditControl Control Template.

The CKEditor 4 HTML editor (in either Basic, Standard, Full or Custom mode) and the ACE Code editor are supported. You can create a custom version of the editor, using your own choice of features and plugins at https://ckeditor.com/cke4/builder .

Unless noted in the documentation below, the instructions for the editors are the same.

On Form Procedure

The Editor control can be placed on a Form procedure. A Use Field can then be assigned to the control (right-click on the control, choose Actions.) This field will then be used to populate the control when it opens, and the contents of the control will be moved back to the form when it is saved.

Because the retrieval of the text value from the control is asynchronous this means this code happens during  Event:Completed. If you wish to examine, or manipulate the text before it is saved, be sure to do this in the TakeCompleted method, not in the OK button embed code.

An example of using an HTML Editor on a Form is the UpdateProducts procedure in the example application.

On Window Procedure

On a window procedure you will need to load, and save, the control yourself.

If you don't already have a field to hold the contents of the control, then create a local object, of type StringTheory, to hold the HTML.

str StringTheory

Use this (or another existing field) on the template settings as the USE Field. Or manually bind the control to this field using BindSource;

CEF1.BindSource(str)

If you use a StringTheory object, then the encoding and codepage properties of that object will be used. Other supported types for storing the value are STRING, CSTRING and BLOB. If one of these field types are used, then you need to specify the string encoding (and code page) to be used.

CEF1.BindSource(product:descripton,st:EncodeANSI,st:CP_Windows_1252)

If omitted the encoding defaults to st:EncodeANSI and the code page is auto-detected based on your program system{font:charset}.

If necessary, prime this field with the HTML. For example

str.LoadFile('somefile.htm')

 You can update the CEF control with this text at any point by calling UpdateHTML.

CEF1.UpdateHTML()

or by posting an Event:CefUpdate to the control.

Moving the contents of the edited text back into the source variable is asynchronous. It can be triggered by either SaveFile or UpdateFromHTML.

CEF1.SaveFile(FileName)
or
CEF1.UpdateFromHTML()

In both cases when the operation completes the UpdateSource method will be called. At that point (after the parent call) you can save the field to a table, or close the window, or whatever. A more compact approach is;

CEF1.SaveFile(FileName,cef:Closewindow)

This triggers a save, and then when the save is completed (in UpdateSource) closes the window.

An example of using an HTML Editor on a window is the HTMLFileEditor procedure in the example application.

Downloading a Custom Version (CK Editor)

  1. Open a browser and go to https://ckeditor.com/ckeditor-4/download/
  2. Select the Customize option, and click on the Online Builder button.
  3. Select the starting point from one of the three presets. You can also upload the build-config.js file to the builder, and start with one of the existing Chrome Explorer editor configurations.
  4. Move items from the "Available Plugins" list (on the right) to the Selected Plugins list (on the left) using the < button.
  5. Select your preferred skin from the Available Skins list
  6. Select the languages you want to include from the "languages to choose" list, and move them to the Your Editors Language list using the < button.
  7. Read and agree to the Terms of Use
  8. Select the "optimized" version.
  9. Click the "Download CKEditor 4.xx" button
  10. Once the download has completed, open the ZIP file that was downloaded. Copy the ckeditor folder to your application directory.
  11. Once it is in your application directory rename it to something else, like ckeditor4Custom. It should be a sibling of the ckeditor4basic, ckeditor4standard and ckeditor4full folders.
  12. Copy CKEditor4.htm from one of those sibling directories to your editor4Custom folder.

Assigning a Custom Version (CK Editor)

  1. Open your APP in the Clarion IDE and go to the window with the HTML Editor Control
  2. Go to the Extensions List, and open the Properties for the HTML Editor Control.
  3. In the Use Editor option select Custom
  4. In the Editor HTML file option put 'ckeditor4Custom\CkEditor4.Htm' where ckeditor4Custom is the name of your custom folder.

Changing the Editor Language (CKEditor)

This assumes you have downloaded a custom version of the editor, with support for additional languages, as per Downloading a Custom Version above. In this example the Dutch language (nl) has been downloaded.
  1. Open ckeditor4Custom\config.js in a text editor
  2. At the bottom of the file, inside the closing } add either or both of the following lines;
    config.language = 'nl';
    config.defaultLanguage = 'nl';

    where nl is the language you are changing to
Tip: You can determine the available language codes by looking in the ckeditor4Custom\lang folder

Tip: The default language setting is only used if the browser-language-setting is detected, but the corresponding language file does not exist.

Tip: The language setting sets the language regardless of the users' computer or browser language settings.

Manipulating the Text in the Control

Several methods allow you to manipulate the text in the control.

Trapping Errors after calling SaveFile

The SaveFile method is asynchronous  - the work will be done in the UpdateSource method. This method takes a StringTheory object, called p_NewValue, as a parameter. In order to check the result of the save (ie if there was an error) you can check in p_NewValue.WinErrorCode and p_NewValue.LastError properties AFTER the PARENT call.

Setting a Theme (ACE Editor)

You can change the theme at runtime using the SetTheme method. The example program (HTMLFileEditor procedure) contains sample embed code for populating a queue with a list of themes, and allowing the user to select their own preferred theme. The template also offers you the option to set a default theme for the control.

This should only be done once the editor has finished loading (ie in the OnLoaded method, or later.)

cef1.SetTheme('dracula')

Setting a Language (ACE Editor)

In ACE terminology the programming language is set by setting the Mode. The editor class helpfully includes two methods, SetLanguage and SetMode, which do the same thing. By setting the language the editor can do a better job with color-syntaxing, and also in some cases error detection.

This should only be done once the editor has finished loading (ie in the OnLoaded method, or later.)

cef1.SetMode('ascii')

Setting an Option (ACE Editor)

In addition to the theme, and mode, there are many (many) other options you can set. The SetOption method allows you to set any of them. This method takes two parameters, one to specify the option, and the other the value. tter job with color-syntaxing, and also in some cases error detection.

This should only be done once the editor has finished loading (ie in the OnLoaded method, or later.)

cef1.SetOption('wrap',false)
cef1.SetOption('showLineNumbers',true)

 Examples

Examples are located in the location you chose for them during the install. This section lists the shipping examples, and what their purpose is.
Example Description
\examples\ChromeExplorer\ABC The main demo app, using ABC templates, demonstrating most of the common features.
\examples\ChromeExplorer\Legacy The main demo app, using Clarion (Legacy) templates, demonstrating most of the common features.
\examples\ChromeExplorer\NetOAuth\ABC ABC version of an example (from NetTalk) of using OAuth Logins using the ChromeExplorer Control instead of the fileExplorer Control. The OauthLogin procedure is affected.
\examples\ChromeExplorer\NetOAuth\Legacy The Legacy version of an example (from NetTalk) of using OAuth Logins using the ChromeExplorer Control instead of the fileExplorer Control. The OauthLogin procedure is affected.
\examples\ChromeExplorer\MultiDLL\ABC\ ABC version of multi-dll example. Classes exported from Data DLL, Functions and Exe apps as well.
\examples\ChromeExplorer\MultiDLL\Legacy\ Legacy version of multi-dll example. Classes exported from Data DLL, Functions and Exe apps as well.

Hand-Coding

Using the various Extension and Control Templates is the easiest way to use Chrome Explorer in a program. However it is also possible to use Chrome Explorer on a hand-coded window in a hand-coded application.

Selectors

when interacting (clicking, setting values etc) with a loaded page you need to be able to identify the item that you want to interact with. For example, if you wish to click on a submit button, then you need a way to identify the button you wish to click. This is done using Selectors.

Selectors allow you to identify one (or more) items on the page that meet your specification - ideally you can narrow your specification to a single item, and then interact with that. If you can't reduce the list to a single item, then you can use an Index parameter to indicate which item in the list is being acted on. The first item in the list has the index 0, the next index 1 and so on.

All selectors are Case Sensitive.

Selector Example Example Description
.class .name selects all elements that have, as one of their CSS classes, the class called name
.class1.class2 .name1.name2 Selects all elements that have both name1 and name2 in their CSS class list
.class1 .class2 .name1 .name2 selects all elements with a CSS class name2, which is also a descendant of an element with a CSS class name2
#id #savebutton Selects the element where the ID is set to savebutton
* * Selects everything on the page. (Everything!)
element a Selects all the <a> elements on the page
element.class a.green Selects all the <a> elements that also have a CSS class green in their CSS list.
element , element div, span Selects all div elements and all span elements
element > element div span Selects all span elements that are inside div elements
element + element div + span Selects all span elements that are immediately after a div element
element1~element2 span ~ div Selects every div element that is preceded by a span element
[attribute] [target] Selects all elements that have an attribute called target
[attribute="value"] [target="_blank"] selects all elements that have an attribute called target, and where that attribute is set to _blank
[attribute~="value"] [title~="flower"] selects all elements that have an attribute called title, and where that attribute contains the word flower in a space separated list. (ie not the letters flower, but the distinct word flower separated by spaces from the other words)
[attribute|="value"] lang|="en" Finds elements that start a dash-separated list. So in this case, find all elements that have an attribute called lang, where the value starts with en-
[attribute^="value"] a[href^="https"] selects all <a> elements that have an attribute called href, and where that attribute starts with  https
[attribute$="value"] a[href$=".pdf"] selects all <a> elements that have an attribute called href, and where that attribute ends with .pdf
[attribute*="value"] a[href*="cef"] selects all <a> elements that have an attribute called href, and where that attribute contains the substring cef
This is only a partial list of supported selectors. For more information see https://www.w3schools.com/cssref/css_selectors.asp

Template Reference

Templates

Activate ChromeExplorer Global Extension

General Tab

Disable All ChromeExplorer Features
If this option is on then all the ChromeExplorer template code will not be generated. This does not affect hand-code you may have coded into embed points. (So that code may then generate compile errors as the underlying objects no longer exist.)

Options Tab

No options here yet.

Settings Tab

Cache Path
See Cache Path
User Agent
See User Agent
Locale
See Locale
Log File Path and Name
See Log File 
Log Severity
See Log Severity
Ignore Certificate Errors
See Ignore Certificate Errors
Proxy User and Password
See Proxy Servers

Copy Folders Tab

This tab controls the automatic copying of resources in the \Clarion\Accessory\Bin folder to your application folder.
Copy Locales Folder
If this is on the the Locales folder will be copied. If this is missing Chrome Explorer will assume the local is US English.
Copy SwiftShader Folder
If this is on the the Swiftshader folder will be copied. If this is missing WebGL will not function in software-only mode when the GPU is not available or disabled.
Copy HTML Editor Folders
If this is off then no Editor HTML folders will be copied. If you are not using the HTML Editor at all, then you can tick this off.
From: Clarion Root Folder
By default the files will be copied from the \Clarion\Accessory\Bin folder, where Clarion is the root folder for the current Clarion environment. If you wish to override this source location, then enter a fixed path here.
To: Exe Folder
By default the files will be copied to the App folder. If your Exe is running from a different folder you can enter that folder here.

Multi-DLL Tab

This is part of a Multi-DLL program
Tick this on if this app (DLL or EXE) is part of a multi-app system.
Export Classes from this DLL
Tick this on if this is the app that will export the ChromeExplorer classes to the other apps. (Typically this is on in the Data DLL). It must only be on for one app in the system.
Templates

ChromeControl Control Template

Options Tab

Disable This Template
Tick this on to disable the template on the window. The controls themselves will remain on the window, but the code underneath them will not be generated.
Accept ENTER on URL to trigger Refresh
If this option is on, then pressing enter while the URL has the focus will cause an event:accepted on the URL field. (ie triggering a HTML Control refresh).
Enable Drag and Drop
If this option is on then the user can drag a file from Windows Explorer into the Chrome Explorer control. If the file type is supported by Chromium then it will be displayed to the user. This includes HTML, PDF, various image formats and various text formats.
Enable Right-Click Menu
If this option is on the the default Chromium right-click popup menu will be displayed when the user right-clicks on the control. If this option is off then the right click menu is suppressed. You can replace the right-click menu with your own code - for more on that see Right-Click Popup Menu.

Load from Web or File

Choose one of these options if you are displaying a web page, or file, that is either on the web, or a file on the disk.
Initial URL
Use this if the initial location is a HTTP:// or HTTPS:// address.
Initial Disk File
Use this if the initial location is a file on the disk.
Update URL as User Navigates
If this option is on then the Address entry field will be updated with the current URL as the user navigates from page to page. If this is off then the initial value in the URL will remain. The user can type in a new value to navigate to a new page.

OR Load From Database

Choose one of these options if you are loading HTML from the database.
Load URL From Field
Select a field here, where the field contains a URL (ie a value starting with https:// or whatever). The control will go to the URL specified in this field.
Load HTML From Field
Select a field here, where the field contains actual HTML that should be displayed. STRING, CSTRING and BLOB fields are supported.
Update Control on Browse NewSelection
If there is a browse on the window, and the ChromeControl should update when values in the browse change, (aka "Hot Fields"), then select this option to on.
Browse Object Name
If the above checkbox is on, then enter the Browse Object Name here. (usually BRW1 or something like that.)

Downloads Tab

Allow Downloads
This option must be on for downloads to be supported on the control.
Download To Temp Location
If this option is checked then the downloads will be saved in a temporary location determined by the control. If none of these three options are ticked, then this is the default.
Prompt User For Location
When a file is downloaded, the user will be prompted for where the file should be stored, and under what name. If the user cancels this prompt then the download will be cancelled.
Download Folder
A specific folder to download the file to.

Keyboard Tab

Esc Closes Window
If this is on, and the user presses ESC then the Clarion window closes.
If this is off then the ESC key will be processed by the Chrome control.
No Keyboard Nav in CE Control
If this is set, then keyboard navigation keys (up, down, pageup, pagedown, home, end) will trigger scroll events on the most recent Clarion control. If this is not set then these commands will go to the Chromium control (if it has the focus.) The common use case for this setting is where a Chromium control is being updated by a NewSelection event. This option returns keyboard control to the list control, not to the Chromium control (that has the focus.)
No Tab in CE Control
Once the Chromium control has the focus, Tab and ShiftTab keystrokes will apply inside the control, not outside it. Ticking this option on prevents tab keys from being used inside the Chromium control, and returns them to the Clarion window.
Window KEYs Active
If this is on then the template will automatically look for KEY attributes on controls, and if that key is pressed will post an event:accepted to the control. These Keys will not be passed to the Chrome control.

Insecure Tab

If you wish to allow a control to browse to insecure sites, over the HTTPS protocol, then set the settings on this tab. Choose the settings wisely to limit the insecure browsing to the fewest possible sites.
Ignore Certificate Errors Here
If this is on then this control will allow browsing to insecure sites - as defined below.
Allow All LAN Addresses
If this is on then ALL LAN addresses (based on the URL) will be allowed. Note that DNS entries which resolved to a local LAN IP address do not qualify as LAN Addresses, and would need to be added to the Allowed Domains list below.
LAN addresses are defined as;
  • URL is an IP address that starts with 127.0.0. or 10.  or 192.168. or 172.16. through 172.31.
  • URL ends with the .local TLD
  • URL contains no periods - ie is just a machine name.
Allow Only LAN Addresses
If this is on then ONLY Lan addresses (regardless of the list of domains below) will be allowed. Leaving this option OFF and the Allowed Domains list empty, will allow the user to browse to ANY insecure site over HTTPS. This combination is strongly NOT recommended.
Allowed Domains
If this list is empty then it allows "all domains" (subject to the Allow Only LAN Addresses option above.)

Adding items to this list limits the browsing to only these domains (potentially in addition to All LAN addresses, based on the Allow ALL LAN Addresses option above.)

Domains on this list have to be fully qualified. In other words adding capesoft.com is not sufficient to browse www.capesoft.com if the certificate for www.capesoft.com is invalid.

Class Tab

Object Name
TThe Object name to use for this object. A default will be provided, but a more meaningful name makes the code easier to understand. Especially if there are multiple ChromeExplorer objects on the window.
Class name
The Class to use for this object. The provided default value is usually the correct one to use.
Templates

ChromeControl Navigation Control Template

Options Tab

Disable This Template
Tick this on to disable the template on the window. The controls themselves will remain on the window, but the code underneath them will not be generated.
Print to PDF: FileName
The name to save the contents (as a PDF file) if the PrintPDF button is pressed. If this field contains a blank string ('') then the user will be prompted for a file name at runtime.
Templates

ChromeControl Search Control Template

You can add this control template to an existing ChromeControl template. This adds a search field to the window. The control is set (by default) to be triggered by the Ctrl-F keystroke.

Options Tab

Disable This Template
Tick this on to disable the template on the window. The controls themselves will remain on the window, but the code underneath them will not be generated.
Case Sensitive Search
If this option is turned on then the search field will be case sensitive.
Templates

ChromeEditControl Control Template

Options Tab

Disable This Template
Tick this on to disable the template on the window. The controls themselves will remain on the window, but the code underneath them will not be generated.
Use Editor
Select which editor you wish to use. There are 3 flavors of CKEditor supplied, or you can set the field to Custom to use your own editor.
Editor HTM File
If you select Custom, then select the HTM page (that contains your editor) here.
CK Theme
If the control is using the CK Editor (any version, or custom) then you can select the theme (skin) for the control to use here. The CK Editor is not able to change the skin at runtime, so the skin must be selected before the control opens. (You can override the template setting in the OnLoaded method for the control.)

All the skins are included in the CKEditor folders. You can choose to remove skins that are not being used.
Default ACE Theme
If the control is using the ACE editor, then this sets the default theme for the control. You can override this using the SetTheme method.
Default ACE Language
If the control is using the ACE editor then this sets the default language (mode) for the control. You can override this using the SetLanguage method.
USE Field
If this editor is on a Form, and you want the Editor Control to be primed from a field, and to write the contents back to the field on SAVE, then enter the field here.
USE StringTheory-Object Encoding and CodePage
Tick this on if you are setting the Encoding and code-Page properties of the Use variable yourself AND the Use variable is a Stringtheory object. If you leave this unchecked, then the Encoding and Charset will be set by the settings below.
Field Encoding
Select the encoding that is being used in your variable. The default value is ANSI, other options are UTF-8 and UTF-16. For more on String Encodings see String Encoding.
Field Code Page
If the selected field encoding is ANSI then select a code page to use.
Custom Code Page
If none of the code pages are the one that you want to use, then select Custom, and manually enter a code page value here.

Class Tab

Object Name
The Object name to use for this object. A default will be provided, but a more meaningful name makes the code easier to understand. Especially if there are multiple ChromeExplorer objects on the window.
Class name
The Class to use for this object. The provided default value is usually the correct one to use.

Structure Reference

CEF_PdfPrintSettings

Field Type Description
header_footer_title String(256)
header_footer_url String(2048)
header_footer_enabled BYTE Set to true (1) to print headers and footers or false (0) to not print
selection_only BYTE Set to true (1) for landscape mode or false (0) for portrait mode
page_width
page_height		 LONG Output page size in microns. If either of these values is less than or equal to zero then the default paper size (A4) will be used.
margin_type LONG One of;
PDF_PRINT_MARGIN_DEFAULT , PDF_PRINT_MARGIN_NONE , PDF_PRINT_MARGIN_MINIMUM , PDF_PRINT_MARGIN_CUSTOM 
scale_factor LONG The percentage to scale the PDF by before printing (e.g. 50 is 50%). If this value is less than or equal to zero the default value of 100  will be used.
margin_top
margin_right
margin_bottom
margin_left		 LONG Margins in points. Only used if margin_type is set to PDF_PRINT_MARGIN_CUSTOM.
landscape BYTE Set to true (1) for landscape mode or false (0) for portrait mode.
backgrounds_enabled BYTE Set to true (1) to print background graphics or false (0) to not print background graphics.

Class Reference

Classes

CEF_BaseClass

This class contains functionality used by the other classes. It mostly covers logging, debugging, error trapping and translations.

Derivation

  • CEF_BaseClass (CEF_BaseClass.Inc / CEF_BaseClass.Clw)

Properties

Property Description
LastErrorCode The last error code generated by the class.
LastErrorMessage The last error message generated by the class.
Debug A switch to send the output from the Log method to Debugview or not.

Methods

Method Description
Error Returns the value in the LastErrorMessage property.
ErrorCode Returns the value in the LastErrorCode property.
ErrorTrap This method is called whenever an error occurs.
InterpretError This provides a text meaning to the error number.
Log Optionally sends data to Debugview, based on the Debug property.
SetDebug Set the value of the Debug property.
Start Returns the object to it's virgin state as if it has not yet been used.
Trace Unconditionally sends text to Debugview
Translate A virtual method, containing no code, that allows derived classes to translate any human-readable text.
CEF_BaseClass

Error

Error()

Description

This method returns the value in the LastErrorMessage property.

Return Value

String

Example

s = cef.error()

See Also

ErrorCode,  ErrorTrap, InterpretError

CEF_BaseClass

ErrorCode

ErrorCode()

Description

This method returns the value in the LastErrorCode property.

Return Value

Long.

Example

x = cef.errorcode()


See Also

Error,  ErrorTrap, InterpretError

CEF_BaseClass

ErrorTrap

ErrorTrap (Long p_ErrorCode, String p_Method, String p_Msg)

Description

This method is called whenever an error occurs in the class. The method will format the error message, and pass that to the Log method. Errors are always passed to Debugview, they are not suppressed by the use of the Debug property.

Parameters

Parameter Description
p_ErrorCode The errorcode generated by the class. For a full list of the possible error codes see CEF_BaseClass.Inc.
p_Method The method that called ErrorTrap
p_Msg Any additional information supplied by the calling message.

Return Value

The method returns nothing. The LastErrorCode property is set to the p_ErrorCode parameter. The LastErrorMessage property is set to the formatted version of the error.

See Also

Error,  ErrorCode, InterpretError , Log

CEF_BaseClass

InterpretError

InterpretError (Long p_ErrorCode)

Description

Returns a text description of an error code. The description is passed through the Translate method, so these messages can be translated by derived classes.

Parameters
Parameter Description
p_ErrorCode The error number.


Notes

The OAuthDemo procedure uses this method to save the various tokens. It also displays a message to the user, and closes the login window.

Return Value

The method returns nothing.

See Also

Error,  ErrorCode, ErrorTrap, Log, Translate

CEF_BaseClass

Log

Log (String p_LogText, Long p_Force=false)

Description

This method is called when a login is complete. 

Parameters
Parameter Description
p_LogonText
p_Force If this is set to true then the message is passed to the trace statement. If it is false then it will only be sent to the trace statement if the debug property is true.

Return Value

The method returns nothing.

See Also

ErrorTrap, Trace, SetDebug

CEF_BaseClass

SetDebug

SetDebug (Byte p_Debug)

Description

This method changes the value in the debug proeprty.

Parameters
Parameter Description
p_Debug The new value to put into the debug property.

Return Value

The method returns nothing.

See Also

Log

CEF_BaseClass

Start

Start()

Description

This method returns the object to a virgin state, as if it has never been called or initialized.

Return Value

The method returns nothing.


CEF_BaseClass

Trace

Trace (String p_LogText)

Description

Sends a string to the DebugMessage viewer (DebugView, DebugView++, UltimateDebug and so on.)

Parameters
Parameter Description
p_LogText The string to send to Debugview

Return Value

The method returns nothing.

See Also

Log

CEF_BaseClass

Translate

Translate (String p_Str)

Description

This method is provided as a hook to allow translation tools to translate text generated by the class. By default it returns the same string that is passed in.

Parameters
Parameter Description
p_Str The string to translate.

Return Value

String

Classes

CEF_ProcessClass

This class links the control to the ChromeExplorerProcess exe, and manages the links to these subprocesses. You would not normally call this class directly.

Derivation

  • CEF_ProcessClass  (CEF_ProcessClass.Inc / CEF_ProcessClass.Clw )

Properties

None

Methods

Method Description
GetVersion Returns CEF version information for the LibCef and Chrome libraries.
CEF_ProcessClass

GetVersion

GetVersion ()

Description

This method returns the version number of the CEF library, and CHROME that is being used.   This data can be useful when trying to diagnose a problem that is specific to some specific machines.

Return Value

A string of the form CEF: a.b.c.d CHROME: e.f.g.h

Classes

CEF_GlobalClass

The CEF_Global class is a singleton - a class which only has one object, and is created globally. It manages the code that needs to happen when the program starts up and shuts down.

Derivation

  • CEF_GlobalClass ( CEF_Class.Inc / CEF_Class.Clw )

Properties

Property Description
Initialized Set to true if the object has been initialized (ie Init has been called.)

Methods

Method Description
Init Called when the program starts.
Kill Called when the program ends.


Classes

CEF_Class

Derivation

  • CEF_Class ( CEF_Class.Inc / CEF_Class.Clw )

Properties

Property Description
AuthUser The username to use when interacting with a Proxy server
AuthPassword The password to use when interacting with a Proxy server.
Control The REGION control on the window that acts as a placeholder for the HTML Control.
CurrentURL A reference to a variable in the window, set with BindURL.
CurrentTitle A reference to a variable in the window, set with BindTitle.
Displayed Set to true if the control has been displayed with the current visibility conditions.
DragDropEnabled Set to true if Drag and Drop support has been turned on.
Hidden Set to true if the control has been hidden with the HIDE method. Set to false if the control has been unhidden using the UNHIDE method.
Initialized Set to true if the object has been Initialized (Init has been called)
IsClosing Set to true if the HTML control is in the process of closing down.
ScriptReady Set to true when the JavaScript engine has been initialized. This needs to be true before calls to CallScript can be made.
State A utility property to hold an ID when asynchronous methods are called.

Methods

Method Description
BindSource This ties the content of a field, or blob, to the HTML control. If the field changes then the HTML can be updated by an event Event:CEFUpdate.
BindTitle This ties a String variable to the page title of the current page in the HTML control. If the page changes (ie the user navigates somewhere) then this variable will be automatically updated.
BindURL This ties a String variable to the URL of the current page in the HTML control. If the page changes (ie the user navigates somewhere) then this variable will be automatically updated.
Back Similar to the Back button in a Browser. This causes the HTML control to navigate back to the most recent address. See also Forward.
CallScript Calls JavaScript code that returns a value. See also Script.
Click Click a field on the page.
CloseDeveloperTools
Delete Issues a DELETE request to a server.
DeleteCookie Deletes a cookie added with the SetCookie method.
DeleteFieldValue Deletes a field added with the SetFieldValue method.
DeleteHeader Deletes a header added with the SetHeader method.
Display Force a repaint of the control.
DoClose  
Done Called when GetHTMLSource or GetTextSource completes.


Find Do a Search on the contents of the Chrome Control
FindNext Find the next (or previous) instance of the text.
Forward Similar to the Forward button in a Browser. This causes the HTML control to navigate forward to next address. See also Back.
FreeCookies Empties the Cookies queue
FreeFieldsQueue Empties the Fields queue
FreeHeaders Empties the Headers queue
Get Issues a GET request to a server.
GetBodyHTML Get the contents of the <BODY> tag on the page.
GetContentType Get the Mime type for a specific file name or file extension.
GetCustomResource Allows you to populate a StringThory object, as the result of a URL starting with CELOCAL:\\ (or other custom protocol).
GetCustomResourceDisk Allows you to populate a StringThory object, as the result of a URL starting with DISK:\\
GetCustomResourceMem Allows you to populate a StringThory object, as the result of a URL starting with MEM:\\
GetDiskName This method creates a properly formed file: \\ URL from the name of a file on the disk. The file can have an explicit path, or be set as relative to the program EXE folder. It does not load the file (see also LoadFromDisk).
GetDocumentHTML Get the HTML of the page.
GetElementAttributeValue Get the value of an attribute associated with an ID
GetElementHTML Get the HTML of an Element on the page.
GetElementValue Get the value of an input field on the page.
GetHeadHTML Get the contents of the <HEAD> tag on the page.
GetHTMLSource Returns the HTML contents of the currently displayed page. (This method is asynchronous).
GetTextSource Returns the Text contents of the currently displayed page. (This method is asynchronous).
GetValue See GetElementValue
Hide Hides the HTML control.
Init  
IsParentVisible Returns true if the control has a parent control, and the parent control is visible.
Kill  
Load Load a URL in the HTML Control.
LoadFromBlob Load the contents of a BLOB field into the HTML Control.
LoadFromDisk Load a disk file into the HTML Control.
LoadFromString Load the contents of a string (or StringTheory object) into the HTML Control.
OpenDeveloperTools
OnAddressChange This method is triggered if the URL in the browser changed. (ie the user navigated somewhere). This will also trigger an Event:CEFUrlChanged.
OnBeforeBrowse The user has attempted to navigate to a new URL.
OnBeforeClose  
OnBeforeContextMenu Called before the right-click popup menu appears.
OnBeforeDownload Called when the user clicks on a link that starts a download.
OnBeforePopup  
OnBeforeResourceLoad Called for every resource request that the the control sends to the server.
OnBrowserCreated  
OnDomFailure Called if a DOM request did not find an appropriate value.
OnDomResponse Called when a successful DOM request completes.
OnDownloadCancelled Called if the download was cancelled.
OnDownloadComplete Called when the download is complete.
OnDownloadUpdated Called during the download, when the progress bar updates.
OnFindResult Called after a call to Find.
OnLoaded This method is triggered when the page has finished loading into the HTML control.
OnLoadingStateChanged This method is triggered whenever a page starts, or completes, loading in the HTML control.
OnPDFPrintFinished This method when the PDF file (created by a call to PrintPDF) has completed.
OnScriptReady Called when the JavaScript engine has completed initialization, and is ready for scripts.
OnScriptResponse This method is triggered when JavaScript code, initiated with a call to CallScript, has completed successfully.
OnScriptFailure This method is triggered when JavaScript code, initiated with a call to CallScript, has completed unsuccessfully.
OnStatusMessage This method is triggered when the user mouse enters or exists an anchor on the page.
OnTitleChange This method is triggered if the Page Title in the browser changed. (ie the user navigated somewhere). This will also trigger an Event:CEFTitleChanged.
Post Issues a POST request to a server.
PostEvent Send an Event to a field on the page.
PrintPage This issues a Print command to the HTML control.
PrintPDF Prints the page to a PDF file.
Put See Post, but uses the PUT verb instead of the POST verb.
Reload Reloads the page that is currently in the HTML control..
Script Allows JavaScript on the page to be executed. See also CallScript.
SetAllowPopups Allows additional windows to be opened based on user clicking on links.
SetCookie Set the value of a cookie before making a call to Post, Get, Put, Delete
SetEnableDragDrop Sets the EnableDragDrop property to true or false.
SetFieldValue Set the value of a form field before making a call to Post, Get, Put, Delete
SetHeader Set the value of a header before making a call to Post, Get, Put, Delete
SetValue Set the value of a form field on the current page.
StartDownload Start a download of a file.
Stop Stops the browser from loading the page.
TakeEvent Processes window events that affect the HTML control.
Unhide Unhides the browser control.
Update Updates the location of the control. Called automatically after Event:OpenWindow and Event:Sized.
UpdateHTML Updates the contents of the control with the current contents of the String/Blob which was bound to the control with BindSource.
CEF_Class

BindSource

BindSource(String|Cstring|Blob|StringTheory p_Source ,Long p_SourceOptions=cef:html, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method binds a source variable (StringTheory, String, Cstring or BLOB) to the HTML control on the window.

Parameters
Parameter Description
p_Source A String, Cstring, Blob or StringTheory object that will act as the "source field" for the control.
p_SourceOptions Contains one of the following flags;
cef:url  - the source variable contains a URL
cef:html - (the default) - the source variable contains HTML code.
p_Encoding If the p_Source parameter is a String, CString or BLOB then this field determines the encoding of the string. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16. If the p_Source parameter is a StringTheory object then the Encoding property of the object is used instead.
p_CodePage If the p_Encoding parameter is st:EncodeAnsi then this field determines the code page of the string.

Notes

In concept this is the same as the USE variable for a screen control. It "binds" the variable to the value displayed on the screen.
If this field is updated, then an Event:CefUpdate should be sent to the control (or the method UpdateHTML should be called). This will cause the control to refresh to the new contents of the bound source variable.

Return Value

The method returns nothing.

See Also

BindTitle, BindURL , UpdateHTML , String Encoding

CEF_Class

BindTitle

BindTitle(*String p_Title)

Description

This method binds a string to the Page Title of the web page on display. The field has to be a string (not a cstring). If the user navigates to a new page, with a new title, then an Event:CefTitleChanged will be posted, and on that event this string will be updated.

Parameters
Parameter Description
p_Title A string field that will be updated when the title changes, as the user navigates.

Return Value

The method returns nothing.

See Also

BindSource, BindURL

CEF_Class

BindURL

BindURL(*String p_Url)

Description

This method binds a string to the URL of the web page on display. The field has to be a string (not a cstring). If the user navigates to a new page, then an Event:CefURLChanged will be posted, and on that event this string will be updated.

Parameters
Parameter Description
p_Title A string field that will be updated when the url changes, as the user navigates.

Return Value

The method returns nothing.

See Also

BindSource, BindTitle

CEF_Class

CallScript

CallScript(STRING p_JSCode, <STRING p_FrameName>, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method calls some JavaScript code, and causes the returnvalue to be sent to either the OnScriptResponse method (if successful) or to the OnScriptFailure method (if not successful).

Parameters
Parameter Description
p_JsCode The JavaScript code to execute.
p_FrameName The name of the frame to sent the script to. If this parameter is omitted then the current page is used.
p_Encoding If the p_JSCode parameter is a string then this field determines the encoding of the string. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16. If the p_JSCode parameter is a StringTheory object then the Encoding property of the object is used instead.
p_CodePage If the p_JSCode parameter is a string, and the p_Encoding parameter is st:EncodeAnsi then this field determines the code page of the string.

Return Value

The method returns an ID as a long. This ID can then be used in the OnScriptResponse and OnScriptFailure methods to match a response to a specific request.

See Also

Script, Calling A JavaScript Function with a Return Value , OnScriptResponse , OnScriptReady

CEF_Class

CloseDeveloperTools

CloseDeveloperTools()

Description

This method closes the Developer Tools window.

Return Value

Nothing

See Also

Developer Tools, OpenDeveloperTools

CEF_Class

Delete

Delete(STRING p_Url, <String p_DeleteData>, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)
Delete(STRING p_Url, StringTheory p_DeleteData, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)

Description

The same as the Get method, but the DELETE verb is used instead of the GET verb.
For more information on making direct request to servers see POST, GET, PUT, DELETE.

See Also

Get, Post, Put, SetFieldValue, SetHeader, SetCookie

CEF_Class

DeleteCookie

DeleteCookie(String p_Name)

Description

This method deletes a cookie from the Cookies queue which were added by the SetCookie method.

Parameters
Parameter Description
p_Name The name of the cookie to delete

See Also

Get, Post, Put, Delete,  SetCookie, FreeCookies

CEF_Class

DeleteFieldValue

DeleteFieldValue(String p_Name)

Description

This method deletes a field from the Field Value queue which were added by the SetFieldValue method.

Parameters
Parameter Description
p_Name The name of the field to delete

See Also

Get, Post, Put, Delete,  SetFieldValue, FreeFieldsQueue

CEF_Class

DeleteHeader

DeleteHeader(String p_Name)

Description

This method deletes a header from the Headers queue which were added by the SetHeader method.

Parameters
Parameter Description
p_Name The name of the header to delete

See Also

Get, Post, Put, Delete,  SetHeader, FreeHeaders

CEF_Class

Display

Display()

Description

This method forces a repaint of the control.

Example

cef1.dispay()

CEF_Class

Done

Done(CEF_EA_VisitEventArgsClass p_Args)

Description

This method is called when a call to GetHtmlSource or GetTextSource completes.
The string value being returned is by calling p_Args.GetBuffer(str). The value will be placed into the passed-in StringTheory object.

NOTE that the encoding in this StringTheory object is set to match the encoding requested when the GetHtmlSource or GetTextSource methods were called.

Parameters
Parameter Description
p_Args An object of type CEF_EA_VisitEventArgsClass.

Example

CEF1.Done PROCEDURE (CEF_EA_VisitEventArgsClass p_Args)
str  StringTheory
  code
  if p_Args.GetCallbackID() = someCallBackID
    p_Args.GetBuffer(str) ! the result is now in str
  End

See also

GetHtmlSource, GetTextSource, String Encoding, Retrieving the Contents of an HTML Page

CEF_Class

Find

Find (String | StringTheory p_Search, BYTE p_Forward=true, BYTE p_MatchCase=false)

Description

This method does a search in the control, highlighting all the places where the text is found.

Parameters
Parameter Description
p_Search the text to search for. Can be either a string, or StringTheory object.
p_Forward Set this to Cef:Forward to search forward, or Cef:Backward to search backwards.
p_MatchCase Set this true to do a case sensitive search.

See Also

FindNext

CEF_Class

FindNext

FindNext (BYTE p_Forward=true, BYTE p_MatchCase=false)

Description

Repeats the most recent Find, jumping (either forwards or backwards) to the next instance of the search-for text.

Parameters
Parameter Description
p_Forward Set this to Cef:Forward to search forward, or Cef:Backward to search backwards.
p_MatchCase Set this true to do a case sensitive search.

See Also

Find

CEF_Class

FreeCookies

FreeCookies()

Description

This method deletes all the entries in the Cookies queue which were added by the SetCookie method.

See Also

Get, Post, Put, Delete,  SetCookie, DeleteCookie

CEF_Class

FreeFieldsQueue

FreeFieldsQueue()

Description

This method deletes all the entries in the Fields queue which were added by the SetFieldValue method.

See Also

Get, Post, Put, Delete,  SetFieldValue, DeleteFieldValue

CEF_Class

FreeHeaders

FreeHeaders()

Description

This method deletes all the entries in the Headers queue which were added by the SetHeader method.

See Also

Get, Post, Put, Delete,  SetHeader, DeleteHeader

CEF_Class

Get

Get(STRING p_Url, <String p_GetData>, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)
Get(STRING p_Url, StringTheory p_GetData, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)

Description

This method makes a GET request to a server.
For more information on making direct request to servers see POST, GET, PUT, DELETE

Parameters
Parameter Description
p_Url The URL of the request.
p_GetData Any additional data to be sent with the request. This is in addition to the data set using the SetFieldValue method. This data is passed as part of the URL, separated from the URL by a ? symbol.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.
p_Flags The following flags are supported;
CEF:Cookies - Cookies returned by the server are used by subsequent requests.

Return Value

The method returns nothing.

See Also

Post, Put, Delete, SetFieldValue, SetHeader, SetCookie

CEF_Class

GetBodyHTML

GetBodyHTML (<STRING p_FrameName>)

Description

Gets the <BODY> section of the page. This method is asynchronous and the result is returned in OnDomResponse or OnDomFailure.

Parameters
Parameter Description
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDomResponse to determine the request being replied to.

See Also

GetDocumentHTML, GetElementAttributeValue, GetElementHTML, GetElementValue, GetHeadHTML , OnDomFailure, OnDOMReponse

CEF_Class

GetContentType

GetContentType (STRING p_FileName)

Description

Returns the HTML Mime Type for a given file, based on the file extension. This method also works if just the extension is passed, without the actual filename part.

Parameters
Parameter Description
p_FileName The name of the file being served.

Return Value

The method returns a String, which is the HTML MimeType of the file extension.

See Also

  GetCustomResource, GetCustomResourceMem, GetCustomResourceDisk

CEF_Class

GetCustomResource
GetCustomResourceMem

GetCustomResource (StringTheory p_Url, CEF_RequestClass p_Request, StringTheory p_Content, StringTheory p_MimeType)
GetCustomResourceMem (StringTheory p_Url, CEF_RequestClass p_Request, StringTheory p_Content, StringTheory p_MimeType)

Description

Allows you to populate the result of a request to a URL. GetCustomResource is called when the CELOCAL:\\ (or your custom name) protocol is used, and GetCustomResourceMem is used when the MEM:\\ protocol is used. These methods behave exactly the same - the correct one is called to match the protocol being used.

Parameters
Parameter Description
p_URL The whole URL as passed to the browser control. This URL can be further parsed using the StringTheory URL methods. (see URLFileOnly and friends.) 
p_Request A CEF_RequestClass object. Typically you won't need to access this object here, but it can be useful in some cases to burrow further into the original request.
p_Content This is the result, which needs to be populated by the developer. This is the content that will be returned to the browser.
p_MimeType This is the MimeType of the reply. This needs to be populated by the developer. You can make use of the GetContentType method to format this field correctly.

Return Value

The method returns a byte, True or False. If False then the navigation to this URL fails, and the browse control displays nothing. If the p_content parameter and p_mimetype parameters have been set, then return True.

See Also

GetContentType, GetCustomResourceDisk

CEF_Class

GetCustomResourceDisk

GetCustomResourceDisk (StringTheory p_Url, StringTheory p_FileName, CEF_RequestClass p_Request, StringTheory p_Content, StringTheory p_MimeType)

Description

Allows you to populate the result of a request to a URL. GetCustomResourceDisk is called when the DISK:\\ protocol is used. Before calling this method the class will parse the URL for the filename, and then load that file (if it exists) into the p_Content object, setting p_MimeType based on the file name extension. While this does some of the heavy lifting, you need to ensure that only valid files (files you wish to serve) are served using this approach. Inspect and verify the content of p_FileName.

Parameters
Parameter Description
p_URL The whole URL as passed to the browser control. This URL can be further parsed using the StringTheory URL methods. (see URLFileOnly and friends.)
pFileName The fully qualified name of the file loaded off the disk, and pre-placed into p_Content.
p_Request A CEF_RequestClass object. Typically you won't need to access this object here, but it can be useful in some cases to burrow further into the original request.
p_Content This is the result, which needs to be populated by the developer. This is the content that will be returned to the browser.
p_MimeType This is the MimeType of the reply. This needs to be populated by the developer. You can make use of the GetContentType method to format this field correctly.

Return Value

The method returns a byte, True or False. If False then the navigation to this URL fails, and the browse control displays nothing. If the filename is acceptable then return True.

See Also

GetContentType, GetCustomResource, GetCustomResourceMem

CEF_Class

GetDocumentHTML

GetDocumentHTML(<STRING p_FrameName>)

Description

Gets the html of the page. This method is asynchronous and the result is returned in OnDomResponse or OnDomFailure.

Parameters
Parameter Description
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDomResponse to determine the request being replied to.

See Also

GetBodyHTML, GetElementAttributeValue, GetElementHTML, GetElementValue, GetHeadHTML ,OnDomFailure, OnDOMReponse

CEF_Class

GetElementAttributeValue

GetElementAttributeValue(STRING p_ElementID, STRING p_AttributeName, <STRING p_FrameName>)

Description

Gets the value of a specific attribute which is attached to a specific element.

Parameters
Parameter Description
p_ElementID The ID of the Element on the DOM to inspect.
p_AttributeName The name of the attribute to inspect.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDomResponse to determine the request being replied to.

Example

callbackID = CEF.GetElementAttributeValue('someEntryField','class')

See Also

GetBodyHTML, GetDocumentHTML, GetElementHTML, GetElementValue, GetHeadHTML, OnDomFailure, OnDOMReponse

CEF_Class

GetElementHTML

GetElementHTML (STRING p_ElementID, <STRING p_FrameName>)

Description

Gets the HTML for a specific node in the DOM.

Parameters
Parameter Description
p_ElementID The ID of the Element on the DOM to inspect.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDomResponse to determine the request being replied to.

Example

callbackID = cef.GetElementHTML('someDivId')

See Also

GetBodyHTML, GetDocumentHTML, GetElementAttributeValue, GetElementValue, GetHeadHTML, OnDomFailure, OnDOMReponse

CEF_Class

GetElementValue

GetElementValue (STRING p_ElementID, <STRING p_FrameName>)

Description

Gets the current value of an input field on the page.

Parameters
Parameter Description
p_ElementID The ID of the Element on the DOM to inspect.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDOMReponse to determine the request being replied to.

Example

callbackID = cef.GetElementValue('someEntryID')

See Also

GetBodyHTML, GetDocumentHTML, GetElementAttributeValue, GetElementHTML, GetHeadHTML, OnDomFailure, OnDOMReponse

CEF_Class

GetHeadHTML

GetHeadHTML(<STRING p_FrameName>)

Description

Gets the <HEAD> section of the page. This method is asynchronous and the result is returned in OnDomResponse or OnDomFailure.

Parameters
Parameter Description
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns a Long, which is the ID of the request. This can be used in OnDomResponse to determine the request being replied to.

See Also

GetBodyHTML, GetDocumentHTML, GetElementAttributeValue, GetElementHTML, GetElementValue, OnDomFailure, OnDOMReponse

CEF_Class

GetHTMLSource

GetHTMLSource(<STRING p_FrameName>,Long p_DesiredEncoding=st:EncodeAnsi, Long p_DesiredCodePage=st:CP_Detect)

Description

This method retrieves the contents of the current HTML page.

Parameters
Parameter Description
p_FrameName The name of the frame to fetch. Omit this parameter to get the whole page.
p_DesiredEncoding See String Encoding to understand why these two parameters exist.
One of st:EncodeAnsi, st:EncodeUtf8, st:EncodeUtf16
p_DesiredCodePage A code page value. The default value (st:CP_Detect) will automatically use the code page as determined by the System{prop:Charset} of your program. For a list of code page equates see String Encoding.

Notes

This method is asynchronous. This means the contents of the page are not returned by this method. The contents are returned into the Done method.

Return Value

The Callback ID. This ID is passed into the Done method, so you can connect this call with the response there.

Examples

someCallBackID = cef1.GetHtmlSource()
someCallBackID = cef1.GetHtmlSource( , st:EncodeUtf8)
someCallBackID = cef1.GetHtmlSource( , st:EncodeAnsi, st:CP_WINDOWS_1252)  ! spanish / western europe

See Also

GetTextSource, Done,  String Encoding, Retrieving the Contents of an HTML Page


CEF_Class

GetTextSource

GetTextSource(<STRING p_FrameName>,Long p_DesiredEncoding=st:EncodeAnsi, Long p_DesiredCodePage=st:CP_Detect)

Description

This method retrieves the contents of the current text on the HTML page.  Basically the source of the page, but without any HTML tags. Whether this is meaningful in any way depends on the content on the page.

Parameters
Parameter Description
p_FrameName The name of the frame to fetch. Omit this parameter to get the whole page.
p_DesiredEncoding See String Encoding to understand why these two parameters exist.
One of st:EncodeAnsi, st:EncodeUtf8, st:EncodeUtf16
p_DesiredCodePage A code page value. The default value (st:CP_Detect) will automatically use the code page as determined by the System{prop:Charset} of your program. For a list of code page equates see String Encoding.

Notes

This method is asynchronous. This means the contents of the page are not returned by this method. The contents are returned into the Done method.

Return Value

The Callback ID. This ID is passed into the Done method, so you can connect this call with the response there.

Examples

someCallBackID = cef1.GetHtmlSource()
someCallBackID = cef1.GetHtmlSource( , st:EncodeUtf8)
someCallBackID = cef1.GetHtmlSource( , st:EncodeAnsi, st:CP_WINDOWS_1252)  ! spanish / western europe

See Also

GetHtmlSource, Done,  String Encoding, Retrieving the Contents of an HTML Page


CEF_Class

Load

Load(STRING p_Url, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method populates the control from a URL.

Parameters
Parameter Description
p_URL A String containing the URL to be loaded in the HTML control on the window. The URL could point to a resource on the network (like say https://www.capesoft.com) or to a file on the disk (file://c:\temp\something.html)
p_Encoding This parameter determines the encoding of the URL string. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16.
p_CodePage If the p_Encoding parameter is st:EncodeAnsi then this parameter determines the code page of the URL.

Return Value

True if the load is successful. False if not successful.

Examples

Cef1.Load('https://www.capesoft.com')

See Also

  String Encoding , LoadFromString , LoadFromBlob , LoadFromDisk


CEF_Class

LoadFromBlob

LoadFromBlob(*Blob p_Blob, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method populates the control with the contents of a BLOB.

Parameters
Parameter Description
p_Blob A BLOB containing the text (presumably HTML text), which will be loaded in the HTML control on the window.
p_Encoding This parameter determines the encoding of the blob. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16.
p_CodePage If the p_Encoding parameter is st:EncodeAnsi then this parameter determines the code page of the BLOB.

Return Value

True if the load is successful. False if not successful.

Examples

  cef1.LoadFromString(cus:Comments,st:EncodeUtf8)

See Also

  String Encoding , LoadFromString , LoadFromDisk, Load


CEF_Class

LoadFromDisk

LoadFromDisk(String p_FileName, Long p_Options=CEF:ProgramPath)

Description

This method populates the control with a file on the disk.

Parameters
Parameter Description
p_FileName The name of the file on disk.
p_Options If set to CEF:ProgramPath (the default) then the path to the exe is prepended to the file name.
If set to CEF:CurrentPath then the current PATH() is prepended to the file name.
If neither of these is set (or the file name is already a complete path - ie starting with x: or \\) then this option is ignored.

Return Value

True if the load is successful. False if not successful.

Examples

cef1.LoadFromDisk('home.htm')
cef1.LoadFromDisk('c:\inetpub\docs\home.htm')
cef1.LoadFromDisk('\\mickey\docs\home.htm')
cef1.LoadFromDisk('home.htm',CEF:currentPath)

See Also

LoadFromString , LoadFromBlob , Load


CEF_Class

LoadFromString

LoadFromString(String | StringTheory p_HTML, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method populates the control with the contents of a string, or StringTheory object.

Parameters
Parameter Description
p_HTML A String, or StringTheory object containing the text (presumably HTML text), which will be loaded in the HTML control on the window.
p_Encoding If the p_HTML parameter is a string then this parameter determines the encoding of the string. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16. If the p_HTML parameter is a StringTheory object then the Encoding property of the object is used instead.
p_CodePage If the p_HTML parameter is a string, and the p_Encoding parameter is st:EncodeAnsi then this parameter determines the code page of the string.

Return Value

True if the load is successful. False if not successful.

Examples

str StringTheory
  code
  str.SetValue('<<html><<body>amazing!<</body><</html>')
  cef1.LoadFromString(str,st:EncodeUtf8)

See Also

 String Encoding , LoadFromBlob , LoadFromDisk, Load



CEF_Class

OpenDeveloperTools

OpenDeveloperTools()

Description

This method opens the Developer Tools window.

Return Value

Nothing

See Also

Developer Tools, CloseDeveloperTools

CEF_Class

OnBeforeBrowse

OnBeforeBrowse(CEF_EA_BeforeBrowseEventArgsClass p_Args)

Description

This method is called when the user attempts to navigate to a new URL. This is an ideal spot to examine the proposed URL and either Prevent Navigation to a URL or Redirect Navigation to a Different URL.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the requested navigation.

Notes

This method is only called if the user triggered a request. It is not called for other resources requested by the page. So one user-click results in one OnBeforeBrowse, but when that page arrives it may trigger any number of further requests for css, JavaScript files, images and so on. To trap all of those see the OnBeforeResourceLoad method.

Return Value

If this method returns cef:stop then the request will be cancelled. If it return cef:go then it will proceed.

See Also

OnBeforeResourceLoad

CEF_Class

OnBeforeContextMenu

OnBeforeContextMenu(CEF_EA_BeforeContextMenuEventArgsClass p_Args)

Description

This method is called when the user has attempted to open the right-click popup menu. This allows the developer to intercept the menu, and either suppress it, or replace it with something else.

Parameters
Parameter Description
p_Args An object for suppressing the menu

Notes

To suppress the default menu add the following code, before the parent call;

p_Args.PreventContextMenu(true)

After the parent call, additional code can be added to create, and manage your own popup menu using the Clarion POPUP command. For example;

execute popup('one|two')   
  message('1')
  message('2')
end

Return Value

Nothing

See Also

Right-Click Popup Menu

CEF_Class

OnBeforeDownload

OnBeforeDownload(CEF_EA_BeforeDownloadEventArgsClass p_Args)

Description

This method is called when the user clicks on a download link. If the p_Args.AllowDownload method is not called, then the download will be cancelled.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the download request.

Notes

The p_Args object contains information about the request. You can use this to determine if the download should be allowed or not. You can also determine if the download should continue, and what the filename of the download should be.

The following items are available for use in this method. In all cases the result can be placed in a  passed-in StringTheory object. If no StringTheory object is passed in, then the value will be returned as a string.

p_Args.get_suggested_file_name(str)
p_Args.get_mime_type(str)
p_Args.get_content_disposition(str)
p_Args.get_url(str)
p_Args.get_original_url(str)

The p_Args.AllowDownload method needs to be called before OnBeforeDownload completes, or the download will be cancelled.
This method can be called in one of three ways;

p_Args.AllowDownload()  ! The file will be downloaded to a temporary location, and the name exposed in OnDownloadComplete.

p_Args.AllowDownload(true)  ! The user will be prompted for a name and location. the name selected by the user will be exposed in OnDownloadComplete.

p_Args.AllowDownload(str)  ! The location, and name, of the file is set via the str StringTheory object.

Return Value

The method returns nothing.

See Also

StartDownload, OnDownloadUpdated, OnDownloadComplete, OnDownloadCancelled

CEF_Class

OnBeforeResourceLoad

OnBeforeResourceLoad(CEF_EA_BeforeResourceLoadEventArgsClass p_Args)

Description

This method is called when the browser is going to make a request to the server. By this point the request has been fully formed, and it can be inspected. this makes it an ideal point for logging all requests, or inspecting form data etc.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the requested request.

Notes

Unlike OnBeforeBrowse which is only triggered when the user does something, this method is triggered for all resource requests (including user triggered requests). The request has also been fully formed by this point, unlike OnBeforeBrowse.

A request can be blocked by calling (BEFORE the Parent Call)

p_Args.ContinueRequest(false)
Return

Return Value

Nothing

See Also

OnBeforeBrowse, Inspecting Request Data

CEF_Class

OnDOMFailure

OnDOMFailure (LONG p_CallbackID, LONG p_Error, STRING p_ErrorMessage, CEF_DomResponseClass p_Args)

Description

This method will be called when a DOM request is unsuccessful.

Parameters
Parameter Description
p_CallbackID The ID as returned by the DOM request.
p_Error The error that occurred.
p_ErrorMessage A description of the error that occurred.
p_Args   An object that contains all the necessary data about the DOM request.

Notes

You can access the elements of p_Args, as in the other methods, if you wish to know more about the request being cancelled.

Return Value

The method returns nothing.

See Also

GetBodyHTML, GetDocumentHTML, GetElementAttributeValue, GetElementHTML, GetElementValue, GetHeadValue,  OnDOMReponse

CEF_Class

OnDOMResponse

OnDOMResponse (LONG p_CallbackID, CEF_DomResponseClass p_Args)

Description

This method will be called when a download is cancelled.

Parameters
Parameter Description
p_CallbackID The ID as returned by the DOM request.
p_Args  An object that contains all the necessary data about the download request.

Notes

You can access the elements of p_Args to determine the result of the request.
The value p_Args.Getcommand() returns the type of command which generated this result. Depending on this value you can inspect p_Args.GetMarkup() or p_Args.GetValue() .

Example

Case p_Args.GetCommand()
of DOMCOMMAND:GetDocumentMarkup
orof DOMCOMMAND:GetHeadMarkup
orof DOMCOMMAND:GetBodyMarkup
orof DOMCOMMAND:GetElementMarkup
  result = p_Args.GetMarkup()
of DOMCOMMAND:GetElementValue
orof DOMCOMMAND:GetElementAttributeValue
  result = p_Args.GetValue()
End

Return Value

The method returns nothing.

See Also

GetBodyHTML, GetDocumentHTML, GetElementAttributeValue, GetElementHTML, GetElementValue, GetHeadValue, OnDomFailure

CEF_Class

OnDownloadCancelled

OnDownloadCancelled(CEF_EA_DownloadUpdatedEventArgsClass p_Args)

Description

This method will be called when a download is cancelled.

Parameters
Parameter Description
p_Args  An object that contains all the necessary data about the download request.

Notes

You can access the elements of p_Args, as in the other methods, if you wish to know more about the item being cancelled.

Return Value

The method returns nothing.

See Also

StartDownload, OnBeforeDownload, OnDownloadUpdated, OnDownloadComplete

CEF_Class

OnDownloadComplete

OnDownloadComplete(CEF_EA_DownloadUpdatedEventArgsClass p_Args)

Description

Called when a download has been completed.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the download request.

Notes

The following items are available for use in this method. In all cases the result can be placed in a  passed-in StringTheory object. If no StringTheory object is passed in, then the value will be returned as a string. The full path returns the location of the downloaded file.

p_Args.get_full_path(str)
p_Args.get_mime_type(str)

If you wish to process the download, then it can be loaded into a StringTheory object for processing here.

Example

str  StringTheory
  code
  str.LoadFile(p_Args.get_full_path())


Return Value

The method returns nothing.

See Also

StartDownload, OnBeforeDownload, OnDownloadUpdated, OnDownloadCancelled

CEF_Class

OnDownloadUpdated

OnDownloadUpdated(CEF_EA_DownloadUpdatedEventArgsClass p_Args)

Description

This method is called during a download when the progress bar is updated.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the download request.

Notes

The p_Args.CancelDownload method can be called from here to cancel a download.

If p_Args.is_complete() = false AND p_Args.is_canceled() = false
  p_Args.CancelDownload()
End

If you have a cancel button on the Window, which allows the user to cancel the download, then you could set a local variable there to true, and then use that variable in the OnDownloadUpdated method to trigger the cancel. For example;

If CancelDownload = true and p_Args.is_complete() = false AND p_Args.is_canceled() = false
  p_Args.CancelDownload()
  CancelDownload = false
End

Return Value

The method returns nothing.

See Also

StartDownload, OnBeforeDownload, OnDownloadCancelled, OnDownloadComplete

CEF_Class

OnFindResult

OnFindResult (CEF_EA_FindResultEventArgsClass p_Args)

Description

This method is called after a call to the Find method.

Parameters
Parameter Description
p_Args An object that contains all the necessary data about the find result.

Notes



Return Value

The method returns nothing.

See Also

Find, FindNext

CEF_Class

OnLoaded

OnLoaded ()

Description

Called from the OnLoadingStateChanged method, when the IsLoading property is set to false. (In other words called when the IsLoading property changes to false.)

Notes

Use this method to embed code, which needs to only happen after the page has loaded. For example any calls to Script or CallScript could happen in this embed.

Return Value

The method returns nothing.

See Also

OnLoadingStateChanged

CEF_Class

OnLoadingStateChanged

OnLoadingStateChanged(CEF_EA_LoadingStateChangeEventArgsClass p_Args)

Description

This method is called when the loading state of a page changes.

Parameters
Parameter Description
p_Args A CEF_EA_LoadingStateChangeEventArgsClass object that contains all the necessary data about the load request.

Notes



Return Value

The method returns nothing.

See Also

OnLoaded

CEF_Class

OnPDFPrintFinished

OnPDFPrintFinished(CEF_EA_PDFPrintFinishedEventArgsClass p_Args)

Description

This method is called when the PDF file, created with a call to PrintPDF, has been created.

Parameters

Parameter Description
p_Args A CEF_EA_PDFPrintFinishedEventArgsClass object that contains all the necessary data about the file.
Specifically;
p_Args.GetPrintOk()
p_Args.GetPath()
p_Args.GetCallbackId()


Return Value

Nothing

See Also

PrintPage, PrintPDF

CEF_Class

OnScriptReady

OnScriptReady()

Description

This method is called when the JavaScript engine is ready to receive calls to Script and CallScript. It sets the property ScriptReady to true.
You can use this method to make calls to Script or CallScript as soon as the engine is ready.

Return Value

Nothing

See Also

Script, CallScript

CEF_Class

OnScriptResponse

OnScriptResponse(LONG p_CallbackID, CEF_ScriptResponseClass p_Response)

Description

This method is called when the JavaScript engine has successfully completed the JavaScript code initiated by a call to the CallScript method. The CallBackID passed in here matches the value returned by the call to CallScript.

Parameters

Parameter Description
p_CallBackId The ID of the call, as returned to the CallScript function. This allows you to match up responses to their originating calls.
p_Response An object of type CEF_ScriptResponseClass containing the details of the response.

Return Value

Nothing

Example

CEF1.OnScriptResponse   PROCEDURE (LONG p_CallbackID, CEF_ScriptResponseClass p_Response)
x Long
  code
  PARENT.OnScriptResponse (p_CallbackID,p_Response)
  if p_CallbackID = someID
    x = p_response.GetValue()
  end

See Also

Script, Calling A JavaScript Function with a Return Value, CallScript, OnScriptFailure, CEF_ScriptResponseClass.

CEF_Class

OnScriptFailure

OnScriptFailure(LONG p_CallbackID, LONG p_Error, STRING p_ErrorMessage, CEF_ScriptResponseClass p_Response)

Description

This method is called when the JavaScript engine returns a failure to a CallScript command.

Parameters

Parameter Description
p_CallBackId The ID of the call, as returned to the CallScript function. This allows you to match up responses to their originating calls.
p_Error One of CEF:ERROR:ScriptFailException or CEF:ERROR:ScriptFailNoException
p_ErrorMessage The error message returned by the JavaScript engine.
p_Response An object of type CEF_ScriptResponseClass containing the details of the response.

Notes

p_response.GetExceptionLineNumber() returns the line number of the error.

Return Value

Nothing

Example

CEF1.OnScriptFailure   PROCEDURE (LONG p_CallbackID, LONG p_Error, STRING p_ErrorMessage, CEF_ScriptResponseClass p_Response)
  CODE
  PARENT.OnScriptFailure (p_CallbackID,p_Error,p_ErrorMessage,p_Response)
  message('script (' & p_CallbackID & ') failure: ' & p_Error & ' ' & |
           p_ErrorMessage & ' command: ' & p_Response.GetCommand() & ' Line:' & p_Response.GetExceptionLineNumber())

See Also

Script, CallScript, OnScriptResponse, Calling A JavaScript Function with a Return Value

CEF_Class

OnStatusMessage

OnStatusMessage(CEF_EA_StatusMessageEventArgsClass p_Args)

Description

This method is called when the user mouse-overs an anchor tag on the page. It is called when the mouse enters the tag area, and also when it exists the tag area.

Parameters

Parameter Description
p_Response An object of type CEF_EA_StatusMessageEventArgsClass containing the details of the message.

Notes

p_response.GetStatusMessage() returns the underlying URL of the anchor. If the user is leaving the anchor then this value is a blank string..

Return Value

String. The anchor href value (on mouse in), or a blank string (on mouse out).

Example

CEF1.OnStatusMessage   PROCEDURE (CEF_EA_StatusMessageEventArgsClass p_Args)
  CODE
  PARENT.OnStatusMessage (p_Args)
  CefStatus = p_Args.GetStatusMessage()

See Also



CEF_Class

Post

Post(STRING p_Url, <String p_PostData>, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)
Post(STRING p_Url, StringTheory p_PostData, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)

Description

This method makes a POST request to a server.
For more information on making direct request to servers see POST, GET, PUT, DELETE

Parameters
Parameter Description
p_Url The URL of the request.
p_PostData Any additional data to be sent with the request. This is in addition to the data set using the SetFieldValue method.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.
p_Flags The following flags are supported;
CEF:Cookies - Cookies returned by the server are used by subsequent requests.

Return Value

The method returns nothing.

See Also

Put, Get, Delete, SetFieldValue, SetHeader, SetCookie

CEF_Class

PostEvent

PostEvent(String p_Selector,String p_Event,<Long p_Index>, <STRING p_FrameName>)

Description

Triggers a JavaScript Event on one or more items on the page.

Parameters
Parameter Description
p_Selector A Selector to identify the field to be set.
p_Event A string containing the event name to be sent. For example change or blur. Note that the event name is case sensitive.
p_Index If the selector returns multiple items, and you only want to send the event to one of them, you can use a number here to specify which one to post to.
p_FrameName The name of the frame to make the request from. If omitted the current page frame is used.

Return Value

The method returns nothing.

See Also

Put, Get, Delete, SetFieldValue, SetHeader, SetCookie

CEF_Class

PrintPage

PrintPage()

Description

Sends the contents of the current control to the printer.

Return Value

The method returns a long. This is set to cef:ok if the call is successful, cef:notok otherwise.

See Also

PrintPDF, OnPDFPrintFinished

CEF_Class

PrintPDF

PrintPDF(string p_FileName, CEF_PdfPrintSettings p_PDFPrintSettings)

Description

Exports the current contents of the control to a PDF file. In essence "printing" to a PDF file.

This method is  asynchronous. The actual file is not created by the time this call ends. When the file has been created, then a call to the OnPDFPrintFinished method will be made. So if further action on the PDF file is desired - for example emailing, or uploading, then it must be done in that method, not in the code following this call.

Parameters
Parameter Description
p_FileName The name of the PDF file to create. If this parameter is blank (ie an empty string) then the FILEDIALOG command will be called, and the user will be able to select the filename from the Windows dialog.
p_PDFPrintSettings A group of type CEF_PdfPrintSettings which controls all the options that the PDF engine takes.

Return Value

The method returns a callback ID. When the method has completed the OnPDFPrintFinished method will be called. Comparing this ID to the ID there will allow you to match up calls here to calls there.

See Also

PrintPage, OnPDFPrintFinished
CEF_Class

Put

Put(STRING p_Url, <String p_PostData>, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)
Put(STRING p_Url, StringTheory p_PostData, <STRING p_FrameName>, LONG p_Flags=CEF:COOKIES)

Description

The same as the Post method, but the PUT verb is used instead of the POST verb.
For more information on making direct request to servers see POST, GET, PUT, DELETE

See Also

Post, Get, Delete, SetFieldValue, SetHeader, SetCookie

CEF_Class

Script

Script(STRING p_JSCode, <STRING p_FrameName>, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)
Script(StringTheory p_JSCode, <STRING p_FrameName>)

Description

This method sends a block of JavaScript code to the page. The script is then executed. No return value is expected, and if one is generated by the engine it is ignored. For calling a script, with a return value, see the CallScript method.

Parameters
Parameter Description
p_JsCode The JavaScript code to execute.
p_FrameName The name of the frame to sent the script to. If this parameter is omitted then the current page is used.
p_Encoding If the p_JSCode parameter is a string then this field determines the encoding of the string. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16. If the p_JSCode parameter is a StringTheory object then the Encoding property of the object is used instead.
p_CodePage If the p_JSCode parameter is a string, and the p_Encoding parameter is st:EncodeAnsi then this field determines the code page of the string.

Return Value

The method returns CEF:Ok if the script was sent, CEF:NotOk if it failed.

See Also

String Encoding , SetValue , LoadFromString, CallScript, OnScriptReady, Running JavaScript on the Page

CEF_Class

SetAllowPopups

SetAllowPopups(BYTE p_Allow)

Description

Sets the AllowPopups property to p_Allow (true or false). If allow popups is set to true, and the user clicks on a link which has the target attribute set to '_blank', then a new CEF control, in a new window will be opened. The default value for the property is false, meaning that all links open into the same control, regardless of their target setting.


CEF_Class

SetCookie

SetCookie(String p_Name, String p_Value)

Description

This method adds a cookie to the cookies queue in preparation for a request to a server.
For more on this topic see  POST, GET, PUT, DELETE

Parameters
Parameter Description
p_Name The name of the cookie
p_Value The value for the cookie

Return Value

The method returns nothing.

See Also

Post, Get, Put, Delete, FreeCookies, DeleteCookie

CEF_Class

SetEnableDragDrop

SetEnableDragDrop(BYTE p_enable)

Description

This methods sets the EnableDragDrop property. If this property is set then the control allows external files to be dragged from Windows Explorer onto the control.

Parameters
Parameter Description
p_Enable Set to true to allow drag and drop, and to false to not allow drag and drop.

Return Value

The method returns nothing.

See Also

Drag and Drop onto the Control

CEF_Class

SetFieldValue

SetFieldValue(String pName, String pValue, Long pFile=0,<String pContentType>,<String pCustomHeader>)

Description

This method adds a form field value to the Fields queue in preparation for a request to a server.
For more on this topic see  POST, GET, PUT, DELETE

Parameters
Parameter Description
p_Name The name of the field
p_Value The value for the field

Return Value

The method returns nothing.

See Also

Post, Get, Put, Delete, FreeFieldsQueue, DeleteFieldValue

CEF_Class

SetHeader

SetHeader(String p_Name, String p_Value)

Description

This method adds a cookie to the cookies queue in preparation for a request to a server.
For more on this topic see  POST, GET, PUT, DELETE

Parameters
Parameter Description
p_Name The name of the header
p_Value The value for the header

Return Value

The method returns nothing.

See Also

Post, Get, Put, Delete, FreeHeaders, DeleteHeader

CEF_Class

SetValue

SetValue(String p_Selector, String p_Value, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)
SetValue(String p_Selector, Long p_Index, String p_Value, <STRING p_FrameName>, Long p_Encoding, Long p_CodePage)

Description

This method sets a form-field value for a field on the currently loaded page.

Parameters
Parameter Description
p_Selector A Selector to identify the field to be set.
p_Index An optional index into the selector.
p_Value The value to set the field to.
p_Encoding This field determines the encoding of the Selector, and Value parameters. Possible options are st:EncodeAnsi, st:EncodeUTF8, st:EncodeUTF16. Both string parameters must use the same encoding.
p_CodePage If the p_Encoding parameter is st:EncodeAnsi then this field determines the code page of the strings.
p_FrameName An optional parameter to specify the name of the frame on which the field exists.

Return Value

Returns cef:ok if successful, cef:notok if not.

Example

CEF1.SetValue('#locator1productssearchlist','chrome')

See Also

Set a Value on the page, Selectors, Script, String Encoding

CEF_Class

StartDownload

StartDownload(STRING p_Url)

Description

This method is called during a download when the progress bar is updated.

Parameters
Parameter Description
p_Url The URL of the resource to download.

Notes

This method is the same as a user clicking on a URL to initiate a download. Note however that all the requirements for that download are still required - you still need to call AllowDownload in the OnBeforeDownload method, and so on.
(This is done if the Control template has the Allow Downloads setting on.)

Return Value

The method returns nothing.

See Also

OnBeforeDownload, OnDownloadUpdated, OnDownloadCancelled, OnDownloadComplete

CEF_Class

UpdateHTML

UpdateHTML()

Description

This method updates the control on the window, if the Source of the control (as set by the BindSource method) changes. this method is called automatically on the Event:CEFUpdate. In other words, if the source variable (String, CString, BLOB or StringTheory changes then either post Event:CEFUpdate or call this UpdateHTML method.

Return Value

The method returns nothing.

See Also

BindSource

Classes

CEF_EditorClass

Derivation

  • CEF_EditorClass (CEF_EditorClass.Inc / CEF_EditorClass.Clw)

Properties

Property Description
Dirty Set to cef:dirty when UpdateFromHTML method is called.  Set to cef:clean when UpdateSource method has been called. If dirty when an Event:Completed occurs then UpdateFromHTML is called.
EditorLoaded Set to true when the CKEditor.HTM  (or equivalent) file has been loaded into the control. This does not apply to editor content which may be loaded later on.
EditorInitialized Set to true when the InitEditor has been called for this control. Code which executes after the editor has been initialized should check this first.

Methods

Method Description
InitEditor Starts the editor with some default options.
InsertHTML Insert HTML at the cursor position
InsertText Insert text at the cursor position
OnLoaded Called when the Editor HTML file has completed loading into the control.
OnSaved Called after the contents of the HTML are saved to disk.
PrintContent Print the content of the editor.
ReplaceText Replace text in the control with other text.
SaveFile Trigger an update of the HTML Editor Control to a file on the disk. Asynchronous.
SetOption Set an option for the editor
SetTheme Set the theme for the editor
SetMode / SetLanguage Set the mode (language) for the editor (ACE only)
UpdateHTML Moves the current contents of the bound field into the HTML Editor control.
UpdateFromHTML Triggers an update from the HTML control to the bound field. Asynchronous.
UpdateSource Moves the received HTML into the bound field.
CEF_EditorClass

InsertHTML

InsertHTML(String p_HTML, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method inserts HTML code at the cursor position.

Parameters
Parameter Description
p_HTML The HTML to insert. Note that the parameter IS clipped before being added.
p_Encoding The encoding of the string you are inserting. Possible options are st:EncodeAnsi, st:EncodeUtf8 and st:EncodeUtf16.
p_CodePage If the encoding is st:EncodeAnsi then this is the code page of the HTML you are inserting.
Notes

Note that if the HTML being inserted contains an <img> tag, then the editor control must have the "File Browser" plugin active.
If you embed a filename in the src="" attribute, then it's recommended to call the GetDiskName method to convert the file name from "DOS" format to HTML format.

Return Value

The method returns nothing.

Example

If FileDialog('Load HTML File',Filename,'Png|*.png|All Files|*.*',FILE:KeepDir + FILE:LongName)
  cef1.InsertHTML('<img src="'&cef1.GetDiskName(FileName,0)&'">')
end

See Also

ReplaceText, InsertText , String Encoding

CEF_EditorClass

InsertText

InsertText(String p_Text, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

This method inserts text at the cursor position.

Parameters
Parameter Description
p_Text The text to insert. Note that the parameter is NOT clipped, so care should be taken to pass in already-clipped text if that is desired.
p_Encoding The encoding of the text you are inserting. Possible options are st:EncodeAnsi, st:EncodeUtf8 and st:EncodeUtf16.
p_CodePage If the encoding is st:EncodeAnsi then this is the code page of the text you are inserting.

Return Value

The method returns nothing.

Example

cef1.InsertText(format(today(),'@d1') & ' ' & format(clock(),'@t1'))

See Also

ReplaceText, InsertHTML , String Encoding

CEF_EditorClass

OnLoaded

OnLoaded ()

Description

This method is called when the editor control has completed loading into the CEF Control. An Event:CefUpdate is sent to the control.

Return Value

The method returns nothing.


CEF_EditorClass

OnSaved

OnSaved()

Description

This method is called when the process started by SaveFile has been completed, and the file has been saved to disk. It allows for easily embedding code after the save.

Return Value

The method returns nothing.

See Also

SaveFile

PrintContent

PrintContent()

Description

If the editor has a Print button, then this method will trigger that button, and cause the content of the editor to go to the printer.

Return Value

The method returns nothing.

See Also

 

CEF_EditorClass

ReplaceText

ReplaceText(String p_Search, String p_Replace, Long p_NoCase=false, Long p_All=false, Long p_Encoding=st:EncodeAnsi, Long p_CodePage=st:CP_Detect)

Description

Replace some text in the editor control with some other text.

Parameters
Parameter Description
p_Search The search text to look for. This field can contain JavaScript (not Clarion) regex. Note that this value is NOT clipped inside the function, so be careful of trailing spaces in your search term. Any / characters in the text will be encoded as \/ before sending to the control, so use / as a plain character, do not encode it as \/.
p_Replace The text to put in the place of the searched text. Note that this value is NOT clipped inside the function, so be careful of trailing spaces in your replace term.
p_NoCase if set to true then a case insensitive search is performed
p_All If set to false then only the first instance of the text will be replace. If set to true then all instances will be replaced.
p_Encoding The encoding of the search and replace strings you are using. Possible options are st:EncodeAnsi, st:EncodeUtf8 and st:EncodeUtf16.
pCodePage If the encoding is st:EncodeAnsi then this is the code page of the text you are inserting.

Return Value

The method returns nothing.

See Also

InsertText , String Encoding

CEF_EditorClass

SaveFile

SaveFile(String p_FileName,Long p_Then=0)

Description

This method triggers an update of the source field from the HTML (UpdateFromHTML), and then saves that HTML to disk. This method is asynchronous so will not complete immediately. The OnSaved method will be called when it has completed.

Parameters
Parameter Description
p_FileName The fully qualified filename where the HTML Editor content should be saved to.
p_Then Set to a combination of one of the following;
cef:CloseWindow  : An Event:CloseWindow will be generated.

Return Value

The method returns nothing.

See Also

OnSaved , UpdateFromHTML

CEF_EditorClass

UpdateHTML

UpdateHTML()

Description

This method moves the current contents of the bound field into the HTML Editor control. If the HTML has been edited externally, (ie the source field value has changed) then call this method to update the control.
This method is triggered automatically by Event:CefUpdate.

Return Value

The method returns cef:ok if successful, cef:notok if not.

See Also

UpdateSource, UpdateFromHTML, BindSource

CEF_EditorClass

UpdateFromHTML

UpdateFromHTML()

Description

This method triggers an update from the HTML control to the bound field. This method is asynchronous so will not complete immediately. The UpdateSource method will be called when it has completed.

Return Value

The method returns cef:ok if successful, cef:notok if not.

See Also

UpdateSource, UpdateHTML

CEF_EditorClass

UpdateSource

UpdateSource(StringTheory p_NewValue)

Description

This method is called when the process started by SaveFile has been completed, and the file has been saved to disk. It allows for easily embedding code after the save.

Parameters
Parameter Description
p_NewValue The HTML value inside the CEF Control.

Notes

If embedding before the parent call, then the p_NewValue parameter contains the raw HTML of the page. If after the parent call it contains the contents of the HTML Editor control.

Return Value

The method returns nothing.  It does POST an Event:CloseWindow or an Event:CefMaybeComplete.

See Also

UpdateFromHTML, UpdateHTML, Trapping Errors After Calling SaveFile

Classes

CEF_EA_BaseEventArgsClass

This class is a base class for all the Args classes.It currently has no properties or methods.

Derivation

  • CEF_EA_BaseEventArgsClass (CEF_EA_BaseEventArgsClass.Inc / CEF_EA_BaseEventArgsClass.Clw)

Properties

None

Methods

None
Classes

CEF_EA_LoadingStateChangeEventArgsClass

This class is passed as a parameter to the OnLoadingStateChange method. Inside that method the properties, and methods, of this class can be used.

Derivation

  • CEF_EA_LoadingStateChangeEventArgsClass (CEF_EA_LoadingStateChangeEventArgsClass.Inc / CEF_EA_LoadingStateChangeEventArgsClass.Clw)

Properties

Property Description
IsLoading
CanGoBack
CanGoForward

Methods

Method Description
GetIsLoading
GetCanGoForward
GetCanGoBack
CEF_ScriptResponseClass

GetIsLoading

GetIsLoading()

Description

I

Return Value

A

See Also



Classes

CEF_BaseResponseClass

Derivation

  • CEF_BaseResponseClass (CEF_BaseResponseClassCEF_BaseResponseClass.Inc / .Clw)

Properties

Property Description

Methods

Method Description
GetCommand
GetError
GetErrorMessage
GetId
CEF_BaseResponseClass

GetID

GetID()

Description

This method returns the ID of the response.

Return Value

A Long, the ID of the response.

See Also

CEF_ScriptResponseClass

GetExceptionLineNumber

GetExceptionLineNumber()

Description

If this object was passed into OnScriptFailure then this method returns the line number, of the JavaScript, that triggered the error.

Return Value

A Long

See Also

Calling A JavaScript Function with a Return Value.

Classes

CEF_ScriptResponseClass

This class is passed as a parameter to the CEF_Class OnScriptResponse and OnScriptFailure methods. Inside those methods the properties, and methods, of this class can be used.

Derivation

  • CEF_ScriptResponseClass (CEF_ScriptResponseClass.Inc / CEF_ScriptResponseClass.Clw)

Properties

Property Description

Methods

Method Description
GetExceptionLineNumber Returns the line number, in the JavaScript, of the error that caused the JavaScript to fail.
GetValue Returns the value as a string
GetValueType Gets the actual return type
GetBoolValue Gets the actual value, as a long, if the actual return type was a BOOL.
GetIntValue Gets the actual value, as a long, if the actual return type was an INT.
GetUintValue Gets the actual value, as a ulong, if the actual return type was a UINT.
GetDoubleValue Gets the actual value, as a real, if the actual return type was a DOUBLE.
GetStringValue Gets the actual value, as a StringTheory object.
CEF_ScriptResponseClass

GetExceptionLineNumber

GetExceptionLineNumber()

Description

If this object was passed into OnScriptFailure then this method returns the line number, of the JavaScript, that triggered the error.

Return Value

A Long

See Also

Calling A JavaScript Function with a Return Value.

CEF_ScriptResponseClass

GetValue

GetValue()

Description

Returns the value returned by the JavaScript, as a string, regardless of the type returned by the JavaScript. tis value can then be assigned into any appropriate Clarion data type.

Return Value

A string.

See Also

GetValueType.

CEF_ScriptResponseClass

GetValueType

GetValueType()

Description

Returns the data type, of the value returned by the JavaScript.

Return Value

A string, one of CEF:SCRIPTVALUETYPE:BOOL, CEF:SCRIPTVALUETYPE:INT, CEF:SCRIPTVALUETYPE:UINT, CEF:SCRIPTVALUETYPE:DOUBLE, CEF:SCRIPTVALUETYPE:DATE, CEF:SCRIPTVALUETYPE:STRING, CEF:SCRIPTVALUETYPE:NULL, CEF:SCRIPTVALUETYPE:UNDEFINED, CEF:SCRIPTVALUETYPE:OBJECT, CEF:SCRIPTVALUETYPE:FUNCTION.

See Also

GetValue.

CEF_ScriptResponseClass

Get-----Value

GetBoolValue(*LONG p_Value)
GetIntValue(*LONG p_Value)
GetUIntValue(*ULONG p_Value)
GetDoubleValue(*REAL p_Value)
GetStringValue(*STRINGTHEORY p_Value)

Description

Returns the value returned by the JavaScript as a specific type.

Parameters
Parameter Description
p_Value A variable to receive the actual value
Return Value

Returns CEF:Ok if the JavaScript value matches the specific version of this call. Returns CEF:NotOk if the Type returned, and the call, do not match.
See Also

GetValueType,GetValue.

Trouble Shooting

1. Any of the following warnings during compiling;
Your RED file has not been set correctly.

22. The following warning during compilation

ChromeExplorerProcess.Exe was not copied to the target directory because it could not be found via redirection lookup

Compile the project which is in \clarion\accessory\ChromeExplorerProcess
See ChromeExplorerProcess.Exe

3. Program does not start. Debugview Shows something like;

FATAL:v8_initializer.cc(176)] Failed to open V8 file 'C:\Clarion11\Examples\ChromeExplorer\ABC\natives_blob.bin' (reason: -4)

The necessary BIN and PAK files are missing from the application directory. See Shipping / Distribution.

4. Program does not start. Debugview shows something like;

[ERROR:icu_util.cc(183)] Couldn't mmap icu data file

The necessary DAT file is missing from the application directory. See Shipping / Distribution.

5. Program starts, but displays message "ChromeExplorerProcess.Exe is missing".

The necessary EXE file is missing from the application directory. See Shipping / Distribution.

6. Program Starts, but controls do not display. Debugview shows something like;

ERROR:browser_gpu_channel_host_factory.cc(138)] Failed to launch GPU process.

ChromeExplorerProcess.Exe is missing from your application folder. See Shipping / Distribution.

7. Program starts, but when opening a control you see

ChromeExplorerProcess.Exe or one of it's DLL's was linked to a Clarion RTL Version older than xxx.

Rebuild ChromeExplorerProcess.Exe. See Shipping / Distribution.

8. When Right-Mouse clicking on the control, a blank popup appears.

The Locales folder is missing. See Shipping / Distribution..

9. When Right-Mouse clicking on the control a popup in the wrong language appears.

You can set the "Locale" of the browser using the Global Template option. See Locale.

10. When running the program, the following error message appears.

Procedure entrypoint SymFromAddr not found in DLL-library libcef.dll

Look for a file in application folder called DbgHelp.Dll and delete it.

Version History