1 /*!
2 * \file
3 * \ingroup elwindows
4 * \brief EL window manager.
5 */
6 #ifndef __EL_WINDOWS_H
7 #define __EL_WINDOWS_H
8
9 #include <SDL_keycode.h>
10 #include "keys.h"
11 #include "widgets.h"
12
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17 //! The default color for GUI elements
18 extern const GLfloat gui_color[3];
19 extern const GLfloat gui_invert_color[3];
20 extern const GLfloat gui_bright_color[3];
21 extern const GLfloat gui_dull_color[3];
22
23 /*!
24 * \name Title bar & other constants
25 */
26 /*! @{ */
27 #define ELW_TITLE_HEIGHT 16
28 #define ELW_BOX_SIZE 20
29 #define ELW_TITLE_SIZE 35
30 #define ELW_CM_MENU_LEN 6
31 /*! @} */
32
33 /*!
34 * A simple window handler setup to reduce the code needed to do windows
35 *
36 */
37 typedef struct {
38 int window_id; /*!< the unique window id */
39 int order; /*!< the order the windows are to be displayed (layering) */
40 int pos_id; /*!< id of parent window, pos_id < 0 for normal windows */
41 int pos_loc; /*!< where is it compared to the pos id? NOT SUPPORTED YET */
42 int pos_x, pos_y; /*!< logical location on screen */
43 int len_x, len_y; /*!< the size of the window in pixels */
44 int min_len_x, min_len_y; /*!< for resizable windows, the minimum width and height */
45 int cur_x, cur_y; /*!< current location on screen */
46 int scroll_id; /*!< id of the scroll widget, if window is scrollable */
47 int scroll_yoffset; /*!< scroll bar will be placed below any close box, this is any additional y offset */
48
49 Uint32 flags; /*!< window flags */
50
51 float back_color[4]; /*!< r,g,b,a for the background */
52 float border_color[4]; /*!< r,g,b,a for the border */
53 float line_color[4]; /*!< r,g,b,a for any internal lines */
54
55 char window_name[ELW_TITLE_SIZE]; /*!< should be a unique name suitable for display */
56
57 char displayed; /*!< is the window currently being displayed? */
58 //char collapsed; // is it collapsed or expanded?
59 char dragged; /*!< are we dragging the window? */
60 char resized; /*!< are we resizing the window? */
61 char drag_in; /*!< are we dragging inside the window? */
62 char reinstate; /*!< reinstate this window if the parent is shown again */
63 int opaque; /*!< if non-zero, window is drawn opaque */
64 char owner_drawn_title_bar; /*the title bar is drawn by the window itself*/
65 size_t cm_id; /*!< optional context menu activated by right-clicking title */
66
67 /*!
68 * \name scalable elements
69 */
70 /*! @{ */
71 float current_scale;
72 float current_scale_small;
73 float *custom_scale;
74 int box_size;
75 int title_height;
76 font_cat font_category;
77 int small_font_max_len_x;
78 int small_font_len_y;
79 int default_font_max_len_x;
80 int default_font_len_y;
81
82 /*!
83 * \name the handlers
84 */
85 /*! @{ */
86 int (*init_handler)(); /*!< init, scaling, etc */
87 int (*display_handler)(); /*!< display the window */
88 int (*pre_display_handler)(); /*!< display the window, before body (e.g. scissor) */
89 int (*post_display_handler)(); /*!< display the window, after body (e.g. widgets, scissor) */
90 int (*click_handler)(); /*!< handle mouse clicks */
91 int (*drag_handler)(); /*!< handle dragging inside windows */
92 int (*mouseover_handler)(); /*!< handle mouseovers */
93 int (*resize_handler)(); /*!< handle window resize events */
94 int (*keypress_handler)(); /*!< handle key presses */
95 int (*close_handler)(); /*!< executed after window is closed */
96 int (*destroy_handler)(); /*!< executed upon window destruction */
97 int (*show_handler)(); /*!< executed before the window is shown */
98 int (*after_show_handler)(); /*!< executed after the window is shown */
99 int (*hide_handler)(); /*!< executed after the window is hidden */
100 int (*ui_scale_handler)(); /*!< executed if the glabal scale ui_scale is changed */
101 int (*font_change_handler)(); /*!< executed when font settings are changed */
102 /*! @} */
103
104 /*
105 // and optional list/data storage - future expansion??
106 void *list;
107 int list_size; // width of list items
108 int num_list; // number of items usable in list
109 int max_list; // amount of space allocated in list
110 int data_value; // a simple data value associated with this window
111 */
112 void * data; /*!< data for this window */
113 widget_list *widgetlist; /*!< list of widgets for this window */
114 } window_info;
115
116 /*!
117 * \name property flags in create
118 */
119 /*! @{ */
120 #define ELW_TITLE_NONE 0x0000
121 #define ELW_TITLE_BAR 0x0001
122 #define ELW_TITLE_NAME 0x0002
123 #define ELW_CLOSE_BOX 0x0004
124
125 #define ELW_SHOW 0x0010
126 #define ELW_DRAGGABLE 0x0020
127 //#define ELW_COLLAPSABLE 0x0040
128 #define ELW_SHOW_LAST 0x0080
129 #define ELW_RESIZEABLE 0x0100
130
131 #define ELW_USE_BACKGROUND 0x0200
132 #define ELW_USE_BORDER 0x0400
133 #define ELW_USE_UISCALE 0x0800
134
135 #define ELW_CLICK_TRANSPARENT 0x1000
136
137 #define ELW_ALPHA_BORDER 0x2000
138 #define ELW_SWITCHABLE_OPAQUE 0x4000
139 #define ELW_SCROLLABLE 0x8000
140 /*! @} */
141
142 /*!
143 * \name predefined window flags
144 */
145 /*! @{ */
146 #define ELW_WIN_DEFAULT (ELW_TITLE_BAR|ELW_CLOSE_BOX|ELW_DRAGGABLE|ELW_USE_BACKGROUND|ELW_USE_BORDER|ELW_SHOW|ELW_TITLE_NAME|ELW_ALPHA_BORDER|ELW_SWITCHABLE_OPAQUE)
147 #define ELW_WIN_INVISIBLE (ELW_TITLE_NONE|ELW_SHOW)
148 /*! @} */
149
150 /*!
151 * \name window position flags
152 */
153 /*! @{ */
154 #define ELW_VUPPER 0x00
155 #define ELW_VCENTER 0x04
156 #define ELW_VLOWER 0x08
157 #define ELW_VAUTO 0x0C //reserved
158 #define ELW_HLEFT 0x00
159 #define ELW_HCENTER 0x01
160 #define ELW_HRIGHT 0x02
161 #define ELW_HAUTO 0x03 //reserved
162
163 #define ELW_POS_UL (ELW_VUPPER|ELW_HLEFT)
164 #define ELW_POS_UC (ELW_VUPPER|ELW_HCENTER)
165 #define ELW_POS_UR (ELW_VUPPER|ELW_HRIGHT)
166
167 #define ELW_POS_CL (ELW_VCENTER|ELW_HLEFT)
168 #define ELW_POS_CC (ELW_VCENTER|ELW_HCENTER)
169 #define ELW_POS_CR (ELW_VCENTER|ELW_HRIGHT)
170
171 #define ELW_POS_LL (ELW_VLOWER|ELW_HLEFT)
172 #define ELW_POS_LC (ELW_VLOWER|ELW_HCENTER)
173 #define ELW_POS_LR (ELW_VLOWER|ELW_HRIGHT)
174 /*! @} */
175
176 /*!
177 * \name window alignment flags
178 */
179 /*! @{ */
180 #define ELW_ALIGN_UL ((ELW_VUPPER|ELW_HLEFT)<<8)
181 #define ELW_ALIGN_UC ((ELW_VUPPER|ELW_HCENTER)<<8)
182 #define ELW_ALIGN_UR ((ELW_VUPPER|ELW_RIGHT)<<8)
183
184 #define ELW_ALIGN_CL ((ELW_VCENTER|ELW_HLEFT)<<8)
185 #define ELW_ALIGN_CC ((ELW_VCENTER|ELW_HCENTER)<<8)
186 #define ELW_ALIGN_CR ((ELW_VCENTER|ELW_HRIGHT)<<8)
187
188 #define ELW_ALIGN_LL ((ELW_VLOWER|ELW_HLEFT)<<8)
189 #define ELW_ALIGN_LC ((ELW_VLOWER|ELW_HCENTER)<<8)
190 #define ELW_ALIGN_LR ((ELW_VLOWER|ELW_HRIGHT)<<8)
191 /*! @} */
192
193 /*!
194 * \name predefined flags
195 */
196 /*! @{ */
197 #define ELW_POS ELW_POS_UL
198 #define ELW_ALIGN ELW_ALIGN_UL
199 #define ELW_RELATIVE (ELW_POS|ELW_ALIGN)
200 /*! @} */
201
202 /*!
203 * \name window color id's
204 */
205 /*! @{ */
206 #define ELW_COLOR_BACK 0
207 #define ELW_COLOR_BORDER 1
208 #define ELW_COLOR_LINE 2
209 /*! @} */
210
211 /*!
212 * \name window handler id's
213 */
214 /*! @{ */
215 #define ELW_HANDLER_INIT 0
216 #define ELW_HANDLER_DISPLAY 1
217 #define ELW_HANDLER_CLICK 2
218 #define ELW_HANDLER_DRAG 3
219 #define ELW_HANDLER_MOUSEOVER 4
220 #define ELW_HANDLER_RESIZE 5
221 #define ELW_HANDLER_KEYPRESS 6
222 #define ELW_HANDLER_CLOSE 7
223 #define ELW_HANDLER_DESTROY 8
224 #define ELW_HANDLER_SHOW 9
225 #define ELW_HANDLER_HIDE 10
226 #define ELW_HANDLER_AFTER_SHOW 11
227 #define ELW_HANDLER_PRE_DISPLAY 12
228 #define ELW_HANDLER_POST_DISPLAY 13
229 #define ELW_HANDLER_UI_SCALE 14
230 #define ELW_HANDLER_FONT_CHANGE 15
231 /*! @} */
232
233 /*!
234 * \name mouse click flags - first ones from events
235 */
236 /*! @{ */
237 #define ELW_RIGHT_MOUSE (1<<28)
238 #define ELW_MID_MOUSE (1<<27) // future expansion
239 #define ELW_LEFT_MOUSE (1<<26)
240 #define ELW_MOUSE_BUTTON (ELW_RIGHT_MOUSE|ELW_MID_MOUSE|ELW_LEFT_MOUSE)
241 #define ELW_DBL_CLICK (1<<25) // future expansion
242 #define ELW_WHEEL_UP (1<<24)
243 #define ELW_WHEEL_DOWN (1<<23)
244 #define ELW_WHEEL (ELW_WHEEL_UP|ELW_WHEEL_DOWN)
245 #define ELW_MOUSE_BUTTON_WHEEL (ELW_MOUSE_BUTTON|ELW_WHEEL)
246 /*! @} */
247
248 /*!
249 * structure containing data for all windows used.
250 */
251 typedef struct {
252 window_info *window; /*!< an array of \ref window_info windows */
253 int num_windows; /*!< highest item used */
254 int max_windows; /*!< number of windows allocated */
255 int display_level;
256 } windows_info;
257
258 extern windows_info windows_list; /*!< global variable defining the list of windows */
259 extern int windows_on_top; /*!< global variable for whether windows appear on top of the console */
260 extern int top_SWITCHABLE_OPAQUE_window_drawn; /*!< the id of the top opaque switchable window */
261 extern int opaque_window_backgrounds;
262
263 /*!
264 * \name managed window definitions, used to specify which window to access
265 */
266 /*! @{ */
267 enum managed_window_enum
268 {
269 MW_TRADE = 0,
270 MW_ITEMS,
271 MW_BAGS,
272 MW_SPELLS,
273 MW_STORAGE,
274 MW_MANU,
275 MW_EMOTE,
276 MW_QUESTLOG,
277 MW_INFO,
278 MW_BUDDY,
279 MW_STATS,
280 MW_HELP,
281 MW_RANGING,
282 MW_ACHIEVE,
283 MW_DIALOGUE,
284 MW_QUICKBAR,
285 MW_QUICKSPELLS,
286 MW_CONFIG,
287 MW_MINIMAP,
288 MW_ASTRO,
289 MW_TABMAP,
290 MW_CONSOLE,
291 MW_CHAT,
292 #ifdef ECDEBUGWIN
293 MW_ECDEBUG,
294 #endif
295 MW_MAX
296 };
297 /*! @} */
298
299 /*!
300 * \name window creation and open functions, defined here to limit includes
301 */
302 /*! @{ */
303 void display_trade_menu(void);
304 void display_items_menu(void);
305 void display_sigils_menu(void);
306 void display_storage_menu(void);
307 void display_manufacture_menu(void);
308 void display_emotes_menu(void);
309 void display_questlog(void);
310 void display_tab_info(void);
311 void display_buddy(void);
312 void display_tab_stats(void);
313 void display_tab_help(void);
314 void display_range_win(void);
315 void display_elconfig_win(void);
316 void display_minimap(void);
317 #ifdef ECDEBUGWIN
318 void display_ecdebugwin(void);
319 #endif
320 /*! @} */
321
322
323 // windows manager function
324
325 /*!
326 * \name managed window access function
327 */
328 /*! @{ */
329 int get_id_MW(enum managed_window_enum managed_win);
330 void set_id_MW(enum managed_window_enum managed_win, int win_id);
331 void set_pos_MW(enum managed_window_enum managed_win, int pos_x, int pos_y);
332 int get_pos_x_MW(enum managed_window_enum managed_win);
333 int get_pos_y_MW(enum managed_window_enum managed_win);
334 int on_top_responsive_MW(enum managed_window_enum managed_win);
335 int not_on_top_now(enum managed_window_enum managed_win);
336 void clear_was_open_MW(enum managed_window_enum managed_win);
337 void set_was_open_MW(enum managed_window_enum managed_win);
338 int was_open_MW(enum managed_window_enum managed_win);
339 int is_hideable_MW(enum managed_window_enum managed_win);
340 void clear_hideable_MW(enum managed_window_enum managed_win);
341 void set_hideable_MW(enum managed_window_enum managed_win);
342 void call_display_MW(enum managed_window_enum managed_win);
343 int match_keydef_MW(enum managed_window_enum managed_win, SDL_Keycode key_code, Uint16 key_mod);
344 float * get_scale_WM(enum managed_window_enum managed_win);
345 void set_save_pos_MW(enum managed_window_enum managed_win, int *pos_x, int *pos_y);
346 int * get_scale_flag_MW(void);
347 void toggle_window_MW(enum managed_window_enum managed_win);
348 int get_window_showable_MW(enum managed_window_enum managed_win);
349 enum managed_window_enum get_by_name_MW(const char *name);
350 const char *get_dict_name_WM(enum managed_window_enum managed_win, char *buf, size_t buf_len);
351 void get_json_window_state_MW(enum managed_window_enum managed_win);
352 void set_json_window_state_MW(enum managed_window_enum managed_win);
353 /*! @} */
354
355 /*!
356 * \ingroup windows
357 * \brief Check if the specified window has pending adjustments and position proportionably
358 *
359 * \param managed_win the index of the window in the managed window array
360 *
361 * \callgraph
362 */
363 void check_proportional_move(enum managed_window_enum managed_win);
364
365 /*!
366 * \ingroup windows
367 * \brief Adjust window positions proportionally using the supplied ratios
368 *
369 * \param pos_ratio_x the ratio of the new window width over the old width
370 * \param pos_ratio_y the ratio of the new window height over the old height
371 *
372 * \callgraph
373 */
374 void move_windows_proportionally(float pos_ratio_x, float pos_ratio_y);
375
376 /*!
377 * \ingroup windows
378 * \brief Adjusts window positions proportionally using window sizes from config
379 *
380 * \callgraph
381 */
382 void restore_window_proportionally(void);
383
384 /*!
385 * \ingroup elwindows
386 * \brief Set the window custom scale factor
387 *
388 * This value is multiplied by the global scale value to
389 * determine the specific scale used for this window.
390 *
391 * \param win_id the id of the window to select
392 * \param managed_win in index of the manage window which stores the scale
393 * \callgraph
394 */
395 void set_window_custom_scale(int win_id, enum managed_window_enum managed_win);
396
397 /*!
398 * \ingroup elwindows
399 * \brief For each window using the specifed scale, update scaling.
400 *
401 * changed_window_custom_scale pointer to the variable from custom_scale_factors_def
402 * \callgraph
403 */
404 void update_windows_custom_scale(float *changed_window_custom_scale);
405
406 /*!
407 * \ingroup elwindows
408 * \brief Update scale settings for all windows
409 *
410 * Update scale settings for all windows
411 *
412 * \param scale_factor the scaling factor
413 * \callgraph
414 */
415 void update_windows_scale(float scale_factor);
416
417 /*!
418 * \ingroup elwindows
419 * \brief Update scale settings for specific windows
420 *
421 * Update scale settings for all windows
422 *
423 * \param win pointer to window structure
424 * \param scale_factor the scaling factor
425 * \callgraph
426 */
427 void update_window_scale(window_info *win, float scale_factor);
428
429 /*!
430 * \ingroup elwindows
431 * \brief Handle a change in fonts
432 *
433 * Handle a change in font or text size for font category \a cat, in all windows.
434 *
435 * \param cat The font category that was changed,
436 */
437 void change_windows_font(font_cat cat);
438
439 /*!
440 * \ingroup elwindows
441 * \brief Displays all active windows
442 *
443 * Displays all active windows
444 *
445 * \param level the display level to display
446 * \callgraph
447 */
448 void display_windows(int level);
449
450 /*!
451 * \ingroup elwindows
452 * \brief callback function used when a mouse click happens in a window.
453 *
454 * This event handler gets called when a mouse click is reported in a window. The coordinates \a mx and \a my denotes the (x,y) position of the mouse within the window.
455 *
456 * \param mx x coordinate of the mouse position where the click occurred
457 * \param my y coordinate of the mouse position where the click occurred
458 * \param flags mouseflags
459 * \retval int
460 * \callgraph
461 */
462 int click_in_windows(int mx, int my, Uint32 flags);
463
464 /*!
465 * \ingroup elwindows
466 * \brief callback function used when a drag event happens in a window.
467 *
468 * This drag event handler get called when a mouse drag event happens in a window. (\a mx, \a my) denotes the coordinates of the mouse, while \a dx and \a dy are the dragging distances in x- and y-direction.
469 *
470 * \param mx x coordinate of the mouse position where the drag started
471 * \param my x coordinate of the mouse position where the drag started
472 * \param flags mouseflags
473 * \param dx dragging distance in x-direction
474 * \param dy dragging distance in y-direction
475 * \retval int
476 * \callgraph
477 */
478 int drag_in_windows(int mx, int my, Uint32 flags, int dx, int dy);
479
480 /*!
481 * \ingroup elwindows
482 * \brief Handles dragging and resizing of a window
483 *
484 * Checks all the windows for one that is currently seletec and moves or resizes this one resp.
485 *
486 * \param mx x coordinate of the mouse position
487 * \param my y coordinate of the mouse position
488 * \param dx amount in x direction to drag or resize the window
489 * \param dy amount in y direction to drag or resize the window
490 * \retval int the id of the window being dragged or resized
491 * \callgraph
492 */
493 int drag_windows(int mx, int my, int dx, int dy);
494
495 /*!
496 * \ingroup elwindows
497 * \brief callback function used when a key is pressed in a window.
498 *
499 * This event handler gets called when a keypress is reported in a window. The coordinates \a mx and \a my denotes the (x,y) position of the mouse within the window.
500 *
501 * \param x x coordinate of the mouse position where the click occurred
502 * \param y y coordinate of the mouse position where the click occurred
503 * \param key_code the SDL key code
504 * \param key_unicode the unicode representation of the key pressed
505 * \param key_mod the status bitmask for mod keys
506 * \retval int
507 * \callgraph
508 */
509 int keypress_in_windows(int x, int y, SDL_Keycode key_code, Uint32 key_unicode, Uint16 key_mod);
510
511 /*!
512 * \ingroup elwindows
513 * \brief Resets the states of all windows which are related to dragging
514 *
515 * Resets the dragged, resized and drag_in states of all windows.
516 *
517 */
518 void end_drag_windows();
519
520 /*!
521 * \ingroup elwindows
522 * \brief Selects the window given by \a win_id.
523 *
524 * Selects the window given in \a win_id. The selected window and each of its childs, if applicable, is brought to front.
525 *
526 * \param win_id the id of the window to select
527 * \retval int -1, if \a win_id is either <0 or greater than \ref windows_info::num_windows, or if \a win_id is not equal the \ref window_info::window_id stored for this \ref windows_info::window.
528 * 0, if the \ref window_info::order of the \ref windows_info::window stored at this index is less than 0,
529 * else 1.
530 *
531 * \pre The parameter \a win_id must be both, greater or equal to 0 and less than \ref windows_info::num_windows
532 * \pre The parameter \a win_id must be equal the \ref window_info::window_id which is currently stored in \ref windows_list.
533 * \pre The \ref window_info::order of the \ref windows_info::window stored at the index \a win_id, must be greater than 0.
534 */
535 int select_window(int win_id);
536
537 // individual functions
538
539 /*!
540 * \ingroup elwindows
541 * \brief Creates a new window and calls \ref init_window to place it.
542 *
543 * Creates a new window with the given \a name and \a property_flags and then calls \ref init_window to place it accordingly.
544 *
545 * \param name name of the window
546 * \param pos_id used to determine the visibility of this window, gets passed to \ref init_window
547 * \param pos_loc passed to \ref init_window
548 * \param pos_x passed to \ref init_window
549 * \param pos_y passed to \ref init_window
550 * \param size_x passed to \ref init_window
551 * \param size_y passed to \ref init_window
552 * \param property_flags the windows properties
553 * \retval int returns the window id as an index into the \ref windows_info::window array.
554 * \callgraph
555 *
556 * \post If this functions returns -1, it indicates an unhandled exception has occured.
557 */
558 int create_window(const char *name, int pos_id, Uint32 pos_loc, int pos_x, int pos_y, int size_x, int size_y, Uint32 property_flags);
559
560 /*!
561 * \ingroup elwindows
562 * \brief Destroys the window with the given \a win_id.
563 *
564 * Destroys the window with the given \a win_id and frees up memory.
565 *
566 * \param win_id the index into the \ref windows_info::window array
567 *
568 * \pre If \a win_id is \<0 or \>\ref windows_info::num_windows this function returns without performing any actions.
569 * \pre If the \ref window_info::window_id of the window stored at the index \a win_id into the \ref windows_list variable is not equal to \a win_id, this function returns without performing any actions.
570 */
571 void destroy_window(int win_id);
572
573 /*!
574 * \ingroup elwindows
575 * \brief Initializes a new window.
576 *
577 * Initializes a new window with the given \a win_id, position and size. Calls \ref move_window to place the window accordingly.
578 *
579 * \param win_id the \ref window_info::window_id for the window
580 * \param pos_id the id of the position
581 * \param pos_loc
582 * \param pos_x x coordinate of the upper left corner of the window
583 * \param pos_y y coordinate of the upper left corner of the window
584 * \param size_x width of the window
585 * \param size_y height of the window
586 * \retval int
587 * \sa move_window
588 */
589 int init_window(int win_id, int pos_id, Uint32 pos_loc, int pos_x, int pos_y, int size_x, int size_y);
590
591 /*!
592 * \ingroup elwindows
593 * \brief Moves the window given by \a win_id
594 *
595 * Moves the given window to the new position given.
596 *
597 * \param win_id id for the window to move
598 * \param pos_id id of the new posisiotn
599 * \param pos_loc
600 * \param pos_x x coordinate of the new position
601 * \param pos_y y coordinate of the new position
602 * \retval int -1, if \a win_id < 0 or \a win_id > \ref windows_info::num_windows,
603 * or if the \ref window_info::window_id of the window at index \a win_id into \ref windows_list is not equal \a win_id,
604 * else 1 is returned.
605 *
606 * \pre If \a win_id is less than 0, this functions returns -1 without performing any actions
607 * \pre If \a win_id is greater than \ref windows_info::num_windows this function returns -1 without performing any actions
608 * \pre If \a win_id is not equal \ref window_info::window_id of the window at the index \a win_id into \ref windows_list this functions returns -1, without performing any action.
609 */
610 int move_window(int win_id, int pos_id, Uint32 pos_loc, int pos_x, int pos_y);
611
612
613 /*!
614 * \ingroup elwindows
615 * \brief Draws the window given by \a win_id
616 *
617 * Draws the given window on the screen. Don't call this function directly,
618 * use the window manager instead. This declaration is only here for the
619 * loading window which bypasses the window manager since it cannot be
620 * drawn in the normal event loop.
621 *
622 * \param win_id id for the window to move
623 */
624 int display_window (int win_id);
625
626 //int set_window_property(int win_id, Uint32 property_flag, int new_property);
627
628 /*!
629 * \ingroup elwindows
630 * \brief Sets the window (background) color to the given values.
631 *
632 * Sets the background color of the window given by \a win_id to the values given in \a r, \a g, \a b and \a a.
633 * \note This function is currently only used when displaying the options menu.
634 *
635 * \param win_id the id of the window
636 * \param color_id an id for the color value
637 * \param r red value of the color (0<=r<=1)
638 * \param g green value of the color (0<=g<=1)
639 * \param b blue value of the color (0<=b<=1)
640 * \param a transparency of the color (0<=a<=1)
641 * \retval int 0, if \a win_id is less than 0, or if \a win_id is greater than \ref windows_info::num_windows,
642 * or if the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array is not equal to \a win_id,
643 * or if no action was performed, else 1 is returned.
644 *
645 * \callgraph
646 *
647 * \pre If \a win_id < 0 this function returns 0 without performing any actions.
648 * \pre If \a win_id is greater than \ref windows_info::num_windows, this functions returns 0 without performing any actions.
649 * \pre If none of the above preconditions is true, but no action is performed else, this function returns 0.
650 * \pre This functions only handles the \a color_id of \ref ELW_COLOR_BACK, \ref ELW_COLOR_BORDER and \ref ELW_COLOR_LINE.
651 */
652 int set_window_color(int win_id, Uint32 color_id, float r, float g, float b, float a);
653
654 /*!
655 * \ingroup elwindows
656 * \brief Uses the color of the window \a win_id that is referred to by \a color_id.
657 *
658 * The part of the window \a win_id given by \a color_id will be used further.
659 * \note This function is only used by the quickbar (\ref display_quickbar_handler)
660 *
661 * \param win_id the id of the window to set the color
662 * \param color_id the color id to use
663 * \retval int 0, if \a win_id is less than 0, or if \a win_id is greater than \ref windows_info::num_windows,
664 * or if the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array is not equal to \a win_id,
665 * or if no action was performed, else 1 is returned.
666 *
667 * \sa display_quickbar_handler
668 *
669 * \pre If \a win_id < 0 this function returns 0 without performing any actions.
670 * \pre If \a win_id is greater than the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns 0 without performing any actions.
671 * \pre If none of the above preconditions is true, but no action is performed else, this function returns 0.
672 * \pre This function only handles the \a color_id of \ref ELW_COLOR_BACK, \ref ELW_COLOR_BORDER and \ref ELW_COLOR_LINE.
673 */
674 int use_window_color(int win_id, Uint32 color_id);
675
676 /*!
677 * \ingroup elwindows
678 * \brief Sets the window's minimum size
679 *
680 * Sets the minimum \a width and \a height for the resizeable window given by \a win_id
681 *
682 * \param win_id the number of the window
683 * \param width the new minimum width
684 * \param height the new minimum height
685 * \retval int 0 on failure, 1 on success
686 *
687 * \pre If \a win_id < 0 this function returns 0, without performing any actions.
688 * \pre If \a win_id is greater than \ref windows_info::num_windows this function returns 0 without performing any actions.
689 * \pre If either \a width or \a height is less than 0 this function returns 0 without performing any actions.
690 */
691 int set_window_min_size (int win_id, int width, int height);
692
693 /*!
694 * \ingroup elwindows
695 * \brief Sets one or more window flags
696 *
697 * Sets the window flags in \a flag
698 *
699 * \param win_id the number of the window
700 * \param flag the flag(s) to set
701 */
702 int set_window_flag (int win_id, Uint32 flag);
703
704 /*!
705 * \ingroup elwindows
706 * \brief Sets a new window handler callback function to be used for the given window.
707 *
708 * The given \a handler will be set to be the callback function to handle \a handler_id callbacks for the \a win_id window.
709 *
710 * \param win_id the id of the window for which to set a callback function.
711 * \param handler_id the type of handler that will be set.
712 * \param handler a pointer to the callback function to use.
713 * \retval void* a pointer to the old handler, or NULL.
714 *
715 * \pre If \a win_id < 0 this function returns NULL without performing any actions.
716 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns NULL without performing any actions.
717 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns NULL without performing any actions.
718 * \pre If \a handler_id is not one of \ref ELW_HANDLER_INIT, \ref ELW_HANDLER_DISPLAY, \ref ELW_HANDLER_CLICK, \ref ELW_HANDLER_DRAG, \ref ELW_HANDLER_MOUSEOVER, \ref ELW_HANDLER_RESIZE, \ref ELW_HANDLER_KEYPRESS or \ref ELW_HANDLER_DESTROY, this function returns NULL.
719 *
720 */
721 void *set_window_handler(int win_id, int handler_id, int (*handler)() );
722
723 /*!
724 * \ingroup elwindows
725 * \brief Selects and shows the given window
726 *
727 * Selects and shows the window given by \a win_id and all it's child windows where applicable.
728 *
729 * \param win_id the id of the window to show
730 *
731 * \sa select_window
732 *
733 * \pre If \a win_id < 0 this function returns without performing any actions.
734 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns without performing any actions.
735 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns without performing any actions.
736 */
737 void show_window(int win_id);
738
739 /*!
740 * \ingroup elwindows
741 * \brief Hides the given window.
742 *
743 * Hides the window given by \a win_id and all its child windows where applicable.
744 *
745 * \param win_id the id of the window to hide.
746 *
747 * \pre If \a win_id < 0 this function returns without performing any actions.
748 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns without performing any actions.
749 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns without performing any actions.
750 */
751 void hide_window(int win_id);
752
753 /*!
754 * \ingroup elwindows
755 * \brief Toggles the visibility of the given window.
756 *
757 * Toggles the visibility of the window given by \a win_id, by either calling \ref hide_window or \ref show_window.
758 *
759 * \param win_id the id of the window to toggle.
760 *
761 * \callgraph
762 *
763 * \pre If \a win_id < 0 this function returns without performing any actions.
764 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns without performing any actions.
765 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns without performing any actions.
766 */
767 void toggle_window(int win_id);
768
769 /*!
770 * \ingroup elwindows
771 * \brief Sets the new size of a resizable window.
772 *
773 * Resizes the window given by \a win_id to given \a new_width and \a new_height, if the window is resizable. Whether a window is resizable or not is determined by looking if the \ref window_info::resize_handler equals NULL or not.
774 *
775 * \param win_id the id of the window to resize
776 * \param new_width the new width of the window
777 * \param new_height the new height of the window
778 *
779 * \callgraph
780 *
781 * \pre If \a win_id < 0 this function returns without performing any actions.
782 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns without performing any actions.
783 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns without performing any actions.
784 * \pre If \a new_width is less than the minimum width (\ref window_info::min_len_x) it will be adjusted accordingly before applying.
785 * \pre If \a new_height is less than the minimum height (\ref window_info::min_len_y) it will be adjusted acoordingly before applying.
786 */
787 void resize_window (int win_id, int new_width, int new_height);
788
789 /*!
790 * \ingroup elwindows
791 * \brief Checks whether a window is currently displayed and returns a proper boolean value.
792 *
793 * Returns the visibility status of the window given by \a win_id in a boolean value.
794 *
795 * \param win_id the id of the window to check
796 * \retval int 0 (false) if the window is hidden, else 1 (true).
797 *
798 * \pre If \a win_id < 0, this function returns false (0), without performing any actions.
799 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns false (0), without performing any actions.
800 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns false (0), without performing any actions.
801 */
802 int get_show_window(int win_id);
803
804 /*!
805 * \ingroup elwindows
806 * \brief Checks whether a window is currently displayable and returns a proper boolean value.
807 *
808 * Checks if a window is either displayed or would be if its parent were visible
809 *
810 * \param win_id the id of the window to check
811 * \retval int 0 (false) if the window is hidden, else 1 (true).
812 *
813 * \pre If \a win_id < 0, this function returns false (0), without performing any actions.
814 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns false (0), without performing any actions.
815 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns false (0), without performing any actions.
816 */
817 int get_window_showable(int win_id);
818
819 //void collapse_window(int win_id); // future expansion
820 //void expand_window(int win_id); // future expansion
821
822 /*!
823 * \ingroup elwindows
824 * \brief Checks if the mouse coordinates are inside a window.
825 *
826 * Checks whether the given mouse coordinates \a x and \a y are within the window given by \a win_id and returns either a boolean value or an error.
827 *
828 * \param win_id the id of the window to check for the coordinates \a x and \a y
829 * \param x the x location of the mouse cursor to check
830 * \param y the y location of the mouse cursor to check
831 * \retval int -1, if either \a win_id < 0, or \a win_id is greater than \ref windows_info::num_windows,
832 * or if \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array.
833 * 0 (false), if the coordinates \a x and \a y are outside the window given by \a win_id,
834 * else 1 (true).
835 *
836 * \pre If \a win_id < 0, this function returns -1, without performing any actions, indicating an error.
837 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns -1, without performing any actions, indicating an error.
838 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns -1 without performing any actions, indicating an error.
839 */
840 int mouse_in_window(int win_id, int x, int y); // is a coord in the window?
841
842 /*!
843 * \ingroup elwindows
844 * \brief Checks if there is a click in a window at the given coordinates.
845 *
846 * Checks whether a click occured inside the window given by \a win_id, at the coordinates \a x and \a y and returns a boolean value or an error.
847 *
848 * \param win_id the id of the window to check
849 * \param x the x coordinate of the cursor position where the click occured
850 * \param y the y coordinate of the cursor position where the click occured
851 * \param flags the window flags of the window. They will be given to the \ref window_info::click_handler that handles the actual click event.
852 * \retval int -1, if either \a win_id < 0, or \a win_id is greater than \ref windows_info::num_windows,
853 * of if \a win_id is not equal the \ref window_info::window_id of the given at index \a win_id into the \ref windows_list array.
854 * 1 (true), if the cursor is actualy inside the window,
855 * else 0 (false).
856 * \callgraph
857 *
858 * \pre If \a win_id < 0, this function returns -1, without performing any actions, indicating an error.
859 * \pre If \a win_id is greater than \ref windows_info::num_windows, this function returns -1, without performing any actions, indicating an error.
860 * \pre If \a win_id is not equal the \ref window_info::window_id of the window at index \a win_id into the \ref windows_list array, this function returns -1, without performing any actions, indicating an error.
861 */
862 int click_in_window(int win_id, int x, int y, Uint32 flags); // click in a coord in the window
863
864 /*!
865 * \ingroup elwindows
866 * \brief Sets the length of the window's scrollbar
867 *
868 * Sets the length of the window's scrollbar, ie. how many pixels you want it to scroll down.
869 *
870 * \param win_id The id of the scrollable window
871 * \param bar_len The amount of pixels you want the bar to scroll.
872 */
873 void set_window_scroll_len(int win_id, int bar_len);
874
875 /*!
876 * \ingroup elwindows
877 * \brief Sets the scrollbar additional y offset
878 *
879 * Normally the scrollbar is drawn from the top of the window or
880 * just under the close bar (if one is in use). Use this function
881 * to move down further and have the size adjusted as required.
882 *
883 * \param win_id The id of the scrollable window
884 * \param yoffset The number of pixels you want the bar moved down.
885 */
886 void set_window_scroll_yoffset(int win_id, int yoffset);
887
888 /*!
889 * \ingroup elwindows
890 * \brief Sets the scrollbar increment size
891 *
892 * Set the number of pixels the window is moved up/down when the
893 * scrollbar is moved one position.
894 *
895 * \param win_id The id of the scrollable window
896 * \param inc The number of pixels moved when scrolling.
897 */
898 void set_window_scroll_inc(int win_id, int inc);
899
900 /*!
901 * \ingroup elwindows
902 * \brief Sets the scrollbar position
903 *
904 * Sets the scrollbar position, i.e. the number of pixels
905 * the window is scrolled down.
906 *
907 * \param win_id The id of the scrollable window
908 * \param pos The new position for the scrollbar.
909 */
910 void set_window_scroll_pos(int win_id, int pos);
911
912 /*!
913 * \ingroup elwindows
914 * \brief Get the scrollbar position
915 *
916 * Get the scrollbar position, i.e. the number of pixels
917 * the window is currently scrolled down.
918 *
919 * \param win_id The id of the scrollable window
920 * \retval int The number of the pixels the window is currently offset.
921 */
922 int get_window_scroll_pos(int win_id);
923
924 /*!
925 * \ingroup elwindows
926 * \brief Set the font category
927 *
928 * Set the font category for the text within the window with ID \a id window
929 * to \a cat.
930 *
931 * \param win_id The ID of the window
932 * \param cat The new font category
933 * \return 1 if the font category was sucessfully set, 0 on failure
934 */
935 int set_window_font_category(int win_id, font_cat cat);
936
937 /*!
938 * \ingroup elwindows
939 * \brief Get the content width of a window
940 *
941 * Get the content width of the window with identifier \a window_id. For non-scrollable windows,
942 * this is the normal window width. For scrollable windows, the width of the scrollbar is subtracted.
943 *
944 * \param window_id The ID of the window
945 * \return The content width of the window in pixels
946 */
947 int get_window_content_width(int window_id);
948
949 /*!
950 * \ingroup elwindows
951 * \brief The callback for context menu clicks
952 *
953 * Called when an option is selected from the title context menu. If
954 * the user window wants to use their own callback, they should still
955 * call this function to implement the title menu options.
956 *
957 * \param win Pointer to the windows structure
958 * \param widget_id The id of the widget clicked to open the menu or -1.
959 * \param mx The x coordinate in window of where the user clicked to open the window
960 * \param my The y coordinate as above
961 * \param option The menu line clicked, first line is 0
962 * \retval int 1 if action was taken otherwise 0
963 */
964 int cm_title_handler(window_info *win, int widget_id, int mx, int my, int option);
965
966 // low level functions
967 //window_info *get_window_info(int win_id);
968 //window_info *get_window_by_name(const Uint8 *name);
969
970 // default handlers - VERY basic
971 //int init_handler(window_info *win);
972 //int display_handler(window_info *win);
973 //int click_handler(window_info *win);
974 //int mouseover_handler(window_info *win);
975
976
977 /*!
978 * \name managed window wrapper functions
979 */
980 /*! @{ */
hide_window_MW(enum managed_window_enum managed_win)981 static inline void hide_window_MW(enum managed_window_enum managed_win) { hide_window(get_id_MW(managed_win)); }
show_window_MW(enum managed_window_enum managed_win)982 static inline void show_window_MW(enum managed_window_enum managed_win) { show_window(get_id_MW(managed_win)); }
get_show_window_MW(enum managed_window_enum managed_win)983 static inline int get_show_window_MW(enum managed_window_enum managed_win) { return get_show_window(get_id_MW(managed_win)); }
984 /*! @} */
985
986 #ifdef __cplusplus
987 } // extern "C"
988 #endif
989
990 #endif //__EL_WINDOWS_H
991