(3)

NAME
LinkText

DESCRIPTION
The LinkText widget is used to display text in multiple fonts and colors and to provide hyperlinks. For correct operation, it should be used only as a child of the accompanying LinkView widget, which provides a scrolling viewport. This widget also requires the dynamically growable buffer routines in the file buffer.c.

  Public variables
LinkText
Name | Class | Type | Default
XtNhypertext | XtCHypertext | String | NULL
XtNactivate | XtCActivate | Callback | NULL
XtNnewpage | XtCNewpage | Callback | NULL
XtNinternalOffset | XtCInternalOffset | Dimension | 4
XtNfont1 | XtCFont1 | FontStruct | XtDefaultFont
XtNfont2 | XtCFont2 | FontStruct | XtDefaultFont
XtNfont3 | XtCFont3 | FontStruct | XtDefaultFont
XtNfont4 | XtCFont4 | FontStruct | XtDefaultFont
XtNfont5 | XtCFont5 | FontStruct | XtDefaultFont
XtNcolor1 | XtCColor1 | Pixel | XtDefaultForeground
XtNcolor2 | XtCColor2 | Pixel | XtDefaultForeground
XtNcolor3 | XtCColor3 | Pixel | XtDefaultForeground
XtNcolor4 | XtCColor4 | Pixel | XtDefaultForeground
XtNcolor5 | XtCColor5 | Pixel | XtDefaultForeground
XtNcolor6 | XtCColor6 | Pixel | XtDefaultForeground
XtNcolor7 | XtCColor7 | Pixel | XtDefaultForeground
XtNcolor8 | XtCColor8 | Pixel | XtDefaultForeground
XtNlinkColor | XtCLinkColor | Pixel | "mediumblue"
XtNselectForeground | XtCSelectForeground | Pixel | XtDefaultBackground
XtNselectBackground | XtCSelectBackground | Pixel | XtDefaultForeground
XtNunderlineLinks | XtCUnderlineLinks | Boolean | True
XtNnormalCursor | XtCNormalCursor | Cursor | "top_left_arrow"
XtNlinkCursor | XtCLinkCursor | Cursor | "hand2"
XtNbusyCursor | XtCBusyCursor | Cursor | "watch"
XtNselectThreshold | XtCSelectThreshold | int | 5
XtNspaceWidth | XtCSpaceWidth | int | 5
XtNindentAscii | XtCIndentAscii | Boolean | True
XtNbulletDiameter | XtCBulletDiameter | int | 7
XtNscrollInterval | XtCScrollInterval | int | 80

XtNhypertext
    The hypertext resource contains the string that is to be displayed. The text may include various formatting tags which are contained within '<' and '>' characters. Font changes are indicated by "<f?>" where ? is a font number from 1 to 5. The specified font will apply to all text up to the next font change. Color changes are indicated by "<c?>" where ? is a color number from 1 to 8. The specified color will apply to all text up to the next color change. A hyperlink is indicated by a string of the form "<l tag-text>link-text<e>". The link-text is the text that will appear to the user, highlighted and underlined. The tag-text is a string that will be passed to a client's activate callback procedure when the hypertext is clicked. A dotted tab is a line of dots that extends across the page to a specified pixel position. It is indicated by "<d nnn>" where nnn is a decimal number specifying the desired pixel position. If the end position of the dotted tab is before the current text position, the dotted tab will be placed on the following line. A "<w1>" tag will cause subsequent text to be wrapped to the width of the parent viewport widget. Wrapping can be disabled (the default state) with a "<w0>" tag. A "<m1>" tag will cause subsequent text to be horizontally centered. Centering can be disabled (the default state) with a "<m0>" tag. Text can be indented by a specified number of pixels with a "<i nnn>" tag, where nnn is a decimal number specifying the desired pixel indent. The indent level remains in effect until it is explicitly changed, or until a bulleted or hanging paragraph is encountered. A hanging paragraph is where all lines except the first are indented by a certain number of pixels. A hanging paragraph is indicated by starting the paragraph with a "<h nnn>" tag, where nnn is the number of pixels to indent. When the paragraph ends (a newline is encountered) the indentation value is reset to zero. A bulleted paragraph is indicated by starting the paragraph with a "<b>" tag. The first line of the paragraph will be preceded by a bullet, and subsequent lines will be indented by the width of the bullet.

XtNactivate
    The activate callback is called when the user clicks on a link. A pointer to a LinkRecord is passed.

XtNnewpage
    The newpage callback is called whenever a new page is is first displayed, either through calling LinkTextNextPage, LinkTextPrevPage, LinkTextSetPage, or by setting new hypertext. A pointer to a PageRecord is passed which contains the current page and the total number of pages. The principal use for this callback is to enable the display of the current page number by a separate widget.

XtNinternalOffset
    The offset from the text to the outside edge of the widgets window.

XtNfont1
    The text is drawn using the fonts given in the font1-5 resources. The particular font to be used for rendering text is specified by font change tags within the hypertext string.

XtNfont2

XtNfont3

XtNfont4

XtNfont5

XtNcolor1
    The color1-8 resources specify the colors used for drawing the text. The particular color to be used for rendering text is specified by color change tags within the hypertext string.

XtNcolor2

XtNcolor3

XtNcolor4

XtNcolor5

XtNcolor6

XtNcolor7

XtNcolor8

XtNlinkColor
    The linkColor resource specifies the color used for drawing hyperlinks.

XtNselectForeground
    The selectForeground and selectBackground resources specify the colors used for drawing selected text.

XtNselectBackground

XtNunderlineLinks
    Specifies whether hyperlinks should be underlined or not.

