REF XpwScrollText Jonathan Meyer, Andreas Schoter Aug 1990
Revised John Gibson Oct 1995
COPYRIGHT University of Sussex 1995. All Rights Reserved.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< XPWSCROLLTEXT >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Xpw is the Poplog Widget Set. It contains a variety of object oriented
user interface components (called widgets) which are controlled through
the X Windows Toolkit (Xt). For an introduction to Xpw, see HELP * Xpw
This file describes the XpwScrollText widget, and the Pop-11
interface to XpwScrollText. It assumes a basic understanding of the Xt
toolkit. Concepts such as resources, actions, translations, etc. are all
introduced in the X Toolkit Intrinsics - C Language Interface manual.
See the section on associated documentation for a list of other
documents describing Xpw.
CONTENTS - (Use <ENTER> g to access required sections)
1 XpwScrollText Widget
1.1 Synopsis
2 Methods
2.1 XpwCore Methods
2.2 XpwScrollText Methods
3 Convenience Procedures
3.1 Scrolling
3.2 Clearing
3.3 Writing
3.4 Cursor/Miscellaneous
4 Resources
4.1 Summary of Core and XpwCore Resources
4.2 Summary of XpwScrollText Resources
4.3 XpwScrollText Resources in Detail
... Resources Not Actually Used by the Widget
4.4 Note on Exposure and Resize Events
5 Actions & Translations
5.1 Actions
5.2 Translations
6 C Programming Information
-----------------------
1 XpwScrollText Widget
-----------------------
Superclass: XpwCore
The XpwScrollText widget is a low level text widget. It provides the
programmer with the ability to write text on a window, and scroll it
about. The widget notifies the application of input events, converts
mouse locations into text rows/columns, and allows applications to
manipulate a text cursor.
The widget keeps a copy of the text that is displayed in the window, and
automatically refreshes itself. Characters in the window may be drawn in
upto 4 different fonts of the same width, and in upto 8 different
foreground/background colour pairs.
There are a variety of operations that can be performed on XpwScrollText
widgets. Most of the operations involve scrolling text, or writing text.
1.1 Synopsis
-------------
In C:
#include <Intrinsic.h>
#include <StringDefs.h>
#include <X11/Xpw/XpwScrollText.h>
widget = XtCreateWidget(name, xpwScrollTextWidgetClass...);
In Pop-11:
xpwScrollTextWidget -> widgetclass [constant]
A member of the Poplog Widget Set.
To make available both the Xpw library directory, and
xpwScrollTextWidget from it, requires either
uses Xpw, XpwScrollText;
or
uses Xpw, xpwScrollTextWidget;
The first loads all the method procedures in this file as well
as the widget itself, whereas the second just loads the widget
and * XpwCallMethod.
Then call either of
XtCreateWidget(name, xpwScrollTextWidget, ...) -> w;
fast_XtCreateWidget(name, xpwScrollTextWidget, ...) -> w;
to create an instance of the XpwScrollText widget.
----------
2 Methods
----------
For more information about Poplog Widget Methods, see REF * XpwMethods
The XpwScrollText widget responds to all of the XpwCore methods.
Additionally it responds to a set of methods that are used to manipulate
the text on the widget. The methods can be grouped as follows:
¤ Scrolling methods
¤ Clearing methods
¤ Writing methods
¤ Cursor/Misc methods
In the case of Scrolling, Clearing and Writing, there is one primitive
generic method for each action, and several convenience methods that
call the generic method with calculated arguments. The Cursor/Misc
methods include several methods that apply the generic
writing/clearing/scrolling methods at the current cursor location.
Note that row and columns are numbered from 0 upwards.
2.1 XpwCore Methods
--------------------
Method Name Arguments Notes
----------- --------- -----
XpwMSetColor string either name or #rgb format
XpwMFreeColor string
XpwMSetFont string font name
XpwMFreeFont string
XpwMSetCursor shape shape in cursorfont.h
XpwMFreeCursor shape
2.2 XpwScrollText Methods
--------------------------
Method Name Arguments
----------- ---------
(Scrolling) (Scrolling)
XpwMScroll col, row, ncols, nrows, cdis, rdis
XpwMScrollScreenUp -
XpwMScrollScreenDown -
XpwMScrollScreenLeft -
XpwMScrollScreenRight -
XpwMScrollLines row, nrows, rdis
XpwMScrollTail col, row, cdis
XpwMScrollTails col, row, nrows, cdis
XpwMScrollTailLeft col, row
XpwMScrollTailRight col, row
(Clearing)
XpwMClear col, row, ncols, nrows
XpwMClearScreen -
XpwMClearLine row
XpwMClearLines row, nrows
XpwMClearTail col, row
XpwMClearTails col, row, nrows
XpwMClearChar col, row
(Writing)
XpwMWrite col,row,soffs,nrows,strings,coffs,ncols,clear
XpwMWriteLine col, row, string, ncols, clear
XpwMWriteLines col, row, soffs, nrows, strings, ncols, clear
XpwMWriteSubstr col, row, string, coffs, ncols, clear
(Cursor/Misc)
XpwMCursorTo col,row
XpwMCursorUp -
XpwMCursorDown -
XpwMCursorLeft -
XpwMCursorRight -
XpwMInsertLineAtCursor -
XpwMInsertCharAtCursor -
XpwMDeleteLineAtCursor -
XpwMDeleteCharAtCursor -
XpwMClearLineAtCursor -
XpwMClearTailAtCursor -
XpwMClearCharAtCursor -
XpwMInsert col, row, string, ncols
XpwMInsertAtCursor string, ncols
XpwMWriteAtCursor string, ncols
XpwMGetCharAttributes -
XpwMSetCharAttributes attributes
XpwMGetTextCursor -
XpwMSetTextCursor cursor_char
XpwMBell volume
-------------------------
3 Convenience Procedures
-------------------------
3.1 Scrolling
--------------
XpwTextScroll(widget, col, row, ncols, nrows, cdis, rdis) [procedure]
Calls the XpwMScroll method for widget.
Scrolls the rectangular region starting at col, row, of width
ncols and height nrows, by distance cdis columns and rdis rows.
cdis and rdis can be positive or negative integers, where
positive means right for cdis and down for rdis, and negative
means left for cdis and up for rdis.
If ncols or nrows are zero, the number of columns/rows from
col/row onwards is used instead (i.e. NUM_COLS-col or
NUM_ROWS-row, where the whole window is NUM_COLS columns by
NUM_ROWS rows).
Here 'scroll' means sweep the specified rectangle of text
up/down and/or then left/right across the window, leaving blank
areas behind (and possibly losing text off the edges of the
window). It is then upto the application to write text in the
blank areas generated by the scroll.
XpwTextScrollScreenUp(widget) [procedure]
XpwTextScrollScreenDown(widget) [procedure]
XpwTextScrollScreenLeft(widget) [procedure]
XpwTextScrollScreenRight(widget) [procedure]
Calls XpwMScrollScreenUp/Down/Left/Right respectively.
Scrolls the window of the specified widget by one character cell
in the required direction. Same as
XpwTextScroll(widget, 0,0, 0,0, 0,-1)
XpwTextScroll(widget, 0,0, 0,0, 0,1)
XpwTextScroll(widget, 0,0, 0,0, -1,0)
XpwTextScroll(widget, 0,0, 0,0, 1,0)
respectively.
XpwTextScrollLines(widget, row, nrows, rdis) [procedure]
Calls the XpwMScrollLines method for widget.
Scroll the region of text starting at row of height nrows by
rdis rows, which can be positive or negative. If nrows is zero,
the number of rows from row onwards is used. Same as
XpwTextScroll(widget, 0,row, 0,nrows, 0,rdis)
XpwTextScrollTail(widget, col, row, cdis) [procedure]
Calls the XpwMScrollTail method for widget.
Moves all text from col on row by cdis columns, which can be
positive or negative. Same as
XpwTextScroll(widget, col,row, 0,1, cdis,0)
For example, to move a whole line left by one character, use:
XpwTextMoveTail(W, LINE, 0, -1);
XpwTextScrollTails(widget, col, row, nrows, cdis) [procedure]
Calls the XpwMScrollTails method for widget.
Moves all text from col on nrows lines starting at row by cdis
columns, which can be positive or negative. If nrows is zero,
the number of rows from ROWS onwards is used. Same as
XpwTextScroll(widget, col,row, 0,nrows, cdis,0)
E.g, To move all of the text in a window right by one character,
for XpwScrollText widget W, use:
XpwTextMoveTails(W, 0, 0, 0, 1);
XpwTextScrollTailLeft(widget, col, row) [procedure]
XpwTextScrollTailRight(widget, col, row) [procedure]
Calls the XpwMScrollTailLeft/Right methods for widget.
Insert or delete a character at col, row by scrolling the tail
of the line left or right by one character cell. Same as
XpwTextScroll(widget, col,row, 0,1, -1,0)
XpwTextScroll(widget, col,row, 0,1, 1,0)
respectively.
3.2 Clearing
-------------
XpwTextClear(widget, col, row, ncols, nrows) [procedure]
Calls the XpwMClear method for widget.
Clear the region starting at col, row, of width ncols columns
and height nrows rows. If ncols or nrows are zero, the number of
columns/rows from col/row onwards is used instead (i.e.
NUM_COLS-col or NUM_ROWS-row, where the whole window is NUM_COLS
columns by NUM_ROWS rows).
XpwTextClearScreen(widget) [procedure]
Calls the XpwMClearScreen method for widget.
Clear the whole window of the widget. Same as
XpwTextClear(widget, 0,0, 0,0)
XpwTextClearLine(widget, row) [procedure]
XpwTextClearLines(widget, row, nrows) [procedure]
Calls the XpwMClearLine(s) method for widget.
Clears the specified row of the widget. The second version
clears nrows lines starting at row, or all rows from row onwards
if nrows is zero. Same as
XpwTextClear(widget, 0,row, 0,1)
XpwTextClear(widget, 0,row, 0,nrows)
respectively.
XpwTextClearTail(widget, col, row) [procedure]
XpwTextClearTails(widget, col, row, nrows) [procedure]
Calls the XpwMClearTail(s) method for widget.
Clears all of the text to right of col on row (or nrows starting
at row in the second form). If nrows is zero, then all rows from
row onwards. Same as
XpwTextClear(widget, col,row, 0,1)
XpwTextClear(widget, col,row, 0,nrows)
respectively.
XpwTextClearChar(widget, col, row) [procedure]
Calls the XpwMClearChar method for widget.
Clear the character at (col, row) for widget. Same as
XpwTextClear(widget, col,row, 1,1)
3.3 Writing
------------
XpwTextWrite(widget, col, row, soffs, nrows, [procedure]
coffs, ncols, strings, clear)
Calls the XpwMTextWrite method for widget.
Paints a rectangle of characters from a vector of strings
strings onto the screen.
The rectangle is ncols columns by nrows rows, and is painted
starting at col, row on the window. Within the vector of
strings, characters are taken starting from the string at offset
soffs within the vector, and character offset coffs within each
string (note that both soffs and coffs are offsets not pop
subscripts, i.e. are based at 0 not 1). That is, the top
left-hand character is
subscrs(coffs+1, subscrv(soffs+1, strings))
If ncols is 0, it is replaced (for each string) by the number of
characters in that string from coffs onwards. In any case, only
as many characters as there are in each string from coffs
onwards will be drawn, upto a maximum of ncols (or the width of
the window from col onwards if that is less).
If the boolean argument clear is true, the tail of each row from
col onwards is cleared first.
XpwTextWriteLine(widget, col, row, string, clear) [procedure]
Calls the XpwMWriteLine method for widget.
Writes the string on the widget starting at the position
designated by col and row. If clear is true then the whole line
from col onwards is cleared first. Same as
XpwTextWrite(widget, col,row, 0, 1, 0, 0, {^string}, clear)
XpwTextWriteLines(widget, col, row, soffs, nrows, [procedure]
strings, clear)
Calls the XpwMWriteLines method for widget.
The same as XpwTextWriteLine, only this takes a vector of
strings strings and writes nrows strings starting from offset
soffs in the vector. Same as
XpwTextWrite(widget,col,row,soffs,nrows,0,0,strings,clear)
XpwTextWriteSubstr(widget, col, row, coffs, ncols, [procedure]
string, clear)
Calls the XpwMWriteSubstr method for widget.
Writes ncols characters of string starting at character offset
coffs at position col,row of the widget. If clear is true the
line from col is cleared first. If ncols is zero, it is replaced
by the number of characters in the string from coffs onwards.
Same as
XpwTextWrite(widget,col,row,0,1,coffs,ncols,{^string},clear)
3.4 Cursor/Miscellaneous
-------------------------
XpwTextCursorTo(widget, row, col) [procedure]
Calls the XpwMCursorTo method for widget.
Moves the text cursor for widget to (row, col).
XpwTextCursorUp(widget) [procedure]
XpwTextCursorDown(widget) [procedure]
XpwTextCursorLeft(widget) [procedure]
XpwTextCursorRight(widget) [procedure]
Calls the XpwMCursorUp/Down/Left/Right methods for widget
respectively.
Moves the cursor for the widget one character cell from its
current location in the specific direction. The cursor will not
move off the screen.
XpwTextInsertLineAtCursor(widget) [procedure]
Calls the XpwMInsertLineAtCursor method for widget.
Insert a blank line at the current cursor position by scrolling
the text currently on that line, and lines below it, down.
XpwTextInsertCharAtCursor(widget) [procedure]
Calls the XpwMInsertCharAtCursor method for widget.
Insert a space at the current cursor location by moving the tail
of the line right by one character cell.
XpwTextDeleteLineAtCursor(widget) [procedure]
Calls the XpwMDeleteLineAtCursor method for widget.
Remove a line at the cursor position by scrolling the text below
the line up one row.
XpwTextDeleteCharAtCursor(widget) [procedure]
Calls the XpwMDeleteCharAtCursor method for widget.
Delete the character under the current cursor's location by
scrolling the tail of the line left by one character.
XpwTextClearLineAtCursor(widget) [procedure]
Calls the XpwMClearLineAtCursor method for widget.
Clears the text on the current cursor row.
XpwTextClearTailAtCursor(widget) [procedure]
Calls the XpwMClearTailAtCursor method for widget.
Clears the text to from current cursor column to end of the line
on the current cursor row.
XpwTextClearCharAtCursor(widget) [procedure]
Calls the XpwMClearCharAtCursor method for widget.
Clears the character under the cursor.
XpwTextInsert(widget, row, col, string) [procedure]
Calls the XpwMInsert method for widget.
Inserts the string at row, col of widget. Text on that row and
column will be moved right to make room for the string. This is
a combination of XpwMScroll and XpwMWrite.
XpwTextInsertAtCursor(widget, string) [procedure]
Calls the XpwMInsertAtCursor method for widget.
This operates like XpwTextInsert, only using the current
location of the cursor as the ROW and COL of the insert. The
Cursor is moved to the end of the string.
XpwTextWriteAtCursor(widget, string) [procedure]
Calls the XpwMWriteAtCursor method for widget.
Writes the string to the specified widget at the current cursor
position. Moves the cursor to the end of the string.
XpwGetCharAttributes(widget) -> attributes [procedure]
Calls the XpwMGetCharAttributes method for widget.
Returns the state of XtNcolorNumber and the boolean
character-attribute resources XtNunderlineOn, XtNboldOn,
XtNaltFontOn, XtNblinkOn and XtNactiveOn as flag bits in the
integer attributes.
The corresponding flag bits are
¤ XpwFcolorNumber
¤ XpwFunderlineOn
¤ XpwFboldOn
¤ XpwFaltFontOn
¤ XpwFblinkOn
¤ XpwFactiveOn
defined in XpwScrollText.ph (which you will need to include to
use them).
For the boolean resources, a set bit equals true and an unset
bit equals false; for the colour, XpwFcolorNumber is a mask for
the 3-bit colour number, which starts at bit XpwFcolorShift.
Thus for example,
XpwGetCharAttributes(widget) -> attributes;
(attributes && XpwFcolorNumber) >> XpwFcolorShift -> color;
would extract the current XtNcolorNumber.
Note that all attributes are contained within 8 bits starting at
bit 16. Thus you can add attributes to an ordinary 8 (or 16)
-bit character value to represent a 24-bit
'character-with-attributes'.
XpwSetCharAttributes(widget, attributes) [procedure]
Calls the XpwMSetCharAttributes method for widget.
Sets XtNcolorNumber and the boolean character-attribute
resources XtNunderlineOn, XtNboldOn, XtNaltFontOn, XtNblinkOn
and XtNactiveOn from flag bits in the integer attributes (as
defined in XpwGetCharAttributes above).
For example, using
(5 << XpwFcolorShift) || XpwFaltFontOn
for attributes would set XtNcolorNumber to 5, XtNaltFontOn true,
and the other booleans false.
Note that the cursor is not displayed while XtNcolorNumber is
non-zero or any of the booleans are true, i.e. while attributes
is non-zero.
XpwGetTextCursor(widget) -> cursor_char [procedure]
Calls the XpwMGetTextCursor method for widget.
Returns the value of the XtNcursorChar resource if
XtNcursorStatus is true (i.e. if the cursor is on), or 0
otherwise.
XpwSetTextCursor(widget, cursor_char) [procedure]
Calls the XpwMSetTextCursor method for widget.
If cursor_char is 0, sets XtNcursorStatus false (i.e. sets the
cursor off); otherwise, sets XtNcursorStatus true (i.e. sets the
cursor on).
In addition, if cursor_char is nonzero and not equal to 1,
assigns cursor_char is to XtNcursorChar.
XpwTextBell(widget, volume) [procedure]
Calls the XpwMBell method for widget.
Calls XBell to make a beep of the specified volume (0-100).
------------
4 Resources
------------
XpwScrollText inherits all of the Core and XpwCore widget resources, and
adds some additional resources.
The following resources are retrieved from the argument list or the
resource database when XpwScrollText widgets are created.
4.1 Summary of Core and XpwCore Resources
------------------------------------------
See REF * XpwCore for information on the following resources:
Name Class Type Access
---- ----- ---- ------
XtNancestorSensitive XtCSensitive Boolean G*
XtNautoFlush XtCBoolean Boolean SGI
XtNautoGeometry XtCParameter String SGI
XtNbackground XtCBackground Pixel SGI
XtNbackgroundPixmap XtCPixmap Pixmap SGI
XtNborderColor XtCBorderColor Pixel SGI
XtNborderPixmap XtCPixmap Pixmap SGI
XtNborderWidth XtCBorderWidth short SGI
XtNdepth XtCdepth short SGI
XtNdestroyCallback XtCCallback XtCallbackList SI
XtNfont XtCFont XFontStruct SGI
XtNforeground XtCForeground Pixel SGI
XtNheight XtCHeight short SGI
XtNmappedWhenManaged XtCMappedWhenManaged Boolean SGI
XtNmodifiers XtCModifiers int G
XtNpointerShape XtCCursor Cursor SGI
XtNsensitive XtCSensitive Boolean GI*
XtNtileForeground XtCTileForeground Pixel GI
XtNtranslations XtCTranslations XtTranslations GI
XtNwidth XtCWidth short SGI
XtNx XtCPosition short SGI
XtNy XtCPosition short SGI
The Access Column is interpreted as follows:
S Value can be set by XtSetValues
G Value can be read by XtGetValues
I Value can be set at initialization
* Value set in other ways
4.2 Summary of XpwScrollText Resources
---------------------------------------
The following table is divided up for easier reading.
Name Class Type Access
---- ----- ---- ------
XtNactiveChange XtCCallback XtCallbackList SI
XtNactiveOn XtCParameter Boolean SGI
XtNaltFontOn XtCParameter Boolean SGI
XtNaltFont XtCAltFont XFontStruct SGI
XtNblinkOn XtCParameter Boolean SGI
XtNboldAltFont XtCBoldAltFont XFontStruct SGI
XtNboldFont XtCBoldFont XFontStruct SGI
XtNboldOn XtCParameter Boolean SGI
XtNbuttonEvent XtCCallback XtCallbackList SI
XtNcolorNumber XtCParameter Short SGI
XtNcolor2Background XtCParameter Pixel SGI
XtNcolor2Foreground XtCParameter Pixel SGI
XtNcolor3Background XtCParameter Pixel SGI
XtNcolor3Foreground XtCParameter Pixel SGI
XtNcolor4Background XtCParameter Pixel SGI
XtNcolor4Foreground XtCParameter Pixel SGI
XtNcolor5Background XtCParameter Pixel SGI
XtNcolor5Foreground XtCParameter Pixel SGI
XtNcolor6Background XtCParameter Pixel SGI
XtNcolor6Foreground XtCParameter Pixel SGI
XtNcolor7Background XtCParameter Pixel SGI
XtNcolor7Foreground XtCParameter Pixel SGI
...
Name Class Type Access
---- ----- ---- ------
XtNcolor0ABackground XtCParameter Pixel SGI
XtNcolor0AForeground XtCParameter Pixel SGI
XtNcolor1ABackground XtCParameter Pixel SGI
XtNcolor1AForeground XtCParameter Pixel SGI
XtNcolor2ABackground XtCParameter Pixel SGI
XtNcolor2AForeground XtCParameter Pixel SGI
XtNcolor3ABackground XtCParameter Pixel SGI
XtNcolor3AForeground XtCParameter Pixel SGI
XtNcolor4ABackground XtCParameter Pixel SGI
XtNcolor4AForeground XtCParameter Pixel SGI
XtNcolor5ABackground XtCParameter Pixel SGI
XtNcolor5AForeground XtCParameter Pixel SGI
XtNcolor6ABackground XtCParameter Pixel SGI
XtNcolor6AForeground XtCParameter Pixel SGI
XtNcolor7ABackground XtCParameter Pixel SGI
XtNcolor7AForeground XtCParameter Pixel SGI
XtNcursorChar XtCParameter Int SGI
XtNcursorColor XtCParameter Pixel SGI
XtNcursorColumn XtCPosition Position SGI
XtNcursorRow XtCPosition Position SGI
XtNcursorStatus XtCCursorStatus Boolean SGI
...
Name Class Type Access
---- ----- ---- ------
XtNdefaultColorMask XtCParameter Int SGI
XtNdrawGraphicChars XtCParameter Boolean SGI
XtNdrawShadowMask XtCParameter Int SGI
XtNfocusChange XtCCallback XtCallbackList SI
XtNfontHeight XtCHeight Dimension G
XtNfontWidth XtCWidth Dimension G
XtNgeometry XtCGeometry String GI
XtNhMargin XtCMargin Short SGI
XtNhighlightBackground XtCParameter Pixel SGI
XtNhighlightForeground XtCParameter Pixel SGI
XtNhighlightOn XtCParameter Boolean SGI
XtNkey XtCKey String G
XtNkeyboardEvent XtCCallback XtCallbackList SI
XtNmenubarBackground XtCBackground Pixel SGI
XtNmenubarForeground XtCForeground Pixel SGI
XtNmenubarOn XtCMenubarOn Boolean SGI
XtNmotionEvent XtCCallback XtCallbackList SI
XtNmouseColumn XtCPosition Int SG
XtNmouseRow XtCPosition Int SG
XtNmouseX XtCPosition Int SG
XtNmouseY XtCPosition Int SG
...
Name Class Type Access
---- ----- ---- ------
XtNnoBlink XtCParameter Boolean SGI
XtNnoGrayScale XtCParameter Boolean SGI
XtNnumColumns XtCDimension Dimension SGI
XtNnumRows XtCDimension Dimension SGI
XtNpointer2Shape XtCCursor Cursor SGI
XtNroundSize XtCRoundSize Boolean SGI
XtNscrollbarBackground XtCBackground Pixel SGI
XtNscrollbarForeground XtCForeground Pixel SGI
XtNscrollbarOn XtCScrollbarOn Boolean SGI
XtNselectionColorNum XtCParameter Short SGI
XtNstatusBackground XtCBackground Pixel SGI
XtNstatusForeground XtCForeground Pixel SGI
XtNstatusStyle XtCParameter Short SGI
XtNsynthetic XtCParameter Boolean G*
XtNunderlineOn XtCParameter Boolean SGI
XtNvMargin XtCMargin Short SGI
XtNvisible XtCVisible Boolean G*
XtNxpwCallback XtCCallback XtCallbackList SI
4.3 XpwScrollText Resources in Detail
--------------------------------------
XtNunderlineOn [resource]
XtNboldOn [resource]
XtNaltFontOn [resource]
XtNblinkOn [resource]
XtNactiveOn [resource]
All BOOL, default false.
These booleans together with XtNcolorNumber control the current
attributes of characters being drawn. When any of them are true,
the cursor is not displayed.
When XtNunderlineOn is true, text is drawn underlined.
When XtNboldOn is true, text is drawn in bold. This is done
either by using XtNboldFont (XtNboldAltFont for alt) if that is
non-NULL, or by overstriking otherwise (i.e. redrawing every
character a second time shifted one pixel to the right).
When XtNaltFontOn is true, text is drawn using XtNaltFont
instead of XtNfont. If XtNaltFont is NULL, text is drawn using
XtNfont but with underlining.
When XtNblinkOn is true, text is drawn blinking, i.e. flashing.
(Or rather, it blinks while XtNnoBlink is false.)
When XtNactiveOn is true, text is drawn with the 'active'
attribute. This attribute (a) causes XtNcolorNumber to select
colours 0A - 7A rather than 0 - 7, and (b) causes the
XtNactiveChange callback to be called when the mouse pointer
moves in or out of active text.
These booleans can also be got and set with XpwGetCharAttributes
and XpwSetCharAttributes.
XtNboldFont [resource]
XtNaltFont [resource]
XtNboldAltFont [resource]
All FONTSTRUCT, default empty (NULL).
These specify upto 3 optional fonts to use instead of XtNfont.
(These fonts may be any size, including proportional, but see
XtNfontWidth below.)
XtNboldFont is used when XtNboldOn is true. If NULL (or the same
as XtNfont), bolding of text is achieved by overstriking with
XtNfont.
XtNaltFont is used when XtNaltFontOn is true. If NULL (or the
same as XtNfont), text is drawn with XtNfont underlined.
XtNboldAltFont is used when both XtNaltFontOn and XtNboldOn are
true. If NULL (or the same as XtNaltFont), bolding is achieved
by overstriking with XtNaltFont. If both XtNboldAltFont and
XtNaltFont are NULL (or the same as XtNfont), then XtNfont is
used with underlining.
XtNstatusForeground [resource]
XtNstatusBackground [resource]
PIXEL, Default values:
XtNDefaultBackground (XtNstatusBackground)
XtNDefaultForeground (XtNstatusForeground).
The widget allows row 0 (the status line in XVed) to behave
specially -- see XtNstatusStyle below. In particular, it allows
different basic colours to be used for it; these resources
specify the background and foreground for that row.
XtNhighlightForeground [resource]
XtNhighlightBackground [resource]
XtNcolor2Foreground [resource]
XtNcolor2Background [resource]
XtNcolor3Foreground [resource]
XtNcolor3Background [resource]
XtNcolor4Foreground [resource]
XtNcolor4Background [resource]
XtNcolor5Foreground [resource]
XtNcolor5Background [resource]
XtNcolor6Foreground [resource]
XtNcolor6Background [resource]
XtNcolor7Foreground [resource]
XtNcolor7Background [resource]
XtNcolor0AForeground [resource]
XtNcolor0ABackground [resource]
XtNcolor1AForeground [resource]
XtNcolor1ABackground [resource]
XtNcolor2AForeground [resource]
XtNcolor2ABackground [resource]
XtNcolor3AForeground [resource]
XtNcolor3ABackground [resource]
XtNcolor4AForeground [resource]
XtNcolor4ABackground [resource]
XtNcolor5AForeground [resource]
XtNcolor5ABackground [resource]
XtNcolor6AForeground [resource]
XtNcolor6ABackground [resource]
XtNcolor7AForeground [resource]
XtNcolor7ABackground [resource]
PIXEL, Default values: empty (-1).
These specify upto 15 alternative colour pairs to use instead of
XtNforeground and XtNbackground when drawing text (or instead of
XtNstatusForeground and XtNstatusBackground when on row 0).
The current pair of colours to use is specified by
XtNcolorNumber, which ranges from 0 - 7, in combination with the
boolean attribute XtNactiveOn.
Colour 0 with XtNactiveOn false is XtNforeground/XtNbackground
for text on rows other than 0, and
XtNstatusForeground/XtNstatusBackground for text on row 0.
The 15 alternative colours are then 1 - 7 with XtNactiveOn false
(note that colour 1 is called XtNhighlightForeground /
XtNhighlightBackground for backward compatibility reasons), and
0A - 7A with XtNactiveOn true.
With any of these, either foreground or background may be
specified as -1 (empty). When empty, the colour used for a
particular colour number component is determined by
XtNdefaultColorMask (see below). The default value (2:10) of
XtNdefaultColorMask maps all unset colours except 1 to the
corresponding (row-dependent) colour 0 component, but reverses
the colour 0 background and foreground for an unset colour 1.
Note that for monochrome displays (StaticGray visuals), all
colours other than 0 and 1 are automatically defaulted via
XtNdefaultColorMask. (That is, the resources for colours 2 - 7
and 0A - 7A are not used.) This also happens for GrayScale
visuals if the XtNnoGrayScale resource is set true.
All these colours default to -1 (and thus by default just act as
colour 0, or that reversed for XtNhighlightForeground and
XtNhighlightBackground).
XtNcolorNumber [resource]
SHORT, default 0.
The current colour number for drawing text, selecting 0 - 7 when
XtNactiveOn is false, and 0A - 7A when XtNactiveOn is true.
Colour 0 with XtNactiveOn false is XtNforeground / XtNbackground
when not on row 0, and XtNstatusForeground / XtNstatusBackground
when on row 0.
With XtNactiveOn false, colour 1 selects XtNhighlightForeground
/ XtNhighlightBackground, and colours 2 - 7 select
XtNcolor2Foreground / XtNcolor2Background to XtNcolor7Foreground
/ XtNcolor7Background respectively.
With XtNactiveOn true, colours numbers 0 - 7 select
XtNcolor0AForeground / XtNcolor0ABackground to
XtNcolor7AForeground / XtNcolor7ABackground respectively.
XtNdefaultColorMask [resource]
INT, default 2:0000000000000010.
Bits 0 - 15 in this integer control whether empty colour
components are defaulted to the corresponding colour 0 or colour
1 component. Bits 0 - 7 refer to colour numbers 0 - 7 (with
XtNactiveOn false), and bits 8 - 15 to colour numbers 0A - 7A
(with XtNactiveOn true).
That is, if text is painted in colour number N, and the
foreground or background of N is not set (i.e. is -1), then the
colour 1 component is used in its place if bit N is set in
XtNdefaultColorMask, otherwise the (row-dependent) colour 0
component.
However, for monochrome displays (i.e. StaticGray visuals), all
colours >= 2 are automatically defaulted in this way. This
enables clients to have resources set for colours 2 - 7 and 0A -
7A, while at the same time ensuring that an appropriate default
of black/white or white/black is used on monochrome displays.
The same applies for GrayScale visuals when XtNnoGrayScale is
true.
Note that if a component of colour 1 (i.e.
XtNhighlightForeground or XtNhighlightBackground) is itself
unset, then colour components defaulting to 1 use the opposite
(row-dependent) colour 0 component, i.e. colour 0 inverted; this
applies to XtNhighlightForeground or XtNhighlightBackground
themselves when bit 1 is set in XtNdefaultColorMask.
The default value of XtNdefaultColorMask is 2:10 (i.e. has bit 1
only set), which maps any unset colours except 1 to the
corresponding (row-dependent) colour 0 component, but unset 1 to
to the inverse colour 0 component.
But (for example), setting XtNdefaultColorMask to
2:1010101010101010
would default all even-numbered colours to colour 0, but all
odd-numbered colours to colour 1. (This is the default used by
XVed, and makes all odd-numbered colours display as
inverse-video on a monochrome screen.)
XtNdrawShadowMask [resource]
INT, default 0.
Bits 0 - 15 in this integer allow characters in a particular
colour to be drawn with a 3-dimensional 'shadow' effect. As with
XtNdefaultColorMask, bits 0 - 7 refer to colour numbers 0 - 7
(XtNactiveOn false), and bits 8 - 15 to colour numbers 0A - 7A
(XtNactiveOn true).
If a bit is set for colour N, characters in that colour are
drawn shadowed; the colour used for the shadow is black on light
backgrounds, and a shade of white on dark backgrounds.
With monochrome displays (StaticGray visuals), or GrayScale
visuals with XtNnoGrayScale true, shadowing is replaced by
underlining.
XtNnoGrayScale [resource]
BOOL, Default false.
Setting this resource true will cause displays with GrayScale
visuals to be treated like StaticGray, i.e. all colours >= 2 are
automatically defaulted via XtNdefaultColorMask.
XtNhighlightOn [resource]
BOOL, Default false.
This resource is retained for backward compatibility with
previous versions of the widget; previously it selected colour 1
(XtNhighlightForeground/XtNhighlightBackground) as the drawing
colour.
It now reflects the state of the least significant bit of
XtNcolorNumber, i.e. setting it from false -> true will set that
bit (making the colour number odd), whereas changing it from
true -> false will clear the bit (making the colour number
even). On the other hand, any change to XtNcolorNumber sets
XtNhighlightOn appropriately for the new state of the bit.
XtNbuttonEvent [resource]
CALLBACKLIST, default empty (NULL).
Called by the "notify-button-event" action in response to button
events. The call data argument passed to the XtNbuttonEvent
callback is an integer containing 3 fields, viz:
(clicks << 16) || (mode << 8) || button
where button is the button number, mode is either 0, 1, or 2 to
indicate RELEASE, PRESS or HOLD respectively, and clicks is the
number of clicks that were made. See the description of
"notify-button-event" under Actions below.
XtNcursorColumn [resource]
XtNcursorRow [resource]
INT, defaults 0, 0.
An inverse rectangle is used to represent the text cursor.
Changing these resources will cause the cursor to be unplotted
and moved to the new location. Any of the methods that can be
applied to the XpwScrollText widget are aware of the cursor, and
will replot it if necessary. The text cursor is filled (i.e.
highlighted) whenever the widget has input focus, and drawn in
outline only when it does not.
XtNcursorChar [resource]
INT, Default ASCII `O`.
This resource is a 24-bit character-with-attributes defining the
text cursor displayed when XtNcursorStatus is true, i.e.
23 16 15 8 7 0
+-------------------------------------------------+
| Attributes | 0 | Character Code |
+----------------+---------------+----------------+
The character attributes are as described under
XpwGetCharAttributes above (and defined in
INCLUDE * XpwScrollText).
The cursor is drawn in the foreground of XpwFcolorNumber (as for
XtNcolorNumber). If XpwFblinkOn is set, the cursor will blink
while the window has keyboard input focus.
The actual character code defines the cursor shape, in
combination with the XpwFboldOn attribute; this attribute is,
however, added automatically when the window has input focus.
Thus specifying a character without XpwFboldOn will give the
bold version when the window has input focus, and the dimmed
version otherwise:
ASCII Char Description
---------- -----------
`O` Rectangle occupying the whole character cell
-- filled in bold (with any underlying
character drawn in the background of
XpwFcolorNumber), or just in outline when
dimmed.
`I` I-beam occupying whole character cell.
`^` Triangular block or outline occupying the
bottom part of the character cell.
`_` Flat rectangular block or outline (like a
thick underscore) underneath the font
baseline.
` ` A space character gives an invisible cursor.
(The XpwFaltFontOn, XpwFunderlineOn and XpwFactiveOn attributes
currently have no effect on the cursor.)
XtNcursorColor [resource]
PIXEL, Default value empty (-1).
This resource specifies the colour 0 foreground for the text
cursor, i.e. is used when the XpwFcolorNumber field of
XtNcursorChar is 0. (If XpwFcolorNumber has a value of 1 - 7,
the foreground of that colour is used.)
If -1, it defaults to the foreground of ordinary colour 0, i.e.
XtNstatusForeground when on row 0, and XtNforeground when not.
XtNcursorStatus [resource]
BOOL, Default true.
If this resource is false, the text cursor is not displayed in
the widget window. By default the cursor is displayed (unless
XtNcolorNumber is non-zero, or any of XtNunderlineOn, XtNboldOn,
XtNaltFontOn, XtNblinkOn or XtNactiveOn are true).
XtNdrawGraphicChars [resource]
BOOL, Default false.
When true, character codes in the range 1 - 16:1F are
interpreted as VT100-style graphics characters and drawn as such
(in the appropriate size for the character cell). That is, the
encodings 1 - 16:1F correspond to the characters given by codes
16:60 - 16:7E (` to ~) when sent to a VT100 in graphics mode.
However, currently only the 15 line-drawing characters (VT100
codes 16:6A - 16:78) and a few others are actually supported
(other values are drawn using the fonts, i.e. as if
XtNdrawGraphicChars were false). The supported characters with
their widget codes are:
16:01 diamond
16:07 degree sign
16:0B bottom-right corner
16:0C top-right corner
16:0D top-left corner
16:0E bottom-left corner
16:0F cross
16:10 horizontal line 1
16:11 horizontal line 2
16:12 horizontal line 3 (middle)
16:13 horizontal line 4
16:14 horizontal line 5
16:15 tee left
16:16 tee right
16:17 tee down
16:18 tee up
16:19 vertical line
16:1F centred dot
XtNfocusChange [resource]
CALLBACKLIST, default empty (NULL).
This callback is called by the widget whenever it gains or loses
keyboard input focus: the call data argument is 1 when gaining
the focus, and 0 when losing it.
XtNactiveChange [resource]
CALLBACKLIST, default empty (NULL).
This callback is called whenever there are no mouse buttons
pressed and the mouse pointer enters or leaves an 'active
segment' of text, that is, a contiguous sequence of characters
on a line all having the 'active' attribute (see XtNactiveOn
above).
When the pointer enters an active segment, XtNactiveChange is
called, with a call data argument which is a pointer to an
"int". The client procedure may then set any combination of the
following bits in the integer to control whether and how the
active segment is highlighted, and whether a corresponding leave
callback is performed:
Bit Meaning
--- -------
0 Do leave callback: if this bit is set, a
corresponding XtNactiveChange callback will be
performed when the mouse leaves the active segment,
with a NULL pointer for the call data argument. (The
segment and/or pointer is restored to its normal
state before making the leave callback.)
1 Invert: redraw the segment with foreground and
background colours swapped.
2 Box: draw a box around the segment.
3 Change pointer: change the mouse pointer to
XtNpointer2Shape (as opposed to the default
XtNpointerShape).
For both enter and leave callbacks, XtNmouseColumn and
XtNmouseRow are set to the position of the active character the
pointer is (or was) on.
XtNfontWidth [resource]
XtNfontHeight [resource]
INT, No default value.
XtNfontWidth and XtNfontHeight are the dimensions of each
character cell in pixels; they are set by the widget whenever
fonts are initialised or changed.
XtNfontWidth is set to the maximum width of any character in any
of the fonts being used (i.e. XtNfont, XtNboldFont, XtNaltFont
XtNboldAltFont), and (regardless of their size, or whether
fixed-width or proportional), all fonts are drawn one character
per cell.
(However, note that drawing a fixed-width font at its normal
width is more efficient than anything else. You are therefore
recommended to have (at least) the main XtNfont be fixed-width,
greater than or equal in width to any of the others, so that
XtNfontWidth = width(XtNfont).)
XtNfontHeight is the actual row height of the widget, and is set
to
(max ascent of all fonts) + (max descent of all fonts)
with text being drawn at offset (max ascent) down from the top
of each row.
XtNhMargin [resource]
XtNvMargin [resource]
SHORT, Default values
XtNhMargin: -50
XtNvMargin: -30
Specifies the horizontal and vertical margins, i.e. the distance
in pixels from the left and top of window to where the text
starts.
A negative value for either of these means use that percentage
of the corresponding character cell dimension, i.e of
XtNfontWidth or XtNfontHeight. Thus the default values give 50%
of fontWidth as the horizontal margin, and 30% of fontHeight as
the vertical.
XtNkeyboardEvent [resource]
CALLBACKLIST, default empty (NULL).
This callback is called both by the "string" and
"notify-key_event" actions (see 'Actions' below); the
XtNsynthetic resource can be used to distinguish between them
(true for "string" and false for "notify-key_event").
For "notify-key_event" the call data argument is the keysym of
the event key, negated for a key release (and positive for a
press). For "string", the call data argument is unused.
In both cases, the XtNkey resource contains the string
pertaining to the event, i.e. the argument given to the "string"
action, or the ASCII key translation from XLookupString.
XtNkey [resource]
STRING, default NULL.
Set to the relevant string whenever the XtNkeyboardEvent
callback is called. For a "string" action it is the argument
given to that action. For a key event it is the translation for
the key returned by XLookupString (which in most cases will just
be a 1-character string containing the ASCII code for the key).
XtNmodifiers [resource]
INT, no default.
This is set to the event state field (i.e. button and modifier
mask bits) before making any of the XtNkeyboardEvent,
XtNbuttonEvent and XtNmotionEvent callbacks.
XtNmotionEvent [resource]
CALLBACKLIST, default empty (NULL).
Called by the "notify-motion-event" action in response to mouse
movement while a button is pressed. See the description of
"notify-motion-event" under Actions below.
XtNmouseColumn [resource]
XtNmouseRow [resource]
XtNmouseX [resource]
XtNmouseY [resource]
INT, defaults 0.
These contain the current position of the mouse pointer, and are
set before making any of the XtNkeyboardEvent, XtNbuttonEvent
and XtNmotionEvent callbacks.
Column and Row give the character cell within which the mouse is
located, whereas X and Y give its position in pixels.
XtNnoBlink [resource]
BOOL, Default false.
Controls whether text drawn with XtNblinkOn actually blinks or
not; setting this false stops the text blinking, and resetting
it to true starts blinking again.
XtNnumRows [resource]
XtNnumColumns [resource]
Both INT, default value 0.
These are based upon the current character cell and window
sizes. They are calculated from XtNfontWidth and XtNfontHeight,
as well as the width and height of the window. They are the
number of text rows and columns that can be fitted into the
window (row 0, column 0 is the top left corner of the window).
If these resources are specified during initialisation, they are
used in preference to XtNwidth and XtNheight (or XtNgeometry).
If no values are specified for any of XtNnumRows, XtNnumColumns,
XtNwidth, XtNheight or XtNgeometry, then XtNnumRows defaults to
24, and XtNnumColumns to 80.
Modifying these resources will cause the widget to resize.
XtNgeometry [resource]
STRING, default NULL.
Specifies the initial geometry for the widget window, in the
usual X format
numColumnsxnumRows+x+y
etc. If either numColumns or numRows is specified in this way,
it will override any initial value for XtNwidth or XtNheight,
but not explicit values for XtNnumColumns or XtNnumRows (which
take precedence).
An x, y position specified in the resource is not used directly
by the widget (but, for example, XVed extracts and makes use of
it after widget creation).
XtNroundSize [resource]
BOOL, default true.
Whenever the widget is resized, it will by default attempt to
round up its XtNwidth (XtNheight) to maintain the overall width
(height) of the window as an exact number of columns (rows) plus
XtNhMargin*2 (XtNvMargin*2).
Setting this resource false stops it from doing so, i.e. it just
fits as many columns (rows) into the width (height) given, and
adjusts the actual margins used to take up any slack.
XtNpointer2Shape [resource]
CURSOR, default "hand2".
An alternate pointer shape useable by the XtNactiveChange
callback to indicate that the pointer is in an active segment of
text.
XtNstatusStyle [resource]
SHORT, default 0.
Being the status line in XVed, the widget allows for special
treatment of row 0:
First, it allows different basic (colour 0) colours for row 0,
i.e. XtNstatusForeground and XtNstatusBackground. (The use of
these for row 0 should be dependent on XtNstatusStyle, but for
historical reasons is not.)
Second, with XtNstatusStyle nonzero, it allows row 0 to be drawn
with a surrounding border, either
¤ at the top of the window, separated by XtNvMargin from row
1, or
¤ at the bottom of the window, separated by XtNvMargin from
the last row (i.e. from row (XtNnumRows-1) ).
These two behaviours are selected by XtNstatusStyle values of 1
and 2 respectively. In either case, a 2-pixel border is added
around row 0, with the inner border pixel in XtNstatusBackground
and the outer in XtNborderColor. The outer border is then
separated from the top or bottom edge of the window by an
additional max(2,XtNvMargin-4) pixels.
When XtNstatusStyle is 0, row 0 is just drawn above and
contiguous with row 1 in the normal way.
XtNsynthetic [resource]
BOOL, no default value.
This resource is set before making an XtNkeyboardEvent callback,
so that "string" actions (true) can be distinguished from
"notify-key-event" actions (false).
XtNvisible [resource]
BOOL, no default value.
Set true whenever the widget window is completely visible, and
false when it is (even partially) obscured.
XtNxpwCallback [resource]
CALLBACKLIST, default empty (NULL).
Called by the widget whenever the text area is resized, i.e.
whenever numRows or numColumns changes. See Note on Exposure and
Resize Events below.
... Resources Not Actually Used by the Widget
----------------------------------------------
XtNautoGeometry [resource]
STRING, default NULL.
This resource is not used by the widget. (XVed uses it to
specify automatic sizing for windows.)
XtNmenubarBackground [resource]
XtNmenubarForeground [resource]
PIXEL, default values:
XtNDefaultBackground
XtNDefaultForeground
These resources are not used by the widget. (XVed uses them for
the background and foreground colours of menubars.)
XtNmenubarOn [resource]
BOOL, Default true.
This resource is not used by the widget. (XVed uses it to
control whether menubars are displayed or not.)
XtNscrollbarBackground [resource]
XtNscrollbarForeground [resource]
PIXEL, default values:
XtNDefaultBackground
XtNDefaultForeground
These resources are not used by the widget. (XVed uses them for
the background and foreground colours of scrollbars.)
XtNscrollbarOn [resource]
BOOL, Default true.
This resource is not used by the widget. (XVed uses it to
control whether scrollbars are displayed or not.)
XtNselectionColorNum [resource]
This resource is not used by the widget. (XVed uses it to
control which colour is used for selections.)
4.4 Note on Exposure and Resize Events
---------------------------------------
Exposure events are dealt with automatically by the widget. However,
whenever numRows or numColumns change, the XtNxpwCallback callback is
called, and this is expected to set the new contents of the window.
Note that this does not necessarily happen for any window size change,
only when numRows or numColumns actually changes. Thus for example,
changing fonts or margins may cause the window to resize, but
XtNxpwCallback is not called unless this necessitates changing the
number of rows or columns.
In general, when any resources such fonts or margins are changed, the
widget will attempt to resize to maintain the same number of rows and
columns; if this fails, the rows and columns will be adjusted to
accomodate the new conditions with the existing size.
-------------------------
5 Actions & Translations
-------------------------
5.1 Actions
------------
The XpwScrollText widget has some generic actions that are each designed
to handle a specific event. The actions all perform some decoding of the
event (extracting information such as mouse coordinates etc), and then
call an associated callback list, usually with a useful piece of
call_data or information set in widget resource fields. The following
table shows the actions defined in XpwScrollText:
Action Name X Event Callback
----------- ------- --------
string Any XtNkeyboardEvent
notify-key-event Key press XtNkeyboardEvent
notify-button-event ButtonPress/Release XtNbuttonEvent
notify-motion-event Mouse Motion XtNmotionEvent
bell Any -
string(string) [action]
string(char)
ACTION, resulting from some (usually keyboard) event
translation, calls XtNkeyboardEvent callback list (with
XtNsynthetic set true).
This action is called with an ASCII string as argument, e.g.
string("abcd")
or with a hexadecimal specification for a single character, e.g.
string(0x1b)
In the first case, it sets the XtNkey resource to the given
string; in the second it sets it to a string containing the
given character. string may also contain \X to indicate Ctrl-X
(e.g. \[ = ESCAPE).
The XtNkeyboardEvent callback is then called with the
XtNsynthetic resource set true (to distinguish it from
notify-key-event). The call data argument is unused.
notify-key-event() [action]
ACTION, handle X KeyPress event, calls XtNkeyboardEvent callback
list (with XtNsynthetic set false).
This action is activated when a keyboard key is pressed or
released within an XpwScrollText widget.
It first sets XtNmodifiers, XtNmouseX, XtNmouseY, XtNmouseColumn
and XtNmouseRow according to the event. It then translates the
keycode into a keysym, and sets the XtNkey resource to reflect
the ASCII translation for that key (got from XlookupString).
The XtNkeyboardEvent callback is then called with the
XtNsynthetic resource set false (to distinguish it from
"string"); if the event is a KeyRelease, the call data is the
negated KeySym of the key, otherwise the (positive) keysym is
used as call data.
notify-button-event() [action]
ACTION, handle X ButtonPress event, calls XtNbuttonEvent
callback list.
This action is activated when a mouse button is pressed or
released within an XpwScrollText widget. Rather than just
calling back for each press or release, it automatically filters
button 'clicks', that is, presses and releases of a button
within MultiClickTime, as well as button 'hold', i.e. holding a
button down (for at least twice MultiClickTime).
The call data argument passed to the XtNbuttonEvent callback is
an integer containing 3 fields, viz:
(clicks << 16) || (mode << 8) || button
where button is the button number, mode is either 0, 1, or 2 to
indicate RELEASE, PRESS or HOLD respectively, and clicks is the
number of clicks that were made.
The sequence of callbacks in a 'dialog' for a given button is
shown below:
PRESS
|
+-------+--------+
| |
N-click PRESS N-click RELEASE
|
+---|
| HOLD
+---|
|
RELEASE
First, an initial button press event produces a callback with
mode PRESS and clicks = 0.
A timer is then set going, and subsequent releases, re-presses
and releases all within MultiClickTime of the previous event are
counted as clicks. A release with no following press within
MultiClickTime generates a callback with mode RELEASE for
however many clicks there were.
If at any stage a press has no following release within
MultiClickTime, then a callback is generated with mode PRESS and
however many clicks preceded it. If the press still has no
release after twice MultiClickTime, another callback with mode
HOLD (and 0 clicks) results. Finally, when the release comes, a
RELEASE callback with 0 clicks is made.
A button press for any other button terminates the dialog for
the current button. XtNmodifiers, XtNmouseX, XtNmouseY,
XtNmouseColumn and XtNmouseRow are set accordinging before
making any callbacks.
notify-motion-event() [action]
ACTION, handle X MotionNotify event, may call XtNactiveChange or
XtNmotionEvent callback list.
This action is activated when the mouse is moved within an
XpwScrollText widget.
If no buttons are pressed, an XtNactiveChange callback may be
generated if the pointer has entered or left a segment of active
text (see XtNactiveChange above). Otherwise, no action results.
If buttons are pressed, it generates an XtNmotionEvent callback,
except while "notify-button-event" is waiting for a 'click',
i.e. less than MultiClickTime has elapsed since the button was
pressed. (If however, notify-button-event is waiting for a
'hold' and the movement changes the current row or column, then
the hold wait is aborted and the motion callback is generated.)
Before callback, the XtNmodifiers, XtNmouseX, XtNmouseY,
XtNmouseColumn and XtNmouseRow resources are set accordingly.
The call data to a callback is the same value as for
XtNmodifiers, i.e. the event button/modifier state.
bell() [action]
ACTION, called in an event translation.
Rings the bell (by calling XBell).
5.2 Translations
-----------------
The default translations for XpwScrollText widgets simply map X events
into the actions described above, using the following translation table:
"<BtnDown>: notify-button-event() \n\
<BtnUp>: notify-button-event() \n\
<Motion>: notify-motion-event() \n\
<KeyPress>: notify-key-event() \n\
<KeyRelease>: notify-key-event()";
Other X events such as EnterNotify and LeaveNotify are dealt with by
internal event handlers.
----------------------------
6 C Programming Information
----------------------------
Xpw follows all of the Xt conventions, and so should be straightforward
to use in C, and in other languages. Widget creation, and resource
setting etc, all follow the Xt norms. The one addition to Xt is the use
of methods instead of a collection of global C procedures to perform
widget-class specific operations on a widget. See REF * XpwCallMethod
for a description of the calling syntax for methods, and a C-style
synopsis of all of the methods available in Xpw.
+-+ C.x/x/pop/ref/XpwScrollText
+-+ Copyright University of Sussex 1995. All rights reserved.