## BtIcLearn

BtIcLearn — interface for devices with learn function

## Functions

gboolean | btic_learn_start ()
gboolean | btic_learn_stop ()
BtIcControl * | btic_learn_register_learned_control ()
gboolean | btic_learn_load_controller_map ()
gboolean | btic_learn_store_controller_map ()
gboolean | (*btic_learn_virtual_start) ()
gboolean | (*btic_learn_virtual_stop) ()
BtIcControl * | (*btic_learn_virtual_register_learned_control) ()

## Properties

gchar * | device-controlchange | Read / Write

## Types and Values

| BtIcLearn

## Object Hierarchy

        GInterface
        ╰── BtIcLearn

## Known Implementations

BtIcLearn is implemented by BtIcASeqDevice and BtIcMidiDevice.

## Includes

    #include <libbtic/ic.h>

## Description

An interface which all devices which support interactive learning of controls should implement.

The interface comes with an implementation for caching the learned controls. The implementor needs to call `btic_learn_load_controller_map()` after construction and `btic_learn_store_controller_map()` when a control got added. The cache files are stored under user-data-dir/buzztrax/controller-maps, e.g. ~/.local/share/buzztrax/controller-maps/.

## Functions

### btic_learn_start ()

    gboolean
    btic_learn_start (const BtIcLearn *self);

Starts the device if needed and enables the learn function. Starts emission of notify::devide-controlchange signals.

#### Parameters

self | the device which implements the BtIcLearn interface |

#### Returns

`TRUE` for success

### btic_learn_stop ()

    gboolean
    btic_learn_stop (const BtIcLearn *self);

Eventually stops the device and disables the learn function. Stops emission of notify::devide-controlchange signals.

#### Parameters

self | the device which implements the BtIcLearn interface |

#### Returns

`TRUE` for success

### btic_learn_register_learned_control ()

    BtIcControl *
    btic_learn_register_learned_control (const BtIcLearn *self,
                                         const gchar *name);

Registers the last detected control with name `name` .

#### Parameters

self | the device which implements the BtIcLearn interface |
name | the name under which to register the control |

#### Returns

the new BtIcControl on success or `NULL`.

[transfer full]

### btic_learn_load_controller_map ()

    gboolean
    btic_learn_load_controller_map (const BtIcLearn *self);

Create initial set of controls from a stored control map. Interface implementations should call this from their `GObjectClass.constructed()` function.

#### Parameters

self | the device |

#### Returns

`TRUE` for success

### btic_learn_store_controller_map ()

    gboolean
    btic_learn_store_controller_map (const BtIcLearn *self);

Store a map of all controls to disk. Interface implementations should call this from their `btic_learn_register_learned_control()` function after they registered a new control.

#### Parameters

self | the device |

#### Returns

`TRUE` for success

### btic_learn_virtual_start ()

    gboolean
    (*btic_learn_virtual_start) (gconstpointer self);

Subclasses will override this methods with a function which enables the learning mode on this device.

#### Parameters

self | device instance |

#### Returns

`TRUE` for success

### btic_learn_virtual_stop ()

    gboolean
    (*btic_learn_virtual_stop) (gconstpointer self);

Subclasses will override this methods with a function which disables the learning mode on this device.

#### Parameters

self | device instance |

#### Returns

`TRUE` for success

### btic_learn_virtual_register_learned_control ()

    BtIcControl *
    (*btic_learn_virtual_register_learned_control)
                                   (gconstpointer self,
                                    const gchar *name);

Subclasses will override this methods with a function which registers the last control which was detected in learn mode.

#### Parameters

self | device instance |
name | the name under which to register the control |

#### Returns

`TRUE` for success

## Types and Values

### BtIcLearn

    typedef struct _BtIcLearn BtIcLearn;

interface for devices which implement a learn-function

## Property Details

### The `“device-controlchange”` property

      “device-controlchange”     gchar *

get the last detected control.

Flags: Read / Write

Default value: NULL