IControl

Base class for all UI controls in iPlug2

IControl

The IControl class is the lowest level base class for all UI controls in IGraphics. Every visible and interactive element in your plugin UI inherits from IControl.

Overview

IControl provides:

• Mouse and keyboard event handling
• Parameter linking and value management
• Drawing interface
• Animation support
• Touch and gesture support

Constructors

Basic Constructor

IControl(const IRECT& bounds, int paramIdx = kNoParameter, IActionFunction actionFunc = nullptr)

bounds · const IRECT& · required

The rectangular area the control occupies

paramIdx · int · default: "kNoParameter"

Parameter index to link this control to (-1 for no parameter)

actionFunc · IActionFunction · default: "nullptr"

Lambda function called when the control action occurs

Example

IRECT bounds(10, 10, 110, 110);
auto* control = new IControl(bounds, kGain);

Multi-Parameter Constructor

IControl(const IRECT& bounds, const std::initializer_list<int>& params,
        IActionFunction actionFunc = nullptr)

Create a control linked to multiple parameters.

params · const std::initializer_list<int>& · required

List of parameter indexes

Example

auto* control = new IControl(bounds, {kGain, kPan, kWidth});

Action-Only Constructor

IControl(const IRECT& bounds, IActionFunction actionFunc)

Create a control not linked to any parameter.

Core Methods

Draw

virtual void Draw(IGraphics& g) = 0

Draw the control. This is a pure virtual function that must be implemented.

g · IGraphics& · required

Reference to the graphics context

Example

void MyControl::Draw(IGraphics& g) {
  g.FillRect(COLOR_BLUE, mRECT);
  g.DrawText(mText, mValueStr.Get(), mRECT);
}

OnInit

virtual void OnInit()

Called when the control is attached, after delegate and graphics are set. Use this for initialization that requires the graphics context.

OnAttached

virtual void OnAttached()

Called after the control is fully attached. Use for controls that attach sub-controls.

OnResize

virtual void OnResize()

Called when the control is constructed or resized via SetRECT().

If you call SetDirty() in OnResize(), use SetDirty(false) to avoid triggering parameter changes.

Mouse Events

OnMouseDown

virtual void OnMouseDown(float x, float y, const IMouseMod& mod)

Called when the mouse is pressed down on this control.

x · float · required

X coordinate of the mouse event

y · float · required

Y coordinate of the mouse event

mod · const IMouseMod& · required

Struct with modifier key states

Example

void MyControl::OnMouseDown(float x, float y, const IMouseMod& mod) {
  if (mod.R) {
    // Right click - show context menu
  } else if (mod.S) {
    // Shift + click
  }
  SetDirty(true);
}

OnMouseUp

virtual void OnMouseUp(float x, float y, const IMouseMod& mod)

Called when the mouse button is released.

OnMouseDrag

virtual void OnMouseDrag(float x, float y, float dX, float dY, const IMouseMod& mod)

Called when the mouse is dragged over this control.

dX · float · required

X delta since last event

dY · float · required

Y delta since last event

OnMouseDblClick

virtual void OnMouseDblClick(float x, float y, const IMouseMod& mod)

Called on double-click.

OnMouseWheel

virtual void OnMouseWheel(float x, float y, const IMouseMod& mod, float d)

Called when the mouse wheel is scrolled over this control.

d · float · required

Delta value (positive = up/forward, negative = down/backward)

OnMouseOver

virtual void OnMouseOver(float x, float y, const IMouseMod& mod)

Called when the mouse moves over this control. Implementations should call the base class to use mMouseIsOver.

OnMouseOut

virtual void OnMouseOut()

Called when the mouse leaves this control.

Keyboard Events

OnKeyDown

virtual bool OnKeyDown(float x, float y, const IKeyPress& key)

Handle key press events.

return · bool

True if the key was handled

OnKeyUp

virtual bool OnKeyUp(float x, float y, const IKeyPress& key)

Handle key release events.

Parameter Management

GetParamIdx

int GetParamIdx(int valIdx = 0) const

Get the parameter index linked to this control.

valIdx · int · default: "0"

Value index for multi-value controls

return · int

Parameter index or kNoParameter if not linked

SetParamIdx

virtual void SetParamIdx(int paramIdx, int valIdx = 0)

Set the parameter index for this control.

GetValue

double GetValue(int valIdx = 0) const

Get the control’s normalized value (0-1).

return · double

Normalized value in the range 0-1

SetValue

virtual void SetValue(double value, int valIdx = 0)

Set the control’s normalized value.

value · double · required

