# os_window.h ## Overview
Implements window management.
## Index
`tm_display_o`
`TM_OS_DISPLAY_API_NAME`

`struct tm_os_display_api`
`num_displays()`
`display()`
`os_display_rect()`
`os_display_dpi_scale_factor()`
`refresh_display_enumeration()`

`DEFAULT_DISPLAY_DPI`
`tm_window_o`
`enum tm_os_window_style`
`struct tm_os_window_border_metrics_t`
`enum tm_os_window_state`
`enum tm_os_window_cursor_mode`
`enum tm_os_window_cursor`
`enum tm_os_window_adjust_rect`
`struct tm_window_platform_data_win32_o`
`struct tm_window_platform_data_macosx_o`
`struct tm_window_platform_data_linux_o`
`struct tm_window_platform_data_o`
`struct tm_window_status_t`
`struct tm_window_update_result_t`
`struct tm_os_dropped_file_t`
`TM_OS_WINDOW_API_NAME`

`struct tm_os_window_api`
`create_window()`
`update_window()`
`wait()`
`destroy_window()`
`set_rect()`
`rect()`
`dpi_scale_factor()`
`adjust_rect()`
`set_size()`
`has_user_requested_close()`
`set_cursor_mode()`
`cursor_mode()`
`set_cursor()`
`cursor()`
`dropped_files()`
`status()`
`set_border_metrics()`
`platform_data()`
`window_from_point()`
`set_focus()`
`set_window_state()`
`set_title()`

`struct tm_os_clipboard_item_t`
`TM_OS_CLIPBOARD_API_NAME`

`struct tm_os_clipboard_api`
`get()`
`set()`

