Initial documentation

[WLCIssuesBot]

Issue by Earnestly Friday Apr 22, 2016 at 00:19 GMT Originally opened as https://github.com/Cloudef/wlc/pull/155

---

The man3 stuff should be okay to go, I'm not sure how you feel about having a second CONTRIBUTING.rst and the WIP section 7 manual could be left out until more complete.

This will need some cmake work where the manuals are installed to (using GNU's terminology) datarootdir/mandir/man(3,7)/ which is usually /share/man/man(3,7)

---

Earnestly included the following code: https://github.com/Cloudef/wlc/pull/155/commits

[WLCIssuesBot]

Comment by Cloudef Friday Apr 22, 2016 at 08:55 GMT

---

Looks good, :+1: for the contribution guide. Will you be adding more commits still?

[WLCIssuesBot]

Comment by Earnestly Friday Apr 22, 2016 at 09:27 GMT

---

Yeah, I've got a few more queued. These are separate because you might not want to accept all of them.

[WLCIssuesBot]

Comment by Drakulix Thursday Oct 20, 2016 at 22:25 GMT

---

The parameter time represents a timestamp of when the mouse event occured. It is a magical number and cannot be relied on. I was looking for some information regarding this timestamp and THIS is the best I've found. Does this mean the argument is effectively useless or may I kindly ask why it is magical and what I can learn from it. :smile:

[WLCIssuesBot]

Comment by Cloudef Friday Oct 21, 2016 at 07:31 GMT

---

@Drakulix I think it's magical in sense that it depends on what backend puts on it and I did not even standardize the unit.. :) For the common case though (running from TTY) that timestamp comes from libinput and will correspond to whatever libinput gives. But the documentation is correct in this case, that the argument is badly specified.

[WLCIssuesBot]

Comment by Drakulix Friday Oct 21, 2016 at 07:38 GMT

---

@Cloudef Alright, thanks! So I guess the only reasonable thing you may do with this value is comparing it to other events?

[WLCIssuesBot]

Comment by Cloudef Friday Oct 21, 2016 at 07:41 GMT

---

Yeah, it's mainly provided so the callback can give you events from the past.

[WLCIssuesBot]

Comment by Fale Tuesday Jan 24, 2017 at 16:39 GMT

---

any news on those man pages?

[WLCIssuesBot]

Comment by Earnestly Tuesday Jan 24, 2017 at 18:05 GMT

---

I haven't been working on many lately

[WLCIssuesBot]

Comment by Timidger Tuesday Jan 24, 2017 at 21:23 GMT

---

What is left to document? I can look into it because I'd rather not have to duplicate documentation for rust-wlc

[WLCIssuesBot]

Comment by Earnestly Tuesday Jan 24, 2017 at 22:17 GMT

---

@Timidger https://github.com/Cloudef/wlc/issues/156

I do have a few WIPs, although they're mostly just been setup, ready to expand, so not much content.

One of the main ones being: wlc_set_view_created_cb.3 which provides for the following manuals:

wlc_set_view_focus_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_destroyed_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_move_to_output_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_render_pre_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_render_post_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_request_move_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_request_state_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_request_resize_cb.3:.so wlc_set_view_created_cb.3
wlc_set_view_request_geometry_cb.3:.so wlc_set_view_created_cb.3

.TH WLC_SET_VIEW_CREATED_CB 3 2016-04-22 WLC "WLC Core API Functions"

.SH NAME
.nh
wlc_set_view_created_cb, wlc_set_view_destroyed_cb, wlc_set_view_focus_cb,
wlc_set_view_move_to_output_cb, wlc_set_view_request_geometry_cb,
wlc_set_view_request_state_cb, wlc_set_view_request_move_cb,
wlc_set_view_request_resize_cb, wlc_set_view_render_pre_cb,
wlc_set_view_render_post_cb, wlc_set_view_properties_updated_cb
\- callbacks for managing views
.hy

.SH SYNOPSIS
.B #include <wlc/wlc.h>

.nf
.BI "void wlc_set_view_created_cb(bool (*"cb ")(wlc_handle "view ));
.BI "void wlc_set_view_destroyed_cb(void (*"cb ")(wlc_handle "view ));
.BI "void wlc_set_view_focus_cb(void (*"cb ")(wlc_handle "view ", bool "focus ));
.BI "void wlc_set_view_move_to_output_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                    wlc_handle "from_output ,
.BI "                                    wlc_handle "to_output ));
.BI "void wlc_set_view_request_geometry_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                      const struct wlc_geometry*));
.BI "void wlc_set_view_request_state_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                   enum wlc_view_state_bit, bool "toggle ));
.BI "void wlc_set_view_request_move_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                  const struct wlc_point*));
.BI "void wlc_set_view_request_resize_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                    uint32_t "edges ", const struct wlc_point*));
.BI "void wlc_set_view_render_pre_cb(void (*"cb ")(wlc_handle "view ));
.BI "void wlc_set_view_render_post_cb(void (*"cb ")(wlc_handle "view ));
.BI "void wlc_set_view_properties_updated_cb(void (*"cb ")(wlc_handle "view ,
.BI "                                        uint32_t "mask ));
.fi

