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