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 own interface methods (when the method is not implemented, the superclass' method is used).

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 is a callback function that is tipically called by the UI object after setValue() is called (useful to alert the caller whenever the Element state has changed).
• isClickable {Boolean} : similar to setClickable() method, this property specifies if an element wants to be notified about 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](Knob Element Interface) element has only one slot, called "knobvalue"). This method sets the element's slot whose name is slot to value value.

setWidth(), setHeight()

Element.prototype.setWidth = function (width) // {Int}
Element.prototype.setHeight = function (height) // {Int}

These methods set width and height of the element. They are tipically used by derived classes in their constructors.

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

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

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

getID()

Element.prototype.getID = function ()

This method returns the element's ID.

getValue()

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

This method returns the value associated with slot slot.

getValues()

Element.prototype.getValues = function ()

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

refresh()

Element.prototype.refresh = function ()

This method is called when the element must be redrawn. It is usually called by the UI object, 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 method is tipically called by the 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 methods are tipically called by the UI object when an event is generated. 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 method associates a DrawClass to the Element.
The Element will subsequently call the DrawClass Interface methods in its refresh() method.

setClickable(), getClickable()

Element.prototype.setClickable = function (isClickable) // {Boolean}
Element.prototype.getClickable = function ()

These methods set and get the clickable state. When an Element is clickable, it means that it wants to be bothered with events. When it's not, its event-handling functions should be not called from the outside (these functions are typically called by an UI object).

setVisible(), getVisible()

Element.prototype.setVisible = function (isVisible) // {Boolean}
Element.prototype.getVisible = function ()

These methods set and get the visible state. Reading this property, whoever is in charge of re-drawing it (typically an UI object) knows what to do.