<html>
<head>
<title>Output Functions</title>
<link rel="stylesheet" type="text/css" href="doc.css"
title="Documentation Standard Style">
</head>
<body bgcolor="#ffffff">
<table class="main" width="600" border="0">
<tr><td>
<div align="right">
DalekenMUD 1.12 documentation.
<br>Updated 7 June 2000.
<br>Based on original Envy 2.2 documentation.
</div>
</td></tr>
<tr><th class="heading">
<h1>Output Functions</h1>
</th></tr>
<tr><td>
<p>This document covers the main functions for sending information to a
character. The central output functions are <code>send_to_char</code>,
<code>send_to_all_char</code>, and <code>act</code>. These functions give
all of the neccessary flexibility in sending text to a player.</p>
</td></tr>
<tr><th class="heading">
<h2>send_to_char</h2>
</th></tr>
<tr><td>
<p>The interface for <code>send_to_char</code> is:
<blockquote><code>
void send_to_char( const char *txt, CHAR_DATA *ch )
</code></blockquote>
The string <code>txt</code> is sent to the character <code>ch</code>. Note
that you will have to send the character an end-of-line sequence as well such
as <code>"\n\r"</code>.</p>
</td></tr>
<tr><th class="heading">
<h2>send_to_all_char</h2>
</th></tr>
<tr><td>
<p>The function <code>send_to_all_char</code> does away with multiple blocks of
code in sending to all active descriptors. This is useful for functions like
system warnings and echos.</p>
<p>The interface for <code>send_to_all_char</code> is:
<blockquote><code>
void send_to_all_char( const char *text )
</code></blockquote>
The string <code>text</code> is sent to all characters with active descriptors.</p>
</td></tr>
<tr><th class="heading">
<h2>charprintf</h2>
</th></tr>
<tr><td>
<p>The interface for <code>charprintf</code> is:
<blockquote><code>
void send_to_char( CHAR_DATA *ch, const char *txt, ... )
</code></blockquote>
This function operates much like the <code>send_to_char</code> function but
it allows you to use a <code>printf</code> style format. This removes the
need for calls to <code>sprintf</code> and the need for buffer strings.
</td></tr>
<tr><th class="heading">
<h2>act</h2>
</th></tr>
<tr><td>
<p>The function <code>act</code> is much hairier. The following section is a
precise reference guide. If you don't already have some notion of what
<code>act</code> format strings look like, then you should read some code
which uses <code>act</code> (such as some of the spell functions in magic.c)
to get a concrete introduction to this function.</p>
<blockquote><code>
void act( const char *format, CHAR_DATA *ch, const void *arg1,
const void *arg2, int type )
</code></blockquote>
<dl>
<dt><code>const char *format;</code></dt>
<dd>
This is a format string, with formatting specifications introduced by
<code>$</code> (just as <code>printf</code> introduces its formatting
sequences with <code>%</code>). Typically this is a complete sentence with a
subject and an object. This format string does not need to be terminated
with <code>"\n\r"</code>.
</dd>
<dt><code>CHAR_DATA *ch;</code></dt>
<dd>
This is the subject of the sentence. It MUST be included.
</dd>
<dt><code>const void *arg1;</code></dt>
<dd>
This is usually the object of the sentence, though its meaning will depend on
what you want to print out. This may be an object or possibly a text string.
</dd>
<dt><code>const void *arg2;</code></dt>
<dd>
This is the target of the sentence, as well as possibly the object of the
sentence. This may be either a victim, an object, or possibly a text string.
</dd>
<dt><code>int type;</code></dt>
<dd>
This is the 'to' type of the sentence. For 'act', values are:
<div align="center"><table width="100%" cellspacing="2" cellpadding="2">
<tr>
<td width="30%"><code>TO_CHAR</code></td>
<td>Send only to <code>ch</code>.</td>
</tr>
<tr>
<td width="30%"><code>TO_VICT</code></td>
<td>Send only to <code>arg2</code> interpreted as a character
(and then only if arg2 != ch).</td>
</tr>
<tr>
<td width="30%"><code>TO_ROOM</code></td>
<td>Send to all chars in room except <code>ch</code>.</td>
</tr>
<tr>
<td width="30%"><code>TO_NOTVICT</code></td>
<td>Send to all chars in room except <code>ch</code> and <code>arg2</code>.</td>
</tr>
<tr>
<td width="30%"><code>TO_ALL</code></td>
<td>Send to all chars in the room.</td>
</tr>
</table></div>
</dd>
</dl>
<p>In <code>act</code>, only characters in the same room as <code>ch</code>
are considered. (Thus <code>ch</code> must always be a legitimate character
whose location is not NOWHERE). If the target character meets the
<code>type</code> requirements, then the formatting string
<code>format</code> is used to construct an output string, with
<code>$</code> sequences substituted using values from <code>ch</code>,
<code>arg1</code>, and <code>arg2</code>. If the target characters of the
message are asleep then they will get the message, but other characters have
to be awake to receive the message.</p>
<p>In the substitution of <code>$</code> sequences, attention is paid to
visibility by calling <code>can_see</code> and <code>can_see_obj</code> as
needed.</p>
<p>The first character of the output string is always capitalized.</p>
</td></tr>
<tr><th class="heading">
<h2>The '$' sequences</h2>
</th></tr>
<tr><td>
Here are all the <code>$</code> sequences supported by 'act':
<dl>
<dt><code>$t</code></dt>
<dd>Result is simply the <code>arg1</code> argument interpreted as a string.</dd>
<dt><code>$T</code></dt>
<dd>
Result is simply the <code>arg2</code> argument interpreted as a string.
</dd>
<dt><code>$a</code></dt>
<dd>
Result is 'a' or 'an' depending on the first letter of <code>arg1</code>
(interpreted as a string). If you can't use $t, you can't use $a.
</dd>
<dt><code>$A</code></dt>
<dd>
Result is 'a' or 'an' depending on the first letter of <code>arg2</code>
(interpreted as a string). If you can't use $T, you can't use $A.
</dd>
<dt><code>$n</code></dt>
<dd>
Result is the name of <code>ch</code>. If <code>ch</code> is not visible to
the target character, result is the string 'someone'.
</dd>
<dt><code>$N</code></dt>
<dd>
Result is the name of <code>arg2</code> (considered as a victim). If
<code>arg2</code> is not visible to the target character, result is the
string 'someone'.
</dd>
<dt><code>$e</code></dt>
<dd>
Result is 'he', 'she', or 'it', depending on the sex of <code>ch</code>.
</dd>
<dt><code>$E</code></dt>
<dd>
Result is 'he', 'she', or 'it', depending on the sex of <code>arg2</code>
(considered as a victim).
</dd>
<dt><code>$m</code></dt>
<dd>
Result is 'him', 'her', or 'it', depending on the sex of <code>ch</code>.
</dd>
<dt><code>$M</code></dt>
<dd>
Result is 'him', 'her', or 'it', depending on the sex of <code>arg2</code>
(considered as a victim).
</dd>
<dt><code>$s</code></dt>
<dd>
Result is 'his', 'her', or 'its', depending on the sex of <code>ch</code>.
</dd>
<dt><code>$S</code></dt>
<dd>
Result is 'his', 'her', or 'its', depending on the sex of <code>arg2</code>
(considered as a victim).
</dd>
<dt><code>$r</code></dt>
<dd>
Result is 'sir', 'madam', or 'buddy', depending on the sex of <code>ch</code>.
</dd>
<dt><code>$R</code></dt>
<dd>
Result is 'sir', 'madam', or 'buddy', depending on the sex of <code>arg2</code>
(considered as a victim).
</dd>
</dd>
<dt><code>$g</code></dt>
<dd>
Result is the deity of <code>ch</code>s religion if they follow a religion, otherwise
"God".
</dd>
<dt><code>$G</code></dt>
<dd>
Result is the deity of <code>arg2</code>s religion if they follow a religion, otherwise
"God".
</dd>
<dt><code>$p</code></dt>
<dd>
Result is the short description of <code>arg1</code>, considered as an
object. If <code>arg1</code> is invisible to the target character, result is
the string 'something'.
</dd>
<dt><code>$P</code></dt>
<dd>
Result is the short description of <code>arg2</code>, considered as an
object. If <code>arg2</code> is invisible to the target character, result is
the string 'something'.
</dd>
<dt><code>$d</code></dt>
<dd>
Result is the first word in <code>arg2</code>, considered as a string. If
'vo' is <code>NULL</code>, result is the string 'door'. This is meant for
extracting the name from a door's keyword list, but may be used in general
for other keyword lists.
</dd>
</dl>
</td></tr>
</table>
</body>
</html>
