Add skeleton classes for hardware event flow (B1)

/*

 * Copyright (C) 2012 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.inputmethod.event;

/**

 * Class representing a generic input event as handled by Latin IME.

 *

 * This contains information about the origin of the event, but it is generalized and should

 * represent a software keypress, hardware keypress, or d-pad move alike.

 * Very importantly, this does not necessarily result in inputting one character, or even anything

 * at all - it may be a dead key, it may be a partial input, it may be a special key on the

 * keyboard, it may be a cancellation of a keypress (e.g. in a soft keyboard the finger of the

 * user has slid out of the key), etc. It may also be a batch input from a gesture or handwriting

 * for example.

 * The combiner should figure out what to do with this.

 */

public class Event {

    static Event obtainEvent() {

        // TODO: create an event pool instead

        return new Event();

    }

}

/*

 * Copyright (C) 2012 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.inputmethod.event;

/**

 * A generic interface for event decoders.

 */

public interface EventDecoder {

}

/*

 * Copyright (C) 2012 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.inputmethod.event;

/**

 * Class describing a decoder chain. This will depend on the language and the input medium (soft

 * or hard keyboard for example).

 */

public class EventDecoderSpec {

    public EventDecoderSpec() {

    }

}

/*

 * Copyright (C) 2012 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.inputmethod.event;

import android.view.KeyEvent;

/**

 * This class implements the logic between receiving events and generating code points.

 *

 * Event sources are multiple. It may be a hardware keyboard, a D-PAD, a software keyboard,

 * or any exotic input source.

 * This class will orchestrate the decoding chain that starts with an event and ends up with

 * a stream of code points + decoding state.

 */

public class EventInterpreter {

    // TODO: Implement an object pool for events, as we'll create a lot of them

    // TODO: Create a combiner

    // TODO: Create an object type to represent input material + visual feedback + decoding state

    // TODO: Create an interface to call back to Latin IME through the above object

    // TODO: replace this with an associative container to bind device id -> decoder

    HardwareEventDecoder mHardwareEventDecoder;

    SoftwareEventDecoder mSoftwareEventDecoder;

    public EventInterpreter() {

        this(null);

    }

    public EventInterpreter(final EventDecoderSpec specification) {

        // TODO: create the decoding chain from a specification. The decoders should be

        // created lazily

        mHardwareEventDecoder = new HardwareKeyboardEventDecoder(0);

    }

    // Helper method to decode a hardware key event into a generic event, and execute any

    // necessary action.

    public boolean onHardwareKeyEvent(final KeyEvent hardwareKeyEvent) {

        final Event decodedEvent = getHardwareKeyEventDecoder(hardwareKeyEvent.getDeviceId())

                .decodeHardwareKey(hardwareKeyEvent);

        return onEvent(decodedEvent);

    }

    public boolean onSoftwareEvent() {

        final Event decodedEvent = getSoftwareEventDecoder().decodeSoftwareEvent();

        return onEvent(decodedEvent);

    }

    private HardwareEventDecoder getHardwareKeyEventDecoder(final int deviceId) {

        // TODO: look up the decoder by device id. It should be created lazily

        return mHardwareEventDecoder;

    }

    private SoftwareEventDecoder getSoftwareEventDecoder() {

        return mSoftwareEventDecoder;

    }

    private boolean onEvent(final Event event) {

        // TODO: Classify the event - input or non-input (see design doc)

        // TODO: IF action event

        //          Send decoded action back to LatinIME

        //       ELSE

        //          Send input event to the combiner

        //          Get back new input material + visual feedback + combiner state

        //          Route the event to Latin IME

        //       ENDIF

        return false;

    }

}

/*

 * Copyright (C) 2012 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.android.inputmethod.event;

import android.view.KeyEvent;

/**

 * An event decoder for hardware events.

 */

public interface HardwareEventDecoder extends EventDecoder {

    public Event decodeHardwareKey(final KeyEvent keyEvent);

}