1 #if !defined(CONTEXMENU_H) 2 #define CONTEXMENU_H 3 4 #include "elwindows.h" 5 6 #ifdef __cplusplus 7 extern "C" 8 { 9 #endif 10 11 /* define an initialisation value for context menu id */ 12 #define CM_INIT_VALUE ((size_t) -1) 13 14 15 /*! 16 * \ingroup context_menu 17 * \brief Creates a new context menu. 18 * 19 * Creates a new context menu with the returned unique id. This id identifies the menu 20 * when control functions are called. The menu_list and handler can be modified using the 21 * \ref cm_set function. If the menu was opened from an associated window, the window 22 * window_info pointer is supplied to the handler; then any associated widget id, followed by the 23 * x and y mouse coordinates in the window where the right-click was done. The last 24 * parameter is the selected menu line. 25 * No error codes are returned by this function. 26 * 27 * \param menu_list \n separated list of menu entries. Use "--" to specify a separator line. 28 * \param handler optional function to call on menu line selection 29 * \retval size_t returns the unique context menu id 30 */ 31 size_t cm_create(const char *menu_list, int (*handler)(window_info *, int, int, int, int)); 32 33 34 /*! 35 * \ingroup context_menu 36 * \brief Deletes a context menu and all its activation entries; i.e. full_window, region or widgets. 37 * 38 * \param cm_id id of context menu 39 * \retval int 1 for success, 0 for failure (invalid id) 40 */ 41 int cm_destroy(size_t cm_id); 42 43 44 /*! 45 * \ingroup context_menu 46 * \brief Test if a context menu id is valid. 47 * 48 * \param cm_id id of context menu 49 * \retval int 1 for success, 0 for failure (invalid id) 50 */ 51 int cm_valid(size_t cm_id); 52 53 54 /*! 55 * \ingroup context_menu 56 * \brief Open a context menu if there is a valid activation for the specified window. 57 * 58 * Activations are created using the \ref cm_add_window \ref cm_add_region and \ref cm_add_widget 59 * functions. If any exist for the specified window and the mouse is in a valid position, the context 60 * menu is display. 61 * 62 * \param window_id id of window to check for activations 63 * \retval int 1 for success a cm was opened , 0 for failure (invalid id) or no window opened 64 */ 65 int cm_show_if_active(int window_id); 66 67 68 /*! 69 * \ingroup context_menu 70 * \brief Opens a context menu without checking for window activation entries. 71 * 72 * \param cm_id id of context menu 73 * \param window_id id of window to treat as parent used for callback or -1 for no id 74 * \param widget_id id of widget used for callback or - -1 for no id 75 * \retval int 1 for success, 0 for failure (invalid id) 76 */ 77 int cm_show_direct(size_t cm_id, int window_id, int widget_id); 78 79 80 /*! 81 * \ingroup context_menu 82 * \brief Called by \ref click_in_windows to prepare for activation checks. 83 * \retval int 1 if the activation mouse state is true (i.e. right click), otherwise 0 84 */ 85 int cm_pre_show_check(Uint32 flags); 86 87 88 /*! 89 * \ingroup context_menu 90 * \brief Called by \ref click_in_windows to closes/hides any open context menu. 91 * \param force if true always close regardless of internal state 92 */ 93 void cm_post_show_check(int force); 94 95 96 /*! 97 * \ingroup context_menu 98 * \brief Replace all context menu lines and the callback function. 99 * \param cm_id id of context menu 100 * \param menu_list \n separated list of menu entries. Use "--" to specify a separator line. 101 * \param handler optional function to call on menu line selection 102 * \retval int 1 for success, 0 for failure (invalid id) 103 */ 104 int cm_set(size_t cm_id, const char *menu_list, int (*handler)(window_info *, int, int, int, int)); 105 106 107 /*! 108 * \ingroup context_menu 109 * \brief Add additional menu lines and optionally replace the callback function. 110 * \param cm_id id of context menu 111 * \param menu_list \n separated list of menu entries. Use "--" to specify a separator line. 112 * \param handler optional function to call on menu line selection 113 * \retval int 1 for success, 0 for failure (invalid id) 114 */ 115 int cm_add(size_t cm_id, const char *menu_list, int (*handler)(window_info *, int, int, int, int)); 116 117 118 /*! 119 * \ingroup context_menu 120 * \brief Add/replacee the pre-show callback function. 121 * \param cm_id id of context menu 122 * \param handler function to call on just before the menu is shown 123 * \retval int 1 for success, 0 for failure (invalid id) 124 */ 125 int cm_set_pre_show_handler(size_t cm_id, void (*handler)(window_info *, int, int, int, window_info *)); 126 127 128 /*! 129 * \ingroup context_menu 130 * \brief Set the border and zoom properties of the specified context menu. 131 * \param cm_id id of context menu 132 * \param border window border size, no hightlight 133 * \param text_border border around text, hightlight extended to cover 134 * \param line_sep line spacing 135 * \param zoom text font zoom 136 * \retval int 1 for success, 0 for failure (invalid id) 137 */ 138 int cm_set_sizes(size_t cm_id, int border, int text_border, int line_sep, float zoom); 139 140 141 /*! 142 * \ingroup context_menu 143 * \brief Enumerated type for context enu colour properties. 144 */ 145 enum CM_COLOUR_NAME { CM_HIGHLIGHT_TOP, CM_HIGHLIGHT_BOTTOM, CM_TEXT, CM_GREY }; 146 147 148 /*! 149 * \ingroup context_menu 150 * \brief Set a context menu colour value 151 * \param cm_id id of context menu 152 * \param colour_name \ref CM_COLOUR_NAME property to modify 153 * \param r red value 154 * \param g green value 155 * \param b blue value 156 * \retval int 1 for success, 0 for failure (invalid id) 157 */ 158 int cm_set_colour(size_t cm_id, enum CM_COLOUR_NAME colour_name, float r, float g, float b); 159 160 161 /*! 162 * \ingroup context_menu 163 * \brief Make a context menu line a tick box option. 164 * 165 * When the menu line is selected, the control variable value is toggled. Also, if the 166 * control variable is modified elsewhere, the context menu dynamically/automatically reflects 167 * the state. This can be used for \ref config options. 168 * 169 * \param cm_id id of context menu 170 * \param line the menu line number to change, range 0 - (number lines - 1) 171 * \param control_var the address of the control variable 172 * \param config_name if not NULL, the elconfig option name - used to set unsaved 173 * \retval int 1 for success, 0 for failure (invalid id) 174 */ 175 int cm_bool_line(size_t cm_id, size_t line, int *control_var, const char *config_name); 176 177 178 /*! 179 * \ingroup context_menu 180 * \brief Enable/disable a context menu line (disable - grey it out). 181 * \param cm_id identifier of the context menu 182 * \param line the line to enable or disable 183 * \param is_grey if \c true, the line is disabled, otherwise enabled 184 * \retval int 1 for success, 0 for failure (invalid id) 185 */ 186 int cm_grey_line(size_t cm_id, size_t line, int is_grey); 187 188 189 /*! 190 * \ingroup context_menu 191 * \brief Add an activation entry for an entire window. 192 * 193 * If the activation mouse click is done anywhere in the window the 194 * context menu is shown. This activation point can be removed using 195 * the \ref cm_remove_window function. 196 * 197 * \param cm_id id of context menu 198 * \param window_id id of window to add activation 199 * \retval int 1 for success, 0 for failure (invalid id or window) 200 */ 201 int cm_add_window(size_t cm_id, int window_id); 202 203 204 /*! 205 * \ingroup context_menu 206 * \brief Add an activation entry for a window region 207 * 208 * If the activation mouse click is done anywhere in the region 209 * within the window the context menu is shown. This activation point 210 * can be removed using the \ref cm_remove_regions function. A region 211 * activation point overides a window activation point. 212 * 213 * \param cm_id id of context menu 214 * \param window_id id of window containing the region 215 * \param posx top left x coordinate in window 216 * \param posy top left y coordinate in window 217 * \param lenx width of region 218 * \param leny height of region 219 * \retval int 1 for success, 0 for failure (invalid id or window) 220 */ 221 int cm_add_region(size_t cm_id, int window_id, int posx, int posy, int lenx, int leny); 222 223 224 /*! 225 * \ingroup context_menu 226 * \brief Add an activation entry over a window widget 227 * 228 * If the activation mouse click is done anywhere on the widget 229 * within the window the context menu is shown. This activation point 230 * can be removed using the \ref cm_remove_widget function. A widget 231 * activation point overides both region and window activation points. 232 * 233 * \param cm_id id of context menu 234 * \param window_id id of window containing the widget 235 * \param widget_id id of widget 236 * \retval int 1 for success, 0 for failure (invalid id, window or widget) 237 */ 238 int cm_add_widget(size_t cm_id, int window_id, int widget_id); 239 240 241 /*! 242 * \ingroup context_menu 243 * \brief Removes the activation for the specified window 244 * \param window_id id of window to remove 245 * \retval int 1 for success, 0 for failure (invalid window) 246 */ 247 int cm_remove_window(int window_id); 248 249 250 /*! 251 * \ingroup context_menu 252 * \brief Remove all activation regions for the specified window 253 * \param window_id id of window containing regions 254 * \retval int 1 for success, 0 for failure (invalid window) 255 */ 256 int cm_remove_regions(int window_id); 257 258 259 /*! 260 * \ingroup context_menu 261 * \brief Remove activation for the specified window/widget 262 * \param window_id id of window containing the widget 263 * \param widget_id id of widget 264 * \retval int 1 for success, 0 for failure (invalid window) 265 */ 266 int cm_remove_widget(int window_id, int widget_id); 267 268 269 /*! 270 * \ingroup context_menu 271 * \brief Show information about the context menu system state 272 */ 273 void cm_showinfo(void); 274 275 276 /*! 277 * \ingroup context_menu 278 * \brief Return the id the currently open context menu or CM_INIT_VALUE if none open. 279 */ 280 size_t cm_window_shown(void); 281 282 283 /*! 284 * \ingroup context_menu 285 * \brief Set the data pointer assiociated with a menu 286 * \param cm_id id of the assiociated context menu 287 * \param data the pointer to save 288 */ 289 void cm_set_data(size_t cm_id, void *data); 290 291 292 /*! 293 * \ingroup context_menu 294 * \brief Get the previously saved data pointer assiociated with a menu 295 * \param cm_id id of the assiociated context menu 296 * \retval void * NULL or the pointer previously set 297 */ 298 void *cm_get_data(size_t cm_id); 299 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 #endif 306