Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 454:d7a9135ec789 r21-2-42

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-42
author cvs
date Mon, 13 Aug 2007 11:40:54 +0200
parents 3d3049ae1304
children 0784d089fdc9
comparison
equal deleted inserted replaced
453:270b05afd845 454:d7a9135ec789
8732 screen images can be instantiated from a single glyph. 8732 screen images can be instantiated from a single glyph.
8733 8733
8734 Glyphs are lazily instantiated by calling one of the glyph 8734 Glyphs are lazily instantiated by calling one of the glyph
8735 functions. This usually occurs within redisplay when 8735 functions. This usually occurs within redisplay when
8736 @code{Fglyph_height} is called. Instantiation causes an image-instance 8736 @code{Fglyph_height} is called. Instantiation causes an image-instance
8737 to be created and cached. This cache is on a device basis for all glyphs 8737 to be created and cached. This cache is on a per-device basis for all glyphs
8738 except glyph-widgets, and on a window basis for glyph widgets. The 8738 except widget-glyphs, and on a per-window basis for widgets-glyphs. The
8739 caching is done by @code{image_instantiate} and is necessary because it 8739 caching is done by @code{image_instantiate} and is necessary because it
8740 is generally possible to display an image-instance in multiple 8740 is generally possible to display an image-instance in multiple
8741 domains. For instance if we create a Pixmap, we can actually display 8741 domains. For instance if we create a Pixmap, we can actually display
8742 this on multiple windows - even though we only need a single Pixmap 8742 this on multiple windows - even though we only need a single Pixmap
8743 instance to do this. If caching wasn't done then it would be necessary 8743 instance to do this. If caching wasn't done then it would be necessary
8750 cached on an XEmacs window basis. 8750 cached on an XEmacs window basis.
8751 8751
8752 Any action on a glyph first consults the cache before actually 8752 Any action on a glyph first consults the cache before actually
8753 instantiating a widget. 8753 instantiating a widget.
8754 8754
8755 @section Glyph Instantiation
8756
8757 Glyph instantiation is a hairy topic and requires some explanation. The
8758 guts of glyph instantiation is contained within
8759 @code{image_instantiate}. A glyph contains an image which is a
8760 specifier. When a glyph function - for instance @code{Fglyph_height} -
8761 asks for a property of the glyph that can only be determined from its
8762 instantiated state, then the glyph image is instantiated and an image
8763 instance created. The instantiation process is governed by the specifier
8764 code and goes through a series of steps:
8765
8766 @itemize @bullet
8767 @item
8768 Validation. Instantiation of image instances happens dynamically - often
8769 within the guts of redisplay. Thus it is often not feasible to catch
8770 instantiator errors at instantiation time. Instead the instantiator is
8771 validated at the time it is added to the image specifier. This function
8772 is defined by @code{image_validate} and at a simple level validates
8773 keyword value pairs.
8774 @item
8775 Duplication. The specifier code by default takes a copy of the
8776 instantiator. This is reasonable for most specifiers but in the case of
8777 widget-glyphs can be problematic, since some of the properties in the
8778 instantiator - for instance callbacks - could cause infinite recursion
8779 in the copying process. Thus the image code defines a function -
8780 @code{image_copy_instantiator} - which will selectively copy values.
8781 This is controlled by the way that a keyword is defined either using
8782 @code{IIFORMAT_VALID_KEYWORD} or
8783 @code{IIFORMAT_VALID_NONCOPY_KEYWORD}. Note that the image caching and
8784 redisplay code relies on instantiator copying to ensure that current and
8785 new instantiators are actually different rather than referring to the
8786 same thing.
8787 @item
8788 Normalization. Once the instantiator has been copied it must be
8789 converted into a form that is viable at instantiation time. This can
8790 involve no changes at all, but typically involves things like converting
8791 file names to the actual data. This function is defined by
8792 @code{image_going_to_add} and @code{normalize_image_instantiator}.
8793 @item
8794 Instantiation. When an image instance is actually required for display
8795 it is instantiated using @code{image_instantiate}. This involves calling
8796 instantiate methods that are specific to the type of image being
8797 instantiated.
8798 @end itemize
8799
8800 The final instantiation phase also involves a number of steps. In order
8801 to understand these we need to describe a number of concepts.
8802
8803 An image is instantiated in a @dfn{domain}, where a domain can be any
8804 one of a device, frame, window or image-instance. The domain gives the
8805 image-instance context and identity and properties that affect the
8806 appearance of the image-instance may be different for the same glyph
8807 instantiated in different domains. An example is the face used to
8808 display the image-instance.
8809
8810 Although an image is instantiated in a particular domain the
8811 instantiation domain is not necessarily the domain in which the
8812 image-instance is cached. For example a pixmap can be instantiated in a
8813 window be actually be cached on a per-device basis. The domain in which
8814 the image-instance is actually cached is called the
8815 @dfn{governing-domain}. A governing-domain is currently either a device
8816 or a window. Widget-glyphs and text-glyphs have a window as a
8817 governing-domain, all other image-instances have a device as the
8818 governing-domain. The governing domain for an image-instance is
8819 determined using the governing_domain image-instance method.
8820
8821 @section Widget-Glyphs
8822
8755 @section Widget-Glyphs in the MS-Windows Environment 8823 @section Widget-Glyphs in the MS-Windows Environment
8756 8824
8757 To Do 8825 To Do
8758 8826
8759 @section Widget-Glyphs in the X Environment 8827 @section Widget-Glyphs in the X Environment
8760 8828
8761 Widget-glyphs under X make heavy use of lwlib (@pxref{Lucid Widget 8829 Widget-glyphs under X make heavy use of lwlib (@pxref{Lucid Widget
8762 Library}) for manipulating the native toolkit objects. This is primarily 8830 Library}) for manipulating the native toolkit objects. This is primarily
8763 so that different toolkits can be supported for widget-glyphs, just as 8831 so that different toolkits can be supported for widget-glyphs, just as
8764 they are supported for features such as menubars etc. 8832 they are supported for features such as menubars etc.
8833
8834 Lwlib is extremely poorly documented and quite hairy so here is my
8835 understanding of what goes on.
8836
8837 Lwlib maintains a set of widget_instances which mirror the hierarchical
8838 state of Xt widgets. I think this is so that widgets can be updated and
8839 manipulated generically by the lwlib library. For instance
8840 update_one_widget_instance can cope with multiple types of widget and
8841 multiple types of toolkit. Each element in the widget hierarchy is updated
8842 from its corresponding widget_instance by walking the widget_instance
8843 tree recursively.
8844
8845 This has desirable properties such as lw_modify_all_widgets which is
8846 called from @file{glyphs-x.c} and updates all the properties of a widget
8847 without having to know what the widget is or what toolkit it is from.
8848 Unfortunately this also has hairy properties such as making the lwlib
8849 code quite complex. And of course lwlib has to know at some level what
8850 the widget is and how to set its properties.
8765 8851
8766 @node Specifiers, Menus, Glyphs, Top 8852 @node Specifiers, Menus, Glyphs, Top
8767 @chapter Specifiers 8853 @chapter Specifiers
8768 8854
8769 Not yet documented. 8855 Not yet documented.