.TH PREFAB-ELEMENT 2.SH NAMEprefab: Element \- menu and display elements for ITV toolkit.SH SYNOPSIS.EXinclude "draw.m";include "prefab.m";prefab := load Prefab Prefab->PATH; # types of ElementsEIcon:      con 0;EText:      con 1;ETitle:     con 2;EHorizontal:con 3;EVertical:  con 4;ESeparator: con 5; # first arg to Element.adjust: size of elementsAdjpack:    con 10; # leave alone, pack tightlyAdjequal:   con 11; # make equalAdjfill:    con 12; # make equal, filling available space # second arg: position of element within spaceAdjleft:    con 20;Adjup:      con 20;Adjcenter:  con 21;Adjright:   con 22;Adjdown:    con 22; Layout: adt{  font:    ref Draw->Font;  color:   ref Draw->Image;  text:    string;  icon:    ref Draw->Image;  mask:    ref Draw->Image;  tag:     string;}; Element: adt{  kind:   int;  r:      Draw->Rect;  environ:ref Environ;    tag:    string;           # different fields defined for different kinds of Elements  kids:   cyclic list of ref Element; # children of elists  str:    string;           # text in an EText element  mask:   ref Draw->Image;  # part of Eicon, ESeparator  image:  ref Draw->Image;  # part of Eicon, ESeparator, EText, Etitle  font:   ref Draw->Font;   # part of EText, Etitle    icon:      fn(env: ref Environ, r: Draw->Rect,               icon, mask: ref Draw->Image):               ref Element;  text:      fn(env: ref Environ, text: string,               r: Draw->Rect, kind: int): ref Element;  layout:    fn(env: ref Environ, lay: list of Layout,               r: Draw->Rect, kind: int): ref Element;  elist:     fn(env: ref Environ, elem: ref Element, kind: int):               ref Element;  separator: fn(env:ref Environ, r: Draw->Rect,               icon, mask: ref Draw->Image): ref Element;   append:    fn(elist: self ref Element, elem: ref Element): int;  adjust:    fn(elem: self ref Element, equal: int, dir: int);  clip:      fn(elem: self ref Element, r: Draw->Rect);  scroll:    fn(elem:self ref Element, d: Draw->Point);  translate: fn(elem:self ref Element, d: Draw->Point);  show:      fn(elist: self ref Element, elem: ref Element): int;};.EE.SH DESCRIPTION.B Prefab.B Elementsare the building blocks of the ITV toolkit.They represent and display text and pictures that can be grouped inarbitrary two-dimensional menus to be walked by the infrared remote control..B Elementsare packaged within.B Compounds(see.IR prefab-compound (2))for display..TF environ.PD.TP.B environThis specifies the element's environment..TP.B imageIf the element needs an.B Imageobject (see.B kindbelow), this member specifies it..TP.B kindThe.B Prefabmodule defines six.B Elementvarieties, each labelled by a defined constant in the.B kindmember..RS.TP.B EIconAn image..TP.B EHorizontalA horizontal list of elements..TP.B ESeparatorAn.B Imageobject, like an.BR EIcon ,but intended to fill space in a list, rather than to serveas an element of the list.Separators are ignored when selecting or highlighting list elements..TP.B ETextA single line of text.Text for this element will be drawn with.B Style.textfontand.BR Style.textcolor ..TP.B ETitleA single line of text, usually giving the title of a.B Compoundobject.Text for this element will be drawn with.B Style.titlefontand.BR Style.titlecolor ..TP.B EVerticalA vertical list of elements..RE.TP.B maskWhen an element contains an.B Imageobject, the.B Image.drawfunction will be used to display it on the screen.The.B maskimage is used as an argument to.BR Image.draw ;see.IR draw-intro (2)for more information..TP.B rAll.B Elementsare rectangular, occupying theposition on the display specified by.BR r.min .The size of the element also depends on.BR r .During creation,if the rectangle is degenerate (haszero size), the element takes its size from thesizes of its components:the image size for icons, text width for strings, etc.Otherwise, the element's size matches the rectangle..TPtagThe.B tagof an element serves two purposes: it allows an element to be labelledwith arbitrary invisible text, and provides a mechanism to control whichelements of a list may be selected: see the description of.B Compound.tagselectin.IR prefab-compound (2).The.B tagfield of an element may be modified freely after the element is created..TP.BI icon( env\fP,\fP\ r\fP,\fP\ icon\fP,\fP\ mask )Build one.B EIconelement to be drawn with the.I iconand.IR mask .The rectangle,.IR r ,gives the element's position and size..TP.BI text( env\fP,\fP\ text\fP,\fP\ r\fP,\fP\ kind )Build a textual element or a list of textual elements..I Kindmay be.B ETextor.BR ETitle ,determining the style of the drawn.IR text .The resulting.B Elementobject may be a single element or a.B EVerticallist of the appropriate kind, if the text occupiesmore than one line.The text is folded as necessary toaccommodate the available horizontal space; newlines inthe text cause line breaks.The width of thetext is determined by.IR r ,but if.I rhas no width, it will beset by the text itself.The height of the Element is alsodetermined by.IR r ;again, if the height of.I ris zero, the Element will be made as tall as necessary (if.I ris not tall enough, the rest of the text may be made visibleby calls to.BR Element.scroll ).Thus one may choosea specific size or let the.I textdetermine the size by setting.I rsuitably..TP.BI layout( env\fP,\fP\ lay\fP,\fP\ r\fP,\fP\ kind )Like.BR Element.text ,but builds a structure using the contents of the list.I layof.B Layoutstructures.  The.B Layouttypeallows construction of a more general form of textual displayby providing fine control over the font and colour in which todisplay text and the inclusion of images as textual elements.It also allows setting of the.B tagfor each component of the resulting element or list of elements.If the.B Layouthas a.RB non- nil.B imagefield, it is taken as a description of apicture to be incorporated in the text as an.B EIconelement (and the.B textfield is ignored);otherwise the.B textfield specifies the text to be drawn in the indicated.B fontand.BR color .As with.BR Element.text ,.B Element.layoutdoes all the geometry management, text line breaking and folding, etc..TP.BI elist( env\fP,\fP\ elem\fP,\fP\ kind )Start a list of.B Elementobjects.The.I kindmay be.B Prefab\->EHorizontalor.BR Prefab\->EVertical ,specifying the orientation of the list..I Elemwill be the first element of the list.It may be.BR nil ,which creates an empty list of therequested orientation.Subsequent.B Element.appendcalls build the list..TP.BI separator( env\fP,\fP\ r\fP,\fP\ icon\fP,\fP\ mask )Build one.B ESeparatorelement to be drawn with the.I iconand.IR mask .The rectangle,.IR r ,gives the element's position and size..TP.IB elist .append( elem )Append one.BR Element ,.IR elem ,to an existing list,.IR elist .The new element will appear after those alreadythere, either to the right for.B EHorizontalor below for.B EVerticallists..TP.IB elem .adjust( spacing\fP,\fP\ dir )Format the list so its elements abut.The list-building functions such as.B appendattempt to build a sensible geometry.Alternatively, one can build a list usingdegenerate geometry and then let.B adjustcompute the geometry for the whole list.For example, one could place all the elementsat (0,\ 0) and then call.B adjustto decide where the elements belong..IP "".I Spacingspecifies how the elements fit together:.RS.TP.B AdjequalMakes them all equal sized in the dimension of the list,but only as big as the largest element.For example, if the element is a horizontal list,all elements will be as wide as the widest item.If the list is too big for the allocated space,only some will be visible. .TP.B AdjfillMakes them all equal sized in the dimension of the list,expanding the elements to fit the space of the list's.BR Element.r .If the list is too big for the allocated space,only some will be visible. .TP.B AdjpackPacks elements as tightly as possible,using the ``natural'' size of each elementand setting their rectangles against one another..RE.IP "".I Dircontrols how each element is placed in its allotted space:.RS.TP.B AdjcenterPlace each element in the middle of its space..TP.B AdjdownIn a vertical list, move each element to the bottom..TP.B AdjleftIn a horizontal list, move each element to the left..TP.B AdjrightIn a horizontal list, move each element to the right..TP.B AdjupIn a vertical list, move each element to the top..RE.TP.IB elem .clip( r )The drawing model for.B Elementobjects is that they occupy some space in the plane, which may be larger or smaller than the space occupiedby its constituent text, icons, sub-elements, etc.The.I clipfunction sets the rectangle of.I elemto.IR r ,without changing its internal geometry.Any space made newly visible by thiswill be filled in by the list's.BR Style.elemcolor .For example, if.B eis an icon element just large enough to display its image,.B e.clip(e.r.inset(-2))will make a two-pixel-wide border around the icon whenit is drawn.As another example, lists are scrolled by leaving their cliprectangle intact while translating the list elements' coordinates..TP.IB elem .scroll( d ).I Dis a.BR Point ,representing a vector;.I elemis an.B Elementobject to be scrolled.The.B scrollfunction leaves the element's.B ralone and translates all the constituent pieces of the list by.IR d ,causing a different portion of.I elemto be visible in its rectangle..TP.IB elem .translate( d )Like.IB elem .scroll( d ),but moves.B rtoo, thus translating the entire.B Elementrather than just the visible part within a fixed rectangle..TP.IB elist .show( elem ).B Showdoes nothing if.I elemis not a list.If it is a list, the list is scrolledso.IR elem ,which must be a member of the list, is visible through.IR elist.r ..PPThe geometry of elements and the membership of listsmay be modified only throughthe provided functions; the Limbo-visible structure is(intended to be) read-only.Tags, text, and images may be modified freelyby the application, but at the moment there is no way to recalculatethe geometry if the components of antextual or image icon change size..PP.B Elementobjects are never drawn explicitly, nor are they drawn after any.B Elementoperation.They are made visible only by calls to.BR Compound.draw ,described by.IR prefab-compound (2)..SH SOURCE.B /libinterp/prefab.c.B /libprefab/*.c.SH SEE ALSO.IR prefab-compound (2).IR prefab-environ (2).IR prefab-style (2)