Class zebkit.ui.Panel
extends <zebkit.layout.Layoutable>
<zebkit.ui>

This the core UI component class. All other UI components has to be successor of panel class.

// instantiate panel with no arguments
var p = new zebkit.ui.Panel();

// instantiate panel with border layout set as its layout manager
var p = new zebkit.ui.Panel(new zebkit.layout.BorderLayout());

// instantiate panel with the given properties (border
// layout manager, blue background and plain border)
var p = new zebkit.ui.Panel({
   layout: new zebkit.ui.BorderLayout(),
   background : "blue",
   border     : "plain"
});

Container Panel can contains number of other UI components as its children where the children components are placed with a defined by the panel layout manager:

// add few children component to panel top, center and bottom parts
// with help of border layout manager
var p = new zebkit.ui.Panel();
p.setLayout(new zebkit.layout.BorderLayout(4)); // set layout manager to
                                               // order children components

p.add("top", new zebkit.ui.Label("Top label"));
p.add("center", new zebkit.ui.TextArea("Text area"));
p.add("bottom", new zebkit.ui.Button("Button"));

Input and component events The class provides possibility to catch various component and input events by declaring an appropriate event method handler. The most simple case you just define a method:

var p = new zebkit.ui.Panel();
p.pointerPressed = function(e) {
    // handle event here
};

If you prefer to create an anonymous class instance you can do it as follow:

var p = new zebkit.ui.Panel([
    function pointerPressed(e) {
        // handle event here
    }
]);

One more way to add the event handler is dynamic extending of an instance class demonstrated below:

var p = new zebkit.ui.Panel("Test");
p.extend([
    function pointerPressed(e) {
        // handle event here
    }
]);

Pay attention Zebkit UI components often declare own event handlers and in this case you can overwrite the default event handler with a new one. Preventing the basic event handler execution can cause the component will work improperly. You should care about the base event handler execution as follow:

// button component declares own pointer pressed event handler
// we have to call the original handler to keep the button component
// properly working
var p = new zebkit.ui.Button("Test");
p.extend([
    function pointerPressed(e) {
        this.$super(e); // call parent class event handler implementation
        // handle event here
    }
]);
Constructor:
zebkit.ui.Panel ([l])

Parameters:
  • [l] <Object | zebkit.layout.Layout>

    pass a layout manager or number of properties that have to be applied to the instance of the panel class.




protected void focused ( )

The method is called whenever the UI component gets or looses focus

public <zebkit.ui.zCanvas> getCanvas ( )

Find a zebkit.ui.zCanvas where the given UI component is hosted


Returns: <zebkit.ui.zCanvas>

a zebkit canvas

public <zebkit.ui.Panel> getComponentAt (x, y)

Get a children UI component that embeds the given point. The method calculates the component visible area first and than looks for a children component only in this calculated visible area. If no one children component has been found than component return itself as a holder of the given point if one of the following condition is true:

  • The component doesn't implement custom "contains(x, y)" method
  • The component implements "contains(x, y)" method and for the given point the method return true

Parameters:
  • x <Integer>

    x coordinate

  • y <Integer>

    y coordinate


Returns: <zebkit.ui.Panel>

a children UI component

public <Boolean> hasFocus ( )

Checks if the component has a focus


Returns: <Boolean>

true if the component has focus

@Override zebkit.layout.Layoutable
public void kidAdded (index, constr, l)

The method is implemented to be aware about a children component insertion.


Parameters:
  • index <Integer>

    an index at that a new children component has been added

  • constr <Object>

    a layout constraints of an inserted component

  • l <zebkit.ui.Panel>

    a children component that has been inserted

@Override zebkit.layout.Layoutable
public void kidRemoved (i, l)

The method is implemented to be aware about a children component removal.


Parameters:
  • i <Integer>

    an index of a removed component

  • l <zebkit.ui.Panel>

    a removed children component

public <zebkit.DoIt> load (JSON)

