| AAX SDK 2.8.0 Avid Audio Extensions Development Kit

- Welcome
- Manual
- Classes
- Files
- Lists
- Support

- Class List
- Class Index
- Class Hierarchy
- Class Members

Loading...
Searching...
No Matches
List of all members
AAX_IACFEffectGUI Class Referenceabstract
AAX SDK Manual » Core AAX Interface » GUI interface

`#include <AAX_IACFEffectGUI.h>`

Inheritance diagram for AAX_IACFEffectGUI:
[legend]
Collaboration diagram for AAX_IACFEffectGUI:
[legend]

## Description

The interface for a AAX Plug-in's GUI (graphical user interface).

This is the interface for an instance of a plug-in's GUI that gets exposed to the host application. The AAX host interacts with your plug-in's GUI via this interface. See GUI interface.

The plug-in's implementation of this interface is responsible for managing the plug-in's window and graphics objects and for defining the interactions between GUI views and the plug-in's data model.

At initialization, the host provides this interface with a reference to AAX_IController. The GUI may use this controller to retrieve a pointer to the plug-in's AAX_IEffectParameters interface, allowing the GUI to request changes to the plug-in's data model in response to view events. In addition, the controller provides a means of querying information from the host such as stem format or sample rate

When managing a plug-in's GUI it is important to remember that this is just one of many possible sets of views for the plug-in's parameters. Other views and editors, such as automation lanes or control surfaces, also have the ability to synchronously interact with the plug-in's abstract data model interface. Therefore, the GUI should not take asymmetric control over the data model, act as a secondary data model, or otherwise assume exclusive ownership of the plug-in's state. In general, the data model's abstraction to a pure virtual interface will protect against such aberrations, but this remains an important consideration when managing sophisiticated GUI interactions.

You will most likely inherit your implementation of this interface from AAX_CEffectGUI, a default implementation that provides basic GUI functionality and which you can override and customize as needed.

The SDK includes several examples of how the GUI interface may be extended and implemented in order to provide support for third-party frameworks. These examples can be found in the /Extensions/GUI directory in the SDK.

Note
  Your implementation of this interface must inherit from AAX_IEffectGUI.

Legacy Porting Notes:
  In the legacy plug-in SDK, these methods were found in CProcess and CEffectProcess. For additional CProcess methods, see AAX_IEffectParameters.

## Public Member Functions
Initialization and uninitialization
virtual AAX_Result | Initialize (IACFUnknown *iController)=0
| Main GUI initialization.
virtual AAX_Result | Uninitialize ()=0
| Main GUI uninitialization.
AAX host and plug-in event notification
virtual AAX_Result | NotificationReceived (AAX_CTypeID inNotificationType, const void *inNotificationData, uint32_t inNotificationDataSize)=0
| Notification Hook.
View accessors
virtual AAX_Result | SetViewContainer (IACFUnknown *iViewContainer)=0
| Provides a handle to the main plug-in window.
virtual AAX_Result | GetViewSize (AAX_Point *oViewSize) const =0
| Retrieves the size of the plug-in window.
GUI update methods
virtual AAX_Result | Draw (AAX_Rect *iDrawRect)=0
| DEPRECATED, Not called from host any longer. Your chosen graphics framework should be directly handling draw events from the OS.
virtual AAX_Result | TimerWakeup ()=0
| Periodic wakeup callback for idle-time operations.
virtual AAX_Result | ParameterUpdated (AAX_CParamID inParamID)=0
| Notifies the GUI that a parameter value has changed.
Host interface methods
Miscellaneous methods to provide host-specific functionality
virtual AAX_Result | GetCustomLabel (AAX_EPlugInStrings iSelector, AAX_IString *oString) const =0
| Called by host application to retrieve a custom plug-in string.
virtual AAX_Result | SetControlHighlightInfo (AAX_CParamID iParameterID, AAX_CBoolean iIsHighlighted, AAX_EHighlightColor iColor)=0
| Called by host application. Indicates that a control widget should be updated with a highlight color.
Public Member Functions inherited from IACFUnknown
virtual BEGIN_ACFINTERFACE ACFRESULT ACFMETHODCALLTYPE | QueryInterface (const acfIID &iid, void **ppOut)=0
| Returns pointers to supported interfaces.
virtual acfUInt32 ACFMETHODCALLTYPE | AddRef (void)=0
| Increments reference count.
virtual acfUInt32 ACFMETHODCALLTYPE | Release (void)=0
| Decrements reference count.

## Member Function Documentation

## ◆ Initialize()

virtual AAX_Result AAX_IACFEffectGUI::Initialize | ( | IACFUnknown * | iController | ) |
| pure virtual

Main GUI initialization.

Called when the GUI is created

Parameters

  [in] | iController | A versioned reference that resolves to an AAX_IController interface

Implemented in AAX_CEffectGUI.

## ◆ Uninitialize()

virtual AAX_Result AAX_IACFEffectGUI::Uninitialize | ( |  | ) |
| pure virtual

