Customizing Clarion5's Editor And Menus

by John Morter

Published 1999-07-13    Printer-friendly version

In a recent Clarion Advisor article Bruce Wells explained how to go about configuring the colour highlighting used by the Clarion 5 Editor. I'm going to take this general concept a bit further and show you other ways to personalise your working environment.

A Custom IDE Menu

A simple, but very useful feature provided by Topspeed lets you add user defined choices to the Clarion IDE application frame menu. For example, I've added a Utilities menu to the IDE that gives me handy access to various commonly used applets. My own Utilities menu now fits in neatly between the standard File and Project menus, as you can see in Figure 1.

Figure 1. A custom Utilities menu.

Here's how you can create a menu to suit your own requirements:

Step 1. You're about to modify the CLARION5.INI file, so the strongly recommended cautious approach is to make a copy of the original file first - just in case. (I always do this by creating a duplicate of the file, replacing the last character of the file extension with an underscore. In this case, creating CLARION5.IN_ )

Step 2. Open CLARION5.INI, which you'll find in your BIN folder, with the text editor of your choice and search for the section headers [User Menus] and [User Applications] where the square brackets are part of the section header construct.

The [User Menus] section provides the descriptive part of your new menu. For example, the [User Menus] section of my CLARION5.INI file is shown in Listing 1. You can readily see how this matches with the result in Figure 1.

Listing 1. The [User Menus] section of my C:\CW5\BIN\CLARION5.INI file.

[User Menus]
_version=41
1=&Utils/&DCT Sorter|DctAS
2=&Utils/&App.Launcher|Lnchr
3=&Utils/&Msg Maker|MakeMsg
4=&Utils/&Icon Works|IconPro
5=&Utils/&Class Viewer|CallTree
6=&Utils/Class &Browser|ClsBrwsr
7=&Utils/&Report Writer|CWRW

Before you go any further, note the line immediately beneath the section header. This is some sort of magic number used by TopSpeed for some sort of under-the-bonnet reason. Don't be tempted to fiddle with this number - just leave it as it is. (You'll find that the standard contents of this section in CLARION5.INI consists only of the first two lines above, and the magic number does change between Clarion versions.)

&Utils is the menu name which will be merged in with the IDE menu, using the standard Clarion convention of identifying the accelerator key character with an ampersand.The leading numbers simply differentiate the menu items within Utils.

The next parameter is the name of the menu item within the Utils menu, again using the ampersand prefix convention to identify the accelerator key.

The last parameter provides the link between this section and the [User Applications] section, which I'll look at next.

But first, go ahead and edit in your own user defined menu. You might like to have handy access to Le Schmoo's Class Browser (highly recommended) or to a Calculator or Calendar utility - or whatever!

Step 3. Now take a look at the [User Applications] section. The standard content of this section in CLARION5.INI is shown in Listing 2.

Listing 2. The default [User Applications] section of CLARION5.INI.

User Applications]
_version=41
CWRW=c5rw %f %a

The same rule applies for the magic number line - don't mess with it!

The line starting with CWRW is a hint from TopSpeed, and shows some of the more advanced features available to you in customising your own menus. The %f is an expansion macro; it will be replaced with the file and path-name currently opened by the IDE. Similarly, the %a is another expansion macro which will be replaced by the current Application or Project name. (See the C5-PG.pdf for more details of these and other expansion macros.)

As I mentioned earlier, the last parameter on lines within the [User Menus] section provides a link with the contents of the [User Applications] section. See my [User Application] section (Listing 3) to understand this better.

Listing 3. The [User Applications] section of my C:\CW5\BIN\CLARION5.INI file.

[User Applications]
_version=41
DctAS=C:\CW5\Utils\DctAS.exe
Lnchr=C:\CW5\Utils\Lnchr.exe
MakeMsg=C:\CW5\Utils\Make_Msg.exe
IconPro=h:\WinUtils\IWPRO\IWPro.exe
CallTree=C:\CW5\Bin\CallTree.exe
ClsBrwsr=C:\CW5\Utils\ClsBrwsr.exe
CWRW=c5rw %f %a