## API
### `tm_display_o`
~~~c typedef struct tm_display_o tm_display_o; ~~~ Opaque object representing a display returned from `display()`.
### `TM_OS_DISPLAY_API_NAME`
~~~c #define TM_OS_DISPLAY_API_NAME "tm_os_display_api" ~~~
### `struct tm_os_display_api`
Interface used to enumerate displays. #### `num_displays()` ~~~c uint32_t (*num_displays)(void); ~~~ Returns the number of connected displays. #### `display()` ~~~c tm_display_o *(*display)(uint32_t index); ~~~ Returns `tm_display_o` for display `index`. #### `os_display_rect()` ~~~c tm_rect_t (*os_display_rect)(const tm_display_o *display); ~~~ Retrieves the operating system display rectangle for a display. #### `os_display_dpi_scale_factor()` ~~~c float (*os_display_dpi_scale_factor)(const tm_display_o *display); ~~~ Retrieves the operating systems display dpi scale factor for a display. #### `refresh_display_enumeration()` ~~~c void (*refresh_display_enumeration)(void); ~~~ A display enumeration is done when the `tm_os_display_api` is first accessed. The user can call `refresh_display_enumeration` to request a re-enumeration and handle display hot swapping.
### `DEFAULT_DISPLAY_DPI`
~~~c #define DEFAULT_DISPLAY_DPI 96 ~~~
### `tm_window_o`
~~~c typedef struct tm_window_o tm_window_o; ~~~ Opaque object representing a window returned from `create_window()`.`
### `enum tm_os_window_style`
Window style flags: ~~~c enum tm_os_window_style { // If not set, the window will be invisible after creation. TM_OS_WINDOW_STYLE_VISIBLE = 1, // If set, the window position will be adjusted to center on screen. TM_OS_WINDOW_STYLE_CENTERED = 2, // If set, the window will be created with a custom border that will follow the metrics specified by the `set_border_metrics` function. // If you don't provide custom metrics, the window will have a default resize margin of 1 pixel, and no caption. TM_OS_WINDOW_STYLE_CUSTOM_BORDER = 4, // If set, the window will automatically resize to the operating systems DPI scaling // Note: This is currently only supported on Windows. TM_OS_WINDOW_STYLE_DPI_SCALING_AWARE = 8, // If set, the window will be created without any border and reszing will be disabled. TM_OS_WINDOW_STYLE_BORDERLESS = 16 }; ~~~
### `struct tm_os_window_border_metrics_t`
Custom border metrics: used to define border behaviours for custom border windows. You are responsible for drawing both the margins and the captions. ~~~c typedef struct tm_os_window_border_metrics_t { // Number of pixels that will be used to detect the "Resize" region, starting from the border of the window. // This means that a window with a resize_margin of 0.0f won't be resizable at all, and a window with resize_margin of 1.0f // will just have a thin 1px resize region. float resize_margin; // Number of pixels that will be used to detect the "Caption" region, starting from the top of the window. // (Upper margin pixel is NOT included). float caption_height; // Reserved pixels in the title bar for client rendering. I.e. clicks in // either the left or right margin will not be considered "caption" region. float titlebar_margin_left; float titlebar_margin_right; } tm_os_window_border_metrics_t; ~~~
### `enum tm_os_window_state`
~~~c enum tm_os_window_state { // Maximize window TM_OS_WINDOW_STATE_MAXIMIZE, // Minimize window TM_OS_WINDOW_STATE_MINIMIZE, // Activates and displays the window, if window was maximized or minimized it will be restored // to its original position and size TM_OS_WINDOW_STATE_NORMAL }; ~~~
### `enum tm_os_window_cursor_mode`
Cursor behavior: ~~~c enum tm_os_window_cursor_mode { // The cursor is visible and can move freely on the screen. TM_OS_WINDOW_CURSOR_MODE_VISIBLE_AND_FREE, // The cursor is visible, but constrained to the frontmost window (as long as that window is // frontmost). This mode is useful for applications that want a cursor, but want to prevent the // user from accidentally clicking outside the window and switching to another application. A // typical example is an application running in "full-screen windowed mode". Without // constraining the mouse, the user could move it to a secondary display, click there and // deactivate the application. TM_OS_WINDOW_CURSOR_MODE_VISIBLE_AND_CONSTRAINED, // The cursor is hidden and immovable. In this mode, the application should exhibit the // following behaviors: // // * The cursor is hidden. // * Mouse clicking does not activate system menus or other applications. // * If the mode is changed to VISIBLE_AND_FREE, the cursor should reappear at the position // where it was hidden. // * Alt-tabbing to other applications is possible. // * When you alt-tab out the cursor reappears at its original position and can be moved. // * Alt-tabbing back hides the cursor again. // * If the cursor is moved when tabbed out, this sets a new position where the cursor will // appear when shown. TM_OS_WINDOW_CURSOR_MODE_HIDDEN_AND_LOCKED, }; ~~~
### `enum tm_os_window_cursor`
Cursor types. ~~~c enum tm_os_window_cursor { // Default cursor (arrow). TM_OS_WINDOW_CURSOR_DEFAULT, // Hovering over a link (hand). TM_OS_WINDOW_CURSOR_POINTER, // Text selection cursor (I-beam). TM_OS_WINDOW_CURSOR_TEXT, // Move cursor (4-way arrow). TM_OS_WINDOW_CURSOR_MOVE, // Scroll in any direction. TM_OS_WINDOW_CURSOR_ALL_SCROLL, // Resize column. TM_OS_WINDOW_CURSOR_COL_RESIZE, // Resize row. TM_OS_WINDOW_CURSOR_ROW_RESIZE, // Bidirectional resize. TM_OS_WINDOW_CURSOR_EW_RESIZE, TM_OS_WINDOW_CURSOR_NS_RESIZE, TM_OS_WINDOW_CURSOR_NESW_RESIZE, TM_OS_WINDOW_CURSOR_NWSE_RESIZE, // Drag cursors. TM_OS_WINDOW_CURSOR_DRAG_AND_DROP, TM_OS_WINDOW_CURSOR_DRAG_NO_DROP, // Hide the cursor. TM_OS_WINDOW_CURSOR_HIDE, }; ~~~
### `enum tm_os_window_adjust_rect`
Adjust rect behavior: ~~~c enum tm_os_window_adjust_rect { // Go from virtual coordinates to pixels. TM_OS_WINDOW_ADJUST_RECT_TO_PIXELS, // Go from pixels to virtual coordinates. TM_OS_WINDOW_ADJUST_RECT_TO_VIRTUAL, }; ~~~
### `struct tm_window_platform_data_win32_o`
~~~c typedef struct tm_window_platform_data_win32_o { uint64_t hwnd; uint64_t hinstance; } tm_window_platform_data_win32_o; ~~~
### `struct tm_window_platform_data_macosx_o`
~~~c typedef struct tm_window_platform_data_macosx_o { void *nswindow; } tm_window_platform_data_macosx_o; ~~~
### `struct tm_window_platform_data_linux_o`
~~~c typedef struct tm_window_platform_data_linux_o { uint64_t *connection; uint64_t window; } tm_window_platform_data_linux_o; ~~~
### `struct tm_window_platform_data_o`
~~~c typedef struct tm_window_platform_data_o { union { tm_window_platform_data_win32_o win32; tm_window_platform_data_macosx_o macosx; tm_window_platform_data_linux_o linuxos; }; } tm_window_platform_data_o; ~~~
### `struct tm_window_status_t`
~~~c typedef struct tm_window_status_t { // True if the window is the focused one (globally, not just within the current application). bool has_focus; // True if the window is the one under the cursor. bool is_under_cursor; // True if the window is minimized. bool is_minimized; // True if the window is in full-screen mode. bool is_maximized; // True if the window is hidden. bool is_hidden; } tm_window_status_t; ~~~
### `struct tm_window_update_result_t`
The result of a window update operation. ~~~c typedef struct tm_window_update_result_t { // The window gained or lost focus (or both) during the update. bool focus_changed; } tm_window_update_result_t; ~~~
### `struct tm_os_dropped_file_t`
Used for storing which files where dropped onto the window during this frame. ~~~c typedef struct tm_os_dropped_file_t { // The filename of the dropped file. char *filename; // The position relative to the window of where the drop ocurred. tm_vec2_t position; } tm_os_dropped_file_t; ~~~
### `TM_OS_WINDOW_API_NAME`
~~~c #define TM_OS_WINDOW_API_NAME "tm_os_window_api" ~~~
### `struct tm_os_window_api`
Interface used for creating windows. #### `create_window()` ~~~c tm_window_o *(*create_window)(const char *title, tm_rect_t rect, enum tm_os_window_style style_flags, const tm_display_o *center_display); ~~~ Creates a new window. Synchronization: Calls to `create_window()` and `destroy_window()` must be externally synchronized. * `title` - window title to display in title bar. * `rect` is for the windows client area (actual window size and position depends on style). * `style_flags` - bit mask composed of `enum tm_os_window_style` flags. * `center_display` - Optional. If provided and `TM_OS_WINDOW_STYLE_CENTERED` is set the window will be centered on the specified display. #### `update_window()` ~~~c tm_window_update_result_t (*update_window)(tm_window_o *window); ~~~ Runs the windows message pump until all messages have been processed. #### `wait()` ~~~c void (*wait)(void); ~~~ Blocks the thread until there are any window messages. Can be used to reduce resource consumption. #### `destroy_window()` ~~~c void (*destroy_window)(tm_window_o *window); ~~~ Destroys the window. Synchronization: Calls to `create_window()` and `destroy_window()` must be externally synchronized. #### `set_rect()` ~~~c void (*set_rect)(tm_window_o *window, tm_rect_t rect); ~~~ Sets the position and size of the window client area. #### `rect()` ~~~c tm_rect_t (*rect)(const tm_window_o *window); ~~~ Returns the position and size of the window client area. #### `dpi_scale_factor()` ~~~c float (*dpi_scale_factor)(const tm_window_o *window); ~~~ Returns the current dpi scale factor for the window. Unless `TM_OS_WINDOW_STYLE_DPI_SCALING_AWARE` is set when creating the window this function will always return 1.f. #### `adjust_rect()` ~~~c tm_rect_t (*adjust_rect)(tm_rect_t rect, float dpi_scale_factor, enum tm_os_window_adjust_rect); ~~~ Helper function to transform window rectangle between virtual coordinates and pixel coordinates based on a dpi scale factor #### `set_size()` ~~~c void (*set_size)(tm_window_o *window, float width, float height); ~~~ Sets the size of the window. #### `has_user_requested_close()` ~~~c bool (*has_user_requested_close)(tm_window_o *window, bool reset); ~~~ Returns `true` if the window has requested to be closed by the user. If `reset` is true, the internal flag will be set to false before returning. #### `set_cursor_mode()` ~~~c void (*set_cursor_mode)(tm_window_o *window, enum tm_os_window_cursor_mode cursor_mode); ~~~ Sets the cursor behavior when the specified window is in front. If the user activates another window, the cursor behavior of that window will be used. If the user Alt-Tabs out of the application, standard system cursor behavior will be used. When this window is reactivated, its cursor behavior will be reactivated too. #### `cursor_mode()` ~~~c enum tm_os_window_cursor_mode (*cursor_mode)(tm_window_o *window); ~~~ #### `set_cursor()` ~~~c void (*set_cursor)(tm_window_o *window, enum tm_os_window_cursor cursor_mode); ~~~ Sets the cursor to display when the specified window is in front. If the user activates another window, the cursor of that window will be used. #### `cursor()` ~~~c enum tm_os_window_cursor (*cursor)(tm_window_o *window); ~~~ #### `dropped_files()` ~~~c const tm_os_dropped_file_t *(*dropped_files)(tm_window_o *window); ~~~ Retrieves a carray of all files dropped during this frame. The returned array is allocated using the frame allocator, do not cache it between frames. #### `status()` ~~~c tm_window_status_t (*status)(tm_window_o *window); ~~~ Returns the current status of the window. #### `set_border_metrics()` ~~~c void (*set_border_metrics)(tm_window_o *window, tm_os_window_border_metrics_t metrics); ~~~ Set the border metrics for the specified custom-border window. This won't have any effect if the Window has not been created with the `TM_OS_WINDOW_STYLE_CUSTOM_BORDER` flag. #### `platform_data()` ~~~c tm_window_platform_data_o (*platform_data)(const tm_window_o *window); ~~~ Returns win32 window data #### `window_from_point()` ~~~c tm_window_o *(*window_from_point)(tm_vec2_t pos); ~~~ Returns the window under the mouse coordinates (pos.x, pos.y). If there is no window under the mouse, or if the window under the mouse does not belong to this window system, NULL is returned. #### `set_focus()` ~~~c void (*set_focus)(tm_window_o *window); ~~~ Makes the specified window the focused one. #### `set_window_state()` ~~~c void (*set_window_state)(tm_window_o *window, enum tm_os_window_state state); ~~~ Changes state of window. #### `set_title()` ~~~c void (*set_title)(tm_window_o *window, const char *title); ~~~ Updates the title of the window.
### `struct tm_os_clipboard_item_t`
Data for a clipboard item. ~~~c typedef struct tm_os_clipboard_item_t { // Format of the clipboard data as a MIME type (e.g. "text/plain"). const char *format; // Data to put on the clipboard. Note that for text data, the data should be NULL-terminated, // but the size should not include the NULL character. const char *data; // Size of the data to put on the clipboard. uint32_t size; TM_PAD(4); } tm_os_clipboard_item_t; ~~~
### `TM_OS_CLIPBOARD_API_NAME`
~~~c #define TM_OS_CLIPBOARD_API_NAME "tm_os_clipboard_api" ~~~
### `struct tm_os_clipboard_api`
#### `get()` ~~~c tm_os_clipboard_item_t (*get)(const char *format, struct tm_temp_allocator_i *ta); ~~~ Gets the clipboard data for the specified MIME format (e.g. "text/plain"). If there is an error or no clipboard data is found for the format a zeroed out structure is returned. The returned data is allocated with the specified temp allocator. #### `set()` ~~~c void (*set)(tm_os_clipboard_item_t *items, uint32_t n); ~~~ Sets the data in the clipboard. You can supply multiple items to set clipboard data in various formats.