From xemacs-m  Sun Feb  9 21:05:40 1997
Received: from venus.Sun.COM (venus.Sun.COM [192.9.25.5])
	by xemacs.org (8.8.5/8.8.5) with SMTP id VAA27466
	for <xemacs-beta@xemacs.org>; Sun, 9 Feb 1997 21:05:39 -0600 (CST)
Received: from Eng.Sun.COM ([129.146.1.25]) by venus.Sun.COM (SMI-8.6/mail.byaddr) with SMTP id TAA22551; Sun, 9 Feb 1997 19:05:07 -0800
Received: from kindra.eng.sun.com by Eng.Sun.COM (SMI-8.6/SMI-5.3)
	id TAA16930; Sun, 9 Feb 1997 19:05:06 -0800
Received: from xemacs.eng.sun.com by kindra.eng.sun.com (SMI-8.6/SMI-SVR4)
	id TAA18668; Sun, 9 Feb 1997 19:05:05 -0800
Received: by xemacs.eng.sun.com (SMI-8.6/SMI-SVR4)
	id TAA23941; Sun, 9 Feb 1997 19:05:04 -0800
Date: Sun, 9 Feb 1997 19:05:04 -0800
Message-Id: <199702100305.TAA23941@xemacs.eng.sun.com>
From: Martin Buchholz <mrb@Eng.Sun.COM>
To: pez@dwwc.com
Cc: xemacs-beta@xemacs.org
Subject: x-set-screen-icon-pixmap 
In-Reply-To: <199702100202.VAA06652@localhost.interport.net>
References: <199702100202.VAA06652@localhost.interport.net>
Reply-To: Martin Buchholz <mrb@Eng.Sun.COM>
Mime-Version: 1.0 (generated by tm-edit 7.100)
Content-Type: text/plain; charset=US-ASCII

>>>>> "Pez" == Peter Pezaris <pez@dwwc.com> writes:

Pez> I started to write a really long-winded email griping about how
Pez> FREAKING complicated it is do find out how to set the icon for a
Pez> XEmacs frame, but I'm going to leave it as an exercise to the
Pez> reader.  Start with the following code and try to remove the two
Pez> references to obsolete functions:

Pez> (x-set-screen-icon-pixmap (selected-frame) (make-pixmap "foo.xpm"))

Didn't seem all that bad....

They byte-compiler told me to do 
(set-glyph-image frame-icon-glyph ...)

Doc for set-glyph-image told me I had to find an image specification.
Other XEmacs icons are in the "etc" directory, so I just guessed and tried

(set-glyph-image frame-icon-glyph "trash.xpm")

and this worked fine.

Absolute pathnames to an xpm file also work fine.

Pez> Come back in 4 hours when you're done and let me know how much hair
Pez> you have left.

Pez> Why are things now 100 times more complicated than the simple
Pez> straight forward code above?

It's true that XEmacs sometimes seems like it has too much power, at
the expense of comprehensibility.  The current functionality is
customizable at the device-type, device, and frame level, which is
very nice.  It's true that the number of choices of image
specifications is truly scary, but the world itself is having troubles
deciding on formats for images.

Martin


  ** x-set-screen-icon-pixmap is an obsolete function; use (set-glyph-image
     frame-icon-glyph ...).


set-glyph-image: (glyph spec &optional locale tag-set how-to-add)
  -- a compiled Lisp function.
Change the image of the given glyph.

