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 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 ... 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 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 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; ... 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: -1----- -----2- |-3----- -----4-| ||-5----- -----6-|| -|| | | ||- -| | | |- ------- ------- 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 savedefaults. SearchDoesSelect [xved value name] Boolean, default false. If this is set to true, then performing a search using /, " 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: XVed.Icon.background: XVed.Icon.font: 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 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 [11 followed by the function key number and a tilde: vars my_translations = [ '#override' 'R1: string(0x1b) string("[111~")' 'R2: string(0x1b) string("[112~")' 'R3: string(0x1b) string("[113~")' 'R4: string(0x1b) string("[114~")' ]; vedset xved [] translations = % my_translations % endvedset; (Note that 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 \ R1: string(0x1b) string("[111~") \n\ R2: string(0x1b) string("[112~") \n\ R3: string(0x1b) string("[113~") \n\ 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.