diff options
Diffstat (limited to 'blt/html/htext.html')
| -rw-r--r-- | blt/html/htext.html | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/blt/html/htext.html b/blt/html/htext.html new file mode 100644 index 00000000000..67cc43905f4 --- /dev/null +++ b/blt/html/htext.html @@ -0,0 +1,397 @@ + <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, --> +<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> + +<HTML> +<HEAD> +<TITLE>htext(n) manual page</TITLE> +</HEAD> +<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red"> +<A HREF="#toc">Table of Contents</A><P> + +<H2><A NAME="sect0" HREF="#toc0">Name</A></H2> +htext - Create and manipulate hypertext widgets + +<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2> +<B>htext</B> <I>pathName </I>?<I>option value</I>?... +<H2><A NAME="sect2" HREF="#toc2">Description</A></H2> +<P> +The <B>htext</B> command creates +a new window (given by the <I>pathName</I> argument) and makes it into a <B>htext</B> +widget. Additional options, described above, may be specified on the command +line or in the option database to configure aspects of the widget such +as its color and font. At the time this command is invoked, there must +not exist a window named <I>pathName</I>, but <I>pathName</I>'s parent must exist. The +<B>htext</B> command returns its <I>pathName</I>. <P> +The <B>htext</B> widget is hybrid of a non-editable +text widget and a geometry manager (e.g. the packer). It displays text (optionally +read from file) in a window. Text can be scrolled either horizontally or +vertically using the <B>htext</B> window as a viewport. In addition, Tcl commands +can be embedded into the text which are evaluated as the text is parsed. + Text between special double characters (percent signs "%%") is immediately +passed to the Tcl interpreter for evaluation. <P> +Furthermore, any widget +or widget hierarchy can be packed in-line and made to appear on the current +line of the text. Widgets are packed using the <B>htext append</B> command. All +widgets must be children of the <B>htext</B> window and must already exist before +packing. Once a widget has been packed it cannot be moved to a different +position within the text. Widgets can be resized but they will remain +at the same position within the text. <P> +Before a file or text string is parsed +by the <B>htext</B> widget, all the widget's current children are destroyed. You +can reload files or text without worrying about unmapping or destroying +each child window beforehand. <P> +Setting the either the <B>-filename</B> or <B>-text</B> configuration +option will adjust the value of the other. If both options are set, the +file takes precedence. When a new file is read using the <B>-filename</B> option, +the value of the <B>-text</B> option is reset to the empty string. Likewise, when +the <B>-text</B> option is set, the string representing the <B>-filename</B> option is +cleared. +<H2><A NAME="sect3" HREF="#toc3">File Format</A></H2> +The format of <B>htext</B> text file is typically ASCII text. + Text enclosed by special double characters (by default, percent signs +'%%') is interpreted and executed as Tcl commands. The special character + may be specified by the <B>-specialchar</B> option. In the following example of +a <B>htext</B> file, a button widget is appended to the text between the words +"<I>a</I>" and "<I>which</I>". The <I>pathName</I> of the <B>htext</B> widget is "<I>.ht</I>". <BR> +<CODE><I>This will be displayed as normal text. <BR> +</I>But this will become a %% <BR> + button .ht.button -text "button" -fg red<BR> + .ht append .ht.button <BR> +%% which can invoke a Tcl command.<BR> +<P> + +<H2><A NAME="sect4" HREF="#toc4"></CODE><P>Indices</A></H2> +<P> +Some of the widget operations (<B>selection</B>, gotoline, <B>search</B>, etc.) +take one or more indices as arguments. An index is a string used to indicate +a particular place within the text, such as the first and last characters +in a range to be selected. <P> +An index must have one of the following forms: + +<DL> + +<DT><I>line<B>.<I>char</I></B></I> </DT> +<DD>Indicates <I>char</I>'th character on line <I>line</I>. Both lines and characters +are number from 0, so "0.0" is the first beginning of the text. <I>Char</I> may +be undesignated. In this case a character position of 0 is assumed. </DD> + +<DT><B>@<I>x<B>,<I>y</I></B></I></B> +</DT> +<DD>Indicates the character that covers the pixel whose x and y coordinates +within the text's window are <I>x</I> and <I>y</I>. </DD> + +<DT><B>end</B> </DT> +<DD>Indicates the end of the text. </DD> + +<DT><B>anchor</B> +</DT> +<DD>Indicates the anchor point for the selection, which is set with the <B>selection</B> +operation. </DD> + +<DT><B>sel.first</B> </DT> +<DD>Indicates the first character in the selection. It is +an error to use this form if the selection isn't in the entry window. </DD> + +<DT><B>sel.last</B> +</DT> +<DD>Indicates the character just after the last one in the selection. It is +an error to use this form if the selection isn't in the entry window. </DD> +</DL> + +<H2><A NAME="sect5" HREF="#toc5">Variables</A></H2> +<P> +The +following global Tcl variables are maintained when an <B>htext</B> file is parsed. + +<DL> + +<DT><B>htext(widget)</B> </DT> +<DD>is the pathname of the <B>htext</B> widget. </DD> + +<DT><B>htext(file)</B> </DT> +<DD>is the +name of the file the <B>htext</B> widget is currently parsing. It is the empty +string when the <B>-text</B> option is used. </DD> + +<DT><B><A HREF="htext.l.html">htext(line)</B></A> + </DT> +<DD>is the current line number +in the text. </DD> +</DL> +<P> +This information might be used to construct hyper links +between different files and/or lines. <P> + +<H2><A NAME="sect6" HREF="#toc6">Syntax</A></H2> +The <B>htext</B> command creates a +new Tcl command whose name is <I>pathName</I>. This command may be used to invoke +various operations on the widget. It has the following general form: <BR> +<P> +<CODE><I>pathName oper </I>?<I>args</I>?<BR> +</CODE><P><I>Oper</I> and <I>args</I> determine the exact behavior of the command. <P> + +<H2><A NAME="sect7" HREF="#toc7">Operations</A></H2> +The +following operations are available for <B>htext</B> widgets: +<DL> + +<DT><I>pathName <B>append <I>window +</I></B></I>?<I>option value</I>?... </DT> +<DD>Embeds the widget <I>window</I> into the htext widget. <I>Window</I> +is the pathname of the widget to be embedded which must be a child of <I>pathName</I>. + <I>Window</I> will be positioned in the htext widget at the current location +of the text. If <I>option</I> and <I>value</I> pairs are present, they configure various +aspects how <I>window</I> appears in <I>pathName</I>. The following options are available. +<blockquote></DD> + +<DT><B>-anchor <I>anchorPos</I></B> </DT> +<DD>Specifies how <I>window</I> will be arranged if there is any +extra space in the cavity surrounding the window. For example, if <I>anchorPos</I> +is <B>center</B> then the window is centered in the cavity; if <I>anchorPos</I> is <B>w</B> +then the window will be drawn such it touches the leftmost edge of the +cavity. The default is <I>center</I>. </DD> + +<DT><B>-fill <I>style</I></B> </DT> +<DD>Specifies how the <I>window</I> should +be stretched to occupy the extra space in the cavity surrounding it (if +any exists). <I>Style</I> is <I>none</I>, <I>x</I>, <I>y</I>, <I>both</I>. If <I>style</I> is <I>x</I>, the width of <I>window</I> +is expanded to fill the cavity. If <I>style</I> is <B>y</B>, the height is expanded. +The default is <I>none</I>. </DD> + +<DT><B>-height <I>pixels</I></B> </DT> +<DD>Sets the height of the cavity surrounding +<I>window</I>. If <I>pixels</I> is zero, the height of the cavity will be the same as +the requested height of <I>window</I>. If <I>pixels</I> is less than the requested height +of <I>window</I>, <I>window</I> will be reduced to fit the cavity. The default is <I>0</I>. </DD> + +<DT><B>-ipadx +<I>pad</I></B> </DT> +<DD>Sets the amount of internal padding to be added to the width <I>window</I>. + <I>Pad</I> can be a list of one or two numbers. If <I>pad</I> has two elements, the +left side of <I>window</I> is extended by the first value and the right side by +the second value. If <I>pad</I> is just one value, both the left and right sides +are padded by evenly by the value. The default is <I>0</I>. </DD> + +<DT><B>-ipady <I>pad</I></B> </DT> +<DD>Sets an amount +of internal padding to be added to the height of <I>window</I>. <I>Pad</I> can be a list +of one or two numbers. If <I>pad</I> has two elements, the top of <I>window</I> is padded +by the first value and the bottom by the second value. If <I>pad</I> is just one +number, both the top and bottom are padded evenly by the value. The default +is <I>0</I>. </DD> + +<DT><B>-justify <I>justify</I></B> </DT> +<DD>Justifies <I>window</I> vertically within the cavity containing +it in relation to the line of text. <I>Justify</I> is <B>top</B>, <B>bottom</B>, or <B>center</B>. + If <I>justify</I> is <I>center</I> the widget is centered along the baseline of the +line of text. The default is <I>center</I>. </DD> + +<DT><B>-padx <I>pad</I></B> </DT> +<DD>Sets the padding on the left +and right sides of <I>window</I>. <I>Pad</I> can be a list of one or two numbers. If <I>pad</I> +has two elements, the left side of <I>window</I> is padded by the first value +and the right side by the second value. If <I>pad</I> has just one value, both +the left and right sides are padded evenly by the value. The default is +<I>0</I>. </DD> + +<DT><B>-pady <I>pad</I></B> </DT> +<DD>Sets the padding above and below <I>window</I>. <I>Pad</I> can be a list of +one or two numbers. If <I>pad</I> has two elements, the area above <I>window</I> is padded +by the first value and the area below by the second value. If <I>pad</I> is just +one number, both the top and bottom are padded by the value. The default +is <I>0</I>. </DD> + +<DT><B>-relheight <I>value</I></B> </DT> +<DD>Specifies the height of the cavity containing <I>window</I> +relative to the height of <I>pathName</I>. <I>Value</I> is real number indicating the +ratio of the height of the cavity to the height of <I>pathName</I>. As the height +of <I>pathName</I> changes, so will the height of <I>window</I>. If <I>value</I> is 0.0 or less, +the height of the cavity is the requested height <I>window</I>. The default is +<I>0.0</I>. </DD> + +<DT><B>-relwidth <I>value</I></B> </DT> +<DD>Specifies the width of the cavity containing <I>window</I> relative +to the width of <I>pathName</I>. <I>Value</I> is real number indicating the ratio of +the width of the cavity to the width of IpathName. As the height of <I>pathName</I> +changes, so will the height of <I>window</I>. If <I>value</I> is 0.0 or less, the width +of the cavity is the requested width of <I>window</I>. The default is <I>0.0</I>. </DD> + +<DT><B>-width +<I>value</I></B> </DT> +<DD>Species the width of the cavity containing the child window. <I>Value</I> +must be in a form accepted by <B>Tk_GetPixels</B>. If <I>value</I> is greater than zero, +the cavity is resized to that width. If the requested window width is +greater than the cavity's width, the window will be reduced to fit the cavity. +By default, the cavity is requested width of the child window. </DD> +</DL> +</blockquote> + +<DL> + +<DT><I>pathName +<B>configure</B></I> ?<I>window</I>? ?<I>option</I>? ?<I>value option value ...</I>? </DT> +<DD>Queries or modifies the +configuration options of the text widget or one of its embedded widgets. + If no <I>window</I> argument is present, the htext widget itself is configured. + Otherwise <I>window</I> is the pathname of a widget already embedded into the +htext widget. Then this command configure the options for the embedded widget. +</DD> +</DL> +<P> +If <I>option</I> isn't specified, a list describing all of the current options +for <I>pathName</I> or <I>window</I> is returned. If <I>option</I> is specified, but not <I>value</I>, +then a list describing the option <I>option</I> is returned. If one or more <I>option</I> +and <I>value</I> pairs are specified, then for each pair, the htext or embedded + window option <I>option</I> is set to <I>value</I>. <P> +The following options are valid for +the htext widget. <blockquote> +<DL> + +<DT><B>-background</B> <I>color<I> </I></I></DT> +<DD>Sets the background of the htext widget +to <I>color</I>. This default is <I>white</I>. </DD> + +<DT><B>-cursor</B> <I>cursor</I> </DT> +<DD>Specifies the cursor for +the htext widget. The default cursor is <I>pencil</I>. </DD> + +<DT><B>-filename</B> <I>fileName</I> </DT> +<DD>Specifies +a <B>htext</B> file to be displayed in the window. If the value is the empty string, +the <B>-text</B> option is used instead. See the section <FONT SIZE=-1><B>FILE</B></FONT> + for a description +of the <B>htext</B> file format. </DD> + +<DT><B>-font</B> <I>fontName</I> </DT> +<DD>Sets the font of the text in the +htext widget to <I>fontName</I>. The default is <I>*-Helvetica-Bold-R-Normal-*-12-120-*</I>. </DD> + +<DT><B>-foreground</B> +<I>color</I> </DT> +<DD>Sets the foreground of the htext widget to <I>color</I>. This is the color +of the text. This default is <I>black</I>. </DD> + +<DT><B>-height</B> <I>pixels</I> </DT> +<DD>Specifies the height of +the htext widget window. </DD> + +<DT><B>-linespacing</B> <I>pixels</I> </DT> +<DD>Specifies the spacing between +each line of text. The value must be in a form accepted by <B>Tk_GetPixels</B>. +The default value is 1 pixel. </DD> + +<DT><B>-specialchar</B> <I>number</I> </DT> +<DD>Specifies the ASCII value +of the special double character delimiters. In <B>htext</B> files, the text between +these special characters is evaluated as a block of Tcl commands. The default +special character is the <I>0x25</I> (percent sign). </DD> + +<DT><B>-text</B> <I>text</I> </DT> +<DD>Specifies the +text to be displayed in the htext widget. <I>Text</I> can be any valid string +of characters. See <FONT SIZE=-1><B>FILE FORMAT</B></FONT> + for a description. </DD> + +<DT><B>-xscrollcommand</B> <I>string</I> + </DT> +<DD>Specifies the prefix for a command used to communicate with horizontal +scrollbars. When the view in the htext widget's window changes (or whenever +anything else occurs that could change the display in a scrollbar, such +as a change in the total size of the widget's contents), the widget invoke +<I>string</I> concatenated by two numbers. Each of the numbers is a fraction between +0 and 1, which indicates a position in the document. If this option is +not specified, then no command will be executed. </DD> + +<DT><B>-yscrollcommand</B> <I>string</I> </DT> +<DD>Specifies +the prefix for a command used to communicate with vertical scrollbars. +When the view in the htext widget's window changes (or whenever anything +else occurs that could change the display in a scrollbar, such as a change +in the total size of the widget's contents), the widget invoke <I>string</I> concatenated +by two numbers. Each of the numbers is a fraction between 0 and 1, which +indicates a position in the document. If this option is not specified, +then no command will be executed. </DD> + +<DT><B>-width</B> <I>pixels</I> </DT> +<DD>Specifies the desired width +of the viewport window. If the <I>pixels</I> is less than one, the window will +grow to accommodate the widest line of text. </DD> + +<DT><B>-xscrollunits</B> <I>pixels</I> </DT> +<DD>Specifies +the horizontal scrolling distance. The default is 10 pixels. </DD> + +<DT><B>-yscrollunits</B> +<I>pixels</I> </DT> +<DD>Specifies the vertical scrolling distance. The default is 10 pixels. +</DD> +</DL> +</blockquote> + +<DL> + +<DT><I>pathName <B>gotoline </B></I>?<I>index</I>? </DT> +<DD>Sets the top line of the text to <I>index</I>. <I>Index</I> +must be a valid text index (the character offset is ignored). If an <I>index</I> +isn't provided, the current line number is returned. </DD> + +<DT><I>pathName <B>scan mark +<I>position</I></B></I> </DT> +<DD>Records <I>position</I> and the current view in the text window; used +in conjunction with later <B>scan dragto</B> commands. <I>Position</I> must be in the +form "<I>@x,y</I>, where <I>x</I> and <I>y</I> are window coordinates. Typically this command +is associated with a mouse button press in the widget. It returns an empty +string. </DD> + +<DT><I>pathName <B>scan dragto <I>position</I></B></I> </DT> +<DD>Computes the difference between <I>position</I> +and the position registered in the last <B>scan mark</B> command for the widget. + The view is then adjusted up or down by 10 times the difference in coordinates. + This command is can be associated with mouse motion events to produce +the effect of dragging the text at high speed through the window. <I>Position</I> +must be in the form "<I>@x,y</I>, where <I>x</I> and <I>y</I> are window coordinates. The command +returns an empty string. </DD> + +<DT><I>pathName <B>search <I>pattern</I></B></I> ?<I>from</I>? ?<I>to</I>? </DT> +<DD>Returns the +number of the next line matching <I>pattern</I>. <I>Pattern</I> is a string which obeys +the matching rules of <B>Tcl_StringMatch</B>. <I>From</I> and <I>to</I> are text line numbers +(inclusive) which bound the search. If no match for <I>pattern</I> can be found, +<B>-1</B> is returned. </DD> + +<DT><I>pathName <B>xview </B></I>?<I>position</I>? </DT> +<DD>Moves the viewport horizontally +to the new text x-coordinate position. <I>Position</I> is the offset from the +left side of the text to the current position and must be in a form accepted +by <B>Tk_GetPixels</B>. If <I>position</I> is not present, the current text position is +returned. </DD> + +<DT><I>pathName <B>yview </B></I>?<I>position</I>? </DT> +<DD>Moves the viewport vertically to the +new text y-coordinate position. <I>Position</I> is the offset from the top of +the text to the current position and must be in a form accepted by <B>Tk_GetPixels</B>. +If <I>position</I> is not present, the current text position is returned. </DD> +</DL> + +<H2><A NAME="sect8" HREF="#toc8">Bugs</A></H2> +Text +with embedded tabs can be obscured by child windows when scrolled horizontally. + +<H2><A NAME="sect9" HREF="#toc9">Keywords</A></H2> +hypertext, widget <P> + +<HR><P> +<A NAME="toc"><B>Table of Contents</B></A><P> +<UL> +<LI><A NAME="toc0" HREF="#sect0">Name</A></LI> +<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI> +<LI><A NAME="toc2" HREF="#sect2">Description</A></LI> +<LI><A NAME="toc3" HREF="#sect3">File Format</A></LI> +<LI><A NAME="toc4" HREF="#sect4">Indices</A></LI> +<LI><A NAME="toc5" HREF="#sect5">Variables</A></LI> +<LI><A NAME="toc6" HREF="#sect6">Syntax</A></LI> +<LI><A NAME="toc7" HREF="#sect7">Operations</A></LI> +<LI><A NAME="toc8" HREF="#sect8">Bugs</A></LI> +<LI><A NAME="toc9" HREF="#sect9">Keywords</A></LI> +</UL> +</BODY></HTML> |