JUCE: Block Class Reference

JUCE

Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
Block Class Referenceabstract

Represents an individual BLOCKS device. More...

Inheritance diagram for Block:

## Classes
struct | BlockArea
| A simple struct representing the area of a block. More...
struct | ConfigMetaData
| Metadata for a given config item. More...
struct | ConnectionPort
| These are the edge-connectors that a device may have. More...
struct | DataInputPortListener
| Interface for objects listening to input data port. More...
struct | Program
| A program that can be loaded onto a block. More...
struct | ProgramEventListener
| Interface for objects listening to custom program events. More...
struct | ProgramEventMessage
| A message that can be sent to the currently loaded program. More...

## Public Types
enum | Type { unknown = 0, lightPadBlock, liveBlock, loopBlock, developerControlBlock, touchBlock, seaboardBlock, lumiKeysBlock }
| The different block types. More...
using | Ptr = ReferenceCountedObjectPtr< Block >
| The Block class is reference-counted, so always use a Block::Ptr when you are keeping references to them. More...
using | Array = ReferenceCountedArray< Block >
| The Block class is reference-counted, so Block::Array is useful when you are storing lists of them. More...
using | UID = uint64
| This type is used for the unique block identifier. More...
using | Timestamp = uint32
| This type is used for timestamping events. More...

