REF XVED Jonathan Meyer, Apr 1991
Revised John Gibson Jan 1997
COPYRIGHT University of Sussex 1997. All Rights Reserved.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< THE X-BASED VED EDITOR >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This file documents the facilities provided by the XVed editor. This
editor is built on top of the Poplog Ved editor, but with enhancements
that make full use of the windowing facilities of the X Window System.
This is a comprehensive guide to the XVed system. If you have just
started using XVed, you should read the section Loading and Running XVed
first. TEACH * XVED will give you a basic outline of the XVed system and
documentation.
CONTENTS - (Use <ENTER> g to access required sections)
1 "Flavours" of XVed
1.1 Vanilla XVed
1.2 Motif and OpenLook XVed
2 Loading and Running XVed
2.1 Loading XVed
2.2 Making Ved Use XVed
2.3 Server Keyboard Setup
2.4 XVed Initialisations when Ved is Run
2.5 The XVed Standalone Saved Image
3 XVed Resources
3.1 XVed Window Structure
3.2 Setting Resources
... xved_value
... vedset xved
... <ENTER> window
3.3 Application Settings
3.4 General Window Settings
3.5 Next & Default Window Settings
3.6 Special Icon Resources
3.7 Event and Key Mapping Tables
4 Keyboard Handling
4.1 Specifying Key Mappings via Event Translation
4.2 vedset keys
5 Mouse Handling
5.1 Events in a Button Dialog
5.2 vedset mouse
6 Selections & The Clipboard
6.1 The Clipboard
6.2 Selections
7 Menu Specifications
8 GUI Specific Information
8.1 OpenLook
8.2 Motif
8.3 Reverse Video
9 XVed and the Window Manager
10 XVed Internal Event Handling
10.1 Button Events
10.2 Other Events
11 Caveat
---------------------
1 "Flavours" of XVed
---------------------
The XVed interface comes in three different forms, to support three
different levels of GUI:
¤ vanilla A multi-window version of Ved.
¤ motif vanilla plus Motif menus, scrollbars and dialogs
¤ openlook vanilla plus OpenLook menus, scrollbars and dialogs
The "vanilla" level of support is the basic starting point for XVed.
Motif and OpenLook add additional features on top of the Vanilla
version, such as dialog boxes and popup prompts.
1.1 Vanilla XVed
-----------------
In its basic "vanilla" form, XVed includes the following:
¤ a single window for each Ved buffer that is being edited
¤ customisation of window fonts, colours, and many other attributes
¤ facilities for interacting with Ved via the mouse
¤ support for OpenLook drag-and-drop
¤ interclient cut and paste via the X clipboard
¤ iconifying, resizing, raising and otherwise managing Ved windows
Reasons for wanting to use the vanilla version of XVed include:
¤ greatly reduced memory usage and disk space usage
¤ independence from Motif or OpenLook widgets
¤ increased speed of window creation due to fewer widgets
1.2 Motif and OpenLook XVed
----------------------------
The following additional components are available in the Motif and
OpenLook versions of XVed:
1) Scrollbars
Each buffer has a vertical and/or horizontal scrollbar attached to
it. The scrollbar is used to position the insertion point in the Ved
buffer.
2) A Popup Menu
By default this menu is attached to the third mouse button. This menu
is shared by ALL the XVed windows (and on the OpenLook version
includes a pushpin so that it can be pinned to the workspace).
This menu is described by the list held in the "Menu" application
setting (which can only be set from Poplog, not from .Xdefaults).
(The popup menu is also available when running a Motif or OpenLook
XVed in vanilla mode.)
3) Dialogs
---------------------------
2 Loading and Running XVed
---------------------------
In a standard Poplog system, XVed is incorporated into the 'startup.psv'
image run by pop11, prolog, etc. The next section applies only if you
wish to load XVed into basepop11.
2.1 Loading XVed
-----------------
The command:
uses xved;
will load XVed if it is not already loaded. To load XVed, you will
require Poplog 14.1 or later, and static X toolkit and X11 libraries.
Additionally, XVed can be used with Motif or OpenLook widgetsets.
Note that XVed cannot be loaded when:
¤ Ved is currently running
¤ You are using anything earlier than Poplog 14.1
When you load XVed, and if sysxsetup contains its default value,
sysxsetup will be redefined as xvedsetup. This allows you to make saved
images including xved, and then start them with the %x option (see
REF * SYSTEM).
XVed itself is entirely user-level Pop-11 code (although there are hooks
in the system that have been added explicitly with XVed in mind). If you
load XVed before starting the X toolkit, you can safely make a saved
image containing XVed (although the %nort option should be used to start
the Poplog system so that runtime actions are delayed until the saved
image is run).
The script $popcom/mkxved is an example of how to make a standalone XVed
saved image.
The following example makes a simple saved image that starts XVed when
restored:
pop11 %nort
: uses xved
Loading Sussex XVed
<loading messages>
Loaded XVed
: if syssave('xved.psv') then
: syssetup();
: xvedsetup();
: 'myfile.p' -> vedargument; chain(ved_ved);
: endif;
You can control which version of XVed (and which features of that
version) is loaded by defining the variable XVED_LOAD_OPTIONS before
loading the XVed system.
XVED_LOAD_OPTIONS [variable]
This (initially undefined) variable can be used to control which
aspects of XVed are loaded. It should be a list of words, where
the first element of the list is one of:
¤ vanilla
¤ openlook
¤ motif
In addition, various units within XVed can also be requested by
adding additional words to XVED_LOAD_OPTIONS:
¤ scrollbars
¤ menubar
¤ dialogs
If this constant is undefined when LIB * XVED is loaded, XVed
will provide a default value based on the information found in
INCLUDE * XDEFS. For example, on systems with OpenWindows, the
default value of XVED_LOAD_OPTIONS is:
[openlook scrollbar menubar dialogs]
Once XVed has finished loading, it will cancel the
XVED_LOAD_OPTIONS identifier, although the value of the constant
xved will be set to the head of the XVED_LOAD_OPTIONS list, so
that programs can test which flavour of XVed is loaded.
NOTE: It is possible to load XVed in segments. You can have a
series of layered saved images where the first image contains
"vanilla" XVed, and subsequent layers contain either "openlook"
or "motif" XVed units. You do this by setting XVED_LOAD_OPTIONS
to be the desired segment, and then explicilty using LIB * XVED
to force XVED to reload:
vars XVED_LOAD_OPTIONS = [vanilla];
lib xved;
;;; make saved image here
vars XVED_LOAD_OPTIONS = [openlook scrollbar];
lib xved;
;;; make second saved image here
2.2 Making Ved Use XVed
------------------------
You cannot start using XVed until the procedure xvedsetup is called:
xvedsetup() [procedure]
This procedure initialises XVed and the X Toolkit, opens a
connection to the X server, fetches a keyboard setting library
relevant to the server, and prints out a banner (if appropriate). It
also sets up Ved to use XVed when Ved is started.
When XVed is loaded, xvedsetup is added to * sysxsetup (which in the
normal system also contains the initialisation procedure for the Poplog
User Interface). Thus in the normal system, running
pop11 %x
or
prolog %x
etc, will execute xvedsetup as part of sysxsetup.
Alternatively, you can omit the %x flag and call either xvedsetup or
sysxsetup explicitly.
2.3 Server Keyboard Setup
--------------------------
During xvedsetup, XVed will attempt to determine what type of keyboard
it is being attached to, and pick up a key binding library which is
appropriate. The current server key library is held in the variable
vedserverxvedkeys.
Initially, the X server VendorString is examined, and a key mapping may
be based on this string. Unfortunately, all MIT X servers have the same
server vendor string, so this information is not always going to work.
If the first check was unsuccessful, the next test is that the server is
on the local machine - if this is the case, XVed will use a key mapping
library suitable for the machine based upon the sys_machine_type.
Finally, if this fails, XVed makes some crude guesses based upon the
name of the host that it is connecting to.
If all of this fails, the value of vedserverxvedkeys when xvedsetup is
first called is used. This means that the last xved key library you
manually load will get picked up (each xved key library assigns its
keybinding procedure to vedserverxvedkeys).
Finally, there is a reasonable (if different) default binding for keys
if no server keyboard binding is found (see HELP * XVEDKEYS).
The following are the supplied xved key libraries:
vedxvedkeys see HELP * XVEDKEYS
vedncdxvedkeys see HELP * NCDXVEDKEYS
veddxvedkeys see HELP * DXVEDKEYS
vedsunxvedkeys see HELP * SUNXVEDKEYS
vedhpxvedkeys see HELP * HPXVEDKEYS
2.4 XVed Initialisations when Ved is Run
-----------------------------------------
When Ved is started, * vedsetup calls the procedure * vedinitterm, which
normally calls * veduseterm to set up the keyboard and screen for the
appropriate terminal type.
In XVed mode (i.e. after xvedsetup has been called), vedinitterm is
redefined so that in addition to calling veduseterm('xved'), it first
calls the user-definable procedure vedxvedinit:
vedxvedinit() [procedure variable]
This variable procedure is called by the XVed version of
* vedinitterm, immediately before calling veduseterm('xved'). It
may be used to initialise XVed resource and mouse bindings.
XVed resource bindings may be set with vedset xved, and mouse
bindings with vedset mouse (see sections below).
By default, vedxvedinit is a procedure which just calls
* vedxvedmouse to set up the standard mouse bindings. Therefore,
if you redefine vedxvedinit, and you want the standard mouse
bindings, you must make your vedxvedinit call vedxvedmouse
explicitly. (Note that the behaviour of vedxvedmouse is affected
by some XVed application resources, hence resource bindings
should always be done first.)
Note that (as for other versions of Ved), key bindings should go
into your * vedinit procedure or be specified as Ved runtime
actions. (You can also deal with mouse and non-application
resource bindings in this way, but application resource bindings
should always be put in vedxvedinit.)
2.5 The XVed Standalone Saved Image
------------------------------------
The XVed standalone saved image is primarily useful when you wish to run
XVed either from a window manager menu or as the editor for some other
application.
The script $popcom/mkxved is used to build the saved image. Once this is
made you can type:
% pop11 +xved [file ...]
or just
% xved [file ...]
to edit a file using XVed.
The XVed saved image calls the procedure xved_standalone_setup when it
is restored. This procedure processes command line options, starts up
XVed, opens the specified files, and goes into a loop processing XVed
input until there are no files or input:
xved_standalone_setup() [procedure]
Initialises XVed, processes any arguments in * poparglist, and
goes into a loop waiting until the Ved input stream and buffer
list is empty, whereupon it exits from XVed and Poplog.
The XVed saved image calls this procedure on startup to process
arguments and run XVed. The procedure handles a variety of
command line options, which fall into 3 categories: special
options, X toolkit options, and file options.
Special Options
The following options are handled before other command line
option processing takes place:
-help
Prints out a usage message for the command and then
exits.
-im
Starts an 'immediate mode' buffer (see HELP * VED_IM
before editing any of the specified files. Immediate
mode buffers are useful for typing commands to one of
the Poplog compilers.
-stdio filename
Sets * ved_chario_file so that any input or output on
Poplog standard devices (pop_charin_device and
pop_charout_device) is redirected to the Ved buffer with
the specified name. This allows you to simulate having
standard input and output devices even when XVed was
started in a script or from a menu.
If you specify a stdio file, popdevin and popdevout are
set to /dev/null.
This option is recommended if you want to start XVed
from a window manager menu or a session startup script.
Toolkit Options
All of the standard X Toolkit arguments can used. See MAN * X
for a list of the options and their arguments. The following
lists some of the options:
-display displayname
Allows you to connect to a remote X server, passing the
name of the X server on the command line.
-fn name, -font name
Specifies the default font to use for windows.
-geometry geom
Sets the initial geometry for XVed windows. You can
specify the number of columns and rows and the X and Y
coordinates of the window, and also specify the location
of the icon.
-iconic
Sets the initial state of the Ved windows to iconic, so
that new windows appear as icons.
-xrm string
Allows you to specify additional X resources on the
command line.
File Options
After processing special and toolkit options, the rest of the
contents of the command line options in * poparglist are treated
as file options and files. You can specify zero or more file
options or files. The file options and files are processed in
sequence. For each option or file an appropriate action is added
to Ved's input stream:
-do command
Adds an action to call * veddo on command. This option
can be used to perform one or more Ved <ENTER> commands.
=line_number, = line_number
Adds an action to sets * vvedgotoplace so that, for the
next file, XVed will automatically go to the specified
line number.
filename
Adds an action to edit the specified file.
Examples
The following starts XVed and fetches a few documentation files:
xved -do 'help initial' -do 'help xved'
The following edits your login file at line 10, and then sets
vedwriteable to false for that file:
xved =10 ~/.login -do ':false -> vedwriteable'
To start xved in inverse video with a large font, use:
xved -fn 9x15 -rv
-----------------
3 XVed Resources
-----------------
The resource values that control the behaviour of XVed are of two kinds:
"application" settings (which affect all windows), and per-window
settings for default window, next window and current window. Default
window settings can be set for different classes and types of window.
The values of all XVed resources can be set inside Poplog with vedset
xved (or the procedure which that calls, xved_value). Most (but not all)
can also be set with the usual X resources mechanism (i.e. in your
.Xdefaults).
Note that xved_value settings take precedence over .Xdefaults settings.
However, there are no xved_value settings by default , and all default
values are set at the .Xdefaults level. (Except for those resources that
are xved_value-only.)
3.1 XVed Window Structure
--------------------------
A single top level (iconifiable) XVed window will be created each time
Ved opens a new buffer (or rather, when the buffer is set 'onscreen').
The XVed window (held in the variable * wvedwindow) is in fact an X
Toolkit "Widget" -- see REF * XpwScrollText for details of the Text
widget XVed uses to display its buffers. (It will therefore respond to
calls of things such as XtVaSetValues, etc. Use this knowledge with care
-- XVed will not respond kindly if you call XtDestroyWidget to kill a
Ved window.)
An XVed window is in fact a structure of three widgets, as follows
(where wvedwindow is the Text widget):
Widget Resource Class Resource Name
------ -------------- -------------
Shell XVed xved
|
Wrapper (see below) xved_value class setting
|
Text XpwScrollText xved_value type setting
The resource names of the Wrapper and Text widgets are set from the
class and type settings from xved_value (see General Window Settings
below), and depend upon the file.
The 'Wrapper' widget is different for the different flavours of XVed --
in the Vanilla version it is an XpwComposite widget containing just the
Text widget, but the Motif and Openlook versions use other wrapping
widgets which also contain scrollbars and/or a menubar.
Thus the resource class of the Wrapper should be treated as unknown, and
when specifying resources in .Xdefaults you should use either the
resource name for that component or "*", e.g.
XVed*font: 9x15
XVed.Program*font: 6x13
The corresponding vedset xved form would be
vedset xved
[] font = '9x15'
[Program] font = '6x13'
endvedset;
3.2 Setting Resources
----------------------
The main programming interface to XVed is, like the X Toolkit itself,
via a value fetching/setting procedure xved_value. The vedset xved form
provides a simple syntactic interface to xved_value.
... xved_value
---------------
xved_value(context, name) -> item [procedure]
xved_value(context, name_list) -> (item1, ..., itemN)
item -> xved_value(context, name)
item1, ..., itemN -> xved_value(context, name_list)
This procedure is used to customise XVed windows and XVed
itself. If context is a word, it must be one of:
"application" specifies global XVed settings
"currentWindow" dynamically change current window settings
"nextWindow" specify settings for next created window
"defaultWindow" specify default window settings
Instead of "defaultWindow", context may also be a list
[class type]
to specify that "defaultWindow" resources are constrained to a
particular window class and type. Either class or type may be
the word "*" to match any class/type, and trailing "*"s in the
list may be omitted (hence [] is the same as "defaultWindow").
(context may also be a Ved file structure or an XVed window
structure to set values for that file/window.)
The last argument may be either a single value name (i.e. a
word), or a list of them. For a list of length N, N values are
returned or updated. The value names are specific to each
context, though all of the Window types share many setting
names.
The "application" context refers to XVed variables that users
can modify. Application settings can be specified at startup
time in your * vedxvedinit procedure, or in your .Xdefaults
file, using a resource line like:
XVed.name: value
For example, the following specifies the WarpContexts setting:
XVed.WarpContexts: [ved_ved ved_rb vedfileselect]
The "currentWindow" setting refers to the window held in the
variable wvedwindow. xved_value will dynamically change
attributes such as fonts, colours and cursors for XVed windows.
This lets you for example increase the size of the font used in
a window to make it more legible.
Both the "nextWindow" and "defaultWindow" settings are in fact
pseudo-windows -- they don't refer to actual X windows.
The "nextWindow" setting contains a set of attributes which are
used when the next Ved window is created, and then cleared. Many
of the "nextWindow" settings can also be applied to the
"currentWindow", although there are additional settings which
can only be specified when new windows are created. Note that
the "nextWindow" is consulted AFTER vedveddefaults is called for
a new file, so users can write things in their vedinit.p like:
define vedveddefaults;
#_IF DEF xved ;;; only compiled if XVed is loaded
if vedusewindows == "x"
and isstartstring('/tmp', vedpathname) then
'cross' -> xved_value("nextWindow", "pointerShape");
endif;
#_ENDIF
enddefine;
"defaultWindow" is perhaps the most special context. It is used
to specify fallback defaults for XVed. "defaultWindow" settings
can contain the same types of values as "nextWindow" and
"currentWindow" settings. However, they can also be procedures,
in which case the procedures are called to dynamically generate
the default value for an attribute. Such dynamic defaulting
procedures take the form:
default_p() -> default_value
The default_p will get called from within the window creation
procedures, and in other places when a new value is needed. At
the stage when it is called, the environment for the Ved buffer
will have been created - so variables such as vedpathname will
be set correctly for the buffer.
Many of the slots in "defaultWindow" start with XVed-supplied
dynamic defaulting procedures, which are used to create things
such as window names, icons, etc. A dynamic defaulting procedure
should return a default_value which is of the correct type for
the setting, based on the current values of Ved variables. For
example, this is the XVed-supplied dynamic defaulting procedure
for generating icon labels:
define make_icon_label;
;;; return icon label for current window
sys_fname_name(vedpathname);
enddefine;
;;; install dynamic defaulting procedure
make_icon_label -> xved_value("defaultWindow", "iconName")
As well as default values for windows, the "defaultWindow" also
holds two special tables, the "eventTable" and the
"keyMapTable". See below for details.
For "nextWindow" and "defaultWindow" types, a setting can have
the special value "undef" to indicate that no value is provided.
With "undef" settings, the settings will be derived from the
widget's default values, or from the users .Xdefaults
specifications. Settings applicable to "nextWindow" and
"defaultWindow" can be specified in the users .Xdefaults using
the resource line:
XVed*name: value
For example, the following will set the font of all XVed buffers
to '9x15':
XVed*font: 9x15
The following examples illustrate the sort of things you can do
with xved_value:
;;; set the main (colour 0) colours of the window ...
'orange', 'blue' -> xved_value("currentWindow",
[foreground background]);
;;; ... specifying the status line colours in RRGGBB format
'#666688', '#ffff88' -> xved_value("currentWindow",
[statusForeground statusBackground]);
;;; change the mouse pointer shape for the window
'cross' -> xved_value("currentWindow", "pointerShape");
;;; set the location of the next window Ved makes:
150, 200 -> xved_value("nextWindow", [x y]);
;;; disable mouse warping:
true -> xved_value("application", "WarpPointer");
;;; set default colours for all windows ...
'black', 'white' -> xved_value([], [foreground background]);
;;; ... and a different default for class Documentation
'red', 'yellow' -> xved_value([Documentation],
[foreground background]);
... vedset xved
----------------
vedset xved is a simple syntactic interface to * xved_value. It has the
form
vedset xved
context
resource_name = value
resource_name = value
.....
context
resource_name = value
resource_name = value
.....
.....
endvedset
where each assignment of value to resource_name is for the preceding
context.
context is the same as the context argument to xved_value, and can be
one of
application
defaultWindow
nextWindow
currentWindow
Instead of defaultWindow, context may also be a list [class type] to
constrain the following assignments to windows of a particular class and
type. Either class or type may be * (to match any), and trailing
asterisks in the list may be omitted (thus all of [* *], [*] and [] are
equivalent to defaultWindow).
For each resource_name, value must be a single Pop-11 lexical item. If
value is a word, it is converted to a string, with the special exception
that the words true and false are converted to the corresponding boolean
values. Anything that is not a single Pop-11 lexical item must be
specified as a quoted string.
Note that context, resource_name and value all undergo macro expansion
(with autoloading disabled). value may also be % expression % to mean
the result of evaluating the Pop-11 expression.
For example,
vedset xved
application
WarpPointer = true
[]
foreground = black
background = white
pointerShape = cross
geometry = '80x48'
[Documentation]
foreground = red
background = yellow
geometry = '74x24'
[Documentation help]
foreground = blue
[Select]
autoGeometry = '120x48/20x8'
endvedset;
... <ENTER> window
-------------------
There is also a simple Ved interface to altering window resources via an
extension to the ved_window command. See HELP * ved_window for more
details.
3.3 Application Settings
-------------------------
AlwaysRaiseWindow [xved value name]
Boolean, default false. If true, XVed will try and ensure the
window you are editing in is always fully visible, by raising it
to the front of the screen.
AutoWindowPlacement [xved value name]
Boolean, default false. If true, XVed will place windows
starting at the top left corner of the screen, alternating left
and right across the screen, staggered downwards and inwards
towards the centre, thus:
Ư----+ +---DŽ+
|Ʊ---++ ++--dž+|
||Ƴ---++ ++--Lj+||
+|| | | ||+
+| | | |+
+-----+ +-----+
If AutoWindowPlacement is false, each window will be placed in
accordance with any geometry resource specification for it.
AutoCut [xved value name]
Boolean, default true. If this resource is true, XVed will
automatically perform a 'cut' on selected text when you start
typing. This allows you to select some text and then replace it
quickly by typing over it. Also, hitting a key bound onto
vedchardelete while there is an active selection will cut the
selection instead of deleting a character.
If the resource is false, typing while there is an active
selection will just cancel the selection.
BellVolume [xved value name]
Integer, value 0-100, default 100 This setting specifies the
loudness of the beep generated by vedscreenbell in XVed. 100 is
full volume, and 0 is silent.
DialogForeground [xved value name]
DialogBackground [xved value name]
These settings control the foreground and background colours of
XVed specific dialog boxes (ie, all dialog boxes not supplied by
the Poplog User Interface --- see HELP * POPLOG_UI.) The default
values for these settings are XtDefaultForeground and
XtDefaultBackground.
EditKeysEnabled [xved value name]
Boolean, default false. Some keyboards (notably Sun type 4
keyboards) have keys marked Cut, Copy and Paste. These keys are
historically used for different purposes by Ved. The (default)
value of false causes XVed to use the traditional key bindings.
The value of true causes XVed to make the Cut, Copy and Paste
keys work on the current selection. Changing this resource
invokes a call to vedset.
KeypadKeysEnabled [xved value name]
Boolean, default true. On terminals with keypads, setting this
attribute false will make the keypad behave like a numeric
keypad rather than sending cursor control sequences.
MaxWindows [xved value name]
Integer, default 1000000. XVed will limit its use of windows to
this number.
Whenever a window is to be created for a new or existing file,
and there are already MaxWindows windows, the last file on
vedbufferlist that currently has a window will have its window
destroyed. The new window then replaces it, in the same screen
position.
MenuForeground [xved value name]
MenuBackground [xved value name]
These settings control the foreground and background colours of
the popup menu. Their default values are XtDefaultForeground and
XtDefaultBackground respectively.
MultiClickTimeOut [xved value name]
Integer, default 200. Time interval in milliseconds used for
multiple button click detection.
PopFocusOnly [xved value name]
Boolean, default false. If this is true, XVed will warp the
pointer and/or input focus to a window ONLY if it can determine
that a Poplog window currently has the input focus -- that is,
regardless of the values of WarpPointer and SetInputFocus, it
will not steal the pointer/focus away from a non-Poplog window
receiving keyboard input.
NOTE, however, that in order for XVed to be able to identify the
Poplog base (i.e. terminal) window as 'belonging' to Poplog, the
environment variable/logical name WINDOWID must be set to its X
window ID. This is done automatically by xterm in Unix. (But
not, unfortunately, by the corresponding terminal emulator in
VMS. Even in Unix, WINDOWID will not be available if Poplog is
running on a different machine from the xterm.)
If WINDOWID is not set, PopFocusOnly being true will therefore
prevent XVed warping pointer/focus to a window Ved'ed from the
base window.
ResourceFile [xved value name]
String. Its default value is:
$HOME/.Xdefaults.
This setting should be the filename of the resource database
that default settings should be saved in by <ENTER>
savedefaults.
SearchDoesSelect [xved value name]
Boolean, default false. If this is set to true, then performing
a search using <ENTER>/, <ENTER>" etc. causes the matching text
to be highlighted and selected. See REF * VEDSEARCH
SetInputFocus [xved value name]
Boolean, default true. Specifies whether XVed should set the
input focus when Ved switches to a new window. If this setting
is false, XVed will not explicitly set the input focus when a
window is entered.
In a click-to-type regime, it makes sense to have WarpPointer
false and SetInputFocus true. In a pointer-following regime, you
should usually have both true or both false, so that the pointer
and the focus always stay together. (See also PopFocusOnly.)
SetLineBreakOnResize [xved value name]
Boolean, default false. If true, XVed will adjust the point at
which lines are broken to be close to the right edge of the
window you are editing in, whenever the window is resized.
ShowFileName [xved value name]
Boolean, default true. If true, XVed will display the string
* vednamestring as the default message on the status line: this
contains the name of the file being edited.
If false, no message is displayed by default. You may find this
preferable if you have window manager title bars on your
windows, since the vednamestring information is displayed in
those also.
StatusAtTop [xved value name]
Boolean, default true. If true, XVed will display the status
line at the top of each window, otherwise at the bottom.
UseOldMouseBindings [xved value name]
Boolean, default true for Openlook, false otherwise. Setting
this value to true will restore the default mouse bindings prior
to Version 15+.
UsePwmMouseBindings [xved value name]
Boolean, default false. Setting this value to true will modify
the mouse bindings used by LIB * VEDXVEDMOUSE to be more like
those provided by LIB * VEDMICE.
UseXVedIcons [xved value name]
Boolean, default true. If true, XVed windows will have special
pictures for their icons (illustrating the type of window, i.e.
"help", "ref" etc).
If false, no special icons are created, and you get whatever
style of icon the window manager gives you. (This saves a bit on
memory resources, makes window creation a little faster, etc.)
VScrollStep [xved value name]
HScrollStep [xved value name]
Integer, default 1 (for both). These variables control the step
size for vertical and horizontal scrolling respectively. That
is, when scrolling a file up/down L lines or left/right C
columns, XVed will do the scroll in steps of the size given.
Setting these variables to values of 2 (or even 3) will give
faster scrolling, especially on colour machines. (However, as
the step size increases, the effect is less smooth.)
Vanilla [xved value name]
Boolean, default false. If true, specifies that XVed should
operate in vanilla mode even when the Openlook or Motif parts of
XVed are loaded -- that is, no scrollbars, menubars or dialog
boxes.
(Vanilla mode generally uses less resources, requires the
creation of less widgets, and is therefore faster, etc. Note
that you can also turn off scrollbars/menubars with the
per-window menubarOn, scrollbarOn and hscrollbarOn resources --
these will only be created when turned on.)
WarpPointer [xved value name]
Boolean, default false. Specifies whether XVed should warp the
pointer when Ved switches to a new window. If this setting is
false, XVed will never cause the X mouse pointer to be moved.
In a click-to-type regime, it makes sense to have WarpPointer
false and SetInputFocus true. In a pointer-following regime, you
should usually have both true or both false, so that the pointer
and the focus always stay together. (See also PopFocusOnly.)
WarpContexts [xved value name]
List or Boolean (default true). A List of words specifying when
Ved is allowed to warp the input focus or mouse. See
* vedwarpcontext for details.
3.4 General Window Settings
----------------------------
The following settings are available on "currentWindow", "nextWindow"
and "defaultWindow" contexts:
foreground [xved value name]
background [xved value name]
statusForeground [xved value name]
statusBackground [xved value name]
highlightForeground [xved value name]
highlightBackground [xved value name]
color2Foreground [xved value name]
color2Background [xved value name]
color3Foreground [xved value name]
color3Background [xved value name]
color4Foreground [xved value name]
color4Background [xved value name]
color5Foreground [xved value name]
color5Background [xved value name]
color6Foreground [xved value name]
color6Background [xved value name]
color7Foreground [xved value name]
color7Background [xved value name]
color0AForeground [xved value name]
color0ABackground [xved value name]
color1AForeground [xved value name]
color1ABackground [xved value name]
color2AForeground [xved value name]
color2ABackground [xved value name]
color3AForeground [xved value name]
color3ABackground [xved value name]
color4AForeground [xved value name]
color4ABackground [xved value name]
color5AForeground [xved value name]
color5ABackground [xved value name]
color6AForeground [xved value name]
color6ABackground [xved value name]
color7AForeground [xved value name]
color7ABackground [xved value name]
These colours are used to paint the text in a Ved window.
foreground and background are the basic (colour 0) window
colours for the whole window excluding the status line;
statusForeground" and statusBackground are colour 0 for the
status line.
The remaining colours are used for text that has attributes
containing the colour numbers 1 - 7 (without the 'active'
attribute) and colour numbers 0A - 7A (with the active
attribute). The highlight- colours are in fact colour number 1
(and are so called for backward compatibility reasons).
To provide some sort of standard for the use of colours on
colour displays, and to allow sensible behaviour for monochrome
displays, Ved uses the convention that the even-numbered colours
2(A), 4(A), and 6(A) are 'foreground-only' (i.e. have the usual
background), whereas the odd-numbered colours 1(A), 3(A), 5(A),
and 7(A) change the background as well.
In accordance with this, XVed is set up so that
¤ On a monochrome display, the resources for colours 2 - 7 and
0A - 7A are not used. The even-numbered colours will display
as the basic colours, whereas the odd-numbered ones will
display as colour 1 (which is the basic colours inverted,
i.e. inverse video).
¤ On a colour display, the backgrounds of the even-numbered
colours default to the basic background colour (i.e.
background or statusBackground).
For colour displays, XVed provides a default set of colours
which are set as 'fallback' resources (which means they will NOT
be used if there is an 'app-defaults' file for XVed). These are
color2Foreground: red color3Foreground: yellow
color3Background: red
color4Foreground: green4 color5Foreground: yellow
color5Background: green4
color6Foreground: blue color7Foreground: white
color7Background: blue3
color2AForeground: brown color3AForeground: coral
color4AForeground: olivedrab4 color5AForeground: green3
color6AForeground: slateblue3 color7AForeground: dodgerblue
(The backgrounds for the odd-numbered active colours are not
set, so they default to the basic foreground, i.e. foreground or
statusForeground.)
Note that apart from the above fallback resources (and in the
absence of any other settings, e.g. in a user .Xdefaults), the
resources for colours 1 - 7 and 0A - 7A will be empty, i.e. have
the value -1. They do not have X resource class XtCForeground or
XtCBackground, and are not initialised by the Text widget
either. (In accordance with the colour convention described
above, empty components for even colours will use the
corresponding colour 0 component, whereas empty components for
odd colours will use the colour 1 component. The colour 1
components themselves default to the inverse of the colour 0
components, i.e. colour 1 by default is 'reverse video' on
colour 0.)
On the other hand, the colour 0 resources will always be
initialised to something, since they all have class
XtCForeground or XtCBackground, and have widget defaults as
well, viz
Resource Class Default
-------- ----- -------
foreground XtCForeground XtDefaultForeground
background XtCBackground XtDefaultBackground
statusForeground XtCForeground XtDefaultForeground
statusBackground XtCBackground XtDefaultBackground
(N.B You can assign a valid X colour string such as 'red' or
'blue' or '#1a2b3f' to any colour resources, but you will NOT
get a string back if you fetch the value of the setting for
"currentWindow" (it will return the X pixel value for the
colour).
cursorColor [xved value name]
Specifies the colour of the text cursor when drawn in normal
colour, i.e. colour 0 (if the cursor character given to
vedscreencursoron specifies a colour 1 - 7, the foreground of
that is used).
Setting this resource to -1 (empty) will cause the row-dependent
colour 0 foreground to be used instead (statusForeground when on
the status line, and foreground otherwise).
selectionColorNum [xved value name]
The colour number (0 - 7) to be used for highlighting
selections. The default value is 1, which selects
highlightForeground/Background.
y and x [xved value name]
These integer settings are used to control the location of an
XVed window on the screen. The x and y settings refer to the
distance in pixels from the top left corner of the screen to the
top left corner of the (whole) XVed window.
numRows [xved value name]
numColumns [xved value name]
The numRows and numColumns settings specify the width and height
of the Ved buffer in terms of rows and columns (remember that
the status line takes up one row, and the start character of
each buffer line is also used). Thus the view area of the text
is (numRows-1, numColumns-1).
geometry [xved value name]
This integrates the x, y, numRows and numColumns settings into a
standard X geometry string, i.e.
[numColumns][xnumRows][+x+y]
where brackets [...] specify optional parts. Assigning to it
changes any of the four resources that are specified in the
string.
Note that as an X resource in your .Xdefaults, you should always
use geometry rather than any of the individual ones, e.g.
XVed*geometry: 80x24
XVed.Documentation*geometry: 74x20+400+200
etc.
autoGeometry [xved value name]
Setting this resource for "nextWindow" or "defaultWindow"
specifies that a new window should be auto-sized on the basis of
the number of lines in the buffer and/or the maximum length of
any buffer line. (This resource is not applicable to
"currentWindow".)
The resource string is either an X geometry, or two X geometries
separated by a `/`, i.e.
[maxColumns][xmaxRows][/[minColumns][xminRows]]
where brackets [...] specify optional parts.
If maxColumns is present, the window width will be auto-sized.
numColumns will be set to the length of the longest buffer line
plus 2, but up to a maximum of maxColumns; the minimum width is
the greater of 12 or minColumns if present.
If maxRows is present, the window height will be auto-sized.
numRows will be set to the number of buffer lines plus 2, but up
to a maximum of maxRows; the minimum height is the greater of 4
or minRows if present.
For example:
120x48/20x8
specifies that both width and height should be auto-sized, with
maximum size 120x48 and minimum size 20x8. Alternatively,
120/20
specifies that only the width should be auto-sized. (I.e. the
height will default to whatever value if would have had
otherwise. Note that an auto-size value overrides any geometry
spec, except an explicit "nextWindow" one.)
You can use autoGeometry in your .Xdefaults (for example) to
auto-size windows produced by vedfileselect and ved_ls etc:
XVed.Select*autoGeometry: 120x48/20x8
hMargin [xved value name]
vMargin [xved value name]
The hMargin and vMargin specify the amount of padding space that
appears around the text (i.e. Ved) part of the XVed window, in
pixels.
Either one or both may also have a negative value, meaning use a
percentage of the corresponding character cell dimension, i.e of
the font width or font height. This allows the margins to grow
and shrink automatically with different font sizes.
The default values are -50 for hMargin (i.e. 50% of font width)
and -30 for vMargin (i.e. 30% of font height).
borderWidth [xved value name]
The margin around the text (i.e. Ved) part of the XVed window in
pixels. Default 1.
borderColor [xved value name]
The colour of the border around the text part of the XVed
window. Also used for the 1-pixel border around the status line.
font [xved value name]
boldFont [xved value name]
altFont [xved value name]
boldAltFont [xved value name]
These settings specify the X fonts to use for the XVed text
window. For example, '6x13' can usually be used for font. All
the fonts can be any size. (Including proportional, but this is
not likely to give very satisfactory results. Regardless of
their size, or whether fixed-width or proportional, all fonts
are drawn to the maximum spacing required by any of them.)
If specified, altFont should normally be an italic-style font or
something similar (this is what Poplog documentation assumes).
For example, the 6 x 12 font
-schumacher-clean-medium-i-*--12-*-*-*-c-60-*-1
could be used with '6x13' on MIT systems. Another possible
combination is
font: -b&h-lucidatypewriter-medium-r-*-*-14-*-*-*-m-90-*-1
altFont: -adobe-courier-medium-o-*--14-*-*-*-m-90-*-1
(both 9 x 14), or (specifying bold fonts as well),
font: -misc-fixed-medium-r-normal-*-13-*-*-*-c-70-*-*
boldFont: -misc-fixed-bold-r-normal-*-13-*-*-*-c-70-*-*
altFont: -adobe-courier-medium-o-*-*-12-*-*-*-m-70-*-*
boldAltFont: -adobe-courier-bold-o-*-*-12-*-*-*-m-70-*-*
which mixes 7 x 13 with 7 x 12.
If not specified (or set to 0), text in Ved buffers marked as
'alt font' will come out in the normal font but underlined.
(This also happens if altFont is the same as font.)
If specified, boldFont should be a bold version of font; if not
specified (or set to 0), bold text is drawn by 'overstriking'
with font. (Which also happens if boldFont is the same as font.)
Similiarily for boldAltFont versus altFont.
Changing any font will cause the window to resize to maintain
the same number of rows and columns.
noBlink [xved value name]
This boolean (default false) controls whether text in the window
with the 'blink' attribute actually blinks or not.
drawGraphicChars [xved value name]
This boolean (default true) indicates whether or not the
XpwScrollText widget representing the XVed window should draw
its own version of graphics characters (e.g. as used to paint
the status line and mark ranges). With this true, you can use
any fixed-width font(s) for an XVed window, regardless of
whether the font actually supports the graphics characters or
not.
(Note that the widget only supports those characters in the Ved
standard graphics set, i.e. the line-drawing characters and a
few others -- see Graphics Characters in REF * VEDPROCS.)
pointerShape [xved value name]
pointer2Shape [xved value name]
pointerShape controls which X cursor is displayed in the text
(i.e. Ved) part of an XVed window. It can be set to one of the
standard cursor shapes, as a string, though (like colours),
fetching this setting is not guaranteed to return a string
(currentWindow types will return the XID of the cursor).
pointer2Shape is an alternate pointer used when the mouse moves
into a 'text action' (see Embedded Text Actions in
REF * VEDPROCS).
pointerForeground [xved value name]
pointerBackground [xved value name]
Foreground and background colours to be used for the cursors
specified by pointerShape and pointer2Shape.
iconic [xved value name]
A boolean setting indicating whether the window is iconic or
not. Can be used to iconify a window. Can also be used to
specify that new windows should be created in iconified form.
menubarOn [xved value name]
scrollbarOn [xved value name]
hscrollbarOn [xved value name]
In Openlook and Motif XVed, these booleans control whether a
menubar (menubarOn), vertical scrollbar (scrollbarOn) and
horizontal scrollbar (hscrollbarOn) are displayed in the window.
(By default, menubarOn and scrollbarOn are true and hscrollbarOn
is false.)
scrollbarForeground [xved value name]
scrollbarBackground [xved value name]
menubarForeground [xved value name]
menubarBackground [xved value name]
Foreground and background colours to be used for the menubar and
scrollbars in Openlook and Motif XVed.
title [xved value name]
iconName [xved value name]
These strings specify the labels that appear on an XVed window
and its icon. Usually set by dynamic-defaulting procedures.
raised [xved value name]
A boolean setting that, when set, will cause an XVed window to
be raised to the front of the window stack. For nextWindow and
defaultWindow types, this setting is ignored. Fetching this
setting for the "currentWindow" will return true if the window
is unobscured by any other window, and false if it is partially
obscured, wholly obscured or iconified.
shellBorderWidth [xved value name]
Specifies the borderWidth for the XVed shell window, i.e. the
margin around the whole XVed window. It has no default value.
(This resource is xved_value-only; in .Xdefaults, you would set
this as XVed.borderWidth.)
translations [xved value name]
X Toolkit event translations for the text part of the window.
This resource may be either a string or a list of strings: if a
string is given, that is used unchanged.
A list is converted to a single string by concatenating the
given strings with a newline appended to the end of each except
the last. If the first string in the list is not one of
'#override', '#augment'or '#replace', then '#override' as added
as the default.
class [xved value name]
type [xved value name]
These two slots contain the resource names of the new buffer
'Wrapper' widget (the class setting) and the new buffer Text
widget (the type setting). Dynamic defaulting procedures are
used to create names based upon the type of the buffer. (Note
that you cannot update these values for "currentWindow", only
interrogate them.)
If vedfileprops is a word containing a `.` character, then the
part preceding the `.` is used as the class. Otherwise
(depending on vedfileprops), class is set to one of:
¤ Program
¤ Text
¤ Documentation
¤ Library
¤ Sourcefile
If vedfileprops is a word, the type is set to vedfileprops with
any leading 'Class.' part removed. If vedfileprops is false,
type is set to one of:
¤ pop11
¤ prolog
¤ lisp
¤ ml
for compilable files, and "ved" otherwise.
This allows you to specify resources for XVed windows in your
* vedxvedinit or .Xdefaults based upon this information. For
example, the following could be used to set colours and fonts
for several types of Ved buffer:
vedset xved
[Program]
font = '9x15'
[Text]
background = skyblue
[Library pop11]
background = pink
foreground = black
[Documentation ref]
pointerShape = cross
endvedset;
The equivalent .Xdefaults lines would be:
XVed.Program*font: 9x15
XVed.Text*background: skyblue
XVed.Library.pop11.background: pink
XVed.Library.pop11.foreground: black
XVed.Documentation.ref.pointerShape: cross
3.5 Next & Default Window Settings
-----------------------------------
In addition to the general settings listed above, the following
additional settings can be specified for "defaultWindow" or
"nextWindow" contexts:
iconX [xved value name]
iconY [xved value name]
These two settings are integers that specify the x and y
coordinates of the buffer's icon. By default these are undefined
Icon placement is left to the window manager.
iconWindow [xved value name]
Contains the XID of a Window which is to be the icon of the new
buffer, or false to specify no special icon for the buffer. A
dynamic-defaulting procedure for this setting creates icon
windows using bitmaps held in $usepop/pop/x/ved/bitmaps, based
on the vedfileprops of the new file.
3.6 Special Icon Resources
---------------------------
There are three resources for the foreground colour, background colour,
and font used by all XVed icons. These are not part of the xved_value
system and have to be specified in the users resource database file
(usually .Xdefaults or .xrdb). The resources and their default values
are:
XVed.Icon.foreground: <XtDefaultForeground>
XVed.Icon.background: <XtDefaultBackground>
XVed.Icon.font: <XtDefaultFont>
3.7 Event and Key Mapping Tables
---------------------------------
Two special resources, keyMapTable and eventTable, are used to specify
the mapping of keys and XVed internal events onto strings and procedures
respectively. Each XVed window can have its own keyMapTable and
eventTable -- accessing the table on the "currentWindow" or the
"nextWindow" for the first time causes it to be created.
XVed will consult a windows local table first, but if no entry for the
event or key name is found, XVed will also consult the tables with the
same name held in the "defaultWindow". The "defaultWindow" tables are
therefore very important -- they specify XVed-wide mappings for events
and keys.
--------------------
4 Keyboard Handling
--------------------
XVed translates X Key events into ASCII strings, which it adds to Ved's
input queue. For compatibility, function keys still send escape
sequences (although it would be perfectly possible to write X toolkit
actions that bypassed escape sequences altogether). However, these
escape sequences are not based on any traditional terminal emulator
escape sequences, but instead on the X KeySym number for the key.
XVed uses a fairly sophisticated series of rules to turn an X Key event
into something that is presentable to Ved (ie. the ASCII string or
escape sequence).
When a key is pressed, there are several sources of information for
determining what action to take. Each key is uniquely identified by an X
KeySym. This is an integer representing the key in a keyboard
independent way. Additionally, we are given the current state of
keyboard modifiers (shift, control, etc). There is also a string
representing what X thinks is the correct ASCII string for the key is.
The first thing the Key event handler does is to look for any entry
corresponding to the keysym of the key in the "keyMapTable" of both the
"currentWindow" and the "defaultWindow". Since these are the first
tables consulted for key mappings, they can be used to override other
key translations. Because each window can have a local key translation
table (created when you first fetch it), you can force certain windows
to only accept specific kinds of keys.
Entries in the keyMapTable should have an X "KeySym" as their key, and
either a string or a procedure as their value. If the entry is a
procedure, it is called with the keysym and the modifier mapping (as an
integer set of bits) for the key:
KEYMAP_P(X_KEYSYM, MODIFIERS) -> STRING_UNDEF_OR_FALSE
KEYMAP_P is expected to return:
a string
this will be added to Ved's input queue
false
nothing should be sent for this key.
"undef"
this means that the key is unrecognized, and the
key callback will continue to process the key to see
if it can find a valid value for it.
Note that assigning nullstrings to keysyms in the keyMapTables
effectively disables them.
If the search of both keyMapTables is unfruitful, the key callback will
follow a set of builtin rules for determining what action to take. The
rules are designed so that there is a reasonable default behaviour for
any X Server. This behaviour is independent of server implementation,
server keyboard etc. Ie. the <Up> key on any keyboard will always send
the same sequence.
By default, in XVed, the keyboard sends escape sequences for non-ASCII
keys based upon their X "KeySym". This means that it is possible to
determine what escape sequence a logical keyname will send by
translating that name first into a keysym and then into an escape
sequence.
The following lists the steps that the Key handler goes through:
interrupt key
An interrupt signal is generated
ascii keys
If the standard X binding for the key is an ASCII string, XVed
will add that ASCII string to the input queue.
default
The escape sequence based on the keysym of the key as a
hexadecimal number is added to the input queue.
4.1 Specifying Key Mappings via Event Translation
--------------------------------------------------
The Ved window widget has a "string" action that can be used to specify
direct mappings between any X Event and strings to add to Ved's input
stream. This allows you to specify translations for keys in the
translations resource (either with xved_value or in your .Xdefaults).
The "string" action uses a similar syntax to the string action of the
XTERM client. The following vedset xved translation binding sets
function keys R1-R4 to send <ESCAPE>[11 followed by the function key
number and a tilde:
vars my_translations = [
'#override'
'<Key>R1: string(0x1b) string("[111~")'
'<Key>R2: string(0x1b) string("[112~")'
'<Key>R3: string(0x1b) string("[113~")'
'<Key>R4: string(0x1b) string("[114~")'
];
vedset xved [] translations = % my_translations % endvedset;
(Note that <ESCAPE> can be coded in Pop strings as \e, so the above
could be specified more simply as string("\e[111~") etc; however, this
does not work in .Xdefaults. Note also that the '#override' is
unnecessary, since this is the default.)
The corresponding thing in a .Xdefaults file would be
XVed*XpwScrollText.translations: #override \
<Key>R1: string(0x1b) string("[111~") \n\
<Key>R2: string(0x1b) string("[112~") \n\
<Key>R3: string(0x1b) string("[113~") \n\
<Key>R4: string(0x1b) string("[114~")
String actions bypass the rules described above for keypress handling.
4.2 vedset keys
----------------
Ved bindings for ASCII input characters can be specified exactly as for
other versions of Ved with vedset keys (see HELP * vedset).
In addition, key sequences expressed in parenthesis can be used to refer
to non-ASCII keys by using their logical KeySym names. For example, the
following specifies the behaviour for the cursor keys:
vedset keys
charup = (Up)
chardown = (Down)
charleft = (Left)
charright = (Right)
endvedset;
KeySyms can also be specified by using the (keysym:X) form, where X is
the KeySym number in hexidecimal. This is useful where the keysym does
not have a logical name (ie. it is an unnamed keysym). For example:
vedset keys
loadline = (keysym:1000FF6D) ;;; this is the HP "System" keysym
endvedset
vedset will convert such bracketed expressions into the escape sequences
used by the named KeySym.
-----------------
5 Mouse Handling
-----------------
The standard bindings for mouse buttons are set up by the procedure
vedxvedmouse. (Note that this procedure is called by the default
* vedxvedinit; if you redefine vedxvedinit, you must call vedxvedmouse
in your new definition to get the standard bindings.)
vedxvedmouse() [procedure variable]
Sets up the standard XVed mouse bindings (as described in
HELP * XVEDMOUSE).
You can use vedset mouse to add additional (or alternative) bindings.
This requires knowledge of the possible button events that can occur
within a 'dialog' for a single button.
5.1 Events in a Button Dialog
------------------------------
The sequence of possible events in a button dialog is shown below. The
first event is always a buttonPress; this may then terminate with a
buttonRelease event, or turn into a buttonHold (holding the button for
twice MultiClickTimeout), or a buttonDrag (moving the mouse while the
button is held). buttonHold either terminates with buttonHoldRelease, or
turns into buttonDrag, which then ends with buttonDragRelease:
buttonPress
|
+-------<-------+--------->--------+
| | |
| buttonHold --->--- buttonDrag
| | |
| | |
buttonRelease buttonHoldRelease buttonDragRelease
Subsumed within this description is the processing of 'clicks', that is,
presses and releases of the button within MultiClickTimeout. Each of the
events except the initial buttonPress is qualified by the number of
clicks N associated with it.
An N-click buttonRelease means there were N clicks (including this
release), and no further press occurred within MultiClickTimeout.
An N-click buttonHold or buttonDrag means there were N clicks followed
by a further press within MultiClickTimeout (and no release within
another MultiClickTimeout, although note that if a release comes within
twice MultiClickTimeout without the mouse moving, i.e. before Hold or
Drag is generated, then it becomes an N+1 buttonRelease).
buttonHoldRelease and buttonDragRelease events have the same number of
clicks as the preceding buttonHold or buttonDrag.
Note that a buttonRelease always has N >= 1; only the other events can
have N = 0.
5.2 vedset mouse
-----------------
For mouse button bindings, the following form of vedset is used:
vedset mouse ( attribute [, attribute ...] )
assignment
assignment
.....
endvedset
Each assignment for mouse bindings is a statement of the form:
function = [ num-click] event-type btn [or btn ...]
[ num times ]
[with modifier or modifier]
The rules for converting from function to a procedure are the same as
those used by vedset keys except that the prefix for the procedure is
vedmouse__ rather than ved. The standard vedmouse__ procedures available
are described in REF * XVEDMOUSE (see Button Events below for details of
how to define your own vedmouse__ procedures).
event-type should be one of the XVed button events described above, but
without the button prefix, i.e:
press
release
drag
dragRelease
hold
holdRelease
The adjective num-click can be used in front of event-type to select the
appropriate number of clicks for events other than press. (If not
specified, the number of clicks defaults to 1 for release and 0 for
anything else.)
In addition, a 1-click release can be specified as event type click, or
a num-click release as click with the num times clause. Thus
function = release btn
function = 1-click release btn
function = click btn
function = click btn 1 times
are all the same, as are
function = 2-click release btn
function = click btn 2 times
etc. The num times clause can only be used with click and not with other
event types.
btn should be one of:
btn1
btn2
btn3
btn4
btn4
btn5
anyBtn
and modifier should be one of:
shift
control
meta
mod1
mod2
mod3
mod4
mod5
anyModifier
noModifier
(where meta is synonymous with mod1).
The attribute list specifies how the new bindings are to be added to any
existing bindings, as well as telling the vedset command what window to
apply the changes to. The following are valid attributes:
Attribute Action
--------- ------
override clear any mouse bindings before adding new ones
at front concatenate new bindings in front of existing ones
at back concatenate new bindings after any existing ones
defaultWindow specifies the eventTable for the defaultWindow
currentWindow specifies the eventTable for the currentWindow
nextWindow specifies the eventTable for the nextWindow
For each vedset command, code will be planted which concatenates the new
function onto the existing handler in the eventTable for the event type.
Each function is also enclosed in a wrapper which checks that the event
corresponds to the specified bindings. ie. the function is only called
if the correct event type, button, modifier and click count is set in
the events data vector.
This allows generic mouse event handlers which can be rebound onto
different mouse events.
See HELP * XVEDMOUSE for details of the default mouse bindings.
-----------------------------
6 Selections & The Clipboard
-----------------------------
6.1 The Clipboard
------------------
XVed provides an active clipboard, which can be used to cut and paste
text between XVed and any other X based program that communicates via
the X server's selection mechanism.
The active variable vvedclipboard is the main interface to the X
clipboard:
vvedclipboard -> string_or_false [active variable]
string_or_false -> vvedclipboard
vvedclipboard is an active variable that represents the current
value of an X server's PRIMARY or CLIPBOARD selection. Accessing
vvedclipboard will cause XVed to request the current value of
first the X server's PRIMARY selection, and then the CLIPBOARD
selection if the PRIMARY selection is empty. Try:
vvedclipboard =>
The value returned will always be a Pop-11 string or false if
both the PRIMARY and the CLIPBOARD selections are empty.
You can also assign a string to vvedclipboard:
'hello' -> vvedclipboard;
This will cause XVed to request the ownership of the PRIMARY
selection. Assigning the word "CLIPBOARD" as well, i.e.
'hello', "CLIPBOARD" -> vvedclipboard;
will instead set the CLIPBOARD selection. Future requests of
either selection's value from any X clients sharing the same
display will transfer the string that you assign to the other
client.
vvedclipboard can optionally be given a procedure to call when
it looses the ownership of the selection (as happens when
another client requests the selection). The procedure should be
passed as an additional argument when you assign to
vvedclipboard:
'hello', vedscreenbell -> vvedclipboard;
'hello', vedscreenbell, "CLIPBOARD" -> vvedclipboard;
6.2 Selections
---------------
XVed provides a high level interface to interact with the clipboard
described above using a set of selection facilities driven by the mouse.
See HELP * XVEDMOUSE for instructions on how to mark a selection. The
following operations can be performed on selections.
XVed selections complement the Ved marked ranges (see HELP * MARK).
Unlike marked ranges, selections are not anchored to a row/column in
your document. Instead, you make a selection using the mouse (either in
a Ved buffer, or in any other X text editor), and then ask Ved to apply
some action to the selection. Operations that you can apply to a
selection are:
Operation Result
--------- ------
Cut moves the selected text from document to clipboard
Copy copies the selection onto the clipboard
Paste pastes the clipboard into the document
Compile compiles the clipboard
Get Help gets help on the text held in the clipboard
Typing any textual characters while you have a selection displayed will
cause that selection to be cut.
----------------------
7 Menu Specifications
----------------------
Every Motif/OpenLook XVed window has two menus associated with it: An
(optional) menubar across the top of each window (in the "menubar"
window setting slot), and a popup menu (held in the "Menu" application
setting) within the Ved window (available on mouse button 3) . Each
window can have a different menubar. The popup menu is shared among all
of the XVed windows (and is also available when running in vanilla
mode).
Each menu on the menubar or popup menu is specified using lists of the
form:
[MENU_TITLE
ITEM_1
ITEM_2
...
ITEM_N
]
The menubar and popup menu consists of a list of several such menu
specifications - one for each top-level menu button. item can be several
things:
a vector
Vectors of the form {label action} are used to specify basic
menu options. The label should be a string, and is used to
label the corrosponding menu button. The action is then
applied when the menu option is selected. action can be:
A procedure
taking no arguments
A string
The string is executed using * veddo
A word or an ident
Either * valof or * idval is used to get the value
associated with the item -- which should be a procedure
taking no arguments.
action can also be a vector of any of the above - each
operation in the vector is then applied in sequence.
a list
You use nested lists to specify walking menus. The first
element of the list is the name of the menu-option that
activates the walking menu.
"fixable"
If the word "fixable" appears in the menu specification, the
menu is given a pushpin in OpenLook. Future versions of
Motif XVed will make tearoff Motif menus when this attribute
is set).
"space"
This word indicates that a separator should be created at
this point in the menu. You can have as many separators as
you like - use them to improve the presentation of the menu.
See LIB * VEDXVEDMENU and LIB * VEDXVEDMENUBAR for example menu
specifications.
You can change both the menubar and the popup menu dynamically. Note
however that doing so may take some time for large menus since the
previous menu needs to be destroyed and the new one created. XVed is
optimized to add additional menus onto the end of the menubar or popup
menu, so it is quickest to add any new option menus at the end of any
existing options. For example, the following adds a very short menu to
the current windows menubar:
xved_value("currentWindow", "menubar") <> [
['Print'
{'Print File' ved_print}
{'Print Range' ved_printmr}
space
{'Print Output' 'print output.p'}
]
] -> xved_value("currentWindow", "menubar");
---------------------------
8 GUI Specific Information
---------------------------
8.1 OpenLook
-------------
Because of bugs in the Sun "OLIT" or OpenLook widget set in OpenWindows
version 2.0 (which uses calls to obsolete and non standard X toolkit
routines), XVed does not create its own 'application context' when using
OpenLook widgets. Instead it shares the default application context
which is created by the OpenLook procedure OlInitialize.
This will only effect you if you are involved with writing your own X
applications, since you will then have to share the default application
context with XVed. The implications of this are:
¤ Creating more than one display connection to the X server does
causes OpenLook widgets to stop working.
¤ Writing programs that break the toolkits default connection to the X
Server (ie. XptDefaultAppContext or XptDefaultDisplay) will cause
XVed to stop working, with possibly unpredictable results.
¤ Disabling asynchronous event handling without manually requesting
for events to be handled using XptAppProcessEvents will cause XVed
to become inactive.
¤ Remaining within a callback procedure for long periods will also
cause XVed to become inactive.
If you are not involved with developing X programs, or are writing
fairly straightforward applications, these situations should not arise.
8.2 Motif
----------
As well as a popup menu on each window, Motif XVed users will find the
same menu attached as a menubar across the top of each Ved window. This
goes a long way towards making up for the lack of a puspin for these
menus.
8.3 Reverse Video
------------------
Notice that if you wish to use reverse video with Motif or OpenLook
XVed, the following resource names and values need to be set in your
.Xdefaults file or equivalent.
! get XVed in inverse video
XVed*Foreground: white
XVed*FontColor: white
XVed*Background: black
! get property sheets in inverse video
Propsheet*FontColor: white
Propsheet*Foreground: white
Propsheet*Background: black
------------------------------
9 XVed and the Window Manager
------------------------------
XVed attempts to work with the window manager. It will do things such as
set the size hints for windows, and respond to requests to delete
windows, iconify windows, and so on.
Some versions of XVed will not work well with all window managers.
Specifically, the "OpenLook" flavour of XVed do not work well with TWM,
UWM or MWM window managers. This is because the OpenLook widgetset
expects certain conditions to hold which are not respected by these
window managers.
One thing to be clear about is the difference between 'Delete Window'
and 'Destroy Window' in window managers such as TWM. The 'Destroy
Window' operation will actually break the socket connecting the client
to the server - equivalent to an xkill or a 'kill -9' in Unix parlance.
XVed cannot continue to work after a Destroy Window request.
The 'Delete Window' operation on the other hand will send the window a
message asking it to close. XVed respects these messages and responds
accordingly.
If you are a TWM user you might want to have a line reading:
"Delete Window" f.delete
in your twm menu. This "Delete Window" option will let you quit XVed
menus3 and icons safely.
--------------------------------
10 XVed Internal Event Handling
--------------------------------
XVed 'internal events' are generated within for example X Toolkit
callback procedures for X events such as mouse button clicks, menu
selections, scrollbar dragging, window deletion, etc. Such callback
handlers generally do a little interpretation of the event, and then
place one or more XVed 'events' on Ved's input stream. Each XVed event
consists of an XVed Window, an event name (a word), and a single piece
of event data (which can be anything).
When Ved comes across an XVed event in its input stream, it first
selects the file that belongs to the window that the event occurred in.
Then it calls xved_dispatch_event to handle the event:
xved_dispatch_event(window, name, data) [vars procedure]
Searches for a handler for the XVed "Event" specified by name (a
word). First, the "eventTable" property held in the
"currentWindow" is examined. If a procedure exists in the table
under the key name, it is called with then name and data as
arguments. If a handler is not found in the "currentWindow"
table, the "defaultWindow" table is searched in the same manner.
xved_dispatch_event could be defined as:
define vars xved_dispatch_event(window, name, data);
lvars window, name, handler_p, data table;
;;; search this window's table
xved_value("currentWindow", "eventTable") -> table;
if table(name) ->> handler_p then
handler_p(window, name, data) -> (,,);
return;
endif;
;;; search default windows table
xved_value("defaultWindow", "eventTable") -> table;
if table(name) ->> handler_p then
handler_p(window, name, data) -> (,,);
return;
endif;
enddefine;
Event handlers take the form:
HANDLER_P(window, name, data) -> (window, name, data)
that is, they must return their arguments as results -- this
allows handlers to be chained together, i.e.
HANDLER1_P <> HANDLER2_P
will work as an event handler, since the arguments to the first
get returned and passed on to the second.
To assign a handler to an event, first fetch the event table:
vars table = xved_value("defaultWindow", "eventTable");
Then assign the procedure into the appropriate entry of the
table. The following example makes the "buttonHold" event
generate a bell (see below for more button event types):
vedscreenbell -> table("buttonHold");
(Technical aside: Each XVed "Event" appears to Ved as a
procedure on ved_char_in_stream - so handlers for events can do
exactly the same sorts of things that handlers for key presses
do; each event will cause Ved to cycle through vedprocess, so
changes to Ved variables such as vedline and vedcolumn work
correctly. Also, an XVed "Event" is not executed inside an X
toolkit callback procedure, so the X toolkit is in a normal
state when the procedure is called).
10.1 Button Events
-------------------
This section gives more details of the mouse button handling system. See
Mouse Handling above for an introduction, and how to set mouse button
bindings with vedset mouse.
The majority of events currently generated by XVed are for the pointer
device.
The raw XVed X Pointer event callback does some processing of the event,
and then notifies Ved that an event has happened by raising an XVed
event. The callback does not implement any button policy, but does
simplify the task of determining what sort of button event is being
dealt with.
Note that the button event callback filters button events -- it doesn't
allow "chords" -- more than one button at the same time (X Servers
sometimes map two buttons pressed together into a different button
number but that is accepted). It also ensures that only one button is
active for any given button "dialog", so it will ignore events for mouse
button 2 if you are currently in the middle of doing something with
mouse button 1.
The following XVed Event name types can be set in one of the XVed
"eventTable" properties:
buttonPress [xved event name]
buttonHold [xved event name]
buttonDrag [xved event name]
buttonHoldRelease [xved event name]
buttonDragRelease [xved event name]
buttonRelease [xved event name]
These XVed button events are described in Events in a Button
Dialog above.
The event data field of a button event handler is an 11 element vector.
The include file INCLUDE * XVED_CONSTANTS contains the following
constants that are used for accessing and decoding the information in
this vector:
XVM_BUTTON [include constant]
XVM_MODIFIERS [include constant]
XVM_CLICKS [include constant]
XVM_COL [include constant]
XVM_ROW [include constant]
XVM_START_COL [include constant]
XVM_START_ROW [include constant]
XVM_X [include constant]
XVM_Y [include constant]
XVM_START_X [include constant]
XVM_START_Y [include constant]
These constants, defined in INCLUDE * XVED_CONSTANTS, are used
to decode XVed button events. They specify indexes to a vector
that is passed as the event data for button events. An event
handler uses the data to determine how to interpret the event.
The following example illustrates the use of the constants:
include xved_constants;
define show_event(window, name, data) -> (window, name, data);
lvars window, name, data, button_num, button_col;
data(XVM_BUTTON) -> button_num;
data(XVM_COL) -> button_col;
vedputmessage(
sprintf(button_col, button_num, name,
'button event: %p %p (column %p)'));
enddefine;
vars table;
xved_value("currentWindow", "eventTable") -> table;
show_event -> table("buttonPress");
show_event -> table("buttonDrag");
XVM_BUTTON
is an integer 1-5 representing the button number.
XVM_MODIFIERS
is an integer representing the current state of the
keyboard modifiers (see below for a list of modifier bits).
XVM_CLICKS
contains the number of clicks associated with the
event (as described above).
XVM_ROW and XVM_COL
are the position of the mouse when the button event
occurred (in Ved screen rows and columns).
XVM_START_ROW and XVM_START_COL
are the starting row and column at which the initial
buttonPress occurred.
XVM_X and XVM_Y
are the position of the mouse when the button event
occurred (in pixels).
XVM_START_X and XVM_START_Y
are the starting x and y at which the initial buttonPress
occurred.
Modifiers are represented as an integer with one or more of the
following bits set:
XVM_NOMODMASK [include constant]
XVM_SHIFTMASK [include constant]
XVM_LOCKMASK [include constant]
XVM_CONTROLMASK [include constant]
XVM_METAMASK [include constant]
XVM_MOD1MASK [include constant]
XVM_MOD2MASK [include constant]
XVM_MOD3MASK [include constant]
XVM_MOD4MASK [include constant]
XVM_MOD5MASK [include constant]
XVM_ANYMODMASK [include constant]
Constants representing bits that are set in the XVM_MODIFIERS
field of a button event according to the state of the keyboard
modifiers.
If no modifiers are held down, XVM_NOMODMASK is set.
XVM_ANYMODMASK represents any combination of modifiers.
XVM_SHIFTMASK, XVM_LOCKMASK, XVM_CONTROLMASK and XVM_METAMASK
are set according to the status of the shift, lock, control and
meta keys respectively. XVM_MOD1MASK is the same as
XVM_METAMASK, and XVM_MOD2MASK through XVM_MOD5MASK correspond
to any other modifiers that are defined with xmodmap.
The following mask would test for the shift and control key
being on at the same time:
define event_hander(window, name, data) -> (window, name, data);
lvars window, name, data, ok;
data(XVM_MODIFIERS) == XVM_SHIFTMASK || XVM_CONTROLMASK ->ok;
returnunless(ok);
...
enddefine;
xvedignorepixelmotion [variable]
This variable controls whether buttonDrag events are generated
for a mouse movement which does not cross the current character
cell boundary, i.e. does not change the pointer row or column.
The initial button press sets this variable false; thereafter it
is up to an event handler (e.g. for a drag) to set it true if
generation of further drag events for pixel-only movement is not
required in the current button dialog.
When a vedmouse__ button handler is called, the event vector is made
available in the variable vvedmousedata:
vvedmousedata [variable]
Set to the mouse event vector for the event before calling the
specified vedmouse__ handler for it. (See above for details of
the vector contents.)
Handlers should be defined thus:
define vedmouse__myhandler();
< process vvedmousedata ... >
;;; if the handler accepts the event, it should set this
;;; variable true:
true -> xvedeventhandled;
enddefine;
Setting xvedeventhandled true stops further handlers being called for
this event. Note that a handler may also wish to set
xvedignorepixelmotion true (see above).
10.2 Other Events
------------------
The following events are also be generated by XVed callbacks:
createWindow [xved event name]
Dispatched when a window is created (NB. this event is
dispatched directly, and does not cause Ved to cycle through
vedprocess);
destroyWindow [xved event name]
Dispatched when a window is destroyed (NB. this event is
dispatched directly, and does not cause Ved to cycle through
vedprocess);
selectWindow [xved event name]
This event is dispatched whenever XVed selects a new input
source. When it is received "currentWindow" will refer to the
new input window.
unselectWindow [xved event name]
This event is dispatched just before XVed selects a new input
source.
dragLoad [xved event name]
Passed a list of strings as data. The default handler calls
ved_ved for each string. This event is generated when an
XV_DO_DRAG_LOAD client message is sent to an XVed window, for
example, when the OpenLook filemanager drops a file on XVed.
dragMove [xved event name]
Passed a string as data. The default handler inserts the string
into the current Ved buffer - this event is generated when an
XV_DO_DRAG_MOVE client message is sent to an XVed window, for
example by dragging some text from another OpenLook application.
clearSelection [xved event name]
Generated by the Key event handler if a selection needs to be
reset before the key press can be dealt with.
scrollbarMoved [xved event name]
hscrollbarMoved [xved event name]
Passed the new position of the vertical or horizontal scrollbar.
These event handlers will scroll to the specified position.
menuAction [xved event name]
Used to handler the user selecting a menu item.
----------
11 Caveat
----------
This note is for Poplog users who have written programs that drive
terminal versions of Ved.
As from Poplog 14.1, XVed is a new part of Poplog. Because of this it
was reasonable to make some bold changes to the way that Ved works (when
under XVed) so that it is more adapted to a windowing, event driven
environment.
These changes will NOT effect current Ved users who continue to use Ved
from a terminal. However, it is possible that, if you switch to XVed,
your old Ved programs will not continue working.
It is reasonably straightforward to write or modify programs so that
they continue to work under both windowing XVed and non-windowing Ved.
Efforts have been taken to ensure that the changes are well documented
so that, if you do end up changing Ved programs, the changes are easy to
implement.
The two fundamental changes introduced for XVed are:
¤ Under XVed, vedprocess is a proper Poplog process. It is suspended
when there is no Ved input waiting waiting to be processed, and
resumed when input appears on Ved's input stream and Poplog is in a
long term wait. The Ved process will continue to stay active until
there are no more inputs to be processed, at which point Ved will
suspend itself.
In other words, Ved is continuously being started and stopped - it
is no longer the case that you are either running Ved or not running
Ved.
There are many advantages to this - one is that Ved maintains its
own stack. Another is that you can run Ved 'asynchronously', at the
same time as for example loading programs from the top level window.
¤ Ved no longer directly uses poprawdevin and poprawdevout to write
output or receive input. Instead, it uses a set of redefinable
procedures that, under non-windowing Ved are simply written to use
the standard devices. Under XVed, these procedures are redefined to
instead send output and read input from the current XVed window.
This for the first time means that Ved is not tied to a set of
terminal devices for its input and output. The standard devices are
not taken over by XVed, and so writing to poprawdevout will have
exactly the same effect whether you are running XVed or not. Error
messages and trace output will appear in your terminal window
without interrupting your interaction with Ved. The 'VED HERE: PRESS
RETURN TO CONTINUE' message does not appear in XVed.
In essence, the programs that will be effected are those that:
¤ Assume that vedediting is an indication of when Ved has control of
the screen.
¤ Use the standard input/output devices, or rawcharin/rawcharout to
present data/receive input from the user.
¤ Assume that they are talking to a terminal, and send escape
sequences or expect escape sequences for specific terminal types.
¤ Rewrite the vedprocess loop to manually drive Ved.
See HELP * VEDTOXVED for hints on how to translate programs from XVed to
Ved.
+-+ C.x/x/ved/ref/xved
+-+ Copyright University of Sussex 1997. All rights reserved.