home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / pascal / !Pascal / h / txt < prev    next >
Encoding:
Text File  |  1992-02-09  |  27.3 KB  |  796 lines
  1. (*
  2.  * Title:   txt.h
  3.  * Purpose: Text display object.
  4.  *
  5.  *)
  6.  
  7. #ifndef __txt_h
  8. #define __txt_h
  9.  
  10. (* 
  11.  * A txt is an array of characters, displayed in a window on the screen. It
  12.  * behaves in many ways in a manner similar to a single buffer from a
  13.  * conventional full screen text editor.
  14.  *
  15.  *)
  16.  
  17. (* 
  18.  * This interface is intended to be independent of any underlying window 
  19.  * system.
  20.  *
  21.  *)
  22.  
  23. (****************************** TXT DATA TYPE *****************************)
  24.  
  25. (* This is an abstract handle on a text object. *)
  26.  
  27. type txt_ptr = ^txt;
  28.      txt = ^txt1_str;
  29.      txt1_str = record end;
  30.  
  31.  
  32. (****************************** INTERFACE FUNCTIONS ************************)
  33.  
  34.  
  35. (* ------------------------------- txt_new ---------------------------------
  36.  * Description:   Creates a new txt object, containing no charcters, with a
  37.  *                given title (to appear in its window).
  38.  *
  39.  * Parameters:    char *title -- the text title to appear in its window
  40.  * Returns:       pointer to the newly created text.
  41.  * Other Info:    This function does not result in the text being displayed
  42.  *                on the screen; it purely creates a new text object.
  43.  *                0 is returned if there is not enough space to create the
  44.  *                object.
  45.  *
  46.  *)
  47. function txt_new(title : string) : txt; extern;
  48.  
  49.  
  50. (* -------------------------------- txt_show -------------------------------
  51.  * Description:   Display a given text object in a free standing window of
  52.  *                its own.
  53.  *
  54.  * Parameters:    txt t -- the text to be displayed.
  55.  * Returns:       void.
  56.  * Other Info:    "t" should have been created using txt_new.
  57.  *
  58.  *)
  59. procedure txt_show(t : txt); extern;
  60.  
  61.  
  62. (* ------------------------------ txt_hide ---------------------------------
  63.  * Description:   Hide a text which has been displayed.
  64.  *
  65.  * Parameters:    txt t -- the text to be hidden.
  66.  * Returns:       void.
  67.  * Other Info:    none.
  68.  *
  69.  *)
  70. procedure txt_hide(t : txt); extern;
  71.  
  72.  
  73. (* ---------------------------- txt_settitle -------------------------------
  74.  * Description:   Change the title of the window used to display a text
  75.  *                object.
  76.  *
  77.  * Parameters:    txt t -- the text object
  78.  *                char *title -- new title of window.
  79.  * Returns:       void.
  80.  * Other Info:    Long titles may be truncated when displayed.
  81.  *
  82.  *)
  83. procedure txt_settitle(t : txt; title : string); extern;
  84.  
  85.  
  86. (* ----------------------------- txt_dispose -------------------------------
  87.  * Description:   Destroy a text and the window associated with it.
  88.  *
  89.  * Parameters:    txt *t -- pointer to the text.
  90.  * Returns:       void.
  91.  * Other Info:    none.
  92.  *
  93.  *)
  94. procedure txt_dispose(var t : txt); extern;
  95.  
  96.  
  97. (*************************** General control operations. *******************)
  98.  
  99. (* A text object's main data content is an array of characters. This resides
  100.  * in a buffer of known size. The characters of the array are not laid out
  101.  * precisely in the buffer, gaps and wraparound of various forms are used in
  102.  * order to make insertion and deletion fast. When initially created a text 
  103.  * has bufsize=0. If the buffer size is precisely the same as the number of
  104.  * characters in the array then some operations (e.g. moving around in the
  105.  * array) become even faster, this may be relevant when building fixed-size
  106.  * VDU emulations.
  107.  *
  108.  *)
  109.  
  110.  
  111. (* ----------------------------- txt_bufsize -------------------------------
  112.  * Description:   Informs caller of how many characters can be stored in the
  113.  *                buffer, before more memory needs to be requested from the
  114.  *                operating system.
  115.  *
  116.  * Parameters:    txt t -- the text.
  117.  * Returns:       size of buffer.
  118.  * Other Info:    none.
  119.  *
  120.  *)
  121. function txt_bufsize(t : txt) : integer; extern;
  122.  
  123.  
  124. (* --------------------------- txt_setbufsize ------------------------------
  125.  * Description:   Allocates more space for the text buffer.
  126.  *
  127.  * Parameters:    txt t -- the text.
  128.  *                int b -- new buffer size
  129.  * Returns:       TRUE if space could be allocated successfully.
  130.  * Other Info:    This call increases the buffer size, such that at least
  131.  *                "b" characters can be stored, before requiring more from 
  132.  *                the operating system.
  133.  *
  134.  *)
  135. function txt_setbufsize(t : txt; n : integer) : boolean; extern;
  136.  
  137.  
  138. (* 
  139.  * The character array is displayed on the screen in a window.  The
  140.  * characters travel horizontally from left to right. If a '\n' is
  141.  * encountered this signifies the end of the current text line, and the 
  142.  * start of a new one. All lines have the same height, although characters
  143.  * may be of differing widths. There is no limit on the number of characters
  144.  * allowed in a line. There is no restriction on the characters allowed in
  145.  * the array, [0..255] are all acceptable.
  146.  * Clearing the DISPLAY flag can be used during a long and complex sequence
  147.  * of edits, to reduce the overall amount of display activity. The UPDATED
  148.  * flag is set by the insertion or deletion of any characters in the array.
  149.  *
  150.  *)
  151. const txt_DISPLAY = 1;     (* display changes to text as made *)
  152.       txt_CARET = 2;       (* give visible indictaion of "dot" *)
  153.       txt_UPDATED = 4;     (* set when chars are inserted/deleted *)
  154.  
  155. type txt_charoption = integer;
  156.  
  157.  
  158. (* ----------------------------- txt_charoptions ---------------------------
  159.  * Description:   Informs caller of currenly set charoptions.
  160.  *
  161.  * Parameters:    txt t -- text object.
  162.  * Returns:       Currently set charoptions.
  163.  * Other Info:    none.
  164.  *
  165.  *)
  166. function txt_charoptions(t : txt) : txt_charoption; extern;
  167.  
  168.  
  169. (* ----------------------------- txt_setcharoptions ------------------------
  170.  * Description:   Sets flags which are used to control display of text in
  171.  *                screen window.
  172.  *
  173.  * Parameters:    txt t -- text object
  174.  *                txt_charoption affect -- flags to affect
  175.  *                txt_charoption values -- values to give to affected flags
  176.  * Returns:       void.
  177.  * Other Info:    Only the flags named in "affect" are affected - they are
  178.  *                set to the value "values".
  179.  *                Thus this has the meaning:
  180.  *                  (previousState & ~affect) | (affect & values).
  181.  *
  182.  *)
  183. procedure txt_setcharoptions(t : txt_charoption;
  184.                 affect : txt_charoption;
  185.                 values : txt_charoption); extern;
  186.  
  187. (* ----------------------------- txt_lastref -------------------------------
  188.  * Description:   Returns last_ref field (for Message_DataSaved).
  189.  *
  190.  * Parameters:    txt t -- text object.
  191.  * Returns:       Current value of last_ref (for Message_DataSaved).
  192.  * Other Info:    none.
  193.  *
  194.  *)
  195. function txt_lastref(t : txt) : integer; extern;
  196.  
  197.  
  198. (* ----------------------------- txt_setlastref ----------------------------
  199.  * Description:   Sets value of last_ref (for Message_DataSaved).
  200.  *
  201.  * Parameters:    txt t -- text object
  202.  *                int newvalue -- new value
  203.  * Returns:       void.
  204.  * Other Info:    Sets the last_ref field in a txt, so that subsequently a
  205.  *                Message_DataSaved can mark the data unmodified.
  206.  *
  207.  *)
  208. procedure txt_setlastref(t : txt; newvalue : integer); extern;
  209.  
  210.  
  211. (* -------------------------- txt_setdisplayok -----------------------------
  212.  * Description:   Sets the display flag in charoptions for a given text
  213.  *
  214.  * Parameters:    txt t -- text object
  215.  * Returns:       void.
  216.  * Other Info:    You may have unset the display flag during a long/complex
  217.  *                update to the array of characters. A call to this function
  218.  *                turns display back on.
  219.  *
  220.  *)
  221. procedure txt_setdisplayok(t : txt); extern;
  222.  
  223.  
  224. (******************** Operations on the array of characters. ***************)
  225.  
  226. (* 
  227.  * "dot" is an index into the character array. If there are n chars in the
  228.  * array, with indices in [0..n-1], then dot is in [0..n]. It is thought of
  229.  * as pointing just before the character with the same index, but it can also
  230.  * point just after the last one. When the text is displayed, the character
  231.  * after the dot is always visible. The Caret is a visible indication of the
  232.  * position of the dot within the array, it can be made visible using
  233.  * SetCharOptions above.
  234.  *)
  235. type txt_index = integer; (* An index into the char array *)
  236.  
  237.  
  238. (* ------------------------------ txt_dot ----------------------------------
  239.  * Description:   Informs caller of where the "dot" (current position) is in
  240.  *                the array of characters.
  241.  *
  242.  * Parameters:    txt t -- text object 
  243.  * Returns:       An index into the array of characters.
  244.  * Other Info:    none.
  245.  *
  246.  *)
  247. function txt_dot(t : txt) : txt_index; extern;
  248.  
  249.  
  250. (* ------------------------------- txt_size --------------------------------
  251.  * Description:   Informs the caller as to the maximum value "dot" can take
  252.  *
  253.  * Parameters:    txt t -- text object.
  254.  * Returns:       Maximum permissible value of "dot".
  255.  * Other Info:    none.
  256.  *
  257.  *)
  258. function txt_size(t : txt) : txt_index; extern;
  259.  
  260.  
  261. (* ------------------------------- txt_setdot ------------------------------
  262.  * Description:   Sets the "dot" at a given index in the array of characters.
  263.  *
  264.  * Parameters:    txt t -- text object.
  265.  *                txt_index i -- index at which to set "dot".
  266.  * Returns:       void.
  267.  * Other Info:    If "i" is outside the bounds of the array it is set to the
  268.  *                beginning/end of the array appropriately.
  269.  *
  270.  *)
  271. procedure txt_setdot(t : txt; i : txt_index); extern;
  272.  
  273.  
  274. (* ------------------------------ txt_movedot ------------------------------
  275.  * Description:   Move the "dot" by a given distance in the array.
  276.  *
  277.  * Parameters:    txt t -- text object
  278.  *                int by -- distance to move by.
  279.  * Returns:       void
  280.  * Other Info:    If the resulting "dot" is outside the bounds of the array
  281.  *                it is set to the beginning/end of the array appropriately.
  282.  *
  283.  *)
  284. procedure txt_movedot(t : txt; by : integer); extern;
  285.  
  286.  
  287. (* ----------------------------- txt_insertchar ----------------------------
  288.  * Description:   Insert a character into the text just after the "dot".
  289.  *
  290.  * Parameters:    txt t -- text object
  291.  *                char c -- the character to be inserted.
  292.  * Returns:       void.
  293.  * Other Info:    If the DISPLAY option flag is set, the window is
  294.  *                redisplayed after insertion.
  295.  *
  296.  *)
  297. procedure txt_insertchar(t : txt; c : char); extern;
  298.  
  299.  
  300. (* --------------------------- txt_insertstring ----------------------------
  301.  * Description:   Inserts a given character string into a text.
  302.  *
  303.  * Parameters:    txt t -- text object
  304.  *                char *s -- the character string.
  305.  * Returns:       void.
  306.  * Other Info:    If the DISPLAY option flag is set, the window is
  307.  *                redisplayed after insertion.
  308.  *
  309.  *)
  310. procedure txt_insertstring(t : txt; s : string); extern;
  311.  
  312.  
  313. (* ------------------------------ txt_delete -------------------------------
  314.  * Description:   Deletes "n" characters from the "dot" onwards.
  315.  *
  316.  * Parameters:    txt t -- text object
  317.  *                int n -- number of characters to delete.
  318.  * Returns:       void.
  319.  * Other Info:    If "dot +n" is beyond the end of the array, then deletion
  320.  *                is to end of array.
  321.  *
  322.  *)
  323. procedure txt_delete(t : txt; n : integer); extern;
  324.  
  325.  
  326. (* ---------------------------- txt_replacechars ---------------------------
  327.  * Description:   Deletes "ntodelete" charcters from "dot", and inserts "n"
  328.  *                characters in their place, where the characters are
  329.  *                pointed at by "a".
  330.  *
  331.  * Parameters:    txt t -- text object
  332.  *                int ntodelete -- number of characters to delete
  333.  *                char *a -- pointer to characters to insert
  334.  *                int n -- number of characters to insert.
  335.  * Returns:       void.
  336.  * Other Info:    none.
  337.  *
  338.  *)
  339. procedure txt_replacechars(t : txt;
  340.                 ntodelete : integer;
  341.                 a : string;
  342.                 n : integer); extern;
  343.  
  344.  
  345. (* ---------------------------- txt_charatdot ------------------------------
  346.  * Description:   Informs caller of the character held at "dot" in the array.
  347.  *
  348.  * Parameters:    txt t -- text object.
  349.  * Returns:       Character at "dot".
  350.  * Other Info:    Returns 0 if "dot" is at/beyond end of array.
  351.  *
  352.  *)
  353. function txt_charatdot(t : txt) : char; extern;
  354.  
  355.  
  356. (* ------------------------------ txt_charat -------------------------------
  357.  * Description:   Informs caller of the character at a given index in the
  358.  *                array.
  359.  *
  360.  * Parameters:    txt t -- text object
  361.  *                txt_index i -- the index into the array.
  362.  * Returns:       Character at given index in array.
  363.  * Other Info:    Returns 0 if index is at/beyond end of array.
  364.  *
  365.  *)
  366. function txt_charat(t : txt; i : txt_index) : char; extern;
  367.  
  368.  
  369. (* ---------------------------- txt_charsatdot -----------------------------
  370.  * Description:   Copies at most "n" characters from "dot" in the array into
  371.  *                a supplied buffer.
  372.  *
  373.  * Parameters:    txt t -- text object
  374.  *                char *buffer -- the buffer
  375.  *                int *n -- maximum characters to copy.
  376.  * Returns:       void.
  377.  * Other Info:    If you are close to the end of the array, then "n" chars
  378.  *                may not be available. In this case, chars up to the end of
  379.  *                the array are copied, and *n is updated to report how many
  380.  *                were copied.
  381.  *
  382.  *)
  383. procedure txt_charsatdot(t : txt;
  384.                 buffer : string;
  385.                 var n : integer); extern;
  386.  
  387.  
  388. (* -------------------------- txt_replaceatend -----------------------------
  389.  * Description:   Deletes a specified number of characters from the end of
  390.  *                the array and then inserts specified characters.
  391.  *
  392.  * Parameters:    txt t -- text object
  393.  *                int ntodelete -- number of characters to delete
  394.  *                char *s -- pointer to characters to insert
  395.  *                int n -- number of characters to insert.
  396.  * Returns:       void.
  397.  * Other Info:    none.
  398.  *
  399.  *)
  400. procedure txt_replaceatend(t : txt;
  401.                 ntodelete : integer;
  402.                 s : string;
  403.                 n : integer); extern;
  404.  
  405.  
  406. (************************ Layout-dependent Operations. *********************)
  407.  
  408. (* 
  409.  * These operations are provided specifically for the support of cursor-
  410.  * key-driven editing.
  411.  *)
  412.  
  413.  
  414. (* ------------------------- txt_movevertical ------------------------------
  415.  * Description:   Moves the "dot" by a specified number of textual lines,
  416.  *                with the caret staying in the same horizontal position
  417.  *                on the screen.
  418.  *
  419.  * Parameters:    txt t -- text object
  420.  *                int by -- number of lines to move by
  421.  *                int caretstill -- set to non-zero, if you want the text to
  422.  *                                  move rather than the caret.
  423.  * Returns:       void.
  424.  * Other Info:    none.
  425.  *
  426.  *)
  427. procedure txt_movevertical(t : txt;
  428.                 by : integer;
  429.                 caretstill : integer); extern;
  430.  
  431.  
  432. (* --------------------------- txt_movehorizontal --------------------------
  433.  * Description:   Move the caret (and "dot") "horizontally".
  434.  *
  435.  * Parameters:    txt t -- text object
  436.  *                int by -- distance to move by.
  437.  * Returns:       void.
  438.  * Other Info:    This behaves like txt_movedot(), except that if "by" is
  439.  *                positive and the end of the current text line is
  440.  *                encountered, then the caret will continue to move to the
  441.  *                right on the screen.
  442.  *
  443.  *)
  444. procedure txt_movehorizontal(t : txt; by : integer); extern;
  445.  
  446.  
  447. (* -------------------------- txt_visiblelinecount -------------------------
  448.  * Description:   Gives the number of lines visible or partially visible
  449.  *                on the display.
  450.  *
  451.  * Parameters:    txt t -- text object.
  452.  * Returns:       Number of visible lines.
  453.  * Other Info:    Takes into account current window size, font etc.
  454.  *
  455.  *)
  456. function txt_visiblelinecount(t : txt) : integer; extern;
  457.  
  458.  
  459. (* -------------------------- txt_visiblecolcount --------------------------
  460.  * Description:   Gives the number of columns currently visible.
  461.  *
  462.  * Parameters:    txt t -- text object.
  463.  * Returns:       Visible column count.
  464.  * Other Info:    If a fixed pitch font is currently in use, then this gives
  465.  *                the number of display columns, otherwise it makes a guess
  466.  *                for "average" characters.
  467.  *
  468.  *)
  469. function txt_visiblecolcount(t : txt) : integer; extern;
  470.  
  471.  
  472. (*************************** Operations on Markers. ************************)
  473.  
  474. (* 
  475.  * Markers are indices into the array. Once set, a marker will point to the
  476.  * same character in the array regardless of insertions or deletions within
  477.  * the array. If the character pointed at by the marker is deleted then the
  478.  * marker will point to the next character. Markers never "fall off the end"
  479.  * of the array, but stay at the top or bottom of it if that's where they
  480.  * end up.
  481.  *)
  482. type txt_marker_ptr = ^txt_marker;
  483.      txt_marker =
  484.        record
  485.          a, b : integer
  486.        end;
  487. (* Abstract record, uses of fields not public. *)
  488.  
  489.  
  490. (* ---------------------------- txt_newmarker ------------------------------
  491.  * Description:   Create a new "marker" in the text.
  492.  *
  493.  * Parameters:    txt t -- text object
  494.  *                txt_marker *mark -- pointer to your text marker.
  495.  * Returns:       void.
  496.  * Other Info:    Marker itself is kept by the client of this function, but
  497.  *                the text object retains a pointer to it. The client's
  498.  *                marker is updated by the text object whenever necessary.
  499.  *                Its initial value is the same as "dot". If the character
  500.  *                at which a marker points is deleted, then the marker gets
  501.  *                moved to the value of "dot" when the deletion occurred. If
  502.  *                characters are inserted when the marker is at dot, the 
  503.  *                marker stays with "dot".
  504.  *
  505.  *)
  506. procedure txt_newmarker(t : txt; mark : txt_marker_ptr); extern;
  507.  
  508.  
  509. (* -------------------------- txt_movemarker -------------------------------
  510.  * Description:   Resets an existing marker.
  511.  *
  512.  * Parameters:    txt t  - text object
  513.  *                txt_marker *mark -- the marker
  514.  *                txt_index to -- place to move the marker to
  515.  * Returns:       void.
  516.  * Other Info:    The amrker must already point into this text object
  517.  *
  518.  *)
  519. procedure txt_movemarker(t : txt;
  520.                 mark : txt_marker_ptr;
  521.                 _to : txt_index); extern;
  522.  
  523.  
  524. (* ------------------------- txt_movedottomarker ---------------------------
  525.  * Description:   Moves the "dot" to a given marker.
  526.  *
  527.  * Parameters:    txt t -- text object
  528.  *                txt_marker *mark -- pointer to the marker
  529.  * Returns:       void.
  530.  * Other Info:    none.
  531.  *
  532.  *)
  533. procedure txt_movedottomarker(t : txt; mark : txt_marker_ptr); extern;
  534.  
  535.  
  536. (* ----------------------- txt_indexofmarker -------------------------------
  537.  * Description:   Gives the current index into the array of a given marker
  538.  *
  539.  * Parameters:    txt t -- text object
  540.  *                txt_marker *mark.
  541.  * Returns:       Index of marker
  542.  * Other Info:    none.
  543.  *
  544.  *)
  545. function txt_indexofmarker(t : txt;
  546.                 mark : txt_marker_ptr) : txt_index; extern;
  547.  
  548.  
  549. (* ---------------------------- txt_disposemarker --------------------------
  550.  * Description:   Delete a marker from a text object.
  551.  *
  552.  * Parameters:    txt t -- text object
  553.  *                txt_marker *mark -- the marker to be deleted.
  554.  * Returns:       void.
  555.  * Other Info:    WARNING: You should remember to dispose of a marker which
  556.  *                logically ceases to exist, otherwise the text object will
  557.  *                continue to update the location where it was!.
  558.  *
  559.  *)
  560. procedure txt_disposemarker(t : txt; mark : txt_marker_ptr); extern;
  561.  
  562.  
  563. (*********************** Operations on a selection. ************************)
  564.  
  565. (* The selection is a contiguous portion of the array which is
  566.  * displayed highlighted.
  567.  *)
  568.  
  569. (* ---------------------------- txt_selectset ------------------------------
  570.  * Description:   Informs caller whether there is a selction made in a text.
  571.  *
  572.  * Parameters:    txt t -- text object.
  573.  * Returns:       TRUE if there is a selection in this text.
  574.  * Other Info:    none.
  575.  *
  576.  *)
  577. function txt_selectset(t : txt) : boolean; extern;
  578.  
  579.  
  580. (* --------------------------- txt_selectstart -----------------------------
  581.  * Description:   Gives the index into the array of the start of the current
  582.  *                selection.
  583.  * 
  584.  * Parameters:    txt t -- text object.
  585.  * Returns:       Index of selection start.
  586.  * Other Info:    none.
  587.  *
  588.  *)
  589. function txt_selectstart(t : txt) : txt_index; extern;
  590.  
  591.  
  592. (* --------------------------- txt_selectend -------------------------------
  593.  * Description:   Gives the index into the array of the end of the current
  594.  *                selection.
  595.  *
  596.  * Parameters:    txt t -- text object.
  597.  * Returns:       Index of selection end.
  598.  * Other Info:    none.
  599.  *
  600.  *)
  601. function txt_selectend(t : txt) : txt_index; extern;
  602.  
  603.  
  604. (* -------------------------- txt_setselect --------------------------------
  605.  * Description:   Sets a selection in a given text, from "start" to "end"
  606.  *
  607.  * Parameters:    txt t -- text object
  608.  *                txt_index start -- array index of start of selection
  609.  *                txt_index end -- array index of end of selection.
  610.  *
  611.  * Returns:       void.
  612.  * Other Info:    If "start" >= "end" then the selection will be unset.
  613.  *
  614.  *)
  615. procedure txt_setselect(t : txt; start, _end : txt_index); extern;
  616.  
  617.  
  618. (*************************** Input from the user ***************************)
  619.  
  620. (* Characters entered into the keyboard, and various mouse events, are
  621. buffered up by the text object for use by the client. *)
  622.  
  623. type txt_eventcode = integer;
  624.  
  625.  
  626. (* ------------------------------- txt_get ---------------------------------
  627.  * Description:   Gives the next user event code to the caller.
  628.  *
  629.  * Parameters:    txt t -- text object.
  630.  * Returns:       The event code.
  631.  * Other Info:    The returned code can be ASCII, or various other (system-
  632.  *                specific) values for function keys etc.
  633.  *
  634.  *)
  635. function txt_get(t : txt) : txt_eventcode; extern;
  636.  
  637.  
  638. (* ------------------------------- txt_queue -------------------------------
  639.  * Description:   Informs caller of how many event codes are currently
  640.  *                buffered for a given text.
  641.  *
  642.  * Parameters:    txt t -- text object.
  643.  * Returns:       No. of buffered event codes.
  644.  * Other Info:    none.
  645.  *
  646.  *)
  647. function txt_queue(t : txt) : integer; extern;  
  648.  
  649.  
  650. (* ----------------------------- txt_unget ---------------------------------
  651.  * Description:   Puts an event code back on the front of the event queue
  652.  *                for a given text.
  653.  *
  654.  * Parameters:    txt t -- text object
  655.  *                txt_eventcode code -- the event code.
  656.  * Returns:       void.
  657.  * Other Info:    none.
  658.  *
  659.  *)
  660. procedure txt_unget(t : txt; code : txt_eventcode); extern;
  661.  
  662.  
  663. (****************************** Mouse events *******************************)
  664.  
  665. const
  666.   txt_MSELECT = $01000000;
  667.   txt_MEXTEND = $02000000;
  668.   txt_MSELOLD = $04000000;
  669.   txt_MEXTOLD = $08000000;
  670.   txt_MEXACT = $10000000;
  671.   txt_EXTRACODE = $40000000;
  672.   txt_MOUSECODE = unot($7fffffff);
  673.  
  674. type txt_mouseeventflag = integer; (* used as a set *)
  675.  
  676. (* A mouse event occurs when the mouse is pointing in the text object and a
  677.  * button is pressed or released, or the mouse moves while any button is
  678.  * depressed. A mouse event will result in Get producing an EventCode with
  679.  * bit 31 set, bits 24..28 as a mouseeventflags value, and the rest of the
  680.  * word containing an index value.
  681.  *
  682.  * The index shows where in the visible representation of the array the mouse
  683.  * event happened. If all three index bytes are 255 then the event happened
  684.  * outside the window. The mouseeventflags show what button transitions
  685.  * occurred:
  686.  *    MSELECT -- select's new value
  687.  *    MEXTEND -- extend's new value
  688.  *    MSELOLD -- select's old value
  689.  *    MEXTOLD -- extend's old value
  690.  *    MEXACT -- the event is in exactly the same place as the last one
  691.  * The byte gives the values of the select and extend buttons, 1 for
  692.  * depressed and 0 for not depressed. It gives their previous values,
  693.  * allowing transitions to be detected. It says if the position of the mouse
  694.  * is exactly the same as for the last event, so that multiple clicks may be
  695.  * detected. No assumptions should be made concerning the relationship of
  696.  * these bits to the last mouse event sent to the programmer, as polling
  697.  * delays etc. could cause any combinations to happen. 
  698.  *
  699.  * If txt_EXTRACODE is set then the identity of the event is not defined
  700.  * by this interface. This is used for any expansion. Clients of this
  701.  * interface which receive such events that they do not recognise, should
  702.  * ignore them without reporting an error. 
  703.  *
  704.  * The menu button on the mouse is not transmitted through this interface,
  705.  * but caught elsewhere.
  706.  * 
  707.  *)
  708. type txt_event_proc = ^procedure event_proc(t : txt; handle : pointer);
  709.  
  710.  
  711. (* ---------------------------- txt_eventhandler ---------------------------
  712.  * Description:   Register an eventhandler function for a given text, 
  713.  *                which will be called whenever there is a value ready which
  714.  *                can be picked up by txt_get().
  715.  *
  716.  * Parameters:    txt t -- text object
  717.  *                txt_event_proc func -- event handler function
  718.  *                void *handle -- caller-defined handle to be passed to func.
  719.  * Returns:       void.
  720.  * Other Info:    If func==0 then no function is registered.
  721.  *
  722.  *)
  723. procedure txt_eventhandler(t : txt;
  724.                 p : txt_event_proc;
  725.                 handle : pointer); extern;
  726.  
  727.  
  728. (* -------------------------- txt_readeventhandler -------------------------
  729.  * Description:   Informs caller of the currently registered eventhandler
  730.  *                function associated with a given text, and the handle which
  731.  *                is passed to it.
  732.  *
  733.  * Parameters:    txt t -- text object
  734.  *                txt_event_proc *func -- returned pointer to handler func
  735.  *                void **handle -- returned pointer to handle.
  736.  * Returns:       void.
  737.  * Other Info:    none.
  738.  *
  739.  *)
  740. procedure txt_readeventhandler(t : txt;
  741.                 var func : txt_event_proc;
  742.                 var handle : pointer); extern;
  743.  
  744.  
  745. (******************* Direct Access to the array of characters **************)
  746.  
  747. (* ---------------------------- txt_arrayseg -------------------------------
  748.  * Description:   Gives a direct pointer into the memory used to hold the
  749.  *                characters in a text.
  750.  *
  751.  * Parameters:    txt t -- text object
  752.  *                txt_index at -- index into the text
  753.  *                char **a -- *a will point at the character whose index
  754.  *                            in the text is "at"
  755.  *                int *n -- *n == no. of contiguous bytes after "at"
  756.  * Returns:       void.
  757.  * Other Info:    It is permissible for the caller of this function to change
  758.  *                the characters pointed at by *a, provided that a redsiplay
  759.  *                is prompted (using setcharoptions).
  760.  *
  761.  *)
  762. procedure txt_arrayseg(t : txt;
  763.                 at : txt_index;
  764.                 var a : string;
  765.                 var n : integer); extern;
  766.  
  767.  
  768. (******************************* System hook *******************************)
  769.  
  770.  
  771. (* ---------------------------- txt_syshandle ------------------------------
  772.  * Description:   Obtains a system_dependent handle on the object underlying
  773.  *                a text.
  774.  *
  775.  * Parameters:    txt t -- text object.
  776.  * Returns:       System-dependent handle for the given text.
  777.  * Other Info:    none.
  778.  *
  779.  *)
  780. function txt_syshandle(t : txt) : integer; extern;
  781.  
  782.  
  783. (* ---------------------------------- txt_init -----------------------------
  784.  * Description:   Initialise the txt module of the library
  785.  *
  786.  * Parameters:    void.
  787.  * Returns:       void.
  788.  * Other Info:    none.
  789.  *
  790.  *)
  791. procedure txt_init; extern;
  792.  
  793. # endif
  794.  
  795. (* end txt.h *)
  796.