NAME
tkemacs - Create and manipulate tkemacs widgets

SYNOPSIS
tkemacs pathName ?options?

STANDARD OPTIONS

background	foreground	insertWidth	selectBorderWidth
borderWidth	insertBackground	padX	selectForeground
cursor	insertBorderWidth	padY	setGrid
exportSelection	insertOffTime	relief	xScrollCommand
font	insertOnTime	selectBackground	yScrollCommand

See the ``options'' manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name:	command
Class:	Command
Command-Line Switch:	-command

    Specifies the emacs executable that is called as background emacs. The default name is TkEmacs.

Name:	debug
Class:	Debug
Command-Line Switch:	-debug

    Turn on/off the debugging for the widget.

Name:	endSource
Class:	EndSource
Command-Line Switch:	-endsource

    Specifies lisp code that is sent to emacs right before the emacs is terminated.

Name:	errorCallback
Class:	ErrorCallback
Command-Line Switch:	-errorcallback

    Specifies a tcl procedure that is called if an error is received from emacs. The procedure gets two parameters. The first parameter is the name of the TkEmacs widget, and the second parameter is the error message from emacs.

Name:	file
Class:	File
Command-Line Switch:	-file

    Specifies the file that is loaded in the emacs when the widget is created. This file represents the text you want to edit.

Name:	geometry
Class:	Geometry
Command-Line Switch:	-geometry

    Specifies the geometry of the widget in pixels. This option is overlayed by the options -height and -width.

Name:	height
Class:	Height
Command-Line Switch:	-height

    Specifies the desired height for the window, in units of characters.

Name:	lispfile
Class:	LispFile
Command-Line Switch:	-lispfile

    Specifies the lispfile that is loaded in the emacs when the widget is created. This lisp code connects to the widget, and provides the lisp functions that are necessary for the widget. The default value is tkemacs.el.

Name:	pollInterval
Class:	PollInterval
Command-Line Switch:	-pollinterval

    Specifies the interval between two updates of the scrollbars. To reduce the traffic between emacs and the widget, this option allows the update of the scrollbar size and position in intervals.

Name:	startSource
Class:	StartSource
Command-Line Switch:	-startsource

    Specifies the lisp code that is sent to emacs right after the emacs has been started.

Name:	state
Class:	State
Command-Line Switch:	-state

    This option is ignored.

Name:	timeout
Class:	Timeout
Command-Line Switch:	-timeout

    Specifies a timeout for the communication between emacs and the widget. If a command has been sent and does not return a value after this number of seconds, the widget aborts this command.

Name:	useAdvise
Class:	UseAdvise
Command-Line Switch:	-useadvise

    The update of the scrollbars is done by wrapping an update command around most of the commands that could change the size and position of the scrollbar. This will lead into traffic between emacs and the widget, which can be avoided by setting this option to false. In this case, there are no wrappers.

Name:	width
Class:	Width
Command-Line Switch:	-width

    Specifies the desired width for the window in units of characters.

Name:	windowId
Class:	WindowId
Command-Line Switch:	-windowid

    Specifies the window id that is used to send events. This window id is created by emacs, and the option is set to the correct value by emacs. You should not play with this option, because this will kill your emacs and wish.

Name:	wrap
Class:	Wrap
Command-Line Switch:	-wrap

    This option is ignored.

DESCRIPTION

The tkemacs command creates a new window (given by the pathName argument) and makes it into a tkemacs widget. Additional options, as described above, may be specified on the command line or in the option database to configure aspects of the tkemacs such as its default background color and relief. The tkemacs command returns the path name of the new window.

A tkemacs widget displays one or more lines of text and allows that text to be edited. To display and edit the text an external emacs is used, the output of which is redirected to the widget window.

The TkEmacs widget tries to be as compatible to the text widget as possible. At some points the widget is incompatible, because some concepts of the text widget cannot be provided with emacs (Or it was too tough at this moment :-).

INDICES

Many of the widget commands for tkemacs take one or more indices as arguments. An index is a string used to indicate a particular place within a text, such as a place to insert characters or an endpoint of a range of characters to delete. Indices have the syntax

    base modifier.

Where base gives a starting point and the modifier adjusts the index from the starting point (e.g. move forward or backward one character). Every index must contain a base, but the modifier is optional.

The base for an index must have one of the following forms:

line.char
    Indicates char'th character on line line. Lines are numbered from 0, which is different from the numbering in the text widget. Within a line, characters are numbered from 0.

charpos
    This references the charpos'th character, where charpos is calculated by counting all characters from the beginning of the file.

