From e8b53f2378a38a990b9e620b22810be83edc4bc2 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 01:10:27 +0100 Subject: [PATCH 01/14] Begin library documentation This is an initial commit with documentation for wlc_init, wlc_run and wlc_terminate in the groff markup. --- man/man3/wlc_init.3 | 129 +++++++++++++++++++++++++++++++++++++++ man/man3/wlc_run.3 | 34 +++++++++++ man/man3/wlc_terminate.3 | 33 ++++++++++ 3 files changed, 196 insertions(+) create mode 100644 man/man3/wlc_init.3 create mode 100644 man/man3/wlc_run.3 create mode 100644 man/man3/wlc_terminate.3 diff --git a/man/man3/wlc_init.3 b/man/man3/wlc_init.3 new file mode 100644 index 00000000..2e227bdb --- /dev/null +++ b/man/man3/wlc_init.3 @@ -0,0 +1,129 @@ +.TH WLC_INIT 3 2016-04-21 WLC "WLC Core API Functions" + +.SH NAME +wlc_init \- initialize the wlc library + +.SH SYNOPSIS +.B #include + +.B bool wlc_init(void); + +.SH DESCRIPTION +.BR wlc_init () +is used to initialize the wlc library after any necessary callbacks are +configured and drop permissions when running in a priviledged mode via suid. + +.SH RETURN VALUE +Upon successful initialization +.BR wlc_init () +will return +.IR true . + +.SH ERRORS +None. + +.SH NOTES +.BR wlc_init () +may be called only once during the program's lifetime. + +.BR wlc_init () +can abort on several exceptional situations. These include: +.IP * +Not running from an X11 server with logind support and without access to +.IR /dev/input/event0 . +.IP * +Failures from +.BR wl_display_create (3). +.IP * +Failure to initialize logind. +.IP * +Failure to allocate necessary memory. +.IP * +Failures from +.BR wl_display_init_shm (3). +.IP * +Failure to initialize udev. +.IP * +Failure to initialize libinput. +.IP * +Failure to start the compositor itself. + +.SH EXAMPLE +This simple example demonstrates focusing and bringing any client as they +start to the foreground. A more detailed example is provided with the source +code in +.IR example/example.c . + +.SS Program source +.nf +#include +#include + +static bool +view_created(wlc_handle view) +{ + wlc_handle output = wlc_view_get_output(view); + wlc_view_set_mask(view, wlc_output_get_mask(output)); + wlc_view_bring_to_front(view); + wlc_view_focus(view); + + return true; +} + +static void +view_focus(wlc_handle view, bool focus) +{ + wlc_view_set_state(view, WLC_BIT_ACTIVATED, focus); +} + +int +main(int argc, char *argv[]) +{ + wlc_set_view_created_cb(view_created); + wlc_set_view_focus_cb(view_focus); + + if (!wlc_init()) + exit(EXIT_FAILURE); + + wlc_run(); + exit(EXIT_SUCCESS); +} +.fi + +.SH SEE ALSO +.BR wlc_run (3) + +.SS Output Callbacks +.BR wlc_set_output_created_cb (3), +.BR wlc_set_output_destroyed_cb (3), +.BR wlc_set_output_focus_cb (3), +.BR wlc_set_output_resolution_cb (3), +.BR wlc_set_output_render_pre_cb (3), +.BR wlc_set_output_render_post_cb (3), +.BR wlc_set_output_context_created_cb (3), +.BR wlc_set_output_context_destroyed_cb (3) + +.SS View Callbacks +.BR wlc_set_view_created_cb (3), +.BR wlc_set_view_destroyed_cb (3), +.BR wlc_set_view_focus_cb (3), +.BR wlc_set_view_move_to_output_cb (3), +.BR wlc_set_view_request_geometry_cb (3), +.BR wlc_set_view_request_state_cb (3), +.BR wlc_set_view_request_move_cb (3), +.BR wlc_set_view_request_resize_cb (3), +.BR wlc_set_view_render_pre_cb (3), +.BR wlc_set_view_render_post_cb (3) + +.SS Input Callbacks +.BR wlc_set_input_created_cb (3), +.BR wlc_set_input_destroyed_cb (3) +.BR wlc_set_pointer_button_cb (3), +.BR wlc_set_pointer_scroll_cb (3), +.BR wlc_set_pointer_motion_cb (3), +.BR wlc_set_keyboard_key_cb (3), +.BR wlc_set_touch_cb (3) + +.SS State Callbacks +.BR wlc_set_compositor_ready_cb (3), +.BR wlc_set_compositor_terminate_cb (3) diff --git a/man/man3/wlc_run.3 b/man/man3/wlc_run.3 new file mode 100644 index 00000000..a01a71bd --- /dev/null +++ b/man/man3/wlc_run.3 @@ -0,0 +1,34 @@ +.TH WLC_RUN 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_run \- run the main event loop + +.SH SYNOPSIS +.B #include + +.B void wlc_run(void); + +.SH DESCRIPTION +.BR wlc_run () +starts the main event loop created by +.BR wlc_init (3). +The event loop is terminated with +.BR wlc_terminate (3). + +.SH RETURN VALUE +None. + +.SH NOTES +If +.BR wlc_run () +is called before +.BR wlc_init (3) +then nothing shall happen. + +If +.BR wlc_run () +is called inside the event loop the behaviour is undefined. + +.SH ALSO SEE +.BR wlc_init (3), +.BR wlc_terminate(3) diff --git a/man/man3/wlc_terminate.3 b/man/man3/wlc_terminate.3 new file mode 100644 index 00000000..b3ad9da9 --- /dev/null +++ b/man/man3/wlc_terminate.3 @@ -0,0 +1,33 @@ +.TH WLC_TERMINATE 3 2016-04-21 WLC "WLC Core API Functions" + +.SH NAME +wlc_terminate \- terminate the compositor + +.SH SYNOPSIS +.B #include + +.B void wlc_terminate(void); + +.SH DESCRIPTION +.BR wlc_terminate () +ends any running event loop created with +.BR wlc_run (3) +and terminates the wlc library. + +.SH RETURN VALUE +None. + +.SH NOTES +After the first call to +.BR wlc_terminate () +any subsequent calls will have no effect. + +Calling +.BR wlc_terminate () +before +.BR wlc_init (3) +will have no effect. + +.SH ALSO SEE +.BR wlc_init (3), +.BR wlc_run (3) From bab16ceaf96f82d0148a6e2236a1a262562785b0 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 01:11:56 +0100 Subject: [PATCH 02/14] Document contribution Since groff might be a little alien to people I've added a brief guide with further links to more complete resources. Since I'm following man-pages(7) pretty closely a lot of this effort is already documented. --- man/CONTRIBUTING.rst | 63 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 man/CONTRIBUTING.rst diff --git a/man/CONTRIBUTING.rst b/man/CONTRIBUTING.rst new file mode 100644 index 00000000..3bd72703 --- /dev/null +++ b/man/CONTRIBUTING.rst @@ -0,0 +1,63 @@ +CONTRIBUTING DOCUMENTATION +========================== +These manuals use the groff markup using the man macros, see `groff(7) +`_, `groff_man(7) +`_ and `man(7) +`_ for detailed information. + +This project closely follows the guidelines specified in +`man-pages(7) `_ so +please try to read through them. + +Avoid in-line escapes +--------------------- +Instead of using ``\fB`` to start boldface and ``\fR`` to switch back to roman +such as: + +.. code:: groff + + foo \fBbar\fR baz + +prefer + +.. code:: groff + + foo + .B bar + baz + +Section headers +--------------- +Section content should come directly after the ``.SH`` section header +definition: + +.. code:: groff + + .SH NAME + foo \- bar baz + +Leave a linebreak between section headers. + +.. code:: groff + + foo + + .SH EXAMPLE + bar baz + +Useful macros +------------- +Use the alternating form macros where it makes sense, such as ``.BR`` for +alternating between bold and roman or ``.IR`` for alternative between italics +and roman. Note that one can use empty spaces ``" "`` to consume an +alternation. + +.. code:: groff + + .SH DESCRIPTION + .BR foo () + is a function which takes arguments + .IR a , + .IR b , + and + .IR c . From fba5777a937af24111185c5454673f9a859b250a Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 01:13:05 +0100 Subject: [PATCH 03/14] Add WIP section 7 manual for wlc A section 7 manual is a wonderful resource for introducing library concepts and showing rational or acting as a directed index for the other manuals in the system. Since this is a fairly high level manual most of it is unfinished which hopefully overtime it gets fleshed out based on how the library is used and the design settles. --- man/man7/wlc.7 | 206 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 man/man7/wlc.7 diff --git a/man/man7/wlc.7 b/man/man7/wlc.7 new file mode 100644 index 00000000..aacd992a --- /dev/null +++ b/man/man7/wlc.7 @@ -0,0 +1,206 @@ +.TH WLC 7 2016-04-20 WLC "Wayland Library Compositor" + +.SH NAME +wlc \- the wayland library compositor + +.SH DESCRIPTION +.B wlc +is a library created to make writing wayland compositors easier by providing +most of the necessary interface to the wayland protocol. + +.SS General concepts + +.B Views +.RS +Surfaces with interactive roles which handling is left to user of wlc library +(usually windows, handled by window manager). +.RE + +.B Surfaces +.RS +Rectangular area that is displayed on the screen. It has a location, size and +pixel contents. wlc's views are surfaces that have interactive role assigned. + +.UR http://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_surface +.UE +.RE + +.B Outputs +.RS +Target which containing surfaces are composed to. Output may be physical +monitor, remote desktop, render node, etc. +.RE + +.SS Protocol extensions + +.B xdg-surface +.RS +Provides surface role for traditional desktop like behaviour. The extension is +still in development, but preferred and is the one that will be used by major +DEs (GNOME, KDE, E*). +.RE + +.B shell-surface +.RS +Deprecated surface role built into libwayland. It's not suitable for desktops +and is currently only used by legacy programs and by Qt. + +.UR http://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_shell_surface +.UE + +.SH ENVIRONMENT + +.B WLC_SHM +.RS +Takes a boolean +.I 0 +or +.IR 1 , +true forces EGL clients to fallback on shm. (Default: +.IR 0 ) +.RE + +.B WLC_DEBUG +.RS +Takes a comma-separated list of values which enable corresponding debug section +in wlc. These include: + +.B handle +.RS +Stub. +.RE + +.B render +.RS +Stub. +.RE + +.B render-loop +.RS +Stub. +.RE + +.B focus +.RS +Stub. +.RE + +.B xwm +.RS +Stub. +.RE + +.B keyboard +.RS +Stub. +.RE + +.B commit +.RS +Stub. +.RE + +.B request +.RS +Stub. +.RE +.RE + +.B WLC_DRM_DEVICE +.RS +The DRM device used when running under the DRM backend. (Default: +.IR card0 ) +.RE + +.B WLC_XWAYLAND +.RS +Takes a boolean +.I 0 +or +.I 1 +which disables or enables the use of xwayland respectively. (Default: +.IR 1 ) +.RE + +.B WLC_DRAW_OPAQUE +.RS +Stub. +.RE + +.B WLC_OUTPUTS +.RS +Stub. +.RE + +.B WLC_LIBINPUT +.RS +Stub. +.RE + +.B WLC_REPEAT_DELAY +.RS +The time in milliseconds before keyboard repeat initiates. +.RE + +.B WLC_REPEAT_RATE +.RS +The speed in milliseconds at which the keyboard repeats depressed keys. +.RE + +.B WAYLAND_DEBUG +.RS +Enables message tracing in libwayland. Possible values are +.IR 1 , " client" +and +.IR server . +.RE + +.B WAYLAND_DISPLAY +.RS +Stubby McStub. +.RE + +.B XDG_SEAT +.RS +Stubby. +When using logind this environment is honored during compositor initialization. +.RE + +.B XKB_DEFAULT_LAYOUT +.RS +This corresponds to the layout you might use in X11 such as +.BR gb . +Use this if you want to select a non-us keyboard layout. +.RE + +.B XKB_DEFAULT_OPTIONS +.RS +Sets the keyboard options. The syntax is the same (comma-separated values) as +within an +.I xorg.conf +or when used via +.IR setxkbmap " " -option . +For example +.I compose:ralt,ctrl:nocaps +would set +.I ralt +to the compose key and cause the +.I Caps Lock +key to mimic +.IR ctrl . +.RE + +.B XKB_DEFAULT_VARIANT +.RS +Stub. +.RE + +.B XKB_DEFAULT_RULES +.RS +Stub. +.RE + +.B XKB_DEFAULT_MODEL +.RS +Stub. +.RE From 959cc69259ecf07df5c7080fe171995742d2d2e1 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 12:47:18 +0100 Subject: [PATCH 04/14] Use a more descriptive identifier for userdata This replaces the use of args for userdata as it makes the purpose of it much clearer at a glance. --- include/wlc/wlc.h | 4 ++-- src/wlc.c | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/include/wlc/wlc.h b/include/wlc/wlc.h index 2d5d3c27..a6e78515 100644 --- a/include/wlc/wlc.h +++ b/include/wlc/wlc.h @@ -240,10 +240,10 @@ void wlc_handle_set_user_data(wlc_handle handle, const void *userdata); void* wlc_handle_get_user_data(wlc_handle handle); /** Add fd to event loop. Return value of callback is unused, you should return 0. */ -WLC_NONULLV(3) struct wlc_event_source* wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *arg), void *arg); +WLC_NONULLV(3) struct wlc_event_source* wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *userdata), void *userdata); /** Add timer to event loop. Return value of callback is unused, you should return 0. */ -WLC_NONULLV(1) struct wlc_event_source* wlc_event_loop_add_timer(int (*cb)(void *arg), void *arg); +WLC_NONULLV(1) struct wlc_event_source* wlc_event_loop_add_timer(int (*cb)(void *userdata), void *userdata); /** Update timer to trigger after delay. Returns true on success. */ WLC_NONULL bool wlc_event_source_timer_update(struct wlc_event_source *source, int32_t ms_delay); diff --git a/src/wlc.c b/src/wlc.c index 5dc97285..eda00412 100644 --- a/src/wlc.c +++ b/src/wlc.c @@ -179,17 +179,17 @@ wlc_cleanup(void) } WLC_API struct wlc_event_source* -wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *arg), void *arg) +wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *userdata), void *userdata) { assert(wlc_event_loop()); - return (struct wlc_event_source*)wl_event_loop_add_fd(wlc_event_loop(), fd, mask, cb, arg); + return (struct wlc_event_source*)wl_event_loop_add_fd(wlc_event_loop(), fd, mask, cb, userdata); } WLC_API struct wlc_event_source* -wlc_event_loop_add_timer(int (*cb)(void *arg), void *arg) +wlc_event_loop_add_timer(int (*cb)(void *userdata), void *userdata) { assert(wlc_event_loop()); - return (struct wlc_event_source*)wl_event_loop_add_timer(wlc_event_loop(), cb, arg); + return (struct wlc_event_source*)wl_event_loop_add_timer(wlc_event_loop(), cb, userdata); } WLC_API bool From 9d83b813b9fad02f7d545da4a609e1f3a210dc97 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 13:28:01 +0100 Subject: [PATCH 05/14] Add initial pointer callback manuals --- man/man3/wlc_set_pointer_button_cb.3 | 76 ++++++++++++++++++++++++++++ man/man3/wlc_set_pointer_motion_cb.3 | 76 ++++++++++++++++++++++++++++ man/man3/wlc_set_pointer_scroll_cb.3 | 1 + 3 files changed, 153 insertions(+) create mode 100644 man/man3/wlc_set_pointer_button_cb.3 create mode 100644 man/man3/wlc_set_pointer_motion_cb.3 create mode 100644 man/man3/wlc_set_pointer_scroll_cb.3 diff --git a/man/man3/wlc_set_pointer_button_cb.3 b/man/man3/wlc_set_pointer_button_cb.3 new file mode 100644 index 00000000..0f7c69ea --- /dev/null +++ b/man/man3/wlc_set_pointer_button_cb.3 @@ -0,0 +1,76 @@ +.TH WLC_SET_POINTER_BUTTON_CB 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME + +wlc_set_pointer_button_cb, wlc_set_pointer_scroll_cb, wlc_set_pointer_motion_cb +\- mouse pointer events + +.SH SYNOPSIS +.nf +.B #include + +.BI "void wlc_set_pointer_button_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_modifiers*, uint32_t "button , +.B " enum wlc_button_state, const struct wlc_point*));" +.BI "void wlc_set_pointer_scroll_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_modifiers*, uint8_t "axis_bits , +.BI " double "amount[2] "));" +.BI "void wlc_set_pointer_motion_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_point*));" + +.SH DESCRIPTION +The callback defined in +.I cb +when given to +.BR wlc_set_pointer_button_cb () +is called on button events. These events are +.I WLC_BUTTON_STATE_PRESSED +and +.IR WLC_BUTTON_STATE_RELEASED . +The retuned +.I button +is a raw keycode and the representation depends on the operating system or +hardware. + +Additional modifiers are set including led state. + +The +.I axis_bits +provided to the callback +.I cb +in +.BR wlc_set_pointer_scroll_cb () +can be used to determine the velocity of the mouse pointer by applying a +logical AND with the value and +.I WLC_SCROLL_AXIS_VERTICAL +or +.IR WLC_SCROLL_AXIS_HORIZONTAL . + +The amount scrolled is stored in the +.I amount +array. The first element represents the vertical movement and the value stored +is the amount it has moved, negative values represent an upward scroll. For +horizontal scrolling the second element represents a leftward direction for +negative values and rightward for positive. + +The +.I time +represents a timestamp of when the mouse event occured. It is a magical number +and cannot be relied on. + +.SH RETURN VALUE +The return value of all callbacks dictate what is sent to the client. If +the callback returns +.I true +then the client doesn't see the event, if +.I false +the events fall through to the client. + +.SH NOTES +The button codes and behaviour are currently mapped to onto +.I +and +.IR . + +.SH ALSO SEE +.BR wlc_init (3) diff --git a/man/man3/wlc_set_pointer_motion_cb.3 b/man/man3/wlc_set_pointer_motion_cb.3 new file mode 100644 index 00000000..0f7c69ea --- /dev/null +++ b/man/man3/wlc_set_pointer_motion_cb.3 @@ -0,0 +1,76 @@ +.TH WLC_SET_POINTER_BUTTON_CB 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME + +wlc_set_pointer_button_cb, wlc_set_pointer_scroll_cb, wlc_set_pointer_motion_cb +\- mouse pointer events + +.SH SYNOPSIS +.nf +.B #include + +.BI "void wlc_set_pointer_button_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_modifiers*, uint32_t "button , +.B " enum wlc_button_state, const struct wlc_point*));" +.BI "void wlc_set_pointer_scroll_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_modifiers*, uint8_t "axis_bits , +.BI " double "amount[2] "));" +.BI "void wlc_set_pointer_motion_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_point*));" + +.SH DESCRIPTION +The callback defined in +.I cb +when given to +.BR wlc_set_pointer_button_cb () +is called on button events. These events are +.I WLC_BUTTON_STATE_PRESSED +and +.IR WLC_BUTTON_STATE_RELEASED . +The retuned +.I button +is a raw keycode and the representation depends on the operating system or +hardware. + +Additional modifiers are set including led state. + +The +.I axis_bits +provided to the callback +.I cb +in +.BR wlc_set_pointer_scroll_cb () +can be used to determine the velocity of the mouse pointer by applying a +logical AND with the value and +.I WLC_SCROLL_AXIS_VERTICAL +or +.IR WLC_SCROLL_AXIS_HORIZONTAL . + +The amount scrolled is stored in the +.I amount +array. The first element represents the vertical movement and the value stored +is the amount it has moved, negative values represent an upward scroll. For +horizontal scrolling the second element represents a leftward direction for +negative values and rightward for positive. + +The +.I time +represents a timestamp of when the mouse event occured. It is a magical number +and cannot be relied on. + +.SH RETURN VALUE +The return value of all callbacks dictate what is sent to the client. If +the callback returns +.I true +then the client doesn't see the event, if +.I false +the events fall through to the client. + +.SH NOTES +The button codes and behaviour are currently mapped to onto +.I +and +.IR . + +.SH ALSO SEE +.BR wlc_init (3) diff --git a/man/man3/wlc_set_pointer_scroll_cb.3 b/man/man3/wlc_set_pointer_scroll_cb.3 new file mode 100644 index 00000000..1e8b365c --- /dev/null +++ b/man/man3/wlc_set_pointer_scroll_cb.3 @@ -0,0 +1 @@ +.so wlc_set_pointer_button_sb.3 From 2379605dc3446cfdf774302de466cf35adee1473 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 13:29:41 +0100 Subject: [PATCH 06/14] Add initial event loop and source manuals --- man/man3/wlc_event_loop_add_fd.3 | 58 ++++++++++++++++++++++++ man/man3/wlc_event_loop_add_timer.3 | 38 ++++++++++++++++ man/man3/wlc_event_source_remove.3 | 18 ++++++++ man/man3/wlc_event_source_timer_update.3 | 35 ++++++++++++++ 4 files changed, 149 insertions(+) create mode 100644 man/man3/wlc_event_loop_add_fd.3 create mode 100644 man/man3/wlc_event_loop_add_timer.3 create mode 100644 man/man3/wlc_event_source_remove.3 create mode 100644 man/man3/wlc_event_source_timer_update.3 diff --git a/man/man3/wlc_event_loop_add_fd.3 b/man/man3/wlc_event_loop_add_fd.3 new file mode 100644 index 00000000..4d354bd9 --- /dev/null +++ b/man/man3/wlc_event_loop_add_fd.3 @@ -0,0 +1,58 @@ +.TH WLC_EVENT_LOOP_ADD_FD 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_event_loop_add_fd - add file descriptor to event loop + +.SH SYNOPSIS +.B #include + +.nf +.BI "struct wlc_event_source* wlc_event_loop_add_fd(int "fd ", uint32_t "mask , +.BI " int (*"cb ")(int "fd , +.BI " uint32_t "mask ", void *"userdata ), +.BI " void *"userdata ), +.fi + +.SH DESCRIPTION +.BR wlc_event_loop_add_fd () +can be used to add a file descriptor ( +.IR fd ) +to the event loop created by +.BR wlc_init (3). +The callback is triggered whenever the condition defined in the +.I mask +is met. These conditions are of type +.I wlc_event_bit +and have the following values: + +.IP WLC_EVENT_READABLE +When the file descriptor is available for read operations. + +.IP WLC_EVENT_WRITABLE +When the file descriptor is available for write operations. + +.IP WLC_EVENT_HANGUP +When the hang up event occurred on the file descriptor, usually indicating a +peer has closed their end of a connection. + +.IP WLC_EVENT_ERROR +An error occurred on the file descriptor. + +.SH RETURN VALUE +.BR wlc_event_loop_add_fd () +returns a pointer to a wlc_event_source. + +The return value of the callback is ignored. + +.SH NOTES +libwayland's implementation is based on +.BR epoll (7) +and much of its functionality is represented here. For example, a +.I WLC_EVENT_READABLE +bit is equivalent to +.I EPOLLIN +defined in +.BR epoll_ctl(3 ). + +.SH ALSO SEE +.BR wlc_init (3) diff --git a/man/man3/wlc_event_loop_add_timer.3 b/man/man3/wlc_event_loop_add_timer.3 new file mode 100644 index 00000000..6187e4ac --- /dev/null +++ b/man/man3/wlc_event_loop_add_timer.3 @@ -0,0 +1,38 @@ +.TH WLC_EVENT_LOOP_ADD_TIMER 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_event_loop_add_timer \- add a timer to the event loop + +.SH SYNOPSIS +.B #include + +.nf +.BI "struct wlc_event_source* wlc_event_loop_add_timer(int (*"cb ")(void *"userdata ), +.BI " void *"userdata ); +.fi + +.SH DESCRIPTION +.BR wlc_event_loop_add_timer () +is used to add a timer callback +.I cb +to the wlc_event_loop which triggered after a time interval specified by +.BR wlc_event_source_timer_update (3). + +The callback +.I cb +is only triggered once when the time is met. +.BR wlc_event_source_remove (3) +is used to remove the timer callback from the wlc_event_loop. + +.SH RETURN VALUE +On success +.BR wlc_event_loop_add_timer () +returns an opaque wlc_event_source otherwise it shall return +.IR NULL . + +.SH NOTES +The return value of the callback is unused. + +.SH ALSO SEE +.BR wlc_event_source_timer_update (3), +.BR wlc_event_source_remove (3) diff --git a/man/man3/wlc_event_source_remove.3 b/man/man3/wlc_event_source_remove.3 new file mode 100644 index 00000000..6b83456e --- /dev/null +++ b/man/man3/wlc_event_source_remove.3 @@ -0,0 +1,18 @@ +.TH WLC_EVENT_SOURCE_REMOVE 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_event_source_remove \- remove an event from event loop + +.SH SYNOPSIS +.B #include + +.BI "void wlc_event_source_remove(struct wlc_event_source *"source ); + +.SH DESCRIPTION +.BR wlc_event_source_remove () +is used to remove a +.I source +from the event loop. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_event_source_timer_update.3 b/man/man3/wlc_event_source_timer_update.3 new file mode 100644 index 00000000..a08ec0b7 --- /dev/null +++ b/man/man3/wlc_event_source_timer_update.3 @@ -0,0 +1,35 @@ +.TH WLC_EVENT_SOURCE_TIMER_UPDATE 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_event_source_timer_update \- set the delay for timer activation + +.SH SYNOPSIS +.B #include + +.nf +.BI "void wlc_event_source_timer_update(struct wlc_event_source *"source , +.BI " uint32_t "ms_delay ); +.fi + +.SH DESCRIPTION +For a given +.IR source , +.BR wlc_event_source_timer_update () +sets a time in milliseconds according to +.IR ms_delay . +This will prime the timer added with +.BR wlc_event_loop_add_timer (3) +which is triggered once the +.I ms_delay +reaches zero. + +Setting a +.I ms_delay +of zero will disarm the event source. + +.SH RETURN VALUE +None. + +.SH ALSO SEE +.BR wlc_event_loop_add_timer (3), +.BR wlc_event_source_remove (3) From 6561e08d9c2f7afb4a2ab065606925fdc9c2244f Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 13:30:33 +0100 Subject: [PATCH 07/14] Add initial output callback manuals --- man/man3/wlc_set_output_context_created_cb.3 | 1 + .../wlc_set_output_context_destroyed_cb.3 | 1 + man/man3/wlc_set_output_created_cb.3 | 130 ++++++++++++++++++ man/man3/wlc_set_output_destroyed_cb.3 | 1 + man/man3/wlc_set_output_focus_cb.3 | 1 + man/man3/wlc_set_output_render_post_cb.3 | 1 + man/man3/wlc_set_output_render_pre_cb.3 | 1 + man/man3/wlc_set_output_resolution_cb.3 | 1 + 8 files changed, 137 insertions(+) create mode 100644 man/man3/wlc_set_output_context_created_cb.3 create mode 100644 man/man3/wlc_set_output_context_destroyed_cb.3 create mode 100644 man/man3/wlc_set_output_created_cb.3 create mode 100644 man/man3/wlc_set_output_destroyed_cb.3 create mode 100644 man/man3/wlc_set_output_focus_cb.3 create mode 100644 man/man3/wlc_set_output_render_post_cb.3 create mode 100644 man/man3/wlc_set_output_render_pre_cb.3 create mode 100644 man/man3/wlc_set_output_resolution_cb.3 diff --git a/man/man3/wlc_set_output_context_created_cb.3 b/man/man3/wlc_set_output_context_created_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_context_created_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_context_destroyed_cb.3 b/man/man3/wlc_set_output_context_destroyed_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_context_destroyed_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_created_cb.3 b/man/man3/wlc_set_output_created_cb.3 new file mode 100644 index 00000000..ec010f57 --- /dev/null +++ b/man/man3/wlc_set_output_created_cb.3 @@ -0,0 +1,130 @@ +.TH WLC_SET_OUTPUT_CREATED_CB 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +.nh +wlc_set_output_created_cb, wlc_set_output_destroyed_cb, +wlc_set_output_focus_cb, wlc_set_output_resolution_cb, +wlc_set_output_render_pre_cb, wlc_set_output_render_post_cb, +wlc_set_output_context_created_cb, wlc_set_output_context_destroyed_cb +\- output creation, management and deletion +.hy + +.SH SYNOPSIS +.B #include + +.nf +.BI "void wlc_set_output_created_cb(bool (*"cb ")(wlc_handle "output "));" +.br +.BI "void wlc_set_output_destroyed_cb(void (*"cb ")(wlc_handle "output "));" +.br +.BI "void wlc_set_output_focus_cb(void (*"cb ")(wlc_handle "output ", bool "focus "));" +.br +.BI "void wlc_set_output_resolution_cb(void (*"cb ")(wlc_handle "output , +.BI " const struct wlc_size *"from , +.BI " const struct wlc_size *"to "));" +.br +.BI "void wlc_set_output_render_pre_cb(void (*cb)(wlc_handle output)); +.br +.BI "void wlc_set_output_render_post_cb(void (*cb)(wlc_handle output)); +.br +.BI "void wlc_set_output_context_created_cb(void (*cb)(wlc_handle output)); +.br +.BI "void wlc_set_output_context_destroyed_cb(void (*cb)(wlc_handle output)); +.fi + +.SH DESCRIPTION +The output functions all take a callback +.I cb +which define the creation, management and destruction of the +.I output +where an output is typically attached to a physical monitor but can also be a +virtual display or a render node. + +.BR wlc_set_output_created_cb () +creates an output on a given wlc_handle. +The +.I output +will be destroyed if the callback returns +.IR false . + +.BR wlc_set_output_destroyed_cb () +allows for to monitoring events such as output disconnection. This is called +whenever an output is being destroyed. The +.BR wlc_handle (3) +is invalid once it completes. + +.BR wlc_set_output_focus_cb () +is triggered on gaining or losing focus of an output. + +.BR wlc_set_output_resolution_cb () +is called on resolution changes. The new resolution is updated inside the +.I to +structure and the old resolution inside the +.I from +structure. + +The +.BR wlc_set_output_context_created_cb () +events are triggered when the wlc library creates a graphical context such as +EGL or GL. This is specifically useful when using +.BR wlc_set_output_render_pre_cb () +and +.BR wlc_set_output_render_post_cb (3) +to indicate that any EGL or GL resources need to be recreated. + +Likewise, +.BR wlc_set_output_context_destroyed_cb (3) +triggers on wlc's graphical context destruction indicating one needs to release +their resources. + +.SH EXAMPLE +These examples are demonstrative and not functional. + +.nf +#include + +static bool +handle_output_creation(wlc_handle output) +{ + if (!output) + return false; + + register_new_output(output); +} + +static void +handle_output_destruction(wlc_handle output) +{ + move_all_windows_to_next_available_output(); +} + +static void +handle_output_focus(wlc_handle output, bool focus) +{ + if (focus) + set_focus(output); +} + +static void +handle_resolution_change(wlc_handle output, + const struct wlc_size *from, + const struct wlc_size *to) +{ + int area_from = from->w * from->h; + int area_to = to->w * to->h; + + if (area_from > area_to) + fit_views(output, to); +} + +wlc_set_output_created_cb(handle_output_creation); +wlc_set_output_focus_cb(handle_output_focus); +wlc_set_output_destroyed_cb(handle_output_destruction); +wlc_set_output_resolution_cb(handle_resolution_change); + +wlc_init(); +.fi + +.SH ALSO SEE +.BR wlc_set_view_created_cb (3), +.BR wlc_init (3) diff --git a/man/man3/wlc_set_output_destroyed_cb.3 b/man/man3/wlc_set_output_destroyed_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_destroyed_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_focus_cb.3 b/man/man3/wlc_set_output_focus_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_focus_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_render_post_cb.3 b/man/man3/wlc_set_output_render_post_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_render_post_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_render_pre_cb.3 b/man/man3/wlc_set_output_render_pre_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_render_pre_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 diff --git a/man/man3/wlc_set_output_resolution_cb.3 b/man/man3/wlc_set_output_resolution_cb.3 new file mode 100644 index 00000000..08431922 --- /dev/null +++ b/man/man3/wlc_set_output_resolution_cb.3 @@ -0,0 +1 @@ +.so wlc_set_output_created_cb.3 From c63e26e2fe7bf4f30ecd324499885cafc809466d Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 13:31:39 +0100 Subject: [PATCH 08/14] Add wlc_exec manual --- man/man3/wlc_exec.3 | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 man/man3/wlc_exec.3 diff --git a/man/man3/wlc_exec.3 b/man/man3/wlc_exec.3 new file mode 100644 index 00000000..f35425af --- /dev/null +++ b/man/man3/wlc_exec.3 @@ -0,0 +1,42 @@ +.TH WLC_EXEC 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_exec \- exec programs + +.SH SYNOPSIS +.B #include + +.BI "void wlc_exec(const char *" bin ", char *const " args[] ");" + +.SH DESCRIPTION +.BR wlc_exec () +will fork and exec a new process defined by +.I bin +with the arguments +.IR args . +The bin argument cannot be +.IR NULL . + +.SH RETURN VALUE +None. + +.SH NOTES +.BR wlc_exec () +will send +.I stdout +and +.I stderr +to +.I /dev/null +and calls +.BR setsid (3) +if necessary. The new process will inherit the environment from the compositor. + +.SH EXAMPLE +.nf +#include +#include + +char *terminal = getenv("TERMINAL"); +wlc_exec(terminal, (char* const*)0); +.fi From 74c0ff68f25c80dd108566dfc8b3e8d7dcc25215 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 14:03:44 +0100 Subject: [PATCH 09/14] Document a few miscellaneous things https://github.com/Cloudef/wlc/issues/156 * wlc_get_backend_type.3 * wlc_handle_get_user_data.3 * wlc_handle_set_user_data.3 * wlc_log_set_handler.3 * wlc_output_get_mask.3 * wlc_pointer_get_position.3 * wlc_pointer_set_position.3 * wlc_view_get_app_id.3 --- man/man3/wlc_get_backend_type.3 | 49 +++++++++++++++++++++++++++ man/man3/wlc_handle_get_user_data.3 | 27 +++++++++++++++ man/man3/wlc_handle_set_user_data.3 | 28 ++++++++++++++++ man/man3/wlc_log_set_handler.3 | 51 +++++++++++++++++++++++++++++ man/man3/wlc_output_get_mask.3 | 30 +++++++++++++++++ man/man3/wlc_pointer_get_position.3 | 17 ++++++++++ man/man3/wlc_pointer_set_position.3 | 22 +++++++++++++ man/man3/wlc_view_get_app_id.3 | 43 ++++++++++++++++++++++++ 8 files changed, 267 insertions(+) create mode 100644 man/man3/wlc_get_backend_type.3 create mode 100644 man/man3/wlc_handle_get_user_data.3 create mode 100644 man/man3/wlc_handle_set_user_data.3 create mode 100644 man/man3/wlc_log_set_handler.3 create mode 100644 man/man3/wlc_output_get_mask.3 create mode 100644 man/man3/wlc_pointer_get_position.3 create mode 100644 man/man3/wlc_pointer_set_position.3 create mode 100644 man/man3/wlc_view_get_app_id.3 diff --git a/man/man3/wlc_get_backend_type.3 b/man/man3/wlc_get_backend_type.3 new file mode 100644 index 00000000..5237f261 --- /dev/null +++ b/man/man3/wlc_get_backend_type.3 @@ -0,0 +1,49 @@ +.TH WLC_GET_BACKEND_TYPE 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_get_backend_type \- query which backend wlc is using + +.SH SYNOPSIS +.B #include + +.B enum wlc_backend_type wlc_get_backend_type(void); + +.SH DESCRIPTION +.BR wlc_get_backend_type () +can be used to determine which backend the compositor is currently running on. +This is useful if the compositor needs to know whether it is running nested +inside an X11 (Xorg) server or directly on DRM. + +.SH RETURN VALUE +.BR wlc_get_backend_type () +returns a +.I wlc_backend_type +which can be one of +.IR WLC_BACKEND_X11 , +.I WLC_BACKEND_DRM +or +.IR WLC_BACKEND_NONE . + +.SH NOTES +.I WLC_BACKEND_NONE +shall be returned if +.BR wlc_init (3) +failed or when +.BR wlc_get_backend_type () +is called before +.BR wlc_init (3). + +.SH EXAMPLE +.nf +#include + +const enum wlc_backend_type backend = wlc_get_backend_type(); + +switch (backend) { + WLC_BACKEND_X11: + set_default_prefix(WLC_BIT_MOD_ALT); + break; + default: + set_default_prefix(WLC_BIT_MOD_LOGO); +} +.fi diff --git a/man/man3/wlc_handle_get_user_data.3 b/man/man3/wlc_handle_get_user_data.3 new file mode 100644 index 00000000..ea9d5542 --- /dev/null +++ b/man/man3/wlc_handle_get_user_data.3 @@ -0,0 +1,27 @@ +.TH WLC_HANDLE_GET_USER_DATA 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_handle_get_user_data \- get user data associated with the handle + +.SH SYNOPSIS +.B #include + +.BI "void* wlc_handle_get_user_data(wlc_handle "handle ");" + +.SH DESCRIPTION +.BR wlc_handle_get_user_data () +provides a mechanism to aquire the user data provided via +.BR wlc_handle_set_user_data (3) +allowing for direct access to its contents. + +.SH RETURN VALUE +.BR wlc_handle_get_user_data () +returns a pointer to the address of the user data. + +If no user data has been set then +.BR wlc_handle_get_user_data () +will return +.IR NULL . + +.SH ALSO SEE +.BR wlc_handle_set_user_data (3) diff --git a/man/man3/wlc_handle_set_user_data.3 b/man/man3/wlc_handle_set_user_data.3 new file mode 100644 index 00000000..33dc9b42 --- /dev/null +++ b/man/man3/wlc_handle_set_user_data.3 @@ -0,0 +1,28 @@ +.TH WLC_HANDLE_SET_USER_DATA 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_handle_set_user_data \- add user data to the handle + +.SH SYNOPSIS +.B #include + +.BI "void wlc_handle_set_user_data(wlc_handle "handle ", const void *" userdata ");" + +.SH DESCRIPTION +.BR wlc_handle_set_user_data () +lets the programmer add arbitrary user data to the handle for later use or +inspection. + +.SH RETURN VALUE +None. + +.SH NOTES +If the handle is invalid then +.BR wlc_handle_set_user_data () +will do nothing. + +In order to validate that the user data was set one should use +.BR wlc_handle_get_user_data (3). + +.SH ALSO SEE +.BR wlc_handle_get_user_data (3) diff --git a/man/man3/wlc_log_set_handler.3 b/man/man3/wlc_log_set_handler.3 new file mode 100644 index 00000000..a1b3fede --- /dev/null +++ b/man/man3/wlc_log_set_handler.3 @@ -0,0 +1,51 @@ +.TH WLC_LOG_SET_HANDLER 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_log_set_handler \- provides for a callback to a custom log handler + +.SH SYNOPSIS +.B #include + +.BI "void wlc_log_set_handler(void (*"cb ")(enum wlc_log_type "type ", const char *" str "));" + +.SH DESCRIPTION +.BR wlc_log_set_handler () +allows for the use of a custom log handler if the +project requires it. Without a handler configured wlc will not produce any +output. The argument of +.I wlc_log_type +can be one of +.IR WLC_LOG_INFO , +.IR WLC_LOG_WARN , +.I WLC_LOG_ERROR +or +.IR WLC_LOG_WAYLAND . + +.SH NOTES +This callback can be configured before or after +.BR wlc_init (3) +is initialized. + +.SH EXAMPLE +.nf +#include + +void logger(const char *fmt, ...); + +static void +log_handler(enum wlc_log_type type, const char *str) +{ + switch (type) { + case WLC_LOG_INFO: + case WLC_LOG_WARN: + case WLC_LOG_ERROR: + case WLC_LOG_WAYLAND: + logger("%s", str); + } +} + +wlc_log_set_handler(log_handler); +.fi + +.SH ALSO SEE +.BR wlc_init (3) diff --git a/man/man3/wlc_output_get_mask.3 b/man/man3/wlc_output_get_mask.3 new file mode 100644 index 00000000..e82a56a5 --- /dev/null +++ b/man/man3/wlc_output_get_mask.3 @@ -0,0 +1,30 @@ +.TH WLC_OUTPUT_GET_MASK 3 2016-04-22 WLC "WLC API Funcitons" + +.SH NAME +wlc_output_get_mask \- get bitmask of visible surfaces for an output + +.SH SYNOPSIS +.B #include + +.BI "uint32_t wlc_output_get_mask(wlc_handle "output ");" + +.SH DESCRIPTION +.BR wlc_output_get_mask () +is a utility function which can be used with visibility masks to provide a +convenient way of implementing workspaces, tagging, or simply provide view +hiding. + +Conceptually this allows one to group a collection of views into a specific +bit position and then use this to display or hide these collections based +on which bit, or bits, are active. + +.SH RETURN VALUE +.BR wlc_output_get_mask () +returns a visibility mask for the given +.IR output . + +.SH NOTES +Currently the mask is limited to 32-bits. + +.SH ALSO SEE +.BR wlc_output_set_mask (3) diff --git a/man/man3/wlc_pointer_get_position.3 b/man/man3/wlc_pointer_get_position.3 new file mode 100644 index 00000000..b3dcd2b8 --- /dev/null +++ b/man/man3/wlc_pointer_get_position.3 @@ -0,0 +1,17 @@ +.TH WLC_POINTER_GET_POSITION 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME + +wlc_pointer_get_position \- gets the mouse pointer position + +.SH SYNOPSIS +.B #include + +.BI "void wlc_pointer_get_position(const struct wlc_point *"out_position ");" + +.SH DESCRIPTION +.BR wlc_pointer_get_position () +is used to get the mouse pointer position on the currently focused output. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_pointer_set_position.3 b/man/man3/wlc_pointer_set_position.3 new file mode 100644 index 00000000..1c77bdab --- /dev/null +++ b/man/man3/wlc_pointer_set_position.3 @@ -0,0 +1,22 @@ +.TH WLC_POINTER_SET_POSITION 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_pointer_set_position \- sets the mouse pointer position + +.SH SYNOPSIS +.B #include + +.BI "void wlc_pointer_set_position(const struct wlc_point *"position ");" + +.SH DESCRIPTION +.BR wlc_pointer_set_position () +is used to set the mouse pointer to a new +.I position +relative to the top left corner of the currently focused output. + +.SH RETURN VALUE +None. + +.SH NOTES +The mouse pointer position will be clamped to the focused output if the +requested position is out of bounds. diff --git a/man/man3/wlc_view_get_app_id.3 b/man/man3/wlc_view_get_app_id.3 new file mode 100644 index 00000000..06f45d10 --- /dev/null +++ b/man/man3/wlc_view_get_app_id.3 @@ -0,0 +1,43 @@ +.TH WLC_VIEW_GET_APP_ID 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_view_get_app_id - get the application identifier for a given view + +.SH SYNOPSIS +.B #include + +.BI "const char* wlc_view_get_app_id(wlc_handle "view ");" + +.SS Wayland protocol requirements: +.RS +.BR wlc_view_get_app_id (): +xdg_shell +.RE + +.SH DESCRIPTION +.BR wlc_view_get_app_id () +can be used to acquire an application identifier which +identifies the general class of applications to which the +.I view +belongs. +The compositor can use this to group multiple views together, or to +determine how to launch a new application. + +For applications supporting D-Bus activation the application identifier is +used as the D-Bus service name. + +.SH RETURN VALUE +.BR wlc_view_get_app_id () +returns the application identifier for +.I view +if the assigned role for view is xdg-surface. + +If the role is not xdg-surface then +.BR wlc_view_get_app_id () +will return +.IR NULL . + +.SH ALSO SEE +The XDG Shell protocol extension +.UR http://cgit.freedesktop.org/wayland/weston/tree/protocol/xdg-shell.xml +.UE From 24d6c15070fa449de04e4e40bef9ff8e86f1e2e5 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 14:59:57 +0100 Subject: [PATCH 10/14] Document more of the wlc.h API https://github.com/Cloudef/wlc/issues/156 * wlc_get_outputs.3 * wlc_keyboard_get_current_keys.3 * wlc_keyboard_get_utf32_for_key.3 * wlc_output_focus.3 * wlc_set_keyboard_key_cb.3 --- man/man3/wlc_get_outputs.3 | 35 ++++++++ man/man3/wlc_keyboard_get_current_keys.3 | 20 +++++ man/man3/wlc_keyboard_get_utf32_for_key.3 | 42 ++++++++++ man/man3/wlc_output_focus.3 | 16 ++++ man/man3/wlc_set_keyboard_key_cb.3 | 97 +++++++++++++++++++++++ 5 files changed, 210 insertions(+) create mode 100644 man/man3/wlc_get_outputs.3 create mode 100644 man/man3/wlc_keyboard_get_current_keys.3 create mode 100644 man/man3/wlc_keyboard_get_utf32_for_key.3 create mode 100644 man/man3/wlc_output_focus.3 create mode 100644 man/man3/wlc_set_keyboard_key_cb.3 diff --git a/man/man3/wlc_get_outputs.3 b/man/man3/wlc_get_outputs.3 new file mode 100644 index 00000000..78ba2553 --- /dev/null +++ b/man/man3/wlc_get_outputs.3 @@ -0,0 +1,35 @@ +.TH WLC_GET_OUTPUTS 3 2016-04-22 WLC "WLC Output API Functions" + +.SH NAME +wlc_get_outputs \- get list of outputs + +.SH SYNOPSIS +.B #include + +.BI "const wlc_handle* wlc_get_outputs(size_t *"out_count ); + +.SH DESCRIPTION +.BR wlc_get_outputs () +is used to return an array of wlc_handles while setting the +.I out_count +parameter to the number of outputs available. + +.SH RETURN VALUE +.BR wlc_get_outputs () +returns an array of wlc_handles. + +.SH NOTES +The returned array is a direct reference so care is needed when moving and +destroying handles. If ownership is required the array should be copied +instead. + +.SH EXAMPLE +.nf +#include + +size_t count; +const wlc_handle *outputs = wlc_get_outputs(&count); + +for (size_t i = 0; i < count; ++i) + wake_up(outputs[i]); +.fi diff --git a/man/man3/wlc_keyboard_get_current_keys.3 b/man/man3/wlc_keyboard_get_current_keys.3 new file mode 100644 index 00000000..8a833516 --- /dev/null +++ b/man/man3/wlc_keyboard_get_current_keys.3 @@ -0,0 +1,20 @@ +.TH WLC_KEYBOARD_GET_CURRENT_KEYS 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_keyboard_get_current_keys \- get list of currently held keys + +.SH SYNOPSIS +.B #include + +.BI "const uint32_t* wlc_keyboard_get_current_keys(size_t *"out_count ); + +.SH DESCRIPTION +.BR wlc_keyboard_get_current_keys () +is used to list all the currently held keys which is primarily used to detect a +correct combinations of keys have been pressed. The +.I out_count +parameter is set to the number of keys pressed. + +.SH RETURN VALUE +.BR wlc_keyboard_get_current_keys () +returns an array of keys pressed. diff --git a/man/man3/wlc_keyboard_get_utf32_for_key.3 b/man/man3/wlc_keyboard_get_utf32_for_key.3 new file mode 100644 index 00000000..27512317 --- /dev/null +++ b/man/man3/wlc_keyboard_get_utf32_for_key.3 @@ -0,0 +1,42 @@ +.TH WLC_KEYBOARD_GET_UTF32_FOR_KEY 3 2016-04-22 WLC "WLC Utility Functions" + +.SH NAME +wlc_keyboard_get_utf32_for_key \- convert keycode to UTF-32 codepoint + +.SH SYNOPSIS +.B # include + +.nf +.BI "uint32_t wlc_keyboard_get_utf32_for_key(uint32_t "key , +.BI " const struct wlc_modifiers *"modifiers ); +.fi + +.SH DESCRIPTION +.BR wlc_keyboard_get_utf32_for_key () +converts raw keycodes to a UTF-32 encoded Unicode codepoint. Additional +modifiers passed in may change the key and the resulting codepoint. + +For example, this allows the programmer to provide a mechanism whereby +users are able to bind keys by glyph directly. + +.SH RETURN VALUE +.BR wlc_keyboard_get_utf32_for_key () +returns a UTF-32 encoded Unicode representation of the raw keycode. + +.SH EXAMPLE +.nf +#include + +const uint32_t sym = wlc_keyboard_get_keysym_for_key(key, 0); +const uint32_t u32 = wlc_keyboard_get_utf32_for_key(key, 0); + +char name[64] = {0}; +const uint8_t mb = chck_utf32_encode(u32, name); + +if (!mb || (mb == 1 && (!isprint(name[0]) || isspace(name[0])))) { + if (xkb_keysym_get_name(sym, name, sizeof(name)) == -1) + return false; +} + +pass_key(view, time, modifiers, name); +.fi diff --git a/man/man3/wlc_output_focus.3 b/man/man3/wlc_output_focus.3 new file mode 100644 index 00000000..9b829b14 --- /dev/null +++ b/man/man3/wlc_output_focus.3 @@ -0,0 +1,16 @@ +.TH WLC_OUTPUT_FOCUS 3 2016-04-22 WLC "WLC Output API Functions" + +.SH NAME +wlc_output_focus \- focus output + +.SH SYNOPSIS +.B #include + +.BI "void wlc_output_focus(wlc_handle "output ); + +.SH DESCRIPTION +.BR wlc_output_focus () +focuses the output defined in the output handle. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_set_keyboard_key_cb.3 b/man/man3/wlc_set_keyboard_key_cb.3 new file mode 100644 index 00000000..f0bf07e9 --- /dev/null +++ b/man/man3/wlc_set_keyboard_key_cb.3 @@ -0,0 +1,97 @@ +.TH WLC_SET_KEYBOARD_KEY_CB 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_set_keyboard_key_cb - keyboard callbacks + +.SH SYNOPSIS +.nf +.B #include + +.BI "void wlc_set_keyboard_key_cb(bool (*"cb ")(wlc_handle "view ", uint32_t "time , +.BI " const struct wlc_modifiers*, uint32_t "key , +.BI " enum wlc_key_state));" +.fi + +.SH DESCRIPTION +.BR wlc_set_keyboard_key_cb () +configures the callback +.I cb +which is triggered on key events for the given view. If the view is not focused +then +.I view +shall be set to +.IR 0 . +This is useful to handle key events in situations where focus is or is not +required. For example global key bindings or view specific keybindings. + +The +.I time +represents a timestamp of when the key event occured. It is a magical number +and cannot be relied on. + +The +.I modifiers +may be one of +.IR WLC_BIT_MOD_CAPS , +.IR WLC_BIT_MOD_CTRL , +.IR WLC_BIT_MOD_ALT , +.IR WLC_BIT_MOD_MOD2 , +.IR WLC_BIT_MOD_MOD3 , +.I WLC_BIT_MOD_LOGO +and +.IR WLC_BIT_MOD_MOD5 . + +The +.I WLC_BIT_MOD_LOGO +modifier corresponds to the key which has a system logo drawn onto it such as +Windows\*R or the Linux\*(Tm penguin. This is also known as the "super" key or +"mod4". + +The +.I key +returns the raw keycode which depends on the operating system and +hardware. This value should be processed via a function such as +.nh +.BR wlc_keyboard_get_keysym_for_key (3). +.hy + +The key state provides distinction between pressed and released positions +with +.I WLC_KEY_STATE_PRESSED +and +.I WLC_KEY_STATE_RELEASED +respectively. + +.SH RETURN VALUE +The return value of the callback +.I cb +dictate what is sent to the client. If the callback returns +.I true +then the client doesn't see the event, if +.I false +the events fall through to the client. + +.SH EXAMPLE +.nf +#include + +static bool +handle_key(wlc_handle view, uint32_t time, + const struct wlc_modifiers *modifiers, uint32_t key, + enum wlc_key_state state) +{ + if (state == WLC_KEY_STATE_PRESSED) { + uint32_t sym = wlc_keyboard_get_keysym_for_key(key, 0); + + if (bind = match_bind(sym, modifiers->mods, bindings)) + process(bind); + } +} + +wlc_set_keyboard_key_cb(handle_key); +.fi + +.SH ALSO SEE +.BR wlc_interface.view (3), +.BR wlc_init (3), +.BR wlc_keyboard_get_keysym_for_key (3) From 141866aaacfe73233c3fa916abece405e861e97c Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 16:51:30 +0100 Subject: [PATCH 11/14] Document the compositor readiness callbacks https://github.com/Cloudef/wlc/issues/156 --- man/man3/wlc_set_compositor_ready_cb.3 | 26 ++++++++++++++++++++++ man/man3/wlc_set_compositor_terminate_cb.3 | 1 + 2 files changed, 27 insertions(+) create mode 100644 man/man3/wlc_set_compositor_ready_cb.3 create mode 100644 man/man3/wlc_set_compositor_terminate_cb.3 diff --git a/man/man3/wlc_set_compositor_ready_cb.3 b/man/man3/wlc_set_compositor_ready_cb.3 new file mode 100644 index 00000000..e48c6042 --- /dev/null +++ b/man/man3/wlc_set_compositor_ready_cb.3 @@ -0,0 +1,26 @@ +.TH SET_COMPOSITOR_READY_CB 3 2016-04-22 WLC "WLC Core API Functions" + +.SH NAME +wlc_set_compositor_ready_cb, wlc_set_compositor_terminate_cb \- compositor +readiness callbacks + +.SH SYNOPSIS +.B #include + +.BI "void wlc_set_compositor_ready_cb(void (*"cb ")(void)); +.BI "void wlc_set_compositor_terminate_cb(void (*"cb ")(void)); + +.SH DESCRIPTION +.BR wlc_set_compositor_ready_cb () +lets one configure a callback +.I cb +to trigger when the main compositor is ready to +accept clients while +.BR wlc_set_compositor_terminate_cb () +provides a mechanism to notify the programmer about imminent compositor +shutdown where a callback +.I cb +can be set to handle any custom teardown routines. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_set_compositor_terminate_cb.3 b/man/man3/wlc_set_compositor_terminate_cb.3 new file mode 100644 index 00000000..c3496a66 --- /dev/null +++ b/man/man3/wlc_set_compositor_terminate_cb.3 @@ -0,0 +1 @@ +.so wlc_set_compositor_terminate_cb.3 From 7a9cfca56547800244f535c96c43e90f5051c081 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 18:32:20 +0100 Subject: [PATCH 12/14] Document a few output API functions https://github.com/Cloudef/wlc/issues/156 * wlc_get_focused_output.3 * wlc_output_get_name.3 * wlc_output_get_resolution.3 * wlc_output_set_resolution.3 --- man/man3/wlc_get_focused_output.3 | 16 +++++++++++ man/man3/wlc_output_get_name.3 | 22 ++++++++++++++ man/man3/wlc_output_get_resolution.3 | 31 ++++++++++++++++++++ man/man3/wlc_output_set_resolution.3 | 43 ++++++++++++++++++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 man/man3/wlc_get_focused_output.3 create mode 100644 man/man3/wlc_output_get_name.3 create mode 100644 man/man3/wlc_output_get_resolution.3 create mode 100644 man/man3/wlc_output_set_resolution.3 diff --git a/man/man3/wlc_get_focused_output.3 b/man/man3/wlc_get_focused_output.3 new file mode 100644 index 00000000..c1564173 --- /dev/null +++ b/man/man3/wlc_get_focused_output.3 @@ -0,0 +1,16 @@ +.TH WLC_GET_FOCUSED_OUTPUT 3 2016-04-22 WLC "WLC Output API Functions" + +.SH NAME +wlc_get_focused_output \- get the focused output + +.SH SYNOPSIS +.B #include + +.B wlc_handle wlc_get_focused_output(void); + +.SH DESCRIPTION +.BR wlc_get_focused_output () +is used to get the currently focused output. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_output_get_name.3 b/man/man3/wlc_output_get_name.3 new file mode 100644 index 00000000..9d385fa0 --- /dev/null +++ b/man/man3/wlc_output_get_name.3 @@ -0,0 +1,22 @@ +.TH WLC_OUTPUT_GET_NAME 3 2016-04-22 WLC "WLC CORE API FUNCTIONS" + +.SH NAME +wlc_output_get_name \- get the output name +.SH SYNOPSIS +.B #include + +.BI "const char* wlc_output_get_name(wlc_handle "output ); + +.SH DESCRIPTION +Use +.BR wlc_output_get_name () +for a given +.I output +to determine its name, such as +.IR LVDS1 , +.IR DP1 , +.IR HDMI1 , +etc. + +.SH RETURN VALUE +None. diff --git a/man/man3/wlc_output_get_resolution.3 b/man/man3/wlc_output_get_resolution.3 new file mode 100644 index 00000000..eb2f9830 --- /dev/null +++ b/man/man3/wlc_output_get_resolution.3 @@ -0,0 +1,31 @@ +.TH WLC_OUTPUT_GET_RESOLUTION 3 2016-04-22 WLC "WLC API FUNCTIONS" + +.SH NAME +wlc_output_get_resolution \- return output resolution + +.SH SYNOPSIS +.B #include + +.BI "const struct wlc_size* wlc_output_get_resolution(wlc_handle "output ); + +.SH DESCRIPTION +.BR wlc_output_get_resolution () +can be used to get the resolution of a given +.IR output . + +.SH RETURN VALUE +.BR wlc_output_get_resolution () +returns a wlc_size with the values +.I w +and +.I h +representing the output's dimensions. + +.SH ERRORS +If +.BR wlc_output_get_resolution () +fails for any reason it shall return +.IR NULL . + +.SH SEE ALSO +.BR wlc_output_set_resolution (3) diff --git a/man/man3/wlc_output_set_resolution.3 b/man/man3/wlc_output_set_resolution.3 new file mode 100644 index 00000000..6a9ed498 --- /dev/null +++ b/man/man3/wlc_output_set_resolution.3 @@ -0,0 +1,43 @@ +.TH WLC_OUTPUT_SET_RESOLUTION 3 2016-04-22 WLC "WLC API FUNCTIONS" + +.SH NAME +wlc_output_set_resolution \- set output resolution + +.SH SYNOPSIS +.B #include + +.nf +.BI "void wlc_output_set_resolution(wlc_handle "output , +.BI " const struct wlc_size *"resolution ); +.fi + +.SH DESCRIPTION +.BR wlc_output_set_resolution () +can be used to set the +.I resolution +of a given +.IR output . + +.SH RETURN VALUE +None. + +.SH NOTES +If the +.I output +is NULL or the requested +.I resolution +is the same as the +.I output +resolution then +.BR wlc_output_set_resolution () +shall do nothing. + +.BR wlc_output_set_resolution () +will abort if the +.I resolution +is NULL. + +It can also abort on memory allocation failure. + +.SH SEE ALSO +.BR wlc_output_get_resolution (3) From b67786d7ea6d583ae74c7ea9861d702f9a66eda9 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 19:17:28 +0100 Subject: [PATCH 13/14] man: wlc_get_focused_output mention abort state --- man/man3/wlc_get_focused_output.3 | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/man/man3/wlc_get_focused_output.3 b/man/man3/wlc_get_focused_output.3 index c1564173..bf17f584 100644 --- a/man/man3/wlc_get_focused_output.3 +++ b/man/man3/wlc_get_focused_output.3 @@ -1,7 +1,7 @@ .TH WLC_GET_FOCUSED_OUTPUT 3 2016-04-22 WLC "WLC Output API Functions" .SH NAME -wlc_get_focused_output \- get the focused output +wlc_get_focused_output \- get currently focused output .SH SYNOPSIS .B #include @@ -10,7 +10,17 @@ wlc_get_focused_output \- get the focused output .SH DESCRIPTION .BR wlc_get_focused_output () -is used to get the currently focused output. +can be used to get the currently focused output regardless of the surrounding +context. .SH RETURN VALUE -None. +.BR wlc_get_focused_output () +returns a wlc_handle to the currently focused output. + +.SH NOTES +.BR wlc_get_focused_output () +will abort if called before +.BR wlc_init (3). + +.SH SEE ALSO +.BR wlc (7) From cabde14c8d79a2f0465cc7a44e7cacac722ff905 Mon Sep 17 00:00:00 2001 From: Earnestly Date: Fri, 22 Apr 2016 19:18:43 +0100 Subject: [PATCH 14/14] Add some more manuals https://github.com/Cloudef/wlc/issues/156 * wlc_output_get_sleep.3 * wlc_output_set_sleep.3 * wlc_view_close.3 * wlc_view_focus.3 --- man/man3/wlc_output_get_sleep.3 | 24 ++++++++++++++++++++ man/man3/wlc_output_set_sleep.3 | 39 +++++++++++++++++++++++++++++++++ man/man3/wlc_view_close.3 | 27 +++++++++++++++++++++++ man/man3/wlc_view_focus.3 | 25 +++++++++++++++++++++ 4 files changed, 115 insertions(+) create mode 100644 man/man3/wlc_output_get_sleep.3 create mode 100644 man/man3/wlc_output_set_sleep.3 create mode 100644 man/man3/wlc_view_close.3 create mode 100644 man/man3/wlc_view_focus.3 diff --git a/man/man3/wlc_output_get_sleep.3 b/man/man3/wlc_output_get_sleep.3 new file mode 100644 index 00000000..3b661409 --- /dev/null +++ b/man/man3/wlc_output_get_sleep.3 @@ -0,0 +1,24 @@ +.TH WLC_OUTPUT_GET_SLEEP 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_output_get_sleep \- get sleep state of the output + +.SH SYNOPSIS +.B #include + +.BI "bool wlc_output_get_sleep(wlc_handle "output ); + +.SH DESCRIPTION +.BR wlc_output_get_sleep () +is used to determine the sleep state of a given +.IR output . + +.SH RETURN VALUE +.BR wlc_output_get_sleep () +will return +.I true +to indicate that the output is sleeping otherwise it will return +.IR false . + +.SH SEE ALSO +.BR wlc_output_set_sleep (3) diff --git a/man/man3/wlc_output_set_sleep.3 b/man/man3/wlc_output_set_sleep.3 new file mode 100644 index 00000000..cf0bd453 --- /dev/null +++ b/man/man3/wlc_output_set_sleep.3 @@ -0,0 +1,39 @@ +.TH WLC_OUTPUT_SET_SLEEP 3 2016-04-22 WLC "WLC API FUNCTIONS" + +.SH NAME +wlc_output_set_sleep \- put an output to sleep + +.SH SYNOPSIS +.B #include + +.BI "void wlc_output_set_sleep(wlc_handle "output ", bool "sleep ); + +.SH DESCRIPTION +.BR wlc_output_set_sleep () +is used to put a given +.I output +to sleep or to wake it up depending on the value of +.IR sleep . + +If it is +.I true +then +.BR wlc_output_set_sleep () +will to put the +.I output +to sleep, otherwise, it will wake it up with +.IR false . + +.SH RETURN VALUE +None. + +.SH NOTES +If the given +.I output +is NULL, already asleep or pending sleep state then +.BR wlc_output_set_sleep () +will do nothing. + +.SH SEE ALSO +.BR wlc (7), +.BR wlc_output_get_sleep (3) diff --git a/man/man3/wlc_view_close.3 b/man/man3/wlc_view_close.3 new file mode 100644 index 00000000..23a2dd02 --- /dev/null +++ b/man/man3/wlc_view_close.3 @@ -0,0 +1,27 @@ +.TH WLC_VIEW_CLOSE 3 2016-04-22 WLC "WLC API Functions" + +.SH NAME +wlc_view_close \- close a view +.SH SYNOPSIS +.B #include + +.BI "void wlc_view_close(wlc_handle "view ); + +.SH DESCRIPTION +.BR wlc_view_close () +is used to close a given +.IR view . +This is typically a window representing a client. + +.SH RETURN VALUE +None. + +.SH NOTES +If +.I view +is NULL or zero then +.BR wlc_view_close () +shall do nothing. + +.SH SEE ALSO +.BR wlc (7) diff --git a/man/man3/wlc_view_focus.3 b/man/man3/wlc_view_focus.3 new file mode 100644 index 00000000..f9821dc1 --- /dev/null +++ b/man/man3/wlc_view_focus.3 @@ -0,0 +1,25 @@ +.TH WLC_VIEW_FOCUS 3 2016-04-22 WLC "WLC API FUNCTIONS" + +.SH NAME +wlc_view_focus \- focus or defocus a view + +.SH SYNOPSIS +.B #include + +.BI "void wlc_view_focus(wlc_handle "view ); + +.SH DESCRIPTION +.BR wlc_view_focus () +is used to focus a given +.I view +or if +.I view +is zero or NULL +.BR wlc_view_focus () +will defocus all views. + +.SH RETURN VALUE +None. + +.SH SEE ALSO +.BR wlc (7)