Previous
|
Up
|
Next
|
Character Widths and Columns |
Primitives and EEL Subroutines |
Printf-style Format Strings |
Epsilon User's Manual and Reference >
Primitives and EEL Subroutines >
Display Primitives >
Displaying Status Messages
int say(char *format, ...)
int sayput(char *format, ...)
The say( ) primitive displays text in the echo area. It
takes a printf-style format string, and zero or more other
parameters, as described in Printf-style Format Strings. The
sayput( ) primitive is similar, but it positions the cursor
at the end of the string. Each returns the number of characters
displayed.
int note(char *format, ...)
int noteput(char *format, ...)
int unseen_msgs()
int unseen_msgs_time()
wait_for_unseen_msgs()
drop_pending_says()
short expire_message;
When you use the say( ), sayput( ), or error( )
primitives (error( )'s description appears in Control Flow) to display a message to the user, Epsilon ensures
that it remains on the screen long enough for the user to see it (the
see-delay variable controls just how long) by delaying future
messages. Messages that must remain on the screen for a certain
length of time are called timed messages.
The note( ) and noteput( ) primitives work like
say( ) and sayput( ), respectively, but their messages can be
overwritten immediately. These untimed messages should be used for
"status" messages that don't need to last ("95% done", for
example).
Epsilon copies the text of each timed message to the #messages#
buffer. It doesn't copy untimed messages (but see the
show_text( ) primitive below).
The unseen_msgs( ) primitive returns the number of unexpired
timed messages. When the user presses a key, and there are unseen
messages, Epsilon immediately displays the most recent message
waiting to be displayed, and discards all pending timed messages.
The unseen_msgs_time( ) primitive returns the time remaining
for the current timed message. It returns 0 if there are no timed
messages, or -1 if the current timed message has an infinite delay
(and thus won't be replaced until the user presses a key).
The wait_for_unseen_msgs( ) subroutine delays until all timed
messages have been displayed. Epsilon calls it before exiting. If
one of the messages has an infinite delay set, it displays that message
for several seconds and then returns regardless. Since only a key
press can advance past a message with an infinite delay, it also reads
and discards keys while displaying such messages.
The drop_pending_says( ) primitive makes Epsilon discard
any timed messages that have not yet been displayed. It also makes
the current message be untimed (as if it were generated by
note( ), not say( )), so that the next say( ),
note( ), or similar will appear immediately. It returns 0 if
there were no timed messages, or 1 if there were (or the current
message had not yet expired).
An EEL function sometimes needs to display some text in the echo area
that is only valid until the user performs some action. For
instance, a command that displays the number of characters in the
buffer might wish to clear that count if the user inserts or deletes
some characters. After displaying text with one of the primitives
above, an EEL function may set the expire_message variable to
1 to tell Epsilon to clear that text on the next user key.
int aside(char *format, ...)
int debug_log(char *format, ...)
The aside( ) primitive copies text to the #messages#
buffer like say( ) does, but without displaying anything on the
screen. The debug_log( ) primitive writes the given text to
Epsilon's debug log file.
int show_text(int column, int time, char *fmt, ...)
The show_text( ) primitive is the most general command for
displaying text in the echo area. Like the other display primitives,
it takes a printf-style format string, and returns the number of
characters it displayed.
When Epsilon displays text in the echo area, you can tell it to begin
at a particular column, and Epsilon will subdivide the echo area into
two sections. You can then display different messages in each area
independently of one another. When it's necessary to display a very
long message, Epsilon will combine the sections again and use the
full display width. There are never more than two sections in the
echo area.
In detail, the show_text( ) primitive tells Epsilon to begin
displaying text in the echo area at the specified column, where the
leftmost column is column 0 . Epsilon then clears the rest of
that echo area section, but doesn't modify the other section.
Whenever you specify a column greater than zero in show_text( ),
Epsilon will subdivide the echo area at that column. It will clear
any text to the right of the newly-displayed text, but not any text
to its left.
Epsilon will recombine the sections of the echo area under two
conditions: whenever you write text starting in column 0 that begins
to overwrite the next section, and whenever you write the empty
string "" at column 0 . When Epsilon recombines sections, it
erases the entire echo area before writing the new text.
Specifying a column of -1 acts just like specifying column 0 ,
making Epsilon display the text at the left margin, but it also tells
Epsilon to position the cursor right after the text.
The time says how long in hundredths of a second Epsilon must
display the message before moving on and displaying the next message,
if any. As with any timed message, when the user presses a key,
Epsilon immediately displays the last message waiting, skipping
through any pending messages. A value of 0 for time means the
message doesn't have to remain for any fixed length of time. A value
of -1 means that Epsilon may not go on to the next message until
it receives a keystroke; such messages will never time out.
Most of the other echo area display primitives are equivalent to some
form of show_text( ), as shown in the following table:
note("abc") show_text(0, 0, "abc")
say("abc") show_text(0, see_delay, "abc")
noteput("abc") show_text(-1, 0, "abc")
sayput("abc") show_text(-1, see_delay, "abc")
aside("abc") show_text(-2, 1, "abc")
Just as Epsilon copies timed messages created with say( ) or
sayput( ) to the #messages# buffer, the text from a
show_text() call will be copied if its time is nonzero. Epsilon
treats a time of 1 (hundredth of a second) the same as zero (it's
untimed), but still copies it to the #messages# buffer. A
column of -2 has a special meaning; Epsilon copies the resulting
text to the #messages# buffer if time is nonzero, but
doesn't display it at all, just like the aside( ) primitive.
delayed_say(int flags, int before, int after, char *fmt, ...)
The delayed_say( ) primitive tells Epsilon to display some text
later. It's intended for operations that may take some time. EEL
code may display a message provisionally before starting some
potentially lengthy operation, telling Epsilon to display it only
after a certain amount of time has elapsed, and then cancel the
pending message when it finishes. The message will only appear if the
operation actually took a long time.
The before parameter says how long to wait, in hundredths of a
second, before displaying the message, which is built using the
printf-style format string fmt and any following parameters. If
the resulting message is zero-length, it simply cancels any delayed
say message that has not yet been displayed.
If the before time elapses and the message hasn't been canceled,
Epsilon displays it, ensuring it isn't overwritten by a following
message for at least after hundredths of a second. Epsilon saves
the message in the #messages# buffer if after is nonzero.
If flags is 1 , Epsilon positions the cursor after the message;
otherwise it doesn't.
int mention(char *format, ...)
user char mention_delay;
The mention( ) primitive acts like sayput( ), but
displays its string only after Epsilon has paused waiting for user
input for mention_delay tenths of a second. It doesn't cause
Epsilon to wait for input, it just arranges things so that if Epsilon
does wait for input and the required delay elapses, the message is
displayed and the wait continues. Writing to the echo area with
say( ) or the like cancels any pending mention( ). By
default, mention_delay is 0 .
int muldiv(int a, int b, int c)
The muldiv( ) primitive takes its arguments and returns the
value a * b / c, performing this computation using 128-bit
arithmetic. It's useful in such tasks as showing "percentage
complete" while operating on a large buffer. Simply writing point
* 100 / size() in EEL would use 64-bit arithmetic, as EEL always
does, and on very large buffers the result could be wrong. (Previous
versions of EEL used 32-bit arithmetic, where such overflows were more
likely and this function was more useful.)
Previous
|
Up
|
Next
|
Character Widths and Columns |
Primitives and EEL Subroutines |
Printf-style Format Strings |
![](/pics/spacer.gif)
Epsilon Programmer's Editor 14.06 manual. Copyright (C) 1984, 2024 by Lugaru Software Ltd. All rights reserved.
|