end Indicates the last character in the text.

mark
    Indicates the character just after the mark the name of which is mark.

top Indicates the first character in the text.

If modifier follows the base index, it must have one of the forms listed below. Keywords such as chars and wordend may be abbreviated as long as the abbreviation is unambiguous.

+ count chars
    Adjusts the index forward by count characters, moving to later lines in the text if necessary. If there are fewer than count characters in the text after the current index, then set the index to the last character in the text. Spaces on either side of count are optional.

- count chars
    Adjusts the index backward by count characters, moving to earlier lines in the text if necessary. If there are fewer than count characters in the text before the current index, then set the index to the first character in the text. Spaces on either side of count are optional.

+ count lines
    Adjusts the index forward by count lines, retaining the same character position within the line. If there are fewer than count lines after the line containing the current index, then set the index to refer to the same character position on the last line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.

- count lines
    Adjusts the index backward by count lines, retaining the same character position within the line. If there are fewer than count lines before the line containing the current index, then set the index to refer to the same character position on the first line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.

linestart
    Adjusts the index to refer to the first character on the line.

lineend
    Adjusts the index to refer to the last character on the line (the newline).

wordstart
    Adjusts the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these.

wordend
    Adjusts the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text, it is not modified.

TAGS

Tags are not implemented by the TkEmacs widget.

MARKS

Only the mark insert is implemented. The mark may be manipulated with the ``pathName mark'' widget command, and the current location may be determined by using the mark name as an index in widget commands. The mark insert is associated with the insertion cursor, as described under THE INSERTION CURSOR below.

THE SELECTION

TkEmacs widgets support the standard X selection, in that way that emacs handles X selections.

THE INSERTION CURSOR

The mark named insert has special significance in TkEmacs widgets. It is defined automatically when a TkEmacs widget is created and it may not be unset with the ``pathName mark unset'' widget command. The insert mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the TkEmacs widget has the input focus.

WIDGET COMMAND

The tkemacs command creates a new Tcl command the name of which is the same as the path name of the TkEmacs's window. This command may be used to invoke various operations on the widget. It has the following general form: pathName option ?arg arg ...? PathName is the name of the command, which is the same as the tkemacs widget's path name. Option and the args determine the exact behavior of the command. The following commands are possible for tkemacs widgets:

pathName compare index1 op index2
    Compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators <, <=, ==, >=, >, or !=. If op is ==, then 1 is returned if the two indices refer to the same character, if op is <, then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.

pathName configure ?option? ?value option value ...?
    Queries or modifies the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named "option" (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the tkemacs command.

pathName debug ?boolean?
    If boolean is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. If the value is a true one, you will see some debugging information. If boolean has a false value, the debugging checks will be turned off. In either case the command returns an empty string. If boolean is not specified, the command returns on or off to indicate whether or not debugging is turned on.

pathName delete index1 ?index2?
    Deletes a range of characters from the text. If both index1 and index2 are specified, it deletes all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified, the single character at index1 is deleted. The command returns the deleted text.

pathName get ?index1? ?index2?
    Returns a range of characters from the text. The return value will be all the characters in the text starting with the one the index of which is index1 and ending just before the one with the index index2 (the character at index2 will not be returned). If index2 is omitted, the end is assumed for index2. If index1 and index2 are omitted, the complete text is returned. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1), an empty string is returned.

pathName index index
    Returns the position corresponding to index in the form charpos where charpos is the position of the character counted from the beginning of the file. Index may have any of the forms described under INDICES above.

pathName insert index chars
    Inserts chars into the text just before the character at index and returns an empty string.

pathName mark option ?arg arg ...?
    This command is used to manipulate marks. The exact behavior of the command depends on the option argument that follows the mark argument. The following forms of the command are currently supported:

    pathName mark names
        Not implemented.

    pathName mark set markName index
        This is only implemented for the mark named insert.

    pathName mark unset markName ?markName markName ...?
        Not implemented.

pathName redisplay
    This command redisplays the widget.

pathName reset
    This command resets the internal protocol handling. This command is usually of no interest for the "standard" user.

pathName scan option args
    Not implemented.

pathName send lisp-code
    This command sends the given lisp-code to emacs. Emacs evaluates this code and returns a value.

pathName setxscroll totalUnits windowUnits firstUnit lastUnit
    This command is called to set the x-scrollbar to the correct size and position. Usually this command is only called by the emacs code.

pathName setyscroll totalUnits windowUnits firstUnit lastUnit
    This command is called to set the y-scrollbar to the correct size and position. Usually this command is only called by the emacs code.