Shortcut method to register the specific to the concrete component events listener. For instance "zebkit.ui.Button" component fires event when it is pressed:

       var b = new zebkit.ui.Button("Test");
       b.on(function() {
           // button has been pressed
       });


       /**

Load content of the panel UI components from the specified JSON file.


Parameters:
  • JSON <String | Object>

    URL, JSON string or JS object tthat describes UI to be loaded into the panel


Returns: <zebkit.DoIt>

a runner to track JSON loading

public void paintComponent (g)

Paint the component and all its child components using the given 2D HTML Canvas context


Parameters:
public chainable paintViewAt (g, ax, ay, v)

Paint the given view with he specified horizontal and vertical alignments.


Parameters:
@Override zebkit.layout.Layoutable
public void relocated (px, py)

The method is implemented to be aware the component location updating


Parameters:
  • px <Integer>

    a previous x coordinate of the component

  • py <Integer>

    a previous y coordinate of the component

public chainable removeAll ( )

Remove all children components

public void repaint ([x], [y], [w], [h])

Request the whole UI component or part of the UI component to be repainted


Parameters:
  • [x] <Integer>

    x coordinate of the component area to be repainted

  • [y] <Integer>

    y coordinate of the component area to be repainted

  • [w] <Integer>

    width of the component area to be repainted

  • [h] <Integer>

    height of the component area to be repainted

public void requestFocus ( )

Force the given component to catch focus if the component is focusable.

public void requestFocusIn ([timeout])

Force the given component to catch focus in the given timeout.


Parameters:
  • [timeout] <Integer>

    a timeout in milliseconds. The default value is 50 milliseconds

@Override zebkit.layout.Layoutable
public void resized (pw, ph)

The method is implemented to be aware the component size updating


Parameters:
  • pw <Integer>

    a previous width of the component

  • ph <Integer>

    a previous height of the component

public chainable setBackground (v)

Set the background. Background can be a color string or a zebkit.draw.View class instance, or a function(g,x,y,w,h,c) that paints the background:

// set background color
comp.setBackground("red");

// set a picture as a component background
comp.setBackground(new zebkit.draw.Picture(...));

// set a custom rendered background
comp.setBackground(function(g,x,y,w,h,target) {
    // paint a component background here
    g.setColor("blue");
    g.fillRect(x,y,w,h);
    g.drawLine(...);
    ...
});

Parameters:
public chainable setBorder ([v])

Set the border view


Parameters:
  • [v] <zebkit.draw.View | Function | String>

    a border view or border "paint(g,x,y,w,h,c)" rendering function or one of predefined border name: "plain", "sunken", "raised", "etched". If no argument has been passed the method tries to set "plain" as the component border.


Example:
 var pan = new zebkit.ui.Panel();

 // set round border
 pan.setBorder(zebkit.draw.RoundBorder("red"));

 ...
 // set one of predefined border
 pan.setBorder("plain");
public chainable setBottomPadding (bottom)

Set bottom padding


Parameters:
  • bottom <Integer>

    a bottom padding

public chainable setConstraints (ctr)

Set the component layout constraints.


Parameters:
  • ctr <Object>

    a constraints whose value depends on layout manager that has been set

public chainable setEnabled (b)

Set the UI component enabled state. Using this property an UI component can be excluded from getting input events


Parameters:
protected chainable setKids (a)

Add the given children component or number of components to the given panel.


Parameters:
  • a <zebkit.ui.Panel | Array | Object>

    children component of number of components to be added. The parameter can be:

    • Component
    • Array of components
    • Dictionary object where every element is a component to be added and the key of the component is stored in the dictionary is considered as the component constraints
public chainable setLeftPadding (left)

Set left padding


Parameters:
  • left <Integer>

    a left padding

public chainable setPadding (v)

Set the UI component top, right, left, bottom paddings to the same given value


Parameters:
  • v <Integer>

    the value that will be set as top, right, left, bottom UI component paddings

public chainable setPadding (top, left, bottom, right)

Set UI component top, left, bottom, right paddings. The paddings are gaps between component border and painted area.


Parameters:
  • top <Integer>

    a top padding

  • left <Integer>

    a left padding

  • bottom <Integer>

    a bottom padding

  • right <Integer>

    a right padding

public chainable setRightPadding (right)

Set right padding


Parameters:
  • right <Integer>

    a right padding

public chainable setTopPadding (top)

Set top padding


Parameters:
  • top <Integer>

    a top padding

public chainable setVisible (b)

Set the UI component visibility


Parameters:
public chainable toBack ( )

Send the UI component to back

public chainable toFront ( )

Bring the UI component to front

public chainable toPreferredHeight ( )

Set the UI component height to its preferred height

public chainable toPreferredSize ( )

Set the UI component size to its preferred size

public chainable toPreferredWidth ( )

Set the UI component width to its preferred width

public <zebkit.draw.View> toView (target)

Build zebkit.draw.View that represents the UI component


Parameters:
Returns: <zebkit.draw.View>

a view of the component

public void vrp ( )

Shortcut method to invalidating the component and then initiating the component repainting.



Inherited attributes:
public Object constraints    public Integer height    public Boolean isValid    public Boolean isVisible    public Array kids    public zebkit.layout.Layout layout    public zebkit.layout.Layoutable parent    public Integer width    public Integer x    public Integer y   



public <zebkit.draw.View> bg

UI component background view

public <zebkit.draw.View> border

UI component border view

public <Boolean> canHaveFocus

Define and set the property to true if the component has to catch focus

public <Boolean> isEnabled

UI component enabled state


childEventName

It is also possible to listen all the listed above event for children component. To handle the event register listener method following the pattern below:

var p = new zebkit.ui.Panel();
p.childPointerPressed = function(e) { ... }; // add event handler

Parameters:
clipCopy

The method is called for focusable UI components (components that can hold input focus) to ask a string to be saved in native clipboard

clipPaste

The method is called to pass string from clipboard to a focusable (a component that can hold input focus) UI component


Parameters:
  • s <String>

    a string from native clipboard

compAdded

Implement the event handler method to catch component added event The event is triggered every time the component has been inserted into another one.

var p = new zebkit.ui.Panel();
p.compAdded = function(e) { ... }; // add event handler

Parameters:
compEnabled

Implement the event handler method to catch component enabled event The event is triggered every time a component enabled state has been updated.

var p = new zebkit.ui.Panel();
p.compEnabled = function(e) { ... }; // add event handler

Parameters:
compMoved

Implement the event handler method to catch component moved event The event is triggered every time the component location has been updated.

 var p = new zebkit.ui.Panel();
 p.compMoved = function(e) { ... }; // add event handler

Parameters:
compRemoved

Implement the event handler method to catch component removed event The event is triggered every time the component has been removed from its parent UI component.

var p = new zebkit.ui.Panel();
p.compRemoved = function(e) { ... }; // add event handler

Parameters:
compShown

Implement the event handler method to catch component shown event The event is triggered every time a component visibility state has been updated.

var p = new zebkit.ui.Panel();
p.compShown = function(e) { ... }; // add event handler

Parameters:
compSized

Implement the event handler method to catch the component sized event The event is triggered every time the component has been re-sized.

var p = new zebkit.ui.Panel();
p.compSized = function(e) { ... }; // add event handler

Parameters:
  • e <zebkit.ui.event.CompEvent>

    a component event. Source of the event is a component that has been sized, "prevWidth" and "prevHeight" fields keep a previous size the component had.

focusGained

Implement the event handler method to catch component focus gained event The event is triggered every time a component has gained focus.

var p = new zebkit.ui.Panel();
p.focusGained = function(e) { ... }; // add event handler

Parameters:
focusLost

Implement the event handler method to catch component focus lost event The event is triggered every time a component has lost focus

var p = new zebkit.ui.Panel();
p.focusLost = function(e) { ... }; // add event handler

Parameters:
keyPressed

Implement the event handler method to catch key pressed event The event is triggered every time a key has been pressed.

var p = new zebkit.ui.Panel(); p.keyPressed = function(e) { ... }; // add event handler


Parameters:
keyReleased

Implement the event handler method to catch key released event The event is triggered every time a key has been released.

var p = new zebkit.ui.Panel();
p.keyReleased = function(e) { ... }; // add event handler

Parameters:
keyTyped

Implement the event handler method to catch key types event The event is triggered every time a key has been typed.

var p = new zebkit.ui.Panel();
p.keyTyped = function(e) { ... }; // add event handler

Parameters:
pointerClicked

Implement the event handler method to catch pointer clicked event. The event is triggered every time a pointer button has been clicked. Click events are generated only if no one pointer moved or drag events has been generated in between pointer pressed -> pointer released events sequence.

var p = new zebkit.ui.Panel();
p.pointerClicked = function(e) { ... }; // add event handler

Parameters:
pointerDragEnded

Implement the event handler method to catch pointer drag ended event. The event is triggered every time a pointer cursor has been moved last time when a pointer button has been pressed. Or when a finger has been moved last time over a touch screen.

var p = new zebkit.ui.Panel();
p.pointerDragEnded = function(e) { ... }; // add event handler

Parameters:
pointerDragged

Implement the event handler method to catch pointer dragged event. The event is triggered every time a pointer cursor has been moved when a pointer button has been pressed. Or when a finger has been moved over a touch screen.

var p = new zebkit.ui.Panel();
p.pointerDragged = function(e) { ... }; // add event handler

Parameters:
pointerDragStarted

Implement the event handler method to catch pointer drag started event. The event is triggered every time a pointer cursor has been moved first time when a pointer button has been pressed. Or when a finger has been moved first time over a touch screen.

var p = new zebkit.ui.Panel();
p.pointerDragStarted = function(e) { ... }; // add event handler

Parameters:
pointerEntered

Implement the event handler method to catch pointer entered event. The event is triggered every time a pointer cursor entered the given component.

var p = new zebkit.ui.Panel();
p.pointerEntered = function(e) { ... }; // add event handler

Parameters:
pointerExited

Implement the event handler method to catch pointer exited event. The event is triggered every time a pointer cursor exited the given component.

var p = new zebkit.ui.Panel();
p.pointerExited = function(e) { ... }; // add event handler

Parameters:
pointerMoved

Implement the event handler method to catch pointer moved event. The event is triggered every time a pointer cursor has been moved with no a pointer button pressed.

var p = new zebkit.ui.Panel();
p.pointerMoved = function(e) { ... }; // add event handler

Parameters:
pointerPressed

Implement the event handler method to catch pointer pressed event. The event is triggered every time a pointer button has been pressed or a finger has touched a touch screen.

var p = new zebkit.ui.Panel();
p.pointerPressed = function(e) { ... }; // add event handler

Parameters:
pointerReleased

Implement the event handler method to catch pointer released event. The event is triggered every time a pointer button has been released or a finger has untouched a touch screen.

var p = new zebkit.ui.Panel();
p.pointerReleased = function(e) { ... }; // add event handler

Parameters: