Initial documentation #155
Conversation
This is an initial commit with documentation for wlc_init, wlc_run and wlc_terminate in the groff markup.
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.
|
Looks good, 👍 for the contribution guide. Will you be adding more commits still? |
|
Yeah, I've got a few more queued. These are separate because you might not want to accept all of them. |
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.
This replaces the use of args for userdata as it makes the purpose of it much clearer at a glance.
#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
#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
#156 * wlc_get_focused_output.3 * wlc_output_get_name.3 * wlc_output_get_resolution.3 * wlc_output_set_resolution.3
#156 * wlc_output_get_sleep.3 * wlc_output_set_sleep.3 * wlc_view_close.3 * wlc_view_focus.3
|
|
|
@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. |
|
@Cloudef Alright, thanks! So I guess the only reasonable thing you may do with this value is comparing it to other events? |
|
Yeah, it's mainly provided so the callback can give you events from the past. |
|
any news on those man pages? |
|
I haven't been working on many lately |
|
What is left to document? I can look into it because I'd rather not have to duplicate documentation for rust-wlc |
|
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: .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) |
|
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. |
The
man3stuff should be okay to go, I'm not sure how you feel about having a secondCONTRIBUTING.rstand 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)