Newbie Corner - Tips and Tricks - Using Clarion Help and Online Resources

Newbie Corner - Tips and Tricks - Using Clarion Help and Online Resources - Part 1

by Frank Magistro

Published 1999-04-01 Printer-friendly version

Background

The first time I used Clarion was 3 months ago when I joined TopSpeed's Documentation Team. During that time I've been shown a few "Tips and Tricks" by the development team that I'd like to share with you.

Do you know that you can copy example code from the On-line help and paste it directly into your application?
Do you know that you can position your cursor over a Keyword or an ABC Property/Method while in your Module or Source code and get extensive on-line help?
Do you know that the Context Sensitive Help tool, with functionality built into the Clarion editor, will point out if a Keyword or Language Term is a Language Keyword, Template Construct, or an ABC Method or property?
Do you know that there are many "Helper Applications" Supplied with Clarion?
Do you know you can use Clarion's Menu Editor while viewing code?

Quick Tour

In part 1 of this article we will:

Learn how to locate the many example applications supplied with Clarion.
Explore one of the "Helper Applications", Exampro.
Open one of the Example applications and run it.
View the source code of one of the Example applications.
Use Context Sensitive Help.

Locating the Example Applications

From Clarion's Main Menu, select Help>Contents. You should see the following menu.

Figure 1

If this is new to you, take a few minutes and explore the options on this menu. Press the button labeled "Guide to Examples", this is the third button down on the right side

Select Other Example Programs, then Select CDPlayer. This looks like an interesting application to explore, so let's note the location of this application and open it.

Helper Application - Exampro

Take the time to become familiar with this section of the On-line Help - "Guide to Examples". The example programs are great tools to learn more about Clarion. Later in this article I'll cover some of the helper applications included with Clarion. One of them is the Exampro application, (in Clarion release C5A Exampro has been renamed to Features). Exampro was written by one of my colleagues within TopSpeed's Documentation Group, Steve Trautmann, to assist us with cataloging all the example and test applications we use.

Exampro (Features - rel. C5A) is a tool that assists with the cataloging and organizing of your example programs. You can also use this tool to catalog your own programs. If you want to try it now, it can be found at C:\Clarion5\Bin\Exampro.EXE, (for rel. C5A, it can be found on the Windows Start Menu underStart>Programs>Clarion 5>Tools>Features).

I use this helper application frequently and have created a Window's short cut for it. I keep it on my Window's desktop and you may want to do the same.

Opening an Example Application and Running it

To open the CDPlayer application:

From Clarion's Main Menu, select File>Open and locate the folder C:\Clarion5\Examples\Scr\CDPlayer.
You may notice that the Window's Open Dialog is empty. This is because the application we are trying to open is a hand-coded application. We first need to find the CDPlayer's Project file, which has a file extension of .prj.
On the very bottom of the Window's Open Dialog is the "Files of type:" field. Select Project(*.prj).
Select CDPlayer.prj and open it. Your screen should now look like Figure 2.

Figure 2

When using the example programs as learning aids, I find it very helpful to run the application first. This helps me get a feel for the general way the application performs. If you want to, make and run CDPlayer now and try it out.

Viewing Source Code

On the Project Tree Dialog, select cdplayer.clw. see Figure 3.

Figure 3

Double Click on cdplayer.clw. (or highlight it and press Edit)
Scroll down until you find the line "CDPlayWin WINDOW('Audio CD Player')……..". See Figure 4.

Another method that can be used to locate keywords within a source listing is to select Search>Find. Try it now. SelectSearch>Find and type"Initializeplayer". To getback to where you started, select Search>Findandtype "CDPlayWin".

Figure 4

Using Context Sensitive Help

We are now going to use Clarion's Context Sensitive Help Facility.

Position your cursor over the language keyword SYSTEM, on the line starting with CDPlayWin, and press the F1 key.

Figure 5

Now let's take a look at viewing the Context Sensitive Help for the Clarion Language Keyword "WINDOW". Staying on the same line of code, see Figure 4, position your cursor over the Keyword WINDOW and press the F1 key.

Figure 6

How Do I Know What Help Topic to Select?

Notice that we now have several topics to choose from. How do you know which one to choose? Why are there several choices?

Clarion has the Clarion Language, the Clarion Template Language and the ABC Methods and Properties, to name a few. A term like WINDOW has several uses. Within Clarion, a term can be used as a Language Keyword, used within the Template Language and used as a Method or Property within the ABC Classes.

So how do you know which Topic to select from the Topics Found Dialog? Well, here's a "Tip".

Take a look at Figure 6. One way to easily determine which Topic to select is by knowing TopSpeed's Documentation conventions.

The conventions used are: (see Figure 6)

ALL UPPER CASE = A Clarion Language Keyword - WINDOW(declare a dialog window).
Proper Case = An ABC Method or Property - Window(Window/Manager object).
# or % = Most Template Language Keywords or Statements
#CONTROL(define a control template)
#PROCEDURE(begin a procedure template)

If you remember, earlier we invoked the Context Sensitive Help for the Keyword WINDOW, as it was used within the CDPlayer application. So which Help Topic items do you think we should select. Right, the Help Topic item that is ALL UPPER CASE - WINDOW(declare a dialogwindow).

Before we select the Help Topic item we are interested in, let's take a look at the other Help Topics.

Let's start with the Help Topic Item #CONTROL(define a control template). Select it. You should now have the On-line help text for #Control on your screen. Take a look at the upper right-hand corner of the help screen. You'll notice a gray message box with the words "Template Language"

Now let's try the last Help Topic item - Window(WindowManager Object). Notice on the upper right-hand corner of the Help Screen the text box with "ABC Library". This tells us this is an ABC Method or Property.

So even if you initially selected the incorrect Help Topic, once on the Help Screen, you can easily determine if you are where you need to be. Just determine what convention is used, (UPPER CASE, Proper Case, or starts with a "#"), select the help topic. Look at the upper right-hand corner of the Help Screen. Pretty simple when you know what convention is being used.

Now let's finally get to the information we are trying to get Help about - WINDOW(declare a dialog window). Notice that the Help Screen does not have a text box in the upper right-hand corner of the screen. This signifies that this is a Clarion Language Keyword Statement.

If you are new to Clarion, take the time to review the Help for the Language Statement WINDOW. Compare the help to what was implemented within the CDPlayer application. Run the application. You might even want to copy the example program, and then make changes to your copy to see "what changes" when you modify and run the example program. It's a great way to learn the ins-and-outs of the Clarion development environment. Try it with the other example programs.

So What Have We Covered So Far?

Clarion comes with many example applications. These are valuable learning tools.
Clarion comes with many Helper applications like Exampro, (Features in release C5A).
On-line Help can be used as a tool to learn Clarion.
Context Sensitive Help can be used while you're within an application's source or module code.
Documentation conventions are used to aid in determining the specific Help Topic you need to view, (Language Keyword, Template Language, or ABC Property or Method).

What's Next?

In the remaining parts of this article I'll cover;

Other uses of Context Sensitive Help.
How to copy example code from Help directly into your application.
Describe other Helper Applications.
A tour of Help>Contents.
How to use Clarion's Menu Editor while viewing code.

Note from the Author: If you have any suggestions about how we can improve our User Documentation both contents and organization, please e-mail your suggestions along with a little background about how you are using Clarion and how long you've been using the product. I'm particularly interested in suggestions that would make the User Documentation more effective for new users of Clarion. Please send suggestions to fmagistro@topspeed.com

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942