Mercurial > hg > xemacs-beta

comparison man/lispref/glyphs.texi @ 2127:4657b5a54253

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2004-06-14 10:24:44 by stephent] Improve glyph docs <87659uxwsv.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Mon, 14 Jun 2004 10:24:45 +0000
parents 2ba4f06a264d
children c91543697b09
comparison
equal deleted inserted replaced
2126:1777d8a3b486 2127:4657b5a54253
68 68
69 @var{type} specifies the type of the glyph, which specifies in which 69 @var{type} specifies the type of the glyph, which specifies in which
70 contexts the glyph can be used, and controls the allowable image types 70 contexts the glyph can be used, and controls the allowable image types
71 into which the glyph's image can be instantiated. @var{type} should be 71 into which the glyph's image can be instantiated. @var{type} should be
72 one of @code{buffer} (used for glyphs in an extent, the modeline, the 72 one of @code{buffer} (used for glyphs in an extent, the modeline, the
73 toolbar, or elsewhere in a buffer), @code{pointer} (used for the 73 toolbar, or elsewhere in a frame), @code{pointer} (used for the
74 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults 74 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
75 to @code{buffer}. @xref{Glyph Types}. 75 to @code{buffer}. @xref{Glyph Types}.
76 76
77 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual 77 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
78 display (the XEmacs term for this is @dfn{rune}), but rather is an 78 display (the XEmacs term for this is @dfn{rune}, and runes are confined
79 to the internal implementation of redisplay), but rather is an
79 object encapsulating a graphical element, such as an image or widget (an 80 object encapsulating a graphical element, such as an image or widget (an
80 element such as a button or text field; @dfn{widget} is the term for 81 element such as a button or text entry field; @dfn{widget} is the term for
81 this under X Windows, and it's called a @dfn{control} under MS Windows). 82 this under X Windows, while @dfn{control} is the term under MS Windows).
82 This graphical element could appear in a buffer, a margin, a gutter, or 83 This graphical element could appear in a buffer, a margin, a gutter, or
83 a toolbar, or as a mouse pointer or an icon, for example. 84 a toolbar, or as a mouse pointer or an icon, for example.
84 85
85 Creating a glyph using @code{make-glyph} does not specify @emph{where} 86 Creating a glyph using @code{make-glyph} does not specify @emph{where}
86 the glyph will be used, but it does specify @emph{what} the glyph will 87 the glyph will be used, but it does specify @emph{what} the glyph will
87 look like. In particular, @var{spec-list} is used to specify this, and it's 88 look like. @var{spec-list} is used to specify this, and it is the
88 used to initialize the glyph's @code{image} property, which is an image 89 initializer for the glyph's @code{image} property, which is an image
89 specifier. (Note that @dfn{image} as used in the context of a glyph's 90 specifier. (Note that @dfn{image} as used in the context of a glyph's
90 @code{image} property or in the terms @dfn{image specifier}, @dfn{image 91 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
91 instantiator}, or @dfn{image instance} does not refer to what people 92 instantiator}, or @dfn{image instance} does not refer to what people
92 normally think of as an image (which in XEmacs is called a 93 normally think of as an image (which in XEmacs is called a
93 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or 94 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
95 The format of the @var{spec-list} is typically an image instantiator (a string 96 The format of the @var{spec-list} is typically an image instantiator (a string
96 or a vector; @ref{Image Specifiers}), but can also be a list of such 97 or a vector; @ref{Image Specifiers}), but can also be a list of such
97 instantiators (each one in turn is tried until an image is successfully 98 instantiators (each one in turn is tried until an image is successfully
98 produced), a cons of a locale (frame, buffer, etc.) and an 99 produced), a cons of a locale (frame, buffer, etc.) and an
99 instantiator, a list of such conses, or any other form accepted by 100 instantiator, a list of such conses, or any other form accepted by
100 @code{canonicalize-spec-list}. @xref{Specifiers}, for more information 101 @code{canonicalize-spec-list}.
101 about specifiers. 102
102 103 Some understanding of specifiers is necessary in working with glyphs,
103 If you're not familiar with specifiers, you should be in order to 104 because they do not behave like ordinary variables, and are accessed and
104 understand how glyphs work. The clearest introduction to specifiers 105 mutated with special APIs. @xref{Specifiers}, for more information
105 is in the Lispref manual, available under Info. (Choose 106 about specifiers. The docstring of
106 Help->Info->Info Contents on the menubar or type C-h i.) You can 107 @code{make-specifier} gives a capsule summary. The most important
107 also see @code{make-specifier} for a capsule summary. What's important to 108 aspect of specifiers is that a specifier lets you set a value for
108 keep in mind is that a specifier lets you set a different value for 109 each buffer, window, frame, device, or console, or it will compute an
109 any particular buffer, window, frame, device, or console. This allows 110 appropriate default if no specific value is set for a particular
110 for a great deal of flexibility; in particular, only one global glyph 111 @emph{locale} or @emph{domain} (display contexts; locales are used by
112 the programmer create an abstract link between an object such as a
113 buffer position and an image, while domains must be concrete enough to
114 enable XEmacs to identify the device type: you can't
115 usefully display a JPEG on stdout). Therefore only one global glyph
111 needs to exist for a particular purpose (e.g. the icon used to represent 116 needs to exist for a particular purpose (e.g. the icon used to represent
112 an iconified frame, the mouse pointer used over particular areas of a 117 an iconified frame, the mouse pointer used over particular areas of a
113 frame, etc.), and in these cases you do not create your own glyph, but 118 frame, etc.), and in these cases you do not create your own glyph, but
114 rather modify the existing one. 119 rather modify the existing one. You can specify that a given glyph
120 appear as a monochrome image on monochrome displays, a color image on
121 color displays, and as a string on TTYs.
115 122
116 As well as using @var{spec-list} to initialize the glyph, you can set 123 As well as using @var{spec-list} to initialize the glyph, you can set
117 specifications using @code{set-glyph-image}. Note that, due to a 124 specifications using @code{set-glyph-image}. Due to an
118 possibly questionable historical design decision, a glyph itself is not 125 arguable historical design decision, a glyph itself is not
119 actually a specifier, but rather is an object containing an image 126 actually a specifier, but rather is an object containing an image
120 specifier (as well as other, seldom-used properties). Therefore, you 127 specifier (as well as other, seldom-used properties). Therefore, you
121 cannot set or access specifications for the glyph's image by directly 128 cannot set or access specifications for the glyph's image by directly
122 using @code{set-specifier}, @code{specifier-instance} or the like on the 129 using @code{set-specifier}, @code{specifier-instance} or the like on the
123 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the 130 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
124 convenience functions @code{set-glyph-image}, 131 convenience functions @code{set-glyph-image},
125 @code{glyph-image-instance}, and @code{glyph-image}. 132 @code{glyph-image-instance}, and @code{glyph-image}.
126 133
127 Once you have created a glyph, you specify where it will be used as 134 Once you have created a glyph, you specify where it will be used by
128 follows: 135 attaching it to an extent as a @emph{begin-glyph} or @emph{end-glyph}.
136 There are also a number of special objects whose appearance is specified
137 by a glyph. Most of these a global objects that you update with
138 @code{set-glyph-image}, such as mouse pointers and the glyph that
139 denotes a line truncation. Frame icons, toolbar button icons, and the
140 modeline are the main non-text objects which accept glyphs as elements.
129 141
130 @itemize @bullet 142 @itemize @bullet
131 @item 143 @item
132 To insert a glyph into a buffer, create an extent in the buffer and then 144 To insert a glyph into a buffer, create an extent in the buffer and then
133 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set 145 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
141 when using margin glyphs with layout policy @code{whitespace}.) Then follow 153 when using margin glyphs with layout policy @code{whitespace}.) Then follow
142 the same procedure above for inserting a glyph in a buffer, and then 154 the same procedure above for inserting a glyph in a buffer, and then
143 set a non-default layout policy for the glyph using 155 set a non-default layout policy for the glyph using
144 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}. 156 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
145 Alternatively, use the high-level annotations API (see 157 Alternatively, use the high-level annotations API (see
146 @code{make-annotation}). (In point of fact, you can also use the annotations 158 @code{make-annotation}). (In fact, you can also use the annotations
147 API for glyphs in a buffer, by setting a layout policy of @code{text}.) 159 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
148 160
149 @item 161 @item
150 To insert a glyph into the modeline, just put the glyph directly as one 162 A glyph may be displayed in the modeline by inserting the glyph as one
151 of the modeline elements. (Unfortunately you can't currently put a begin 163 of the elements of the modeline format. (Unfortunately you can't
152 glyph or end glyph on one of the modeline extents---they're ignored.) 164 currently put a begin glyph or end glyph on one of the modeline
153 165 extents---they're ignored.)
154 @item 166
155 To insert a glyph into a toolbar, specify it as part of a toolbar 167 @item
156 instantiator (typically set on the specifier @code{default-toolbar}). 168 To insert a glyph into a toolbar, specify it as the icon part of a toolbar
157 See @code{default-toolbar} for more information. (Note that it is 169 button, which in turn must be part of a toolbar instantiator (typically
158 standard practice to use a symbol in place of the glyph list in the 170 set on the specifier @code{default-toolbar}).
159 toolbar instantiator; the symbol is evalled to get the glyph list. This 171 See @code{default-toolbar} for more information. (As a convenience, you
172 may use a symbol in place of the glyph list in the toolbar button
173 instantiator; the symbol is evalled to get the glyph list. This
160 facilitates both creating the toolbar instantiator and modifying 174 facilitates both creating the toolbar instantiator and modifying
161 individual glyphs in a toolbar later on. For example, you can change 175 individual glyphs in a toolbar later on. For example, you can change
162 the way that the Mail toolbar button looks by modifying the value of the 176 the way that the Mail toolbar button looks by modifying the value of the
163 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon}) 177 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
164 and then calling @code{(set-specifier-dirty-flag default-toolbar)}. 178 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
165 (#### Unfortunately this doesn't quite work the way it should; the 179 (#### Unfortunately this doesn't quite work the way it should; the
166 change will appear in new frames, but not existing ones. 180 change will appear in new frames, but not existing ones, because once an
167 181 image has been displayed the pixmap replaces the symbol for those domains.)
168 @item 182
169 To insert a glyph into a gutter, create or modify a gutter instantiator 183 @item
170 (typically set on the specifier @code{default-gutter}). Gutter 184 To insert a glyph into a gutter, use
171 instantiators consist of strings or lists of strings, so to insert a
172 glyph, create an extent over the string, and use
173 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a 185 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
174 glyph to be displayed at the corresponding edge of the extent, just like 186 glyph to be displayed at the corresponding edge of extent in a string,
175 for glyphs in a buffer. 187 similar to the way you insert glyphs in a buffer. Then insert the
176 188 string into the gutter @ref{Specifying a Gutter}.
177 @item 189
178 To use a glyph as the icon for a frame, you do not actually create a new 190 @item To use a glyph as the icon for a frame, you do not actually create
179 glyph; rather, you change the specifications for the existing glyph 191 a new glyph; rather, you change the specifications for the existing
180 @code{frame-icon-glyph}. (Remember that, because of the specifier nature 192 glyph @code{frame-icon-glyph}. (This is a unique, predefined object.
181 of glyphs, you can set different values for any particular buffer or 193 Remember that, because of the specifier nature of glyphs, you can set
182 frame.) 194 different values for any particular buffer or frame.)
183 195
184 @item 196 @item
185 To use a glyph as the mouse pointer, in general you do not create a new 197 To use a glyph as the mouse pointer, in general you do not create a new
186 glyph, but rather you change the specifications of various existing 198 glyph, but rather you change the specifications of various existing
187 glyphs, such as @code{text-pointer-glyph} for the pointer used over 199 glyphs, such as @code{text-pointer-glyph} for the pointer used over
188 text, @code{modeline-pointer-glyph} for the pointer used over the 200 text, @code{modeline-pointer-glyph} for the pointer used over the
189 modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of 201 modeline, etc. Do an apropos over @samp{pointer-glyph} to find all of
190 them. (Note also that you can temporarily set the mouse pointer to some 202 them. (Note also that you can temporarily set the mouse pointer to some
191 specific shape by using @code{set-frame-pointer}, which takes an image 203 specific shape by using @code{set-frame-pointer}, which takes an image
192 instance, as obtained from calling @code{glyph-image-instance} on a glyph 204 instance, as obtained from calling @code{glyph-image-instance} on a glyph
193 of type @code{pointer} -- either one of the above-mentioned variables or 205 of type @code{pointer} -- either one of the above-mentioned variables or
194 one you created yourself. (See below for what it means to create a 206 one you created yourself. (See below for what it means to create a
195 glyph of type @code{pointer}.) This pointer will last only until the 207 glyph of type @code{pointer}.) This pointer will last only until the
222 #### Note: Display tables do not currently support general Mule 234 #### Note: Display tables do not currently support general Mule
223 characters. They will be overhauled at some point to support this 235 characters. They will be overhauled at some point to support this
224 and to provide other features required under Mule. 236 and to provide other features required under Mule.
225 237
226 @item 238 @item
227 To use a glyph as the background pixmap of a face: Note that the 239 Glyphs are not actually used as the background pixmaps of faces, but the
240 API is similar. The
228 background pixmap of a face is actually an image specifier -- probably 241 background pixmap of a face is actually an image specifier -- probably
229 the only place in XEmacs where an image specifier occurs outside of a 242 the only place in XEmacs where an image specifier occurs outside of a
230 glyph. Similarly to how the glyph's image specifier works, you don't 243 glyph. If you would like to use a glyph's image as a background pixmap,
231 create your own image specifier, but rather add specifications to the 244 you can extract it with @code{glyph-image}, and then add it to a face.
232 existing one (using @code{set-face-background-pixmap-file} or 245 @xref{Face Convenience Functions}.
233 @code{set-face-background-pixmap}). Note that the image instance that is
234 generated in order to actually display the background pixmap is of type
235 @code{mono-pixmap}, meaning that it's a two-color image and the
236 foreground and background of the image get filled in with the
237 corresponding colors from the face.
238 @end itemize 246 @end itemize
239 247
240 It is extremely rare that you will ever have to specify a value for 248 It is extremely rare that you will ever have to specify a value for
241 @var{type}, which should be one of @code{buffer} (used for glyphs in an 249 @var{type}, which should be one of @code{buffer} (used for glyphs in an
242 extent, the modeline, the toolbar, or elsewhere in a buffer), 250 extent, the modeline, the toolbar, or elsewhere in a buffer),
243 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a 251 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
244 frame's icon), and defaults to @code{buffer}. The only cases where it 252 frame's icon), and defaults to @code{buffer}. The only cases where it
245 needs to be specified is when creating icon or pointer glyphs, and in 253 needs to be specified is when creating icon or pointer glyphs, and in
246 both cases the necessary glyphs have already been created at startup and 254 both cases the necessary glyphs have already been created at startup and
247 are accessed through the appropriate variables, 255 are accessed through the appropriate variables,
248 e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph}) 256 e.g. @code{text-pointer-glyph} (or in general, any @samp{*-pointer-glyph})
249 and @code{frame-icon-glyph}. @xref{Glyph Types}. 257 and @code{frame-icon-glyph}. @xref{Glyph Types}.
250 @end defun 258 @end defun
251 259
252 @defun make-glyph-internal &optional type 260 @defun make-glyph-internal &optional type
253 This function creates a new, uninitialized glyph of type @var{type}. 261 This function creates a new, uninitialized glyph of type @var{type}.
270 @var{spec-list}. This function is equivalent to calling 278 @var{spec-list}. This function is equivalent to calling
271 @code{make-glyph} with a @var{type} of @code{icon}. 279 @code{make-glyph} with a @var{type} of @code{icon}.
272 280
273 It is extremely unlikely that you will ever need to create a pointer 281 It is extremely unlikely that you will ever need to create a pointer
274 glyph. Instead, you probably want to be calling @code{set-glyph-image} 282 glyph. Instead, you probably want to be calling @code{set-glyph-image}
275 on an existing glyph, e.g. @code{text-pointer-glyph}. 283 on the existing glyph, @code{frame-icon-glyph}.
276 @end defun 284 @end defun
277 285
278 @node Glyph Properties 286 @node Glyph Properties
279 @subsection Glyph Properties 287 @subsection Glyph Properties
280 288