cooledit.1

具有IDE功能的编辑器

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.
.PP
.SH PYTHON MACRO PROGRAMMING
As of version 3.8.0, \fBCooledit\fP has a builtin \fBPython\fP interpretor.
This means that \fBCooledit\fP can execute arbitrary \fBPython\fP scripts
from within its environment and bind scripts to keys and so forth. This
is analogous to the way that \fBEmacs\fP uses a \fBLisp\fP interpretor.
\fBPython\fP is an object orientated scripting language like java, but
with a much saner syntax. It is used for \fIRapid Application Development\fP,
and as a replacement for other intepretor languages like \fBPerl\fP, 
\fBTcl\fP and \fBLisp\fP.

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

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

One of the reasons for the python interpretor is to enable emulation of
other editors such as \fBvi\fP and \fBEmacs\fP. 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...
.PP
.nf
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()")
.fi
.PP
The \\034 and \\035 means to draw a bevel around the enclosed text. The
other escape characters cause colour changes (1 - 26, 27 = black).
.PP
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 \fBtype_change()\fP from the
\fBglobal.py\fP 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 \fBUtil\fP 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.
.TP
\fBmove(\fP\fIint\fP\fB)\fP
Moves the cursor relative to its current position in units of one character.
.TP
\fBmove_to(\fP\fIint\fP\fB)\fP
Moves the cursor to an absolute position in the buffer.
.TP
\fBmove_lines(\fP\fIint\fP\fB)\fP
Moves the cursor relative to its current position up or down.
.TP
\fIint\fP \fBbuffer_size()\fP
Returns the size in bytes of the edit buffer.
.TP
\fBinsert(\fP\fIstring\fP\fB)\fP
Types out the given string at the current cursor position.
.TP
\fBindent(\fP\fI[int]\fP\fB)\fP
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. \fBinsert ("\\n");
indent (3)\fP is like hitting Enter and then hitting Tab three times.
.TP
\fBinsert_ahead(\fP\fIstring\fP\fB)\fP
Inserts the given string ahead of the current cursor position.
.TP
\fBback_space(\fP\fIint\fP\fB)\fP
Deletes the given number of characters behind the cursor.
.TP
\fBdelete(\fP\fIint\fP\fB)\fP
Deletes the given number of characters ahead of the cursor.
.TP
\fIint\fP \fBcurrent()\fP
Returns the current absolute cursor position.
.TP
\fIint\fP \fBcurrent_line()\fP
Returns the current line number counting from zero for the first line.
.TP
\fIint\fP \fBbol(\fP\fIint\fP\fB)\fP
Returns the absolute offset of the start of the given line.
.TP
\fIint\fP \fBeol(\fP\fIint\fP\fB)\fP
Returns the absolute offset of the end of the given line.
.TP
\fIint\fP \fBfind_forwards(\fP\fIint\fP, \fIstring\fP\fB)\fP
Searches forward from the given offset and returns the absolute
offset of the found string.
.TP
\fIint\fP \fBfind_backwards(\fP\fIint\fP, \fIstring\fP\fB)\fP
Searches backward from the given offset and returns the absolute
offset of the found string.
.TP
\fIint\fP \fBline(\fP\fIint\fP\fB)\fP
Returns the line number of the given offset. Repeated calls to this
function will be slow.
.TP
\fIstring\fP \fBget_text(\fP\fI[int[\fP\fB,\fP \fIint]]\fP\fB)\fP
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.
.TP
\fIstring\fP \fBget_line(\fP\fI[int[\fP\fB,\fP \fIint]]\fP\fB)\fP
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.
.PP
The following functions allow binding of arbitrary python code
to menu items and keys:
.TP
\fBkey(\fP\fIstring\fP\fB,\fP \fIint[\fP\fB,\fP \fIstring]\fP\fB)\fP
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
\fBkeysymdef.h\fP X Window header file (with or without the \fBXK_\fP
prefix). The second argument is zero or the inclusive OR of any of the
following modifiers:
.RS
.TP
.B ShiftMask
.TP
.B LockMask
.TP
.B ControlMask
.TP
.B AltMask
.TP
.B Mod1Mask
.TP
.B Mod2Mask
.TP
.B Mod3Mask
.TP
.B Mod4Mask
.TP
.B Mod5Mask
.PP
\fBAltMask\fP is defined in the \fBglobal.h\fP 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.
.RE
.TP
\fBbind(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fIint[\fP\fB,\fP \fIfunction]\fP\fB)\fP
.RS
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 \fBkeysymdef.h\fP X Window header file (with or without
the \fBXK_\fP prefix) (for example \fBbind ("A", "Z", ControlMask,
control_keys)\fP, which binds the keys \fBA\fP through \fBZ\fP to the
function \fBcontrol_keys\fP). The third argument is the modifier as with the
\fBkey()\fP function. The bound function must take two arguments: the
key name as a string and the modifier as an integer.
.PP
The key binding will be seen in the current (focussed) editor window
only. If the same key is bound globally (using the \fBkey()\fP function),
then it will be overridden by \fBbind()\fP.
.PP
This is useful for binding particular keys depending on the type of
text being edited. \fBbind()\fP should hence be used within the
\fBtype_change()\fP function.
.RE
.TP
\fBmenu(\fP\fIstring\fP\fB,\fP \fI[string[\fP\fB,\fP \fIstring]]\fP\fB)\fP
.RS
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
\fBFile\fP, \fBEdit\fP, \fBSearch\fP, \fBCommand\fP, \fBOptions\fP,
\fBReadme\fP or \fBUtil\fP. The second argument is the menu item text to
be added to the given menu. If this text contains a \fB\\t\fP
then the text after the \fB\\t\fP will be right justified (eg
\fI"Open...\fP\fB\\t\fP\fIC-o"\fP). The \fBUtil\fP menu is
specific to each editor window, hence this is useful for
defining tools specific to a particular file type. The
\fBUtil\fP menu is activated by pressing on the \fBUtil\fP tool
button of each editor window, or
\fBMeta-U\fP.

