Table of Contents

include/AK/Wwise/SourceControl/ISourceControlUtilities.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided 
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
00015 "Apache License"); you may not use this file except in compliance with the 
00016 Apache License. You may obtain a copy of the Apache License at 
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024   Version: <VERSION>  Build: <BUILDNUMBER>
00025   Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 /// \file
00029 /// Wwise source control plug-in utilities interface, used to create custom dialogs, display the progress dialog, and get
00030 /// the registry path needed to save the plug-in configuration.
00031 
00032 #ifndef _AK_WWISE_ISOURCECONTROLUTILITIES_H
00033 #define _AK_WWISE_ISOURCECONTROLUTILITIES_H
00034 
00035 #include <AK/SoundEngine/Common/AkTypes.h>
00036 
00037 #include "ISourceControlDialogBase.h"
00038 #include "ISourceControlOperationProgress.h"
00039 
00040 // Audiokinetic namespace
00041 namespace AK
00042 {
00043     // Audiokinetic Wwise namespace
00044     namespace Wwise
00045     {
00046         /// Wwise source control utilities interface. This interface is provided when the plug-in is initialized.
00047         /// With this interface, you can display a progress dialog, create custom dialogs, display message boxes, and
00048         /// save the plug-in configuration to the registry.
00049         class ISourceControlUtilities
00050         {
00051         public:
00052             /// Get a pointer to an AK::Wwise::ISourceControlOperationProgress interface, so you can display a simple progress dialog for the operation.
00053             /// \warning This function is not thread-safe.
00054             /// \return A pointer to an AK::Wwise::ISourceControlOperationProgress interface.
00055             virtual ISourceControlOperationProgress* GetProgressDialog() = 0;
00056 
00057             /// This function does the same thing as the standard ::MessageBox function, except that this one will
00058             /// be displayed with the Wwise UI look and feel.
00059             /// \warning This function is not thread-safe.
00060             /// \return The window results of the dialog
00061             virtual int MessageBox( 
00062                 HWND in_hWnd,                   ///< The window handle of the dialog
00063                 LPCWSTR in_pszText,             ///< The text to be displayed in the message box
00064                 LPCWSTR in_pszCaption,          ///< The caption of the message box
00065                 UINT in_uiType                  ///< The window message box type (e.g. MB_OK)
00066                 ) = 0;
00067 
00068             /// This function show a dialog with a edit field and allow the user enter input string
00069             /// \warning This function is not thread-safe.
00070             /// \return The window results of the dialog: IDOK or IDCANCEL
00071             virtual int PromptMessage( 
00072                 HWND in_hWnd,                   ///< The window handle of the dialog
00073                 LPCWSTR in_pszText,             ///< The text to be displayed in the message box
00074                 LPCWSTR in_pszCaption,          ///< The caption of the message box
00075                 LPWSTR out_pszInput,            ///< The buffer to receive the user input
00076                 UINT in_uiInputSize,            ///< The size of the buffer to receive input
00077                 bool in_bIsPassword             ///< True to hide text; used for passwords
00078                 ) = 0;
00079     
00080             /// Show a browse for folder dialog.  
00081             /// \warning This function is not thread-safe.
00082             /// \return The resulting path is set in out_pszChoosenPath
00083             /// \return True if user clicked OK, false if user clicked Cancel
00084             virtual bool ShowBrowseForFolderDialog(
00085                 LPCWSTR in_pszDialogTitle,          ///< The dialog title
00086                 LPWSTR out_pszChoosenPath,          ///< The choosen path
00087                 UINT in_uiChoosenPathSize,          ///< The size of the buffer to receive path (out_pszChoosenPath)
00088                 LPCWSTR in_pszRootPath = NULL       ///< The root path for the browse for folder dialog
00089                 ) = 0;
00090 
00091             /// This function does the same thing as the CDialog::DoModal function.
00092             /// \warning This function is not thread-safe.
00093             /// \return The window results of the dialog (e.g. IDOK)
00094             virtual INT_PTR CreateModalCustomDialog( 
00095                 ISourceControlDialogBase* in_pDialog    ///< A pointer to a dialog class that implements 
00096                                                         ///< AK::Wwise::ISourceControlDialogBase functions.
00097                 ) = 0;
00098 
00099             /// Get the path to the registry for the current project. This path is to be used with
00100             /// the HKEY_CURRENT_USER registry key.
00101             /// \warning This function is not thread-safe.
00102             /// \return A string containing the registry path.
00103             virtual LPCWSTR GetRegistryPath() = 0;
00104 
00105             /// Set DWORD value in user preferences.
00106             /// \warning This function is not thread-safe.
00107             virtual void SetUserPreferenceDword(
00108                 LPCWSTR in_pszPreference,       ///< Name of preference
00109                 DWORD in_dwValue                ///< Value to set in user preferences.
00110                 ) = 0;
00111 
00112             /// Get DWORD value in user preferences.
00113             /// \warning This function is not thread-safe.
00114             virtual void GetUserPreferenceDword(
00115                 LPCWSTR in_pszPreference,       ///< Name of preference
00116                 DWORD& io_dwValue               ///< in: value to return if preference is not set; out: changed to user preference value if set
00117                 ) = 0;
00118 
00119             /// Set string value in user preferences.
00120             /// \warning This function is not thread-safe.
00121             virtual void SetUserPreferenceString(
00122                 LPCWSTR in_pszPreference,       ///< Name of preference
00123                 LPCWSTR in_pszValue             ///< Value to set in user preferences.
00124                 ) = 0;
00125 
00126             /// Get string value from user preferences.
00127             /// \warning This function is not thread-safe.
00128             virtual void GetUserPreferenceString(
00129                 LPCWSTR in_pszPreference,       ///< Name of preference
00130                 LPWSTR io_pszValue,             ///< in: value to return if preference is not set; out: changed to user preference value if set
00131                 DWORD in_dwSize                 ///< Size of out_pszValue buffer.
00132                 ) = 0;
00133 
00134             /// Get the root path for a move operation.  
00135             /// The input file can either be a work unit or a source file
00136             /// \warning This function is not thread-safe.
00137             /// \return Nothing as return value.  The out_pszRootPath will contain the path.
00138             virtual void GetMoveRootPath( 
00139                 LPCWSTR in_pszFullPath,         ///< The full path of an audio source or work unit file
00140                 LPWSTR out_pszRootPath,         ///< A pointer to the array that receives the root path
00141                 UINT in_uiRootPathSize          ///< The size of the array that receives the root path
00142                 ) = 0;
00143 
00144             /// Create a AK style list control with 3 columns:
00145             /// - Filename
00146             /// - Status
00147             /// - Owner
00148             /// You must create a static control in the resources delimitating the region of the list control and
00149             /// pass the control ID of it.
00150             /// \note DestroyFileStatusListControl must be called when handling WM_DESTROY in WindowProc
00151             /// \warning This function is not thread-safe.
00152             virtual void CreateFileStatusListControl( 
00153                 HWND in_hWndParent,                 ///< The parent dialog to create the list control
00154                 UINT in_idStatic,                   ///< The ID of the placeholder static control, which will also be the ID of the list control after the creation
00155                 const WCHAR** in_ppFilenameList,    ///< The list of files to show in the list
00156                 unsigned int in_uiFilenameListCount ///< the number of files in the in_ppFilenameList array
00157                 ) = 0;
00158         };                            
00159     }
00160 }
00161 
00162 #endif // _AK_WWISE_ISOURCECONTROLUTILITIES_H