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) // {Object}

Constructor arguments (args).

This object contains a series of proprieties that tell the constructor how to build the Element.

• ID {String}: unique ID for the element.
• top, left {Int, Int}: the top-left corner of the element in its graphical representation.
• onValueSet {Function}: this property value is a callback function that is tipically called by the UI after setValue() is called (useful to alert the caller when the Element state has changed).
• isClickable {Boolean}: similar to setClickable() method, this property specifies if an element wants to react to events.
• isVisible {Boolean}: this property is used to set the visible flag in the constructor. see setVisible() and getVisible()
• ROITop, ROILeft, ROIWidth, ROIHeight {Int, Int, Int, Int}: these properties are used to set a custom ROI for the element.

Methods

setValue()

Element.prototype.setValue = function (slot, value) // {String, Object}

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 the element's slot whose name is slot to value value.

getValue()

Element.prototype.getValue = function (slot) // {String}

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 is called when the element must be redrawn. It is usually called by the UI, when UI.refresh() is called. If the element's drawClass object is defined, this function draws the object using drawClass primitives.

isInROI()

Element.prototype.isInROI = function (x, y) // {Int, Int}

This function is tipically called by an UI 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) // {Int, Int}
Element.prototype.onMouseDown = function (x,y) // {Int, Int}
Element.prototype.onMouseUp = function (x,y) // {Int, Int}

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) // {Object}

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.

setClickable(), getClickable()

Element.prototype.setClickable = function (isClickable) // {Boolean}
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 (typically by an UI object).

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.