Review
	Reviewed by Tom Hebenstreit

CapeSoft File Explorer v2.1

Information comes packaged in many forms, and for raw database access Clarion is an awesome tool. Quite often, though, I find myself wanting to incorporate other "pre-packaged" bits of information into my programs as well. By that I mean information in other common file formats such as HTML (web pages), PDF (Adobe Acrobat), WAV (audio), AVI (video) or even advanced formats like Macromedia Flash animations. All offer features well beyond the usual static display that the average Clarion program exhibits, and give you an enormous amount of flexibility in presenting information in a more forceful manner.

Tutorials, demos, sales tools, wizards, program help - all can benefit from an infusion of dynamic or pre-formatted content. Also, by using these common file formats you have a lot of freedom in choosing the tools you use to create the files to display. Even better, most of the programs associated with these file formats also provide OCX/ActiveX/OLE viewer controls that other programs can access. Yes, even Clarion.

The primary obstacle to using these OCX controls in the past, though, has been the poor level of Clarion OCX/ActiveX/OLE support. That and the daunting amount of research and tinkering it takes to figure how to actually implement a given ActiveX control in a Clarion program (unless you are like Jim Kane and like to program in Assembler just for grins).

With the arrival of the much more stable Clarion 5.5, though, longtime Clarion third-party vendor CapeSoft now had the platform they needed to solve the second half of the puzzle – making the use of those controls template-based and hence, easy.

Major Features

File Explorer lets you incorporate the following types of files and features into your programs:

• HTML (View only). The common language of the World Wide Web, HTML files can be loaded either from the local hard drive or from the Internet (or both, via hyperlinks). Templates are provided to let you put common ‘browser’ type buttons on your HTML viewing window (back, forward, print, stop refresh and so forth).
• HTML (Edit). In addition to the view-only control, you can do many basic HTML editing tasks with File Explorer as well by using a more advanced control.
• View PDF files. View, print, zoom and find are all available (and more).
• Play sound files in the MP3, Wav, Snd, Au, MID, M3U and MPE formats.
• View video files in the MPEG, MOV, AVI WMV or QT formats.
• View Macromedia Flash animation files.
• Either specify files to display via program code or let the user choose.
• Advanced programmers can register callback functions and/or access all of the methods and properties supported by any of the controls (many more than the template prompts can provide).
• Multiple controls can be placed on the same window, so you could, for example, play audio instructions while the user browses a web file.
• And more…

File Explorer supports Clarion 5.5 only, 32-bit, ABC and Legacy. It is pure template code and does not have any DLLs.

Installation

CapeSoft’s installers follow the Clarion 3^rd Party Association guidelines for install programs (as you’d expect, since they helped to define the standards), and as such there is not a whole lot to say about the File Explorer setup. It located the correct Clarion folders, registered the templates, offered to do the requisite editing of the redirection file, added shortcuts to the documentation to the IDE Accessories/Help menu, and displayed the help file at the end of the install.

Click, click, click, click, click, done. Just the way I like it.

Implementation

In a nutshell, File Explorer is a toolbox full of template wrappers. The main document control template wraps around a variety of specialized OCX/ActiveX/OLE controls from other vendors such as Microsoft, Adobe or Macromedia and provides you with a simplified method of using them in your Clarion programs. You don’t have to get down and dirty messing around with the Clarion OLE layer or wade through reams of documentation on obscure properties and methods (unless you like doing that sort of thing). For the most part, using File Explorer is a matter of dropping a control template onto a window and then filling out a few prompts.

It is important to note that these OCX controls do not come with File Explorer. Many are provided either with Windows (the multimedia viewer used for audio and video files, for example) or as part of other common programs (the PDF viewer OCX is installed automatically when the free Adobe Acrobat Reader program is installed.) The key point is that if, for example, your program displays PDF files, and the machine where you want to run your program does not have the Acrobat Reader installed, that portion of your program will not work.

So, a word to the wise: If your program will rely on a particular OCX, it would be smart to either include the tool itself with your own program installs (e.g., the free Acrobat Reader setup program) or provide your users with clear instructions on how to obtain it (e.g., downloading the Flash viewer.)

On to implementing File Explorer…

After you add a global extension, most other File Explorer functionality is as easy as creating a Window procedure and then dropping the viewer control onto it. You then check the box (or boxes) for the types of files you’d like the control to display, maybe set a few more options, and that’s about it.

Figure 1. Selecting the file types a viewer can handle



Figure 2. Advanced options for generating embeds or

If you want buttons to control the viewer (play/pause/stop buttons for audio/video, browser buttons for HTML, etc.), you can just drop on the appropriate File Explorer control template onto the window as well.

Figure 3. The HTML viewer control in action, browsing a portion of the CapeSoft web site (the file listed at the top was the original local file I loaded)

Even if you don’t place the optional navigation controls on the window, you still get whatever native right-click support the control offers (going back to the previous page in a web browser, for example).

