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

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