pathName startemacs
    This command starts the emacs that is linked with the emacs widget. This is usually done automatically, when the widget is created.

pathName stopemacs
    This command stops the emacs that is linked with the emacs widget. This is usually done automatically, when the widget is destroyed.

pathName tag option ?arg arg ...?
    Not implemented.

pathName updatescrollbars
    This command updates the scrollbars of the emacs widget.

pathName xview ?-pickplace? what
    This command changes the view in the widget's window so that the column given by what is visible in the window. What may be an absolute column number, that is used in the commands issued by scrollbars to control the widget's view.

pathName yview ?-pickplace? what
    This command changes the view in the widget's window so that the line given by what is visible in the window. What may be an absolute line number, that is used in the commands issued by scrollbars to control the widget's view.

BINDINGS

The TkEmacs widget does not define any bindings for the widget. The only special binding is for the button press. To get the input focus to the emacs widget, you have to press a mouse button in the emacs widget. If you don't press the mouse button, the input will be redirected to the widget that currently has the input focus.

COMPATIBILITY

The TkEmacs widget tries to be as compatible to the text widget as possible. The following features are not implemented:

    tags,

    marks,

    scan,

    indices with multiple modifiers,

    and some more I forgot to mention :-).

The following resources are not implemented:

    -exportselection,

    -insertborderwidth,

    -insertofftime,

    -insertontime,

    -insertwidth,

    -padx,

    -pady,

    -selectbackground,

    -selectborderwidth,

    -selectforeground,

    -setgrid,

    -state,

    -wrap.

IMPLEMENTATION

We tried to keep the changes to Tk and emacs as small as possible. The changes to Tk only add the TkEmacs widget to the known commands. If you don't use the TkEmacs widget, you will not notice any changes compared to the standard wish (only tclRawTCP is new :-). In emacs all changes are only active if you call emacs with a special new option. If you don't call emacs with this option, you should not notice any changes compared to emacs.

The basic concept of this widget is, that the TkEmacs widget provides a window id that emacs uses for its displaying instead of making a own new window. Emacs creates a local window that is not mapped, from which it receives X11 events. This window id is passed to the TkEmacs widget. The widget forwards all events to this window id that are interesting for emacs.

Beside this mechanisms for passing X11 events and displaying the output of emacs in the widget window, the communication between the widget and emacs is done via a tcp connection. The communication follows a simple protocol.

Each line that is sent via the communication channel begins with a special token. There are five types of tokens.

CMD:
    This token indicates that the following data is a command that is to be evaluated by Tcl/Tk or emacs. A command can consist of many lines each beginning with this token. The end of the command is represented by the token END:. The evaluation of a command produces a result string that is returned with the token RET:.

RET:
    This token indicates that the following data is a result from a command execution. This returned data can also be a number of lines terminated with a final END:.

ERR:
    This token indicates that the following data is an error message. An error message is only one line, and is not terminated with END:.

RST:
    This token resets the communication channel.

END:
    As already explained the tokens CMD: and RET: are terminated with this token. This token follows on the next line.

PERFORMANCE ISSUES

Performance is a critical point with the TkEmacs widget. Each created widget has a complete emacs process. That means you should be careful with the number of widgets. The handling of the scrollbars leads to a relatively high traffic between emacs and the widget. On slow machines this will make scrolling a pain. On these machines it is probably a better solution to switch off the permanent updating with the option -useadvice.

BUGS

•   The byte compiled version of cl.el that is distributed with emacs 18.59 seems to make problems. To get a working TkEmacs remove the file cl.elc and recompile cl.el.

•   If the Emacs Lisp function "y-or-n-p" is called from a process filter, i.e. from the TkEmacs widget, it cannot be interrupted with C-g due to an already known bug in Emacs 18.58. On some machines this will result in the abort of Emacs (possibly with a core dump), on others in an endless loop with Emacs emitting an (also) endless loop of beeps. In this case it may be difficult to kill the process because the X server is busy beeping. In Emacs 18.59 this problem seems to be solved for some OS versions.

•   The connection between the TkEmacs widget and emacs is relatively loose. That means, that especially the scrollbar handling may not always be correct.

•   If event processing in wish is blocked for a long time, it can happen that the polling of the scrollbar destroys a previous result from emacs (at least that is the explanation I found :-).

•   On my System V Release 4 (Esix) I had massive problems with tclRawTCP. This was fixed by inserting an fprintf (I hate this kind of fixing). This fix is by default activated with the define: MY_SYSVR4_FIX in the file

•   Surely there are many bugs.

KEYWORDS
emacs, widget