1 /****************************************************************************** 2 Copyright (C) 2013-2014 by Hugh Bailey <obs.jim@gmail.com> 3 4 This program is free software: you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 2 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see <http://www.gnu.org/licenses/>. 16 ******************************************************************************/ 17 18 #pragma once 19 20 #include "util/c99defs.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @file 28 * 29 * Modules can specify custom user-interface-specific exports. UI functions 30 * can be within the same library as the actual core logic, or separated in to 31 * different modules to split up UI logic and core module logic. 32 * 33 * The reasoning for this is to allow for custom user interface of differing 34 * toolkits or for automatically generated user interface, or to simply allow 35 * separation of UI code from core code (which may often be in differing 36 * languages). 37 */ 38 39 /** Modal UI definition structure */ 40 struct obs_modal_ui { 41 const char *id; /**< Identifier associated with this UI */ 42 const char *task; /**< Task of the UI */ 43 const char *target; /**< UI target (UI toolkit or program name) */ 44 45 /** 46 * Callback to execute modal interface. 47 * 48 * The @b object variable points to the input/output/encoder/etc. The 49 * @b ui_data variable points to the UI parent or UI-specific data to 50 * be used with the custom user interface. 51 * 52 * What @b ui_data points to differs depending on the target, and you 53 * should use discretion and consistency when using this variable to 54 * relay information to the UI function. For example, it would be 55 * ideal to have @b ui_data point to a parent, QWidget for Qt, or a 56 * wxWindow for wxWidgets, etc., though it's up to the discretion of 57 * the developer to define that value. Because of the nature of void 58 * pointers, discretion and consistency is advised. 59 * 60 * @param object Pointer/handle to the data associated with this 61 * call. 62 * @param ui_data UI data to pass associated with this specific 63 * target, if any. 64 * @return @b true if user completed the task, or 65 * @b false if user cancelled the task. 66 */ 67 bool (*exec)(void *object, void *ui_data); 68 69 void *type_data; 70 void (*free_type_data)(void *type_data); 71 }; 72 73 /** 74 * Registers a modal UI definition to the current obs context. This should be 75 * used in obs_module_load. 76 * 77 * @param info Pointer to the modal definition structure 78 */ 79 EXPORT void obs_register_modal_ui(const struct obs_modal_ui *info); 80 81 /* ------------------------------------------------------------------------- */ 82 83 /** Modeless UI definition structure */ 84 struct obs_modeless_ui { 85 const char *id; /**< Identifier associated with this UI */ 86 const char *task; /**< Task of the UI */ 87 const char *target; /**< UI target (UI toolkit or program name) */ 88 89 /** 90 * Callback to create modeless interface. 91 * 92 * This function is almost identical to the modal exec function, 93 * except modeless UI calls return immediately, and typically are 94 * supposed to return a pointer or handle to the specific UI object 95 * that was created. For example, a Qt object would ideally return a 96 * pointer to a QWidget. Again, discretion and consistency is advised 97 * for the return value. 98 * 99 * @param object Pointer/handle to the data associated with this 100 * call. 101 * @param ui_data UI data to pass associated with this specific 102 * target, if any. 103 * @return Pointer/handle to the modeless UI associated with 104 * the specific target. 105 */ 106 void *(*create)(void *object, void *ui_data); 107 108 void *type_data; 109 void (*free_type_data)(void *type_data); 110 }; 111 112 /** 113 * Registers a modeless UI definition to the current obs context. This should 114 * be used in obs_module_load. 115 * 116 * @param info Pointer to the modal definition structure 117 */ 118 EXPORT void obs_register_modeless_ui(const struct obs_modeless_ui *info); 119 120 /* ------------------------------------------------------------------------- */ 121 122 #define OBS_UI_SUCCESS 0 123 #define OBS_UI_CANCEL -1 124 #define OBS_UI_NOTFOUND -2 125 126 /** 127 * Requests modal UI to be displayed. Returns when user is complete. 128 * 129 * @param name Name of the input/output/etc type that UI was requested for 130 * @param task Task of the user interface (usually "config") 131 * @param target Desired target (i.e. "qt", "wx", "gtk3", "win32", etc) 132 * @param data Pointer to the obs input/output/etc 133 * @param ui_data UI-specific data, usually a parent pointer/handle (if any) 134 * 135 * @return OBS_UI_SUCCESS if the UI was successful, 136 * OBS_UI_CANCEL if the UI was cancelled by the user, or 137 * OBS_UI_NOTFOUND if the UI callback was not found 138 */ 139 EXPORT int obs_exec_ui(const char *id, const char *task, const char *target, 140 void *data, void *ui_data); 141 142 /** 143 * Requests modeless UI to be created. Returns immediately. 144 * 145 * @param name Name of the input/output/etc type that UI was requested for 146 * @param task Task of the user interface 147 * @param target Desired target (i.e. "qt", "wx", "gtk3", "win32", etc) 148 * @param data Pointer to the obs input/output/etc 149 * @param ui_data UI-specific data, usually a parent pointer/handle (if any) 150 * 151 * @return Pointer/handle to the target-specific modeless object, or 152 * NULL if not found or failed. 153 */ 154 EXPORT void *obs_create_ui(const char *id, const char *task, const char *target, 155 void *data, void *ui_data); 156 157 #ifdef __cplusplus 158 } 159 #endif 160