NAME

cooledit-3.17.20 - Full featured text editor for the X Window System, Version 11.

USAGE

cooledit [-AabCEhiPsSUVv?] [options] [[+<line>] [<path>/]<file>] [[+<line>] [<path>/]<file>] ...

DISCLAIMER

The information in this file is provided without warranty for its accuracy or completeness. Use of this file or its information is entirely at your own risk.

DESCRIPTION

This is a portable, fast X Window text editor with beautiful 3D widgets. It requires only the X11 library to run. The engine is the same as that used for the internal editor of the Midnight Commander and hence cooledit represents a X Window version of that editor. The library that comes with Cooledit is now standalone. You can use it to write your own Cool applications. Check out the included programs Coolman and Smalledit.

OPTIONS

-d, -display <display>: The X server and display you would like to display to.
-g, -geom, -geometry <geometry>: Main window size and position on the screen, eg cooledit -geom 630x490+95+5. If cooledit is envoked with the size, the size will be saved on exit. If cooledit is envoked with the position, the position will be saved on exit. cooledit -geom + envokes the default size.
-lines <n>: Size of the edit window in text lines.
-columns <n>: Size of the edit window in mean character widths.
-vis, --visual <visual-class> (experimental): Without this option, the visual class is selected from a list of preferred classes and depth ranges. Use cooledit -vis help for more information.
-C, -cmap, --own-colormap (experimental): Force use of own colormap. If Cooledit is started after other colour-hungry application, and you are using one of the colour-palette visuals (like PseudoColor) the colors may look poor. In this case, use this option for a separate colour palette. (Contact me if you are forced to use this option.)
-defcmap, --default-colormap (experimental): Force use of default colormap. If Cooledit is started with a visual other than the default, then it creates its own colormap. This overrides this behaviour. (Contact me if you are forced to use this option.)
--edit-bg <nn>: Editor background colour. Rather edit your ~/.cedit/.cooledit.ini file, look for the option option_editor_bg_normal and others. This can be 0 to 26. Useful options are probably only 1 and 0 for dark blue and black.
-bg, --background-color <color>: Specifies the background color for a solid background. If <color> is igloo (default) then a background color is not used, and the background is set to the igloo logo.
-R, --foreground-red <value>: Red component of actual widget colors (buttons, windows), default: 0.9.
-G, --foreground-green <value>: Green component, default: 1.1.
-B, --foreground-blue <value>: Blue component, default: 1.4.
-f, -fn, -font <font-name>: The font you would like to use. (See FONTS below.) If <font-name> is default then the default font 8x13bold is invoked. If <font-name> is -? or -h then a list of example fonts are printed. If <font-name> is a number, then the example font of that number is used, eg cooledit -font 3
-no-fontset, --no-fontset: Turns off use of font sets under X. X has two methods of drawing fonts: the old "fontstruct" or "raw" method and the new font set method. The font set method properly interprets locales and their characters sets and is required for creating an X Input Method (for inputting international characters). Unfortunately, not all X servers understand UTF-8 (Unicode) encoding, hence the old "raw" method may be required when used with --utf8-interpretation.
-utf8, --utf8-interpretation: Should be used in conjunction with --no-fontset if required. Enable UTF-8 interpretation. Use for Unicode encoded files.
--anti-aliasing: This is depreciated, use font-name/3 instead.
--interchar-spacing <n>: Add extra pixels of space between each character. This option works with --anti-aliasing only. (Default is 0.)
--interwidget-spacing <n>: Spacing between widgets in dialog boxes. Make larger for a more spacious. Different defaults for different looks.
--look [gtk|cool|next]: Cooledit can emulate the look of a Gtk or NeXT application. Gtk is now the default, although you can invoke the old look with cooledit --look cool --widget-font default. There is some complexity in setting options for looks: certain settings, like --interwidget-spacing and --font are saved on exit, hence switching looks may inherit incorrect settings. Note that the default Gtk font for real Gtk applications is -adobe-helvetica-medium-r-normal--*-120-*-*-*-*-*-*, which is very close to -winfonts-arial-medium-r-normal-*-*-120-*-*-*-*-*-*.
--red-first: For LCD displays use R-G-B pixel ordering. (Default.)
--blue-first: For LCD displays use B-G-R pixel ordering. Try both of these options and see which looks better.
-S, --suppress-load-files: Don't load saved desktop on startup.
-U, --suppress-load-options: Don't load any saved options on startup.
-E, -no-override: Command line must not override any options already set in the initialisation file.
-I, --use-initialisation-file <file>: Use alternative intialisation file. Default: ~/.cedit/.cooledit.ini
-i, --all-characters: Display characters outside of locale if there are glyphs for them. This does not work if you did not specify the font completely - Cooledit would then be using a font set (which does not allow non-locale characters to be printed). See FONTS for more information. Default: display only isgraph(3) characters - i.e. characters printable under the current locale.
--word-wrap <length>: The maximum length of a line. See the next two options.
--type-writer: This option causes a newline to be inserted when the line you are typing becomes longer than --word-wrap length.
--auto-paragraph: This is a more advanced form of the option above: it causes the entire paragraph to be reformatted with each edit of a paragraph. See WORD PROCESSOR MODE below.
-t, -tab, --tab-spacing <spacing>: Interpret the tab character as being the length of <spacing> characters. Default is 8. You should avoid using other than 8 since most other editors and text viewers assume a tab spacing of 8. Use -fake-half-tabs to simulate a smaller tab spacing.
-s, -space, --space-filled-tabs: Never insert a tab space. Rather insert spaces (ascii 20h) to fill to the desired tab size.
-nospace, --no-space-filled-tabs: Default.
-a, --auto-indent: Pressing return will tab across to match the indentation of the first line above that has text on it (default).
-noautoi, --no-auto-indent: Turn off auto tabs.
-b, --backspace-through-tabs: Make a single backspace delete all the space to the left margin if there is no text between the cursor and the left margin.
-noback, --no-backspace-through-tabs: Default.
-half, --fake-half-tabs: This will emulate a half tab for those who want to program with a tab spacing of 4, but do not want the tab size changed from 8 (so that the code will be formatted the same when displayed by other programs). When editing between text and the left margin, moving and tabbing will be as though a tab space were 4, while actually using spaces and normal tabs for an optimal fill. When editing anywhere else, a normal tab is inserted.
-no-half, --no-fake-half-tabs: Turn off half tabbing.
-toolbar: Edit windows have a toolbar on the left: default.
--no-xim: Disable XIM support.
-no-toolbar: Edit windows do not have a toolbar.
-m, --minimal-main-window: This is used internally to create a new main window with one edit window when the user activates `New Main Window' from the Window menu. You can also use it to force the main window to be just large enough to hold all the sub-windows.
-A, -save-setup: Save options on exit (default).
-P, -no-save-setup: Don't save options on exit.
-W, --whole-chars-search <chars>: Characters that constitute a whole word when searching, default: 0-9a-z_ (typed out in full)
-w, --whole-chars-move <chars>: Characters that constitute a whole word when moving and deleting, default: 0-9a-z_; ,[](){} (typed out in full)
-verbose: Print info about X intialisation.
-h, -H, -?, --help: Print out commandline options summary.
-V, -v, --version: Print out version number.

Commandline examples

cooledit +10 hello.c -S -geom +: Start cooledit with one file, with minimum geometry, with cursor at line 10.
cooledit hello.c program.c: Start cooledit with two files, the file hello.c being the current file. The previous files are also loaded underneath these two files.

Features

Cooledit supports multiple edit windows and has all the conveniences of MSW/MAC text editors. The interface has a beautiful 3D look and feel vaguely like Motif. It has an extensible file size limit of 64Mb and edits binary files flawlessly. Besides typical functions of a basic editor, cooledit has the following features: a builtin Python interpretor for Python programmability; spell-check as you type with red wavy lines; graphical C/C++ debugger; Key for key undo; shift-arrow text highlighting; macro recording; a generic shell execution facility that can be used to run make, sort or any user defined shell function on text or editor files; easy key redefinition; mouse text highlighting; XDND drag and drop; double-click on a gcc error message to go immediately to the file and line number; desktop and cursor position memory; easy window cycling; comprehensive search and replace; input histories; and lots more. The editor is very easy to use and requires no tutoring. To see what keys do what, just consult the appropriate pull-down menu.

A complete set of key definitions follows.

HINT MESSAGES

Cooledit displays a new help message on the title bar every 2 minutes. All features not obvious from the user interface are documented by these hint messages, so reading them should be of considerable help to those who prefer not to read this man page.

To look at the complete list of hint messages, see the HINTS file in the distribution, or look under the doc/cooledit-3.17.18 directory in your file-system.

DEFAULT KEY DEFINITIONS

Keys may be redefined using an easy to use key learner. See the next section on how to get this to work.

The following is a partial list of all default key bindings and their actions, for reference. You will probably never need to refer to it because most of the editor actions can be found in the menus. Note that F14 is analogous to Shift-F4 etc. Also be aware that on some machines, what X percieves as an Alt/Meta is actually some other modifier key (our Sun-Sparc uses the diamond key).

Movement keys:
   Left                    left one char
   Right                   right one char
   Up                      up one line
   Down                    down one line
   Home                    beginning of line
   End                     end of line
   PgUp                    up one screen full
   PgDn                    down one screen full
   Ctrl-PgUp               beginning of file
   Ctrl-PgDn               end file
   Ctrl-Home               beginning of page
   Ctrl-End                end of page
   Ctrl-Left               left one word
   Ctrl-Right              right one word
   Ctrl-Up                 up one paragraph
   Ctrl-Down               down one paragraph
   Meta/Alt-Up             scroll up one line
   Meta/Alt-Down           scroll down one line
Highlight keys:
   Shift with any of the above keys will highlight
   at the same time.
Column highlighting:
   Holding down the Control key while using the mouse to highlight text,
   will cause the highlighted text to be displayed in inverse colour. You
   will be able to select columns (arbitrary rectangles) of text and
   drag and drop them as usual.
Input History:
   When editing an input line, Shift-Up or Shift-Down 
   will bring up a history of previous inputs.
Editing keys:
   Delete                  delete char to the right
   Backspace               delete char to the left
   Meta/Alt-Del            delete to line end
   Meta/Alt-Backspace      delete to line begin
   Meta/Alt-Right          delete word to the right
   Meta/Alt-Left           delete word to the left
   F5                      copy highlighted text to cursor
   F6                      move highlighted text to cursor
   F8                      delete highlighted text
   Ctrl-y                  delete line
   Shift-Enter             insert a newline
   Enter                   insert a newline with auto indent (default)
   Tab                     insert a tab (see options menu)
   Insert                  toggle insert/overwrite
   Ctrl-q                  quote - the next key pressed will be
                           interpreted as a literal
Undo:
   Ctrl-u
   Ctrl-Backspace
File
   Ctrl-F1                 man page
   F2                      save
   F12 or
   Shift-F2                save as
   Ctrl-o                  load
   Ctrl-j                  jump to file under cursor
   Ctrl-n                  new
   Ctrl-f                  save highlighted text as
   Shift-F5 or
   F15                     insert file at cursor
Mark:
   F3                      toggle highlight
   Ctrl-b                  toggle highlight columns
Search and replace:
   F7                      search
   F17 or
   Shift-F7                search again
   F4                      replace
   F14 or
   Shift-F4                replace again
X Clipboard:
   Ctrl-Ins                copy to clipboard
   Shift-Ins               paste to clipboard
   Shift-Delete            cut to clipboard
   Ctrl-Delete             delete highlighted text
   Meta/Alt-Ins            insert from selection history
General:
   F10                     exit (current editor)
   Ctrl-F3                 new edit window
   Shift-F3                new main window
   Alt-F6                  maximise the window
   Ctrl-F6                 window cycle
   Ctrl-F10                exit application
   Meta/Alt-x              save all and exit
   Ctrl-F2                 save state of desktop
   Ctrl-d                  insert date and time
   Meta/Alt-l              goto line number
   Meta/Alt-F7             run make
   Meta/Alt-t              sort
   Ctrl-r                  start/end record macro
   Ctrl-a                  execute macro
   Ctrl-p                  spell check highlighted text
   Shift-F9                C formatter
   Ctrl-Tab                complete word
   Meta/Alt-i              insert unicode character
   Shift/F1                rxvt terminal
Debug:
   Alt-F2                  toggle breakpoint
   Alt-F3                  continue until cursor
   Alt-F4                  continue
   Alt-F5                  run from beginning
   Alt-F8                  single step, dive into functions
   Alt-F9                  single step, skip over functions
   Ctrl-c                  interrupt program

New shell scripts will be added from time to time. Consult the Scripts menu for the hotkeys that envoke these.

EMERGENCIES

keywords: hang, crash, halt, pause, stop, infinite loop, SIGHUP, SIGUSR1.

There are some circumstances when Cooledit may go into an infinite loop, like if there is a bug in the editor movement commands, or if you create a recursive macro. In this case, you can restore Cooledit by using the kill shell function. Try kill -SIGUSR1 pid where pid is the process ID of cooledit from: ps | grep cooledit, for example. This will send SIGUSR1, a user signal, which, for Cooledit, will force a jump into its main loop, and restore operation. It is a good idea to then save what you have done and exit immediately in case there has been memory corruption.

KEY REDEFINING

The Options menu has a key binding learner which is easy to use. The key learning dialog contains a list of every re-definable action that the editor can perform. Simply click on the action you want to associate a key to, and press that key. An 'X' will appear next to the action to indicate the recording of a binding. To clear that binding click on the Clear Line button (or the Clear All button to clear all the bindings). You can even bind the same action to two separate keys: for instance using either the key pad arrows, or the normal arrows for cursor movement --- just click on that action again, and hit another key --- where two X's will appear. Up to three keys can be associated with an action. The binding is also sensitive to the keyboard 'state' (i.e. whether Control, Shift, Alt, Meta, or Hyper is pressed, and any combination of these) so binding Shift-Left to an action will work, and will be considered a different key stroke to Shift-Control-Left, and will also be considered a different key stroke to Shift-Left with NumLock on. Note that the difference between 'Enter' and 'Return' is that the one does an auto-indent.

The key binding records X11 key-codes. These are the actual hardware codes that come from the keyboard, so the key binding works on the lowest possible level of interpretation. The editor checks for these user defined keys before any hard-coded key bindings, so user binded keys will override the default key bindings. This means user defining keys will always work, but may be specific to the hardware you are using.

To redefine hardcoded keys (i.e. the default keys), modify the file edit_key_translator.c and then recompile. It contains simple C code which gets incorporated directly into the program during compilation. Note that the first function it calls is to get the user defined action for the key if there is one. To recompile, remove the file edit.o and run make in the top directory. This will allow you to change any key-binding. The editor menu however will have to be modified separately to reflect the changes you've made (see editmenu.c). A detailed explanation is given in the commentary of edit_key_translator.c.

(I added key redefinition mainly because different X Servers seem to interpret the same keys differently. It seems ridiculous that this should happen in the face X11's thorough key definition standard. The new X11R6.3 for Linux does seem to interpret keys properly and all the keys should work as expected on the PC; so there should be no need to redefine keys under Linux. You can however easily emulate another editor as you like.)

JUMP TO FILE AND YOUR PERSONAL FILE LIST

As of version 3.17.8, if the cursor is over a text file, in a normal edit window, you can hit Ctrl-j to open that file in a new window, through a fast text search of your personal file list. Your personal file list is located in ~/.cedit/filelist and can be created simply with

  find /this/directory/ /that/directory/ -type f > ~/.cedit/filelist

The list of directories should reflect any source trees you are currently interested in. This is useful for C/C++ source code where a #include directive specifies a file that you would like to immediately open. If the file under your cursor contains a leading / character, then it is assumed to be a full path and the file is immediately opened without consulting the file list. Cooledit checks the file list periodically to see if you have updated it, hence you need not restart Cooledit should your file list have been updated.

The file list is also used by the built in interface to gdb wherever gdb's output contains a file without mentioning its path. This could be because the object file currently being debugged does not contain sufficient debug information.

SPELL CHECK AS YOU TYPE

As of version 3.10.0, Cooledit spell checks typed words on the fly, placing the traditional wavy red line under miss-spelled words. This works by feeding typed words through ispell and placing them amidst the syntax highlighting rules if ispell returns a non-match. These rules expire after 60 seconds - which mean they won't stay underlined indefinitely. Word feeding is initiated by most key presses and applies only to the word under the cursor. To look up a word, merely move the cursor over it.

UNICODE, UCS AND UTF-8 SUPPORT

As of version 3.15.0, Cooledit has Unicode support. What kind of unicode support it has, and what unicode, UCS and UTF-8 are is explained as follows:

UCS stands for Universal Character Set. UCS is like ASCII (see ascii(1)) but instead of storing only 128 english specific characters, UCS goes up to 65535 characters and covers every known non-fictional language as well as scientific and mathematical symbols etc.

UCS theoretically goes beyond 65535 (for example defining the very useful Klingon character set). However, it is likely that most implementations will keep to a 2 byte size requirement. Cooledit supports up to 131072 (1FFFFh) characters. UCS is also called Unicode and is officially ISO standard 10646. So wherever you see ISO-10646 it means Unicode. (Actually, Unicode is a standard to define further things like typographical layout, but for here, they are taken to mean the same thing.)

2 bytes (for UCS) instead of 1 byte for ASCII posses a problem for most programs. For example, the average C program uses a string function every few lines (that assumes a 1 character per byte format). To solve this we have UTF-8. UTF-8 stands for UCS Transformation Format. It is an encoding scheme that says that any byte encountered by an application that has a value below 128 is to be treated as ordinary ascii characters, but a byte with a value above 128 means that a sequence of bytes is forthcoming that represents some character in the range 128 to 65536 (or above). This enables a stream of single bytes to represent the UCS character set, albeit with some inefficiency. More information can be had from http://www.unicode.org.

Hence pure ASCII text is already in UTF-8 format.

At the time of this writing, I am not quite sure precisely what an application has to be able to do to be classified as "Supporting Unicode". For instance: what about inserting characters? Don't input methods produce tradition charset encodings? And why are characters displayed by X's Xmb* and Xwc* functions?

At the moment Cooledit can display Unicode characters if: (1) the "UTF8 Interpretation" is on, (2) the "Display Characters outside locale" is on, (3) you are using a non-"fontset" type font - when loading you get an error message "Font set not loaded", and (4) if the font is a Unicode font - i.e. ending in the font name iso10646-1.

This may involve you having to install Unicode fonts. See http://www.cl.cam.ac.uk/~mgk25/unicode.html and http://czyborra.com/unifont/.

For instance

    cooledit --utf8-interpretation --all-characters --no-fontset       -font -gnu-unifont-*-*-*--*-*-*-*-*-*-iso10646-1

works. The GNU Unicode font is an attempt at supporting the entire Unicode character set in one font. Most other fonts will support a limited range (such as omitting the 20000 Chinese ideographs).

What Cooledit is supposed to do under a non-US locale I have no idea, so please give me a hint sometime. (Looking at the yudit documentation, it seems Gaspar also has my problems.

Note that Cooledit does no character set translations whatsoever - maybe later versions will.

THE INTERACTIVE GRAPHICAL DEBUGGER

As of version 3.9.0, Cooledit features an interface to gdb(1) under the new Debug menu. This means that you can seamlessly debug C/C++ programs from within Cooledit just like you used to with your DOS Turbo Debugger. This is extremely cool. You can set and clear breakpoints (the line is bookmarked in red) and follow the program flow with the green cursor line. Please remember that this an interface to gdb: Cooledit has no debugging features of its own. If you do not have the correct version of gdb, then a warning will be displayed on startup.

Interfaces are given to the common gdb commands. Any other commands can be executed with the Enter Command menu item. Automatic variable displays will soon be available though.

When a program stops for some reason (either a breakpoint or a signal), Cooledit tries to determine the file and line number. If this cannot be done, a backtrace is displayed. Backtraces do not contain full paths, hence files cannot be located if they are not already loaded. If the file is already loaded, then hitting enter on a file:line backtrace line will jump to the currect line number.

Programs must of course be compiled with the -g option and preferably the -O0 option (without -O0 gcc's optimizations may make the program flow appear a little strange and some variables will not be accessible).

Break-points are set and cleared from the menu or with Meta-F2. If you set a break point manually (with Meta-F1) it will not display in the edit window. Similarly if you clear a break point manually or close a window (thus clearing the breakpoints) there will be discrepancy between the book marks and the actual breakpoints. The same goes if you modify a file without restarting gdb.

Variables can be displayed by selecting Display variable.... A listbox will show all the variables you have selected. Click on the listbox and press Del to delete from this list. Use Ins to highlight a variable - this will cause a watchpoint to be inserted for this variable (i.e. the program will thereafter stop whenever the value of that variable changes). The listbox will also show an X in the second column if the variable has been altered since the last time the listbox was refreshed - this enables you to easily see which variable changes as you step through the lines of your program.

Everything else you need to know is obvious from the menu. You would do well to read gdb's info pages if you have never used a debugger under Unix before.

See also the section JUMP TO FILE AND YOUR PERSONAL FILE LIST regarding how Cooledit will consult your personal file list to resolve a path to a file.

PYTHON MACRO PROGRAMMING

As of version 3.8.0, Cooledit has a builtin Python interpretor. This means that Cooledit can execute arbitrary Python scripts from within its environment and bind scripts to keys and so forth. This is analogous to the way that Emacs uses a Lisp interpretor. Python is an object orientated scripting language like java, but with a much saner syntax. It is used for Rapid Application Development, and as a replacement for other intepretor languages like Perl, Tcl and Lisp.

On startup, Cooledit reads the top level Python file lib/cooledit/global.py, and then the user's personal file ~/.cedit/global.py. Any Python code can go into these files. No other files are explicitely read, but the code within global.py will call other Python files. The location of the directory lib/cooledit/ is dependant on your installation and is added to the default search path for modules.

To learn to program in Python, consult the tutorials and reference manuals that come with the Python sources.

One of the reasons for the python interpretor is to enable emulation of other editors such as vi and Emacs. It is quite feasable to write python scripts that will emulate all of the functions of these editors, and have user dialogs and menu items to switch between different editor emulations...

def get_ctrl_x_key():
    status ("\034Press \030s\033\035")
    k, m = get_key ()
    if m == 0:
        if k == "s":
            command (Save_As)
key ("x", ControlMask, "get_ctrl_x_key()")

The \034 and \035 means to draw a bevel around the enclosed text. The other escape characters cause colour changes (1 - 26, 27 = black).

Another powerful capacity is to have utilities specific to the particular file type that is being edited. When the type of an edit window is changed, the function type_change() from the global.py script is run. This function must run an appropriate file for the given file type which defines keys and creates menu items in that window's Util menu.

The following low level function are defined for manipulating the edit buffers. The functions operate on the current edit buffer. This is usually the one with the focus.

move(int): Moves the cursor relative to its current position in units of one character.
move_to(int): Moves the cursor to an absolute position in the buffer.
move_lines(int): Moves the cursor relative to its current position up or down.
int buffer_size(): Returns the size in bytes of the edit buffer.
insert(string): Types out the given string at the current cursor position.
indent([int]): Inserts tabs and spaces according to the current half-tab and tab settings. The inserted margin copies the margin from the first non-blank line above the current line. If an argument is given, then it makes the margin bigger or smaller by this many tabs. i.e. insert ("\n"); indent (3) is like hitting Enter and then hitting Tab three times.
insert_ahead(string): Inserts the given string ahead of the current cursor position.
back_space(int): Deletes the given number of characters behind the cursor.
delete(int): Deletes the given number of characters ahead of the cursor.
int current(): Returns the current absolute cursor position.
int current_line(): Returns the current line number counting from zero for the first line.
int bol(int): Returns the absolute offset of the start of the given line.
int eol(int): Returns the absolute offset of the end of the given line.
int find_forwards(int, string): Searches forward from the given offset and returns the absolute offset of the found string.
int find_backwards(int, string): Searches backward from the given offset and returns the absolute offset of the found string.
int line(int): Returns the line number of the given offset. Repeated calls to this function will be slow.
string get_text([int[, int]]): Returns a string containing the characters between the given offsets. If the second argument is omitted, then this returns a string one character in length at the given offset. If both arguments are omitted then this returns the character under the cursor.
string get_line([int[, int]]): Returns a string containing the characters between the given lines inclusive. If the second argument is omitted, then this returns a string containing the given line. If both arguments are omitted, then this returns the current line of the cursor. The trailing newline is not included.

The following functions allow binding of arbitrary python code to menu items and keys:

key(string, int[, string]): Binds a python statement to a key. The last argument contains python code. If it is omitted then the action is to unbind the key if it is bound. The first argument is the string representation of a key from the keysymdef.h X Window header file (with or without the XK_ prefix). The second argument is zero or the inclusive OR of any of the following modifiers:

ShiftMask
LockMask
ControlMask
AltMask
Mod1Mask
Mod2Mask
Mod3Mask
Mod4Mask
Mod5Mask

AltMask is defined in the global.h header file in the distribution and is system dependant.

The usual usage of this function is to bind a key to a short python statement. The statement itself would then call functions that were previously defined.

The key binding will be seen through all edit windows.

bind(string, string, int[, function])

Binds a python function to a range of keys in the current editor. If the last argument is omitted then the action is to unbind those keys if they are bound. The first two arguments are the string representation of a range of keys from the keysymdef.h X Window header file (with or without the XK_ prefix) (for example bind ("A", "Z", ControlMask, control_keys), which binds the keys A through Z to the function control_keys). The third argument is the modifier as with the key() function. The bound function must take two arguments: the key name as a string and the modifier as an integer.

The key binding will be seen in the current (focussed) editor window only. If the same key is bound globally (using the key() function), then it will be overridden by bind().

This is useful for binding particular keys depending on the type of text being edited. bind() should hence be used within the type_change() function.

menu(string, [string[, string]])

Creates a menu item. The last argument contains python code. If it is omitted then the action is to remove the menu item if it exists. The first argument is the name of one of the menus and can be one of File, Edit, Search, Command, Options, Readme or Util. The second argument is the menu item text to be added to the given menu. If this text contains a \t then the text after the \t will be right justified (eg "Open...\tC-o"). The Util menu is specific to each editor window, hence this is useful for defining tools specific to a particular file type. The Util menu is activated by pressing on the Util tool button of each editor window, or Meta-U.

If only one argument is given, then this command clears the menu of all its items.

replace_menu(string, string, string, string): Replaces an existing menu item with a new menu item. The arguments are respectively: The menu (i.e. File, Edit, etc.), the old menu item, the new menu item, and the python code.
insert_menu(string, string, string, string): Inserts a menu item after an existing menu item. The arguments are respectively: The menu (i.e. File, Edit, etc.), the menu item before which the insertion is to be made, the new menu item, and the python code.

The following functions return information about the current edit buffer:

string file(): Returns the file-name excluding the path.
string directory(): Returns the directory.
int modified(): Returns the flag to indicate if the buffer has been modified since the last load or save.
int overwrite([int]): Returns the overwrite flag (indicating type-over mode). If an integer is given, then this sets the overwrite flag and returns the previous value of the overwrite flag.
(int, int, int, int, int) markers([int, int[, int, int, int]])

Returns the state of the markers. The five values returned are: the starting marker, the ending marker, a flag indicating whether column highlighting mode is on, the starting column and the ending column. The last two values should be ignored if column highlighting (the third value) is found to be zero.

If nothing is highlighted then this function returns None.

If values are passed to the function, then the state of the markers will be set to those values. Note that if the end marker is -1, then the ending marker is the cursor and movements of the cursor will change the selection. If the third argument is zero then that last two arguments are ignored.

The following functions display and return information to/from the user:

(tuple, tuple) generic_dialog(string, tuple, tuple, tuple, tuple, tuple, tuple, tuple [[, int], int])

This function takes a string value as the title to a dialog, then displays the dialog, returning the results of various checkboxes or input widgets. The dialog has the same format as what you will see when doing a Find file from the File menu. An arbitrary number of input widgets or check boxes can be specified. The arguments passed to generic_dialog are as follows.

string

Title of the dialog.