/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* This source file was written by Acorn Computers Limited. It is part of *
* the RISCOS library for writing applications in C for RISC OS. It may be *
* used freely in the creation of programs for Archimedes. It should be *
* used with Acorn's C Compiler Release 3 or later. *
* *
***************************************************************************/
/*
* 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
#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif
/****************************** DATA TYPES *********************************/
typedef enum
{
txtedit_CHARSEL = 1, txtedit_WORDSEL = 2, txtedit_LINESEL = 4
} txtedit_seltype;
typedef struct txtedit_state
{
txt t;
txt_marker selpivot; /* used in mouse op calculations */
txtedit_seltype seltype; /* used in mouse op calculations */
int selectrecent; /* used in mouse op calculations */
int selectctl; /* used in mouse op calculations */
char filename[256];
typdat ty;
int deletepending;
struct txtedit_state *next; /* chain of all of them. */
BOOL overwrite;
BOOL wordtab;
BOOL wordwrap;
} txtedit_state;
typedef BOOL (*txtedit_update_handler)(char *, txtedit_state *, void *);
typedef void (*txtedit_close_handler)(char *, txtedit_state *, void *);
typedef BOOL (*txtedit_save_handler)(char *, txtedit_state *, void *);
typedef void (*txtedit_shutdown_handler)(void *);
typedef void (*txtedit_undofail_handler)(char *, txtedit_state *, void *);
typedef void (*txtedit_open_handler)(char *, txtedit_state *, void *);
/**************************** 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.
*
*/
txtedit_state *txtedit_install(txt t);
/* ----------------------------- 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.
* int filetype -- filetype to be given if null filename
* 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.
*
*/
txtedit_state *txtedit_new(char *filename, int filetype);
/* ---------------------------- 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.
*
*/
void txtedit_dispose(txtedit_state *s);
/* --------------------------- 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.
*
*/
BOOL txtedit_mayquit(void);
/* ----------------------------- 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.
*
*/
void txtedit_prequit(void);
/* ---------------------------- 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.
*/
menu txtedit_menu(txtedit_state *s);
/*------------------------------ 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.
*
*/
void txtedit_menuevent(txtedit_state *s, char *hit);
/* --------------------------- 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.
*
*/
BOOL txtedit_doimport(txtedit_state *s, int filetype, int estsize);
/* ------------------------- 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.
*
*/
void txtedit_doinsertfile(txtedit_state *s, char *filename, BOOL replaceifwasnull);
/* ------------------------ txtedit_settexttitle --------------------------
* Description: Updates the text window titles to reflect the state of
* the specified text object
*
* Parameters: txtedit_state *s -- the text object
* Returns: void.
* Other Info: none.
*
*/
void txtedit_settexttitle(txtedit_state *s);
/* ------------------------ 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.
*
*/
txtedit_update_handler txtedit_register_update_handler(txtedit_update_handler h, void *handle);
/* ------------------------ 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.
*
*/
txtedit_save_handler txtedit_register_save_handler(txtedit_save_handler h,
void *handle);
/* ------------------------ 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.
*
*/
txtedit_close_handler txtedit_register_close_handler(txtedit_close_handler h,
void *handle);
/* ------------------------ 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.
*
*/
txtedit_shutdown_handler txtedit_register_shutdown_handler(txtedit_shutdown_handler h, void *handle);
/* ------------------------ 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.
*
*/
txtedit_undofail_handler txtedit_register_undofail_handler(txtedit_undofail_handler h, void *handle);
/* -------------------------- 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.
*
*/
txtedit_open_handler txtedit_register_open_handler(txtedit_open_handler h, void *handle);
/* ---------------------------- 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
*
*/
txtedit_state *txtedit_getstates(void);
/* ---------------------------- txtedit_setBASICaddresses ------------------
* Description: Initialises the internal pointers to BASIC's tokenising
* and detokenising routines. This is necessary before the
* txtedit module can tokenise and detokenise BASIC.
*
* Parameters: int tokenise -- the address of BASIC's tokeniser
* int detokenise -- the address of BASIC's detokeniser
* Returns: void.
* Other Info: These two addresses can be obtained from the short BASIC
* program inside !Edit, which sets two system variables.
*
*/
void txtedit_setBASICaddresses(int tokenise, int detokenise);
/* ---------------------------- txtedit_setBASICstrip ----------------------
* Description: Sets the internal flag to indicate whether or not line
* numbers should be stripped from BASIC files being loaded.
*
* Parameters: BOOL strip -- TRUE if line numbers should be stripped,
* else FALSE
* Returns: void.
* Other Info: none.
*
*/
void txtedit_setBASICstrip(BOOL strip);
/* ---------------------------- txtedit_setBASICincrement ------------------
* Description: Sets the increment to be used when creating line numbers.
*
* Parameters: int increment
* Returns: void.
* Other Info: none.
*
*/
void txtedit_setBASICincrement(int increment);
/* ---------------------------- txtedit_init -------------------------------
* Description: Initialise the txtedit module of the library
*
* Parameters: void.
* Returns: void.
* Other Info: none.
*
*/
void txtedit_init(void);
#endif
/* end txtedit.h */