(* 
 * Title: txtedit.h
 * Purpose: Text editing facilities.
 *
 *)

# ifndef __txtedit_h
# define __txtedit_h

# ifndef __txt_h
# include "txt.h"
# endif

# ifndef __typdat_h
# include "typdat.h"
# endif

#ifndef __menu_h
#include "menu.h"
#endif

(****************************** DATA TYPES *********************************)

const
    txtedit_CHARSEL = 1;
    txtedit_WORDSEL = 2;
    txtedit_LINESEL = 4;

type txtedit_seltype = integer;

type txtedit_state_ptr = ^txtedit_state;
     txtedit_state =
       record
         t : txt;
         selpivot : txt_marker;       (* used in mouse op calculations *)
         seltype : txtedit_seltype;   (* used in mouse op calculations *)
         selectrecent : integer;      (* used in mouse op calculations *)
         selectctl : integer;         (* used in mouse op calculations *)
         filename : packed array[1..255] of char;
         ty : typdat;
         deletepending : integer;
         next : txtedit_state_ptr;    (* chain of all of them. *)
         overwrite : integer;
         wordtab : integer;
         wordwrap : integer
       end;

type txtedit_update_handler = ^function update_handler(s : string;
                                         state : txtedit_state_ptr;
                                         handle : pointer) : boolean;
type txtedit_close_handler = ^procedure close_handler(s : string;
                                         state : txtedit_state_ptr;
                                         handle : pointer);
type txtedit_save_handler = ^function save_handler(s : string;
                                         state : txtedit_state_ptr;
                                         handle : pointer) : boolean;
type txtedit_shutdown_handler = ^procedure shutdown_handler(
                                         handle : pointer);
type txtedit_undofail_handler = ^procedure undofail_handler(s : string;
                                         state : txtedit_state_ptr;
                                         handle : pointer);
type txtedit_open_handler = ^procedure open_handler(s : string;
                                         state : txtedit_state_ptr;
                                         handle : pointer);

(**************************** INTERFACE FUNCTIONS *************************)


(* --------------------------- txtedit_install -----------------------------
 * Description:   Installs an event handler for the txt t, thus making it
 *                an editable text.
 *
 * Parameters:    txt t -- the text object (created via txt_new)
 * Returns:       A pointer to the resulting txtedit_state.
 * Other Info:    none.
 *
 *)
function txtedit_install(t : txt) : txtedit_state_ptr; extern;


(* ----------------------------- txtedit_new -------------------------------
 * Description:   Creates a new text object, loads the given file into it
 *                and the text can now be edited.
 *
 * Parameters:    char *filename -- the file to be loaded.
 * Returns:       a pointer to the txtedit_state for this text.
 * Other Info:    If the file cannot be found, then 0 is returned as a 
 *                result, and no text is created. If "filename" is a null
 *                pointer, then an editor window with no given file name
 *                will be constructed. If the file is already being edited,
 *                then a pointer to the existing txtedit_state is returned.
 *
 *)
function txtedit_new(filename : string) : txtedit_state_ptr; extern;


(* ---------------------------- txtedit_dispose ----------------------------
 * Description:   Destroys the given text being edited.
 *
 * Parameters:    txtedit_state *s -- the text to be destroyed.
 * Returns:       void.
 * Other Info:    Note: this will ask no questions of the user before
 *                destroying the text.
 *
 *)
procedure txtedit_dispose(s : txtedit_state_ptr); extern;


(* --------------------------- txtedit_mayquit -----------------------------
 * Description:   Check if we may safely quit editing.
 *
 * Parameters:    void.
 * Returns:       TRUE if we may safely quit, otherwise FALSE.
 * Other Info:    If a text is being edited, then a dialogue box is displayed
 *                asking the user if he really wants to quit.
 *                This calls dboxquery(), and therefore requires the 
 *                template "query" as described in dboxquery.h.
 *
 *)
function txtedit_mayquit : boolean; extern;


(* ----------------------------- txtedit_prequit ---------------------------
 * Description:   Deal with a PREQUIT message from the task manager.
 *
 * Parameters:    void.
 * Returns:       void.
 * Other Info:    Calls txtedit_mayquit(), to see if we may quit, if text
 *                is being edited. If user replies that we may quit, then
 *                all texts are disposed of, and this function sends an
 *                acknowledgement to the task manager.
 *
 *)
procedure txtedit_prequit; extern;


(* ---------------------------- txtedit_menu -------------------------------
 * Description:   Sets up a menu structure for the text being edited,
 *                tailored to its current state.
 *
 * Parameters:    txtedit_state * s -- the text's current state.
 * Returns:       a pointer to an appropriately formed menu structure
 * Other Info:    The menu created will have the same form as that displayed
 *                when mouse menu button is clicked on an !Edit window.
 *                (For !Edit version 1.00).
 *                Entries in the menu are set according to the supplied
 *                txtedit_state.
 *)
function txtedit_menu(s : txtedit_state_ptr) : menu; extern;


(*------------------------------ txtedit_menuevent -------------------------
 * Description:   Apply a given menu hit to a given text.
 *
 * Parameters:    txtedit_state *s -- the text to which hit should be applied
 *                char *hit -- a menu hit string.
 * Returns:       void.
 * Other Info:    This can be called from a menu event handler.
 *
 *)
procedure txtedit_menuevent(s : txtedit_state_ptr; hit : string); extern;


(* --------------------------- txtedit_doimport ----------------------------
 * Description:   Import data into the specified txtedit object, from a file
 *                of a given type.
 *
 * Parameters:    txtedit_state *s -- the text object
 *                int filetype -- type of the file
 *                int estsize -- file's estimated size.
 * Returns:       TRUE if import completed successfully.
 * Other Info:    none.
 *
 *)