If only one argument is given, then this command clears the menu of all
its items.
.RE
.TP
\fBreplace_menu(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fIstring\fP,\fP \fIstring\fP\fB)\fP
Replaces an existing menu item with a new menu item. The arguments
are respectively: The menu (i.e. \fBFile\fP, \fBEdit\fP, etc.),
the old menu item, the new menu item, and the python code.
.TP
\fBinsert_menu(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fIstring\fP,\fP \fIstring\fP\fB)\fP
Inserts a menu item after an existing menu item. The arguments
are respectively: The menu (i.e. \fBFile\fP, \fBEdit\fP, etc.),
the menu item before which the insertion is to be made, the new menu item,
and the python code.
.PP
The following functions return information about the current edit buffer:
.TP
\fIstring\fP \fBfile()\fP
Returns the file-name excluding the path.
.TP
\fIstring\fP \fBdirectory()\fP
Returns the directory.
.TP
\fIint\fP \fBmodified()\fP
Returns the flag to indicate if the buffer has been modified since
the last load or save.
.TP
\fIint\fP \fBoverwrite(\fP\fI[int]\fP\fB)\fP
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.
.TP
\fB(\fP\fIint\fP\fB,\fP \fIint\fP\fB,\fP \fIint\fP\fB,\fP \fIint\fP\fB,\fP \fIint\fP\fB)\fP \fBmarkers(\fP\fI[int\fP\fB,\fP \fIint[\fP\fB,\fP \fIint\fP\fB,\fP \fIint\fP\fB,\fP \fIint]]\fP\fB)\fP
.RS
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 \fBNone\fP.

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.
.RE
.PP
The following functions display and return information to/from the user:
.TP
\fB(\fP\fItuple\fP\fB,\fP \fItuple\fP\fB)\fP \fBgeneric_dialog(\fP\fIstring\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple\fP\fB, \fP\fItuple [[\fP\fB, \fP\fIint]\fP\fB, \fP\fIint]\fP\fB)\fP
.RS
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 \fBFind file\fP from the \fBFile\fP menu. An arbitrary number of
input widgets or check boxes can be specified. The arguments passed to
\fBgeneric_dialog\fP are as follows.
.TP
\fIstring\fP
Title of the dialog.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list of default strings to go into each of the input widgets.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list of labels to go above each of the input widgets.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list of names used internally to store histories of entries to that
input widget. These can be anything, although a descriptive name,
of about 20 characters in length, will ensure uniqueness for each widget.
This is actually the internal name of the widget which must be unique
within the entire application. Something of the form 
\fIdialogname\fP\fB.\fP\fIentryname\fP for each input widget is fine.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list of tool hints for each input widget. Elements may be
null or there may be less elements than the number if widgets.
.TP
\fB(\fP\fIint\fP\fB,\fP \fIint\fP\fB,\fP \fI...\fP\fB)\fP
A list of values for check boxes - either 0 for off or 1 for on.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list labels for each check box.
.TP
\fB(\fP\fIstring\fP\fB,\fP \fIstring\fP\fB,\fP \fI...\fP\fB)\fP
A list of tool hints for each checkbox. Elements may be
null or there may be less elements than the number if widgets.
.TP
\fIint\fP
An optional width of the dialog. This is in units of the mean character
width for the current font. The default value is 60.
.TP
\fIint\fP
An optional options integer being the inclusive OR of one or more of the following
values:
.nf
    \fBINPUTS_WITH_OPTIONS_BROWSE_LOAD_1\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_SAVE_1\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_DIR_1\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_LOAD_2\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_SAVE_2\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_DIR_2\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_LOAD_3\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_SAVE_3\fP
    \fBINPUTS_WITH_OPTIONS_BROWSE_DIR_3\fP
.fi
This indicates that a `Browse' button should
accompany the entry widget. The browse button
will open a file with behaviour appropriate to
loading, saving or selecting a directory.
.PP
The return values are two tuples containing a list of the values
of the input widgets and checkbox's respectively. If the dialog was
canceled, the return value is null.
.PP