XFACES(1)XFACES(1)NAMExfaces - mail image display for X
SYNOPSISxfaces [-toolkitoption ...] [-option ...]
DESCRIPTION
XFaces version 3.0 is a program that will display an image
and optionally play a sound for each piece of mail in your
mail box. Additionaly, you can have a shell command exe-
cuted. This lets you know at a glance (or a listen, or a
whatever) who you have mail from. XFaces starts out (when
you have no mail) looking like a color xbiff. As you
receive mail XFaces becomes a column (or a number of
columns) of mail icons.
XFaces can also be used to monitor other lists using the
-e option or the listCommand resource.
OPTIONS
Xfaces accepts all of the standard X Toolkit command line
options as well as the following options designed to be
compatible with Rich Burridge's faces program:
-c <columns>
Specify the number of images that faces will allow
before starting a new row. This is also available
as resource XFaces.frame.maxWidth.
-e <command>
Run <command> and use output for faces list. This
is also available as XFaces.listCommand.
-f <facedb path>
This option set the default facedb search path to
the colon separated list of directories specified
in <facedb path>. Also available as resource
XFaces.facedbPath.
-h <image height>
This option sets the height used internally by
XFaces to layout images in a tiled fashion. This
is also available as the resource
XFaces.frame.tileHeight.
-p <update time>
Specify the amount of time to wait between checks
for new mail. Also available as resource
XFaces.update.
-s <spool file>
This option specifies an alternate mail spool file
to watch. Also available as XFaces.spoolFile.
1
XFACES(1)XFACES(1)-w <image width>
This option sets the width used internally by
XFaces to layout images in a tiled fashion. This
is also available as the resource
XFaces.frame.tileWidth.
-C This option disables image compression. Image
compression is used to only show a particular
image only once in the display. Also available as
resource XFaces.compressImages.
-K This option insists that the order of the images
in the display reflect the order of the images in
the spool file or those returned by a <command>.
Also available as resource XFaces.keepOrder.
-S This option says not to shape extra space added to
images that are smaller than the tile size.
-pop <hostname>
This option specifies the host name to use for a
POP3 mailbox. Also available as XFaces.popHost.
X DEFAULTS
The application class name is XFaces. For best results
the following Shell resource is suggested:
XFaces.allowShellResize: True
This will allow the XFaces window to resize to be
the exact size that is required for the current
images.
This program uses a very simple tiled layout widget to
layout the images. Each image is displayed in an Athena
Label widget. The name of the layout widget is frame and
the following resources are available:
XFaces.frame.tileWidth: <tile width>
This resource specifies the width of the children
that the Tiled widget is to manage. This size is
enforced. The default is 64
XFaces.frame.tileHeight: <tile height>
This resource specifies the height of the children
that the Tiled widget is to manage. This size is
enforced. The default is 64.
XFaces.frame.setWidth: <force width>
This resource forces the width of the Tiled widget
to be <width> tiles wide. If the value is zero
then no width is forced. The default is 0.
2
XFACES(1)XFACES(1)
XFaces.frame.setHeight: <force height>
This resource forces the height of the Tiled wid-
get to be <height> tiles wide. If the value is
zero then no height is forced. The default is 0.
XFaces.frame.minWidth: <minimum width>
This resource specifies the minimum width in tiles
that the Tiled widget is allowed. If the value is
zero then there is no minimum. The default is 0.
XFaces.frame.minHeight: <minimum height>
This resource specifies the minimum height in
tiles that the Tiled widget is allowed. If the
value is zero then there is no minimum. The
default is 0.
XFaces.frame.maxWidth: <maximum width>
This resource specifies the maximum width in tiles
that the Tiled widget is allowed. If the value is
zero then there is no maximum. The default is 0.
Note that since the Tiled widget lays out its
children in row major order a value of 0 creates a
horizontal list of images. If the value is speci-
fied as 1 a vertical list is created.
XFaces.frame.maxHeight: <maximum height>
This resource specifies the maximum height in
tiles that the Tiled widget is allowed. If the
value is zero then there is no maximum. The
default is 0.
XFaces.frame.vertSpacing: <spacing>
This resource specifies the spacing in pixels that
the Tiled widget places vertically between chil-
dren.
XFaces.frame.horizSpacing
This resource specifies the spacing in pixels that
the Tiled widget places horizontally between chil-
dren.
XFaces.frame.internalWidth
This resource specifies the spacing in pixels that
the Tiled widget places horizontally between its
borders and its children.
XFaces.frame.internalHeight
This resource specifies the spacing in pixels that
the Tiled widget places vertically between its
borders and its children.
Note: If you have specified a border width for the
children of the Tiled widget that is non zero then
you should specify the following resource values to
3
XFACES(1)XFACES(1)
be at least two times the border width specified
for the children:
o vertSpacing
o horizSpacing
o internalWidth
o internalHeight
XFaces also introduces the following application
resources:
XFaces.spoolFile: <mail spool file>
This can be used to specify the mail spool file to
watch. The default is to append the users name
onto the spoolDir resource.
XFaces.spoolDir: <mail spool directory>
This resource specifies the directory that con-
tains user mail spool files. The default is
/usr/spool/mail. On some machines (SVR4?) you
may want to set this to /usr/mail.
XFaces.popHost: <hostname>
This resource specifies the name of a host to con-
tact for a POP3 mailbox. Note that in order for
this to work you need to create a file called
.popauth in your home directory. The file needs
to contain one line that contains your pop host
login id followed by white space followed by your
pop host password. Since this file contains a
clear text password it is not the most secure
method. I currently do not have access to a pop
server that supports any other type of authentica-
tion.
XFaces.popPort: <port number>
This specifies what port number to use for POP.
The default is the standard POP3 port 110.
XFaces.listCommand:<usercommand>
This resource specifies a user command that will
be executed instead of looking at the spool file.
If this resource is specified then value specified
in the spoolFile is ignored. See the USER COM-
MANDS section for a description of the data format
that XFaces expects from user commands.
XFaces.imagePath: <image path>
This resource specifies a colon-separated list of
directories that specify the default directories
to use for image files. The default is
/usr/images.
4
XFACES(1)XFACES(1)
XFaces.soundPath: <sound path>
This resource specifies a colon-separated list of
directories that specify the default directories
to use for sound files. The default is
/usr/sounds.
XFaces.facedbPath: <facedb path>
This is a list of directories that contain a
multi-level directory hierarchy. The first few
levels are the host name where each part of the
host name is a new directory level. Inside this is
another directory using the users name. And
finally, inside of this directory are the actual
image and sound files for this user. The root of
the face (for images and for sounds) is face.
This file can be in any of the supported
image/sound formats. See the description of the
facedb search type under the imageSearch resource.
XFaces.machine: <machine file>
This resource specifies the name of a file that is
used to alias machine names. Each facedb tree is
allowed to contain one of these. The default is
machine.tab. Any blank lines and lines starting
with the # character are ignored. All other lines
are expected to look like:
old.host.name=new.name
XFaces.people: <people file>
This resource specifies the name of a file that is
used to alias user names for specific hosts. Each
facedb tree is allowed to contain
one of these. The default is people.tab. Any
blank lines and lines starting with the # charac-
ter are ignored. All other lines are expected to
look like:
host.name/olduser=newuser
XFaces.update: <update time>
How often to check for new mail in seconds. The
default is 60.
XFaces.volume:
The volume at which to play sounds. The default is
33.
XFaces.fromField:
This resource specifies which mail header to use
as the from header. The default is the old uucp
"From_" header. (the _ is really a space charac-
ter)
5
XFACES(1)XFACES(1)
XFaces.noMailImage: <empty image>
The image to use when you have no mail. The
default is "nomail". The imagePath is used to
locate this file.
XFaces.noMailSound: <empty sound>
The sound to use when you have no mail. The
default not to play a sound with no mail. The
soundPath is used to locate this sound.
XFaces.lookupHostname: <flag>
If this resource is True then the host name part
of the from address will be looked up and trans-
lated to the real hostname. The default value is
False.
XFaces.keepOrder: <flag>
This boolean resource controls the image ordering
in faces. For performance reasons the default is
False. When scripts are being run you will usu-
ally want to specify this as True.
XFaces.compressImages: <flag>
Only show each image once in the image display.
The default is True. When scripts are being run
you will usually want to specify this as False.
XFaces.useSound: <flag>
Play sounds. The default is True. A user can
disable sounds for his XFaces by setting this
resource to False in his resources.
XFaces.useShape: <flag>
Use shaped images if available. This will also
cause the background of the XFaces main window to
become transparent where there is no image. This
defaults to True.
XFaces.useCommands: <flag>
This resource tells FIXFaces if it needs to search
for shell commands to run in addition to image and
sounds. The default is False.
XFaces.useContentLength: <flag>
This resource enable code to use a Content-Length:
mail header to specify how large the mail body is.
After the headers this many bytes are skiped.
XFaces.shapeBorders: <flag>
This resource, when set to True will cause the
borders of the Label widgets to be shaped out.
The default is True.
6
XFACES(1)XFACES(1)
XFaces.shapeInternal: <flag>
This resource when set to True will cause the
internal width and height margins of the Label
widgets to be shaped out. The default is True.
XFaces.closeness: <closeness value>
This resource controls how close a color must come
to the actual color for the XPM library to accept
it. The default is 40000.
XFaces.imageTypes: <image type list>
This resource specifies the default image types
that are used to attempt to load an image file.
The list also specifies the order the types are
attempted. Valid types are:
xpm-shaped
This is a shaped color image. Shaped xpm
files should be named face-shaped.xpm.
xpm This is a non shaped color image. These
files should be named face.xpm.
xbm-shaped
This a an monochrome shaped image. The
image file and mask are stored in separate
files called face-shape.xbm for the image
data and face-shape.xbm-mask for the shape
mask.
xbm This is a non shaped monochrome image.
These files should be called face.xbm.
the default value for this resource is:
xpm-shape:xpm:xbm-shape:xbm
XFaces.imageSearch: <search specs>
XFaces.soundSearch: <search specs>
XFaces.commandSearch: <search specs>
These resources have complete control of the
search type , image types for images and path
arguments for locating images, sounds and com-
mands. The search spec is a multi line resource.
Each line represents a new search. Each line is
constructed as follows:
<search type> [<format list> [<search path>]]
The <format list> is currently ignored for the
soundSearch resource. Both the <format list> and
the <search path> are (except if you use the
7
XFACES(1)XFACES(1)
facedb search) for the commandSearch resoiurce.
If the <format list> is empty then the list in the
imageFormats resource is used. If the <search
path> is empty then the facedbPath is used for
facedb searches for both sounds and images and one
of the soundPath or imagePath is used for the
other search types.
The valid search types are:
beforeImage
The beforeImageBindings resource is used
as a set of regular expression to match
lines in the mail header. beforeSound The
beforeSoundBindings resource is used as a
set of regular expression to match lines
in the mail header. beforeCommand The
beforeCommandBindings resource is used as
a set of regular expression to match lines
in the mail header.
resource
The user name and host name are looked up
in the X resources for a match. The
resources attempted are:
XFaces.<type>.user@host
XFaces.<type>.user
XFaces.<type>.host
Where type is one of: image, sound, command.
u@h The user name and host name is combined
and looked for as a file name. The names
attempted are:
[path]user@host
[path]user
[path]host
facedb This is the search that is used in Rich
Burridge's faces program. The search
attempts the following for the address
liebman@zod.clark.net:
[path]/net/clark/zod/liebman
[path]/net/clark/zod/liebman/face
[path]/net/clark/liebman
[path]/net/clark/liebman/face
[path]/net/liebman
[path]/net/liebman/face
[path]/MISC/liebman
[path]/MISC/liebman/face
[path]/net/clark/zod/unknown
[path]/net/clark/zod/unknown/face
8
XFACES(1)XFACES(1)
[path]/net/clark/unknown
[path]/net/clark/unknown/face
[path]/net/unknown
[path]/net/unknown/face
[path]/MISC/unknown
[path]/MISC/unknown/face
x-face This looks for an X-Face: header and
extracts a 48 pixel by 48 pixel monochrome
image.
afterImage
The afterImageBindings resource is used as
a set of regular expression to match lines
in the mail header.
afterSound
The afterSoundBindings resource is used as
a set of regular expression to match lines
in the mail header.
afterImage
The afterCommandBindings resource is used
as a set of regular expression to match
lines in the mail header.
The default value of the imageSearch resource is:
beforeImage\n\
resource\n\
facedb\n\
x-face\n\
afterImage
The default value of the soundSearch resource is:
beforeImage\n\
resource\n\
facedb\n\
afterImage
The default value of the commandSearch resource
is:
beforeImage\n\
resource\n\
afterImage
XFaces.beforeImageBindings: <spec>
XFaces.afterImageBindings: <spec>
XFaces.beforeSoundBindings: <spec>
XFaces.afterSoundBindings: <spec>
XFaces.beforeCommandBindings: <spec>
9
XFACES(1)XFACES(1)
XFaces.afterCommandBindings: <spec>
These resources specify regular expressions that
can be matched against the mail headers to locate
an image or sound. These are multi-line
resources. Each line is constructed as:
<field name> <regexp><:> <file>
<label><:><anno>
If the <field name> is specified as * then all headers are
tested. If the <field name> begins with a (like Subject:
or *) then the search is case insensitive. The <label>
field is only used for image and if specified, it will be
used in the annotations at position <anno> if <anno> is
not supplied then it defaults to 1.
XFaces.ignoreMessageBindings:
These resources specify regular expressions that
can be matched against the mail headers to locate
an image or sound. These are multi-line
resources. Each line is constructed as:
<field name> <regexp>
If the field name is specified as * then all headers are
tested. Any match found will cause the message to be
ignored, no sound, no image, no nothing!
XFaces.annotationCount: <number of annotations>
XFaces.unknownAnnotationCount: <number of annotations>
This resource specifies the number of annotations
that the user is specifing. The unknown annota-
tions are applied on faces that were located via
the facedb search when substituting "unknown" for
the user name. For each annotation the following
resources will be retrieved where N runs from 1 to
annotationCount (or unknownAnnotationCount)
XFaces.annotationN.x: <x>
XFaces.unknownAnnotationN.x: <x>
If <x> is a positive number then it is the
offset from the left side of the image to
the left side of the text. If <x>P is a
negative number then it is the offset from
the right side of the image to the right
side of the text.
XFaces.annotationN.y: <y>
XFaces.unknownAnnotationN.y: <y>
If <y> is a positive number then it is the
offset from the top of the image to the
top of the text. If <y>P is a negative
number then it is the offset from the
10
XFACES(1)XFACES(1)
bottom of the image to the bottom of the
text.
XFaces.annotationN.maxWidth: <width>
XFaces.unknownAnnotationN.maxWidth: <width>
This specifies the maximum width in pixels
the text is allowed to be.
XFaces.annotationN.font: <font name>
XFaces.unknownAnnotationN.font: <font name>
This is the font to use to render the
annotation.
XFaces.annotationN.foreground: <X color spec>
XFaces.unknownAnnotationN.foreground: <X color
spec>
This is the foreground color for the anno-
tation.
XFaces.annotationN.background: <X color spec>
XFaces.unknownAnnotationN.background: <X color
spec>
This is the background color for the anno-
tation.
XFaces.annotationN.shapeText: <flag>
XFaces.unknownAnnotationN.shapeText: <flag>
If true then the text itself is used as
the shape mask, if false then the shape
mask is a filled rectangle with extents
matching those of the text. The default is
False.
XFaces.annotationN.opaqueText: <flag>
XFaces.unknownAnnotationN.opaqueText: <flag>
If true then the text background is drawn
too (the background is the bounding filled
rectangle, when false only the text is
drawn. The default is True.
XFaces.mail.annotationN: <type>
XFaces.mail.unknownAnnotationN: <type>
This specifies what is to be placed into this
annotation position for mail items. The values
for type are:
none An empty string.
11
XFACES(1)XFACES(1)
user The user part of the From address.
host The host part of the From address.
user@host The user and host parts of the From address.
count The number of messages represented by this
face.
*<header> Any value beginning with a '*' is expected to
be a header name and the contents of that
header will be displayed. For instance "*sub-
ject:" will display the subject line.
XFaces.annotationAbove: <flag>
This really should be called something else! Any-
way, when this resource is true and the image
found is smaller than the tile size the extra
space allocated will be placed on teh top instead
of the bottom. The default value is False.
XFaces.background: <color>
This is the color of any extra image space allo-
cated.
XFaces.shapeExtra: <flag>
This, if true, will cause any extra image space
allocated to be shaped out.
XFaces.xbm.foreground: <color>
This is the foreground color for loaded X bitmaps.
XFaces.xbm.background: <color>
This is the background color for loaded X bitmaps.
XFaces.xpm.noneColor: <color>
This is the color used to represent the transpar-
ent pixels when the overrideNoneColor is True.
XFaces.xpm.overrideNoneColor: <flag>
When this value is set to true the transparent
pixels in a Xpm image are replaced bu the color
specified in the noneColor resource. The default
value is False.
XFaces.xpm.filterCount: <count>
This resource specifies the number of external
filters to look for. The filters are specified
with the following resources:
XFaces.xpmFilterN.name: <name>
This is the image type name used to refer
to this filter. It can be used in the
imageType resource and anywhere else an
12
XFACES(1)XFACES(1)
image type name is expected.
XFaces.xpmFilterN.filter: <command>
This is the command that will produce an
xpm file on stdout. This could be some-
thing like: "giftopnm %s | ppmtoxpm". A
single %s will be replaced by the file
name of the image to be loaded.
XFaces.xpmFilterN.extension: <entension>
This is the file extension that the image
file is expected to have.
USER COMMANDS
These commands add a very powerful feature to XFaces. They
allow almost anything to be monitored visually and audi-
bly. When a value is specified for the listCommand
resource XFaces will run the command and read the commands
standard output. The following is expected.
The first line consists of two tokens. The first
is expected to be a user name and the second a host
name. They are intended to describe the image that
should be displayed by XFaces in an iconic state.
Note: This is currently not implemented though the
line is still expected.
The second line is expected as
Cols=<columns> Rows=<rows>
where <columns> is the number of columns and <rows> that
faces should display. These values are used to set the
setWidth and setHeight resources on the Tiled layout wid-
get.
Each line following is expected to contain two to
six TAB separated fields. The fields are: user,
host, annotation1, annotation2, annotation3, anno-
tation4. See the annotationCount resource to see
how to specify how and where each of the annota-
tions are displayed.
Steve Kinzler maintains a distribution of scripts that can
be used to generate faces lists in cs.indi-
ana.edu:pub/faces/scripts.tar.Z.
SEE ALSOmail(1), sendmail(8)AUTHOR
Christopher B. Liebman (liebman@zod.clark.net)
ACKNOWLEDGEMENTS
Special thanks to Rich Burridge. A lot of the concepts
that now exist in XFaces came from faces first.
13
XFACES(1)XFACES(1)
Thanks also go to James Ashton for the X-Faces header face
compression / decompression code.
14