SPEC should be an instantiator (a string or vector; see
  `image-specifier-p' for a description of possible values here),
  a list of (possibly tagged) instantiators, an alist of specifications
  (each mapping a locale to an instantiator list), or an image specifier
  object.

If SPEC is an alist, LOCALE must be omitted.  If SPEC is a
  specifier object, LOCALE can be a locale, a locale type, 'all,
  or nil; see `copy-specifier' for its semantics.  Otherwise LOCALE
  specifies the locale under which the specified instantiator(s)
  will be added, and defaults to 'global.

See `set-glyph-property' for more information.


image-specifier-p: (OBJECT)
  -- a built-in function.
Return non-nil if OBJECT is an image specifier.

An image specifier is used for images (pixmaps and the like).  It is used
to describe the actual image in a glyph.  It is instanced as an image-
instance.

Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
etc.  This describes the format of the data describing the image.  The
resulting image instances also come in many types -- `mono-pixmap',
`color-pixmap', `text', `pointer', etc.  This refers to the behavior of
the image and the sorts of places it can appear. (For example, a
color-pixmap image has fixed colors specified for it, while a
mono-pixmap image comes in two unspecified shades "foreground" and
"background" that are determined from the face of the glyph or
surrounding text; a text image appears as a string of text and has an
unspecified foreground, background, and font; a pointer image behaves
like a mono-pixmap image but can only be used as a mouse pointer
[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
important to keep the distinction between image instantiator format and
image instance type in mind.  Typically, a given image instantiator
format can result in many different image instance types (for example,
`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
whereas `cursor-font' can be instanced only as `pointer'), and a
particular image instance type can be generated by many different
image instantiator formats (e.g.  `color-pixmap' can be generated by `xpm',
`gif', `jpeg', etc.).

See `make-image-instance' for a more detailed discussion of image
instance types.

An image instantiator should be a string or a vector of the form

 [FORMAT :KEYWORD VALUE ...]

i.e. a format symbol followed by zero or more alternating keyword-value
pairs.  FORMAT should be one of

'nothing
  (Don't display anything; no keywords are valid for this.
   Can only be instanced as `nothing'.)
'string
  (Display this image as a text string.  Can only be instanced
   as `text', although support for instancing as `mono-pixmap'
   should be added.)
'formatted-string
  (Display this image as a text string, with replaceable fields;
  not currently implemented.)
'xbm
  (An X bitmap; only if X support was compiled into this XEmacs.
   Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
'xpm
  (An XPM pixmap; only if XPM support was compiled into this XEmacs.
   Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.)
'xface
  (An X-Face bitmap, used to encode people's faces in e-mail messages;
  only if X-Face support was compiled into this XEmacs.  Can be
  instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
'gif
  (A GIF87 or GIF89 image; only if GIF support was compiled into this
   XEmacs.  Can be instanced as `color-pixmap'.)
'jpeg
  (A JPEG image; only if JPEG support was compiled into this XEmacs.
   Can be instanced as `color-pixmap'.)
'png
  (A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
   Can be instanced as `color-pixmap'.)
'tiff
  (A TIFF image; not currently implemented.)
'cursor-font
  (One of the standard cursor-font names, such as "watch" or
   "right_ptr" under X.  Under X, this is, more specifically, any
   of the standard cursor names from appendix B of the Xlib manual
   [also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
   On other window systems, the valid names will be specific to the
   type of window system.  Can only be instanced as `pointer'.)
'font
  (A glyph from a font; i.e. the name of a font, and glyph index into it
   of the form "FONT fontname index [[mask-font] mask-index]".
   Currently can only be instanced as `pointer', although this should
   probably be fixed.)
'subwindow
  (An embedded X window; not currently implemented.)
'autodetect
  (XEmacs tries to guess what format the data is in.  If X support
  exists, the data string will be checked to see if it names a filename.
  If so, and this filename contains XBM or XPM data, the appropriate
  sort of pixmap or pointer will be created. [This includes picking up
  any specified hotspot or associated mask file.] Otherwise, if `pointer'
  is one of the allowable image-instance types and the string names a
  valid cursor-font name, the image will be created as a pointer.
  Otherwise, the image will be displayed as text.  If no X support
  exists, the image will always be displayed as text.)
'inherit
  Inherit from the background-pixmap property of a face.

The valid keywords are:

:data
  (Inline data.  For most formats above, this should be a string.  For
  XBM images, this should be a list of three elements: width, height, and
  a string of bit data.  This keyword is not valid for instantiator
  formats `nothing' and `inherit'.)
:file
  (Data is contained in a file.  The value is the name of this file.
  If both :data and :file are specified, the image is created from
  what is specified in :data and the string in :file becomes the
  value of the `image-instance-file-name' function when applied to
  the resulting image-instance.  This keyword is not valid for
  instantiator formats `nothing', `string', `formatted-string',
  `cursor-font', `font', `autodetect', and `inherit'.)
:foreground
:background
  (For `xbm', `xface', `cursor-font', and `font'.  These keywords
  allow you to explicitly specify foreground and background colors.
  The argument should be anything acceptable to `make-color-instance'.
  This will cause what would be a `mono-pixmap' to instead be colorized
  as a two-color color-pixmap, and specifies the foreground and/or
  background colors for a pointer instead of black and white.)
:mask-data
  (For `xbm' and `xface'.  This specifies a mask to be used with the
  bitmap.  The format is a list of width, height, and bits, like for
  :data.)
:mask-file
  (For `xbm' and `xface'.  This specifies a file containing the mask data.
  If neither a mask file nor inline mask data is given for an XBM image,
  and the XBM image comes from a file, XEmacs will look for a mask file
  with the same name as the image file but with "Mask" or "msk"
  appended.  For example, if you specify the XBM file "left_ptr"
  [usually located in "/usr/include/X11/bitmaps"], the associated
  mask file "left_ptrmsk" will automatically be picked up.)
:hotspot-x
:hotspot-y
  (For `xbm' and `xface'.  These keywords specify a hotspot if the image
  is instantiated as a `pointer'.  Note that if the XBM image file
  specifies a hotspot, it will automatically be picked up if no
  explicit hotspot is given.)
:color-symbols
  (Only for `xpm'.  This specifies an alist that maps strings
  that specify symbolic color names to the actual color to be used
  for that symbolic color (in the form of a string or a color-specifier
  object).  If this is not specified, the contents of `xpm-color-symbols'
  are used to generate the alist.)
:face
  (Only for `inherit'.  This specifies the face to inherit from.)

If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
`console-type-image-conversion-list' (q.v.) for the console type of
the domain (usually a window; sometimes a frame or device) over which
the image is being instantiated.

If the instantiator specifies data from a file, the data will be read
in at the time that the instantiator is added to the image (which may
be well before when the image is actually displayed), and the
instantiator will be converted into one of the inline-data forms, with
the filename retained using a :file keyword.  This implies that the
file must exist when the instantiator is added to the image, but does
not need to exist at any other time (e.g. it may safely be a temporary
file).

