By Michael Wulff Nielsen

Documentation by Ryan Abrams
 

Table Of Contents


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 CommentSymbol to indicate that the rest of the line is a comment
Block Comment OnSymbol to indicate the start of a block comment
Block Comment OffSymbol to indicate the end of a block comment comment
String CharsCharacters that contain a string
File ExtensionsFile 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.


Credits & Contributors

Cool Cat is created and coded by Michael Wulff Nielsen.

The following people contributed to the cause:

  • YNOP Talton - Syntax coloring modules, Image Slicer Add-On, and secondary code work.
  • Ryan Abrams - Menu and Toolbar design and XML layout, Documentation, Testing & Feature Planning.
  • Morten Leerhøy - Created the splashscreen and Cool Cat logo.
  • Bernhard Berger - Created the ColorFont2Html tool addon
  • Erwan Remot - Created and submitted a HTML menu for V0.5, which supplied inspiration for the current HTML menu.
  • Christian Hartmann - Contributed Icons for Cool Cat
  • Jens Johansson - Also contributed Icons for Cool Cat

Release Notes & History

Bugs fixed for Cool Cat V0.6:

  • Clinched the phantom cursor, once and for all!
  • The horizontal scrollbar was activated in word wrap mode, bummer!
  • The tools were sorted in reverse order in the Tools menu, this is now fixed.
  • When you dragged a color from the bucket to the color selector Cool Cat would crash. This is now fixed.
  • Activating Text inserting elements could cause Cool Cat to crash if no documents were open.
Improvements for Cool Cat V0.6

  • The entire menu structure is now defined in XML, therefore it can be customized a lot.
  • The toolbar is now defined in XML, thus you can finetune it to your needs.
  • The HTML syntax colormodule has been rewritten to provide more speed and options.
  • Cool Cat now saves its settings in /boot/home/config/settings/CoolCat, this prevents conflicts with upcoming versions of BeOS. (Thanks to Trey Boudreau of Be Inc. for pointing this out to me).
  • Improved the syntax coloring API, so that the modules can be configured.
  • YNOP Talton kindly turned his image splitter application into a Cool Cat addon.
  • YNOP Talton also created a UltraEdit wordfile compatible syntax coloring. Therefore Cool Cat now supports syntax coloring for Java, C/C++, Pascal, BASH, x86 assembler and Perl.
  • You can now set the default background and font colors for non syntax colored texts.
  • I have now enabled the nonwordwrap code in Cool Cat, so now you can enjoy non wrapped text, while editing.
  • Find/Replace implemented (in a basic form)
Known bugs in Cool Cat V0.6:

  • Mysterious Crash on Exit when saving multiple files in the close all routine.
  • Ampersand option in the HTML->Special Characters menu leaves cursor in the wrong place.
Release Notes for Cool Cat V0.5:

Bugs fixed for Cool Cat V0.5:

  • The anchor addon had a bug in the HTML it generated. This is now fixed.
  • Removed a lot of bugs in the syntaxcoloring module for HTML.
  • Removed the bug that caused a remnant of the cursor to stay onscreen.
  • Fixed some bugs in the addons that could cause problems, if you invoked them more than once.
  • Made sure that the addons are initialized proberbly. This could in extreme cases cause problems.
  • Some addons could be zoomed, though they could not be resized, this is now fixed.
  • Fixed a HTML typo the table wizard.
Improvements for Cool Cat V0.5
  • Added some icons to the icon toolbar.
  • Improved the syntax coloring module.
  • Added some colorbuckets to the colorselector module. You can now save your 9 most used colors.
  • Cool Cat now remembers it window position and size
  • You now have an option to strip out Windows linefeeds from any loaded text.
  • You can now customize your own HTML menu, by using an XML file.
  • The commenter addon has been removed, and replaced by an entry in the menu XML file.
  • Cleaned up the addon code, and I hope to able to release it publicly by V0.6
  • Made room for a statuswindow - it should appear in V0.6
  • Bernhard Berger submitted his program Font Color 2 Html for integration into Cool Cat. I have now integrated his code into an addon. But I am not yet sure how good a job I have done.
  • Made a preview button, based on the code from Bernhard Berger.
  • An irrelevant improvement is a small Cool Cat screen saver that I wrote, and included in the Goodies directory
  • Made minor adjusments to the GUI to acommodate the upcoming statusbar.
Release notes for Cool Cat V0.4.1 Bugs fixed for Cool Cat V0.4.1:
  • Changed splashscreen from PNG to BMP to stop reported crashes.
Release notes for Cool Cat V0.4

Bugs fixed for Cool Cat V0.4:

  • Fixed a small bug that caused the undo code to break.
  • Fixed a typo in the table wizard
  • Fixed another bug, that would cause the scrollbars to go crazy, and allow you to scroll beyond the text.
  • Filenames should no longer spill over tab boundaries.
Improvements for Cool Cat V0.4:
  • Cool Cat now marks a file as dirty when text is deleted from the file.
  • Experimental syntax coloring is now in place. It still has some bugs. Currently only HTML is supported.
  • Added a Websafe option to the color selector.
  • There is now an option to turn the splashscreen off.
  • When opening a new document, or switching to one, Cool Cat sets the focus to be the editable text.
  • Improved the preferences.
  • Tool Addons can now be configured.
  • Cool Cat can now set autoindenation on and off.
  • Cool Cat exports its filetypes, so that it can be set as a preferred handler
  • Added an image tag generator addon.
  • Added an anchor generator addon.
Known bugs for 0.4:
  • When using the new syntax colormodule, sometimes a small part of the cursor stays onscreen.
  • The Syntax coloring can be very slow when working with large HTML files, this WILL be fixed.
  • Something causes the non wordwrap code to break. I am currently looking into this. Until then, you will have to be satisfied
Release Notes for Cool Cat V0.3

Bugs fixed for Cool Cat V0.3:

  • Fixed a bug that would cause Cool Cat to trash saved files.
  • Cleaned up the UI code, it should be marginally more reliable now.
  • Fixed an error that would occur when you closed the tabs.
Improvements for Cool Cat V0.3:
  • Improved the dirty marking of the text. It is now more reliable.
  • Supports opening of multiple files, and now also supports dragged and dropped files.
  • Now Cool Cat doesn't force the mimetype of an opened file to text/HTML. This makes it a better allround editor.
  • Filenames don't spill over tab boundaries.
  • Added a new colorselector add-on.
  • Prelimenary preferences menu has been added.
  • Added support for configuring the individual addon.
  • Changed the addon architecture to allow the user to set his/her own shortcut keys for the tools.
  • Made a lot of modifications to the tablewizard.
  • Made support for syntax coloring plugins.
  • The splashscreen now respects other applications.
Known bugs for 0.3:
  • Sometimes Cool Cat crashes upon exit. The source of this problem is as yet unknown
Release Notes for Cool Cat V0.2
  • First Release