Main GUI uninitialization.

Called when the GUI is destroyed. Frees the GUI.

Implemented in AAX_CEffectGUI.

## ◆ NotificationReceived()

virtual AAX_Result AAX_IACFEffectGUI::NotificationReceived | ( | AAX_CTypeID | inNotificationType,
|  | const void * | inNotificationData,
|  | uint32_t | inNotificationDataSize
| ) |  |
| pure virtual

Notification Hook.

Called from the host to deliver notifications to this object.

Look at the AAX_ENotificationEvent enumeration to see a description of events you can listen for and the data they come with.

- Note
    some notifications are sent only to the plug-in GUI while other notifications are sent only to the plug-in data model. If you are not seeing an expected notification, try checking the other plug-in objects' `NotificationReceived()` methods.
- Note
    the host may dispatch notifications synchronously or asynchronously, and calls to this method may occur concurrently on multiple threads.
  A plug-in may also dispatch custom notifications using AAX_IController::SendNotification(). Custom notifications will be posted back to the plug-in's other objects which support a `NotificationReceived()` method (e.g. the data model).

Parameters

  [in] | inNotificationType | Type of notification being received. Notifications form the host are one of AAX_ENotificationEvent
  [in] | inNotificationData | Block of incoming notification data
  [in] | inNotificationDataSize | Size of `inNotificationData`, in bytes

Implemented in AAX_CEffectGUI.

## ◆ SetViewContainer()

virtual AAX_Result AAX_IACFEffectGUI::SetViewContainer | ( | IACFUnknown * | iViewContainer | ) |
| pure virtual

Provides a handle to the main plug-in window.

Parameters

  [in] | iViewContainer | An AAX_IViewContainer providing a native handle to the plug-in's window

Implemented in AAX_CEffectGUI.

## ◆ GetViewSize()

virtual AAX_Result AAX_IACFEffectGUI::GetViewSize | ( | AAX_Point * | oViewSize | ) | const
| pure virtual

Retrieves the size of the plug-in window.

See also
  AAX_IViewContainer::SetViewSize()

Parameters

  [out] | oViewSize | The size of the plug-in window as a point (width, height)

Implemented in AAX_CEffectGUI.

## ◆ Draw()

virtual AAX_Result AAX_IACFEffectGUI::Draw | ( | AAX_Rect * | iDrawRect | ) |
| pure virtual

DEPRECATED, Not called from host any longer. Your chosen graphics framework should be directly handling draw events from the OS.

Implemented in AAX_CEffectGUI.

## ◆ TimerWakeup()

virtual AAX_Result AAX_IACFEffectGUI::TimerWakeup | ( |  | ) |
| pure virtual

Periodic wakeup callback for idle-time operations.

GUI animation events such as meter updates should be triggered from this method.

This method is called from the host's main thread. In general, it should be driven at approximately one call per 30 ms. However, the wakeup is not guaranteed to be called at any regular interval - for example, it could be held off by a high real-time processing load - and there is no host contract regarding maximum latency between wakeup calls.

This wakeup runs continuously and cannot be armed/disarmed by the plug-in.

Implemented in AAX_CEffectGUI.

## ◆ ParameterUpdated()

virtual AAX_Result AAX_IACFEffectGUI::ParameterUpdated | ( | AAX_CParamID | inParamID | ) |
| pure virtual

Notifies the GUI that a parameter value has changed.

This method is called by the host whenever a parameter value has been modified

This method may be called on a non-main thread

Implemented in AAX_CEffectGUI.

## ◆ GetCustomLabel()

virtual AAX_Result AAX_IACFEffectGUI::GetCustomLabel | ( | AAX_EPlugInStrings | iSelector,
|  | AAX_IString * | oString
| ) |  | const
| pure virtual

Called by host application to retrieve a custom plug-in string.

If no string is provided then the host's default will be used.

Parameters

  [in] | iSelector | The requested strong. One of AAX_EPlugInStrings
  [out] | oString | The plug-in's custom value for the requested string

Implemented in AAX_CEffectGUI.

## ◆ SetControlHighlightInfo()

virtual AAX_Result AAX_IACFEffectGUI::SetControlHighlightInfo | ( | AAX_CParamID | iParameterID,
|  | AAX_CBoolean | iIsHighlighted,
|  | AAX_EHighlightColor | iColor
| ) |  |
| pure virtual

Called by host application. Indicates that a control widget should be updated with a highlight color.

Todo:
  Document this method

Legacy Porting Notes:
  This method was re-named from `SetControlHighliteInfo()`, its name in the legacy plug-in SDK.

Parameters

  [in] | iParameterID | ID of parameter whose widget(s) must be highlighted
  [in] | iIsHighlighted | True if turning highlight on, false if turning it off
  [in] | iColor | Desired highlight color. One of AAX_EHighlightColor

Implemented in AAX_CEffectGUI.

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

- AAX_IACFEffectGUI.h