Introduction
Thanks for trying Cool Cat!
Cool Cat began life as an advanced, text-based HTML editor, and is quickly evolving to fufill that goal and surpass it. It features a user interface that is almost completely customizable, advanced syntax coloring, and a plug in architecture for expanded capabilities.
It comes preconfigured as a powerful HTML editor, and has most of the tags in the HTML specification as listed by The Barebones Guide to HTML either configured as standard, or accessible through one of the many powerful plugins.
While we like to think it is one of the most powerful and easy to use HTML-focused editors on the BeOS, version 0.6 is far from complete. Work is already progressing on the next version of Cool Cat, and 1.0 isn't too far off.
While 0.6 gives a hint of whats to come, you ain't seen nothing yet.
In this documentation we are going to skip the basics of using the editor (we like to think it explains itself) and move directly to the customization of the editor. This will take two parts: the XML commands available, and the Syntax File Format.
You will always find the latest version of Cool Cat, and it's documentation at the Cool Cat Homepage.
XML Guide
The XML structure of Cool Cat is fairly simple. We are going to focus on the menu XML, as the toolbar XML is simply a derivative of that, and easy to figure out once the menus are clear. If you dont understand the following, don't edit the menus! It is very possible to ruin part or all of the functionality of this program by editing or deleting a menu file. While the XML shouldn't damage anything outside of coolcat, it is essential to everything inside of Cool Cat. Edit at your own risk. The worst that can really happen is that you have to download Cool Cat again for the menus.
Ok. the menu structure looks something like this:
<menu name="Menu" priority="1" state="conditional">
<menu name="SubMenu">
<menuitem name="Make A New HTML File" shortcut="N" qualifier="B_COMMAND_KEY" action="NewFile">
<parameter name="Mimetype">text/html</parameter>
<parameter name="Contents"Generic HTML Contents</parameter>
</menuitem>
<separator/>
<menuitem name="Modify Some Text" shortcut="M" qualifier="B_COMMAND_KEY" action="textevent">
<parameter name="before">Insert before selected text</parameter>
<parameter name="replace">Replace the selected text with this</parameter>
<parameter name="after">Insert after selected text</parameter>
</menuitem>
</menu>
</menu>
Lets go through that a bit at a time then...
<menu name="Menu" priority="1" state="conditional">
<menu name="SubMenu">
The menu tag is pretty easy to use. If it is the first menu tag in the file, it will define the name of the menu as seen on the menu bar.
The priority attribute controls where on the menu bar it is. The lower the priority, the further left on the menu bar it is. If two menus share a priority, it is done in the order they are found by the filesystem - essentially randomly. So plan well.
The state attribute controls the conditions the option is a available. It has three options - Enabled, Disabled, and Conditional. Enabled and Disabled are exactly what they sound like, while Conditional means the option is only available if there is an open file. Enabled is the default. This tag can be used on menus and menuitems.
Submenus are created just as you would expect - by placing a complete menu tag inside of another.
All menu tags must be closed with the </menu> tag.
Now for the next section of the code:
<menuitem name="Make A New HTML File" shortcut="N" qualifier="B_COMMAND_KEY" action="NewFile">
<parameter name="Mimetype">text/html</parameter>
<parameter name="Contents">Generic HTML Contents</parameter>
</menuitem>
The menu item is the bread and butter of a menu.
The name attribute just assigns it a name to be shown in the menu. This is required.
The shortcut and qualifier attributes are both optional, and work with each other to assign hotkeys to menu items. The shortcut key is a standard key that is used in conjunction with the defined qualifiers. Qualifiers include:
B_SHIFT_KEY
B_CONTROL_KEY
B_OPTION_KEY
B_COMMAND_KEY
If you do not declare a qualifier, B_COMMAND_KEY will be assigned automatically. When Declaring Qualifiers, just seperate them with a |The action parameter tells the menu what to do when this item is selected. In this case, it creates a new file. A full listing of all currently enabled XML action items is at the end of this tutorial section.
The parameters supply extra information to the action telling it what to do. This menuitem would create a newfile with the Mime-type of text/html and place the text "Generic HTML Contents" in the newly created file.
The </menuitem> tag tells the menu that this item has no more parameters and is finished.
What's that? Next Code Block Please? Ok.
<separator/>
The separator does exactly what it says. It places a horizontal separator in the menu.
The rest of the sample code should make sense now. If it does, it's time to start editing. If it doesn't, go back to the top of the XML docs, and try again. Or just don't edit your menus. Below is a complete listing of the XML Action Items available in v0.6 - This list is still pretty basic, but will grow alot in the future. Have fun!
XML Action Items |
Command Name |
Parameters |
Action |
NewFile |
Creates a new file in the editor |
|
Mimetype |
Define the MIME type of the new file |
Contents |
The default contents of the new file |
OpenFile |
Opens a file from disk |
SaveFile |
Save the current file to disk |
|
SaveAll |
Save ALL open files to disk |
ForceFilerequester |
Force a SAVE AS... |
CloseFile |
Close the current file |
|
CloseAll |
Close ALL open files. |
Cut |
Move the currently selected text to the clipboard |
Copy |
Copy the currently selected text to the clipboard |
Paste |
Paste the contents of the clipboard into the current document. |
OpenFindReplace |
Open the minimalist Find/Replace Dialog |
SelectAll |
Select all the text in the current document |
Undo |
Undo the previous action |
Preferences |
Load the preferences panel. |
PreviewText |
Open the current document in it's native viewer. Currently only enabled for HTML. |
NextText |
Change focus to the next open file. |
PreviousText |
Change focus to the previous open file. |
About |
Show the about box. |
Quit |
Exit the application |
Textevent |
Perform action on the currently selected text |
|
Before |
Text to insert BEFORE selected text |
After |
Text to insert AFTER selected text |
Replace |
Text to REPLACE the selected text with. |
Syntax File Guide
The syntax coloring in Cool Cat is fairly easy to understand, but what if you wanted coloring on a language that isnt supported by the default install? Easy! Just create the syntax module yourself!! It isn't hard at all. Here's how.
You need to create a syntax definition file, which takes the following format:
/L1"C/C++" Line Comment = // Block Comment On = /* Block Comment Off = */ String Chars = "' File Extensions = C CPP H HPP AWK
/Delimiters = ~!@^&*()|{}[]:"' , ?
/Function String = "%[a-zA-Z]*)"
/Indent Strings = "{"
/Unindent Strings = "}"
/C1 KEYWORDS
.... key words. ...
/C2 OTHERWORDS
.... other words ...
/C3 ....
NOTE: This format is very close to the UltraEdit syntax file format. With very little modification, you should be able to get UltraEdit syntax files to work with Cool Cat.
The first line of the file must be the line that explains the basis of the syntax. In this case that is:
/L1"C/C++" Line Comment = // Block Comment On = /* Block Comment Off = */ String Chars = "' File Extensions = C CPP H HPP AWK
The various values on this line should make sense to you. If they don't, you aren't ready for syntax editing. Here is a quick explanation anyway.
Line Comment | Symbol to indicate that the rest of the line is a comment |
Block Comment On | Symbol to indicate the start of a block comment |
Block Comment Off | Symbol to indicate the end of a block comment comment |
String Chars | Characters that contain a string |
File Extensions | File extensions that this syntax module can handle. |
Currently the comment tags are not used, but the next version of the module will use them, so add them now.
The next line of the file should be the /Delimiters line. This line lists all characters which help break up statements into chunks. This helps the plugin figure out how to color the text. Space and Return are built into the plugin. All others should be added to this line.
The next three lines (Function String, Indent String, and Unindent String) are ignored completely and not required. To maintain format compatibility with UltraEdit, we have added them here. They may be used in the future, but this is not guaranteed. It is up to you wether to add them or not. If so, you are on your own.
The rest of this file takes the following format:
/C? <NAME>
word1 word2 word3 word4
/C? <NAME>
word1 word2 word3 word4
where ? is a number incrementing from 1 to 8, and <NAME> is the name of that category. Then below that just list all the words that belong in that category. Each category will have its coloring defined in the cool cat preferences panel.
So now that this definition file is done, how do you install it? That is pretty easy too.
Look in CoolCat/Addons/Languages and make a duplicate of one of the existing WordFile plugins (they have the plug icon). Rename it to WordFilePluginXXXX where XXXX is whatever the name of your new syntax module is. Then place your syntax text file into the CoolCat/Addons/Languages/Wordfiles directory, with the name WordFileXXXX where XXXX is the same as what you used when renaming the plugin. The new plugin should show up the next time you load Cool Cat.