vexi.ui.Box - Vexi Box Object

The vexi box is a fundamental component from which user interfaces are composed.

Rendering Properties

The rendering properties affect what the box looks like visually.

Property Type Initial Value Description

fill

String
Stream

null

A box will draw itself on-screen filled with the color or image specified by this property.

If the value is a stream, Vexi will try to load the stream as an image with one of the supported file extensions. The image will then be rendered in the on-screen area represented by the box according to it's tile property. If the image fails to load, the error will be re-put to the fill property.

If the value is a 5-character hex string (#RGB), 7-character hex string (#RRGGBB), 9-character hex string (#AARRGGBB), a box's fill color will be set to that color.

If the value is one of the ICC colors (the same set of color names supported by SVG), the box's fill color is set to that color.

If the value is null, the fill color will be set to clear (#00000000).

font

Stream

vexi.ui.font.vera

When an object is written to this property, its stream is read using the freetype2 library, and the resulting font is used to render the box's text.

fontsize

Number

"medium"

The size, either in points or relative size, to render the text.

Valid values are a number, in which case it is interpreted as the pointsize of the text, or one of the following strings representing the relative size:

  • "xxsmall"
  • "xsmall"
  • "small"
  • "medium"
  • "large"
  • "xlarge"
  • "xxlarge"

If using a relative size, the box will react to vexi.ui.fontsize.* property changes.

text

String

null

The text of a box. Visually null renders the same as the text to "" (i.e as nothing).

textcolor

String

"#ffffff"

If the value is a 5-character hex string (#RGB), 7-character hex string (#RRGGBB), 9-character hex string (#AARRGGBB), a box's text color will be set to that color.

If the value is one of the ICC colors (the same set of color names supported by SVG), the text color is set to that color.

If the value is null, the text color will be set to clear (#00000000).

tile

String

null

This property can be set to any of the values specified for textcolor. If the value written is a stream then it will interpreted as a PNG, GIF, or JPEG image, which will become the texture for the box. The box's minwidth and minheight properties will be automatically set to the dimensions of the image.

Child Control Properties

The properties/methods related to the children of the box.

Property Type Initial Value Description

numeric properties

Box

N/A

The nth child of box b can be accessed by reading from b[n].

The nth child can be removed by writing null to b[n] causing the child to become parentless.

A new child can be inserted before the nth child by writing it to b[n]; if the value written is already a child of b, it will be removed from b first. It is important to note that this behavior is different from JavaScript arrays; for boxes, writing a non-null value to b[n] does not eliminate the nth child but instead shifts it over one position.

Note: Unlike most JavaScript objects, enumerating a box's properties with the JavaScript for..in construct will enumerate only the box's children and not any other properties.

layout

String

"pack"

The layout strategy for a box - how it lays out it's children.

Valid values are "pack", "place", and "layer".

Packed layout will pack boxes according to the orient setting for the box.

If placing children, child boxes are positioned absolutely within a parent box, and displayed in order - a child appearing above previous siblings and under subsequent sibling boxes.

Layered children behaved like placed children, only the parent box will respect the contentsizes of it's children.

numchildren

Number

varies

Read only reflecting the number of children a box has.

orient

String

"horizontal"

The direction the children are layed out in the box when layout="pack". Valid values are "horizontal" or "vertical".

redirect

Box

thisbox

Writing to this property sets a box's redirect target. Reading from this property will return a boolean instead of the redirect target - true if redirect target is a box, false if it is null.

A box's redirect target must be a descendent of the box. An error will be thrown if it is not.

Children

N/A

N/A

The Children property is a meta-property representing a gateway for accessing the children of a box.

Placing a trap on this lets a box receive notification when a child is accessed using a numeric index - see numeric properties.

In a read or write trap placed on the Children property, the index is accessible as arguments.trapname and modifying this value will cascade a new index up the trap chain.

In a write trap placed on the Children property, the trap function argument is the child box being assigned. Any existing child at that index is thisbox[trapname] before the cascade.

In a read trap placed on the Children property, the child box being read is accessible by reading cascade. To get a different child, modify arguments.trapname before calling cascade.

Note that if the parent's redirect target is set to another box, these traps will only be invoked when children are manipulated by reading and writing to the parent. Reads and writes directly to the redirect target will not trigger the traps.

Also note that these traps are still triggered if a box's redirect target is null. This is useful for boxes that need to accept children and then relocate them elsewhere.

Child Control Methods

Method Returns Description

add(b)

null

Add a new child to the end of the box's children. It is the equivalent of the following vexiscript:

 box[box.numchildren] = child;

clear([from, to])

null

Clear a box of its children. When called with no arguments, all children are cleared, and it is the equivalent of the following vexiscript:

 while (box.numchildren) box[0] = null;

When one index is supplied, it clears all children from that index, inclusive of the index. If a 2nd index is supplied, it clears up to but not including the 2nd index.

holds(box)

Boolean

Determines whether the argument box is a descendent of the subject box.

indexof(b)

Number

Returns the index of box b within the subject box. If box b is not an immediate child of the box, or an immediate child of the box's redirect, then the function returns -1.

Layout Properties

Property Type Initial Value Description

shrink

Boolean

false

If set to true this box will shrink to the smallest size allowed by its packed children and minwidth and minheight properties.

It is a combination of the hshrink and vshrink properties, hence only reads true if both set to true.

Setting shrink sets hshrink and vshrink to the same value.

hshrink
vshrink

Boolean

false

Affects how a box is shrunk in the horizontal and vertical dimensions.

A horizontally shrunk (hshrink) box will decline any horizontal slack available to it within a parent box, and a vertically shrunk (vshrink) box will decline vertical slack.

If this box is the root box of a window, setting it to shrink will make it unresizable.

x
y

Number

varies

If a box is a surface, this is the (x, y) coordinates of the surface.

Otherwise it is the distance between a parent's alignment point and the box's alignment point.

If a box is packed, puts to it's x and y properties are ignored.

width
height

Number

0

When read, this is the width and height of a box.

Putting to width or height

When core layout alters the dimensions of a box, these properties are put to but the respective min- and max-dimensions are not.

minwidth
minheight

Number

0

The minimum width and height a box may be in pixels.

A box will never be smaller than its min-dimension properties with the exception of when the corresponding max-dimension property is set to a lower value.

maxwidth
maxheight

Number

vexi.ui.maxdim

The maximum width and height a box may be in pixels.

A box will never be larger than its max-dimension properties.

contentwidth
contentheight

Number

0

Read only property describing the minimum size a box may be in pixels when constrained by its contents and dimension restricting properties.

That is, considering width, the maximum of a box's minwidth property and the constrained size of it's children, and the minimum of this value and the boxes maxwidth property.

See the layout section of Box Model for more details on constraining.

align

String

"center"

Determines a box's alignment point. This affects the position of:

  • the box's textual content
  • a tiled texture
  • children within the space allocated to them by the layout method of the box

Valid values are:

  • "center", "left", "right", "top", "bottom", "bottomleft", "bottomright", "topleft", "topright"

display

Boolean

true

Whether to display a box and it's contents.

If this box is the root box of a window, its display property will determine whether or not the window is visible.

visible

Boolean

varies

Read only property describing the visible status of this box.

Reads false if an ascendent box has its display property set to false or if the root box is not attached to a surface. Otherwise it is true.

Other Properties

Miscellaneous

Property Type Initial Value Description

cursor

String

null

The shape that the cursor should take when inside this box.

Valid values are:

  • "default", "wait", "crosshair", "text", "hand", "move"
  • "east", "west", "north", "south", "northwest", "northeast", "southwest", "southeast" (resize cursors)

Note that on some platforms, resize cursors for opposite directions (such as northwest and southeast) are the same.

If a box's cursor is null, its parent's cursor will be used. If the root box's cursor is null, the "default" cursor will be used.

surface

varies

null

This special property is read only - alter it by placing a read trap. Puts to this property will have no effect and do not throw an error.

If a box has a parent, this property returns parent.surface; otherwise it returns null. This property is a simple building block that the widget library uses to implement more complex functionality such as focus control and popups.

For more details see Surfaces.

thisbox

Box

thisbox

Returns a reference of a box to itself. If null is written to this property, and this box has a parent, it will be detached from its parent. If this box is the root box of a surface, the box will be detached and the surface destroyed.

After a null put, the thisbox property will still return a reference to itself, and the put does not guarrantee a box and its contents will be garbage collected as there may still be other references to the box and/or its contents.

Other Methods

Method Returns Description

reflow()

null

Read only function that forces a box to discover the size of itself and its contents. This process is normally deferred until a box becomes visible on screen, but sometimes it is desirable to have boxes learn their size before this occurs or if the box only ever exists in an off-screen context.

render()

Renders a box and it's content to an image, returning a box containing the image as it's fill property.

WARNING: experimental; this function may change

inputevent(event, x, y)

null

Read only function that can be used to emulate an event on a box and it's contents.

Other Constructors

Constructor Description

distanceto(target)

Returns an immutable object that dynamically represents the distance between the box that it was called upon and the box given as an argument.

mouse()

Returns an immutable object that dynamically represents the position between of the mouse relative to the box that it was called upon.

Frame Properties

These properties are only relevant to the surface box of a frame.

Property Type Description

Minimized

true

The value true is put to this property on the root box when the surface is minimized, and false when the surface is unminimized. Reading from this value will return true if the surface is minimized and false if it is not. Putting true to this property will minimize the window, and putting false will unminimize it.

Maximized

true

The value true is put to this property on the root box when the surface is maximized, and false when the surface is un-maximized. Reading from this value will return true if the surface is maximized and false if it is not. Putting true to this property will maximize the window, and putting false to this property will unmaximize the window. Note that not all platforms support maximization.

Close

true

When the user attempts to close a surface, the value true will be put to this property. Scripts may trap this property to prevent the window from closing.

Putting the value true to this property on a root box has the same effect as putting null to the thisbox property.

RequestFocus

true

Putting true to this property will attempt to grab the user input focus and assign it to the Surface represented by this box. Focus can not be guarranteed.

ToBack

true

Putting true to this property will attempt to send the Surface represented by this box behind any other windows on a users desktop.

ToFront

true

Putting true to this property will attempt to bring the Surface represented by this box to the front of the other windows on a users desktop.

frameicon

Stream

The icon of the frame a box is attached to. This is usually displayed on the titlebar of a window.

The value should be the stream name of a PNG image. Note that not all platforms support this property.

framealign

String

The alignment of the frame within the user desktop.

frametitle

String

The titlebar text of the frame a box is attached to.

Note that not all platforms support this property. Only ASCII characters 0x20-0x7F are permitted.

framewidth
frameheight

Number

The initial dimensions of a frame, excluding any frame decorations, if this box is used to initialize a frame - see the vexi.ui.frame property.

Event Properties

These properties are put to by the core. Place traps on these properties for event notification.

Property Type Description

Enter

true

The value true is written to this property when the mouse enters a box.

Leave

true

The value true is written to this property when the mouse leaves a box.

Move

true

Indicates that the mouse has moved while within a box.

Press1 / Press2 / Press3

true

Indicates that the user has pressed a mouse button.

On platforms with three mouse buttons, the middle button is button 3. This ensures that applications written to only use two buttons (1 and 2) will work intuitively on three button platforms.

Release1 / Release2 / Release3

true

Indicates that the user has released a mouse button.

Click1 / Click2 / Click3

true

Indicates that the user has pressed and released the mouse button without moving the mouse much (exactly how much is platform-dependent).

DoubleClick1 / DoubleClick2 / DoubleClick3

true

Indicates that the user has clicked the mouse button twice within a short period of time (exactly how long is platform-dependent).

KeyPressed / KeyReleased

String

A string is written to this property when a key is pressed or released.

If the key was any other key, a multi-character string describing the key will be put. For simplicity, we use the VK_ constants in the Java 1.1 API java.awt.event.KeyEvent class. When a key is pressed or released, the string put will be the portion of its VK_ constant after the underscore, all in lower case.

If the shift key was depressed immediately before the event took place, then the string will be capitalized. Special keynames are also capitalized; shift+home is reported as "HOME". Symbols are capitalized as they appear on the keyboard; for example, on an American QWERTY keyboard, shift+2 is reported as "\\@".

If the alt, meta, or command key was depressed immediately before this key was pressed, then the string will be prefixed with the string "A-". If the control key was depressed while this key was pressed, then the string will be prefixed with the string "C-". If both alt and control are depressed, the string is prefixed with "C-A-".

Vexi does not distinguish between a key press resulting from the user physically pushing down a key, and a 'key press' resulting from the keyboard's typematic repeat. In the rare case that an application needs to distinguish between these two events, it should watch for KeyReleased messages and maintain an internal key-state vector.

Properties

Property Type Description

reflow

inputevent

indexof

distanceto

add

clear

mouse

 


Copyright © 2011 The Vexi Project (vexi.sourceforge.net)