EDITWIN

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

Editwin - editing windows package for STDWIN  

SYNOPSIS

#include "stdwin.h"
#include "editwin.h"

typedef struct editwin {
        WINDOW *win;
        TEXTEDIT *tp;
        char *filename;
        char saved;
} EDITWIN;

EDITWIN *ewcreate(char *filename);
EDITWIN *ewnew();
EDITWIN *ewopen();

bool ewsave(EDITWIN *ew);
bool ewsaveas(EDITWIN *ew);
bool ewsavecopy(EDITWIN *ew);
bool ewsaveall();
bool ewrevert(EDITWIN *ew);
bool ewclose(EDITWIN *ew);
bool ewcloseall();

bool ewwritefile(EDITWIN *ew, char *filename);
bool ewreadfile(EDITWIN *ew, char *filename);

bool ewevent(EDITWIN *ew, EVENT *e, int *closed_return);
void ewreplace(EDITWIN *ew, char *str);
void ewundo(EDITWIN *ew); /* Not implemented */
void ewcopy(EDITWIN *ew);
void ewpaste(EDITWIN *ew);

EDITWIN *ewfind(WINDOW *win);
int ewcount();
 

DESCRIPTION

Editwin is a package built on top of the textedit package, to ease the construction of views on text files etc. Many calls exist to make it extremely simple to respond to standard menus of File operations (New, Open..., Save, etc.) and Edit operations (Cut, Copy, Paste).

Below are descriptions of the individual functions. Note that when a reference is made to a window's contents, the entire contents of the edit buffer belonging to the window is meant, not just the part of it visible in the window.

