Category Archives: Clarion 9

News, examples and tips on Clarion 9

9.1 and Reg-Free COM

As previously posted 9.1 introduces support for registration-free COM activation.  That simply means that you can deploy your App that uses any COM controls without having to install and “register” the COM control. You simply include the binaries for the COM controls and deploy it with two manifest files; one manifest for your App that specifies the “dependency”, like this example:


After talking about this on Wednesday on ClarionLive we went and added this support to the templates.  It is as simple as this example:


Now the only thing left is for you to create the manifest for your COM control.  There are various tools out there like “Make My Manifest” (link) and “Unattended Make My Manifest” (link), as well as several others, which handle the manifest creation for registration-free COM.

Clarion 9.1

The next Clarion release (9.1) has over a dozen new features, and many bug fixes and changes to improve the RTL and IDE, but two new features stand out above the others.  That is the support of Touch input and  the support for Registration-free activation of COM objects from side-by-side assemblies.

The Touch support is automatic and transparent, no code changes needed — just a rebuild of your app and you have it.  But you also have the option to use an interface to take full control of all the touch events and handle them as you see fit.  We have a few good examples that will show you exactly how to do that.

The Reg-free COM support is also automatic, and likewise requires no change to your code. If the OCX ProgID isn’t found in the OS registry then the RTL looks for a local manifest.  The declaration of the interfaces in the OCX can be placed in either the program’s manifest or in a separate manifest. In the latter case, the program manifest must contain the <dependency>
block with assembly name equal to name of the OCX’s manifest without the “.manifest” extension (this the preferable way).

Tomorrow we’ll be expanding the group of Clarion 9.1 alpha testers, and our goal is to get 9.1 to all 3rd party vendors by the end of the week.  If all goes well within another ~week it’ll move to a general release.



H5 Builder

At CIDC in September we showed a quick demo of an H5 enabled app.  For the details on what the H5 product is all about you can read this;

At the conference I talked about our plans for H5:

H5 will be included with a future C9.x EE.  H5 will be our first Clarion Community open source project.  We’ll be posting the templates and classes onto GitHub so that Clarion developers from around the world can hack, enhance, branch, and generally share their ideas and expertise (working along side our core dev team).  At the conference quite a few of the Clarion devs present indicated they are looking forward to getting involved with the project, and I think there are many more who weren’t at the conference who will join in.

Currently we are refactoring the templates/classes to move each control into separate file(s).  This is a necessary first step to ensure its easy to work on files and get them checked back into the common repository while minimizing conflicting changes.  We expect to open the project on GitHub in approximately 2 weeks.

Template for creating a CLASS in an .App

At the CIDC conference we showed a template (that is already included with C9) for easily creating CLASSes within your APP.
The Help doesn’t yet cover it, (but will in the next update) and it’s very simple to use without any docs. Here are a few screenshots to get you going;

start by inserting a new procedure and then select “Source Class”

if you press the Actions button, you have the option to declare the module as a generic MEMBER() so you can share the class between Apps as needed.  (this option was actually added during the devcon based on feedback during the presentation)


the embed points are pretty much self-explanatory



You may have noticed the other new template Procedure “Generated UserControl Class”. As the name implies that template creates a ‘user control’ which is comprised of a Window and all the controls on it.  We’ll post separately about that one.

REPORTs in the new RTL

Clarion uses Windows metafiles to generate reports since the very first version of Clarion for Windows. A metafile is a sequence of records containing a list of GDI functions and parameters. Metafiles are created in memory and can be written to disk files. The RTL also uses metafiles to handle direct drawing operations like ARC() or PIE() in both WINDOWs and REPORTs. A metafile is a simple way to store drawing operations but there are several issues:

  1. Windows metafiles do not support all GDI functions used for drawing. For example, images with semi-transparent parts cannot be stored in Windows metafiles.
  2. Reports are sequences of bands and bands consist of controls and can be nested. Multiple drawing operations can be required to draw individual controls. For example, multiple lines and multiple strings must be drawn for LIST controls. Reports are best represented as a tree structure, and metafiles with their linear organization are not an easy/adequate way to represent them.
  3. The RTL must carefully track images, pens and fonts used in metafiles to avoid leaking of resources.

Problem (1) can be solved by use of Enhanced metafiles (EMF) instead of Windows metafiles (WMF). But other problems exist for both types of metafiles. The RTL must enumerate metafile records every time some delayed action needs to be executed, for example when processing widow/orphan settings to find end of page. The RTL inserts additional records into metafiles to mark logically related records and assist in enumeration and parsing both during report generation and during conversion metafiles to text/PDF/XML/HTML format.


