JUCE/extras/BLOCKS/doxygen/pages/juce_example_blocks_monitor.dox

/**
@page example_blocks_monitor BlocksMonitor

In order to compile and run this application you need to first download the @jucelink{JUCE framework}, which can be obtained from GitHub @jucegithub{here}.

@section blocks_monitor_introduction Introduction

BlocksMonitor is a simple JUCE application that shows currently connected Lightpad and Control %Block devices and visualises touches and button presses. It also displays some basic information about the Blocks.

Generate a Projucer project from the PIP file located in the @s_file{JUCE/examples/BLOCKS/} folder, then navigate to the @s_file{BlocksMonitorDemo/Builds/} directory and open the code project in your IDE of choice. Run the application and connect your Blocks (if you do not know how to do this, see @ref connecting_blocks). Any devices that you have connected should now show up in the application window and this display will be updated as you add and remove Blocks. Lightpads are represented as a black square and will display the current touches as coloured circles, the size of which depend on the touch pressure, and Control Blocks are shown as rectangles containing the LED row and clickable buttons on the hardware. If you hover the mouse cursor over a %Block, a tooltip will appear displaying the name, UID, serial number and current battery level.

@image html BlocksMonitor.png "The BlocksMonitor application with a Lightpad and 3 Control Blocks connected"

@section blocks_monitor_topology Topology

One of the fundamental concepts of the BLOCKS API is topology - a topology is a set of physically connected Blocks and the connections between them. Knowing when the topology has changed and accessing a data structure containing the current topology is the basis of any Blocks application.

To access the current topology, @s_projcode{BlocksMonitorDemo} inherits from the TopologySource::Listener base class @s_item{[1]} and implements the TopologySource::Listener::topologyChanged() method @s_item{[2]}, a callback which is used to inform listeners when any physical devices have been added or removed.

@code{.cpp}
class BlocksMonitorDemo   : public Component,
                            public TopologySource::Listener, // [1]
                            private Timer
{
public:
//...
    void topologyChanged() override                          // [2]
    {
    //...
@endcode

In order to receive these callbacks, @s_projcode{BlocksMonitorDemo} contains an instance of the PhysicalTopologySource class @s_item{[3]} and registers itself as a listener to this object in its constructor @s_item{[4]}.

@code{.cpp}
    BlocksMonitorDemo()
    {
        //...
        topologySource.addListener (this);          // [4]
        //...
    }

private:
    //...
    PhysicalTopologySource topologySource;          // [3]
    OwnedArray<BlockComponent> blockComponents;
    BlockComponent* masterBlockComponent = nullptr;
//...
@endcode

When the @s_projcode{topologyChanged()} method is called, this object can be used to access the updated topology through the PhysicalTopologySource::getCurrentTopology() method @s_item{[5]} which returns a BlockTopology struct containing an array of currently connected Block objects and an array of BlockDeviceConnection structs representing the connections between them.

@code{.cpp}
    void topologyChanged() override
    {
        //...
        auto topology = topologySource.getCurrentTopology(); // [5]
        //...
    }
@endcode

@section blocks_monitor_block_object The Block Object

The array of %Block objects contained in the %BlockTopology struct can be used to access individual %Block objects @s_item{[1]} and determine their type using the Block::getType() method @s_item{[2]}.

@code{.cpp}
for (auto& block : topology.blocks) // [1]
{
    if (auto* blockComponent = createBlockComponent (block))
    {
        //...
    }
}
@endcode

The application uses this information to construct an on-screen representation of the currently connected Blocks by creating either a @s_projcode{LightpadComponent} object @s_item{[3]} or a @s_projcode{ControlBlockComponent} object @s_item{[4]} for each %Block in the current topology.

@code{.cpp}
    BlockComponent* createBlockComponent (Block::Ptr newBlock)
    {
        auto type = newBlock->getType();                 // [2]

        if (type == Block::lightPadBlock)
            return new LightpadComponent (newBlock);     // [3]

        if (type == Block::loopBlock || type == Block::liveBlock
            || type == Block::touchBlock || type == Block::developerControlBlock)
            return new ControlBlockComponent (newBlock); // [4]

        jassertfalse;
        return nullptr;
    }
@endcode

Both of these classes derive from @s_projcode{BlockComponent}, a relatively simple base class that contains some virtual functions for painting the %Block on screen and handling callbacks from the touch surface and/or buttons on the %Block.

@code{.cpp}
class BlockComponent : public Component,
                       //...
{
public:
    //...
    virtual void paint (Graphics&) override = 0;
    virtual void handleButtonPressed  (ControlButton::ButtonFunction, uint32) {}
    virtual void handleButtonReleased (ControlButton::ButtonFunction, uint32) {}
    virtual void handleTouchChange (TouchSurface::Touch) {}
    virtual void handleBatteryLevelUpdate (float) {}
    //...
@endcode

In its constructor, @s_projcode{BlockComponent} takes a pointer to the %Block object that it represents and adds itself as a listener to the touch surface (if it is a Lightpad) and buttons using the Block::getTouchSurface() and Block::getButtons() methods, respectively.

@code{.cpp}
    BlockComponent (Block::Ptr blockToUse)
        : block (blockToUse)
    {
        //...
        if (auto touchSurface = block->getTouchSurface())
            touchSurface->addListener (this);

        for (auto button : block->getButtons())
            button->addListener (this);
        //...
    }
@endcode

It inherits from the TouchSurface::Listener and ControlButton::Listener classes and overrides the TouchSurface::Listener::touchChanged(), ControlButton::Listener::buttonPressed() and ControlButton::Listener::buttonReleased() methods to call its own virtual methods, which are implemented by the @s_projcode{LightpadComponent} and @s_projcode{ControlBlockComponent} classes to update the on-screen components.

@code{.cpp}
class BlockComponent : public Component,
                       public SettableTooltipClient,
                       private TouchSurface::Listener,
                       private ControlButton::Listener,
                       private Timer
{
private:
    //...
    void touchChanged (TouchSurface&, const TouchSurface::Touch& t) override { handleTouchChange (t); }
    void buttonPressed  (ControlButton& b, Block::Timestamp t) override      { handleButtonPressed  (b.getType(), t); }
    void buttonReleased (ControlButton& b, Block::Timestamp t) override      { handleButtonReleased (b.getType(), t); }
    //...
@endcode

To visualise touches on the Lightpad, @s_projcode{LightpadComponent} contains an instance of the TouchList class called @s_projcode{touches} and calls the TouchList::updateTouch() method whenever it receives a touch surface listener callback in the @s_projcode{LightpadComponent::handleTouchChange()} method.

@code{.cpp}
class LightpadComponent   : public BlockComponent
{
public:
    //...
    void handleTouchChange (TouchSurface::Touch touch) override { touches.updateTouch (touch); }

private:
    //...
    TouchList<TouchSurface::Touch> touches;
    //...
@endcode

The @s_projcode{LightpadBlock::paint()} method then iterates over the current TouchSurface::Touch objects in the %TouchList and visualises them on the component at 25Hz.

@code{.cpp}
    void paint (Graphics& g) override
    {
        //...
        for (auto touch : touches)
        {
            //...
        }
    }
@endcode

The @s_projcode{ControlBlockComponent} class represents a generic Control %Block with 15 LEDs, 8 circular buttons and 1 rounded rectangular button. When a button is pressed on the physical Control %Block, the @s_projcode{BlockComponent::handleButtonPressed()} function is called and this class uses the ControlButton::ButtonFunction variable to determine which button was pressed and should be activated on the on-screen component.

@code{.cpp}
    void handleButtonPressed  (ControlButton::ButtonFunction function, uint32) override
    {
        displayButtonInteraction (controlButtonFunctionToIndex (function), true);
    }
@endcode

The same process is repeated for when the button is released.

@code{.cpp}
    void handleButtonReleased (ControlButton::ButtonFunction function, uint32) override
    {
        displayButtonInteraction (controlButtonFunctionToIndex (function), false);
    }
@endcode

This class also overrides the @s_projcode{BlockComponent::handleBatteryLevelUpdate()} method to update which LEDs should be on based on the battery level, which is accessed in the @s_projcode{BlockComponent} base class using the Block::getBatteryLevel() and Block::isBatteryCharging() methods.

@code{.cpp}
    void handleBatteryLevelUpdate (float batteryLevel) override
    {
        auto numLedsOn = static_cast<int> (numLeds * batteryLevel);

        if (numLedsOn != previousNumLedsOn)
            for (auto i = 0; i < numLeds; ++i)
                leds.getUnchecked (i)->setOnState (i < numLedsOn);

        previousNumLedsOn = numLedsOn;
        repaint();
    }
@endcode

These callback methods are a simple and powerful way to get user input from the Blocks and use this data to drive some process in your application. In this example, the input is simply mirrored on the screen but it could be used to control any number of things such as audio synthesis (see the @ref example_blocks_synth example) and graphics (see the @ref example_blocks_drawing example).

@section blocks_monitor_connections Blocks Connections

The %BlockTopology struct returned by the @s_projcode{%PhysicalTopologySource::getCurrentTopology()} method also contains an array of BlockDeviceConnection objects representing all the current DNA port connections between Blocks in the topology. A single %BlockDeviceConnection struct describes a physical connection between two ports on two Blocks and contains a Block::UID and Block::ConnectionPort object for each of the two devices.

This information is used to calculate the position and rotation of each connected %Block and update the corresponding @s_projcode{topLeft} and @s_projcode{rotation} member variables of its @s_projcode{BlockComponent} so that the correct topology is displayed on the screen. The @s_projcode{topLeft} variable is a Point that describes the position of the top left of the @s_projcode{BlockComponent} in terms of logical device units relative to the top left of the master %Block at Point (0, 0).

@code{.cpp}
    int rotation = 0;
    Point<float> topLeft = { 0.0f, 0.0f };
@endcode

Initially, all @s_projcode{BlockComponent} instances have the @s_projcode{topLeft} position (0, 0) and the @s_projcode{BlocksMonitorDemo::positionBlocks()} method iterates first over all of the Blocks connected to the master %Block and then any remaining Blocks and calculates the correct @s_projcode{topLeft} %Point and @s_projcode{rotation} for each using the array of %BlockDeviceConnection objects.

@code{.cpp}
    void positionBlocks (BlockTopology topology)
    {
        //...
        Array<BlockDeviceConnection> masterBlockConnections;
        for (auto connection : topology.connections)
            if (connection.device1 == masterBlockComponent->block->uid || connection.device2 == masterBlockComponent->block->uid)
                masterBlockConnections.add (connection);

        while (maxDelta > 0.001f && --maxLoops)
        {
            //...
            for (auto connection : masterBlockConnections)
            {
                //...
                for (auto otherBlockComponent : blockComponents)
                {
                    //...
                }
            }
        }

        Array<BlockComponent*> unpositionedBlocks;
        for (auto blockComponent : blockComponents)
            if (blockComponent != masterBlockComponent && ! blocksConnectedToMaster.contains (blockComponent))
                unpositionedBlocks.add (blockComponent);

        if (unpositionedBlocks.size() > 0)
        {
            //...
            while (maxDelta > 0.001f && --maxLoops)
            {
                //...
                for (auto blockComponent : unpositionedBlocks)
                {
                    Array<BlockDeviceConnection> blockConnections;
                    for (auto connection : topology.connections)
                        if (connection.device1 == blockComponent->block->uid || connection.device2 == blockComponent->block->uid)
                            blockConnections.add (connection);

                    for (auto connection : blockConnections)
                    {
                        //...
                        for (auto otherBlockComponent : blockComponents)
                        {
                            //...
                        }
                    }
                }
            }
        }
    }
@endcode

Then, in the @s_projcode{BlocksMonitorDemo::resized()} method these attributes are used to correctly position the components.

@code{.cpp}
    void resized() override
    {
        //...
        if (numBlockComponents == 0)
        {
            //...
            return;
        }

        //...
        if (isInitialResized)
        {
            //...
            for (auto blockComponent : blockComponents)
            {
                auto topLeft = blockComponent->topLeft;
                auto rotation = blockComponent->rotation;
                //...
            }

            //...
            masterBlockComponent->centreWithSize (...);
            //...
        }
        else
        {
            masterBlockComponent->setSize (...);
        }

        for (auto blockComponent : blockComponents)
        {
            if (blockComponent == masterBlockComponent)
                continue;

            blockComponent->setBounds (...);

            if (blockComponent->rotation != 0)
                blockComponent->setTransform (AffineTransform::rotation (...));
        }
    }
@endcode

@section blocks_monitor_summary Summary

This tutorial and the accompanying code has introduced the %BlockTopology and %Block objects, and demonstrated how to receive callbacks from connected Blocks when the touch surface or buttons are pressed, allowing you to use this input in your own applications.

@section blocks_monitor_see_also See also

- @ref example_blocks_drawing
- @ref example_blocks_synth

*/