Normalized value (0-1)

Example

SetValue(0.5); // Set to 50%

SetValueFromDelegate

virtual void SetValueFromDelegate(double value, int valIdx = 0)

Called by the delegate to update the control’s value. Sets the control dirty for redraw.

SetValueFromUserInput

virtual void SetValueFromUserInput(double value, int valIdx = 0)

Set value after user input (text entry or popup menu). Calls SetDirty(true) to send the value back to the delegate.

SetValueToDefault

virtual void SetValueToDefault(int valIdx = kNoValIdx)

Reset value(s) to the default parameter value.

valIdx · int · default: "kNoValIdx"

Specific value index, or kNoValIdx to reset all values

GetParam

const IParam* GetParam(int valIdx = 0) const

Get the IParam associated with this control.

return · const IParam*

Pointer to IParam or nullptr if not linked

User Interaction

PromptUserInput

void PromptUserInput(int valIdx = 0)

Create a text entry box or popup menu for parameter input.

Example

void MyControl::OnMouseDown(float x, float y, const IMouseMod& mod) {
  if (mod.R) {
    PromptUserInput(); // Show text entry or menu
  }
}

OnPopupMenuSelection

virtual void OnPopupMenuSelection(IPopupMenu* pSelectedMenu, int valIdx)

Handle popup menu selection. Override to customize behavior.

OnTextEntryCompletion

virtual void OnTextEntryCompletion(const char* str, int valIdx)

Handle text entry completion. Override to customize behavior.

CreateContextMenu

virtual void CreateContextMenu(IPopupMenu& contextMenu)

Add custom items to the right-click context menu.

Example

void MyControl::CreateContextMenu(IPopupMenu& menu) {
  menu.AddItem("Reset to Default");
  menu.AddItem("Learn MIDI CC");
}

OnContextSelection

virtual void OnContextSelection(int itemSelected)

Handle context menu selection.

Bounds and Layout

GetRECT

const IRECT& GetRECT() const

Get the control’s draw area.

return · const IRECT&

The control’s bounds

SetRECT

void SetRECT(const IRECT& bounds)

Set the control’s draw area and call OnResize().

GetTargetRECT

const IRECT& GetTargetRECT() const

Get the mouse tracking target area.

SetTargetRECT

void SetTargetRECT(const IRECT& bounds)

Set the mouse tracking target area.

SetTargetAndDrawRECTs

void SetTargetAndDrawRECTs(const IRECT& bounds)

Set both the draw rect and target area to the same bounds.

SetPosition

virtual void SetPosition(float x, float y)

Move the control to a new position, preserving size.

SetSize

virtual void SetSize(float w, float h)

Resize the control, preserving position.

IsHit

virtual bool IsHit(float x, float y) const

Test if a point hits this control.

return · bool

True if the control was hit

Override IsHit() for controls with non-rectangular hit areas (e.g., circular buttons).

State Management

SetDirty

virtual void SetDirty(bool triggerAction = true, int valIdx = kNoValIdx)

Mark the control for redraw.

triggerAction · bool · default: "true"

If true and control is linked to a parameter, notify the delegate of the change

valIdx · int · default: "kNoValIdx"

Specific value index or kNoValIdx for all

SetDirty() always marks the control for redraw. The parameter only affects whether actions are triggered.

IsDirty

virtual bool IsDirty()

Check if the control needs redrawing.

Hide

virtual void Hide(bool hide)

Show or hide the control.

IsHidden

bool IsHidden() const

Check if the control is hidden.

SetDisabled

virtual void SetDisabled(bool disable)

Disable or enable the control.

IsDisabled

bool IsDisabled() const

Check if the control is disabled.

SetIgnoreMouse

virtual void SetIgnoreMouse(bool ignore)

Make the control ignore mouse events.

Animation

SetAnimation

void SetAnimation(IAnimationFunction func, int duration)

Set an animation function and start it.

func · IAnimationFunction · required

Animation function called each frame

duration · int · required

Duration in milliseconds

Example

SetAnimation([](IControl* pCaller) {
  double progress = pCaller->GetAnimationProgress();
  // Animate based on progress (0.0 to 1.0)
}, 300);

StartAnimation

void StartAnimation(int duration)

Start a previously set animation.

OnEndAnimation

virtual void OnEndAnimation()

Called when animation completes. Override to perform cleanup.

GetAnimationProgress

double GetAnimationProgress() const

Get animation progress (0.0 to 1.0).

return · double

Current animation progress

Action Functions

SetActionFunction