The new RTL won’t use metafiles for direct drawing operations or during report generation. Instead it will produce a dynamic tree structure matching the Report with a sequence of drawing operations. Every tree node is a class instance derived from the MetaNode class:
MetaNode       CLASS,TYPE
Next             &MetaNode
Bounds           LIKE(RECT)
Flags            ULONG
Custom1          LONG
Custom2          LONG
Draw             PROCEDURE (LONG context),VIRTUAL

ContainerNode  CLASS(MetaNode),TYPE
Nested           &MetaNode

PageNode       CLASS(ContainerNode),TYPE
Print            PROCEDURE (HDC, ULONG skipmask)

IndirectNode   CLASS(MetaNode),TYPE
Actual           &ContainerNode

There are 3 categories of nodes:

  1. Nodes with information to execute a direct draw operation or to draw a control. A Nodes’ classes have fields for all values required to perform both drawing and post-processing: fonts, colors, pen style and width, value of the EXTEND attribute, etc.
  2. Container nodes used for referencing a list of nested nodes.
  3. Indirect nodes referencing some Container node.

The container node class for a report page has a function to start drawing or printing. The call to this function initiates iteration of the page sub-tree and calls the Draw method for every node. This approach provides a very easy method to get a page in any required form:

  • If the HDC parameter is a handle to a screen device context (DC), the page contents are drawn on screen.
  • If the HDC parameter is a handle to a printer DC, the page contents are sent to the corresponding printer.
  • If the HDC parameter is a handle to an Enhanced metafile DC, an .EMF file with the page’s image is generated.
  • If the HDC parameter is a handle to a Windows metafile DC, a .WMF file with the page’s image is generated.


The skipmask parameter of PageNode.Print function is used to filter which nodes to print/draw. If the value of the expression

BAND (node.Flags, skipmask)

is not 0, the node (and all nested nodes for container) are not drawn.  Filtering nodes can be used in multiple ways, for example to exclude some pages from printing, or to show the document form at preview time but not print it without needing to re-generate the report. The program can set its own flags in high WORD of the node’s Flags field (low WORD is reserved for Clarion internal use). The program also can use node’s Custom1 and Custom2 fields to store any useful data associated with that node.

Position of nodes corresponding to bands (FORM, HEADER, FOOTER, DETAIL, BREAK) is calculated relative to the page origin. Position of controls is calculated relative to the origin of the band they belong to. This allows us to have “references to containers” implemented by indirect nodes. Upon drawing/printing an indirect node the RTL uses its position, flags, custom data and a list of nested nodes of the container it points to. Indirect nodes are used internally to handle the FORM band, which is shared by all report pages. But a program can use them in other ways, for example to merge several short reports to print them on the same page, or to print a number of copies of specific pages.



The new internal organization for Reports retains complete backward compatibility with the current and prior versions of the RTL because WMF files can be easily generated for every page.  But it opens the door to numerous potential enhancements:

  1. Faster report generation by eliminating the need for repeated re-scanning of metafiles to merge them or to find the point of a page break.
  2. Easier conversion of reports to formats other than WMF and EMF by elimination of the need to parse the WMF file to reconstruct the structure of the report in another format.
  3. Easier after-generation modification of reports, for example placing the correct total number of pages to “Page n of N” text.
  4. The possibility to have report pages with multi-layered contents and then selecting the desired layers at preview time.

WINDOWs in the new RTL

To distinguish between Clarion WINDOW and APPLICATION structures, and Windows OS User objects, the following text uses upper-cased WINDOW for Clarion structures and a lower-case italic font for User objects: window.

Every window  has 2 logical areas:

  • Client area – rectangular part of window surface where window contents (controls) is drawing. The client area can be empty, e.g. for iconized windows.
  • Non-client area – part of the window’s surface outside the client area. The non-client area can be empty if the client area is equal in size to the entire window rectangle.

Windows uses the non-client area of a window to draw the border, caption, menubar and scrollbars, if any. Because modern window styles assume usage of additional informational and control elements, for example toolbars or status bars which can be created/destroyed at run time, Clarion uses 2 or more windows to implement WINDOW structures:

  • Non-client window (mandatory)
  • Client window (mandatory)
  • Toolbar (optional)
  • Site windows for dockable toolboxes (optional)
  • MDI Tab bar (in APPLICATIONs, optional)


The term non-client part indicates the non-client window of a WINDOW/APPLICATION structure, and the term client part to indicate the client window area.

