Matrix (Javadocs: controlP5)

controlP5

## Class Matrix

- java.lang.Object
- - controlP5.Controller<Matrix>
  - - controlP5.Matrix

- All Implemented Interfaces:
    CDrawable, ControllerInterface<Matrix>, ControlP5Constants

      public class Matrix
      extends Controller<Matrix>

  A matrix is a 2d array with a pointer that traverses through the matrix in a timed interval. if an item of a matrix-column is active, the x and y position of the corresponding cell will trigger an event and notify the program. see the ControlP5matrix example for more information.
  +Example
    `

        /**
         * ControlP5 Matrix
         *
         * A matrix can be used for example as a sequencer, a drum machine.
         *
         * find a list of public methods available for the Matrix Controller
         * at the bottom of this sketch.
         *
         * by Andreas Schlegel, 2012
         * www.sojamo.de/libraries/controlp5
         *
         */

        import controlP5.*;

        ControlP5 cp5;

        Dong[][] d;
        int nx = 10;
        int ny = 10;

        void setup() {
          size(700, 400);

          cp5 = new ControlP5(this);

          cp5.addMatrix("myMatrix")
             .setPosition(50, 100)
             .setSize(200, 200)
             .setGrid(nx, ny)
             .setGap(10, 1)
             .setInterval(200)
             .setMode(ControlP5.MULTIPLES)
             .setColorBackground(color(120))
             .setBackground(color(40))
             ;

          cp5.getController("myMatrix").getCaptionLabel().alignX(CENTER);

          // use setMode to change the cell-activation which by
          // default is ControlP5.SINGLE_ROW, 1 active cell per row,
          // but can be changed to ControlP5.SINGLE_COLUMN or
          // ControlP5.MULTIPLES

            d = new Dong[nx][ny];
          for (int x = 0;x

    `