IControl* SetActionFunction(IActionFunction actionFunc)

Set a custom action function.

return · IControl*

Pointer to this control (for chaining)

Example

pControl->SetActionFunction([](IControl* pCaller) {
  DBGMSG("Control value: %f\n", pCaller->GetValue());
});

SetAnimationEndActionFunction

IControl* SetAnimationEndActionFunction(IActionFunction actionFunc)

Set an action function called when animation ends.

Appearance

GetText

const IText& GetText() const

Get the control’s text style.

SetText

virtual void SetText(const IText& txt)

Set the control’s text style.

SetBlend

void SetBlend(const IBlend& blend)

Set the control’s blend mode.

GetBlend

IBlend GetBlend() const

Get the control’s blend mode.

SetTooltip

IControl* SetTooltip(const char* str)

Set a tooltip for this control.

return · IControl*

Pointer to this control (for chaining)

GetTooltip

const char* GetTooltip() const

Get the tooltip text.

Grouping and Tagging

SetGroup

void SetGroup(const char* groupName)

Assign the control to a group.

Example

pControl->SetGroup("filterSection");

GetGroup

const char* GetGroup() const

Get the control’s group name.

GetTag

int GetTag() const

Get the control’s tag (assigned via AttachControl).

Context Access

GetUI

IGraphics* GetUI()

Get pointer to the IGraphics context.

GetDelegate

IGEditorDelegate* GetDelegate()

Get pointer to the editor delegate.

GetParent

IContainerBase* GetParent() const

Get pointer to the parent container (if any).

GetMouseIsOver

bool GetMouseIsOver() const

Check if mouse is over this control.

Only valid if IGraphics::EnableMouseOver(true) has been called.

Utility Methods

SnapToMouse

virtual void SnapToMouse(float x, float y, EDirection direction, const IRECT& bounds,
                        int valIdx = -1, double minClip = 0., double maxClip = 1.)

Set control value based on x,y position within a rectangle. Commonly used for sliders/faders.

direction · EDirection · required

Horizontal or vertical direction

bounds · const IRECT& · required

Track area bounds

As

template <class T>
T* As()

Dynamic cast helper to convert to a subclass.

Example

if (auto* knob = pControl->As<IVKnobControl>()) {
  knob->SetGearing(2.0);
}

Base Control Classes

IContainerBase

class IContainerBase : public IControl

Base class for controls that contain child controls. Automatically clips child drawing and manages child visibility/state.

Example

class MyPanel : public IContainerBase {
public:
  MyPanel(const IRECT& bounds) : IContainerBase(bounds) {}
  
  void OnAttached() override {
    AddChildControl(new IVKnobControl(mRECT.GetGridCell(0, 2, 1), kGain));
    AddChildControl(new IVKnobControl(mRECT.GetGridCell(1, 2, 1), kPan));
  }
};

IKnobControlBase

class IKnobControlBase : public IControl

Base class for knob/dial controls with standard mouse handling and gearing.

Key Features:

• Vertical or horizontal drag direction
• Configurable gearing/sensitivity
• Fine control with modifier keys
• Auto-hide cursor during drag

ISliderControlBase

class ISliderControlBase : public IControl

Base class for slider/fader controls with track-based mouse handling.

Key Features:

• Click-to-jump or drag-only modes
• Track bounds management
• Handle sizing
• Gearing support

Example Usage

Custom Control

class MyCustomControl : public IControl {
public:
  MyCustomControl(const IRECT& bounds, int paramIdx)
  : IControl(bounds, paramIdx) {}
  
  void Draw(IGraphics& g) override {
    // Draw background
    g.FillRoundRect(COLOR_DARK_GRAY, mRECT, 5.f);
    
    // Draw value indicator
    IRECT valueRect = mRECT.FracRectVertical(GetValue());
    g.FillRoundRect(COLOR_BLUE, valueRect, 5.f);
    
    // Draw text
    if (const IParam* pParam = GetParam()) {
      WDL_String str;
      pParam->GetDisplayForHost(str);
      g.DrawText(mText, str.Get(), mRECT);
    }
  }
  
  void OnMouseDown(float x, float y, const IMouseMod& mod) override {
    SnapToMouse(x, y, EDirection::Vertical, mRECT);
  }
  
  void OnMouseDrag(float x, float y, float dX, float dY, const IMouseMod& mod) override {
    SnapToMouse(x, y, EDirection::Vertical, mRECT);
  }
};

See Also

IGraphics

Graphics context and drawing API

IGraphics Structs

Supporting data structures (IRECT, IColor, etc.)