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