- - ### Field Summary

    - ### Fields inherited from class controlP5.Controller

      `autoHeight, autoSpacing, autoWidth`

    - ### Fields inherited from interface controlP5.ControlP5Constants

      `acceptClassList, ACTION_BROADCAST, ACTION_CLICK, ACTION_DOUBLE_PRESS, ACTION_DRAG, ACTION_END_DRAG, ACTION_ENTER, ACTION_EXIT, ACTION_LEAVE, ACTION_MOVE, ACTION_PRESS, ACTION_PRESSED, ACTION_RELEASE, ACTION_RELEASE_OUTSIDE, ACTION_RELEASED, ACTION_RELEASEDOUTSIDE, ACTION_START_DRAG, ACTION_WHEEL, ACTIVE, ALL, ALT, AQUA, ARC, ARRAY, BACKSPACE, BASELINE, BITFONT, BLACK, BLUE, BOOLEAN, BOTTOM, BOTTOM_OUTSIDE, CAPTIONLABEL, CENTER, CHECKBOX, COMMANDKEY, CONTROL, controlEventClass, CUSTOM, DECREASE, DEFAULT, DELETE, delimiter, DONE, DOWN, DROPDOWN, ELLIPSE, ENTER, ESCAPE, EVENT, eventMethod, FADEIN, FADEOUT, FIELD, FLOAT, FUCHSIA, GRAY, GREEN, grixel, HALF_PI, HIDE, HIGHLIGHT, HORIZONTAL, IDLE, IMAGE, INACTIVE, INCREASE, INTEGER, INVALID, J2D, JSON, KEYCONTROL, LEFT, LEFT_OUTSIDE, LIME, LINE, LIST, LOAD, MAROON, MENU, METHOD, MOVE, MULTI, MULTIPLES, NAVY, OLIVE, ORANGE, OVER, P2D, P3D, pathdelimiter, PI, PRESS, PRESSED, PRINT, PURPLE, RED, RELEASE, RELEASED, RESET, RIGHT, RIGHT_OUTSIDE, SAVE, SERIALIZED, SHIFT, SILVER, SINGLE, SINGLE_COLUMN, SINGLE_ROW, SPRITE, standard56, standard58, STRING, SWITCH, SWITCH_BACK, SWITCH_FORE, synt24, TAB, TEAL, THEME_A, THEME_CP52014, THEME_CP5BLUE, THEME_GREY, THEME_RED, THEME_RETRO, TOP, TOP_OUTSIDE, TRANSITION_WAIT_FADEIN, TREE, TWO_PI, UP, VALUELABEL, VERBOSE, VERTICAL, WAIT, WHITE, YELLOW`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Matrix(ControlP5 theControlP5, ControllerGroup<?> theParent, java.lang.String theName, int theCellX, int theCellY, int theX, int theY, int theWidth, int theHeight)`
    `Matrix(ControlP5 theControlP5, java.lang.String theName)` Convenience constructor to extend Matrix.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Matrix` | `clear()`
    `boolean` | `get(int theX, int theY)`
    `int[][]` | `getCells()`
    `int` | `getInterval()`
    `int` | `getMode()`
    `static int` | `getX(float thePosition)`
    `static int` | `getX(int thePosition)`
    `static int` | `getY(float thePosition)`
    `static int` | `getY(int thePosition)`
    `boolean` | `isPlaying()`
    `void` | `mousePressed()`
    `void` | `mouseReleased()`
    `Matrix` | `pause()`
    `Matrix` | `play()`
    `Matrix` | `plugTo(java.lang.Object theObject)`
    `Matrix` | `plugTo(java.lang.Object theObject, java.lang.String thePlugName)`
    `void` | `remove()` removes a controller from controlP5.
    `Matrix` | `set(int theX, int theY, boolean theValue)` set the state of a particular cell inside a matrix.
    `Matrix` | `setBackground(int c)`
    `Matrix` | `setCells(int[][] theCells)`
    `Matrix` | `setGap(int theX, int theY)`
    `Matrix` | `setGrid(int theCellX, int theCellY)`
    `Matrix` | `setInterval(int theInterval)` set the speed of intervals in millis iterating through the matrix.
    `Matrix` | `setMode(int theMode)` use setMode to change the cell-activation which by default is ControlP5.SINGLE_ROW, 1 active cell per row, but can be changed to ControlP5.SINGLE_COLUMN or ControlP5.MULTIPLES
    `Matrix` | `setValue(float theValue)`
    `Matrix` | `stop()`
    `Matrix` | `trigger(int theColumn)`
    `Matrix` | `update()` updates the value of the controller without having to set the value explicitly.
    `Matrix` | `updateDisplayMode(int theMode)`
    `Matrix` | `updateInternalEvents(processing.core.PApplet theApplet)` a method for putting input events like e.g.

    - ### Methods inherited from class controlP5.Controller

      `add, addCallback, addListener, addListenerFor, align, bringToFront, bringToFront, changeValue, continuousUpdateEvents, draw, getAbsolutePosition, getAddress, getArrayValue, getArrayValue, getBehavior, getCaptionLabel, getColor, getControllerPlugList, getControlWindow, getDecimalPrecision, getDefaultValue, getHeight, getId, getInfo, getLabel, getMax, getMin, getName, getParent, getPickingColor, getPointer, getPosition, getProperty, getProperty, getStringValue, getTab, getValue, getValueLabel, getView, getWidth, getWindow, hide, init, isActive, isBroadcast, isInside, isLabelVisible, isListening, isLock, isMouseOver, isMousePressed, isMoveable, isUpdate, isUserInteraction, isVisible, keyEvent, linebreak, listen, listenerSize, lock, moveTo, moveTo, moveTo, moveTo, moveTo, moveTo, moveTo, moveTo, moveTo, onChange, onClick, onDoublePress, onDrag, onDraw, onEndDrag, onEnter, onLeave, onMove, onPress, onRelease, onReleaseOutside, onStartDrag, onWheel, plugTo, plugTo, registerProperty, registerProperty, registerTooltip, remove, removeBehavior, removeCallback, removeCallback, removeListener, removeListenerFor, removeListenersFor, removeProperty, removeProperty, set, setAbsolutePosition, setAddress, setArrayValue, setArrayValue, setBehavior, setBroadcast, setCaptionLabel, setColor, setColorActive, setColorBackground, setColorCaptionLabel, setColorForeground, setColorLabel, setColorValue, setColorValueLabel, setDecimalPrecision, setDefaultValue, setGroup, setGroup, setHeight, setId, setImage, setImage, setImages, setImages, setImages, setLabel, setLabelVisible, setLock, setMax, setMin, setMouseOver, setMousePressed, setMoveable, setParent, setPosition, setPosition, setSize, setSize, setStringValue, setTab, setTab, setUpdate, setUserInteraction, setValueLabel, setValueSelf, setView, setView, setVisible, setWidth, show, toString, unlock, unplugFrom, unplugFrom, unregisterTooltip, updateAbsolutePosition, updateEvents, updateSize, x, y`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Matrix

          public Matrix(ControlP5 theControlP5,
                        ControllerGroup<?> theParent,
                        java.lang.String theName,
                        int theCellX,
                        int theCellY,
                        int theX,
                        int theY,
                        int theWidth,
                        int theHeight)

    - #### Matrix

          public Matrix(ControlP5 theControlP5,
                        java.lang.String theName)

      Convenience constructor to extend Matrix.
      Parameters:
        `theControlP5` -
        `theName` -
      +Example
        `

            /**
             * ControlP5 extending Controllers
             *
             * the following example shows how to extend the Controller class to
             * create customizable Controllers. You can either extend the Controller class itself,
             * or any class that extends Controller itself like the Slider, Button, DropdownList, etc.
             *
             * How to:
             *
             * 1) do a super call to the convenience constructor requiring
             * 2 parameter (ControlP5 instance, name)
             *
             * 2) the Controller class has a set of empty methods that allow you to capture
             * inputs from the mouse including
             * onEnter(), onLeave(), onPress(), onRelease(), onClick(), onScroll(int), onDrag()
             * These you can override and include functionality as needed.
             *
             * 3) use method getPointer() to return the local (relative)
             * xy-coordinates of the controller
             *
             * 4) after instantiation custom controllers are treated the same
             * as default controlP5 controllers.
             *
             * by Andreas Schlegel, 2012
             * www.sojamo.de/libraries/controlp5
             *
             */

            import controlP5.*;

            ControlP5 cp5;
            PApplet p;

            void setup() {
              size(400, 400);
              cp5 = new ControlP5(this);

              // create 2 groups to show nesting of custom controllers and
              //
              Group g1 = cp5.addGroup("a").setPosition(0,100).setWidth(180);
              Group g2 = cp5.addGroup("b").setPosition(0,10).setWidth(180);
              g2.moveTo(g1);

              // create 2 custom Controllers from class MyButton
              // MyButton extends Controller and inherits all methods accordingly.
              new MyButton(cp5, "b1").setPosition(0, 0).setSize(180, 200).moveTo(g2);
              new MyButton(cp5, "b2").setPosition(205, 15).setSize(180, 200);

            }

            void draw() {
              background(0);
            }

            // b1 will be called from Controller b1
            public void b1(float theValue) {
              println("yay button "+theValue);
            }

            public void controlEvent(ControlEvent theEvent) {
              println("controlEvent : "+theEvent);
            }

            // Create a custom Controller, please not that
            // MyButton extends Controller,
            // is an indicator for the super class about the type of
            // custom controller to be created.

            class MyButton extends Controller {

              int current = 0xffff0000;

              float a = 128;

              float na;

              int y;

              // use the convenience constructor of super class Controller
              // MyButton will automatically registered and move to the
              // default controlP5 tab.

              MyButton(ControlP5 cp5, String theName) {
                super(cp5, theName);

                // replace the default view with a custom view.
                setView(new ControllerView() {
                  public void display(PGraphics p, Object b) {
                    // draw button background
                    na += (a-na) * 0.1;
                    p.fill(current,na);
                    p.rect(0, 0, getWidth(), getHeight());

                    // draw horizontal line which can be moved on the x-axis
                    // using the scroll wheel.
                    p.fill(0,255,0);
                    p.rect(0,y,width,10);

                    // draw the custom label
                    p.fill(128);
                    translate(0,getHeight()+14);
                    p.text(getName(),0,0);
                    p.text(getName(),0,0);

                  }
                }
                );
              }

              // override various input methods for mouse input control
              void onEnter() {
                cursor(HAND);
                println("enter");
                a = 255;
              }

              void onScroll(int n) {
                println("scrolling");
                y -= n;
                y = constrain(y,0,getHeight()-10);
              }

              void onPress() {
                println("press");
                current = 0xffffff00;
              }

              void onClick() {
                Pointer p1 = getPointer();
                println("clicked at "+p1.x()+", "+p1.y());
                current = 0xffffff00;
                setValue(y);
              }

              void onRelease() {
                println("release");
                current = 0xffffffff;
              }

              void onMove() {
                println("moving "+this+" "+_myControlWindow.getMouseOverList());
              }

              void onDrag() {
                current = 0xff0000ff;
                Pointer p1 = getPointer();
                float dif = dist(p1.px(),p1.py(),p1.x(),p1.y());
                println("dragging at "+p1.x()+", "+p1.y()+" "+dif);
              }

              void onReleaseOutside() {
                onLeave();
              }

              void onLeave() {
                println("leave");
                cursor(ARROW);
                a = 128;
              }
            }

        `

  - ### Method Detail

    - #### clear

          public Matrix clear()

    - #### get

          public boolean get(int theX,
                             int theY)

    - #### getCells

          public int[][] getCells()

    - #### getInterval

          public int getInterval()

    - #### getMode

          public int getMode()

    - #### getX

          public static int getX(float thePosition)

    - #### getX

          public static int getX(int thePosition)

    - #### getY

          public static int getY(float thePosition)

    - #### getY

          public static int getY(int thePosition)

    - #### isPlaying

          public boolean isPlaying()

    - #### mousePressed

          public void mousePressed()

    - #### mouseReleased

          public void mouseReleased()

    - #### pause

          public Matrix pause()

    - #### play

          public Matrix play()

    - #### plugTo

          public Matrix plugTo(java.lang.Object theObject)

      Overrides:
        `plugTo` in class `Controller<Matrix>`
      Returns:
        Controller

    - #### plugTo

          public Matrix plugTo(java.lang.Object theObject,
                               java.lang.String thePlugName)

      Overrides:
        `plugTo` in class `Controller<Matrix>`

    - #### remove

          public void remove()

      Description copied from class: `Controller`
      removes a controller from controlP5.
      Specified by:
        `remove` in interface `ControllerInterface<Matrix>`
      Overrides:
        `remove` in class `Controller<Matrix>`

    - #### set

          public Matrix set(int theX,
                            int theY,
                            boolean theValue)

      set the state of a particular cell inside a matrix. use true or false for parameter theValue
      Parameters:
        `theX` -
        `theY` -
        `theValue` -
      Returns:
        Matrix

    - #### setBackground

          public Matrix setBackground(int c)

    - #### setCells

          public Matrix setCells(int[][] theCells)

    - #### setGap

          public Matrix setGap(int theX,
                               int theY)

    - #### setGrid

          public Matrix setGrid(int theCellX,
                                int theCellY)

    - #### setInterval

          public Matrix setInterval(int theInterval)

      set the speed of intervals in millis iterating through the matrix.
      Parameters:
        `theInterval` - int
      Returns:
        Matrix

    - #### setMode

          public Matrix setMode(int theMode)

      use setMode to change the cell-activation which by default is ControlP5.SINGLE_ROW, 1 active cell per row, but can be changed to ControlP5.SINGLE_COLUMN or ControlP5.MULTIPLES
      Parameters:
        `theMode` - return Matrix

    - #### setValue

          public Matrix setValue(float theValue)

      Specified by:
        `setValue` in interface `ControllerInterface<Matrix>`
      Overrides:
        `setValue` in class `Controller<Matrix>`
      Parameters:
        `theValue` - float

    - #### stop

          public Matrix stop()

    - #### trigger

          public Matrix trigger(int theColumn)

    - #### update

          public Matrix update()

      Description copied from class: `Controller`
      updates the value of the controller without having to set the value explicitly. update does not visually update the controller. the updating status can be set with setUpdate(true/false) and checked with isUpdate().
      Specified by:
        `update` in interface `ControllerInterface<Matrix>`
      Overrides:
        `update` in class `Controller<Matrix>`
      Returns:
        Controller
      See Also:
        `Controller.setUpdate(boolean)`, `Controller.isUpdate()`

    - #### updateDisplayMode

          public Matrix updateDisplayMode(int theMode)

    - #### updateInternalEvents

          public Matrix updateInternalEvents(processing.core.PApplet theApplet)

      Description copied from interface: `ControllerInterface`
      a method for putting input events like e.g. mouse or keyboard events and queries. this has been taken out of the draw method for better overwriting capability.
      Specified by:
        `updateInternalEvents` in interface `ControllerInterface<Matrix>`
      Overrides:
        `updateInternalEvents` in class `Controller<Matrix>`
      See Also:
        `ControllerInterface.updateInternalEvents`

processing library controlP5 by Andreas Schlegel. (c) 2006-2015