function txtedit_doimport(s : txtedit_state_ptr;
                filetype : integer;
                estsize : integer) : boolean; extern;


(* ------------------------- txtedit_doinsertfile --------------------------
 * Description:   Inserts a named file in a given text object.
 *
 * Parameters:    txtedit_state *s -- the text object
 *                char *filename -- the given file
 *                BOOL replaceifwasnull -- if set to TRUE then the text
 *                                         object will be considred to have
 *                                         come from "filename", ie. window
 *                                         title is updated.
 *
 * Returns:       void.
 * Other Info:    none.
 *
 *)
procedure txtedit_doinsertfile(s : txtedit_state_ptr;
                filename : string;
                replaceifwasnull : boolean); extern;


(* ------------------------ txtedit_register_update_handler ---------------
 * Description:   Register a handler to be called when a text window is 
 *                modified
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    This routine will be called whenever a window's title bar
 *                is redrawn, and the text in the window has been modified.
 *                Note: this is not just called when the '*' first appears 
 *                in a window's title bar, but every time the title bar of a
 *                modified text window is redrawn (eg. when the filename
 *                changes or wordwrap is turned on/off etc).
 *                The handler function will be passed:
 *                       i) the filename for the window title
 *                      ii) the address of this 'txtedit_state'
 *                     iii) the handle registered with this function
 *                If the handler returns FALSE, then the last modification
 *                will be undone.  This is only possible if the modification
 *                is not greater than ~5kb.
 *                Calling with h == 0 removes the handler.
 *
 *)
procedure txtedit_register_update_handler(h : txtedit_update_handler;
                handle : pointer) : txtedit_update_handler; extern;


(* ------------------------ txtedit_register_save_handler ------------------
 * Description:   Register a handler to be called when a text window is 
 *                saved
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    This routine will be called whenever a text window is saved
 *                to file (NOT via RAM transfer).
 *                The handler function will be passed:
 *                       i) the filename for the window title
 *                      ii) the address of this 'txtedit_state'
 *                     iii) the handle registered with this function
 *                Calling with h == 0 removes the handler.
 *                Returning FALSE from your handler will abort the save
 *                operation.
 *
 *)
procedure txtedit_register_save_handler(h : txtedit_save_handler;
                handle : pointer) : txtedit_save_handler; extern;


(* ------------------------ txtedit_register_close_handler ----------------
 * Description:   Register a handler to be called when a modified text 
 *                window is closed
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    This routine will be called whenever a text
 *                window is closed.
 *                The handler function will be passed:
 *                       i) the filename for the window title
 *                      ii) the address of this 'txtedit_state'
 *                     iii) the handle registered with this function
 *                Calling with h == 0 removes the handler.
 *
 *)
procedure txtedit_register_close_handler(h : txtedit_close_handler;
                handle : pointer) : txtedit_close_handler; extern;

(* ------------------------ txtedit_register_shutdown_handler --------------
 * Description:   Register a handler to be called when txtedit_prequit() is
 *                called. 
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    This routine will be called whenever txtedit_prequit() is
 *                called, and the user answers "yes" when asked if he really
 *                wants to quit edit, or no files have been modified.
 *                The handler function will be passed the handle
 *                registered with this function
 *                Calling with h == 0 removes the handler.
 *
 *)
procedure txtedit_register_shutdown_handler(h : txtedit_shutdown_handler;
                handle : pointer) : txtedit_shutdown_handler; extern;

(* ------------------------ txtedit_register_undofail_handler --------------
 * Description:   Register a handler to be called when your update_handler
 *                returned FALSE, and the undo buffer overflowed. 
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    This will be called when the modification made to an
 *                edited file cannot be undone (only in conjunction with
 *                an update handler).
 *                The handler function will be passed:
 *                       i) the filename for the window title
 *                      ii) the address of this 'txtedit_state'
 *                     iii) the handle registered with this function
 *                Calling with h == 0 removes the handler.
 *
 *)
procedure txtedit_register_undofail_handler(h : txtedit_undofail_handler;
                handle : pointer) : txtedit_undofail_handler; extern;

(* ----------------------- txtedit_register_open_handler -------------------
 * Description:   Register a handler to be called when a new txtedit_state is
 *                created. 
 *
 * Parameters:    txtedit_handler h -- the handler function
 *                void *handle      -- handle to be passed to the function
 * Returns:       previous handler
 * Other Info:    The handler function will be passed:
 *                       i) the filename for the window title
 *                      ii) the address of this 'txtedit_state'
 *                     iii) the handle registered with this function
 *                Calling with h == 0 removes the handler.
 *
 *)
procedure txtedit_register_open_handler(h : txtedit_open_handler;
                handle : pointer) : txtedit_open_handler; extern;

(* ---------------------------- txtedit_getstates --------------------------
 * Description:   Get a pointer to the list of current txtedit_states
 *
 * Parameters:    void.
 * Returns:       Pointer to the list of txtedit_states
 * Other Info:    The txtedit part of RISC_OSlib keeps a list of all
 *                txtedit_states created (via txtedit_new). This function
 *                allows access to this list
 *
 *)
function txtedit_getstates : txtedit_state_ptr; extern;


(* ---------------------------- txtedit_init -------------------------------
 * Description:   Initialise the txtedit module of the library
 *
 * Parameters:    void.
 * Returns:       void.
 * Other Info:    none.
 *
 *)
procedure txtedit_init; extern;

#endif

(* end txtedit.h *)
