Next: libhlp, Previous: libglb, Up: C API

### 5.21 libgui

#### 5.21.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/coverage/src/lib/gui/index.html.

#### 5.21.2 API

— Function: void lw6gui_button_register_down (lw6gui_button_t * button, int64_t timestamp)

> button: the button to update

> timestamp: the current ticks (milliseconds)

> Registers a "down" (press) event on a button.

> Return value: none.

— Function: void lw6gui_button_register_up (lw6gui_button_t * button)

> button: the button to update

> Registers a "up" (release) event on a button.

> Return value: none.

— Function: int lw6gui_button_is_pressed (lw6gui_button_t * button)

> button: the button to query

> Tells wether a button is pressed or not.

> Return value: 1 if pressed, 0 if not.

— Function: int lw6gui_button_pop_press (lw6gui_button_t * button)

> button: the button to query

> Tells how many times the button has been pressed. Typical usage: the button is pressed, released, pressed, released several times. Then, after all this, you want to know how many times it has been pressed. Querying its state with `lw6gui_button_is_pressed` won't tell you much but this `pop_press` function will return 1 for each press there's been.

> Return value: 1 if there's a press event in the queue, 0 if empty.

— Function: int lw6gui_button_pop_simple_click (lw6gui_button_t * button)

> button: the button to query

> Tells how many times the button has been simpleclicked. This is different from a simple press, in fact, there's a delay, we must wait until the double-click delay is elapsed to make sure this is a simple click... Designed for use with mouse to differentiate fire and alternate fire.

> Return value: 1 if there's a simpleclick event in the queue, 0 if empty.

— Function: int lw6gui_button_pop_double_click (lw6gui_button_t * button)

> button: the button to query

> Tells how many times the button has been doubleclicked. Typical usage: the button is doubleclicked, released, doubleclicked, released several times. Then, after all this, you want to know how many times it has been doubleclicked.

> Return value: 1 if there's a doubleclick event in the queue, 0 if empty.

— Function: int lw6gui_button_pop_triple_click (lw6gui_button_t * button)

> button: the button to query

> Tells how many times the button has been tripleclicked. Typical usage: the button is tripleclicked, released, tripleclicked, released several times. Then, after all this, you want to know how many times it has been tripleclicked.

> Return value: 1 if there's a tripleclick event in the queue, 0 if empty.

