Clarion 9.1 under the hood - Part 2

Owned by David Harms
Last updated: May 29, 2014Version comment

In Part 1 I had a look at the new files (templates, source, etc.) shipping with Clarion 9.1; now it's time to see what's changed in the existing files. 

Browse changes

The release notes for build 10971 have this note:

FEATURE: Added methods to ABBrowse to enable or disable the showing of the wait cursor in a Browse SetUseWaitCursor(True/False)

In 9.0 when there's a potential delay the code calls SetCursor to show a standard wait cursor. Now you can override this behavior via the supplied methods. 

In abbrowse.clw in 9.0 you'll see these comments:

!The SELF.ILC.Choice() - SELF.ILC.GetControl(){PROP:YOrigin} + 1 expresion
!will be encapsulated in a new StandardBehavior method
!SEL = StandardBehavior.GetSelectedRow()

This change has been implemented; ILC is the IListControl interface, and it now has a GetSelectedItem method. I suppose there's some benefit to this but it's not clear to me what it might be. If you have an idea, please post a comment. 

This change also affects the GridClass, which is supporting code for the BrowseGrid template. 

I have to confess that I've never, ever used the BrowseGrid in anger. The help says this:

The BrowseGrid template provides a group control that is used to define an area (within a BrowseBox) to display controls in a matrix format. The size of the BrowseGrid control and BrowseBox can be manipulated to give the end result of a matrix with one column or many. When this template is added, the BrowseBox control does not display at runtime.

This feature is particularly useful for Web applications, but can also extend the capabilities of desktop applications.

There is a sample app called BrwGrid. Here are a couple of grids from that app:

While there's nothing really new in this sample app, as always when I go trawling through the Clarion code base I find templates and code I think I really should be trying out. 

ABPOPUP.inc shows a new method, which appeared in build 10916:

FEATURE: Added Method to the PopupClass - "EmptyItems" to empty the popup items when needed

Nifty.

There are also new Ask and GetText methods. The new Ask is an overloaded method, apparently in response to PTSS 37601: "In PopUpClass.Ask please support the 3rd parameter that the POPUP command does". The GetText methods matches the SetText method and lets you retrieve the menu text for a specified popup menu item name. 

XML class changes

There are lots of changes in the abprxml.inc and abprxml.clw files. A lot of these seem to be related to the refactoring of an XMLWriter base class out of the XMLGenerator class. 

Window resizing

The WindowResizeClass gets two new methods, WindowResizeBegin() and WindowResizeEnd(). As stated in the release notes these provide notification of the start and end of resizing. 

The window resizing code also shows something I've noticed in other source files - more extensive error trapping and reporting. Asserts() statements now often include the Error() value or some other explanatory text as a second parameter. 

ABUtil

Abutil.inc and .clw contain a variety of utility classes:

  • ConstantClass
  • FieldPairsClass
  • BufferedPairsClass
  • INIClass
  • SelectFileClass
  • TranslatorClass
  • CalendarBaseClass
  • CalendarClass
  • CalendarSmallClass
  • CalendarSmallTouchClass
  • CalendarSmallTouchIconsClass
  • CalendarSmallTouchRegionsClass
  • DynaStringClass

All of these classes are in 9.0 also, and most of them are in Clarion 8, but again it's easy to overlook this code as these classes are all lumped together in one file pair. I think this is just another argument for maintaining a one class per file rule and using a class naming convention. 

There are some changes to these files, mainly involving the movement of some declarations for days of the week from one file to another. 

WindowManager

The WindowManager gets a new ModalEvent method which returns true of the current event is 

WindowManager.ModalEvent          PROCEDURE()
controlId  LONG,AUTO
  CODE
    CASE EVENT()
    OF EVENT:Contracting
    OROF EVENT:Dragging
    OROF EVENT:DroppingDown
    OROF EVENT:Expanding
    OROF EVENT:GainFocus
    OROF EVENT:Iconize
    OROF EVENT:LoseFocus
    OROF EVENT:Maximize
    OROF EVENT:MouseIn
    OROF EVENT:MouseOut
    OROF EVENT:Move
    OROF EVENT:PreAlertKey
    OROF EVENT:Restore
    OROF EVENT:Selecting
    OROF EVENT:Size
    OROF EVENT:TabChanging
      RETURN TRUE
    OF EVENT:ScrollUp
    OROF EVENT:ScrollDown
    OROF EVENT:PageUp
    OROF EVENT:PageDown
    OROF EVENT:ScrollTop
    OROF EVENT:ScrollBottom
    OROF EVENT:ScrollTrack
    OROF EVENT:ScrollDrag
      controlId = FIELD()
      RETURN CHOOSE(controlId{PROP:IMM})
    END
    RETURN FALSE

