## BtPatternEditor

BtPatternEditor — the pattern editor widget

## Synopsis

    #include "bt-edit.h"

    struct              BtPatternEditor;
                        BtPatternEditorCallbacks;
                        BtPatternEditorColumn;
    enum                BtPatternEditorColumnType;
                        BtPatternEditorColumnGroup;
    enum                BtPatternEditorColumnGroupType;
    enum                BtPatternEditorSelectionMode;
    GtkWidget *         bt_pattern_editor_new               (void);
    void                bt_pattern_editor_set_pattern       (BtPatternEditor *self,
                                                             gpointer pattern_data,
                                                             guint num_rows,
                                                             guint num_groups,
                                                             BtPatternEditorColumnGroup *groups,
                                                             BtPatternEditorCallbacks *cb);
    gboolean            bt_pattern_editor_get_selection     (BtPatternEditor *self,
                                                             gint *start,
                                                             gint *end,
                                                             gint *group,
                                                             gint *param);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----BtPatternEditor

## Implemented Interfaces

BtPatternEditor implements AtkImplementorIface and GtkBuildable.

## Properties

      "cursor-group"             guint                 : Read / Write
      "cursor-param"             guint                 : Read / Write
      "cursor-row"               guint                 : Read / Write
      "octave"                   guint                 : Write
      "play-position"            gdouble               : Write

## Signals

      "set-scroll-adjustments"                         : Run Last

## Description

Provides an editor widget for BtPattern instances.

## Details

### struct BtPatternEditor

    struct BtPatternEditor;

Opaque editor instance data.

### BtPatternEditorCallbacks

    typedef struct {
      /* FIXME: what about supplying
       * - BtPatternEditorColumn instead of BtPatternEditorColumn->user_data
       * - BtPatternEditorColumnGroup instead of track;
       */
      gfloat (*get_data_func)(gpointer pattern_data, gpointer column_data, guint row, guint group, guint param);
      void (*set_data_func)(gpointer pattern_data, gpointer column_data, guint row, guint group, guint param, guint digit, gfloat value);
    } BtPatternEditorCallbacks;

Data format conversion callbacks.

`get_data_func` () | called to fetch data from the model and convert for view
`set_data_func` () | called to convert from view format for storage in the model

### BtPatternEditorColumn

    typedef struct {
      BtPatternEditorColumnType type;
      float def, min, max;
      gpointer user_data;
    } BtPatternEditorColumn;

A parameter column.

BtPatternEditorColumnType `type`; | column value type
float `def`; | default value
float `min`; | minimum allowed value
float `max`; | maximum allowed value
gpointer `user_data`; | extra data to attach

### enum BtPatternEditorColumnType

    enum BtPatternEditorColumnType {
      PCT_NOTE=0,
      PCT_SWITCH,
      PCT_BYTE,
      PCT_WORD,
      PCT_FLOAT
    };

Column data types.

`PCT_NOTE` | musical notes
`PCT_SWITCH` | on/off switches
`PCT_BYTE` | 8bit values
`PCT_WORD` | 16bit value
`PCT_FLOAT` | single precission floating point values

### BtPatternEditorColumnGroup

    typedef struct {
      // just an id to tell groups apart
      BtPatternEditorColumnGroupType type;
      // can be used for the headline above the group
      gchar *name;
      guint num_columns;
      BtPatternEditorColumn *columns;
      gpointer user_data;
    } BtPatternEditorColumnGroup;

A group of BtPatternEditorColumns, such as a voice or all global parameters.

BtPatternEditorColumnGroupType `type`; | group type
gchar *`name`; | group name
guint `num_columns`; | number of columns
BtPatternEditorColumn *`columns`; | array of columns
gpointer `user_data`; | extra data to attach

### enum BtPatternEditorColumnGroupType

    enum BtPatternEditorColumnGroupType {
      PGT_WIRE=0,
      PGT_GLOBAL,
      PGT_VOICE
    };

Column group type

`PGT_WIRE` | wire parameters
`PGT_GLOBAL` | global parameters
`PGT_VOICE` | voice parameters

### enum BtPatternEditorSelectionMode

    enum BtPatternEditorSelectionMode {
      PESM_COLUMN,
      PESM_GROUP,
      PESM_ALL
    };

Seleting single columns, whole groups (e.g. voices) or the whole pattern.

`PESM_COLUMN` | a single columns
`PESM_GROUP` | a whole group
`PESM_ALL` | all columns (and groups)

### bt_pattern_editor_new ()

    GtkWidget *         bt_pattern_editor_new               (void);

Create a new pattern editor widget. Use `bt_pattern_editor_set_pattern()` to pass pattern data.

Returns : | the widget

### bt_pattern_editor_set_pattern ()

    void                bt_pattern_editor_set_pattern       (BtPatternEditor *self,
                                                             gpointer pattern_data,
                                                             guint num_rows,
                                                             guint num_groups,
                                                             BtPatternEditorColumnGroup *groups,
                                                             BtPatternEditorCallbacks *cb);

Set pattern data to show in the widget.

`self` : | the widget
`pattern_data` : | memory block of values (passed to the callbacks)
`num_rows` : | number of tick rows (y axis)
`num_groups` : | number of groups (x axis)
`groups` : | group parameters
`cb` : | value transformation callbacks

### bt_pattern_editor_get_selection ()

    gboolean            bt_pattern_editor_get_selection     (BtPatternEditor *self,
                                                             gint *start,
                                                             gint *end,
                                                             gint *group,
                                                             gint *param);

Get selection rectangle.

`self` : | the widget
`start` : | location for start tick
`end` : | location for end tick
`group` : | location for group
`param` : | location for parameter in group
Returns : | `TRUE` if there was a selection.

## Property Details

### The `"cursor-group"` property

      "cursor-group"             guint                 : Read / Write

The current group the cursor is in.

Default value: 0

### The `"cursor-param"` property

      "cursor-param"             guint                 : Read / Write

The current parameter the cursor is at.

Default value: 0

### The `"cursor-row"` property

      "cursor-row"               guint                 : Read / Write

The current cursor row.

Default value: 0

### The `"octave"` property

      "octave"                   guint                 : Write

The octave for note input.

Allowed values: <= 12

Default value: 2

### The `"play-position"` property

      "play-position"            gdouble               : Write

The current playing position as a fraction.

Allowed values: [-1,1]

Default value: -1

## Signal Details

### The `"set-scroll-adjustments"` signal

    void                user_function                      (BtPatternEditor *hadjustment,
                                                            GtkAdjustment   *vadjustment,
                                                            GtkAdjustment   *arg2,
                                                            gpointer         user_data)        : Run Last

Internal signal for scrolling.

`hadjustment` : | horizontal adjustment
`vadjustment` : | vertical adjust
`user_data` : | user data set when the signal handler was connected.

## See Also

BtPattern, BtMainPagePatterns