Non-client part of WINDOW


The non-client part of WINDOW can contain:

  • Caption
  • Border
  • Menubar

All elements are optional depending on the actual WINDOW declaration.

The client area of non-client part of WINDOW can contain:

  • Toolbar
  • Status bar
  • MDI Tab bar (for frame WINDOWs)
  • Docking site spaces

The non-client part is a parent window for the client-part.

The non-client part determines the position and dimensions of WINDOW:

  • Coordinates of the upper-left corner of the non-client part are position of WINDOW.
  • Width and height of the client part are the dimensions of WINDOW.

The Windows OS (not the RTL) deals with the non-client part to move, size, change position in Z-order, activate, maximize, restore, iconize and hide/unhide WINDOW.

Implementation of WINDOW structures in the RTL

Implementation of WINDOWs in the RTL follows their (user) declared structure. In both the current version (C9) of the RTL, and all previous versions, the RTL considers non-client and client parts as a united object.


Schema of implementation of WINDOWs (APPLICATIONs have additional elements)

The Clarion RTL creates the entire WINDOW including window objects for non-client and client parts, toolbar and other elements in the thread where the program executes the CREATE statement for that WINDOW. Because Clarion does not allow creation of MDI child WINDOWs in the Frame’s thread, the RTL uses the CreateMDIWindow API function to create the non-client part of WINDOW. The CreateMDIWindow function has been listed as one of benefits of 32-bit Windows in comparison with earlier 16-bit Windows 3.x versions because it can create an MDI child window in a different thread other than one running the frame window. But the real life implementation of the MDI API in Windows OS is not thread safe. Therefore simultaneous activity of several MDI child windows running in their own threads will eventually cause an inconsistent state of the Windows OS internal structure containing MDI-related information and, consecutively, incorrect functioning of both the MDI frame and MDI child windows in multiple ways.

Since Clarion 6 was introduced and the problems with MDI were discovered huge efforts have been made to hide them for MDI child WINDOWs in Clarion. Unfortunately, there is no complete solution without changing of the internal structure of WINDOWs. The new Clarion RTL will use a new implementation of WINDOWs. The main change is that the non-client and client parts will be strictly separated.


Changes in the WINDOW structure provide several important benefits:

  1. The non-client part and the client part of the same WINDOW can be created in different threads. Specifically, the non-client part of an MDI child WINDOWs can be created in the Frame’s thread. This solves all the problems caused by the thread-unsafe implementation of MDI in Windows. All the code added to the RTL to work around these problems becomes unnecessary and can be removed. This makes the RTL far more manageable and extensible.
  2. The client part of WINDOWs with or without the MDI attribute is absolutely identical and is very close to the toolbar. There are a few minor differences, e.g., the client part of a WINDOW can be scrollable and setting focus to a toolbar’s controls is handled in special way.  This allows us to share most of the code for the client part and for the toolbar.
    1. The separate client part can be “glued” to any rectangular area within the bounds of the client area of the non-client part of any WINDOW, for example, to a TAB control. That means the client part can be used as a compound custom control. It can be created multiple times, and every copy can be “glued” to different places without the necessity to duplicate the code. Implementation of such user-defined control could be coded as a class with a method to declare a client-part-only WINDOW and run it’s ACCEPT loop and methods to set or query values of any USE variables.  Dockable toolboxes can be re-implemented in this same way.  Probably, a new keyword will be added to the language for declaring client-part-only WINDOWs. The host WINDOW would provide a simple interface to inform the “glued” object about events like resizing. The functionality of REGION controls could be extended for handling that implementation. Alternatively we could introduce another new keyword for areas where client-part-only WINDOWs can be “glued”.
    2. The common part of a WINDOW object is created upon entry to the scope where a WINDOW is declared is the same for WINDOWs with and without the MDI attribute. This allows the possibility to change the type of non-frame WINDOWs at run time before opening them.


C9 gold release!

C9 went into pre-release in the beginning of May.  Now almost 20 weeks and 9 beta releases later, we are ready to release the official gold version.
The next (gold) release has some additions and touch-ups in the docs, and a couple more fixes for recently found (important) issues.  We project a release date for this coming Monday (9/23)!

There is a lot more coming during the lifetime of C9, including new support for Touch gestures, the H5 project, a new Topscan, and much more.  Additionally we have some big projects in the works which I have posted about today, and I’ll be going into the details of those projects, and other upcoming features at the upcoming DevCon in Orlando next week.