One of my tests was on a Clarion 5.5e, ABC, multi-DLL program. I wanted to use HTML pages to display information about various portions of the program when it was in demo mode. Using the HTML viewer, I found it very easy to load just one local page, and to have all of the other local pages (six in all) linked to each other so that the user could easily read related information. And what if they wanted to print the HTML pages? Easy – I dropped on the File Explorer Print button control template. No muss, no fuss, no embedded code.

Having the HTML pages external to my program meant that it was a snap to edit them on the fly and instantly view the results inside my program. I could also put ‘mailto:’ links in my HTML pages (these bring up the users email program), and even links to websites out on the Internet.

One tip I’ll share here: I found that the viewer in my program usually didn’t have enough screen real estate allocated to it to be able to do justice to other web sites (see Figure 3 - most web pages are designed for 800x600 now days). By placing the optional target="_blank" parameter on links that left my local pages and went to actual web sites, I caused those pages to pop up in a full-blown Internet Explorer browser. Meanwhile, my own local pages stayed within my program. Here what an external link might look like:

<a href=http://www.site.com/page.html 
 target="_blank">Go to my site</a>

Performance

I found the performance of File Explorer to be very good, in so far as it can go.

What do I mean by that? Remember, since File Explorer basically just wraps around the other OLE controls, your performance will really be based on two factors: 1) the stability of the C5.5 OLE layer, and 2) the stability and speed of code from Microsoft, Adobe, Macromedia or other vendors. Assuming Clarion 5.5 is stable (knock on wood!), then if another vendor puts out a flaky control there is not a whole lot CapeSoft can do for you.

That said, CapeSoft has built-in several options to help "stabilize" some of the more, shall we say, nervous controls such as the Microsoft HTML1 viewer (the read-only one). In reading the documentation and experimenting myself, I was impressed with how some of their workarounds helped make the OCX more stable on various platforms.

The other caveat is that, like most programs, newer versions of the controls tend to work better than older versions and, in some cases, old versions of the controls just don’t work at all. CapeSoft does help out by listing the preferred minimum versions in the docs, and which ones work best.

I did run into one major stumbling block in my use of File Explorer. In the course of upgrading from an earlier version to the latest one, the file type for a Print button for my viewer control got out of step with the viewer control itself. With the print button set to html2 (the edit control) and the viewer itself set to html1 (the view only control), the app would shift into glacial mode (one small step above totally frozen) whenever I tried to load a document. Since I hadn’t changed any template settings myself it took a while to track this down, but setting the two templates back to the same type did fix the problem.

Lest all of that sound too negative, I want to stress that File Explorer does work, and it works amazing well (this from somebody who has spent some very painful times in the OCX trenches in earlier versions of Clarion). And the ability to use the lightweight yet powerful Flash animation format in Clarion programs is (dare I say it)… way cool.

Documentation

Documentation is provided in the form of an HTML file. I’ve become a major fan of using HTML for documentation – the ability to easily jump from topic to topic, the formatting and graphic capabilities it provides and, last but not least, ease of printing as compared to Windows Help files. By the way, if you want to print the File Explorer document it works out to about 55 pages of solid information.

The docs cover all of the basics: installation, using the templates, examples, FAQ, version history, File Explorer methods and properties, and more. Written in a breezy but informative style, the help is easy to follow and understand.

Three example applications are provided. The first is an extensive demonstration of all the major features and templates (one app for Legacy, one app for ABC), while the other is a simple one-procedure app showing how to display a Flash file full-screen (this app contains exactly one line of embed code). The larger example demonstrates quite nicely that most File Explorer windows can be created with no embedded source code at all.

Technical Support

CapeSoft’s technical support has always been excellent, and did not disappoint this time, either. Questions were fully answered, suggestions were politely received, and support staff were up front in confirming the problem that I mentioned above (and said it would be fixed in the next release.)

The standard support method is email (unless you happen to live in South Africa or like making long distance phone calls.) CapeSoft is also active on the SoftVelocity third-party newsgroup.

Summary

Since it is impossible to capture how dynamic content such as audio, video or Flash animations perform in a static image in a review, I highly recommend that you download the File Explorer demo from the CapeSoft web site (see below) and check it out yourself.

Could you write code yourself to do everything that File Explorer does? Sure, but if you value your time at anything above a buck an hour, you’d be hard pressed to justify the time and anguish you’d go through versus the very reasonable price CapeSoft charges for File Explorer. You wouldn’t get regular free updates and enhancements, either!

Bottom line:

File Explorer is a great way to expand the visual vocabulary of your programs, and offers a lot of bang for the buck. If you want to add any kind of pre-formatted or dynamic content to your programs, it is definitely worth checking out.



CapeSoft File Explorer v2.1 costs US$149, and is available online from https://www.clarionshop.com.
Clarion versions supported: 5.5 or higher, ABC or Legacy, 32-bit programs only.
For more information or to download a free demo of File Explorer, visit the CapeSoft web site at http://www.capesoft.com.