v06i066: Xpw Documentation, Part02/02
Jonathan Meyer
jonm%syma.sussex.ac.uk at NSFnet-Relay.AC.UK
Thu Apr 12 17:36:55 AEST 1990
Submitted-by: Jonathan Meyer <jonm%syma.sussex.ac.uk at NSFnet-Relay.AC.UK>
Posting-number: Volume 6, Issue 66
Archive-name: xpwdoc/part02
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 2 (of 2)."
# Contents: doc/ref/PopScrollText doc/ref/PopText
# doc/ref/XpwCallMethod doc/ref/XpwMethods doc/ref/XpwResources
# doc/man/poplog.man doc/sysdoc/PopWidgets.imp
# Wrapped by jonm at csunb on Wed Apr 4 16:16:15 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/ref/PopScrollText' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/ref/PopScrollText'\"
else
echo shar: Extracting \"'doc/ref/PopScrollText'\" \(19823 characters\)
sed "s/^X//" >'doc/ref/PopScrollText' <<'END_OF_FILE'
XREF *PopScrollText Jonathan Meyer, Jan 1990
X
XPoplog Widget Set, revision 3.
X
XThis file describes the PopScrollText widget class, which is part of the
XPoplog Widget Set. For details of other widgets in the Poplog Widget
XSet, see HELP *PopWidgets. For information about the Pop-11 interface to
Xthe PopScrollText widget, see HELP *PopScrollText.
X
X
X CONTENTS - (Use <ENTER> g to access required sections)
X
X -- PopScrollText Widget
X -- PopScrollText Resources
X -- Information about new resources
X -- Handling Exposure Events
X -- Actions
X -- PopScrollText Translations
X -- Methods
X -- Scroll Operations
X -- Clear Operations
X -- Write Operations
X -- Cursor and Misc Operations
X
X-- PopScrollText Widget -----------------------------------------------
X
XSuperclass: PopCore
X
XThe PopScrollText widget is a low level text widget. It provides the programmer
Xwith the ability to write text on a window, and scroll it about. The widget also
Xnotifies the application of exposure and input events, so that the program can
Xredraw the text, process input etc. The PopScrollText widget maintains an
XXtNexposedLines resource, which contains a list of lines that need redrawing
Xafter an exposure event. It also converts mouse locations into text rows/
Xcolumns, and allows applications to manipulate a text cursor.
X
XThe widget does not keep a copy of the text that is on the window, and so
Xit cannot refresh itself. However, it is very helpful for editors (VED)
Xthat already do the hard work of keeping a terminal updated, but don't
Xwork with Xlib.
X
XThere are a variety of operations that can be performed on ScrollText
Xwidgets. Most of the operations involve scrolling text, or writing text.
X
X
X-- PopScrollText Resources --------------------------------------------
X
XPopScrollText inherits all of the resources of PopCore. The following
Xresources are retrieved from the resource database or the argument list
Xwhen PopScrollText widgets are created:
X
X
X========================================================================
XName Class RepType Default* Description
X========================================================================
XXtNwidth Width Dimension 0 Window width
XXtNheight Height Dimension 0 Window height
XXtNx X Position 0 X coordinate in pixels
XXtNy Y Position 0 Y coordinate in pixels
XXtNborderWidth BorderWidth Dimension 1 Border width in pixels
XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap
XXtNborderColor BorderColor Pixel foreground Window border color
XXtNbackground Background Pixel XtDefault Window background color
XXtNforeground Foreground Pixel XtDefault Window foreground color
XXtNfont Font FontStruct XtDefault Font for text operations
XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont)
XXtNtranslations Translations String see below Event-to-action translations
XXtNpopCallback Callback Pointer NULL Callbacks for expose events
XXtNautoFlush Boolean Boolean TRUE XFlush after methods?
XXtNusersGC GC Pointer NULL Graphics Context for ops
XXtNmodifiers Parameter Int None event->state modifiers
XXtNtopMargin TopMargin Dimension 0 Distance to start of text
XXtNleftMargin LeftMargin Dimension 2 Distance to start of text
XXtNfontWidth Width Dimension None Width of current font
XXtNfontHeight Height Dimension None Height of current font
XXtNcursorRow Position Position 0 Cursors Y location
XXtNcursorColum Position Position 0 Cursors X location
XXtNcursorStatus CursorStatus Boolean TRUE Cursor on/off
XXtNmouseX MouseLocation Int None Mouse column
XXtNmouseY MouseLocation Int None Mouse row
XXtNnumRows Dimension Dimension 24 Text columns
XXtNnumColumns Dimension Dimension 80 Text rows
XXtNexposedLines Parameter (int *) NULL Lines that need redrawing
XXtNkey Key String NULL Ascii string of KeyPress
XXtNkeyboardEvent Callback Callback NULL keyboard inputs callback
XXtNbuttonEvent Callback Callback NULL Mouse buttonpress events
XXtNmotionEvent Callback Callback NULL Mouse motion events
XXtNdestroyCallback Callback NULL XtDestroyWidget callback
X
X
X-- Information about new resources -----------------------------------
X
XXtNfontWidth XtNfontHeight
X fontWidth and fontHeight are the dimensions of the current font in pixels.
X The font is expected to have a fixed width.
X
XXtNtopMargin XtNleftMargin
X distance from top and left of window where text starts.
X
XXtNnumRows, XtNnumColumns
X These are based upon the current font and window size. They are calculated
X from fontWidth and fontHeight, as well as the width and height of the
X window. They are the number of text rows and columns that can be fitted
X into the window. Row 0, Column 0 is the top left character of the window.
X
X Changing the widgets font will cause fontWidth, fontHeight, numRows
X and numColumns to be recalculated. Resizing the widget will cause
X numRows and numColumns to be recalculated, and exposedLines to be
X recreated.
X
XXtNexposedLines
X The 'exposedLines' resource is an array of unsigned ints, with the number
X of elements of the array kept the same as the number of rows of text in the
X widget. After an exposure event, this array is set as follows:
X For each line of text in the window that needs to be redrawn:
X the lower short of the array element for that line is set to
X the start column and the higher short is set to the end column of text
X that needs to be redrawn. See below for more information on exposed lines.
X
X
XXtNcursorRow, XtNcursorColumn
X An inverse rectangle is used to represent the cursor. Changing these
X resources will cause the cursor to be unplotted and moved to the new
X location. Any of the methods that can be applied to the PopScrollText
X widget are aware of the cursor, and will replot it if necessary.
X
XXtNcursorStatus
X If this resource is false, or off, the text cursor is not displayed in the
X widget. By default the cursor is displayed.
X
XXtNkeyboardEvent XtNbuttonEvent XtNmotionEvent
X These three callbacks are used to notify the client of key, button and
X motion events. See below.
X
XXtNkey
X This is the string returned from XLookupKeysym when given the Keysym
X of a keyboard event. This resource is set each time a key is pressed
X or released. In many cases it will be the ASCII string of the key
X that was pressed.
X
XNOTE: Currently, if you change a PopScrollText's font or margins it DOES
XNOT clear the window and force a redisplay. This allows you to display
Xmultiple fonts in the same window, though you have to be careful about
Xdoing so. If you do want only one font, then call XpwMClearWindow after
Xeach font/margin change.
X
X
X-- Handling Exposure Events -------------------------------------------
X
XExposure events happen when an area of the window that was occluded is
Xmade visible by a raise/lower or map/unmap event. They also occur when a
Xscroll operation is used on a region that is partially occluded. (This
Xtype of exposure is called GraphicsExsposure).
X
XWhen repainting text in a PopScrollText widget, the following may be useful:
X
XThe simplist refresh algorithm would work as follows:
X
X for each line on display
X if exposed_lines(line) is not 0 then
X refresh line
X endif
X endfor
X
XMore complex redraw algorithms could work out which part of the line
Xneeds to be redrawn. The C macros:
X
X int XpwExposeStart(line_entry)
X int XpwExposeEnd(line_entry)
X
XReturn the start and end column derived from an entry in the exposedLines
Xresource. These can be used to calculate exactly which lines need to be
Xredrawn.
X
X-- Actions ---------------------------------------------------------------
X
X
XThe following actions call their associated callback list with data extracted
Xfrom the event.
X
X Name Event Call Data
X ------------------- ------------------ ----------------------
X notify-button-event Button Events Button number*
X notify-key-event Key Events Keysym of key*
X notify-motion-event <Btn>Motion events event->state@
X
X*Button number and Keysyms are signed integers. They are positive when
X the button/key goes down and negative when the button/key comes up.
X
X at only calls the callback if mouseX and mouseY resources have changed, ie.
X when the mouse moves into a new character cell.
X
XThe following additional actions are used by the PopScrollText widget:
X
X Name Event Notes
X ---- ------------------ ---------------------
X notify-graphics-expose Graphics Expose calls popCallback
X highlight-cursor Enter Window
X unhighlight-cursor Leave Window
X
X
X-- PopScrollText Translations --------------------------------------------
X
XThe default translations for PopScrollText widgets are as follows:
X
X
X "<BtnDown>: notify-button-event() \n\
X <BtnUp>: notify-button-event() \n\
X <Keypress>: notify-key-event() \n\
X <KeyRelease>: notify-key-event() \n\
X <EnterWindow>: highlight-cursor() \n\
X <LeaveWindow>: unhighlight-cursor() \n\
X <GraphicsExpose>: notify-graphics-expose() \n\
X <Motion>: notify-motion-event()";
X
X-- Methods --------------------------------------------------------------
X
XThe PopScrollText widget responds to all of the PopCore methods. Additionally
Xit responds to a set of methods that are used to manipulate the text on the
Xwidget. The methods can be grouped as follows:
X
X Scrolling methods
X Clearing methods
X Writing methods
X Cursor/Misc methods
X
XIn the case of Scrolling, Clearing and Writing, there is one primative
Xgeneric method for each action, and several convenience methods that call
Xthe generic method with calculated arguments. There are also several
Xmethods that apply the generic Scrolling/Clearing/Writing method at the
Xcurrent cursor location.
X
XMethod Name Arguments Notes
X========================================================================
XXpwMScroll col,row,cols,rows,x_dist,y_dist
XXpwMScrollScreenUp -
XXpwMScrollScreenDown -
XXpwMScrollScreenLeft -
XXpwMScrollScreenRight -
XXpwMScrollLines row, rows, dist
XXpwMScrollTail col, row, dist
XXpwMScrollTails col, row, rows, dist
XXpwMScrollTailLeft col, row
XXpwMScrollTailRight col, row
XXpwMInsertLineAtCursor -
XXpwMInsertCharAtCursor -
XXpwMDeleteLineAtCursor -
XXpwMDeleteCharAtCursor -
XXpwMClear col, row, cols, rows
XXpwMClearWindow -
XXpwMClearLine row
XXpwMClearLines row, rows
XXpwMClearTail col, row
XXpwMClearTails col, row, rows
XXpwMClearChar col, row
XXpwMClearLineAtCursor -
XXpwMClearTailAtCursor -
XXpwMClearCharAtCursor -
XXpwMInsert col, row, str, len
XXpwMInsertAtCursor str, len
XXpwMWrite col, row, index, lines, strs, off,len,clr
XXpwMWriteLine col, row, str, len, clr
XXpwMWriteLines col, row, index, lines, strs, len, clr
XXpwMWriteSubstr col, row, str, off, len, clr
XXpwMWriteAtCursor str, len
XXpwMCursorTo col,row
XXpwMCursorUp -
XXpwMCursorDown -
XXpwMCursorLeft -
XXpwMCursorRight -
XXpwMBell volume
X
X
X-- Scroll Operations --------------------------------------------------
X
XXpwMScroll
X XpwCallMethod(widget,XpwMScroll, col,row,cols,rows,x_dist,y_dist);
X Widget widget;
X int col, row, cols, rows, x_dist, y_dist;
X
X Scrolls the region starting at col, row, of width cols and height rows,
X by distance x_dist, y_dist. x_dist and y_dist can be positive or negative
X integers, and are measured in character cells. If cols or rows are zero,
X the current width/height of the window are used.
X
XXpwMScrollScreenUp
XXpwMScrollScreenDown
XXpwMScrollScreenLeft
XXpwMScrollScreenRight
X XpwCallMethod(widget,XpwMScrollScreenUp);
X XpwCallMethod(widget,XpwMScrollScreenDown);
X XpwCallMethod(widget,XpwMScrollScreenLeft);
X XpwCallMethod(widget,XpwMScrollScreenRight);
X Widget widget;
X
X Scroll the screen one character cell in each direction
X
XXpwMScrollLines
X XpwCallMethod(widget,XpwMScrollLines, row, rows, dist);
X Widget widget;
X int row, rows, dist;
X
X Scroll the text starting at row and extending to row+rows by distance dist.
X Distance dist can be a positive or negative integer specifying the number
X of character cells to move the text up/down. If rows is zero, the current
X height of the window is used.
X
XXpwMScrollTail
XXpwMScrollTails
X XpwCallMethod(widget,XpwMScrollTail, col, row, dist);
X XpwCallMethod(widget,XpwMScrollTails, col, row, rows, dist);
X Widget widget;
X int col, row, rows, dist;
X
X Scroll all of the text to the left of col, on row (extending row+rows)
X left or right acording to distance dist. Dist is a positive or negative
X integer specifying the number of character cells to move the text.
X If rows is zero, the current height of the window is used.
X
XXpwMScrollTailLeft
XXpwMScrollTailRight
X XpwCallMethod(widget,XpwMScrollTailLeft, col, row);
X XpwCallMethod(widget,XpwMScrollTailRight, col, row);
X Widget widget;
X int col, row;
X
X Insert or delete a character at col,row by scrolling the tail of the
X line left or right by one character cell.
X
XXpwMInsertLineAtCursor
X XpwCallMethod(widget,XpwMInsertLineAtCursor);
X Widget widget;
X
X Insert a line at the current cursor position by scrolling the text on
X that line, and lines below it, down.
X
XXpwMInsertCharAtCursor
X XpwCallMethod(widget,XpwMInsertCharAtCursor);
X Widget widget;
X
X Insert a blank space at the current cursor location by moving the
X tail of the line right by one character cell.
X
XXpwMDeleteLineAtCursor
X XpwCallMethod(widget,XpwMDeleteLineAtCursor);
X Widget widget;
X
X Remove a line at the cursor position by scrolling the text below the
X line up one character cell.
X
XXpwMDeleteCharAtCursor
X XpwCallMethod(widget,XpwMDeleteCharAtCursor);
X Widget widget;
X
X Delete the character under the cursor by scrolling the text on the
X cursors line, after the cursors column, left one character cell.
X
X-- Clear Operations ---------------------------------------------------
X
XXpwMClear
X XpwCallMethod(widget,XpwMClear, col, row, cols, rows);
X Widget widget;
X int col, row, cols, rows;
X
X Clear the region specified by (col, row, col+cols, row+rows). If cols or
X rows are zero, the current length of the window are used.
X
XXpwMClearWindow
X XpwCallMethod(widget,XpwMClearWindow);
X Widget widget;
X
X Clear the whole window.
X
XXpwMClearLine
X XpwCallMethod(widget,XpwMClearLine, row);
X Widget widget;
X int row;
X
X Clear the text on the specified row.
X
XXpwMClearLines
X XpwCallMethod(widget,XpwMClearLines, row, rows);
X Widget widget;
X int row, rows;
X
X Clear the text on all lines starting at row, extending row+rows. If rows
X is zero, the height of the window is used instead.
X
XXpwMClearTail
X XpwCallMethod(widget,XpwMClearTail, col, row);
X Widget widget;
X int col, row;
X
X Clears text to the left of col, on row.
X
XXpwMClearTails
X XpwCallMethod(widget,XpwMClearTails, col, row, rows);
X Widget widget;
X int col, row, rows;
X
X Same as ClearTail for multiple lines. If rows is zero, the height of the
X window is used instead.
X
XXpwMClearChar
X XpwCallMethod(widget,XpwMClearChar, col, row);
X Widget widget;
X int col,row;
X
X Clear the character cell (col, row).
X
X
XXpwMClearLineAtCursor
X XpwCallMethod(widget,XpwMClearLineAtCursor);
X Widget widget;
X
X Clears the text on the current cursor row.
X
XXpwMClearTailAtCursor
X XpwCallMethod(widget,XpwMClearTailAtCursor);
X Widget widget;
X
X Clears the text to the left of the current cursor column, on the current
X cursor row.
X
XXpwMClearCharAtCursor
X XpwCallMethod(widget,XpwMClearCharAtCursor);
X Widget widget;
X
X Clears the character under the cursor.
X
X-- Write Operations ---------------------------------------------------
X
XNOTE: For string operations, if a negative number is given as the length of
Xthe string, the string is assumed to be a Poplog string, with its length
Xstored two words before the start of the string pointer.
X
XXpwMWrite
X XpwCallMethod(widget,XpwMWrite, col, row, index, lines, strs, off,len,clr);
X Widget widget;
X String strs[];
X Boolean clr;
X int col, row, index, lines, off, len;
X
X Takes an array of strings, strs. Takes an index into the array, and the
X number of lines from the array to draw. It starts at col, row on the
X screen and draws len characters of the string strs[index+line] starting
X at character off. If clr is true, the line is cleared first. This is
X repeated for the next line, on the next row. If len is zero, the
X string from character off onwards is drawn.
X
X
XXpwMWriteLine
X XpwCallMethod(widget,XpwMWriteLine, col, row, str, len, clr);
X Widget widget;
X String str;
X Boolean clr;
X int col, row, len;
X
X Writes len characters of the string str at col, row. If clr is true
X the line is cleared first. If len is zero, the whole string is drawn.
X
XXpwMWriteLines
X XpwCallMethod(widget,XpwMWriteLines,
X col, row, index, lines, strs, len, clr);
X Widget widget;
X String strs[];
X Boolean clr;
X int col, row, len, index, lines;
X
X Same as WriteLine, only it takes an array of strings strs and starts at
X strs[index], continuing to strs[index+lines]. If len is zero, the
X whole string is drawn
X
X
XXpwMWriteSubstr
X XpwCallMethod(widget,XpwMWriteSubstr, col, row, str, off, len, clr);
X Widget widget;
X String str;
X Boolean clr;
X int col, row, len, off;
X
X Writes len characters of the string str starting at character off,
X at col, row of the window. If clr is true, the line is cleared first. If
X len is zero, the string from character off onwards is drawn.
X
XXpwMWriteAtCursor
X XpwCallMethod(widget,XpwMWriteAtCursor, str, len);
X Widget widget;
X String str;
X int len;
X
X Writes the string str, of length len, at current cursors location. Moves
X cursor to end of string.
X
XXpwMInsert
X XpwCallMethod(widget,XpwMInsert, col, row, str, len);
X Widget widget;
X String str;
X int col, row, len;
X
X Scrolls tail of text at col, row right by len characters, and then
X draws the string.
X
XXpwMInsertAtCursor
X XpwCallMethod(widget,XpwMInsertAtCursor, str, len);
X Widget widget;
X String str;
X int len;
X
X Scrolls tail of text at the current cursor col and row right by len
X characters, and then draws the string at the cursor row and column.
X Moves the cursor to the end of the string.
X
X
X-- Cursor and Misc Operations ------------------------------------------
X
XXpwMCursorTo
X XpwCallMethod(widget,XpwMCursorTo, col,row);
X Widget widget;
X int col, row;
X
X Move the text cursor to col,row.
X
XXpwMCursorUp
XXpwMCursorDown
XXpwMCursorLeft
XXpwMCursorRight
X XpwCallMethod(widget,XpwMCursorUp);
X XpwCallMethod(widget,XpwMCursorDown);
X XpwCallMethod(widget,XpwMCursorLeft);
X XpwCallMethod(widget,XpwMCursorRight);
X Widget widget;
X
X
X Move the text cursor one character cell in each direction.
X
XXpwMBell
X XpwCallMethod(widget,XpwMBell, volume);
X Widget widget;
X int volume;
X
X Calls XBell to make a beep of the specified volume (0-100).
END_OF_FILE
if test 19823 -ne `wc -c <'doc/ref/PopScrollText'`; then
echo shar: \"'doc/ref/PopScrollText'\" unpacked with wrong size!
fi
# end of 'doc/ref/PopScrollText'
fi
if test -f 'doc/ref/PopText' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/ref/PopText'\"
else
echo shar: Extracting \"'doc/ref/PopText'\" \(4153 characters\)
sed "s/^X//" >'doc/ref/PopText' <<'END_OF_FILE'
XREF *PopText Jonathan Meyer, Jan 1990
X
XPoplog Widget Set, revision 3.
X
XThis file descibes the PopText widget. For information on the Pop-11 interface
Xto this widget, see HELP *PopText. For an overview of Poplog Widgets, see
XHELP *PopWidgets.
X
X-- PopText Widget -----------------------------------------------------
X
XSuperclass: (Athena) AsciiString Text
X
XThe PopText widget class is similar to PopCore and PopComposite in that
Xit adds a callback action to an existing widget class (from the Athena
XWidget Set). The callback is activated using an action in the
Xtranslation table. The default translation table is show below. Users
Xcan modify the translation table to trap specific events.
X
XThe PopText widget is useful in applications that want to use simple
Xtext editors, and to be able to specify new methods for handling key and
Xbutton events.
X
XThe PopText widget class variable is popTextWidgetClass.
X
XFor more information on the PopText widget, see the Athena Widget Set manual
Xsection on the Text widget.
X
X
X-- PopText Resources --------------------------------------------------
X
XPopText inherits the resources from the AsciiText and Text Athena widget
Xclasses. The following new resources are retrieved from the resource database
Xor argument list at widget creation:
X
X=========================================================================
XName Class RepType Default Description
X=========================================================================
XpopCallback Callback Pointer NULL Callback for Key/Btn events
X
XThe popCallback callback is used to notify applications of events.
X
X-- PopText Actions and Translations -----------------------------------
X
XThe PopText widget class has one additional action to the text widget
Xclass, called "notify-event". This action calls the 'popCallback' list,
Xpassing the event to the callback list. The notify-event action can be
Xspecified in the translations table to trap keys and buttons that the
Xapplication specifies. The default translations are:
X
Xstatic char defaultTranslations[] = "
XCtrl<Key>F: forward-word() \n\
XCtrl<Key>B: backward-word() \n\
XCtrl<Key>C: notify-event(CTR_C) \n\
XCtrl<Key>D: notify-event(CTR_D) \n\
XCtrl<Key>A: beginning-of-line() \n\
XCtrl<Key>E: kill-to-end-of-line() \n\
XCtrl<Key>H: delete-previous-character() \n\
XCtrl<Key>J: newline-and-indent() \n\
XCtrl<Key>K: backward-paragraph() \n\
XCtrl<Key>L: forward-paragraph() \n\
XCtrl<Key>M: newline() \n\
XCtrl<Key>P: delete-next-character() \n\
XCtrl<Key>V: next-line() \n\
XCtrl<Key>W: kill-selection() \n\
XCtrl<Key>Y: unkill() \n\
XCtrl<Key>Z: scroll-one-line-up() \n\
X<Key>Escape: notify-event(ESC) \n\
X<Key>Right: forward-character() \n\
X<Key>Left: backward-character() \n\
X<Key>Down: next-line() \n\
X<Key>Up: previous-line() \n\
X<Key>Delete: delete-previous-character() \n\
X<Key>BackSpace: delete-previous-character() \n\
X<Key>Linefeed: newline-and-indent() \n\
X<Key>Return: newline() \n\
X<Key>F1: select-start() \n\
X<Key>F2: select-end() \n\
X<Key>F3: backward-kill-word() \n\
X<Key>F4: beginning-of-line() kill-to-end-of-line() delete-previous-character()\n\
X<Key>F5: kill-to-end-of-line() \n\
X<Key>F6: backward-kill-word() \n\
X<Key>F7: kill-word() \n\
X<Key>F8: kill-selection() insert-selection()\n\
X<Key>F9: stuff() \n\
X<Key>R1: beginning-of-line() \n\
X<Key>R2: previous-page() \n\
X<Key>R3: end-of-line() \n\
X<Key>R4: beginning-of-line() \n\
X<Key>R5: next-page() \n\
X<Key>R6: end-of-line() \n\
X<Key>R7: backward-character() previous-line() \n\
X<Key>R9: forward-character() previous-line() \n\
X<Key>R13: backward-character() next-line() \n\
X<Key>R15: forward-character() next-line() \n\
X<Key>: insert-char() \n\
X<FocusIn>: focus-in() \n\
X<FocusOut>: focus-out() \n\
XCtrl<Btn1Down>: notify-event(BTN1) \n\
XCtrl<Btn2Down>: notify-event(BTN2) \n\
XCtrl<Btn3Down>: notify-event(BTN3) \n\
X<Btn1Down>: select-start() \n\
X<Btn1Motion>: extend-adjust() \n\
X<Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \n\
X<Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \n\
X<Btn3Down>: extend-start() \n\
X<Btn3Motion>: extend-adjust() \n\
X<Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) "
X
X
END_OF_FILE
if test 4153 -ne `wc -c <'doc/ref/PopText'`; then
echo shar: \"'doc/ref/PopText'\" unpacked with wrong size!
fi
# end of 'doc/ref/PopText'
fi
if test -f 'doc/ref/XpwCallMethod' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/ref/XpwCallMethod'\"
else
echo shar: Extracting \"'doc/ref/XpwCallMethod'\" \(1287 characters\)
sed "s/^X//" >'doc/ref/XpwCallMethod' <<'END_OF_FILE'
XHELP *XpwCallMethod Jonathan Meyer, Jan 1990
X
X
XPoplog Widget Set, revision 3.
X
XXpwCallMethod is a C procedure that takes a widget, a method ID, and
Xa variable number of arguments according to the method.
X
XIf the widget is a subclass of the PopCore widget class, XpwCallMethod
Xlooks for the specified method ID in a table held in the widgets class
Xstructure, and in the class structure of its superclasses.
X
XIf the method ID is found in the table, the associated method procedure
Xis extracted and called.
X
XFor more information on the methods available to Poplog Widgets, see
XHELP *XpwMethods. For more information on the methods calling technique
Xsee SYSDOC *PopWidgets.imp. HELP *PopWidgets gives an overview of the
XPoplog Widget Set.
X
XThe XpwCallMethod procedure is externally loaded into Pop-11. Because it
Xtakes a variable number of arguments, which can be of different types,
XLIB *EXTERNAL is NOT used. This means that, to use XpwCallMethod, you
Xmust specify two extra arguments, telling external_apply how many
Xarguments you are passing to C and whether the method returns a value or not.
XFor Example, the call:
X
X XpwCallMethod(w, XpwMDrawPoint, 10,10, 4, false)
X
XCalls the C XpwCallMethod procedure with 4 arguments, and does not return
Xa value.
END_OF_FILE
if test 1287 -ne `wc -c <'doc/ref/XpwCallMethod'`; then
echo shar: \"'doc/ref/XpwCallMethod'\" unpacked with wrong size!
fi
# end of 'doc/ref/XpwCallMethod'
fi
if test -f 'doc/ref/XpwMethods' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/ref/XpwMethods'\"
else
echo shar: Extracting \"'doc/ref/XpwMethods'\" \(3715 characters\)
sed "s/^X//" >'doc/ref/XpwMethods' <<'END_OF_FILE'
XREF *XpwMethods Jonathan Meyer, Jan 1990
X
XPoplog Widget Set, revision 3.
X
XThis file describes the methods available to Poplog Widgets. Methods are
Xlike procedures except that a specific widget class can have several
Xprocedures that get called when one method is invoked (methods are
Xsubclass-to-superclass chained, so each superclass of a widget can have
Xan interpretation for a method). Methods are invoked using XpwCallMethod.
XSee REF *XpwCallMethod for more information on calling methods, or
XSYSDOC *PopWidgets.imp for information about how methods are implemented.
X
X
XThe methods listed here are desribed in more detail in the relevant
XREF file.
X
X
XPopCore Methods (See REF *PopCore)
X
XMethod Name Arguments Notes
X========================================================================
XXpwMSetColor string either name or #rgb format
XXpwMFreeColor string
XXpwMSetFont string
XXpwMFreeFont string
XXpwMSetCursor shape shape in cursorfont.h
XXpwMFreeCursor shape eg. XC_crosshair
X
X
XPopPixmap Methods (See REF *PopPixmap)
X
XMethod Name Arguments Notes
X========================================================================
XXpwMDrawArc x,y,w,h,a1,a2
XXpwMDrawArcs arcs,narcs
XXpwMDrawLine x,y,w,h
XXpwMDrawPoint x,y
XXpwMDrawPoints pts,npts
XXpwMDrawRectangle x,y,w,h
XXpwMDrawRectangles recs,nrecs
XXpwMDrawSegments segs,nsegs
XXpwMFillArc x,y,w,h,a1,a2
XXpwMFillArcs arcs,narcs
XXpwMFillPolygon pts,npts,shape,mode
XXpwMFillRectangle x,y,w,h
XXpwMFillRectangles recs,nrecs
XXpwMDrawString x,y,str,len
XXpwMDrawImageString x,y,str,len
XXpwMPutImage image,sx,sy,ex,ey,w,h
XXpwMGetImage x,y,w,h,msk,format
XXpwMClearArea x,y,w,h
XXpwMClearWindow none
XXpwMDrawImage x,y,w,h,data
XXpwMCopyFrom src_widget,x,y,w,h,ex,ey
XXpwMCopyTo dst_widget,x,y,w,h,ex,ey
X
X
XPopGraphic Methods (See REF *PopGraphic)
X
XMethod Name Arguments Notes
X========================================================================
XXpwMAllocColorRange num,r1,g1,b1,r2,g2,b2
XXpwMAllocStoreColor r,g,b
XXpwMCreateColormap -
XXpwMFreeColormap -
X
X
XPopScrollText Methods (See REF *PopScrollText)
X
XMethod Name Arguments Notes
X========================================================================
XXpwMScroll col,row,cols,rows,x_dist,y_dist
XXpwMScrollScreenUp -
XXpwMScrollScreenDown -
XXpwMScrollScreenLeft -
XXpwMScrollScreenRight -
XXpwMScrollLines row, rows, dist
XXpwMScrollTail col, row, dist
XXpwMScrollTails col, row, rows, dist
XXpwMScrollTailLeft col, row
XXpwMScrollTailRight col, row
XXpwMInsertLineAtCursor -
XXpwMInsertCharAtCursor -
XXpwMDeleteLineAtCursor -
XXpwMDeleteCharAtCursor -
XXpwMClear col, row, cols, rows
XXpwMClearWindow -
XXpwMClearLine row
XXpwMClearLines row, rows
XXpwMClearTail col, row
XXpwMClearTails col, row, rows
XXpwMClearChar col, row
XXpwMClearLineAtCursor -
XXpwMClearTailAtCursor -
XXpwMClearCharAtCursor -
XXpwMInsert col, row, str, len
XXpwMInsertAtCursor str, len
XXpwMWrite col, row, index, lines, strs, off,len,clr
XXpwMWriteLine col, row, str, len, clr
XXpwMWriteLines col, row, index, lines, strs, len, clr
XXpwMWriteSubstr col, row, str, off, len, clr
XXpwMWriteAtCursor str, len
XXpwMCursorTo col,row
XXpwMCursorUp -
XXpwMCursorDown -
XXpwMCursorLeft -
XXpwMCursorRight -
XXpwMBell volume
END_OF_FILE
if test 3715 -ne `wc -c <'doc/ref/XpwMethods'`; then
echo shar: \"'doc/ref/XpwMethods'\" unpacked with wrong size!
fi
# end of 'doc/ref/XpwMethods'
fi
if test -f 'doc/ref/XpwResources' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/ref/XpwResources'\"
else
echo shar: Extracting \"'doc/ref/XpwResources'\" \(5311 characters\)
sed "s/^X//" >'doc/ref/XpwResources' <<'END_OF_FILE'
XREF *XpwResources Jonathan Meyer, Mar 1990
X
XPoplog Widget Set, revision 3.
X
XThis file provides an index to the resources used in the Poplog Widget Set.
XFor information about the Poplog Widget Set, see HELP *PopWidgets.
XResources can be set and examined using XtGetValues and XtSetValues,
Xor using LIB *XT_VALUE.
X
XCore and PopCore Resources (See REF *PopCore)
X
X===============================================================================
XName Class RepType Default* Description
X===============================================================================
XXtNwidth Width Dimension 200 Window width
XXtNheight Height Dimension 100 Window height
XXtNx X Position 0 X coordinate in pixels
XXtNy Y Position 0 Y coordinate in pixels
XXtNborderWidth BorderWidth Dimension 1 Border width in pixels
XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap
XXtNborderColor BorderColor Pixel foreground Window border color
XXtNbackground Background Pixel XtDefault Window background color
XXtNforeground Foreground Pixel XtDefault Window foreground color
XXtNfont Font FontStruct XtDefault Font for text operations
XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont)
XXtNtranslations Translations String Event-to-action translations
XXtNpopCallback Callback Pointer NULL Callbacks for events
XXtNautoFlush Boolean Boolean TRUE XFlush after methods?
XXtNusersGC GC Pointer NULL Graphics Context for ops
XXtNmodifiers Parameter Int None event->state modifiers
XXtNdestroyCallback Callback NULL XtDestroyWidget callback
XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget
X
X
XPopPixmap resources (See REF *PopPixmap)
X
X===============================================================================
XName Class RepType Default* Description
X===============================================================================
XXtNfunction Function Int XtDefault GC drawing mode
XXtNsubwindowMode SubWindowMode Int XtDefault GC subwindow mode
XXtNlineWidth LineWidth Int XtDefault GC line width
XXtNlineStyle LineStyle Int XtDefault GC line style
XXtNcapStyle CapStyle Int XtDefault GC cap style
XXtNjoinStyle JoinStyle Int XtDefault GC join style
XXtNprivateGC GC Pointer None Pixmap Graphics Context
XXtNpixmap Pixmap Pointer None Pixmap of Widget.
XXtNpixmapStatus PixmapStatus Cardinal PixmapOn Is Pixmap active?
X
X
XPopGraphic resources (See REF *PopGraphic)
X
X===============================================================================
XName Class RepType Default* Description
X===============================================================================
XXtNusePrivateGC Boolean Boolean TRUE See below
XXtNmyGC GC Pointer NULL GC for window refresh
XXtNswitchCmaps Boolean Boolean FALSE Automatic cmap install
XXtNmouseX MouseLocation Int None Mouse X location in pixels
XXtNmouseY MouseLocation Int None Mouse Y location in pixels
XXtNbuttonEvent Callback Pointer NULL Called on ButtonPress
XXtNkeyboardEvent Callback Pointer NULL Called on KeyPress
XXtNmouseEvent Callback Pointer NULL Called on Enter/Leave
XXtNmotionEvent Callback Pointer NULL Called on mouse Motion
XXrNresizeEvent Callback Pointer NULL Called on Resize Req
X
X
XPopScrollText resources (See REF *PopScrollText)
X
X========================================================================
XName Class RepType Default* Description
X========================================================================
XXtNtopMargin TopMargin Dimension 0 Distance to start of text
XXtNleftMargin LeftMargin Dimension 2 Distance to start of text
XXtNfontWidth Width Dimension None Width of current font
XXtNfontHeight Height Dimension None Height of current font
XXtNcursorRow Position Position 0 Cursors Y location
XXtNcursorColumn Position Position 0 Cursors X location
XXtNcursorStatus CursorStatus Boolean TRUE Cursor on/off
XXtNmouseX MouseLocation Int None Mouse column
XXtNmouseY MouseLocation Int None Mouse row
XXtNnumRows Dimension Dimension 24 Text columns
XXtNnumColumns Dimension Dimension 80 Text rows
XXtNexposedLines Parameter (int *) NULL Lines that need redrawing
XXtNkey Key String NULL Ascii string of KeyPress
XXtNkeyboardEvent Callback Callback NULL keyboard inputs callback
XXtNbuttonEvent Callback Callback NULL Mouse buttonpress events
XXtNmotionEvent Callback Callback NULL Mouse motion events
XXtNdestroyCallback Callback NULL XtDestroyWidget callback
END_OF_FILE
if test 5311 -ne `wc -c <'doc/ref/XpwResources'`; then
echo shar: \"'doc/ref/XpwResources'\" unpacked with wrong size!
fi
# end of 'doc/ref/XpwResources'
fi
if test -f 'doc/man/poplog.man' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/man/poplog.man'\"
else
echo shar: Extracting \"'doc/man/poplog.man'\" \(12604 characters\)
sed "s/^X//" >'doc/man/poplog.man' <<'END_OF_FILE'
X.TH POPLOG 1 "December 1989" "Poplog V13.66"
X
XPoplog \- a multi\-language interactive software development environment
X
X.SH SYNOPSIS
X.B pop11 [ \fI\+saved-image\fP ... ]
X[ \fI argument .\.\.\fP ]
X[ \fI :command\fP ]
X.LP
X.B ved [ \fIfilename\fP ]
X.LP
X.B prolog [ \fI\-|\+saved-image\fP ]
X.LP
X.B clisp [ \fI\-|\+saved-image\fP ]
X.LP
X.B pml [ \fI\-|\+saved-image\fP ]
X.LP
X.SH DESCRIPTION
X
X\fIPoplog\fP is an integrated, interactive, multi-language software
Xdevelopment environment. It provides incremental compilers for POP-11,
XPROLOG, COMMON LISP and ML. Features include a powerful extensible
Xmulti-window text editor (\fIVed\fP), over 1700 documentation files, the \fI
XPoplog Window Manager\fP (\fIPwm\fP), many demonstration and utility
Xlibraries including an object oriented extension to Pop-11 known as
X\fIFlavours\fP, compiler-building tools, and mechanisms for dynamically linking
XPASCAL, FORTRAN and C programs so that they can be called from \fIPoplog\fP.
XIt includes the source code for a large number of library packages, which are
Xusually \fIPop-11\fP programs that the user can read and modify.
X.LP
XAt the heart of \fIPoplog\fP is the \fIPoplog Virtual Machine\fP. The
X\fIPoplog\fP compilers translate program text and into a sequence of \fIPoplog
XVirtual Machine\fP (\fIVM\fP) instructions, that are in turn compiled into
Xreal machine code instructions. This system provides the programmer with a
Xsuitable environment for rapid-prototyping, whilst also ensuring efficient
Xcode execution. The provision of the \fIPoplog Virtual Machine\fP as a target
Xfor compilers simplifies porting of Poplog languages, and programs written
Xusing them, to new machines.
X
XPrograms written using AlphaPop on a Macintosh will run on implementations
Xof Poplog on
XWorkstations running UNIX, and DEC VAX machines running VMS. A list of
Xcurrently supported hardware bases is available (see below for address).
X.LP
XThe \fIPoplog Virtual Machine\fP provides support for a large variety of
Xdatatypes, including linked lists, arrays, strings, integers and floating
Xpoint numbers. Users can define new datatypes. \fIPoplog\fP variables and
Xconstants can either be dynamically or lexically scoped, and are weakly typed.
X\fIPoplog\fP provides a trace and debugging facilities. It also has a very
Xefficient storage manager, using a mark-and-sweep copying garbage collector,
Xwhich is automatically replaced by a non-copying algorithm when there is not
Xenough space for copying. \fIPop-11\fP processes start from under a megabyte
Xin size. Prolog, Lisp or ML require more, but all start in less than two
Xmegabytes. Poplog processes can grow to whatever size the machine and the
Xoperating system will allow.
X.LP
XThe core language of \fIPoplog\fP is \fIPop-11\fP. \fIPop-11\fP combines the
Xfeatures found in other AI languages like Lisp with a syntax that is similar
Xin form to Pascal or C. \fIPop-11\fP code is easy to read, and includes many
Xcontrol structures. For example, the following \fIPop-11\fP code prints the
Xword "hello" out five times:
X.sp
X.in +8
X.nf
Xrepeat 5 times
X "hello" => ;;; print hello out five times
Xendrepeat;
X.fi
X.in -8
X.LP
XBecause the syntax of \fIPop-11\fP is very readable, it is easy to learn, and
Xhas been found to be very effective as a teaching tool. However, \fIPop-11\fP
Xprogrammers can also make use of rich syntactic structures, and the large
Xnumbers of utilities, to write very complex and diverse packages. Since the
Xeditor, the compiler and the debugging tools are all part of the same
Xenvironment, programmers are saved from the laborious task of switching
Xbetween editors and compilers, waiting for error messages from the compilers,
Xand switching back to the editor again.
X.LP
X\fIPoplog\fP is far too complex to describe fully in a manual page entry. This
Xdocument serves only as a pointer to the large amount of on-line documentation
Xthat is available within the \fIPoplog\fP environment.
X.SH COMMANDS
X.LP
X.TP
X.I pop11
XLoads the default \fIPoplog\fP system, with only the \fIPop-11\fP compiler.
X.TP
X.I ved
XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler,
Xand then loads the \fIPoplog\fP editor, \fIVed\fP. This command can take one
Xargument (a filename) that is passed to \fIVed\fP as the name of the initial
Xfile to edit.
X.TP
X.I prolog, pop11 +prolog
XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler,
Xand then starts the \fIProlog\fP compiler (provided as a saved image).
X.TP
X.I clisp, pop11 +lisp
XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler,
Xand then starts the \fICommon Lisp\fP compiler (provided as a saved image).
X.TP
X.I pml, pop11 +pml
XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler,
Xand then starts the \fIML\fP compiler.
X.in -8
X.SH OPTIONS
X.LP
XFor more information on \fIPoplog\fP parameter passing, see the Poplog
Xhelp file HELP\ PARAMETERS, or the more detailed specification in
XREF \SYSTEM.
X.TP
X\fI+saved-image\fP ...
XLoads the \fIPoplog\fP environment and then looks for the specified
X\fIPoplog\fP saved image. \fIPoplog\fP will search the directories specified
Xin \fI$popsavepath\fP, and in the current directory. The suffix .psv is added
Xto the filename if no suffix is specified. Several incremental saved images
Xcan be loaded using the "+saved-image" form. Additional arguments specified
Xusing the "-" flag will be passed into the \fIPoplog\fP environment. By
Xdefault, such arguments are ignored, although the programmer may wish to
Xdefine interpretations for them. If this option is given the \fI:command\fP
Xoption must be omitted. For more information about saved images, see REF\
XSYSTEM.
X.TP
X.I :command
XLoads the \fIPoplog\fP environment, and then executes the \fIPop-11\fP
Xinstruction \fIcommand\fP.
X.TP
Xved \fIfilename\fP
XLoads the \fIPoplog\fP environment, sets up the editor (\fIVed\fP), and
Xreads \fIfilename\fP into a ved buffer, ready for editing.
X
X.SH POPLOG INITIALIZATION
X
X\fIPoplog\fP uses environent variables to store information about the location
Xof files, defaults and documentation. These variables are usually initialized
Xusing a shell script. For details see your local system administrator or the
X\fIPoplog Users' Guide\fP. The \fIGuide\fP also explains how to use
Xinitialization files, such as init.p, vedinit.p, init.pl, init.lsp, and
Xinit.ml. Default scripts reside in the pop/com directory of the \fIPoplog\fP
Xtree. These scripts are usually executed as part of the users \fI.login\fP
Xscript. A typical login script would contain the following:
X.LP
X.ti+8n
X\fBsetenv usepop /usr/local/pop13.66 (or whatever)\fP
X.ti+8n
X\fBsource $usepop/pop/com/poplog\fP
X.LP
X
X\fIPoplog\fP initialization often prints out a message giving the Poplog
Xversion, and adds the \fIPoplog\fP executables to the users PATH.
X.LP
XFor more information, contact your system administrator, or see the User Guide,
Xor the online information in POPLOG HELP\ INITIAL.
X.LP
X.SH ENVIRONMENT VARIABLES
X.TP
X.I $usepop
XHolds the path to the root of the \fIPoplog\fP directory tree.
X.TP
X.I $poplocal
XHolds the path to the root of the \fIPoplog\fP local tree. This is used to
Xstore site-specific libraries and documentation.
X.TP
X.I $popcom
XSet to \fI$usepop\fP/pop/com. This directory holds several csh(1) scripts for
Xmaking default saved images, and setting up the poplog environment.
X.TP
X.I $popsrc
XSet to \fI$usepop\fP/pop/src. This directory contains the sources for the
X\fIPoplog\fP environment, if provided. The sources may be in object file form.
X.TP
X.I $popsys
XSet to \fI$usepop\fP/pop/pop. Contains the \fIPoplog\fP executable commands,
Xincluding \fIpop11\fP, \fIprolog\fP, \fIpml\fP, \fIclisp\fP. Other commands
Xinclude:
X.sp
X.in +8
X.nf
X.ig
X\fIteach\fP evokes \fIVed\fP with the TEACH *TEACH file.
X\fIhelp\fP evokes \fIVed\fP with the HELP *TEACH file.
X..
X\fIpwmtool\fP runs the Suntools Poplog Window Manager.
X.ig
X\fIv55\fP loads \fIVed\fP with the Visual 55 terminal setup.
X\fIeliza\fP loads and runs the demo program Eliza.
X..
X.fi
X.in -8
X.TP
X.I $popautolib, $poplocalauto
XSet to $usepop/pop/lib/auto and $poplocal/local/auto respectively. The
Xcompiler searches these directories when it is trying to evaluate an undefined
Xidentifier. If a file is found with the same name as the identifier, it is
Xcompiled. This enables the Poplog environment to be invisibly extended, whilst
Xconserving memory usage.
X.TP
X.I $poplocalbin
XDirectory containing local saved images.
X.TP
X.I $popliblib, $popdatalib, $poppwmlib, $popsunlib, $popvedlib
XSet to directories containing library packages for Pop-11, Pwm, Sun consoles
Xand Ved.
X.TP
X.I $popsavelib
XSet to $usepop/pop/psv. This directory contains some standard saved images,
Xincluding the Prolog, Lisp and ML saved images.
X.TP
X.I $popsavepath
XLists of directories containing Poplog saved images. Users may add paths to
Xdirectories containing their own saved images. By default, this is set to
X$poplib:$poplocalbin:$popsavelib.
X.TP
X.I $poplib
XUser definable. Holds the path to the users library directory. \fIPoplog\fP
Xwill look in this directory for saved images and initialization files (see
Xbelow).
X.TP
X.I $pop_{name}
XWhen \fIPoplog\fP is executed, it checks the name of the command that it was
Xexecuted by (ie. argv[0]). If this command was not "pop11", \fIPoplog\fP looks
Xfor an environment variable starting with "pop_" and ending with argv[0]. If
Xsuch a variable exists, \fIPoplog\fP treats the contents of the variable as
Xthe arguments to \fIPoplog\fP. This is a convenient way of making new
Xcommands. To make a command myved, which loads pop11 with the saved image
Xcalled myved.psv, make a symbolic link between $popsys/pop11 and myved, and
Xset the environment variable pop_myved to "+myved":
X.sp
X.in +8
X.nf
Xln -s $popsys/pop11 myved
Xsetenv pop_myved +myved
X.fi
X.in -8
X.LP
X.SH FILES
X
X.TP
X.I $poplib/init.p
XAfter \fIPoplog\fP is loaded, the \fIPop-11\fP code in this file is compiled.
XUsers can use this file define useful procedures and variables to tailor the
X\fIPoplog\fP environment to their own tastes.
X.TP
X.I $poplib/vedinit.p
XThis \fIPop-11\fP file is compiled when the \fIVed\fP editor is evoked. Users
Xcan write programs to tailor the operation of \fIVed\fP, so that for example
Xit behaves sensibly when different terminals are being used. This file can
Xalso be used to define extra VED <ENTER> commands, or to modify the default
Xactions that \fIVed\fP takes when a new file is edited (see
XHELP\ VEDFILETYPES, HELP\ VEDVEDDEFAULTS).
X.TP
X.I $poplib/init.pl
XA file containing PROLOG code that is compiled when \fIPoplog\fP is loaded
Xwith the PROLOG compiler.
X.TP
X.I $poplib/init.lsp
XA file containing LISP code that is compiled when \fIPoplog\fP is loaded with
Xthe LISP compiler.
X.TP
X.I $poplib/init.ml
XA file containing ML code that is compiled when \fIPoplog\fP is loaded with
Xthe ML compiler.
X.LP
XAll of the above files are optional. If \fIPoplog\fP does not find them in the
X$poplib directory, it searches the current directory.
X
X.SH BUGS
X.LP
XThe \fIPoplog\fP help file HELP *NEWS provides the latest information on
Xproblems and changes in Poplog. Academic sites can mail Sussex University
X(address below) with their problems. Other sites should contact ISL. Some
Xsites may also have a bugreport mechanism, which automatically posts E-mail
Xproblems to Sussex University. See HELP *bugreport, or contact your System
XAdministrator.
X
X.LP
X.SH "SEE ALSO"
X
X
X.IB Poplog\ HELP\ files:
X.LP
XHELP *INITIAL, REF *SYSPEC, HELP *POPLOG, TEACH *TEACH, REF *SYSTEM
X.LP
XB. R. Barret, A. Ramsey and A. Sloman, \fI POP-11, A practical Language for
XArtificial Intelligence\fP, Ellis Horwood, 1986.
X.LP
X.SH FURTHER INFORMATION
X.LP
X\fIPoplog\fP is the property of the University of Sussex. For information
Xabout academic sales, contact:
X
X.sp
X.in +8
X.nf
XMs Alison Mudd
XSchool of Cognitive and Computing Sciences
XUniversity of Sussex
XBrighton
XSussex
XBN1 9QH
XPhone: (0273) 606755
XE-mail to alim at cogs.sussex.uk.ac
X.fi
X.in -8
X.LP
XFor Commercial and overseas sales information, contact:
X.sp
X.in +8
X.nf
XIntegral Solutions Limited
XUnit 3, Campbell Court
XBramley
XBasingstoke
XHampshire, RG26 5EG
XPhone: (0256) 88028 Fax: 0256-882182
XE-mail to isl at integ.uucp
X.fi
X.in -8
X.LP
XFor information about AlphaPop - a Pop-11 environment for the Macintosh,
Xcontact:
X.sp
X.in +8
X.nf
XCognitive Applications Ltd
X4 Sillwood Terrace
XBrighton
XBN1 2LR
XPhone (0273) 821600
X
X.fi
X.in -8
X
X.SH AUTHOR
XCopyright University of Sussex 1989. All rights reserved.
X.br
X Jonathan Meyer, December 15 1989.
X
X.ig
X--- C.unix/doc/man/poplog.1 --------------------------------------------
X--- Copyright University of Sussex 1987. All rights reserved. ----------
END_OF_FILE
if test 12604 -ne `wc -c <'doc/man/poplog.man'`; then
echo shar: \"'doc/man/poplog.man'\" unpacked with wrong size!
fi
# end of 'doc/man/poplog.man'
fi
if test -f 'doc/sysdoc/PopWidgets.imp' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/sysdoc/PopWidgets.imp'\"
else
echo shar: Extracting \"'doc/sysdoc/PopWidgets.imp'\" \(14708 characters\)
sed "s/^X//" >'doc/sysdoc/PopWidgets.imp' <<'END_OF_FILE'
XPoplog Widget Set Revision 3
X
X
X Jonathan Meyer, 14 Jan 1990
X
X
X SYSDOC *POPWIDGETS.IMP Implementation Notes
X
X
X 1. Introduction
X
X
X This document describes some of the implementation details of the
X Poplog Widget Set. Specifically, details regarding Poplog Methods and
X Graphic Context Issues are discussed. For further details about Widg-
X ets and the X Toolkit, refer to the X Toolkit Intrinsics. Details
X about individual widgets in the Poplog Widget Set are found in HELP
X *POPWIDGETS.
X
X
X 2. Methods
X
X
X The Poplog Widget Set implements a new calling technique for accessing
X procedures (called methods) that apply to widgets. Methods are class
X properties, and so different classes respond to different methods.
X Furthermore, superclass chaining is used, so that each widget class
X can respond to a specific method differently.
X
X For example, the PopGraphic widget class interperts the XpwMDrawLine
X method by drawing a line on the window of the widget. The PopPixmap
X widget class responds to the XpwMDrawLine method by drawing a line on
X the widgets Pixmap. Because the PopGraphic widget class is a subclass
X of PopPixmap, drawing a line on a Graphics widget also causes the line
X to be drawn on the Pixmap of the widget. This pixmap is used for
X refreshing the window of the Graphics widget.
X
X
X 2.1 Calling Methods
X
X
X Methods are accessed using the procedure XPwCallMethod, which takes
X a variable number of arguments depending on which method is called.
X The prototype for XpwMCallMethod is:
X
X XpwMethodRet XpwCallMethod(w, id, arg1, arg2, ... argn);
X Widget w;
X XpwMethodID id;
X XpwMethodArg arg1, arg2, ... argn;
X
X w
X Specifies the Poplog widget to apply the method to.
X
X id
X Specifies the Poplog identification number of the method.
X
X arg1, arg2 ... argn
X A list of the arguments to pass to the method.
X
X
X For example, one of the methods understood by graphics widgets is
X XpwMDrawLine, which takes four integer arguments and draws a line
X between them. To draw a line on a graphics widget between (1,1)
X and (100,100), use:
X
X (void) XpwMCallMethod(w, XpwMDrawLine, 1, 1, 100, 100);
X
X
X 2.1.2 Method Lookup
X
X
X PopCore and its descendants have four additional fields in their class
X structures:
X
X XpwMethodList methods; /* array of method structures */
X Cardinal num_methods; /* XtNumber(methods) */
X XpwApplyProc apply_proc; /* Procedure to apply a method */
X XpwAssocTable *methods_table; /* hashed table of methods
X created at class initialize by the
X PopCore class_part initialize. */
X
X Method ID's are in fact integer numbers. They are defined in the
X header file <XpwMethod.h>. They are used to look up XpwMethod
X structures in the hash table methods_table. The hashing technique used
X is similar to XAssocTables.
X
X The hashing table methods_table is constructed from the methods list
X using XpwCreateAssoc, XpwCopyAssoc and XpwMakeAssoc at class
X initialize, by the PopCore class_part initialize procedure. Methods
X are found in the hash table using XpwLookupAssoc procedure. The
X Create, Make and Lookup functions are identical to their XCreateAssoc,
X XMakeAssoc and XLookUpAssoc equivelants, except they use XtMalloc, and
X work with XpwMethodID's (not XID's), and so they do not have to worry
X about different displays with the same XID's. The XpwCopyAssoc
X function copies all of the entries of one association table into
X another, using XpwMakeAssoc for each entry of the source table to
X add it to the destination table.
X
X In most cases the class_initialize create more than one bucket per
X method, so the XpwLookupAssoc procedure is likely to find the method
X after one or two checks. This makes method lookup very rapid (much
X more so than actions or callbacks).
X
X
X 2.1.3 Method Interpretation
X
X
X XpwCallMethod works by looking first at the widgets class for a
X method with the right id. If the method is found, and there is an
X apply_proc for that class, the apply_proc is called with the method,
X the widget, and a pointer to arguments passed to XpwCallMethod. This
X process is then repeated for the superclasses of the widget class. The
X return value of the first apply_proc is returned as the result of the
X XpwCallMethod, since C can only have one return value.
X
X XpwCallMethod will have no effect when called with widgets which are
X not descendants of the PopCore widget, or widgets that do not have a
X methods table, an apply proc, or a method with the corresponding
X method ID.
X
X If a method has a special Cut flag set in its flags field, then the
X superclass chaining is stopped at that method.
X
X 2.1.4 Apply Procs
X
X
X Each XpwMethod structure currently contains:
X
X XpwMethodID id; /* ID of method (integer) */
X XpwMethodProc *proc; /* pointer to procedure of method */
X ShortCard num_args; /* number of parameters for proc */
X Cardinal flags; /* additional method info */
X caddr_t extenstion; /* for future use */
X
X Apply procs are of the form:
X
X XpwMethodRet ApplyProc(w, method, args)
X Widget w;
X XtPopMethod method;
X va_alist args;
X
X w
X Specifies the Poplog widget to apply the method to.
X
X method
X Pointer to the structure for the method being applied.
X
X args
X An argument list in the format described by varargs(3).
X
X The apply procedure extracts the arguments from args, examines the
X methods flags, adds any of its own arguments, and finally calls the
X method (usually using the convenience routine XpwMakeCall). The
X value returned by the method is passed back to the caller. Flags are
X used to determine any additional arguments are be needed to apply the
X method.
X
X For example,the XpwMDrawLine method requires a drawable and a graphics
X context and takes four arguments. The Method Proc for XpwMDrawLine is
X the Xlib line drawing function, XDrawLine. The Method structure for
X the XpwMDrawLine method is therefore:
X
X { XpwMDrawLine, XDrawLine, 4, RequiresDrawable | RequiresGC }
X
X 2.2 Inheritance
X
X Currently, two of the additional fields of the class structure for
X PopCore widgets can be inherited from the superclass. They are the
X apply_proc field, and the methods_table field. To inherit a
X superclass's methods, use the entry XtInheritMethods in the
X methods_table field. To inherit the superclass's apply procedure, use
X the entry XtInheritApplyProc in the apply_proc field. Additional
X methods to those of the superclass can be specified in the methods
X field. At class initialize, the methods from the superclass are first
X added to the hash table for the class, and then those of the class are
X added. Finally, the hash table is stored in the methods_table field.
X This allows a class to inherit most of the methods of the superclass,
X but override superclass methods or add its own methods as well. For
X example, the PopGraphic class inherits all of the PopPixmap methods,
X but adds a few of its own. Thus the class_part entry for the
X PopGraphic widget is as follows:
X
X {/* popcore_part */
X /* methods */ popGraphicMethods,
X /* num_methods */ XtNumber(popGraphicMethods),
X /* apply_proc */ GraphicApplyProc,
X /* methods_table */ XtInheritMethods,
X }
X
X The class part definition, in PopCoreP.h, defines the new class fields
X as:
X XpwMethodList methods; /* array of method structures */
X Cardinal num_methods; /* XtNumber(methods) */
X XpwApplyProc apply_proc; /* Procedure to apply a method */
X XpwAssocTable *methods_table; /* hashed table of methods
X
X
X 2.3 Notes
X
X Methods are useful for several reasons:
X
X o Interpretation of each method is left to the class.
X
X o Superclass chaining means that each superclass of a widget
X can act on a method.
X
X o Methods can easily be constructed from standard functions,
X making it very easy to add methods to widgets.
X
X This final reason was the main one for implementing methods: Rewriting
X every Xlib drawing and text function for the graphics widget so that
X the function would draw on both a pixmap and the window would have
X been tiresome and expensive. Additionally, it would have involved a
X large number of procedures, and hence larger object code size.
X
X The XtAssoc procedures are similarly useful. The X Toolkit has XtMal-
X loc and XtFree procedures like Xmalloc and Xfree. Why it doesn't have
X XtAssoc I don't know.
X
X 2.2.1 Naming conventions, and other issues.
X
X The Implementation of methods may change - it was designed in a hurry,
X and could probably be fine tuned. However, the method calling tech-
X nique is independant of the implementation, so this should not affect
X application programers.
X
X There is a naming problem regarding methods - each different method
X should be given a different number, and flags for the methods must
X also be defined. This is currently done in one header file so that the
X chances of overlap are reduced. Of course, it would not matter if two
X different methods for different classes had the same ID, unless a
X programmer went off and called a widget of one class with a method
X from another. This would have upredictable and undesired affects.
X Currently, method ID ranges have been assigned to different widgets
X (this could be applied on a larger scale, so whole trees get a number
X range to use, like network addressing):
X
X PopCore - 0-200
X PopPixmap - 200-400
X PopGraphic - 400-600
X PopScrollText - 600-800
X
X
X Similarly, flags that are used are defined in one file, so that dif-
X ferent widgets don't use the same bit to represent different flags.
X Some global flags should be defined:
X
X InheritApplyProc
X Use the apply proc for the superclass to apply the method.
X
X ForceReturnVal
X Make return value for this application of the method the
X return value of the method call.
X
X MethodError
X Call XtError to report an error message. The proc field
X could be used to point to a string to use in the error
X message. Or there could be a lookup table of method names to
X id's, or the name could be stored in the method record.
X
X Others?
X
X Other possible improvements include:
X
X o Full argument specification, so that parameters other than
X integers can be specified and returned.
X
X o More complex inheritance of methods. Ability to override or
X augment superclasses methods.
X
X 3. Graphics Contexts
X
X The PopPixmap widget uses the initialize_hook, get_values_hook and the
X set_values_hook entries of the class structure to initialize, get and
X set fields of the graphics context from resource entries and argument
X lists. These fields are called subparts, since they are not directly
X part of the widget structure, but are pointed to by one of the fields
X in the widget.
X
X The GC subpart of the widget is in fact the XGCValues entry of the
X usersGC field of the widget. Since widgets can share Graphics contex-
X ts, they can also share GCsubparts. Because of this, the hooks to
X initialize and set subpart values must write changes to a different
X XGCValues structure, and then compare this structure to the original.
X If there are changes, then UpdateGC is called. In more detail, the
X procedure works as follows:
X
X
X 3.1 InitSubpartValues, GetSubpartValues, SetSubpartValues
X
X
X The InitSubpartValues procedure uses a global XGCValues structure and
X valuemask. First it copies the values from the current GC of the
X widget into the global XGCValues structure (using GCsubpartCopy). Then
X It calles XtGetSubresources to fill in the slots of the XGCValues
X structure from the resource database. Finally, it examines the fields
X of the structure that are resources, compares them to the original
X XGValues for the widget, and sets the relevant fields of a valuemask
X (using GCsubpartMask) so that a subsequent call to UpdateGC will
X affect the slots that are specified in the resource database.
X
X SetSubpartValues works in a similar fashion, except that it calls
X XtSetSubvalues to set the slots in the global XGCValues structure.
X Then it calls UpdateGC with the correct valuemask (determined using
X GCsubpartMask).
X
X GetSubpartValues simply calls XtGetSubvalues with the GCsubpart of the
X widget.
X
X The SetValues procedures also use this Global XGCValues structure and
X valuemask. Because of this, changes to the users graphics context
X which involve parts of the widget structure (such as foreground co-
X lour) and parts of the subpart structure (such as GC function) only
X involve one UpdateGC call.
X
X
X 3.2 Updating Graphics Contexts
X
X
X UpdateGC(w, valuemask, values)
X Widget w;
X XtGCMask valuemask;
X XtGCValues *values;
X
X w
X Widget to modify
X
X valuemask, values
X As for XChangeGC or XCreateGC
X
X UpdateGC first looks to see if the Graphics Context of the widget is
X shared. Shared Graphics Contexts are read-only, and so should not be
X modified. If the widget is sharing a graphics context, then a new
X graphics context is created, with the current graphics contexts set-
X tings. Finally XChangeGC is called to modify the graphics context.
X
X
X 3.3 Notes
X
X
X The subpart setting system works well, but it would be useful to be
X able to use the same scheme to set and modify more than one graphics
X context (determined by class?). Additionally, different subclasses of
X the PopPixmap widget require different subparts of the graphics context
X (the PopScrollText widget doesn't need the GCLineWidth resource!).
X
END_OF_FILE
if test 14708 -ne `wc -c <'doc/sysdoc/PopWidgets.imp'`; then
echo shar: \"'doc/sysdoc/PopWidgets.imp'\" unpacked with wrong size!
fi
# end of 'doc/sysdoc/PopWidgets.imp'
fi
echo shar: End of archive 2 \(of 2\).
cp /dev/null ark2isdone
MISSING=""
for I in 1 2 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked both archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
dan
-----------------------------------------------------------
O'Reilly && Associates
argv at sun.com / argv at ora.com
632 Petaluma Ave, Sebastopol, CA 95472
800-338-NUTS, in CA: 800-533-NUTS, FAX 707-829-0104
Opinions expressed reflect those of the author only.
More information about the Comp.sources.x
mailing list