Version
menu_open
link
Wwise SDK 2022.1.7
HostUndoManager.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /**
28  * \brief Wwise Authoring Plug-ins - API to provide custom undo event and manage undo groups.
29  * \file AK/Wwise/Plugin/HostUndoManager.h
30  */
31 
32 #pragma once
33 
34 #include "HostPropertySet.h"
35 
36 /**
37  * \brief API to create a custom undo event in a plug-in.
38  *
39  * This is useful when you handle custom properties, not handled by Property Sets.
40  */
41 struct ak_wwise_plugin_undo_event_v1
42 #ifdef __cplusplus
43  : public ak_wwise_plugin_base_interface
44 #endif
45 {
46 #ifndef __cplusplus
47  ak_wwise_plugin_base_interface m_baseInterface;
48 #endif
49 
50 #ifdef __cplusplus
51  /// Base instance type for providing custom undo operations.
52  using Instance = ak_wwise_plugin_undo_event_instance_v1;
53 
54  ak_wwise_plugin_undo_event_v1() :
55  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_UNDO_EVENT, 1)
56  {}
57  ak_wwise_plugin_undo_event_v1(decltype(m_interface) in_interface, decltype(m_version) in_version) :
58  ak_wwise_plugin_base_interface(in_interface, in_version)
59  {}
60  ak_wwise_plugin_undo_event_v1(std::underlying_type<decltype(m_interface)>::type in_interface, decltype(m_version) in_version) :
61  ak_wwise_plugin_base_interface((decltype(m_interface))in_interface, in_version)
62  {}
63 #endif
64 
65  /**
66  * \brief Called when the system needs to destroy your ak_wwise_plugin_undo_event_v1 instance.
67  *
68  * Since your plug-in created the instance, you are responsible for destroying it.
69  *
70  * \param[in] in_this Current instance of this Undo Event instance.
71  */
72  void(*Destroy)(struct ak_wwise_plugin_undo_event_instance_v1* in_this);
73 
74  /**
75  * \brief Called when the user asks to undo an action.
76  *
77  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
78  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
79  *
80  * \param[in] in_this Current instance of this Undo Event.
81  * \param[in] in_backend The backend instance that created this event.
82  */
83  bool(*Undo)(
84  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
85  struct ak_wwise_plugin_backend_instance* in_backend);
86 
87  /**
88  * \brief Called when the user asks to redo an action.
89  *
90  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
91  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
92  *
93  * \param[in] in_this Current instance of this Undo Event instance.
94  * \param[in] in_backend The backend instance that created this event.
95  */
96  bool(*Redo)(
97  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
98  struct ak_wwise_plugin_backend_instance* in_backend);
99 
100  /**
101  * \brief Get the event name, to show after the "Undo " and "Redo " terms in the menu.
102  *
103  * \param[in] in_this Current instance of this Undo Event.
104  * \param[out] out_csName Pointer to a static name for this event. The buffer is owned by Authoring and is
105  * valid until the next API call.
106  * \return true if successful.
107  */
108  bool(*GetName)(
109  const struct ak_wwise_plugin_undo_event_instance_v1* in_this,
110  const char ** out_csName);
111 };
112 #define AK_WWISE_PLUGIN_UNDO_EVENT_V1_ID() \
113  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_UNDO_EVENT, 1)
114 #define AK_WWISE_PLUGIN_UNDO_EVENT_V1_CTOR() \
115 { \
116  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_UNDO_EVENT_V1_ID()) \
117 }
118 
119 
120 /**
121  * \brief Host API to handle the plug-in's undo operations.
122  */
123 struct ak_wwise_plugin_host_undo_manager_v1
124 #ifdef __cplusplus
125  : public ak_wwise_plugin_base_interface
126 #endif
127 {
128 #ifndef __cplusplus
129  ak_wwise_plugin_base_interface m_baseInterface;
130 #endif
131 
132 #ifdef __cplusplus
133  /// Base host-provided instance type for ak_wwise_plugin_host_undo_manager_v1.
134  using Instance = ak_wwise_plugin_host_undo_manager_instance_v1;
135 
136  ak_wwise_plugin_host_undo_manager_v1() :
137  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_UNDO_MANAGER, 1)
138  {}
139 #endif
140 
141  /**
142  * \brief Open a group that will contain all subsequent undo events.
143  *
144  * This must be done prior to performing any action on PropertySets, or adding custom events, as it is important to
145  * have one unique element on the undo stack. You can open multiple groups at once, like a stack, as long as you
146  * close them before exiting your function.
147  *
148  * in_reopenGroupId should be set to 0 for a new group.
149  *
150  * Example:
151  * <code>
152  * ak_wwise_plugin_undo_group_id m_dragAndDropGroupId = 0;
153  * m_dragAndDropGroupId = OpenGroup(this, m_dragAndDropGroupId);
154  * if (m_dragAndDropGroupId == 0) return;
155  * CloseGroup(this,
156  * m_done ? AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY :
157  * AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE,
158  * "Drag and drop");
159  * if (m_done) m_dragAndDropGroupId = 0;
160  * </code>
161  *
162  * \param[in] in_this Current instance of this interface.
163  * \param[in] in_reopenGroupId Previously opened undo group, or 0 for a new group.
164  * \return The new undo group that just got created, or 0 if the system cannot open a group at the moment.
165  */
166  ak_wwise_plugin_undo_group_id (*OpenGroup)(
167  struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this,
168  ak_wwise_plugin_undo_group_id in_reopenGroupId);
169 
170  /**
171  * \brief Closes the last opened group, in stack ordering.
172  *
173  * Close the current group (_CLOSE) and add its content as a unique entry to the previous group,
174  * or to the Undo stack (_APPLY), or cancel its contents (_CANCEL).
175  *
176  * in_szApplyEventName is only used for _APPLY. It is ignored elsewhere, and needs to be nullptr on
177  * _APPLY_FIRST_EVENT_NAME or _APPLY_LAST_EVENT_NAME.
178  *
179  * in_groupId is only for validation, you can pass 0 if you do not wish to provide this validation.
180  *
181  * \akwarning Cancelling contents doesn't undo all the grouped actions. You are responsible for doing all the proper
182  * undoing before closing the group. \akwarning
183  *
184  * \param[in] in_this Current instance of this interface.
185  * \param[in] in_action Action to perform when closing the group. Should usually
186  * be AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY.
187  * \param[in] in_groupId (Optional, pass 0) Validation to make sure the group being closed has the proper ID.
188  * \param[in] in_szApplyEventName Event name. Added after "Undo " and "Redo " in the menu.
189  * \return true if successful.
190  */
191  bool(*CloseGroup)(
192  struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this,
193  ak_wwise_plugin_undo_group_close_action in_action,
194  ak_wwise_plugin_undo_group_id in_groupId,
195  const char * in_szApplyEventName);
196 
197  /**
198  * \brief Adds a custom event to the currently opened group.
199  *
200  * By default, you should be in a group while adding an event.
201  *
202  * \param[in] in_this Current instance of this interface.
203  * \param[in] in_event Event to add to the current group.
204  * \return true if successful.
205  */
206  bool(*AddCustomEvent)(
207  struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this,
208  struct ak_wwise_plugin_undo_event_pair_v1 in_event);
209 
210  /**
211  * \brief Check if we are currently in a state where we can add undo events.
212  *
213  * This is different than not being in a group. You should always be in a group when you want to add an event.
214  *
215  * \param[in] in_this Current instance of this interface.
216  * \return true if we can add an event.
217  */
218  bool(*CanAddEvent)(const struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this);
219 
220  /**
221  * \brief Check if we are busy (undoing or redoing).
222  *
223  * \param[in] in_this Current instance of this interface.
224  * \return true if we are currently performing an undo operation.
225  */
226  bool(*IsBusy)(const struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this);
227 
228  /**
229  * \brief Returns whether logging can occur or not.
230  *
231  * Call this function when you are about to log an undo event to know if Wwise is in a state
232  * where undos are enabled. Undo logging can be disabled for a particular plug-in object if
233  * it already lives in the undo stack or in the clipboard.
234  *
235  * This function is useful to determine whether a complex undo operation can be started without opening a
236  * new undo group (see \ref ak_wwise_plugin_host_undo_manager_v1::OpenGroup). Otherwise, the simple fact of
237  * opening an undo group will give a result of 0 if it's not possible to log undos at this time.
238  *
239  * \param[in] in_this Current instance of this interface.
240  * \return true if the plug-in can log undo events at this time.
241  */
242  bool(*CanLogUndos)(
243  const struct ak_wwise_plugin_host_undo_manager_instance_v1* in_this);
244 };
245 #define AK_WWISE_PLUGIN_HOST_UNDO_MANAGER_V1_ID() \
246  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_UNDO_MANAGER, 1)
247 #define AK_WWISE_PLUGIN_HOST_UNDO_MANAGER_V1_CTOR() \
248 { \
249  .m_baseInterface = AK_WWISE_PLUGIN_HOST_UNDO_MANAGER_V1_ID() \
250 }
251 
252 
253 #ifdef __cplusplus
254 namespace AK::Wwise::Plugin
255 {
256  namespace V1
257  {
258  using CUndoEvent = ak_wwise_plugin_undo_event_v1;
259  using CUndoEventPair = ak_wwise_plugin_undo_event_pair_v1;
260 
261  /**
262  * \brief Base API to create a custom undo event in a plug-in.
263  *
264  * This is useful when you handle custom properties, not handled by Property Sets.
265  *
266  * UndoEvent should be handled by the \ref UndoEvent template.
267  */
268  class BaseUndoEvent : public CUndoEvent::Instance
269  {
270  public:
271  /**
272  * \brief The interface type, as provided by this plug-in.
273  */
274  enum : InterfaceTypeValue
275  {
276  /**
277  * \brief The interface type, as provided by this plug-in.
278  */
279  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_UNDO_EVENT
280  };
281  /**
282  * \brief The interface version, as provided by this plug-in.
283  */
284  enum : InterfaceVersion
285  {
286  /**
287  * \brief The interface version, as provided by this plug-in.
288  */
289  k_interfaceVersion = 1
290  };
291 
292  using Interface = CUndoEvent;
293 
294  virtual Interface* GetInterfacePointer() = 0;
295 
296  CUndoEvent::Instance* GetInstancePointer() {
297  return this;
298  }
299 
300  const CUndoEvent::Instance* GetInstancePointer() const {
301  return this;
302  }
303 
304  BaseUndoEvent() :
305  CUndoEvent::Instance()
306  {
307  }
308 
309  virtual ~BaseUndoEvent() {}
310  };
311 
312  /**
313  * \brief Base API to create a custom undo event in a plug-in.
314  *
315  * This is useful when you handle custom properties, not handled by Property Sets.
316  *
317  * Undo events should be derived by your undo class, providing \ref UndoEvent::Undo,
318  * \ref UndoEvent::Redo and \ref UndoEvent::GetName methods.
319  *
320  * No pointer to the backend class should be kept inside the undo event, as the object can be deleted
321  * and recreated when the plug-in gets removed through undo. The backend will be recreated at that point,
322  * making the pointer invalid.
323  *
324  * \tparam Backend The plug-in backend type.
325  */
326  template<typename Backend>
327  class UndoEvent : public BaseUndoEvent
328  {
329  public:
330  struct Interface : public BaseUndoEvent::Interface
331  {
332  using Instance = UndoEvent;
333 
334  /**
335  * \brief The C interface, fulfilled by your plug-in.
336  */
337  Interface()
338  {
339  CUndoEvent::Destroy = [](
340  struct ak_wwise_plugin_undo_event_instance_v1* in_this)
341  {
342  delete static_cast<Instance*>(in_this);
343  };
344  CUndoEvent::Undo = [](
345  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
346  struct ak_wwise_plugin_backend_instance* in_backend)
347  {
348  return (bool)static_cast<Instance*>(in_this)->Undo(*static_cast<Backend*>(in_backend));
349  };
350  CUndoEvent::Redo = [](
351  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
352  struct ak_wwise_plugin_backend_instance* in_backend)
353  {
354  return (bool)static_cast<Instance*>(in_this)->Redo(*static_cast<Backend*>(in_backend));
355  };
356  CUndoEvent::GetName = [](
357  const struct ak_wwise_plugin_undo_event_instance_v1* in_this,
358  const char ** out_csName)
359  {
360  return (bool)static_cast<const Instance*>(in_this)->GetName(
361  out_csName);
362  };
363  }
364  };
365 
366  virtual BaseUndoEvent::Interface* GetInterfacePointer() final {
367  static Interface g_interface;
368  return &g_interface;
369  }
370 
371  /**
372  * \brief Called when the user asks to undo an action.
373  *
374  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
375  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
376  *
377  * \param[in] in_backend The backend instance that created this event.
378  */
379  virtual bool Undo(Backend& in_backend) = 0;
380 
381  /**
382  * \brief Called when the user asks to redo an action.
383  *
384  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
385  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
386  *
387  * \param[in] in_backend The backend instance that created this event.
388  */
389  virtual bool Redo(Backend& in_backend) = 0;
390 
391  /**
392  * \brief Get the event name, to show after the "Undo " and "Redo " terms in the menu.
393  *
394  * \param[out] out_csName Pointer to a static name for this event. This pointer needs to be accessible as long
395  * as the event is not destroyed.
396  * \return true if successful.
397  */
398  virtual bool GetName(const char ** out_csName) const = 0;
399  };
400 
401  template<typename BackendDerivedClass>
402  class DynamicUndoEvent : public BaseUndoEvent
403  {
404  public:
405  struct Interface : public BaseUndoEvent::Interface
406  {
407  using Instance = DynamicUndoEvent;
408 
409  /**
410  * \brief The C interface, fulfilled by your plug-in.
411  */
412  Interface()
413  {
414  CUndoEvent::Destroy = [](
415  struct ak_wwise_plugin_undo_event_instance_v1* in_this)
416  {
417  delete static_cast<Instance*>(in_this);
418  };
419  CUndoEvent::Undo = [](
420  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
421  struct ak_wwise_plugin_backend_instance* in_backend)
422  {
423  BackendDerivedClass *backend = dynamic_cast<BackendDerivedClass*>(in_backend);
424  if (backend)
425  return (bool)static_cast<Instance*>(in_this)->Undo(*backend);
426  else
427  return false;
428  };
429  CUndoEvent::Redo = [](
430  struct ak_wwise_plugin_undo_event_instance_v1* in_this,
431  struct ak_wwise_plugin_backend_instance* in_backend)
432  {
433  BackendDerivedClass *backend = dynamic_cast<BackendDerivedClass*>(in_backend);
434  if (backend)
435  return (bool)static_cast<Instance*>(in_this)->Redo(*backend);
436  else
437  return false;
438  };
439  CUndoEvent::GetName = [](
440  const struct ak_wwise_plugin_undo_event_instance_v1* in_this,
441  const char ** out_csName)
442  {
443  return (bool)static_cast<const Instance*>(in_this)->GetName(
444  out_csName);
445  };
446  }
447  };
448 
449  virtual BaseUndoEvent::Interface* GetInterfacePointer() final {
450  static Interface g_interface;
451  return &g_interface;
452  }
453 
454  /**
455  * \brief Called when the user asks to undo an action.
456  *
457  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
458  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
459  *
460  * \param[in] in_backend The backend instance that created this event.
461  */
462  virtual bool Undo(BackendDerivedClass& in_backend) = 0;
463 
464  /**
465  * \brief Called when the user asks to redo an action.
466  *
467  * \akwarning The backend instance is provided to you. You should never keep pointers to any plug-in instances
468  * or services, as these might have been deleted and recreated in the meantime. \endakwarning
469  *
470  * \param[in] in_backend The backend instance that created this event.
471  */
472  virtual bool Redo(BackendDerivedClass& in_backend) = 0;
473 
474  /**
475  * \brief Get the event name, to show after the "Undo " and "Redo " terms in the menu.
476  *
477  * \param[out] out_csName Pointer to a static name for this event. The buffer is owned by Authoring and is
478  * valid until the next API call.
479  * \return true if successful.
480  */
481  virtual bool GetName(const char ** out_csName) const = 0;
482  };
483 
484  using CHostUndoManager = ak_wwise_plugin_host_undo_manager_v1;
485 
486  /// \copydoc ak_wwise_plugin_host_undo_manager_v1
487  class UndoManager : public CBaseInstanceGlue<CHostUndoManager>
488  {
489  public:
490  using Interface = CHostUndoManager;
491 
492  /**
493  * \brief The interface type, as requested by this plug-in.
494  */
495  enum : InterfaceTypeValue
496  {
497  /**
498  * \brief The interface type, as requested by this plug-in.
499  */
500  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_UNDO_MANAGER
501  };
502  /**
503  * \brief The interface version, as requested by this plug-in.
504  */
505  enum : InterfaceVersion
506  {
507  /**
508  * \brief The interface version, as requested by this plug-in.
509  */
510  k_interfaceVersion = 1
511  };
512 
513  /**
514  * \brief Open a group that will contain all subsequent undo events.
515  *
516  * This must be done prior to performing any action on PropertySets, or adding custom events, as it is important to
517  * have one unique element on the undo stack. You can open multiple groups at once, like a stack, as long as you
518  * close them before exiting your function.
519  *
520  * in_reopenGroupId should be set to 0 for a new group.
521  *
522  * Example:
523  * <code>
524  * ak_wwise_plugin_undo_group_id m_dragAndDropGroupId = 0;
525  * m_dragAndDropGroupId = OpenGroup(this, m_dragAndDropGroupId);
526  * if (m_dragAndDropGroupId == 0) return;
527  * CloseGroup(this,
528  * m_done ? AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY :
529  * AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE,
530  * "Drag and drop");
531  * if (m_done) m_dragAndDropGroupId = 0;
532  * </code>
533  *
534  * \param[in] in_reopenGroupId Previously opened undo group, or 0 for a new group.
535  * \return The new undo group that just got created, or 0 if the system cannot open a group at the moment.
536  */
537  inline ak_wwise_plugin_undo_group_id OpenGroup(ak_wwise_plugin_undo_group_id in_reopenGroupId = 0)
538  {
539  return g_cinterface->OpenGroup(this, in_reopenGroupId);
540  }
541 
542  /**
543  * \brief Closes the last opened group, in stack ordering.
544  *
545  * Close the current group (_CLOSE) and add its content as a unique entry to the previous group,
546  * or to the Undo stack (_APPLY), or cancel its contents (_CANCEL).
547  *
548  * in_szApplyEventName is only used for _APPLY. It is ignored elsewhere, and needs to be nullptr on
549  * _APPLY_FIRST_EVENT_NAME or _APPLY_LAST_EVENT_NAME.
550  *
551  * in_groupId is only for validation, you can pass 0 if you do not wish to provide this validation.
552  *
553  * \akwarning Cancelling contents doesn't undo all the grouped actions. You are responsible for doing all the proper
554  * undoing before closing the group. \akwarning
555  *
556  * \param[in] in_action Action to perform when closing the group. Should usually
557  * be AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY.
558  * \param[in] in_groupId (Optional, pass 0) Validation to make sure the group being closed has the proper ID.
559  * \param[in] in_szApplyEventName Event name. Added after "Undo " and "Redo " in the menu.
560  * \return true if successful and necessary (contains real changes).
561  */
562  inline bool CloseGroup(
563  ak_wwise_plugin_undo_group_close_action in_action = AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY,
564  ak_wwise_plugin_undo_group_id in_groupId = 0,
565  const char * in_szApplyEventName = nullptr)
566  {
567  return MKBOOL(g_cinterface->CloseGroup(this, in_action, in_groupId, in_szApplyEventName));
568  }
569 
570  /**
571  * \brief Adds a custom event to the currently opened group.
572  *
573  * By default, you should be in a group while adding an event.
574  *
575  * \param[in] in_pEvent Event to add to the current group.
576  * \return true if successful.
577  */
578  inline bool AddCustomEvent(BaseUndoEvent* in_pEvent)
579  {
580  return MKBOOL(g_cinterface->AddCustomEvent(
581  this,
582  {in_pEvent->GetInterfacePointer(), in_pEvent->GetInstancePointer() }));
583  }
584 
585  /**
586  * \brief Check if we are currently in a state where we can add undo events.
587  *
588  * This is different than not being in a group. You should always be in a group when you want to add an event.
589  *
590  * \return true if we can add an event.
591  */
592  inline bool CanAddEvent() const
593  {
594  return MKBOOL(g_cinterface->CanAddEvent(this));
595  }
596 
597  /**
598  * \brief Check if we are busy (undoing or redoing).
599  *
600  * \return true if we are currently performing an undo operation.
601  */
602  inline bool IsBusy() const
603  {
604  return MKBOOL(g_cinterface->IsBusy(this));
605  }
606 
607  /**
608  * \brief Returns whether logging can occur or not.
609  *
610  * Call this function when you are about to log an undo event to know if Wwise is in a state
611  * where undos are enabled. Undo logging can be disabled for a particular plug-in object if
612  * it already lives in the undo stack or in the clipboard.
613  *
614  * This function is useful to determine whether a complex undo operation can be started without opening a
615  * new undo group (see \ref ak_wwise_plugin_host_undo_manager_v1::OpenGroup). Otherwise, the simple fact of
616  * opening an undo group will give a result of 0 if it's not possible to log undos at this time.
617  *
618  * \return true if the plug-in can log undo events at this time.
619  */
620  inline bool CanLogUndos() const { return g_cinterface->CanLogUndos(this) ? true : false; }
621  };
622 
623  /**
624  * \brief Requests an UndoManager interface, provided as m_undoManager variable.
625  *
626  * Deriving your plug-in class from RequestUndoManager will automatically request the UndoManager
627  * interface. From this point, you will be able to access the host-provided functions in the
628  * \c m_undoManager variable.
629  */
630  using RequestUndoManager = RequestedHostInterface<UndoManager>;
631 
632  } // of namespace V1
633 
634  /// Latest version of the C UndoEvent interface.
635  using CUndoEvent = V1::CUndoEvent;
636  /// Latest version of the C++ BaseUndoEvent interface.
637  using BaseUndoEvent = V1::BaseUndoEvent;
638 
639  /// Latest version of the C++ UndoEvent template helper.
640  template<typename Backend>
641  using UndoEvent = V1::UndoEvent<Backend>;
642  /// Latest version of the C++ DynamicUndoEvent template helper.
643  template<typename BackendDerivedClass>
644  using DynamicUndoEvent = V1::DynamicUndoEvent<BackendDerivedClass>;
645 
646  /// Latest version of the C UndoManager interface.
647  using CHostUndoManager = V1::CHostUndoManager;
648  /// Latest version of the C++ UndoManager interface.
649  using UndoManager = V1::UndoManager;
650  /// Latest version of the requested C++ UndoManager interface.
651  using RequestUndoManager = V1::RequestUndoManager;
652 
653  AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(UndoManager, undoManager);
654  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(BaseUndoEvent);
655  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(UndoManager);
656  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(BaseUndoEvent);
657  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(UndoManager);
658 
659  class AutoUndoGroup final
660  {
661  public:
662  AutoUndoGroup(
663  UndoManager& in_undoManager,
664  const char* in_applyEventName = nullptr,
665  ak_wwise_plugin_undo_group_id* in_reopenGroupId = nullptr,
666  ak_wwise_plugin_undo_group_close_action in_closeAction = AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY)
667  : m_undoManager(in_undoManager)
668  , m_applyEventName(nullptr)
669  , m_groupId(0)
670  , m_reopenGroupId(in_reopenGroupId ? in_reopenGroupId : &m_groupId)
671  , m_closeAction(in_closeAction)
672  {
673  if (in_applyEventName)
674  {
675  m_applyEventName = new char[strlen(in_applyEventName)+1];
676  strcpy(m_applyEventName, in_applyEventName);
677  }
678  if (m_undoManager.CanAddEvent())
679  {
680  *m_reopenGroupId = m_undoManager.OpenGroup(*m_reopenGroupId);
681  m_valid = m_reopenGroupId != 0;
682  AKASSERT(m_valid);
683  }
684  else
685  {
686  m_valid = false;
687  }
688  }
689 
690  ~AutoUndoGroup()
691  {
692  if (m_valid)
693  {
694  m_undoManager.CloseGroup(m_closeAction, *m_reopenGroupId, m_applyEventName);
695  switch (m_closeAction)
696  {
697  case AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY:
698  case AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_FIRST_EVENT_NAME:
699  case AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_LAST_EVENT_NAME:
700  case AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CANCEL:
701  *m_reopenGroupId = 0;
702  break;
703  case AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE:
704  default:
705  ;
706  }
707  }
708  delete[] m_applyEventName;
709  }
710 
711  // Cancel the group once the class is destroyed.
712  void Cancel()
713  {
714  m_closeAction = AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CANCEL;
715  }
716 
717  // Do not apply the group to the parent once it is closed.
718  void DontApply()
719  {
720  m_closeAction = AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE;
721  }
722 
723  bool IsValid()
724  {
725  return m_valid;
726  }
727 
728  UndoManager& m_undoManager;
729 
730  char* m_applyEventName;
731 
732  ak_wwise_plugin_undo_group_id m_groupId;
733  ak_wwise_plugin_undo_group_id* m_reopenGroupId;
734 
735  ak_wwise_plugin_undo_group_close_action m_closeAction;
736  bool m_valid;
737  };
738 } // of namespace AK::Wwise::Plugin
739 
740 #endif
ak_wwise_plugin_undo_event_v1::ak_wwise_plugin_undo_event_v1
ak_wwise_plugin_undo_event_v1()
Definition: HostUndoManager.h:54
AK.Wwise::Plugin::BaseUndoEvent
V1::BaseUndoEvent BaseUndoEvent
Latest version of the C++ BaseUndoEvent interface.
Definition: HostUndoManager.h:637
ak_wwise_plugin_undo_event_instance_v1
Base instance type for providing custom undo operations through ak_wwise_plugin_undo_event_v1.
Definition: PluginDef.h:868
AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE
@ AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CLOSE
Close this group session (going out of scope), but do not apply it yet.
Definition: PluginDef.h:958
ak_wwise_plugin_undo_event_v1::GetName
bool(* GetName)(const struct ak_wwise_plugin_undo_event_instance_v1 *in_this, const char **out_csName)
Get the event name, to show after the "Undo " and "Redo " terms in the menu.
Definition: HostUndoManager.h:108
AK.Wwise::Plugin::V1::UndoEvent::Interface::Interface
Interface()
The C interface, fulfilled by your plug-in.
Definition: HostUndoManager.h:337
ak_wwise_plugin_host_undo_manager_instance_v1
Base host-provided instance type for ak_wwise_plugin_host_undo_manager_v1.
Definition: PluginDef.h:654
ak_wwise_plugin_host_undo_manager_v1::AddCustomEvent
bool(* AddCustomEvent)(struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this, struct ak_wwise_plugin_undo_event_pair_v1 in_event)
Adds a custom event to the currently opened group.
Definition: HostUndoManager.h:206
ak_wwise_plugin_undo_event_v1::ak_wwise_plugin_undo_event_v1
ak_wwise_plugin_undo_event_v1(decltype(m_interface) in_interface, decltype(m_version) in_version)
Definition: HostUndoManager.h:57
ak_wwise_plugin_base_interface::m_interface
ak_wwise_plugin_interface_type m_interface
Interface type (see ak_wwise_plugin_interface_type)
Definition: PluginBaseInterface.h:121
ak_wwise_plugin_undo_event_v1::ak_wwise_plugin_undo_event_v1
ak_wwise_plugin_undo_event_v1(std::underlying_type< decltype(m_interface)>::type in_interface, decltype(m_version) in_version)
Definition: HostUndoManager.h:60
AK.Wwise::Plugin::V1::UndoManager
Host API to handle the plug-in's undo operations.
Definition: HostUndoManager.h:488
AK.Wwise::Plugin::V1::BaseUndoEvent
Base API to create a custom undo event in a plug-in.
Definition: HostUndoManager.h:269
AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY
@ AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY
Close this group session permanently, and apply its operations to the englobing group.
Definition: PluginDef.h:959
AK.Wwise::Plugin::V1::UndoManager::CloseGroup
bool CloseGroup(ak_wwise_plugin_undo_group_close_action in_action=AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY, ak_wwise_plugin_undo_group_id in_groupId=0, const char *in_szApplyEventName=nullptr)
Closes the last opened group, in stack ordering.
Definition: HostUndoManager.h:562
AK.Wwise::Plugin::V1::BaseUndoEvent::GetInstancePointer
const CUndoEvent::Instance * GetInstancePointer() const
Definition: HostUndoManager.h:300
ak_wwise_plugin_undo_event_v1::Undo
bool(* Undo)(struct ak_wwise_plugin_undo_event_instance_v1 *in_this, struct ak_wwise_plugin_backend_instance *in_backend)
Called when the user asks to undo an action.
Definition: HostUndoManager.h:83
AK.Wwise::Plugin::CBaseInterfaceGlue< CHostUndoManager >::g_cinterface
static GluedInterface * g_cinterface
The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host onc...
Definition: PluginInfoGenerator.h:89
AK.Wwise::Plugin::InterfaceVersion
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:50
ak_wwise_plugin_host_undo_manager_v1::OpenGroup
ak_wwise_plugin_undo_group_id(* OpenGroup)(struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this, ak_wwise_plugin_undo_group_id in_reopenGroupId)
Open a group that will contain all subsequent undo events.
Definition: HostUndoManager.h:166
AK_WWISE_PLUGIN_INTERFACE_TYPE_UNDO_EVENT
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_UNDO_EVENT
2021.1 Undo Event. ak_wwise_plugin_undo_event_v1
Definition: PluginBaseInterface.h:71
ak_wwise_plugin_undo_event_v1
API to create a custom undo event in a plug-in.
Definition: HostUndoManager.h:45
ak_wwise_plugin_undo_event_v1::Redo
bool(* Redo)(struct ak_wwise_plugin_undo_event_instance_v1 *in_this, struct ak_wwise_plugin_backend_instance *in_backend)
Called when the user asks to redo an action.
Definition: HostUndoManager.h:96
ak_wwise_plugin_host_undo_manager_v1::CanLogUndos
bool(* CanLogUndos)(const struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this)
Returns whether logging can occur or not.
Definition: HostUndoManager.h:242
HostPropertySet.h
Wwise Authoring Plug-ins - Plug-in API for property sets.
ak_wwise_plugin_base_interface::m_version
uint32_t m_version
Version of the interface.
Definition: PluginBaseInterface.h:122
AK.Wwise::Plugin::V1::UndoManager::k_interfaceType
@ k_interfaceType
The interface type, as requested by this plug-in.
Definition: HostUndoManager.h:500
AK.Wwise::Plugin::V1::UndoEvent::GetName
virtual bool GetName(const char **out_csName) const =0
Get the event name, to show after the "Undo " and "Redo " terms in the menu.
ak_wwise_plugin_host_undo_manager_v1::CanAddEvent
bool(* CanAddEvent)(const struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this)
Check if we are currently in a state where we can add undo events.
Definition: HostUndoManager.h:218
AK.Wwise::Plugin::V1::CUndoEvent
ak_wwise_plugin_undo_event_v1 CUndoEvent
Definition: HostUndoManager.h:258
AK.Wwise::Plugin::V1::CHostUndoManager
ak_wwise_plugin_host_undo_manager_v1 CHostUndoManager
Definition: HostUndoManager.h:484
AK.Wwise::Plugin::AutoUndoGroup::AutoUndoGroup
AutoUndoGroup(UndoManager &in_undoManager, const char *in_applyEventName=nullptr, ak_wwise_plugin_undo_group_id *in_reopenGroupId=nullptr, ak_wwise_plugin_undo_group_close_action in_closeAction=AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY)
Definition: HostUndoManager.h:662
AK.Wwise::Plugin::V1::UndoManager::AddCustomEvent
bool AddCustomEvent(BaseUndoEvent *in_pEvent)
Adds a custom event to the currently opened group.
Definition: HostUndoManager.h:578
AK.Wwise::Plugin::V1::BaseUndoEvent::GetInstancePointer
CUndoEvent::Instance * GetInstancePointer()
Definition: HostUndoManager.h:296
AK.Wwise::Plugin::V1::DynamicUndoEvent::GetName
virtual bool GetName(const char **out_csName) const =0
Get the event name, to show after the "Undo " and "Redo " terms in the menu.
AK.Wwise::Plugin::V1::UndoManager::CanLogUndos
bool CanLogUndos() const
Returns whether logging can occur or not.
Definition: HostUndoManager.h:620
AK.Wwise::Plugin::V1::DynamicUndoEvent::Undo
virtual bool Undo(BackendDerivedClass &in_backend)=0
Called when the user asks to undo an action.
ak_wwise_plugin_host_undo_manager_v1
Host API to handle the plug-in's undo operations.
Definition: HostUndoManager.h:127
AK.Wwise::Plugin::CBaseInstanceGlue
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
Definition: PluginInfoGenerator.h:104
ak_wwise_plugin_undo_group_id
int ak_wwise_plugin_undo_group_id
Unique identifier for a particular undo group. Useful to reopen an unapplied closed group session.
Definition: PluginDef.h:931
AK.Wwise::Plugin::AutoUndoGroup::m_reopenGroupId
ak_wwise_plugin_undo_group_id * m_reopenGroupId
Definition: HostUndoManager.h:733
AKASSERT
#define AKASSERT(Condition)
Definition: AkAssert.h:67
ak_wwise_plugin_undo_group_close_action
ak_wwise_plugin_undo_group_close_action
Action to apply once this undo group is closed.
Definition: PluginDef.h:957
ak_wwise_plugin_undo_event_v1::Destroy
void(* Destroy)(struct ak_wwise_plugin_undo_event_instance_v1 *in_this)
Called when the system needs to destroy your ak_wwise_plugin_undo_event_v1 instance.
Definition: HostUndoManager.h:72
AK.Wwise::Plugin::V1::DynamicUndoEvent::Interface::Interface
Interface()
The C interface, fulfilled by your plug-in.
Definition: HostUndoManager.h:412
AK.Wwise::Plugin::V1::UndoEvent
Base API to create a custom undo event in a plug-in.
Definition: HostUndoManager.h:328
ak_wwise_plugin_backend_instance
Plug-in backend instance.
Definition: PluginDef.h:535
AK.Wwise::Plugin::V1::BaseUndoEvent::GetInterfacePointer
virtual Interface * GetInterfacePointer()=0
AK.Wwise::Plugin::AutoUndoGroup::m_closeAction
ak_wwise_plugin_undo_group_close_action m_closeAction
Definition: HostUndoManager.h:735
ak_wwise_plugin_host_undo_manager_v1::IsBusy
bool(* IsBusy)(const struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this)
Check if we are busy (undoing or redoing).
Definition: HostUndoManager.h:226
AK.Wwise::Plugin::V1::DynamicUndoEvent::Redo
virtual bool Redo(BackendDerivedClass &in_backend)=0
Called when the user asks to redo an action.
ak_wwise_plugin_host_undo_manager_v1::CloseGroup
bool(* CloseGroup)(struct ak_wwise_plugin_host_undo_manager_instance_v1 *in_this, ak_wwise_plugin_undo_group_close_action in_action, ak_wwise_plugin_undo_group_id in_groupId, const char *in_szApplyEventName)
Closes the last opened group, in stack ordering.
Definition: HostUndoManager.h:191
AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_LAST_EVENT_NAME
@ AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_LAST_EVENT_NAME
Same than AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY, but copies the name of the last inner undo e...
Definition: PluginDef.h:961
AK.Wwise::Plugin::InterfaceTypeValue
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
Definition: PluginInfoGenerator.h:49
AK.Wwise::Plugin::V1::RequestUndoManager
RequestedHostInterface< UndoManager > RequestUndoManager
Requests an UndoManager interface, provided as m_undoManager variable.
Definition: HostUndoManager.h:630
AK.Wwise::Plugin::V1::BaseUndoEvent::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: HostUndoManager.h:279
AK.Wwise::Plugin::V1::UndoEvent::Undo
virtual bool Undo(Backend &in_backend)=0
Called when the user asks to undo an action.
AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CANCEL
@ AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_CANCEL
Close this group session permanently, and cancel all its internal operations. Undo operations are not...
Definition: PluginDef.h:962
AK.Wwise::Plugin::DynamicUndoEvent
V1::DynamicUndoEvent< BackendDerivedClass > DynamicUndoEvent
Latest version of the C++ DynamicUndoEvent template helper.
Definition: HostUndoManager.h:644
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
AK.Wwise::Plugin::V1::DynamicUndoEvent::GetInterfacePointer
virtual BaseUndoEvent::Interface * GetInterfacePointer() final
Definition: HostUndoManager.h:449
AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_UNDO_MANAGER
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_UNDO_MANAGER
2021.1 Undo Manager host service. ak_wwise_plugin_host_undo_manager_v1
Definition: PluginBaseInterface.h:81
AK.Wwise::Plugin::V1::UndoManager::CanAddEvent
bool CanAddEvent() const
Check if we are currently in a state where we can add undo events.
Definition: HostUndoManager.h:592
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
AK.Wwise::Plugin::V1::UndoEvent::GetInterfacePointer
virtual BaseUndoEvent::Interface * GetInterfacePointer() final
Definition: HostUndoManager.h:366
AK.Wwise::Plugin::V1::UndoEvent::Redo
virtual bool Redo(Backend &in_backend)=0
Called when the user asks to redo an action.
ak_wwise_plugin_undo_event_pair_v1
A definition of an undo event, with a specific interface and instance.
Definition: PluginDef.h:926
ak_wwise_plugin_host_undo_manager_v1::ak_wwise_plugin_host_undo_manager_v1
ak_wwise_plugin_host_undo_manager_v1()
Definition: HostUndoManager.h:136
AK.Wwise::Plugin::V1::UndoManager::IsBusy
bool IsBusy() const
Check if we are busy (undoing or redoing).
Definition: HostUndoManager.h:602
AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_FIRST_EVENT_NAME
@ AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY_FIRST_EVENT_NAME
Same than AK_WWISE_PLUGIN_UNDO_GROUP_CLOSE_ACTION_APPLY, but copies the name of the first inner undo ...
Definition: PluginDef.h:960
AK.Wwise::Plugin::V1::UndoManager::OpenGroup
ak_wwise_plugin_undo_group_id OpenGroup(ak_wwise_plugin_undo_group_id in_reopenGroupId=0)
Open a group that will contain all subsequent undo events.
Definition: HostUndoManager.h:537
MKBOOL
#define MKBOOL(cond)
Definition: PluginHelpers.h:74
AK.Wwise::Plugin::V1::UndoManager::k_interfaceVersion
@ k_interfaceVersion
The interface version, as requested by this plug-in.
Definition: HostUndoManager.h:510
AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE
#define AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(in_name, in_varname,...)
PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name,...
Definition: PluginInfoGenerator.h:237
AK.Wwise::Plugin::V1::BaseUndoEvent::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: HostUndoManager.h:289
AK.Wwise::Plugin::AutoUndoGroup::m_groupId
ak_wwise_plugin_undo_group_id m_groupId
Definition: HostUndoManager.h:732
AK.Wwise::Plugin::UndoManager
V1::UndoManager UndoManager
Latest version of the C++ UndoManager interface.
Definition: HostUndoManager.h:649
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
AK.Wwise::Plugin::UndoEvent
V1::UndoEvent< Backend > UndoEvent
Latest version of the C++ UndoEvent template helper.
Definition: HostUndoManager.h:641

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise