Graphical Element Interface

Graphical elements are the building blocks of KievII Library. Elements interface is defined in Element.js and is contained in the prototype of the Element object. Every element inherits from Element and implements its interface methods (or, if the method is unimplemented, the superclass' method is used).

This is a list of each one of the Element interface methods with a brief explanation:

Constructor

Element.prototype.getready = function (args)

This is the constructor of an Element. Every Element has an args.ID property, a string that defines the element univocally, and a args.top and a args.left property, specifying the top-left corner in the document where the element is rendered (by a Wrapper).

setValue()

Element.prototype.setValue = function (slot, value)

Every element can have a number of slots, which are values that map the internal state of the object.

The name of the slot(s) is defined in each element's implementation (for example, the Knob element has only one slot, called "knobvalue"). This function sets slot whose name is slot to value value.

Additionally, setValue():

• checks if drawItself is set, and if it is, it calls the element's refresh() method.
• checks if onValueSet() callback was provided by the user, and if it was, it calls it.

getValue()

Element.prototype.getValue = function (slot)

This function returns the value associated with slot slot.

getValues()

Element.prototype.getValues = function ()

This functions returns an array which contains every slot of the Element.

refresh()

Element.prototype.refresh = function ()

This function can be called by an UI object, directly by the user or automatically by the element's setValue().
It is called when the element has changed its state, and must be redrawn.
If element's drawClass object is defined, this function checks whether Element.preserveBg is true to see if the element background must be preserved, then draws the object using drawClass primitives.

isInROI()

Element.prototype.isInROI = function (x, y)

This function is tipically called internally in the Element object, when an event is handled. This function is passed two coordinates and if they are in the Area of Interest of the Element, it returns true, otherwise it returns false.

onMouseMove(), onMouseDown(), onMouseUp()

Element.prototype.onMouseMove = function (x,y)
Element.prototype.onMouseDown = function (x,y)
Element.prototype.onMouseUp = function (x,y)

These functions are tipically called by an UI object when an event is generated, with the event coordinates and they are responsible to react to the event.
These functions do not change directly the state of the Element, but they return undefined if the state should not be changed or an object in the form of {slot : slotname, value : new_value} if the Element's slot slotname should be updated to new_value. The caller is responsible to change the Element's state via setValue().

setDrawClass()

Element.prototype.setDrawClass = function (drawClass)

This function associates a DrawClass to the Element. The Element calls the DrawClass interface functions to draw itself, without having to worry about the low-level drawing details.

setTainted()

Element.prototype.setTainted = function (value)

If the Element's preserveBg property is true, this method tells the Element that the next refresh() must save the background again, when its parameter is true. When the parameter is false, this method tells the Element it must not save the background. Tipically, this method is used when something "beneath" our Element has been re-drawn and the Element's background has possibly changed.

setPreserveBg()

Element.prototype.setPreserveBg = function (value)

When the parameter is true, the Element save its underlying background when refresh() is called, given that the Element in a 'tainted' state (see setTainted()) . When it is false, this logic is skipped.
Background is tipically preserved when a moving (animated) Element would "dirty" the drawing space re-drawing its moving parts.

setDrawsItself()

Element.prototype.setDrawsItself = function (value)

When the parameter is true, the Element's setValue() automatically calls refresh() to redraw the Element when its state is changed. When the parameter is false, the state changes but the Element is not redrawn until refresh() is called from outside.

setClickable(), getClickable()

Element.prototype.setClickable = function (isClickable)
Element.prototype.getClickable = function ()

These function set and get the clickable state. When an Element is clickable, it signals it wants to be bothered with events, when it's not, its event-handling functions should be not called from the outside.
Warning: These functions will be renamed in the near future.

getName()

Element.prototype.getID = function ()

This function return the Element's ID.

getXCoord(), getYCoord(), getWidth(), getHeight()

Element.prototype.getXCoord = function () 
Element.prototype.getYCoord = function ()
Element.prototype.getWidth = function ()
Element.prototype.getHeight = function ()

These getters return the x,y origin coordinates of the Element and its width and height.

Constructor arguments (args).

This object contains a series of proprieties that are mostly specific to the Element. By the way, some of them are common to all Elements. They are:

• onValueSet: this property value is a callback that is called everytime setValue() is called (useful to alert the caller when the Element state has changed).
• drawItself: similar to setDrawsItself() method, this property can be specified in the constructor, too.
• isClickable: similar to setClickable() method, this property can be specified in the constructor, too.