XtNnormalCursor
    The normalCursor resource specifies the cursor when not on a link.

XtNlinkCursor
    The linkCursor resource specifies the cursor when on a link.

XtNbusyCursor
    The busyCursor resource specifies the cursor to be displayed when the widget gets told (via the SetBusy call) that the application is busy.

XtNselectThreshold
    The selectThreshold resource specifies how many pixels the mouse cursor must be moved before text selection is activated.

XtNspaceWidth
    The spaceWidth resource is used when converting a text selection into ASCII text. For a dotted tab, the pixel measurement is converted to a number of spaces by dividing by this resource.

XtNindentAscii
    The indentAscii resource is used when converting a text selection into ASCII text. If set to true (the default) then if the text to be converted contains a mixture of heading and non-heading lines, then the non-heading lines will be indented by two spaces in order to make the headings stand out. If set to false, then no lines will be indented.

XtNbulletDiameter
    How big a bullet in a bulleted list should be.

XtNscrollInterval
    How often (in milliseconds) the display will scroll by a line when selecting text and the mouse pointer is above or below the viewport.

    Composite
    Name | Class | Type | Default
    XtNchildren | XtCChildren | WidgetList | NULL
    insertPosition | XtCInsertPosition | XTOrderProc | NULL
    numChildren | XtCNumChildren | Cardinal | 0
    Core
    Name | Class | Type | Default
    XtNx | XtCX | Position | 0
    XtNy | XtCY | Position | 0
    XtNwidth | XtCWidth | Dimension | 0
    XtNheight | XtCHeight | Dimension | 0
    borderWidth | XtCBorderWidth | Dimension | 0
    XtNcolormap | XtCColormap | Colormap | NULL
    XtNdepth | XtCDepth | Int | 0
    destroyCallback | XtCDestroyCallback | XTCallbackList | NULL
    XtNsensitive | XtCSensitive | Boolean | True
    XtNtm | XtCTm | XTTMRec | NULL
    ancestorSensitive | XtCAncestorSensitive | Boolean | False
    accelerators | XtCAccelerators | XTTranslations | NULL
    borderColor | XtCBorderColor | Pixel | 0
    borderPixmap | XtCBorderPixmap | Pixmap | NULL
    background | XtCBackground | Pixel | 0
    backgroundPixmap | XtCBackgroundPixmap | Pixmap | NULL
    mappedWhenManaged | XtCMappedWhenManaged | Boolean | True
    XtNscreen | XtCScreen | Screen * | NULL

  Exports
The LinkRecord structure is passed to the clients activate callback procedure when a hyperlink is clicked on. The text is a string of the text actually displayed, link is the tag text associated with the hyperlink.

type
 LinkRecord = struct _linkRecord {
                String                text;
                String                link;
                }
type
 PageRecord = struct _pageRecord {
                int                current;
                int                total;
                }
The LinkTextFind procedure searches for the given text within the current page.
int  LinkTextFind( $, char * str, Boolean  fromTop)
void  LinkTextRefreshSelection( $)
The HypertextToText procedure returns a pointer to a memory block containing an ASCII text version of the hypertext currently displayed by the widget.
char * HypertextToText( $)
The SetBusy procedure takes one boolean argument. If it is true, then the widget will display the busyCursor, otherwise it will display the normalCursor or linkCursor as appropriate.
SetBusy( $, Boolean  v)
The GetBaselineskip procedure returns number of pixels between lines of text. The procedure could be really tricky, but at the moment it simply assumes that font1 is the dominant text and returns the baselineskip for that font.
Dimension  GetBaselineskip( $)
When a display consists of more than one page, display the first page.
LinkTextFirstPage( $, Boolean  reset_to_top)
When a display consists of more than one page, display the last page.
LinkTextLastPage( $, Boolean  reset_to_top)
When a display consists of more than one page, display the next page if it exists.
LinkTextNextPage( $, Boolean  reset_to_top)
When a display consists of more than one page, display the previous page if it exists.
LinkTextPrevPage( $, Boolean  reset_to_top)
When a display consists of more than one page, display the specified page if it exists.
LinkTextSetPage( $, int  p, Boolean  reset_to_top)

  Translations
The following translations allow the page to be grabbed and moved around inside the parents viewport.

<Btn2Down>: grabpage()
<Btn2Motion>: movepage()
<Btn2Up>: releasepage()
<Btn1Up>: chaselink() end_selection()
<Btn1Down>: start_selection()
<Btn1Motion>: move_selection()
<Btn3Down>: extend_selection()
The cursortype action sets the cursor to either the linkCursor or the normalCursor, depending on whether the mouse pointer is over a hyperlink.

<Motion>: cursortype()

  Actions

chaselink
    the chaselink action invokes the activate callback if the mouse pointer is over a hyperlink and text selection is not in progress.

grabpage
    The grabpage action causes the mouse cursor to change into a hand shape. Subsequent mouse movements will allow the screen to be scrolled via the movepage action.

movepage
    The movepage action causes the display to be scrolled within the parent viewport in response to mouse movements.

releasepage
    The releasepage action performs various cleanup operations needed after the display has been scrolled via the movepage action.

cursortype
    The cursortype action sets the cursor to normalCursor or linkCursor depending on whether the mouse pointer is over a hyperlink.

start_selection
    Start text selection. (Usually bound to mouse button 1.)

move_selection
    Drag out the text selection. (Usually bound to motion while mouse button 1 is held down.

extend_selection
    Extend the text selection. (Usually bound to mouse button 3.)

end_selection
    Finish making a text selection with the mouse.