diff options
Diffstat (limited to 'Build/source/texk/web2c/cwebdir/examples/oemacs.w')
| -rw-r--r-- | Build/source/texk/web2c/cwebdir/examples/oemacs.w | 896 |
1 files changed, 896 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/cwebdir/examples/oemacs.w b/Build/source/texk/web2c/cwebdir/examples/oemacs.w new file mode 100644 index 00000000000..5810b0e7b26 --- /dev/null +++ b/Build/source/texk/web2c/cwebdir/examples/oemacs.w @@ -0,0 +1,896 @@ +\datethis +@i xview_types.w + +@* Introduction. +This program provides an interface between the GNU Emacs editor and the +OpenWindows environment, using the XView toolkit for interactive graphics. +It is based on \.{emacstool}, a SunView interface written by Jeff Peck +of Sun Microsystems in 1986 and adapted by him in 1988 to \.{xvetool}, +an early XView interface. The present code, by Don Knuth, is designed to work +with OpenWindows Version~3 as distributed in 1992, using a Sun Type~4 +keyboard. + +GNU Emacs is a highly portable and versatile program, which does most +of the hard work involved in editing files. Our job is simply twofold: +To get \.{emacs} started in an appropriate window, and to transmit +keyboard and mouse events as sequences of characters that \.{emacs} +can happily consume. These simple tasks do, however, require us to +get a lot of fussy details right. In fact, this program could not have been +written without a good deal more knowledge about XView than can be found +in the manuals. Fortunately Jeff Peck works for Sun, and his +inside knowledge has provided the necessary clues. (All complaints below +about the XView documentation are based on the reference manuals and +programming manuals available from Sun and from O'Reilly \AM\ Associates, in +the summer of 1992. Let us hope that such problems will not persist; +computer programming should be fun, but some of the code below was +written only after a bitter struggle!) + +The command-line arguments to \.{oemacs} are either standard XView +arguments, which specify the font and the size and position of the window, +the icon, the colors, etc.; or they are standard arguments of \.{emacs}, +which typically specify the file to be edited and a position in that file. +If I decide later to make certain things in \.{oemacs} less hardwired, +I will look for options in the X resource database instead of on the +command line. + +An important note about using \.{xmodmap} to change the behavior of +certain keys appears below. It makes \.{emacs} more powerful, unless you +have other good uses for those keys. (See the entry for \.{xmodmap} +in the index.) + +Before using \.{oemacs}, you must compile \.{emacs} with the +\.{sunfns} module (which the \.{Makefile} will do for you if you've +configured it correctly), and you should include the lines +$$\vbox{\halign{\.{#}\hfil\cr +(load-library "sun-mouse")\cr +(load-library "sun-fns")\cr}}$$ +in Emacs's file \.{lisp/site-init.el}. + +Caution: This program was developed and tested with Peck's improved +versions of sun-mouse and sun-fns; these are available from +\.{peck@@sun.com} if not yet part of the GNU distribution. + +@ We follow the traditional structure of XView applications. The |exit| +statement at the end is important, because \.{oemacs} can be invoked by +the \.{system} command in \TEX/ (when the user has typed \.e in response +to an error message); without |exit(0)|, \TEX/ would complain of trouble +executing this program, although we would simply be terminating the program +without returning any particular value. + +@c +@<Include header files@>@; +@# +Frame frame; /* the base frame where we will live */ +@<Global variables@>@; /* additional globals besides |frame| */ +@# +@<Event-handling procedures@>@; +@# +main(argc,argv) + int argc;@+char *argv[]; /* typical \UNIX/ setup */ +{ + @<Special initialization@>; + @<Install the components and controls of |frame|@>; + xv_main_loop(frame); + exit(0); +} + +@ Including the header file \.{<xview/xview.h>} also causes other +basic header files like \.{<xview/frame.h>}, \.{<xview/icon.h>}, etc., +to be loaded. We must call the \CEE/ compiler with the flag +\.{-I\$(OPENWINHOME)/include} so that the \CEE/ preprocessor will +find the OpenWindows header files. + +Some \UNIX/ systems define string functions in \.{<string.h>}, some in +\.{<strings.h>}; the Sun documentation calls for \.{<string.h>}. My +experiments indicate that Sun's compiler and loader work perfectly +well with string functions even when no header files are given, so the +programmer doesn't really have to remember the right name. Similarly, +\.{<stdio.h>} isn't really needed with Sun's \CEE/, unless certain macros +are used. I'll include \.{<string.h>} and \.{<stdio.h>} anyway, in the +spirit of being obedient to the stated rules. + +@<Include...@>= +#include <string.h> +#include <stdio.h> +#include <xview/xview.h> + +@* The icon and frame. +First we attach an icon that will appear if the user closes the \.{oemacs} +window later. + +There are two reasons for doing this first. One is that we might as well +begin with an easy task, in order to get warmed up. The other is that +if we specify the icon {\it after\/} creating the frame, we will unconditionally +override an icon that the user may have specified with the \.{-WI} +option on the command line. (This is one of the little things a +programmer has to turn by trial and error, since the XView documentation +leaves much unsaid.) + +The colors used in the icon will be inherited from the frame, so they will +be reversed if the user asks for reverse video. I~prefer to have the icon +always in black on a yellow background, so I'm making the color explicit. +(I hope this will work on monochrome displays; it works fine on my +grayscale monitor.) + +@<Create a frame with the gnu icon@>= +{@+Server_image icon_image=(Server_image)xv_create(NULL,SERVER_IMAGE,@| + XV_WIDTH,64,XV_HEIGHT,64,SERVER_IMAGE_BITS,icon_bits,NULL); + Server_image mask_image=(Server_image)xv_create(NULL,SERVER_IMAGE,@| + XV_WIDTH,64,XV_HEIGHT,64,SERVER_IMAGE_BITS,mask_bits,NULL); + Cms cms=(Cms)xv_create(NULL,CMS,CMS_SIZE,2,@| + CMS_NAMED_COLORS,"yellow","black",NULL,NULL); + Icon icon=(Icon)xv_create(NULL,ICON,@| + ICON_IMAGE,icon_image,ICON_MASK_IMAGE,mask_image,@| + WIN_CMS,cms,NULL); + frame=xv_create(NULL,FRAME,FRAME_ICON,icon,NULL); +} + +@ @<Include...@>= +#include <xview/cms.h> + +@ If the user hasn't specified a label with the \.{-Wl} option, we turn off +the header line at the top of the frame. That gives us a chance to see +two more lines of the file \.{emacs} is editing. However, we add a +label of our own; it will show up in the virtual window manager display. + +@<Remove the frame header, unless the user has specifically requested it@>= +if (xv_get(frame,XV_LABEL)==NULL) /* no label specified */ + xv_set(frame,FRAME_SHOW_HEADER,FALSE,XV_LABEL,"OEMACS",NULL); + +@ The following icon and mask are derived from the ``what's gnu'' image on the +back cover of the GNU Emacs manual. (This accounts for my black-on-yellow +preference.) + +@<Global...@>= +unsigned short icon_bits[]={@| + 0x0000, 0x0000, 0x0000, 0x1E00, + 0x0000, 0x0000, 0x0000, 0x0900,@| + 0x001E, 0x0000, 0x0000, 0x0880, + 0x0064, 0x0000, 0x0000, 0x0440,@| + 0x0088, 0x0000, 0x0000, 0x0420, + 0x0110, 0x0000, 0x0000, 0x0210,@| + 0x0220, 0x0000, 0x0000, 0x0210, + 0x0420, 0x0FCF, 0x01C0, 0x0108,@| + 0x0840, 0x1030, 0x8620, 0x0088, + 0x1080, 0x00C0, 0x5810, 0x0084,@| + 0x1080, 0x1F00, 0x2008, 0x0044, + 0x2100, 0xE200, 0x1004, 0x0044,@| + 0x4103, 0x0400, 0x0002, 0x0042, + 0x4204, 0x080E, 0x0001, 0x0042,@| + 0x8200, 0x7830, 0x0020, 0x8082, + 0x8203, 0x9040, 0x0018, 0x4102,@| + 0x8204, 0x2080, 0x07C6, 0x3E04, + 0x8108, 0x410C, 0x0021, 0x8004,@| + 0x8080, 0x8210, 0x03D0, 0x6008, + 0x4041, 0x0420, 0x0008, 0x1810,@| + 0x403E, 0x0820, 0x0FFC, 0x0620, + 0x2000, 0x1040, 0x0002, 0x01C0,@| + 0x1000, 0x608C, 0x0FFF, 0x0060, + 0x0801, 0x8110, 0x0080, 0x8118,@| + 0x0406, 0x0220, 0x1FFF, 0x66E0, + 0x0238, 0x044F, 0x0000, 0xD800,@| + 0x01C0, 0x0890, 0x8FFF, 0x4000, + 0x0300, 0x10A6, 0x4041, 0x6000,@| + 0x1C00, 0x2026, 0x4FFF, 0x6000, + 0x60CC, 0x4026, 0x4001, 0x6000,@| + 0x1F33, 0x8010, 0x8FFF, 0x4000, + 0x0012, 0x000F, 0x0040, 0xC000,@| + 0x0022, 0x4000, 0x07FF, 0x4000, + 0x0024, 0x4000, 0x0000, 0x2000,@| + 0x0024, 0x4818, 0x8FFF, 0xE000, + 0x0024, 0x4907, 0x0040, 0x2000,@| + 0x0044, 0x4900, 0x1FFF, 0xE000, + 0x0044, 0x4900, 0x0000, 0x2000,@| + 0x0044, 0x4900, 0x07FF, 0xE000, + 0x0044, 0x4880, 0x0020, 0x2000,@| + 0x0044, 0x4880, 0x07FF, 0xE000, + 0x0044, 0x4840, 0x0000, 0x2000,@| + 0x0044, 0x2A20, 0x07FF, 0xE000, + 0x0044, 0x2410, 0x0020, 0x2000,@| + 0x0042, 0x2448, 0x0FFF, 0xE000, + 0x0042, 0x2948, 0x0000, 0x2000,@| + 0x0041, 0x1144, 0x07FF, 0xA000, + 0x0041, 0x1144, 0x2010, 0x1000,@| + 0x0021, 0x1126, 0x20FA, 0x1000, + 0x0024, 0x8925, 0x2600, 0x1000,@| + 0x0014, 0x8924, 0xA138, 0x7000, + 0x0016, 0x88A4, 0x9090, 0x6000,@| + 0x000A, 0x44A4, 0x4880, 0xA000, + 0x0002, 0x44A2, 0x4401, 0x2000,@| + 0x0003, 0x4492, 0x2001, 0x4000, + 0x0001, 0x2451, 0x3002, 0x8000,@| + 0x0000, 0xA251, 0x1E05, 0x0000, + 0x0000, 0x2248, 0xA1F9, 0x8000,@| + 0x0000, 0x1648, 0x9002, 0x8000, + 0x0000, 0x1A28, 0x4C02, 0x8000,@| + 0x0000, 0x1220, 0x43FC, 0x8000, + 0x0000, 0x0120, 0x2000, 0x8000,@| + 0x0000, 0x0120, 0x2003, 0x0000, + 0x0000, 0x0150, 0x1FFC, 0x0000 +}; +unsigned short mask_bits[]={@| + 0x0000, 0x0000, 0x0000, 0x1E00, + 0x0000, 0x0000, 0x0000, 0x0F00,@| + 0x001E, 0x0000, 0x0000, 0x0F80, + 0x007C, 0x0000, 0x0000, 0x07C0,@| + 0x00F8, 0x0000, 0x0000, 0x07E0, + 0x01F0, 0x0000, 0x0000, 0x03F0,@| + 0x03E0, 0x0000, 0x0000, 0x03F0, + 0x07E0, 0x0FCF, 0x01C0, 0x01F8,@| + 0x0FC0, 0x103F, 0x87F0, 0x00F8, + 0x1F80, 0x00FF, 0xDFF0, 0x00FC,@| + 0x1F80, 0x1FFF, 0xFFF8, 0x007C, + 0x3F00, 0xE3FF, 0xFFFC, 0x007C,@| + 0x7F03, 0x07FF, 0xFFFE, 0x007E, + 0x7E04, 0x0FFF, 0xFFFF, 0x007E,@| + 0xFE00, 0x7FFF, 0xFFFF, 0x80FE, + 0xFE03, 0x9FFF, 0xFFFF, 0xC1FE,@| + 0xFE04, 0x3FFF, 0xFFFF, 0xFFFC, + 0xFF08, 0x7FFF, 0xFFFF, 0xFFFC,@| + 0xFF80, 0xFFFF, 0xFFFF, 0xFFF8, + 0x7FC1, 0xFFFF, 0xFFFF, 0xFFF0,@| + 0x7FFF, 0xFFFF, 0xFFFF, 0xFFE0, + 0x3FFF, 0xFFFF, 0xFFFF, 0xFFC0,@| + 0x1FFF, 0xFFFF, 0xFFFF, 0xFFE0, + 0x0FFF, 0xFFFF, 0xFFFF, 0xFFF8,@| + 0x07FF, 0xFFFF, 0xFFFF, 0xFEE0, + 0x03FF, 0xFFFF, 0xFFFF, 0xF800,@| + 0x01FF, 0xFFFF, 0xFFFF, 0xE000, + 0x03FF, 0xFFFF, 0xFFFF, 0xE000,@| + 0x1FFF, 0xFFFF, 0xFFFF, 0xE000, + 0x7FFF, 0xFFFF, 0xFFFF, 0xE000,@| + 0x1F7F, 0xFFFF, 0xFFFF, 0xC000, + 0x001F, 0xFFFF, 0xFFFF, 0xC000,@| + 0x003F, 0xFFFF, 0xFFFF, 0xC000, + 0x003F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x003F, 0xFFFF, 0xFFFF, 0xE000, + 0x003F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x007F, 0xFFFF, 0xFFFF, 0xE000, + 0x007F, 0xFFFF, 0xFFFF, 0xF000,@| + 0x003F, 0xFFFF, 0xFFFF, 0xF000, + 0x003F, 0xFFFF, 0xFFFF, 0xF000,@| + 0x001F, 0xFFFF, 0xFFFF, 0xF000, + 0x001F, 0xFFFF, 0xFFFF, 0xE000,@| + 0x000B, 0xFFFF, 0xFFFF, 0xE000, + 0x0003, 0xFFFF, 0xFFFF, 0xE000,@| + 0x0003, 0xFFFF, 0xFFFF, 0xC000, + 0x0001, 0xFFFF, 0xFFFF, 0x8000,@| + 0x0000, 0xBFF1, 0xFFFF, 0x0000, + 0x0000, 0x3FF8, 0xFFFF, 0x8000,@| + 0x0000, 0x1FF8, 0xFFFF, 0x8000, + 0x0000, 0x1FF8, 0x7FFF, 0x8000,@| + 0x0000, 0x13E0, 0x7FFF, 0x8000, + 0x0000, 0x01E0, 0x3FFF, 0x8000,@| + 0x0000, 0x01E0, 0x3FFF, 0x0000, + 0x0000, 0x0150, 0x1FFC, 0x0000 +}; + +@* Emulating a terminal. +We will run \.{emacs} in a ``tty subwindow,'' named after the teletype +terminals of ancient yore. + +The |argv| array will be a command line that invokes +\.{emacs} with all arguments not removed by |xv_init|, i.e., all arguments +that remain after generic XView arguments have been removed. + +We have to say |WIN_IS_CLIENT_PANE|, otherwise fonts specified on the +command line will be ignored. (This cryptic instruction is mentioned briefly +in the XView reference manual, but not in the XView programming manual; +I~would never have discovered it without Jeff Peck's help.) + +We also have to set |TTY_QUIT_ON_CHILD_DEATH| to |TRUE|. Otherwise when +\.{emacs} exits (via control-X, control-C) there still will be a terminal +window (into which we can type but not access the shell). + +Before starting \.{emacs} we set the environment variable +\.{TERM} equal to \.{sun}. +This will tell \.{emacs} to initialize itself with the +programs in its source file \.{lisp/term/sun.el}, where special +adaptations for Sun-style terminals have been recorded. + +@<Put a tty subwindow into the frame@>= +argv[0]="emacs"; +putenv("TERM=sun"); +tty=(Tty)xv_create(frame,TTY,WIN_IS_CLIENT_PANE,@| + TTY_QUIT_ON_CHILD_DEATH,TRUE,@| + TTY_ARGV,argv,NULL); + +@ @<Global...@>= +Tty tty; + +@ @<Include...@>= +#include <xview/tty.h> + +@ The XView manual doesn't tell us that tty subwindows have a view part +and a pseudo-terminal part. (The manual does mention briefly that text +subwindows have views---at the beginning of section 6.3, and indirectly in +one of the examples in the chapter on color.) + +The view window of an emulated tty will receive keyboard and +mouse events. We need to know its ``handle,'' because we want to +modify XView's default interpretation of many of those events. + +For example, we want to grab the keyboard focus (i.e., to begin receiving +keyboard input) as soon as the user moves the mouse into the \.{emacs} +window. The normal OpenLook default requires a user to click in the window +first, but that is inefficient in a production book-writing environment. +Us \.{emacs} users would rather type than point. + +A secret incantation makes the view window accessible. Dear reader, +would you have guessed how to do this, from reading the manuals only, +without looking at Jeff Peck's code? Be honest now. + +We don't have to enable the notification of other kinds of events; +tty subwindows already do that. + +@<Prepare to be notified when the mouse enters the window@>= +window=(Xv_window)xv_get(tty,OPENWIN_NTH_VIEW,0); +xv_set(window,WIN_CONSUME_EVENT,LOC_WINENTER,NULL); + +@ @<Global...@>= +Xv_window window; /* the view window of |tty| */ + +@ If the user has specified reverse video with the \.{-rv} option, +we will reverse black and white in the mouse cursor. This will make it +more visible against a black background. + +Changing the cursor is another undocumented reason why we need to know +about the tty's view window; nothing changes if we try to attach +the new cursor to |frame| or to |tty| instead of to |window|. + +@<Change the cursor, to avoid black-on-black@>= +if (rv) {Xv_singlecolor white,black; + Xv_cursor cursor; + white.red=white.green=white.blue=255; + black.red=black.green=black.blue=0; + cursor=(Xv_cursor)xv_create(NULL,CURSOR,@| + CURSOR_SRC_CHAR,OLC_BASIC_PTR,CURSOR_MASK_CHAR,OLC_BASIC_MASK_PTR,@| + CURSOR_FOREGROUND_COLOR,&white,CURSOR_BACKGROUND_COLOR,&black,NULL); + xv_set(window,WIN_CURSOR,cursor,NULL); +} + +@ @<Include...@>= +#include <xview/cursor.h> /* we're using the cursor package */ + +@ What is the variable |rv| that was tested in the code above? Good question. +We have to scan for \.{-rv} before |xv_init| looks at the command arguments. + +@<Scan the command line, setting |rv| nonzero if \.{-rv} is present@>= +rv=0; +{@+int k=argc; + while (--k>0) if (strcmp(argv[k],"-rv")==0 || + strcmp(argv[k],"-reverse")==0) rv=1; +} + +@ @<Global...@>= +int rv; + +@ We need to know the height and width of characters in the font, in order +to convert mouse positions into coordinates that \.{emacs} will like. +If the user has specified a font explicitly, the font will presumably have +a fixed width for all characters; we can learn the relevant dimensions +by calling |xv_get|. But if the user has not specified a font, the +situation is trickier; |xv_get| will report the width of the default +{\it non\/}-fixed-width font, and this will probably differ from the width of +the actual fixed-width font the tty subwindow will choose. + +Curiously, if we call |xv_find(NULL,FONT,FONT_FAMILY, +FONT_FAMILY_DEFAULT_FIXEDWIDTH,NULL)| {\it before\/} calling |xv_init|, +without even doing anything with the result returned by |xv_find|, +|xv_init| will not install any fonts specified on the command line. +The trick we used for icons---installing the default gnu icon on the first +call to |xv_create|---will therefore fail. + +Thus, we have to work around two distinct bugs in XView. The solution +is to discover the effects of the user's command line after |xv_init| +has acted and the frame has been set up; we can determine by brute force what +font will go into the tty window. The program below works correctly +even if the command line specifies \.{-scale} \.{large}, say, instead of +specifying a new font explicitly by something like \.{-font} \.{9x15}. + +While we are cataloguing peculiarities of XView, we might as well mention +that the default character dimensions of the default font (Lucida) are +reported to be $8\times13$ in the 12-point (medium) size, $8\times15$ in the +14-point (large) size, and $12\times20$ in the 19-point (extralarge) size. +The actual character dimensions in the window come, however, from the +default fixed-width font (Lucida typewriter), and they are $7\times13$, +$9\times15$, and $11\times23$ in the same three sizes. No logical progression +is evident in either the variable-width or the fixed-width dimensions, +although Lucida is a ``scalable font family.'' + +@<Compute the height and width of characters in the font@>= +{ + Xv_font font=(Xv_font)xv_get(frame,XV_FONT); + Xv_font dfont=(Xv_font)xv_find(NULL,FONT,FONT_FAMILY, + FONT_FAMILY_DEFAULT,NULL); + if (strcmp((char*)xv_get(font,FONT_NAME), + (char*)xv_get(dfont,FONT_NAME))==0) { + /* the user didn't specify a new font by name */ + dfont=(Xv_font)xv_find(NULL,FONT,FONT_FAMILY, + FONT_FAMILY_DEFAULT_FIXEDWIDTH,NULL); + /* this one will be used by the tty window */ + } else dfont=font; + char_width=(int)xv_get(dfont,FONT_DEFAULT_CHAR_WIDTH); + char_height=(int)xv_get(dfont,FONT_DEFAULT_CHAR_HEIGHT); +} + +@ @<Global...@>= +int char_width, char_height; /* character dimensions in the font */ + +@ @<Include...@>= +#include <xview/font.h> /* header for the font package */ + +@ OK, we've figured out how to install a tty subwindow with the right +event mask and the right cursor, and how to calculate the sizes of the +characters it will contain. All that remains is for us to do these +operations in the proper order, and to specify a filter routine that +will monitor and edit all communications between the keyboard and the +Emacs processor in the window. + +The new ingredient is the filter specification. We tell the XView +notifier to call |filter| when a window event occurs, instead of +letting it call the tty subroutine event handler directly. The parameter +|NOTIFY_SAFE| implies that the window's event handler is +part of XView, not an alien routine. + +@<Install the components...@>= +@<Scan the command line, setting |rv| nonzero if \.{-rv} is present@>; +xv_init(XV_INIT_ARGC_PTR_ARGV,&argc,argv,NULL); + /* start XViewing; strip and remember the OpenWin arguments */ +@<Create a frame with the gnu icon@>; +@<Remove the frame header...@>; +@<Put a tty subwindow into the frame@>; +@<Prepare to be notified when the mouse enters the window@>; +@<Change the cursor, to avoid black-on-black@>; +@<Compute the height and width of characters in the font@>; +notify_interpose_event_func(window,filter,NOTIFY_SAFE); + +@* Keyboard events. +The job of an interposed filter function is to look at an event and +either process it ourselves or pass it through (possibly modified) +to its normal recipient. In the first case we return the code +value |NOTIFY_DONE|, since we aren't reporting any errors; +in the second case we call the normal event handler and return the value +it returns to us. + +An XView event is a data structure that has been partially +interpreted by the XView routines, which add semantic sugar to +the complex union type of X~Window events. We need not look +too far inside an event structure to do the things that concern us. + +And what is our job? We are looking for three different kinds of events: + +\smallskip +\itemitem{(1)} When the mouse enters the window, +we want to grab the keyboard focus. + +\itemitem{(2)} When a mouse button goes up or down, and we have the keyboard +focus, we want to send a coded sequence of characters to \.{emacs}. + +\itemitem{(3)} When a key goes down, and we have the keyboard focus, we +want to send an appropriate sequence of characters to \.{emacs}. + +\itemitem{(4)} When the status of the Num Lock indicator light changes, we +will send emacs the command {\tt turn-numlock-on} or {\tt turn-numlock-off}, +for reasons described below. + +\smallskip\noindent Other events, like instructions to repaint or +resize the window, will be passed through without change to the tty window. + +@<Event-handling...@>= +Notify_value filter(window,event,arg,type) + Xv_window window; /* the ``client'' on whom we interposed */ + Event *event; /* the data we are filtering */ + Notify_arg arg; /* optional communication parameter between clients */ + Notify_event_type type; /* |NOTIFY_SAFE| or |NOTIFY_IMMEDIATE| */ +{@+register int id=event_id(event); +#ifdef DEBUG + printf("event %d%s, action %d, shift %x, mouse(%d,%d)\n", + event_id(event),event_is_up(event)?"UP":"DOWN",event->action, + event_shiftmask(event),event_x(event),event_y(event)); +#endif + @<Update the Num Lock status@>; + if (id==LOC_WINENTER) @<Grab the keyboard focus and return@>; + if (event_is_button(event)) @<Translate a mouse event and return@>; + if (event_is_up(event)) return NOTIFY_DONE; /* key has been released */ + @<Translate a function key into a special escape sequence@>; + @<Sanitize a keypress event so that unusual semantic actions are removed@>; + return notify_next_event_func(window,event,arg,type); /* pass it through */ +} + +@ It's easy to take charge of the keyboard and mouse, as soon as the mouse +enters our territory. + +@<Grab...@>= +{ + win_set_kbd_focus(window,xv_get(window,XV_XID)); + return NOTIFY_DONE; +} + +@ If the event is not related to mouse buttons or special function keys, +we want to pass it on unchanged, unless its |event_id| is less than 128. +In that case, it represents a character code, and we want to nuke any +semantic ``keyboard acceleration'' actions it might have been assigned +by OpenWindows. + +We also make the Meta key add 128 here. An undocumented macro +called |event_set_id|, found in \.{<xview/win\_input.h>}, +clears the |action| code as desired. + +@<Sanitize...@>= +if (id<128) + if (event_meta_is_down(event)) event_set_id(event,id+128); + else event_set_action(event,ACTION_NULL_EVENT); + +@* Function keys. +The Sun Type 4 keyboard has lots of keys, and these can be bound to lots +of useful functions when we are \.{emacs}ing to the max. Besides the +letters and punctuation marks of a normal typewriter, there are ten +``left'' function keys, L1--L10; twelve ``top'' function keys, F1--F12; +fifteen ``right'' function keys, R1--R15; and eight additional keys +labeled Help, Alt, AltGraph, Ins, Del, Enter, $+$, $-$, which we will +pretend have been labeled B1--B8. + +The L5 key, also known as Front, is controlled by the Open Look +window manager; it makes a window rise above any that might overlap it, +or shoves the window underneath in case it already was on top. + +The L7 key, aka Open, is likewise preempted by the +window manager. It closes a frame to an icon, or opens an icon. + +The window manager traps the R2 key and calls it the ``language'' key; +but I have no use for that feature. So I have remapped R2 to the comparatively +useless character $3\over4$, and I will translate it back to R2 below. (The +\.{xmodmap} program allows users to reassign the interpretation of key codes.) +I could have recovered the L5 and L7 keys in the same way, but I like +their functions as they stand. (L5 and L7 still come through if a +Shift, Control, and/or Meta key is down.) + +I can never remember the difference between Delete and BackSpace, so I +have mapped them both into control-?, ASCII code 127. + +There are two Shift keys, one at the left and one at the right, which +are best kept indistinguishable from each other. Similarly, the left +and right Meta keys (`\.{\char27}') are essentially identical. There's a +Control key too. These three types of modifier keys generate keypress +events, but we ignore them; the only thing that matters to us is whether +they are currently up or down, when other keys are pressed. + +\font\ttit=cmitt10 +There also are three special keys that do not generate events, so we +never see them. The CapsLock key toggles the Caps Lock light and +changes lowercase letters to uppercase when the light is on. The +NumLock key toggles the Num Lock light and changes the interpretation +of R4--R15 and B4--B8 when that light is on. The Compose key turns the +Compose light on until you type two characters, then it produces a +special symbol if those two characters match a pattern. For example, +when Compose is followed by either \.{a"} or \.{"a} you get the 8-bit +ISO code for {\tt \"a}; when Compose is followed by either \.{th} or +\.{ht} you get the Icelandic thorn; when it's followed by \.{??} you get {\tt +?`}; \.{c/} and \.{L-} give \rlap{\./}\.c and {\ttit\char`\$} +and so on. (A list of all composition patterns +appears in \.{<X11/Suncompose.h>}, but not in any of the manuals +I've seen.) The light goes off after two characters have been +typed, or if your first character is not composable, or if +you hit Compose again prematurely. If no proper two-character pattern +was specified, only ``up'' events (key releases) are transmitted, and +nothing will pass through to \.{emacs}. + +One other feature is worth noting: The key between F12 and Delete +produces a backslash `\.\\', or a vertical line `\.{\char125}' when +shifted. Everybody knows that, but even more is true. If you hold the +AltGraph key down and press this key, it turns out that you get the +broken-bar character `{\tt\hbox to1em{\hss\vbox{\hrule width 1pt height +3pt\vskip1.5pt\hrule height2pt depth1pt}\hss}}'. This is the only key that the +engineers chose to endow with three different graphic symbols. + +A few other anomalies occur; for example, AltGraph-R1 gives ASCII null, +while AltGraph does not affect R4. But I didn't discover any additional +combinations that are either useful or harmful. + +Once upon a time the Caps Lock key might have affected the |event_shiftmask| +field of an event, but it has no effect now. The shiftmask is always an +even number, contrary to the implications of \.{<xview/win\_input.h>}. + +@ The function keys will be translated into a four-character code. +First comes control-X; then an asterisk; then a letter, \.{a}--\.{o} +for function numbers 1--15, respectively; and then another letter, +identifying left, right, top, or bottom. The final letter is +ordinarily `\.l', `\.r', `\.t', or `\.b', respectively. But it is `\.L', `\.R', +`\.T', or `\.B' if a Shift key is down. Furthermore the Control key +subtracts 64 from the ASCII code, so you get `\.,', `\.2', `\.4', or +`\."' with Control and no Shift. With both Control and Shift you get +\.{\\C-L}, \.{\\C-R}, \.{\\C-T}, \.{\\C-B}. A Meta key adds another 128 +to the code. Thus, each function key leads to eight possibilities. + +For example, if F4 is pressed when Control and Shift are down, but not +Meta, the four-letter code is \.{\\C-X*d\\C-T}. The user could type +that sequence of four characters and get the same effect. + +Shifted function keys sometimes have a nice mnemonic significance. +For example, key R14, also labeled PgDn, is usually bound to the Emacs +operation `\.{scroll-up}', which moves the window down [sic] by one +screenful; we can then bind Shift-R14 to \.{forward-page}, which advances +down to the next page boundary. In \.{cweb-mode}, the next page boundary +is the next \.{@@*}, beginning a major part of the program. Similarly, +it's convenient to bind B7, the keypad `\.+' key, to \.{forward-paragraph}. +Then in \.{cweb-mode}, Shift-B7 goes to the next module (the next +\.{@@\ } or \.{@@*}). + +A Composed character will be preceded by \.{\\C-Q}, the Emacs `quote' +character, to distinguish it from a character that was generated with the +Meta key down. This also applies to the broken-bar character, which +will incidentally be preceded by AltGraph, which is B3; you'll probably +want to bind B3 to a no-op if broken bars are important to you. + +@ This program assumes that several key codes have been rebound from +their normal values. Namely, the commands +$$\vbox{\halign{\.{#}\hfil\cr +keysym R2 = threequarters\cr +keysym KP\_Subtract = onehalf\cr +keysym KP\_Add = onequarter\cr +keysym KP\_Enter = threesuperior\cr +keysym KP\_Decimal = twosuperior\cr +keysym KP\_0 = onesuperior\cr}}$$ +should be executed by \.{xmodmap}, preferably in the user's \.{.xinitrc} file. +This makes the keys act as $3\over4$, $1\over2$, $1\over4$, $^3$, $^2$, and +$^1$, respectively. The corresponding 8-bit codes are respectively +190, 189, 188, 179, 178, 185. (By the way, can anybody explain why the ISO +LATIN-1 code has $^0$, $^2$, and $^3$ in the positions of meta-0, meta-2, +and meta-3, while $^1$ is in the position of meta-9?) +@.xmodmap@> + +We haven't actually bound the keys this way to use them in editing. +We did it to provide linguistically unimportant codes that OpenWindows +wouldn't mess up; its normal conventions make those valuable keys +unusable for editing, except as duplicates for other existing keys. + +We send \.{turn-numlock-on/off} commands so that \.{emacs} can keep in +synch with the keyboard state. Namely, it will rebind the function +keys B4--B8 to their numeric-keypad equivalents while the Num Lock light is on. + +On the other hand, our remapping does make the Num Lock +feature useless in other (non-Emacs) applications. If you don't +rebind the keys as stated, you lose the functionality of R2 and B4--B8, +but \.{oemacs} will still work. + +The Help key is another special case. We don't want to remap it, +because it gives useful help information with other OpenWindows +applications. If Help is pressed without the shift or control key, +the |event_id| is zero and the |event_action| is |ACTION_HELP|. +Control-Help is similar, but with |ACTION_TEXT_HELP|. Shift-Help is +more complicated; it invokes `helpopen: starting new Viewer', after +generating an event that has |event_action=WIN_VISIBILITY_NOTIFY|. The +program below considers the Help key B1 to be characterized by any +event with |event_id=0| and either |event_action!=0| or +|event_shiftmask!=CTRLMASK|. + +@<Translate a function key into a special escape sequence@>= +{@+register int bank='b'; /* |'l'|, |'r'|, |'t'|, or |'b'| */ + register int n; /* function key serial number, |1<=n<=15| */ + if (id>=KEY_LEFT(1)) @<Translate an ordinary function key@>@; + else if (id>=256) @<Look for Alt or AltGraph@>@; + else if (id>=128) + @<Translate a special function key or composed character@>@; + else if (id>0 || + (event_action(event)==0 && event_shiftmask(event)==CTRLMASK)) + goto non_function; + else n=1; /* Help key */ +emit_function_key:@<Emit the code for a function key and |return|@>; +non_function:; +} + +@ I'm assuming here that the event id codes occur in the order left, right, +top, bottom, and that no higher event codes exist. + +@<Translate an ordinary function key@>= +{ + if (id<KEY_RIGHT(1)) { /* on the left bank */ + bank='l';@+n=id-KEY_LEFT(0); + } else if (id<KEY_TOP(1)) { /* on the right bank */ + bank='r';@+n=id-KEY_RIGHT(0); + } else if (id<KEY_BOTTOM(1)) { + bank='t';@+n=id-KEY_TOP(0); + } else n=id-KEY_BOTTOM(0); + goto emit_function_key; +} + +@ The event codes examined here appear in \.{<xview/win\_event.h>} +but not in the XView reference manual. + +@<Look for Alt or AltGraph@>= +if (id==SHIFT_ALT) { + n=2;@+goto emit_function_key; +} else if (id==SHIFT_ALTG) { + n=3;@+goto emit_function_key; +} else goto non_function; + +@ The |ttysw_input| routine sends text to a tty's view window. +The second parameter is a string, not necessarily terminated by +|'\0'| or anything else; the third parameter is the string length. + +@<Emit the code for a function key and |return|@>= +{ + if (event_shift_is_down(event)) bank-=32; + if (event_ctrl_is_down(event)) bank-=64; + if (event_meta_is_down(event)) bank+=128; + buf[2]=n+'a'-1; + buf[3]=bank; + ttysw_input(window,buf,4); + return NOTIFY_DONE; +} + +@ @<Global...@>= +char buf[]="\030*??\021"; /* |030| and |021| give control-X, control-Q */ + +@ @<Translate a special function key or composed character@>= +switch (id) { +case 190: bank='r';@+n=2;@+goto emit_function_key; +case 189: n=8;@+goto emit_function_key; +case 188: n=7;@+goto emit_function_key; +case 179: n=6;@+goto emit_function_key; +case 178: n=5;@+goto emit_function_key; +case 185: n=4;@+goto emit_function_key; +default: buf[5]=id; /* composed character or broken-bar */ + ttysw_input(window,buf+4,2); + return NOTIFY_DONE; +} + +@* The NumLock key. +The global variable |num_lock_state| will be 0 if the Num Lock indicator +light is off, 1 if it is on. Whenever an event occurs, we check to see +if |num_lock_state| should change; if so, we change it and send an +appropriate command to \.{emacs}. + +To read the state of the keyboard LED indicator lights, we need an I/O +control command called the |KIOCGLED| ioctl, described on the +man page for \.{kb(4m)}. + +@<Global...@>= +int num_lock_state; +char turnon[]="\370turn-numlock-on\r", turnoff[]="\370turn-numlock-off\r"; +int keyboard; /* file descriptor of \.{/dev/kbd} */ + +@ @<Include...@>= +#include <sys/file.h> /* definition of |O_RDWR| for |open| */ +#include <sundev/kbio.h> /* definition of |KIOCGLED| for |ioctl| */ + +@ @d LED_NUM_LOCK 0x1 /* the official definition is in \.{<server/sunevq.h>}, + but that header file includes huge gobs of other stuff */ + +@<Update the Num Lock status@>= +{@+char leds; /* binary encoding of LED lights */ + ioctl(keyboard,KIOCGLED,&leds); + if ((leds&LED_NUM_LOCK)!=num_lock_state) { + num_lock_state=leds&LED_NUM_LOCK; + if (num_lock_state) ttysw_input(window,turnon,17); + else ttysw_input(window,turnoff,18); + } +} + +@ Any ordinary user can apparently open the keyboard as a file. I would +have tried read-only access if read-write had failed; but read-write access +gives a sense of power even though I won't be writing anything. + +@<Special initialization@>= +keyboard=open("/dev/kbd",O_RDWR); +if (keyboard<0) { + fprintf(stderr,"%s: Can't open /dev/kbd!\n",argv[0]); + exit(1); +} + +@* Mouse events. +When a mouse button is pressed or released, we send \.{emacs} the +codes control-X and ASCII null, followed by a parenthesized list +of four numbers and carriage-return. +For example, as I was typing this paragraph, I +clicked the left mouse button on the screen just for fun; \.{emacs} +received the characters +$$\.{\\030\\0(1 18 28 9999)\\r\\030\\0(129 18 28 141)\\r}$$ +as a result (according to `\.{view-lossage}'). I would have received +the same response if I had typed these characters myself, instead +of clicking the mouse. + +The first of the four numbers identifies the mouse button itself +as the code number 1, 2, or 4 (for left, middle, right), plus 8 if +a Shift key is down, plus 16 if the Control key is down, plus 32 +if a Meta key is down, plus 128 if the mouse key is being released +instead of pressed. + +The second number is the row number in the frame, the top row being +considered row~0. + +The third number is the column number in the frame, the left column being +considered column~0. + +The fourth number is the elapsed time between this mouse event and the +previous one, in milliseconds. If the elapsed time was 10 seconds or +more, 9999 is substituted. + +Macros inside \.{emacs} can use the second and third numbers to +position the cursor. The fourth number can be used to determine if the +user is ``double clicking'' or using ``chords.'' Examples of such +macros appear in the Emacs source file \.{lisp/sun-mouse.el}. + +Incidentally, the ASCII null character in mouse sequence makes us happy that +the string parameter to |ttysw_input| is not null-terminated. + +@<Translate a mouse event...@>= +{@+register int button_code,elapsed_time; + button_code=(id==MS_LEFT? 1: id==MS_MIDDLE? 2: 4); + if (event_shift_is_down(event)) button_code += 8; + if (event_ctrl_is_down(event)) button_code += 16; + if (event_meta_is_down(event)) button_code += 32; + if (event_is_up(event)) button_code += 128; + @<Compute the time elapsed since the previous mouse event@>; + sprintf(mouse_buf+2,"(%d %d %d %d)\r",button_code,@| + event_x(event)/char_width, event_y(event)/char_height,@| + elapsed_time); + ttysw_input(window,mouse_buf,12+strlen(mouse_buf+12)); /* length is at least 12 */ + return NOTIFY_DONE; +} + +@ @<Global...@>= +char mouse_buf[24]="\030"; + +@ XView's event structure includes |event_time(event)|, which has +type |struct timeval|; this data type is declared in \.{<sys/time.h>}, +which is one of the files included automatically as a result of +including \.{<xview/xview.h>}. +A |timeval| structure consists of two |long| integers, |tv_sec| and |tv_usec|, +denoting clock time in seconds and microseconds, respectively. + +@<Compute the time...@>= +{@+struct timeval now; /* current time */ + long delta_sec, delta_usec; /* difference between current and + previous time */ + now=event_time(event); + delta_sec=now.tv_sec-prev_mouse_time.tv_sec; + delta_usec=now.tv_usec-prev_mouse_time.tv_usec; + if (delta_usec<0) delta_usec+=1000000,delta_sec--; + if (delta_sec>=10) elapsed_time=9999; /* infinity (or close enough) */ + else elapsed_time=(delta_sec*1000)+(delta_usec/1000); + prev_mouse_time=now; +} + +@ @<Global...@>= +struct timeval prev_mouse_time; + +@* Remaining problems. There's a terribly unfortunate bug in the +present implementation of XView, causing characters of tty subwindows +to be badly painted at crucial times; the rightmost column of pixels +in a character is often clobbered. If I could figure out how to +generate repaint events for the tty subwindow, I might build a mechanism +into \.{oemacs} that does this after the keyboard has been idle for 10 +seconds, say. This would blink the screen; maybe I'll get used to that, +or maybe I'll prefer to refresh the window manually by binding +\.{redraw-display} to the L2 and R1 keys. In any case a lot of screen +refreshing is necessary at the moment, alas. + +(Note added later: I doubt if I'll get used to blinking, and the present +method of manual refresh is tolerable so I won't pursue the 10-second +timer idea. I have meanwhile noticed a procedure |wmgr_refreshwindow(window)| +mentioned in \.{<xview/wmgr.h>}; it will presumably refresh any +given window. + +Another bug, much less serious, occurs when the window is resized. +If the window gets smaller, \.{emacs} isn't told to correct its +assumptions; so it puts information in strange places or offscreen. +(Internally, emacs uses the \.{TIOCGWINSZ} or \.{TIOCSWINSZ} ioctl, +described in the man page for \.{termio}.) +You can work around this by first making the window very small, then +making it large. + +@* Index. + + |