element

element - menu and display elements for ITV toolkit

Synopsis

include "draw.m";
include "prefab.m";
prefab:= load Prefab Prefab->PATH;

# types of Elements
EIcon:      con 0;
EText:      con 1;
ETitle:     con 2;
EHorizontal:con 3;
EVertical:  con 4;
ESeparator: con 5;

# first arg to Element.adjust: size of elements
Adjpack:   con 10;   # leave alone, pack tightly
Adjequal:  con 11;   # make equal
Adjfill:   con 12;   # make equal, filling available space

# second arg: position of element within space
Adjleft:   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;
};

Description

Elements are the building blocks of the ITV toolkit. They represent and display text and pictures that can be grouped in arbitrary two-dimensional menus to be walked by an infrared remote control. Elements are packaged within Compounds for display. (see compound).


environ	This specifies the element's environment.
image	If the element needs an Image object (see kind below), this member specifies it.


kind	The Prefab module defines six Element varieties, each labeled by a defined constant in the kind member.
	EIcon	An image.
	EHorizontal	A horizontal list of elements.
	ESeparator	An Image object, like an EIcon, but intended to fill space in a list, rather than to serve as an element of the list. Separators are ignored when selecting or highlighting list elements.
	EText	A single line of text. Text for this element will be drawn with `Style.textfont` and Style.textcolor.
	ETitle	A single line of text, usually giving the title of a Compound object. Text for this element will be drawn with `Style.titlefont` and Style.titlecolor.
	EVertical	A vertical list of elements.


mask	When an element contains an Image object, the `Image.draw` function will be used to display it on the screen. The mask image is used as an argument to Image.draw. See Limbo Draw Modules.
r	All `Elements` are rectangular, occupying the position on the display specified by r.min. The size of the element also depends on r. During creation, if the rectangle is degenerate (has zero size), the element takes its size from the sizes of its components: the image size for icons, text width for strings, etc. Otherwise, the element's size matches the rectangle.
tag	The `tag` of an element serves two purposes: it allows an element to be labeled with arbitrary invisible text, and it provides a mechanism to control which elements of a list may be selected. (See Compound.tagselect in prefab-compound). The tag field of an element may be modified freely after the element is created.
icon (env, r, icon, mask)	Build one EIcon element to be drawn with the icon and mask. The rectangle, r, gives the element's position and size.
text (env, text, r, kind)	Build a textual element or a list of textual elements. The kind parameter may be `EText` or ETitle, determining the style of the drawn text. The resulting `Element` object may be a single element or a `EVertical` list of the appropriate kind, if the text occupies more than one line. The text is folded as necessary to accommodate the available horizontal space; newlines in the text cause line breaks. The width of the text is determined by r, but if r has no width, it will be set by the text itself. The height of the Element is also determined by r. If the height of r is zero, the Element will be made as tall as necessary. If r is not tall enough, the rest of the text may be made visible by calls to Element.scroll. Thus one may choose a specific size or let the text determine the size by setting r suitably.
layout (env, lay, r, kind)	Like Element.text, but builds a structure using the contents of the list lay of `Layout` adts. The `Layout` adt allows construction of a more general form of textual display by providing fine control over the font and color in which to display text and the inclusion of images as textual elements. It also allows setting of the tag for each component of the resulting element or list of elements. If the `Layout` has a non`- nil` `image` field, it is taken as a description of a picture to be incorporated in the text as an `EIcon` element (and the `text` field is ignored); otherwise the `text` field specifies the text to be drawn in the indicated `font` and color. As with Element.text, `Element.layout` does all the geometry management, text line breaking and folding, etc.
elist (env, elem, kind)	Start a list of Element objects. The kind may be `Prefab->EHorizontal` or Prefab->EVertical, specifying the orientation of the list. Parameter elem will be the first element of the list. It may be nil, which creates an empty list of the requested orientation. Subsequent `Element.append` calls build the list.
separator (env, r, icon, mask)	Build one `ESeparator` element to be drawn with the icon and mask. The rectangle, r, gives the element's position and size.
elist.append (elem)	Append one Element, elem, to an existing list, elist. The new element will appear after those already there, either to the right for `EHorizontal` or below for `EVertical` lists.

elem.adjust (spacing, dir)

Format the list so its elements abut. The list-building functions such as append attempt to build a sensible geometry. Alternatively, one can build a list using degenerate geometry and then let adjust compute the geometry for the whole list. For example, one could place all the elements at (0, 0) and then call adjust to decide where the elements belong.


spacing	specifies how the elements fit together
	Adjequal	Makes 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.
	`Adjfill`	Makes them all equal sized in the dimension of the list, expanding the elements to fit the space of the list's Element.r. If the list is too big for the allocated space, only some will be visible.
	`Adjpack`	Packs elements as tightly as possible, using the 'natural' size of each element and setting their rectangles against one another.
dir	controls how each element is placed in its allotted space
	`Adjcenter`	Place each element in the middle of its space.
	`Adjdown`	In a vertical list, move each element to the bottom.
	`Adjleft`	In a horizontal list, move each element to the left.
	`Adjright`	In a horizontal list, move each element to the right.
	`Adjup`	In a vertical list, move each element to the top.

element

Synopsis

Description

elem.adjust (spacing, dir)

elem.clip(r)

elem.scroll(d)

elem.translate(d)

elist.show(elem)