— Function: void lw6gui_button_update_repeat (lw6gui_button_t * button, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> button: the button to update

> repeat_settings: the repeat settings

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a button, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_button_sync (lw6gui_button_t * dst, lw6gui_button_t * src)

> dst: the target button object

> src: the source button object

> Synchronizes two button objects. This is typically used to pass data from one thread to another. This is not a simple copy, it will handle data such as "when was it pressed last" it an intelligent manner, popping src data to put it in dst, and clearing src.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_coord_calc_xy (float * dst_x, float * dst_y, float dst_x0, float dst_y0, float dst_w, float dst_h, float src_x, float src_y, float src_x0, float src_y0, float src_w, float src_h)

> dst_x: the x coord to return

> dst_y: the y coord to return

> dst_x0: the x coord of point 0 in destination coord system

> dst_y0: the y coord of point 0 in destination coord system

> dst_w: the width of the area in destination coord system

> dst_h: the width of the area in destination coord system

> src_x: the x coord in source coord system

> src_y: the y coord in source coord system

> src_x0: the x coord of point 0 in source coord system

> src_y0: the y coord of point 0 in source coord system

> src_w: the width of the area in source coord system

> src_h: the width of the area in source coord system

> Registers a "down" (press) event on a button.

> Return value: 1 if OK, 0 if error (unable to calculate).

— Function: void lw6gui_coords_fix_xy_float (float * x, float * y, int * x_flip, int * y_flip, float w, float h, int x_polarity, int y_polarity)

> x: x coord (in/out param)

> y: y coord (in/out param)

> x_flip: flip on x (out param, -1 or +1)

> y_flip: flip on y (out param, -1 or +1)

> w: width

> h: height

> x_polarity: x polarity (-1, 0 or 1)

> y_polarity: y polarity (-1, 0 or 1)

> Same as `lw6map_fix_coords` except it operates on floats. Usefull for cursor and other rendering operations. Additionnally, will keep track of inversions, that is to say if map is flip in one or another way. Be carefull, the flip values are -1 or 1 so that it's easy to multiply an offset by it, for instance, but this means testing if flip is not 0 will always return true, you must test if flip is stritly positive or negative.

> Return value: none

— Function: int lw6gui_input_init (lw6gui_input_t * input)

> input: the input struct to initialise

> Initialises an input structure, don't use twice, it won't free a previous init.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_input_quit (lw6gui_input_t * input)

> input: the input struct to uninitialise

> Unitialises an input structure, need to call it to free event queue.

> Return value: a pointer to the newly allocated object.

— Function: lw6gui_input_t * lw6gui_input_new ()

> Creates an input structure, which can be used to handle input state & buffer.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_input_free (lw6gui_input_t * input)

> input: the input object to free.

> Deletes an input structure.

> Return value: none.

— Function: int lw6gui_input_reset (lw6gui_input_t * input)

> input: the input struct to reset

> Resets an input structure. Must have been initialized before. It will empty all queues and mark everything as unpressed.

> Return value: 1 on success, 0 if failure.

— Function: void lw6gui_input_update_repeat (lw6gui_input_t * input, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> input: the input to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for an input, must be called regularly, as often as possible.

> Return value: none.

— Function: void lw6gui_input_register_change (lw6gui_input_t * input)

> input: the input to update

> Tells an input object that one of its descendants has been modified. This will affect the return value of `lw6gui_input_need_sync`

> Return value: none.

— Function: int lw6gui_input_need_sync (lw6gui_input_t * input)

> input: the input to test

> Tests wether an input object contains was modified and needs synchronisation.

> Return value: 1 if sync is need, 0 if not.

— Function: int lw6gui_input_sync (lw6gui_input_t * dst, lw6gui_input_t * src)

> dst: the target input object

> src: the source input object

> Synchronizes two input objects. This is typically used to pass data from one thread to another. This is not a copy, it will brute-force copy the static data such as mouse position, but anything like a queue will be treated in a "empty source and fill target with data" scheme. So source will be affected by this, the key buffer will be emptied, and so on. And if there are key in the target buffer, they won't be overwritten but kept in front of the FIFO list.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_joystick_check_index (int i)

> i: index to check

> Checks wether the index is correct. Does not mean the joystick exists, it's just to avoid out of bounds errors.

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_axis_x (lw6gui_joystick_t * joystick, int x, int limit, int64_t timestamp)

> joystick: joystick to update

> x: x-axis position, as returned by the driver

> limit: the limit, under this, buttons are considered unpressed.

> timestamp: current ticks (timestamp in ms)

> Updates the x axis of a joystick, this will convert an information of analog type such as "joystick is here" to a pad-like information such as "pressed in that direction".

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_axis_y (lw6gui_joystick_t * joystick, int y, int limit, int64_t timestamp)

> joystick: joystick to update

> limit: the limit, under this, buttons are considered unpressed.

> timestamp: current ticks (timestamp in ms)

> Updates the y axis of a joystick, this will convert an information of analog type such as "joystick is here" to a pad-like information such as "pressed in that direction".

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_repeat (lw6gui_joystick_t * joystick, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> joystick: the joystick to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a joystick, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_joystick_sync (lw6gui_joystick_t * dst, lw6gui_joystick_t * src)

> dst: the target joystick object

> src: the source joystick object

> Synchronizes two joystick objects. This is typically used to pass data from one thread to another.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_joystick_get_move_pad (lw6gui_joystick_t * joystick, lw6gui_move_pad_t * move_pad)

> joystick: the joystick to query

> move_pad: the structure which will contain the results

> Returns the state of the joystick in a uniform, non-device specific structure containing only the up/down/left/right information.

> Return value: none, the value are stored in `move_pad`.

— Function: int lw6gui_keyboard_check_keysym (int keysym)

> keysym: the keysym to check

> Tells wether the keysym is valid or not.

> Return value: 1 if valid, 0 if not

— Function: lw6gui_keypress_t * lw6gui_keyboard_pop_keypress (lw6gui_keyboard_t * keyboard)

> keyboard: the keyboard structure which stores keyboard state

> Pops (in FIFO mode) a keypress stored in the keyboard buffer. You must free the obtained keypress object after you're done with it.

> Return value: a newly allocated pointer, or NULL if no keypress pending.

— Function: int lw6gui_keyboard_is_pressed (lw6gui_keyboard_t * keyboard, int keysym)

> keyboard: the keyboard structure which stores keyboard state

> Tells wether a key is pressed or not. The function will test out of bound values.

> Return value: 1 if pressed, 0 if not.

— Function: int lw6gui_keyboard_register_key_down (lw6gui_keyboard_t * keyboard, int keysym, int unicode, char * label, int64_t timestamp)

> keyboard: the keyboard structure which will store the keypress

> keysym: the keysym for the keypress

> unicode: the ASCII/unicode code for the keypress

> label: the label for the keypress

> timestamp: the current ticks (timestamp in ms)

> Registers a keypress event, that is, puts it in the event queue. This function does not take an `lw6gui_keypress_t` structure but separated args, this is because it will construct the object internally. You may free `label` after calling this, an internal copy will be done. This function will also maintain the array of key states up to date.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_keyboard_register_key_up (lw6gui_keyboard_t * keyboard, int keysym)

> keyboard: the keyboard structure which will store the keypress

> keysym: the keysym for the keypress

> Registers a key release event.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_keyboard_update_repeat (lw6gui_keyboard_t * keyboard, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> keyboard: the keyboard to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a keyboard, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_keyboard_sync (lw6gui_keyboard_t * dst, lw6gui_keyboard_t * src)

> dst: the target keyboard object

> src: the source keyboard object

> Synchronizes two keyboard objects. This is typically used to pass data from one thread to another. Will pop the src queue to fill the dst queue.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_keyboard_get_move_pad (lw6gui_keyboard_t * keyboard, lw6gui_move_pad_t * move_pad)

> keyboard: the keyboard to query

> move_pad: the structure which will contain the results

> Returns the state of the keyboard in a uniform, non-device specific structure containing only the up/down/left/right information.

> Return value: none, the value are stored in `move_pad`.

— Function: lw6gui_keypress_t * lw6gui_keypress_new (int keysym, int unicode, char * label)

> keysym: the keysym to use

> unicode: the unicode value for this keysym

> label: the label (optional, might be NULL)

> Creates a keypress structure, the only reason for needing a contructor is that the label field needs be duplicated.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_keypress_free (lw6gui_keypress_t * keypress)

> keypress: the keypress object to free.

> Deletes a keypress structure.

> Return value: none.

— Function: char * lw6gui_keypress_repr (lw6gui_keypress_t * keypress)

> keypress: the keypress to work on

> Returns a human-readable representation of the keypress.

> Return value: a newly allocated string

— Function: lw6gui_menu_t * lw6gui_menu_new (char * title, char * help, char * popup, char * esc, int enable_esc)

> title: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.

> help: a string introducing the menu, describing what it does, giving hints on how to use it.

> popup: a string to be displayed in popup mode when menu is displayed for the first time.

> esc: the label to be displayed in the ESC button

> enable_esc: wether to enable the escape button.

> Constructs a new menu object. Note that you can always call other functions to modify it afterwards.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_menu_free (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Frees the menu, checking if things are OK before doing so.

> Return value: none.

— Function: int lw6gui_menu_memory_footprint (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Gets the memory occupied by the menu. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.

> Return value: the number of bytes used.

— Function: char * lw6gui_menu_repr (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.

> Return value: a string describing the object, must be freed.

— Function: void lw6gui_menu_set_title (lw6gui_menu_t * menu, char * title)

> menu: a pointer to the menu.

> title: the new title, you can free it after calling the function, an internal copy will be made.

> Change the title of the menu. Use this function to change the title, don't try to access the struct directly. The idea is to have safe memory management.

> Return value: none

— Function: void lw6gui_menu_set_help (lw6gui_menu_t * menu, char * help)

> menu: a pointer to the menu.

> help: the new help, you can free it after calling the function, an internal copy will be made.

> Change the help of the menu. Use this function to change the help, don't try to access the struct directly. The idea is to have safe memory management.

> Return value: none

— Function: void lw6gui_menu_set_popup (lw6gui_menu_t * menu, char * popup)

> menu: a pointer to the menu.

> popup: the new popup, you can free it after calling the function, an internal copy will be made.

> Change the popup of the menu. That is to say, its popup. Use this function to change the popup, don't try to access the struct directly. The idea is to have safe memory management.

> Return value: none

— Function: void lw6gui_menu_close_popup (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Closes the popup, in practice, this is equivalent to setting the popup string to "" or NULL.

> Return value: none

— Function: int lw6gui_menu_has_popup (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Tells wether a popup is defined. Behavior is simplistic, at creation (when a non-NULL non-empty popup string has been set) then the popup is displayed. In this state, popup is considered to be defined. Then it can be close, and after this action the popup ain't here anymore, program continues the way it started.

> Return value: 1 if has popup, 0 if does not

— Function: lw6gui_menuitem_t * lw6gui_menu_get_item (lw6gui_menu_t * menu, int position)

> menu: the menu we want to query

> position: the order of the item we want

> Gets the menu item at the given position. First item is 0, last is N-1. Returns a pointer on the real object, not a copy.

> Return value: a pointer to a menu item, NULL if out of range.

— Function: int lw6gui_menu_select (lw6gui_menu_t * menu, int position, int allow_scroll, int64_t now)

> menu: the menu we want to modify

> position: the position of the item we want to select

> allow_scroll: wether scrolling should be allowed when displaying it

> now: the current time, as a timestamp.

> Selects the item at the given position. Use this function to be sure that only one item is selected, and all other states are consistent. Timestamp is needed for the sake of eye-candy.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_select_esc (lw6gui_menu_t * menu, int state, int64_t now)

> menu: the menu we want to modify

> state: 1 to select, 0 to unselect

> now: the current time, as a timestamp.

> Selects the escape item, this does not affect other items, it's mostly. to handle eye candy.

> Return value: none.

— Function: void lw6gui_menu_enable_esc (lw6gui_menu_t * menu, int state, int64_t now)

> menu: the menu we want to modify

> state: 1 to enable, 0 to disable

> now: the current time, as a timestamp.

> Enables the escape item, this does not affect other items, it's mostly. to handle eye candy.

> Return value: none.

— Function: int lw6gui_menu_scroll_up (lw6gui_menu_t * menu)

> menu: the menu to scroll

> Scrolls a menu up, used as a callback for mouse wheel up for instance. The idea is just to decrement the first displayed item index.

> Return value: 1 if OK, 0 if failed (out of range).

— Function: int lw6gui_menu_scroll_down (lw6gui_menu_t * menu)

> menu: the menu to scroll

> Scrolls a menu down, used as a callback for mouse wheel down for instance. The idea is just to increment the first displayed item index.

> Return value: 1 if OK, 0 if failed (out of range).

— Function: int lw6gui_menu_set_breadcrumbs (lw6gui_menu_t * menu, lw6sys_list_t * breadcrumbs)

> menu: the menu to scroll

> breadcrumbs: list of strings containing breadcrumbs

> Set the breadcrumbs, that's to say the readable, logical path to get to a given menu. This is just eye candy, not linked to any logic at this level.

> Return value: 1 if OK, 0 if failed.

— Function: void lw6gui_menu_center (lw6gui_menu_t * menu, int position, int max_displayed_items)

> menu: the menu to center

> position: the position of the menuitem to be put in the center

> max_displayed_items: the maximum number of items displayed

> Centers the menu on a given menuitem. Typically used when pushing a menu with a menuitem selected 'anywhere' in the list.

> Return value: none.

— Function: int lw6gui_menu_insert (lw6gui_menu_t * menu, lw6gui_menuitem_t * menuitem, int position, int64_t now)

> menu: the menu we want to modify

> menuitem: the item to insert

> position: the position the new item will occupy ("insert before" mode)

> now: the current time, as a timestamp.

> Inserts the given item in the menu. All items starting at the insert position will be "pushed" (that is, their position incremented by 1). Once the menuitem is inserted, the menu object will take care of memory management and automatically free it when needed.

> Return value: 1 if success, 0 if failure (memory problem, out of range).

— Function: int lw6gui_menu_append (lw6gui_menu_t * menu, lw6gui_menuitem_t * menuitem, int64_t now)

> menu: the menu we want to modify

> menuitem: the item to insert

> now: the current time, as a timestamp.

> Appends the given item to the menu. Once the menuitem is appended, the menu object will take care of memory management and automatically free it when needed.

> Return value: 1 if success, 0 if failure (memory problem).

— Function: int lw6gui_menu_remove (lw6gui_menu_t * menu, int position, int64_t now)

> menu: the menu we want to modify

> position: the item to insert

> now: the current time, as a timestamp.

> Removes an item from the menu. It will automatically be freed.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_update_display_range (lw6gui_menu_t * menu, int max_displayed_items)

> menu: the menu concerned

> max_displayed_items: the maximum number of items to display at once

> Updates the display range. The reason for having this is that the first item, that is, how far we scroll in a very long menu, depends on the previous position. Plus you have to handle limit cases (begin/end). Thus, this function, which will automatically pick-up a suitable position. Of course, `first_item_displayed` is not necessarly equal to `selected_item`.

> Return value: none.

— Function: int lw6gui_menu_insert_for_id_use (lw6gui_menu_t * menu, char * label, char * tooltip, int value, int enabled, int selected, int colored, int position, int64_t now)

> menu: the menu to work on

> label: the label of the menuitem to append

> tooltip: the tooltip of the menuitem to append

> value: the value of the menuitem to append

> enabled: wether the inserted menuitem should be enabled

> selected: wether the inserted menuitem should be selected

> colored: wether the inserted menuitem should use value as its color

> now: current time (timestamp)

> Inserts a menu item at the given position. The idea is that the menu item object is automatically constructed on the fly, and an id is returned, which can be passed to '_using_id' menu-related functions. This is typically for using in scripts. The idea is that the script just keeps a copy of the id returned, and can this way operate directly on the menuitem without keeping a pointer, a smob or anything internally. From the C point of view, having a real C structure enables persistent data from one display to the other, and this is nice and conveninent. I acknowledge the prototype is scary.

> Return value: 0 if error, or else an id which will later be used with '_using_id' functions.

— Function: int lw6gui_menu_append_for_id_use (lw6gui_menu_t * menu, char * label, char * tooltip, int value, int enabled, int selected, int colored, int64_t now)

> menu: the menu to work on

> label: the label of the menuitem to append

> tooltip: the tooltip of the menuitem to append

> value: the value of the menuitem to append

> enabled: wether the appended menuitem should be enabled

> selected: wether the appended menuitem should be selected

> colored: wether the appended menuitem should use value as its color

> now: current time (timestamp)

> Appends a menuitem using the same logic as `lw6gui_menu_insert_for_id_use` that is to say a parameter is returned which can later be used to directly operate on a given menuitem, without having its pointer, and even if its position changes.

> Return value: 0 if error, or else an id which will later be used with '_using_id' functions.

— Function: int lw6gui_menu_remove_using_id (lw6gui_menu_t * menu, int menuitem_id, int64_t now)

> menu: the menu to work on

> menuitem_id: the id of the menuitem to remove

> now: current time (timestamp)

> Deletes the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_sync_using_id (lw6gui_menu_t * menu, int menuitem_id, char * label, char * tooltip, int value, int enabled, int selected, int colored, int64_t now)

> menu: the menu to work on

> menuitem_id: the id of the menuitem to synchronize

> label: menu label

> tooltip: menu tooltip

> value: value

> enabled: wether it's usable or not

> selected: 1 if the menuite is current item

> colored: wether to use color

> now: current time (timestamp)

> Updates the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem. In practice, it's heavily used in the game to transmit informations from the scripts to the core C engine. Additionnaly, this function will automatically synchronize the `selected_item` field of the menu struct.

> Return value: 1 if success, 0 if failure (out of range).

— Function: int lw6gui_menu_is_same (lw6gui_menu_t * menu_a, lw6gui_menu_t * menu_b)

> menu_a: first item to compare

> menu_b: second item to compare

> Compares two menus.

> Return value: 1 if they are the same, 0 if not

— Function: lw6gui_menu_t * lw6gui_menu_dup (lw6gui_menu_t * menu)

> menu: the menu to duplicate

> Duplicates a menu structure.

> Return value: a pointer to the new menu.

— Function: int lw6gui_menu_sync (lw6gui_menu_t * dst, lw6gui_menu_t * src)

> dst: the target menu

> src: the source menu

> Synchronizes two menus, this supposes that they represent the same menu, but simply in a different state. This function does not really copy src to dst, it has a special behavior, indeed everything is copied from src to dst, except the `first_item_displayed` and `nb_items_displayed` which are taken from dst and copied to src. This is because in practise, those values are updated in the display loop/thread, which is the one which uses the target. This is not very orthodox, but should work.

> Return value: 1 if success, 0 if failure

— Function: lw6gui_menuitem_t * lw6gui_menuitem_new (char * label, char * tooltip, int value, int enabled, int selected, int colored)

> label: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.

> tooltip: the string to be displayed as a tooltip, describing the menu item in detail. Can be NULL if you don't want to use this feature.

> value: the value. No GUI function uses this, this is the "real" value associated to the item.

> enabled: wether the menu item can be selected, used, and so on

> selected: wether the menu item is the item selected among all menu items.

> colored: wetherr the menu item must, when drawn, be colored according to its value.

> Constructs a new menuitem object. Note that you can always call other functions to modify these values afterwards, this might change rendering since `lw6gui_menuitem_set_value` or `lw6gui_menuitem_set_label` will, for instance, modify the "when was that item last modified" information.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_menuitem_free (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Frees the menuitem, checking if things are OK before doing so.

> Return value: none.

— Function: int lw6gui_menuitem_memory_footprint (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Gets the memory occupied by the menuitem. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.

> Return value: the number of bytes used.

— Function: char * lw6gui_menuitem_repr (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.

> Return value: a string describing the object, must be freed.

— Function: void lw6gui_menuitem_set_label (lw6gui_menuitem_t * menuitem, char * label, int64_t now)

> menuitem: a pointer to the menuitem.

> label: the new label, you can free it after calling the function, an internal copy will be made.

> now: the current time, as a timestamp.

> Change the label of the menu item. That is to say, what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is 1) to have safe memory management and 2) to keep the `last_change` member up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_set_tooltip (lw6gui_menuitem_t * menuitem, char * tooltip, int64_t now)

> menuitem: a pointer to the menuitem.

> tooltip: the new tooltip, you can free it after calling the function, an internal copy will be made.

> now: the current time, as a timestamp.

> Change the tooltip of the menu item (the explanation of what the item is about) Use this function to change the menuitem value, don't try to access the struct directly. The idea is 1) to have safe memory management and 2) to keep the `last_change` member up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_set_value (lw6gui_menuitem_t * menuitem, int value, int64_t now)

> menuitem: a pointer to the menuitem.

> value: the new value.

> now: the current time, as a timestamp.

> Changes the value of a menuitem. This is the internal value, not what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is to keep the `last_change` member up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_select (lw6gui_menuitem_t * menuitem, int state, int64_t now)

> menuitem: a pointer to the menuitem.

> state: 1 to select, 0 to unselect

> now: the current time, as a timestamp.

> Switches the menuitem to (un)selected state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_select` parameter up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_enable (lw6gui_menuitem_t * menuitem, int state, int64_t now)

> menuitem: a pointer to the menuitem.

> state: 1 to enable, 0 to disable

> now: the current time, as a timestamp.

> Switches the menuitem to enabled/disabled state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_select` parameter up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: u_int32_t lw6gui_menuitem_checksum (lw6gui_menuitem_t * menuitem, lw6gui_look_t * look)

> menuitem: the menuitem we want to identify

> Returns a checksum which can be used to know, for instance, wether the menuitem has changed or not, and if we should redraw it.

> Return value: a checksum.

— Function: int lw6gui_menuitem_is_same (lw6gui_menuitem_t * menuitem_a, lw6gui_menuitem_t * menuitem_b)

> menuitem_a: first item to compare

> menuitem_b: second item to compare

> Compares two menuitems.

> Return value: 1 if they are the same, 0 if not

— Function: lw6gui_menuitem_t * lw6gui_menuitem_dup (lw6gui_menuitem_t * menuitem)

> menuitem: the menuitem to duplicate

> The menuitem to duplicate.

> Return value: a pointer to the duplicted menuitem.

— Function: int lw6gui_menuitem_sync (lw6gui_menuitem_t * dst, lw6gui_menuitem_t * src)

> dst: the target menuitem

> src: the source menuitem

> Synchronizes two menuitems, this supposes that they represent the same item, but simply in a different state.

> Return value: 1 if success, 0 if failure

— Function: void lw6gui_mouse_register_move (lw6gui_mouse_t * mouse, int screen_pos_x, int screen_pos_y, int64_t timestamp)

> mouse: the mouse object to work on

> screen_pos_x: the x position on screen

> screen_pos_y: the y position on screen

> timestamp: current timestamp

> Registers a mouse move event.

> Return value: note.

— Function: int lw6gui_mouse_poll_move (lw6gui_mouse_t * mouse, int * screen_pos_x, int * screen_pos_y)

> mouse: the mouse object to poll

> screen_pos_x: pointer to the x position (can be NULL), will be updated even if no move

> screen_pos_y: pointer to the y position (can be NULL), will be updated even if no move

> Asks wether the mouse has moved or not.

> Return value: 1 if mouse was moved since last call, 0 if not.

— Function: void lw6gui_mouse_update_repeat (lw6gui_mouse_t * mouse, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> mouse: the mouse to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a mouse, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_mouse_sync (lw6gui_mouse_t * dst, lw6gui_mouse_t * src)

> dst: the target mouse object

> src: the source mouse object

> Synchronizes two mouse objects. This is typically used to pass data from one thread to another. Will handle "mouse move" attribute and clear it in src if needed while setting it in dst.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_mouse_drag_begin (lw6gui_mouse_t * mouse)

> mouse: mouse struct to update

> To be called when one wants to start recording a drag session, typically when left button is pressed.

> Return value: none.

— Function: void lw6gui_mouse_drag_end (lw6gui_mouse_t * mouse)

> mouse: mouse struct to update

> To be called when one wants to stop recording a drag session, typically when left button is released.

> Return value: none.

— Function: int lw6gui_mouse_drag_pop (lw6gui_mouse_t * mouse, int * delta_x, int * delta_y, int * pos_x, int * pos_y, int * speed_x, int * speed_y)

> mouse: mouse struct to query

> delta_x: x movement (on screen, out param can be NULL)

> delta_y: y movement (on screen, out param can be NULL)

> pos_x: x pos (on screen, out param can be NULL)

> pos_y: y pos (on screen, out param can be NULL)

> speed_x: x speed (on screen, out param can be NULL)

> speed_y: y speed (on screen, out param can be NULL)

> To be called when one wants to stop recording a drag session, typically when left button is released.

> Return value: none.

— Function: int lw6gui_point_is_inside_rect (lw6gui_point_t point, lw6gui_rect_t * rect)

> point: point to test

> rect: rectangle in which point is supposed to be

> Tests wether a point is inside a rectangle, this is typically used to know if a point is inside the right texture or if we're outside.

> Return value: 1 if OK, 0 if outside

— Function: int lw6gui_quad_is_inside_rect (lw6gui_quad_t * quad, lw6gui_rect_t * rect)

> quad: quad to test

> rect: rectangle in which quad is supposed to be

> Tests wether a quad is inside a rectangle, this is typically used to know if a quad is inside the right texture or if we're outside.

> Return value: 1 if OK, 0 if outside

— Function: void lw6gui_rect_init_x1y1x2y2 (lw6gui_rect_t * rect, int x1, int y1, int x2, int y2)

> rect: the structure to initialize

> x1: x for top left corner

> y1: y for top left corner

> x2: x for bottom right corner

> y2: y for bottom right corner

> Initializes a rect structure, will calculate w & h.

> Return value: none.

— Function: void lw6gui_rect_init_xywh (lw6gui_rect_t * rect, int x, int y, int w, int h)

> rect: the structure to initialize

> x: x for top left corner

> y: y for top left corner

> w: width

> h: height

> Initializes a rect structure, will calculate x2 & y2.

> Return value: none.

— Function: void lw6gui_rect_clip (lw6gui_rect_t * dst, lw6gui_rect_t * src, lw6gui_rect_t * clip)

> dst: the structure which will contain the result

> src: the source rect

> clip: the clipping rect (boundaries)

> Clips a rect (think of rectangle clips).

> Return value: none.

— Function: int lw6gui_segment_is_inside_rect (lw6gui_segment_t * segment, lw6gui_rect_t * rect)

> segment: segment to test

> rect: rectangle in which segment is supposed to be

> Tests wether a segment is inside a rectangle, this is typically used to know if a segment is inside the right texture or if we're outside.

> Return value: 1 if OK, 0 if outside

— Function: void lw6gui_smoother_init (lw6gui_smoother_t * smoother, float value, int duration)

> smoother: the structure to initialize

> value: the value to use for now

> duration: the duration of a standard move, in ticks (msec)

> Initializes a smoother object, with a default value. The important point is the duration which will condition all the behavior of the object.

> Return value: none.

— Function: void lw6gui_smoother_immediate_force (lw6gui_smoother_t * smoother, float value)

> smoother: the structure to use

> value: the target value

> Forces a smoother object to immediately point on a value.

> Return value: none.

— Function: void lw6gui_smoother_set_target (lw6gui_smoother_t * smoother, float value, int64_t now)

> smoother: the structure to use

> value: the target value

> now: the current timestamp

> Sets a new target, will automatically calculate current speed to smooth the next returned values.

> Return value: none.

— Function: float lw6gui_smoother_get_value (lw6gui_smoother_t * smoother, int64_t now)

> smoother: the structure to use

> now: the current timestamp

> Returns the current value of the smoother.

> Return value: a float.

— Function: void lw6gui_smoother_fix_overflow (lw6gui_smoother_t * smoother, int step)

> smoother: object to modify

> step: step size, typically twice the map size

> Companion function of `lw6pil_coords_fix_x10`, this one will fix a smoother target to avoid crazy scrolls when cursor is on a map edge.

> Return value: none.

— Function: int lw6gui_test (int mode)

> mode: 0 for check only, 1 for full test

> Run tests in the gui module.

> Return value: 1 if successfull, 0 if failed.

— Function: int lw6gui_triangle_is_inside_rect (lw6gui_triangle_t * triangle, lw6gui_rect_t * rect)

> triangle: triangle to test

> rect: rectangle in which triangle is supposed to be

> Tests wether a triangle is inside a rectangle, this is typically used to know if a triangle is inside the right texture or if we're outside.

> Return value: 1 if OK, 0 if outside

— Function: int lw6gui_video_mode_find_closest (lw6gui_video_mode_t * closest, lw6gui_video_mode_t * wished, lw6sys_list_t * available)

> closest: the closest video_mode found

> wished: the wished video_mode

> available: a list of available video_modes (list of lw6gui_video_mode_t *)

> Finds the closest video_mode available, this is just a small utility to cope with different screen shapes and avoid requesting 640x480 when it's just not available but there's a 640x400 instead.

> Return value: 1 if the wished video_mode exists in available list and was found, else 0 if the wished video_mode doesn't exist and an approximative match was picked.

— Function: int lw6gui_video_mode_is_same (lw6gui_video_mode_t * mode_a, lw6gui_video_mode_t * mode_b)

> mode_a: first mode to compare

> mode_b: second mode to compare

> Compares two video modes, to know if they're the same.

> Return value: 1 if equal, 0 if not.

— Function: int lw6gui_video_mode_sync_ratio (lw6gui_video_mode_t * dst, lw6gui_video_mode_t * src)

> dst: the target video mode

> src: the source video mode

> Applies the ratio of src to dst, for instance if src is 16/9, then dst will be made 16/9 too, trying to keep the same surface.

> Return value: 1 on success, 0 on failure

— Function: int lw6gui_viewport_init (lw6gui_viewport_t * viewport, int screen_w, int screen_h, float drawable_x1, float drawable_y1, float drawable_x2, float drawable_y2, float center_x, float center_y, int map_w, int map_h, int x_polarity, int y_polarity, int x_wrap, int y_wrap, int keep_ratio, float global_zoom, float scroll_limit, int use_old_center)

> viewport: the viewport to initalize

> screen_w: screen width

> screen_h: screen height

> drawable_x1: viewport min x

> drawable_y1: viewport min y

> drawable_x2: viewport max x

> drawable_y2: viewport max y

> center_x: center of display (in map coordinates)

> center_y: center of display (in map coordinates)

> map_w: map width (shape)

> map_h: map height (shape)

> x_polarity: x polarity

> y_polarity: y polarity

> x_wrap: wether to wrap horizontally

> y_wrap: wether to wrap vertically

> keep_ratio: wether to adapt to viewport shape or keep original

> global_zoom: global zoom is style_zoom * dynamic_zoom

> scroll_limit: inside this zone, don't scroll

> use_old_center: wether to take previous center in account

> Initializes all the (jumbo?) viewport structure which will contain valuable informations for a simple "flat" display. Special renderers might not find usefull some fields and handle wrapping and zooming their own way, but this offers a basic skeleton.

> Return value: 1 if ok, 0 on failure

— Function: void lw6gui_viewport_map_to_screen (lw6gui_viewport_t * viewport, float * screen_x, float * screen_y, float map_x, float map_y, int clip)

> viewport: the viewport to use

> screen_x: the x coord on the screen

> screen_y: the y coord on the screen

> map_x: the x coord in map coordinates

> map_y: the y coord in map coordinates

> clip: wether to clip returned values

> Translates from map coords to screen coords. Returned values might be outside screen boundaries if clip is 0. If screen coords are outside drawable area anc clip is 1, then they will be clipped.

> Return value: NULL

— Function: void lw6gui_viewport_screen_to_map (lw6gui_viewport_t * viewport, float * map_x, float * map_y, float screen_x, float screen_y, int wrap)

> viewport: the viewport to use

> map_x: the x coord in map coordinates

> map_y: the y coord in map coordinates

> screen_x: the x coord on the screen

> screen_y: the y coord on the screen

> wrap: wether to use polarity informations to wrap coords.

> Translates from screen coords to map coords. If wrap is set, it will interpret coords the way `lw6map_coords_fix_xy` would, only it can still be formally outside map boundaries for it can return a value exactly equal to w,h while in interger mode it would be w-1,h-1.

> Return value: NULL

— Function: void lw6gui_viewport_calc_drag (lw6gui_viewport_t * viewport, float * map_dst_x, float * map_dst_y, float map_src_x, float map_src_y, int screen_dx, int screen_dy)

> viewport: viewport to work on

> map_dst_x: map det x coord (out param)

> map_dst_y: map dst y coord (out param)

> map_src_x: map src x coord

> map_src_y: map src y coord

> screen_dx: drag x (on screen)

> screen_dy: drag y (on screen)

> Used to calculate the new "center" when in drag mode.

> Return value: none.

— Function: void lw6gui_zone_init_x1y1x2y2 (lw6gui_zone_t * zone, float x1, float y1, float x2, float y2)

> zone: the structure to initialize

> x1: x for top left corner

> y1: y for top left corner

> x2: x for bottom right corner

> y2: y for bottom right corner

> Initializes a zone structure, will calculate w & h.

> Return value: none.

— Function: void lw6gui_zone_init_xywh (lw6gui_zone_t * zone, float x, float y, float w, float h)

> zone: the structure to initialize

> x: x for top left corner

> y: y for top left corner

> w: width

> h: height

> Initializes a zone structure, will calculate x2 & y2.

> Return value: none.

— Function: void lw6gui_zone_clip (lw6gui_zone_t * dst, lw6gui_zone_t * src, lw6gui_zone_t * clip)

> dst: the structure which will contain the result

> src: the source zone

> clip: the clipping zone (boundaries)

> Clips a zone (think of rectangle clips).

> Return value: none.