About Caph Focus Management (Focus Navigation)

This document provides information about the Caph focus management.

Contents

Overview

Caph provides the focus management module between Caph UI components. Basically, all Caph UI Components are focusable components that they can be focused using keyboard or mouse. It means if you make the application using Caph UI Components, you don't need to understand about focus management module in detail. However, if you want to implement new custom UI component using Caph, it is very important to understand about focus management module. 

In this article, it will explain how to control focus in Caph application. It will be very helpful to see the document about Caph event system because they are closely related.

 

Defining a new focusable component

To use Caph focus management module, define a new focusable component. The focusable component should mix-in caph.module.mixins.focus.Focusable and caph.module.mixins.event.Observer object. Sample code is as below:

1
2
3
4
5

var MyFocusableComponent = $class({
    $extends: caph.module.renderer.View,
    $mixins : [caph.module.mixins.event.Observer, caph.module.mixins.focus.Focusable],
    // your own class definition is here.
});

 

The MyFocusableComponent class is now an focusable component class. Or you can simply extends caph.ui.base.Component which already mix-in them. Sample code is as below:

1
2
3
4

var MyFocusableComponent = $class({
    $extends: caph.ui.base.Component,
    // your own class definition is here.
});

 

 

Focus Manager

All focusable components in Caph application are managed by focus manager. It control current focused component and calculate next focused component when user input is entered.

It is a singleton instance and it provides APIs to managing focusable components. Its namespace is caph.module.focus.Manager.

 

The APIs list are as below:

Name Description
getInstance Gets focus manager instance
setRootNode Sets tree root node of focus management system. Focus manager will be initialize the first focus based on root node.
getRootNode Gets current root node.
setFocusLevel

Sets current focus level. Focusable components which have same level with focus manager can be focused. However, the focusable component which is level "-1" is always can be focused.
getFocusLevel Gets current focus level.
getCurrentFocus Gets current focused component.
getLastFocus Gets last focused component.
reset Reset current focused component and last focused component to null and blur current focused component.
focus Focus focusable component.
blur Blur focusable component.
setFocusFinderConfigurations

Set configurations to the focus finder algorithm. Focus manager provides High, Middle, and Low priority algorithm.

 

Focusable Component

Focusable component is a component which is managed by focus manager. It provides APIs to config its properties. 

 

The APIs list are as below:

Name Description
focusable Sets focusable status. / Gets focusable status. It is true if it can focused.
focus Focus focusable component. It is same as using focus API in focus manager.
blur Blur focusable component. It is same as using blur API in focus manager.
focusContainer Sets it is focuscontainer or not. / Gets it is focuscontainer or not. The container includes focusable components.
active

Sets active flag. / Gets active flag. Active or not active focusable component.

If it is not actived, it can't be focused.
domEvent Sets send DOM event to focusable component or not. / Gets send DOM event to focusable component or not.
If you want to not fire Dom event(focus,blur) when focus, blur event is occurred by focus manager, make it false.
level Sets focus level of focusable component. / Gets focus level of focusable component.
keyEvent Sets focusable component will focus with key event or not. / focusable component will focus with key event or not.
mouseEvent Sets focusable component will focus with mouse event or not. / focusable component will focus with mouse event or not.
defaultNextFocus

Sets next focused component for current component. / Gets next focused component for current component. It it is set, focus manager doesn't calculate next focused component using its algorithm.

 

Managing focus, blur, keyboard and mouse event

Focus manager sends focus and blur event using Caph event manager. To receive them, you need to implement focus and blur event handler.

Also, focus manager control the events which are releated keyboard and mouse input because these events are sent to only focused component. (ex. keydown, click, mouseover, etc.)

Especially when key event is sent to focus manager, focus manager send them to focused component, then if its propogation is not stopped, calculate next focused component and change current focused component.

 

The sample code is as below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

    var customUIComponent = $class({
        $extends: caph.ui.base.Component,

        $constructor: function (innerHTML, colorIdx) {
            this.$super();

            this._innerHTML = innerHTML;
            this._colorIdx = colorIdx;
            this.setProperty({
                innerHTML: this._innerHTML,
                style: {
                    backgroundColor: color[colorIdx]
                }
            });
            this.addClass('customUI');

            EventManager.getInstance().addObserver(this);
        },

        onkeydown: function (message) {
            if(this.keyEvent() === false){
                return;
            }
            switch (message.detail.keyCode) {
            case CONSTANT.ENTER:
                if (this._mode === 0) {
                    showMsg('Enter color change mode.');
                    this._mode = 1;
                    this._tempInnerHTML = this._innerHTML;
                    this.setProperty({
                        innerHTML: '<b>Color Change Mode</b>'
                    });
                    this.removeClass('focused');
                    this.addClass('colorChange');
                    message.stopPropagation();
                }
                else {
                    showMsg('Exit color change mode.');
                    this._mode = 0;
                    this._innerHTML = this._tempInnerHTML;
                    this.setProperty({
                        innerHTML: this._innerHTML
                    });
                    this.addClass('focused');
                    this.removeClass('colorChange');
                    message.stopPropagation();
                }
                break;
            case CONSTANT.LEFT:
            case CONSTANT.RIGHT:
                if (this._mode === 1) {
                    showMsg('Color changed.');
                    this._changeColor(message.detail.keyCode);
                    message.stopPropagation();
                }
                break;
            case CONSTANT.UP:
            case CONSTANT.DOWN:
                if (this._mode === 1) {
                    message.stopPropagation();
                }
                break;
            }
        },

        onclick: function (message) {
            if(this.mouseEvent() === false){
                return;
            }
            showMsg('Click event');
            if (this._mode === 0) {
                showMsg('Enter color change mode.');
                this._mode = 1;
                this._tempInnerHTML = this._innerHTML;
                this.setProperty({
                    innerHTML: '<b>Color Change Mode</b>'
                });
                this.removeClass('focused');
                this.addClass('colorChange');
                message.stopPropagation();
            }
            else if (this._mode === 1) {
                showMsg('Color changed.');
                this._changeColor(CONSTANT.RIGHT);
                message.stopPropagation();
            }
        },

        ondblclick: function (message){
            if(this.mouseEvent() === false){
                return;
            }
            showMsg('dblclick event');
        },

        onwheel: function (message){
            if(this.mouseEvent() === false){
                return;
            }
            showMsg('wheel event');
        },

        onfocus: function (message) {
            this.addClass('focused ' + message.detail.method);
        },

        onblur: function (message) {
            this.removeClass('focused mouse key');
            if (this._mode === 1) {
                this._mode = 0;
                this._innerHTML = this._tempInnerHTML;
                this.setProperty({
                    innerHTML: this._innerHTML
                });
                this.removeClass('colorChange');
            }
        },
        _mode: 0,
        _tempInnerHTML: '',
        _changeColor: function (direction) {
            switch (direction) {
            case CONSTANT.LEFT:
                this._colorIdx--;
                if (this._colorIdx < 0) {
                    this._colorIdx = color.length - 1;
                }
                break;
            case CONSTANT.RIGHT:
                this._colorIdx++;
                if (this._colorIdx >= color.length) {
                    this._colorIdx = 0;
                }
                break;
            }
            this.setProperty({
                style: {
                    backgroundColor: color[this._colorIdx]
                }
            });
        }
    });

This sample shows how to make custom UI component and implement event handlers for focus management.

 

Related Documents

About Caph event system