See kARAEditorViewRole.
Users will often reconfigure the plug-in view through scrolling, zooming, navigating lists of entities, etc. to select the subset of ARA entities that they currently need to view or edit. Those selection features can be implemented in the plug-in (which was the only available solution in ARA 1). However, the host applications already have established user workflows for selecting their representations of the ARA objects. Making those workflows available to the plug-ins is leads to a much more consistent, streamlined user experience. Since the views are implemented through the companion API, there is no matching ARA entity yet. Instead, the companion plug-in instance is used as a controller for its associated view. (Note that while some companion APIs allow for multiple views of a given plug-in used at the same time, this is not recommended when using ARA editor views.) These calls only affect views, not the audio rendering. They only should be made while the plug-in is showing its UI, or before entering this state (i.e. during GUI setup phase), in order to optimize resource usage. Accordingly, the host should send an update of the selection when (re-)opening an ARA plug-in view. These calls also may be made while changes are being made to the model graph (i.e. inside of pairs of ARADocumentControllerInterface::beginEditing() and ARADocumentControllerInterface::endEditing()).
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::EditorViewInterface, or extend the already implemented ARA::PlugIn::EditorView class as needed. For host developers this interface is wrapped by the ARA::Host::EditorView.
|
|
typedef struct ARAEditorViewRefMarkupType * | ARAEditorViewRef |
| | Reference to the plug-in side representation of a editor view (opaque to the host).
|
| |
◆ ARAViewSelection
Host generated ARA view selection.
Public Attributes |
|
ARASize | structSize |
| | Size-based struct versioning - see Versioned structs.
|
| |
|
ARASize | playbackRegionRefsCount |
| | Length of playbackRegionRefs.
|
| |
|
const ARAPlaybackRegionRef * | playbackRegionRefs |
| | Variable-sized C array listing the explicitly selected playback regions. The list may be empty, in which case count should be 0 and the pointer NULL. If the plug-in requires a playback region selections in its view, it can derive an implicit playback region selection from the region sequence selection and the time range in that case.
|
| |
|
ARASize | regionSequenceRefsCount |
| | Length of regionSequenceRefs.
|
| |
|
const ARARegionSequenceRef * | regionSequenceRefs |
| | Variable-sized C array listing the explicitly selected region sequences. The list may be empty, in which case count should be 0 and the pointer NULL. If the plug-in requires a region sequence selections in its view, it can derive an implicit region sequence selection from the playback region selection in that case.
|
| |
|
const ARAContentTimeRange * | timeRange |
| | Pointer to the explicitly selected time range. This pointer can be NULL to indicate that selection command does not include an explicit time range selection. If the plug-in requires a time range selection in its view, it can derive an implicit time range selection from the playback region selection, or if that isn't provided either it can evaluate the list of all playback regions of the selected region sequences.
|
| |
◆ ARAEditorViewInterface
| struct ARAEditorViewInterface |
Plug-in interface: view controller. The function pointers in this struct must remain valid until the document controller is destroyed by the host.
Size-based struct versioning |
See Versioned structs.
|
|
ARASize | structSize |
| |
Host UI notifications |
|
void(* | notifySelection )(ARAEditorViewRef editorViewRef, const ARAViewSelection *selection) |
| | Apply the given host selection to all associated views. This ARA 2.0 addition allows hosts to translate the effects of their selection implementation to a selection of ARA objects that can be interpreted by the plug-in. The command is not strict a setter for the given selection state, it rather notifies the plug-in about relevant user interaction in the host so that it can adopt in whatever way provides the best user experience within the context of the given plug-in design. A plug-in may e.g. implement scrolling to relevant positions, select the playback regions in its inspector(s), or filter the provided objects further depending on user settings. The plug-in also remains free to modify its internal selection at any time through its build-in UI behavior. For example, a plug-in may design its UI around individual regions being edited, or around entire region sequences. Melodyne features both modes, switchable by the user. When editing an individual region, it will always pick the "most suitable" region from the selection, and ignore the other selected regions. Melodyne also implements various ways to switch the editable region sequence(s) or playback region at any time independently from the host selection, as well as a user option to temporarily ignore host selection changes to "pin" the current selection. The same "loose" coupling applies on the host side: the selection sent by the host is not necessarily equal to its actual selection, but rather the best representation of the users' intent. For example, the user may be able to select entities that are not directly represented in the ARA API, but relate to a set of playback regions in some meaningful way. In that case, those regions may be sent as selection. The selection command includes various optional entities that describe the selection on the host side, such as playback regions or region sequences. Host will only explicitly provide those objects that best describe their current selection, but plug-ins can often derive other selections from that, such as calculating a region selection based on sequence selection and time range. Most hosts offer both an object-based selection which typically centers around selected arrange events (playback regions) and tracks (region sequences) versus a time-range based selection that is independent of the arrange events but typically also includes track selection. Both modes shall be distinguished by providing a time range only in the latter case. Some hosts even allow to select multiple time ranges, this should be expressed by sending their union range across the API. For an object-based selection, the time range remains NULL, and plug-ins can calculate an implicit time range from the selected playback regions if desired. Arrange event selection may linked to track selection in a variety of ways. For example, selecting a track may select its events (often filter by playback cycle range), and selecting an event may select its associated track as well. The ARA selection must be always updated to reflect any such linking accordingly. In each object list, objects are ordered by importance, with the most relevant, "focused" object being first. So if a plug-in supports only a single region selection, it should use the first region. If it can only show a single region sequence at a time, it should use the first selected sequence, or if no sequences are included in the selection fall back to the sequence of the first selected region, etc. Each new selection call describes a full selection, i.e. replaces the previous selection. An empty selection is valid and should be communicated by the host, since some plug-ins may need to evaluate this in special cases. Being selected does not affect the life time of the objects - selected objects may be deleted without updating the selection status first. Note that a pointer to this struct and all pointers contained therein are only valid for the duration of the current call receiving the pointer - the data must be evaluated/copied inside the call, and the pointers must not be stored anywhere.
|
| |
|
void(* | notifyHideRegionSequences )(ARAEditorViewRef editorViewRef, ARASize regionSequenceRefsCount, const ARARegionSequenceRef regionSequenceRefs[]) |
| | Reflect hiding of region sequences in all associated views. Some hosts offer the option to hide arrange tracks from view, so that they are no longer visible, while still being played back regularly. This can be communicated to the plug-in so that it follows suite. Each call implicitly unhides all previously hidden region sequences, so calling this with an empty list makes all sequences visible. The regionSequenceRefs pointer is only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. It should be NULL if regionSequenceRefsCount is 0.
|
| |