ewcreate
If filename is a nil pointer, this call creates an ``Untitled'' edit window. Otherwise, the specified file must exist, and an edit window showing its contents is created. In both cases, the window's `saved' flag is set initially. A pointer to a newly allocated EDITWIN struct is returned. If something went wrong (e.g., insufficient memory, or an unreadable file was specified), a nil pointer is returned.
ewnew
This function can be called in response to the selection of the New menu item. It is equivalent to a call to ewcreate((char*)0).
ewopen
Call this function for the Open... menu item. It asks the user for an existing file name (using waskfile), and then calls ewcreate with that file name as parameter. It returns nil if the dialog was cancelled or ewcreate returns nil.
ewsave
Call this function for the Save menu item. If the window's contents were modified since they were last read or saved, the function attempts to save the window to its file. If the window was still ``Untitled'', the user is first asked to specify a file name. The function returns true (nonzero) if the contents were actually saved, or didn't need saving.
ewsaveas
Call this function for the Save As... menu item. It asks the user for a new file name to save the window's contents, and if the saving succeeds, sets this to be the file name to which future save operations are directed.
ewsavecopy
Call this function for the Save a Copy... menu item. Like ewsaveas, this function asks file a new file name and saves the window's contents to that file; but it does not change the file name used for future save operations.
ewsaveall
Calls ewsave for all windows. If any call returns false (zero), ewsaveall skips further calls and returns false.
ewrevert
Call this function for the Revert... menu item. It attempts to undo any changes since the window was last read or saved, by re-reading the corresponding file. If this is at all possible, the user is asked to confirm the operation first (since it may destroy valuable changes). The function returns true if the file was actually read back, or if the window was unchanged with respect to the file.
ewclose
Closes the window. If the window was changed since it was last read or saved, the user is first asked whether it should be saved, and if the answer is Yes, ewsave is called. Cancelling the dialog will prevent closing the window. Returns true if the window was actually closed.
ewcloseall
Calls ewclose for all windows. If any call returns false, ewcloseall skips further calls and returns false.
ewwritefile
Writes the contents of the edit window to the specified file. Returns true if the operation succeeded. This does not set the `saved' flag for the window (because it is used internally be ewsavecopy).
ewreadfile
Reads the contents of the given file into the edit window, discarding its previous contents. Returns true if the operation succeeded. This does set the `saved' flag for the window.
ewevent
Call this function in response to any event returned by wgetevent. If the event is a non-menu event applicable to the specified window, it is handled and the function returns true; otherwise nothing is done and the function returns false. (Menu events cannot be handled this way because the editwin package doesn't create its own menus, and thus cannot know the menu IDs or the numbers of the menu items.) If the first parameter is a nil pointer, the event is checked against any edit window; otherwise, only events applying to the given window are handled. The third parameter must be a pointer to an integer variable, which is cleared normally when an event was handled, but set to true when a window was closed as a consequence of the event (it is unchanged when the event was nbot handled at all). In the latter case, the caller should check whether any windows are still open (see ewcount), and if this is not the case, it should either exit or open a new window. This function clears a window's `saved' flag whenever its contents are modified by the event's handling.
ewreplace
Replaces the current text selection in the window by the given (null-terminated) string. This will insert text if the text selection was an insert point.
ewundo
Reserved for future extension of the package with an Undo facility.
ewcopy
Call this function for the Copy menu item. It retrieves the contents of the window's text selection, if non-null, and copies it in into the clipboard through a call to wsetclip. It beeps if the text selection is empty. (To implement the Cut menu item, call ewcopy followed by ewreplace(ew, ``'').)
ewpaste
Call this function for the Paste menu item. It retrieves the contents of the clipboard, if non-null, and pastes it into the window through a call to ewreplace. It beeps (and does not change the window's contents) if the clipboard is empty.
ewfind
Returns a pointer to the EDITWIN struct containing the given WINDOW pointer; returns nil if none exists.
ewcount
Returns the number of open edit windows.
 

EXAMPLE

The following program is a trivial but almost usable single-file text editor. Usage is ``program [file]''.

#include "stdwin.h"
#include "editwin.h"

main(argc, argv) int argc; char **argv; {
        EDITWIN *ew;
        winitnew(&argc, &argv);
        if (argc <= 1) ewnew();
        else           ewcreate(argv[1]);
        for (;;) {
                EVENT e;
                int closed;
                wgetevent(&e);
                if (ewevent(ew, &e, &b) && closed) break;
        }
        wdone();
        exit(0);
}
 

HINTS

The members of the EDITWIN data structure are explicitly intended to be accessible to the caller. Functionality which is not provided directly but which is available for plain windows or for textedit data structures can be implemented by applying it to the win or tp members. Note that the filename member, when non-nil, points to memory allocated with malloc(3).

Changes to the window's contents should preferably be made with ewreplace, since it manages the `saved' flag.

To control the text attributes used in an EDITWIN window, you can set them globally before creating the window.  

DIAGNOSTICS

Ewcreate, ewnew and ewopen return nil when the user cancelled the operation or when they could not get all the necessary memory. The save, revert, close and read/write family of functions return FALSE if the operation was canceled by the user or if the file I/O failed. Ewevent returns TRUE when it has processed the event.

Ewcreate and ewopen warn the user if a file is larger than about 30K; the textedit package was not designed to operate on big files, and may be intolerably slow.  

SEE ALSO

STDWIN documentation
textedit(3)  

AUTHOR

Guido van Rossum  

BUGS

Editwin inherits some bugs from the textedit package.
The package doesn't detect the situation where the user opens the same file twice, edits both copies, and saves them, thus losing the changes to the copy saved first.
If the height of the document gets over 32K scan lines, you are in trouble: most window systems limit coordinates to short integers.
Missing functionality: a way to specify an alternate title for an untitled window; a way to create a non-file window, which isn't saved when closed. (These should be easy to add, given the simplicity of the source.)


 

Index

NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
HINTS
DIAGNOSTICS
SEE ALSO
AUTHOR
BUGS

This document was created by man2html, using the manual pages.
Time: 09:07:09 GMT, February 14, 2025