Clarion projects – Window structures in the RTL

Clarion projects – Window structures in the RTL

The following is excerpted from an MS KB article:
The Microsoft Platform Software Development Kit (SDK) documentation for the CreateMDIWindow function says that “(u)sing the CreateMDIWindow function is similar to sending the WM_MDICREATE message to an MDI client window, except that the function can create an MDI child window in a different thread, while the message cannot.”

Applications that use the CreateMDIWindow function to create a multiple-document interface (MDI) child window on a thread other than the thread that owns the MDICLIENT window may experience problems with the way that MDI manages the client windows. The following problems may occur:

  • – The list of windows on the frame’s window menu may not be complete.
  • – The management of the MDICLIENT scroll bars may not be consistent when you move or size MDI child windows.
  • – The keyboard cannot be used to move between the menus in the frame window and an MDI child window.

RESOLUTION To resolve this problem, applications should not call the CreateMDIWindow function to create MDI child windows on a thread other than the thread that owns the frame window and the MDICLIENT window (emphasis added).

So there you have it. MS doesn’t want or support multi-threaded MDI programs at all.  In fact the .Net runtime displays an error message if you even try to open a window on any but the programs main thread. We have spent literally hundreds of man-hours trying to make MS MDI behave in a multi-threaded program. We know the real life implementation of the MDI API is not thread safe, and never will be. To workaround this deficit we have encumbered the RTL with synchronization code to try to mitigate the OS level problems. I say encumbered; (restrict or burden (someone or something) in such a way that free action or movement is difficult) because that best describes the situation. The extra code we were forced to add restricts our ability to add new functionality, without risking breaking the MDI synchronization sequence we spent so much time on making it work.  So to move forward we have a project underway that will allow us to remove the burden of the synchronization objects, solve all of the above listed MDI issues, and best of all, allow us to add new functionality with 100% backward compatibility.

At next weeks DevCon I’ll be going into the details of what we are doing to solve this issue once and for all, and describing the exciting new abilities that it will bring to Clarion programs.

Clarion projects – Report Engine

Clarion projects – Report Engine

The Clarion Report engine ( the engine in the RTL) has been evolving since it was first implemented in the original Clarion for Windows back in the W95/98 days. Its uses Windows metafiles to generate Reports. Metafiles are created in memory and are written to disk files. The RTL also uses metafiles for direct drawing as in ARC() or PIE() both REPORTs and WINDOWs. A metafile is a simple way to store drawing operations but there are several limitations:

Windows metafiles do not support all GDI functions, for example, images with semi-transparent parts can’t be stored in Windows metafiles. Reports are actually sequences of bands. Bands consist of controls and they can be nested. Multiple drawing operations can be required to draw controls. For example, multiple lines and multiple strings must be drawn for LIST controls. Reports are actually represented internally with a tree structure, and metafiles with their linear organization are not really an adequate way to represent them. The BLANK statement with parameters makes it necessary for the RTL to insert some additional records right in the middle of the metafile. The RTL must also carefully track images, pens and fonts used in metafiles to provide a correct representation of the report, and to avoid leaking of resources.

At the upcoming DevCon in Orlando I’ll be talking about (the details) of how we plan to solve these types of issues, and at the same time bring brand new capabilities to your reports. And as we always strive to do – maintain 100% backward compatibility.

Clarion Projects – Touch support in the RTL

Clarion Projects – Touch support in the RTL

Touch input affects all Windows (all objects with HWND handles), and all controls. A generalized processing of touch gestures and mouse input requires changes in the hierarchy of classes within the RTL that deal with user interactions. By generalized I mean the ACCEPT loop must recognize and handle all possible “gestures”, and then it needs to decode sequences of WM_POINTER* messages to matching gestures and send them back to the your program in a way that makes it easy to respond to. And further, indirectly Touch support affects some areas that are not related to input at all, for example setting and getting properties.

The RTL also needs to expect that touch/pointer messages can be sent to different windows depending upon where the touch is done, and to windows running in different threads as well.  Clarion programs are typically very thread-intensive, unlike the typical MS VC/VB/C# programs which in terms of use of threads, are diametrically the opposite (the UI is almost always single-threaded).

In other words the implementation isn’t a project for a rainy weekend, instead its a complex melding of current code to recognize
user input, with a brand new set of requirements for touch gestures.

A brief description of some of the functionality being worked on:
– scrolling of LIST control
– Zoom in/out
– touch to press button, toggle checkbox, select radio option
– touch to give focus to other controls
– and others that we are still imagining