## Public Member Functions
| ~Block () override
| Destructor. More...
bool | operator== (const Block &other) const noexcept
| Two blocks are considered equal if they have the same UID. More...
bool | operator!= (const Block &other) const noexcept
| Two blocks are considered equal if they have the same UID. More...
virtual Type | getType () const =0
| Returns the type of this device. More...
bool | isControlBlock () const
| Returns true if this a control block. More...
virtual String | getDeviceDescription () const =0
| Returns a human-readable description of this device type. More...
virtual float | getBatteryLevel () const =0
| Returns the battery level in the range 0.0 to 1.0. More...
virtual bool | isBatteryCharging () const =0
| Returns true if the battery is charging. More...
virtual bool | isConnected () const =0
| Returns true if this block is connected and active. More...
virtual Time | getConnectionTime () const =0
| Returns the time this block object was connected to the topology. More...
virtual bool | isConnectedViaBluetooth () const =0
| Returns true if this block or the master block this block is connected to, is connected via bluetooth. More...
virtual bool | isMasterBlock () const =0
| Returns true if this block is directly connected to the application, as opposed to only being connected to a different block via a connection port. More...
virtual UID | getConnectedMasterUID () const =0
| Returns the UID of the master block this block is connected to. More...
virtual int | getWidth () const =0
| Returns the width of the device in logical device units. More...
virtual int | getHeight () const =0
| Returns the height of the device in logical device units. More...
virtual bool | isHardwareBlock () const =0
| Returns true if the device is a physical hardware block (i.e. More...
virtual float | getMillimetersPerUnit () const =0
| Returns the length of one logical device unit as physical millimeters. More...
virtual BlockArea | getBlockAreaWithinLayout () const =0
| Returns the area that this block covers within the layout of the group as a whole. More...
virtual int | getRotation () const =0
| Returns the rotation of this block relative to the master block in 90 degree steps clockwise. More...
virtual LEDGrid * | getLEDGrid () const =0
| If this block has a grid of LEDs, this will return an object to control it. More...
virtual LEDRow * | getLEDRow ()=0
| If this block has a row of LEDs, this will return an object to control it. More...
virtual juce::Array< StatusLight * > | getStatusLights () const =0
| If this block has any status LEDs, this will return an array of objects to control them. More...
virtual TouchSurface * | getTouchSurface () const =0
| If this block has a pressure-sensitive surface, this will return an object to access its data. More...
virtual juce::Array< ControlButton * > | getButtons () const =0
| If this block has any control buttons, this will return an array of objects to control them. More...
virtual bool | supportsGraphics () const =0
| This returns true if the block supports generating graphics by drawing into a JUCE Graphics context. More...
virtual juce::Array< ConnectionPort > | getPorts () const =0
| Returns a list of the connectors that this device has. More...
virtual Result | setProgram (Program *)=0
| Sets the Program to run on this block. More...
virtual Program * | getProgram () const =0
| Returns a pointer to the currently loaded program. More...
virtual void | sendProgramEvent (const ProgramEventMessage &)=0
| Sends a message to the currently loaded program. More...
virtual void | addProgramEventListener (ProgramEventListener *)
| Adds a new listener for custom program events from the block. More...
virtual void | removeProgramEventListener (ProgramEventListener *)
| Removes a listener for custom program events from the block. More...
virtual uint32 | getMemorySize ()=0
| Returns the overall memory of the block. More...
virtual uint32 | getHeapMemorySize ()=0
| Returns the size of the data block that setDataByte and other functions can write to. More...
virtual void | setDataByte (size_t offset, uint8 value)=0
| Sets a single byte on the littlefoot heap. More...
virtual void | setDataBytes (size_t offset, const void *data, size_t num)=0
| Sets multiple bytes on the littlefoot heap. More...
virtual void | setDataBits (uint32 startBit, uint32 numBits, uint32 value)=0
| Sets multiple bits on the littlefoot heap. More...
virtual uint8 | getDataByte (size_t offset)=0
| Gets a byte from the littlefoot heap. More...
virtual void | saveProgramAsDefault ()=0
| Sets the current program as the block's default state. More...
virtual void | resetProgramToDefault ()=0
| Resets the loaded program to the block's default state. More...
virtual uint32 | getMaxConfigIndex ()=0
| Returns the maximum number of config items available. More...
virtual bool | isValidUserConfigIndex (uint32 item)=0
| Determine if this is a valid config item index. More...
virtual int32 | getLocalConfigValue (uint32 item)=0
| Get local config item value. More...
virtual void | setLocalConfigValue (uint32 item, int32 value)=0
| Set local config item value. More...
virtual void | setLocalConfigRange (uint32 item, int32 min, int32 max)=0
| Set local config item range. More...
virtual void | setLocalConfigItemActive (uint32 item, bool isActive)=0
| Set if config item is active or not. More...
virtual bool | isLocalConfigItemActive (uint32 item)=0
| Determine if config item is active or not. More...
virtual ConfigMetaData | getLocalConfigMetaData (uint32 item)=0
| Get config item metadata. More...
virtual void | requestFactoryConfigSync ()=0
| Request sync of factory config with block. More...
virtual void | resetConfigListActiveStatus ()=0
| Reset all items active status. More...
virtual void | factoryReset ()=0
| Perform factory reset on Block. More...
virtual void | blockReset ()=0
| Reset this Block. More...
virtual bool | setName (const String &name)=0
| Set Block name. More...
virtual void | setLogger (std::function< void(const Block &block, const String &)> loggingCallback)=0
| Allows the user to provide a function that will receive log messages from the block. More...
virtual bool | sendFirmwareUpdatePacket (const uint8 *data, uint8 size, std::function< void(uint8, uint32)> packetAckCallback)=0
| Sends a firmware update packet to a block, and waits for a reply. More...
virtual void | setConfigChangedCallback (std::function< void(Block &, const ConfigMetaData &, uint32)>)=0
| Provides a callback that will be called when a config changes. More...
virtual void | setProgramLoadedCallback (std::function< void(Block &)> programLoaded)=0
| Provides a callback that will be called when a program has been loaded. More...
virtual void | addDataInputPortListener (DataInputPortListener *)
| Adds a new listener for the data input port. More...
virtual void | removeDataInputPortListener (DataInputPortListener *)
| Removes a listener for the data input port. More...
virtual void | sendMessage (const void *messageData, size_t messageSize)=0
| Sends a message to the block. More...
Public Member Functions inherited from ReferenceCountedObject
void | incReferenceCount () noexcept
| Increments the object's reference count. More...
void | decReferenceCount () noexcept
| Decreases the object's reference count. More...
bool | decReferenceCountWithoutDeleting () noexcept
| Decreases the object's reference count. More...
int | getReferenceCount () const noexcept
| Returns the object's current reference count. More...

## Static Public Member Functions
static bool | isControlBlock (Block::Type)
| Returns true if Block::Type is a control block. More...

## Public Attributes
const String | serialNumber
| The Block's serial number. More...
String | versionNumber
| The Block's version number. More...
String | name
| The Block's name. More...
const UID | uid
| This Block's UID. More...

## Protected Member Functions
| Block (const String &serialNumberToUse)
| Block (const String &serial, const String &version, const String &name)
Protected Member Functions inherited from ReferenceCountedObject
| ReferenceCountedObject ()=default
| Creates the reference-counted object (with an initial ref count of zero). More...
| ReferenceCountedObject (const ReferenceCountedObject &) noexcept
| Copying from another object does not affect this one's reference-count. More...
| ReferenceCountedObject (ReferenceCountedObject &&) noexcept
| Copying from another object does not affect this one's reference-count. More...
ReferenceCountedObject & | operator= (const ReferenceCountedObject &) noexcept
| Copying from another object does not affect this one's reference-count. More...
ReferenceCountedObject & | operator= (ReferenceCountedObject &&) noexcept
| Copying from another object does not affect this one's reference-count. More...
virtual | ~ReferenceCountedObject ()
| Destructor. More...
void | resetReferenceCount () noexcept
| Resets the reference count to zero without deleting the object. More...

## Protected Attributes
ListenerList< DataInputPortListener > | dataInputPortListeners
ListenerList< ProgramEventListener > | programEventListeners

## Detailed Description

Represents an individual BLOCKS device.

## Member Typedef Documentation

## ◆ Ptr

using Block::Ptr = ReferenceCountedObjectPtr<Block>

The Block class is reference-counted, so always use a Block::Ptr when you are keeping references to them.

## ◆ Array

using Block::Array = ReferenceCountedArray<Block>

The Block class is reference-counted, so Block::Array is useful when you are storing lists of them.

## ◆ UID

using Block::UID = uint64

This type is used for the unique block identifier.

## ◆ Timestamp

using Block::Timestamp = uint32

This type is used for timestamping events.

It represents a number of milliseconds since the block device was booted.

## Member Enumeration Documentation

## ◆ Type

enum Block::Type

The different block types.

See also
  Block::getType()

Enumerator
unknown | Unknown block type.
lightPadBlock | Lightpad block type.
liveBlock | Live control block type.
loopBlock | Loop control block type.
developerControlBlock | Developer control block type.
touchBlock | Touch control block type.
seaboardBlock | Seaboard block type.
lumiKeysBlock | LUMI Keys block type

## Constructor & Destructor Documentation

## ◆ ~Block()

Block::~Block | ( |  | ) |
| override

Destructor.

## ◆ Block() [1/2]

Block::Block | ( | const String & | serialNumberToUse | ) |
| protected

## ◆ Block() [2/2]

Block::Block | ( | const String & | serial,
|  | const String & | version,
|  | const String & | name
| ) |  |
| protected

## Member Function Documentation

## ◆ operator==()

bool Block::operator== | ( | const Block & | other | ) | const
| noexcept

Two blocks are considered equal if they have the same UID.

References uid.

## ◆ operator!=()

bool Block::operator!= | ( | const Block & | other | ) | const
| noexcept

Two blocks are considered equal if they have the same UID.

References uid.

## ◆ getType()

virtual Type Block::getType | ( |  | ) | const
| pure virtual

Returns the type of this device.

See also
  Block::Type

## ◆ isControlBlock() [1/2]

bool Block::isControlBlock | ( |  | ) | const

Returns true if this a control block.

## ◆ isControlBlock() [2/2]

static bool Block::isControlBlock | ( | Block::Type |  | ) |
| static

Returns true if Block::Type is a control block.

## ◆ getDeviceDescription()

virtual String Block::getDeviceDescription | ( |  | ) | const
| pure virtual

Returns a human-readable description of this device type.

## ◆ getBatteryLevel()

virtual float Block::getBatteryLevel | ( |  | ) | const
| pure virtual

Returns the battery level in the range 0.0 to 1.0.

## ◆ isBatteryCharging()

virtual bool Block::isBatteryCharging | ( |  | ) | const
| pure virtual

Returns true if the battery is charging.

## ◆ isConnected()

virtual bool Block::isConnected | ( |  | ) | const
| pure virtual

Returns true if this block is connected and active.

## ◆ getConnectionTime()

virtual Time Block::getConnectionTime | ( |  | ) | const
| pure virtual

Returns the time this block object was connected to the topology.

Only valid when isConnected == true.

See also
  Block::isConnected

## ◆ isConnectedViaBluetooth()

virtual bool Block::isConnectedViaBluetooth | ( |  | ) | const
| pure virtual

Returns true if this block or the master block this block is connected to, is connected via bluetooth.

Only valid when isConnected == true.

See also
  Block::isConnected, Block::isMasterBlock

## ◆ isMasterBlock()

virtual bool Block::isMasterBlock | ( |  | ) | const
| pure virtual

Returns true if this block is directly connected to the application, as opposed to only being connected to a different block via a connection port.

See also
  Block::ConnectionPort

## ◆ getConnectedMasterUID()

virtual UID Block::getConnectedMasterUID | ( |  | ) | const
| pure virtual

Returns the UID of the master block this block is connected to.

## ◆ getWidth()

virtual int Block::getWidth | ( |  | ) | const
| pure virtual

Returns the width of the device in logical device units.

## ◆ getHeight()

virtual int Block::getHeight | ( |  | ) | const
| pure virtual

Returns the height of the device in logical device units.

## ◆ isHardwareBlock()

virtual bool Block::isHardwareBlock | ( |  | ) | const
| pure virtual

Returns true if the device is a physical hardware block (i.e.

not a virtual block).

## ◆ getMillimetersPerUnit()

virtual float Block::getMillimetersPerUnit | ( |  | ) | const
| pure virtual

Returns the length of one logical device unit as physical millimeters.

## ◆ getBlockAreaWithinLayout()

virtual BlockArea Block::getBlockAreaWithinLayout | ( |  | ) | const
| pure virtual

Returns the area that this block covers within the layout of the group as a whole.

The coordinates are in logical block units, and are relative to the origin, which is the master block's top-left corner.

## ◆ getRotation()

virtual int Block::getRotation | ( |  | ) | const
| pure virtual

Returns the rotation of this block relative to the master block in 90 degree steps clockwise.

## ◆ getLEDGrid()

virtual LEDGrid* Block::getLEDGrid | ( |  | ) | const
| pure virtual

If this block has a grid of LEDs, this will return an object to control it.

Note that the pointer that is returned belongs to this object, and the caller must neither delete it or use it after the lifetime of this Block object has finished. If there are no LEDs, then this method will return nullptr.

## ◆ getLEDRow()

virtual LEDRow* Block::getLEDRow | ( |  | ) |
| pure virtual

If this block has a row of LEDs, this will return an object to control it.

Note that the pointer that is returned belongs to this object, and the caller must neither delete it or use it after the lifetime of this Block object has finished. If there are no LEDs, then this method will return nullptr.

## ◆ getStatusLights()

virtual juce::Array<StatusLight*> Block::getStatusLights | ( |  | ) | const
| pure virtual

If this block has any status LEDs, this will return an array of objects to control them.

Note that the objects in the array belong to this Block object, and the caller must neither delete them or use them after the lifetime of this Block object has finished.

## ◆ getTouchSurface()

virtual TouchSurface* Block::getTouchSurface | ( |  | ) | const
| pure virtual

If this block has a pressure-sensitive surface, this will return an object to access its data.

Note that the pointer returned does is owned by this object, and the caller must neither delete it or use it after the lifetime of this Block object has finished. If the device is not touch-sensitive, then this method will return nullptr.

## ◆ getButtons()

virtual juce::Array<ControlButton*> Block::getButtons | ( |  | ) | const
| pure virtual

If this block has any control buttons, this will return an array of objects to control them.

Note that the objects in the array belong to this Block object, and the caller must neither delete them or use them after the lifetime of this Block object has finished.

## ◆ supportsGraphics()

virtual bool Block::supportsGraphics | ( |  | ) | const
| pure virtual

This returns true if the block supports generating graphics by drawing into a JUCE Graphics context.

This should only be true for virtual on-screen blocks; hardware blocks will instead use the LED Grid for visuals.

## ◆ getPorts()

virtual juce::Array<ConnectionPort> Block::getPorts | ( |  | ) | const
| pure virtual

Returns a list of the connectors that this device has.

## ◆ setProgram()

virtual Result Block::setProgram | ( | Program * |  | ) |
| pure virtual

Sets the Program to run on this block.

The supplied Program's lifetime will be managed by this class, so do not use the Program in other places in your code.

## ◆ getProgram()

virtual Program* Block::getProgram | ( |  | ) | const
| pure virtual

Returns a pointer to the currently loaded program.

## ◆ sendProgramEvent()

virtual void Block::sendProgramEvent | ( | const ProgramEventMessage & |  | ) |
| pure virtual

Sends a message to the currently loaded program.

To receive the message the program must provide a littlefoot function called handleMessage with the following form:

void handleMessage (int param1, int param2, int param3)
{
// Do something with the two integer parameters that the app has sent...
}

## ◆ addProgramEventListener()

virtual void Block::addProgramEventListener | ( | ProgramEventListener * |  | ) |
| virtual

Adds a new listener for custom program events from the block.

## ◆ removeProgramEventListener()

virtual void Block::removeProgramEventListener | ( | ProgramEventListener * |  | ) |
| virtual

Removes a listener for custom program events from the block.

## ◆ getMemorySize()

virtual uint32 Block::getMemorySize | ( |  | ) |
| pure virtual

Returns the overall memory of the block.

## ◆ getHeapMemorySize()

virtual uint32 Block::getHeapMemorySize | ( |  | ) |
| pure virtual

Returns the size of the data block that setDataByte and other functions can write to.

## ◆ setDataByte()

virtual void Block::setDataByte | ( | size_t | offset,
|  | uint8 | value
| ) |  |
| pure virtual

Sets a single byte on the littlefoot heap.

## ◆ setDataBytes()

virtual void Block::setDataBytes | ( | size_t | offset,
|  | const void * | data,
|  | size_t | num
| ) |  |
| pure virtual

Sets multiple bytes on the littlefoot heap.

## ◆ setDataBits()

virtual void Block::setDataBits | ( | uint32 | startBit,
|  | uint32 | numBits,
|  | uint32 | value
| ) |  |
| pure virtual

Sets multiple bits on the littlefoot heap.

## ◆ getDataByte()

virtual uint8 Block::getDataByte | ( | size_t | offset | ) |
| pure virtual

Gets a byte from the littlefoot heap.

## ◆ saveProgramAsDefault()

virtual void Block::saveProgramAsDefault | ( |  | ) |
| pure virtual

Sets the current program as the block's default state.

## ◆ resetProgramToDefault()

virtual void Block::resetProgramToDefault | ( |  | ) |
| pure virtual

Resets the loaded program to the block's default state.

## ◆ getMaxConfigIndex()

virtual uint32 Block::getMaxConfigIndex | ( |  | ) |
| pure virtual

Returns the maximum number of config items available.

## ◆ isValidUserConfigIndex()

virtual bool Block::isValidUserConfigIndex | ( | uint32 | item | ) |
| pure virtual

Determine if this is a valid config item index.

## ◆ getLocalConfigValue()

virtual int32 Block::getLocalConfigValue | ( | uint32 | item | ) |
| pure virtual

Get local config item value.

## ◆ setLocalConfigValue()

virtual void Block::setLocalConfigValue | ( | uint32 | item,
|  | int32 | value
| ) |  |
| pure virtual

Set local config item value.

## ◆ setLocalConfigRange()

virtual void Block::setLocalConfigRange | ( | uint32 | item,
|  | int32 | min,
|  | int32 | max
| ) |  |
| pure virtual

Set local config item range.

## ◆ setLocalConfigItemActive()

virtual void Block::setLocalConfigItemActive | ( | uint32 | item,
|  | bool | isActive
| ) |  |
| pure virtual

Set if config item is active or not.

## ◆ isLocalConfigItemActive()

virtual bool Block::isLocalConfigItemActive | ( | uint32 | item | ) |
| pure virtual

Determine if config item is active or not.

## ◆ getLocalConfigMetaData()

virtual ConfigMetaData Block::getLocalConfigMetaData | ( | uint32 | item | ) |
| pure virtual

Get config item metadata.

## ◆ requestFactoryConfigSync()

virtual void Block::requestFactoryConfigSync | ( |  | ) |
| pure virtual

Request sync of factory config with block.

## ◆ resetConfigListActiveStatus()

virtual void Block::resetConfigListActiveStatus | ( |  | ) |
| pure virtual

Reset all items active status.

## ◆ factoryReset()

virtual void Block::factoryReset | ( |  | ) |
| pure virtual

Perform factory reset on Block.

## ◆ blockReset()

virtual void Block::blockReset | ( |  | ) |
| pure virtual

Reset this Block.

## ◆ setName()

virtual bool Block::setName | ( | const String & | name | ) |
| pure virtual

Set Block name.

## ◆ setLogger()

virtual void Block::setLogger | ( | std::function< void(const Block &block, const String &)> | loggingCallback | ) |
| pure virtual

Allows the user to provide a function that will receive log messages from the block.

## ◆ sendFirmwareUpdatePacket()

virtual bool Block::sendFirmwareUpdatePacket | ( | const uint8 * | data,
|  | uint8 | size,
|  | std::function< void(uint8, uint32)> | packetAckCallback
| ) |  |
| pure virtual

Sends a firmware update packet to a block, and waits for a reply.

Returns an error code.

## ◆ setConfigChangedCallback()

virtual void Block::setConfigChangedCallback | ( | std::function< void(Block &, const ConfigMetaData &, uint32)> |  | ) |
| pure virtual

Provides a callback that will be called when a config changes.

## ◆ setProgramLoadedCallback()

virtual void Block::setProgramLoadedCallback | ( | std::function< void(Block &)> | programLoaded | ) |
| pure virtual

Provides a callback that will be called when a program has been loaded.

## ◆ addDataInputPortListener()

virtual void Block::addDataInputPortListener | ( | DataInputPortListener * |  | ) |
| virtual

Adds a new listener for the data input port.

## ◆ removeDataInputPortListener()

virtual void Block::removeDataInputPortListener | ( | DataInputPortListener * |  | ) |
| virtual

Removes a listener for the data input port.

## ◆ sendMessage()

virtual void Block::sendMessage | ( | const void * | messageData,
|  | size_t | messageSize
| ) |  |
| pure virtual

Sends a message to the block.

## Member Data Documentation

## ◆ serialNumber

const String Block::serialNumber

The Block's serial number.

## ◆ versionNumber

String Block::versionNumber

The Block's version number.

## ◆ name

String Block::name

The Block's name.

## ◆ uid

const UID Block::uid

This Block's UID.

This will be globally unique, and remains constant for a particular device.

Referenced by operator!=(), and operator==().

## ◆ dataInputPortListeners

ListenerList<DataInputPortListener> Block::dataInputPortListeners
| protected

## ◆ programEventListeners

ListenerList<ProgramEventListener> Block::programEventListeners
| protected

The documentation for this class was generated from the following file:

- juce_Block.h

handleMessage
void handleMessage(int param1, int param2, int param3)
Called when a block receives a message.