.SH DESCRIPTION
The view functions all take a callback
.I cb
to configure the wlc library before
.BR wlc_init (3)
is called. Views typically represent interactive surfaces such as windows in a
window manager.

The
.BR wlc_set_view_created_cb ()
function can set a callback which is called when views are created, if the
callback returns false then the view is destroyed.

The
.BR wlc_set_view_destroyed_cb ()
function sets a callback which is triggered on view destruction.

The
.BR wlc_set_view_focus_cb ()
function can set a callback to trigger when a focus event occurs, the parameter
.I focus
is used to indicate focus on
.I true
and defocus on
.IR false .

The
.BR wlc_set_view_move_to_output_cb ()
function can set a callback to be trigged when a view has moved to another
output. The
.I from_output
parameter tracks the origin output and the
.I to_output
contains the output the view was moved to.

The
.BR wlc_set_view_request_geometry_cb ()
function can set a callback which is triggered based on the geometry a view
requests.  Typically one would use
.BR wlc_view_set_geometry (3)
to apply the geometry requested.

The
.BR wlc_set_view_request_state_cb ()
function can set a callback which is triggered when views request to toggle a
state bit.  These states include:
.IR WLC_BIT_MAXIMIZED ,
.IR WLC_BIT_FULLSCREEN ,
.IR WLC_BIT_RESIZING ,
.IR WLC_BIT_MOVING ,
and
.I WLC_BIT_ACTIVATED
which can be applied using
.BR wlc_view_set_state (3).

The
.BR wlc_set_view_request_move_cb ()
function can set a callback which is triggered when views request to be moved.
For example one can use
.BR wlc_view_set_geometry (3)
to initiate the move.

The
.BR wlc_set_view_request_resize_cb ()
function can set a callback which is triggered when a view requests to be
resized from the given
.IR edges .

The
.I edges
represents the edges or corners of a view and can be one of
.IR WLC_RESIZE_EDGE_NONE ,
.IR WLC_RESIZE_EDGE_TOP ,
.IR WLC_RESIZE_EDGE_BOTTOM ,
.IR WLC_RESIZE_EDGE_LEFT ,
.IR WLC_RESIZE_EDGE_TOP_LEFT ,
.IR WLC_RESIZE_EDGE_BOTTOM_LEFT ,
.IR WLC_RESIZE_EDGE_RIGHT ,
.IR WLC_RESIZE_EDGE_TOP_RIGHT
or
.IR WLC_RESIZE_EDGE_BOTTOM_RIGHT .

Stub.
.BR wlc_set_view_render_pre_cb ()

Stub.
.BR wlc_set_view_render_post_cb ()

Stub.
.BR wlc_set_view_properties_updated_cb ()

.SH SEE ALSO
.BR wlc (7),
.BR wlc_view_set_state (3),
.BR wlc_view_set_geometry (3)

[WLCIssuesBot]

Comment by telent Friday Mar 17, 2017 at 22:31 GMT

---

These docs are awesome, I wish I'd known about this branch when I started looking at wlc. I won't ask "can it be merged" because free software, your priorities are your own, etc etc, but as a consumer of the software I definitely think it's worth merging as-is irrespective of any further updates that may or may not be forthcoming.