I'll use the second last line of this example to explain what's going in. (It's pretty simple, and you're probably all way ahead of me by now - but I'm gunna be pedantic!)

ClsBrwsr provides the link between the two sections. It tells the [User Menus] section where to find the executable identified in that section as Class Browser.

Notice that I've picked up on TopSpeed's hint to call the Clarion Report Writer by creating a menu item in [User Menus] which links with the CWRW line provided in the [User Applications] section.

Step 4. That's all there is to it. Now save your changes to CLARION5.INI, restart the C5 IDE and make use of your nifty new menu items.

TIP: If changes you've made to your CLARION5.INI file are not reflected in the IDE menu then you'll need to give CLARION5.exe a bit of encouragement to recognise your work. The IDE is not actually reading your CLARION5.INI file each time it starts. Instead, whenever it detects a change in various configuration files it summarises all this stuff into a file named CLARION5.DAT - and it reads that file instead. You can safely delete the CLARION5.DAT file to force its recreation, this time with your CLARION5.INI file changes included.

If the idea of deleting this file makes you a little uneasy, then take the just in case approach again and rename it to CLARION5.DA_ instead. (To be honest, that's what I always do!)

Customised Editor Commands

If, like me, you've been around for a while in the programming game then it's quite likely that, like me, you've got the commands of a favourite text-editor built into your finger-tips, if not into your brain.

For me it's an old Data General editor from my dim, dark, past COBOL programming days. For others it may be WordStar or the XTGold editor, or something else that you've used happily for years - whatever!

I'll show you now how you can influence Clarion5 with flavours from your old favourite text editor. (And, once again, it's pretty simple, once you know how.)

Step 1. This time you'll be working with C5EDT.INI, which you'll find in your BIN folder. Again, I recommend you start out by taking a just-in-case backup copy before making any changes.

When you open C5EDT.INI with your favourite text editor you'll find something like the following, (actually, probably exactly like the following).

Listing 4. Contents of the standard C5EDT.INI file.

[Text Editor Configuration]
_version=43

[Key Mapping]
CharLeft=LeftKey

I'm sure you've got the message by now - don't mess with the magic number line!

The lines listed within the [Key Mapping] section have the general format of ...

  Edit-command-effect =
    Keyboard-combination [;   Keyboard-combination ...]

For example;

  CharLeft=LeftKey

means;

"To move the cursor left one character" = "Press the Left (arrow) Key"

Step 2. Have a look at the entries in this section. Even if you don't intend to change the way the Clarion5 editor works, you'll still likely discover lots of useful keyboard commands you didn't know about, (and which aren't documented elsewhere!).

Step 3. Assuming you do want to put your own stamp on the way the Clarion5 editor works, then there are some important things you need to keep in mind:

There are certain keyboard combinations that are built right into the Clarion5 editor or are part of the standard Windows convention set. You are strongly advised not to redefine these for your own use. At best they may not work; at worst you may get some very confusing results.

Fortunately, there are not many of these. I've included a dummy section header at the top of my C5EDT.INI file to remind myself of them.

Listing 5. Dummy reminder section in my C5EDT.INI file.

[Text Editor Configuration]
_version=43

[** Key Mapping ** < jcm]
The following keys are reserved by the Editor:
AltF, AltE, AltA
CtrlZ, CtrlX, CtrlC, CtrlV, CtrlA, Ctrl1, Ctrl2, Ctrl/, CtrlY, CtrlT, CtrlF
F3, AltF3, ShiftF3, CtrlF3

[Key Mapping]
CharLeft=LeftKey

So what can be safely changed? Well, I've made quite a few changes to my C5EDT.INI file to make the editor work a bit more like the way I want it to. For example:

The standard Clarion5 keyboard editor command to delete a word ahead of the cursor is CtrlT (goodness know why!). My fingers refuse to accept this; they keep using CtrlW no matter what! As you'll soon see, this was easy to change.