This looks quite interesting, but I'm really wondering why I need to know if an event is modal. Anyone have an idea about this one? 

ClaRunExt.dll/inc/clw

There are some changed and new prototypes in ClaRunExt.dll. The image manipulation functions (image to PNG, rotate/flip, and save thumbnail) take pointers to strings instead of cstrings for the filenames, and there are two new functions for sending email and SMS messages. There's also some interesting use of function pointers here that looks worth investigating. 

CWUtil.inc

CWUtil.inc has a new HasTouchInput() function, presumably to determine if the device running the program supports touch inputs. 

EFocus.inc/clw

There are two classes in EFocus, EnterByTabClass (unchanged from 9.0) supports the use of Enter to complete fields (typically for heads-down data entry) and EnhancedFocusClassType, which adds visual indicators of field focus and gets some touch support, including the ability to set an on-screen keyboard for touch devices. 

Equates and properties

There are some new time equates:

! Special time values
TIME:MIDNIGHT           EQUATE (1)
TIME:NOTIME             EQUATE (0)
TIME:ERROR              EQUATE (-1)

which are Mike Hanson's fault. And I need to get Mike in here to explain the current state of SoftVelocity's attempt to handle the time inconsistencies Mike pointed out, and why the attempted fix caused so many problems. 

There are also some groups for 64 bit integer handling:

! 64 bits integers
  OMIT('***',_BUILTIN_I64_)
INT64    GROUP,TYPE
lo         ULONG
hi         LONG
         END
UINT64   GROUP,TYPE
lo         ULONG
hi         ULONG
         END
! ***

There are some new properties as well:

PROP:Locale           EQUATE(7A76H)  ! integer: SYSTEM or FILE LCID value
PROP:Codepage         EQUATE(7A77H)  ! integer: SYSTEM or FILE codepage value
PROP:NoFont           EQUATE(7A78H)  ! boolean:
PROP:TouchInterface   EQUATE(7A79H)  ! integer: get the interface to touch input
PROP:TimeZeroIsLongOne EQUATE(7A7AH) ! boolean: set how TIME(0) to LONG conversions are handled

I'm puzzled by PROP:NoFont, which I don't see in the help, nor does it seem to be used anywhere in the source or templates. 

InternetConnect files

InternetConnect is a mostly-forgotten technology used to present Clarion apps across the internet. Some of that code is being repurposed for SoftVelocity's upcoming H5 product. There definitely are some changes in the IC*.* files in 9.1, but how significant those changes are I don't know. If anything there is less IC code in 9.1 than in 9.0, so perhaps the current work is being done elsewhere. 

JSON support

The ClarionSharp blog entry on H5 contains this mention of JSON:

H5 apps use the jQuery library, either jQuery UI or jQuery Mobile (UI), and JSON for updating client side data without a full page refresh.  They run under the AppBroker SE, so you just install the service and deploy — no IIS knowledge required.

JSON stands for JavaScript Object Notation, and is a simple data format with a wide variety of uses. You can find out more at http://www.json.org/. 

As with XML, there is a growing need in Clarion apps to easily convert to/from JSON structures. JSON support is already in Clarion 9 in the form of JSONDataClass, but 9.1 adds a number of new methods for conversion, data formatting and string parsing. 

QuickXmlParser.inc/clw

The XMLParser and XMLFileParser classes have a few changes, among them the addition of some tracing code using OutputDebugString. Having worked with XML extensively over the last few months I'm sure that code was added out of necessity. 

As with a lot of things buried in the Clarion source code, these classes look like they could be quite useful on their own. 

WinExt.inc/clw

This WindowExtenderClass is heavy on system tray functionality but adds some other nice bits. The IsInstancerunning and RestoreInstanceRunning functions now have optional process name parameters:

IsInstanceRunning           PROCEDURE(<STRING processExeName>),LONG !Return the instance running other than this one
RestoreInstanceRunning      PROCEDURE(<STRING processExeName>),BYTE !If the process is ommited it refere to the current process name returned by GetEXEFileName() processExeName must be Filename.Ext

All those classes

All those classes I hadn't noticed before (or thought about for a while) made me wonder just how many classes ship with Clarion. See the list here.

Next time

That's all for this edition. Next time I'll conclude with a look at the template changes, and I'll list what I consider the most interesting items from the release notes.