Step 3a. First have a look through C5EDT.INI to find the command most likely to do what you want to do. (This is a bit like trying to find the right embed point isn't it?) In my example, it's the DeleteWord command.

Step 3b. Now do a Find/Search through C5EDT.INI to make sure that the key combination you'd like to use is not already being used for something else. If it is, then you have two paths to take...

If you'd decided to reconfigure, say, CtrlF to some new purpose then you're out of luck. CtrlF is in that reserved list of key combinations I mentioned earlier (see Listing 5). It's reserved by the Clarion5 editor to enter FormatStructure mode (as you old CPD 2.1 users out there will remember well).

If, however, your new key combination is being used for some other purpose - but not in a special reserved manner - then it's a case of making a choice. If you like your own new reconfiguration better than the existing purpose defined for the key combination then it's just a matter of removing the existing definition.

NOTE: If you do this then you should also create a new key combination for the action which you "stole" from. (Sometimes, making a change can set off a whole chain-reaction of changes.)

Step 3c. Going back to my example, since CtrlW is not used for any other purpose it was a simple matter to change the original line from;

  DeleteWord=CtrlT

to

  DeleteWord=CtrlW

I have two options available for the use of CtrlT because it is now, potentially, freed-up by my change. Either I can reuse it for some other customised purpose (provided it's not one of the reserved key combinations - which it is!) or I can keep it as an alternative key combination for the same command.

To create two or more key combinations for the same command you just separate them with a semi-colon. For example;

  DeleteWord=CtrlT;CtrlW

Now both these key combinations will achieve the same purpose. (In fact, even without including CtrlT, using this key combination will still delete words as before, because it's one of the special reserved key combinations that can't be redefined - see Listing 5).

Step 4. So, off you go - make the editor work more like the way you want it to, not the other way around.

Listing 6 shows selected contents of standard [Key Mapping] settings. Listing 7 show how I've chosen to redefine the same commands.

Listing 6. The [Key Mapping] section of the standard C5EDT.INI file.

[Key Mapping]
(Some lines skipped)
ScrollDown=CtrlUp
ScrollUp=CtrlDown
TopOfPage=CtrlPgUp
BottomOfPage=CtrlPgDn
TopOfFile=CtrlHome
EndOfFile=CtrlEnd
LeftOnNextLine=CtrlEnter
GotoLine=CtrlG
BackTab=ShiftTab
ToggleInsert=InsertKey
DeleteChar=DeleteKey
DeleteLeft=BSKey;ShiftBS
(Some more lines skipped)
StartMarking=
StartOfBlock=
WriteBlock=
CommentBlock=
CtrlChar=
DeleteBlock=
DeleteEOL=
FindReplace=
InsertLine=
NewChar=
ReadBlock=

Listing 7. The [Key Mapping] section of my C5EDT.INI file.

[Key Mapping]
(Some lines skipped)
ScrollDown=CtrlU
ScrollUp=CtrlD
TopOfPage=CtrlF1
BottomOfPage=CtrlF10
TopOfFile=AltHome
EndOfFile=AltEnd
LeftOnNextLine=
GotoLine=AltG
BackTab=ShiftTab
ToggleInsert=InsertKey
DeleteChar=DeleteKey
DeleteLeft=BSKey;CtrlBS
(Some more lines skipped)
StartMarking=CtrlEnter
StartOfBlock=
WriteBlock=F8Key
CommentBlock=
CtrlChar=
DeleteBlock=
DeleteEOL=CtrlEnd
FindReplace=AltC
InsertLine=CtrlI
NewChar=
ReadBlock=F9Key

It's very unlikely that you'll want to make exactly the same changes I've made, but hopefully these examples will get you started. (They will at least make you wonder about the logic in my fingers!)

---

John Morter is a member of the Victorian Clarion Users Group (Melbourne, Australia). John is Asia Pacific IT Manager for a brand-name multi-national and he's supposed to leave all the fun technical stuff for others to do. So, his Clarion work is developed under the nom-de-keyboard Flat Chat Solutions, where "flat chat" is an Australian expression meaning doing something at top speed / high velocity.

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