netsurf/Docs/ideas/render-library.txt

122 lines
3.0 KiB
Plaintext
Raw Normal View History

Rendering library
=================
General notes
-------------
+ Potentially long-running routines probably want to exit early and
ask to be resumed (or similar)
+ There's loads of stuff missing from here (like a typesystem :)
Possible API
------------
/* Initialise library */
error html_init(void);
/* Finalise library */
error html_fini(void);
/* Create a context */
ctx html_create(void);
/* Destroy a context */
void html_destroy(ctx);
/* Configure a context
*
* Things that need configuring:
*
* Callbacks from library -> client:
*
* + Handler for embedded object fetch requests (how to handle frames?)
* + Event notification handler (e.g. form submission / link navigation,
* mouse pointer shape changing, redraw request, position caret, etc)
*
* Other stuff:
*
* + Scale? (should this be handled by the client?)
* + Whether to run scripts? (possibly, not needed yet)
*/
error html_setopt(ctx, opttype, optparams);
/* Feed HTML data to a context */
error html_process_data(ctx, data, len);
/* Flag end of data to context */
error html_data_done(ctx);
/* Reflow context, to given width/height */
error html_reflow(ctx, width, height);
/* Redraw context, using provided plotters */
error html_redraw(ctx, rect, plot_table);
/* Some kind of input event notification APIs.
* These are called by the client to notify the library
* that something's happened.
*
* e.g.:
*/
error html_mouse_move(ctx, x, y);
error html_mouse_press(ctx, x, y, buttons, modifiers);
error html_mouse_release(ctx, x, y, buttons, modifiers);
error html_key_press(ctx, key, modifiers);
error html_key_release(ctx, key, modifiers);
error html_scroll_x(ctx, offset);
error html_scroll_y(ctx, offset);
/* Retrieve properties of document in context
*
* e.g.:
*/
error html_get_title(ctx, title);
Example usage
-------------
/* Main routine */
main:
/* Initialise library */
html_init();
/* Create a context */
ctx = html_create();
/* Configure the context */
html_setopt(ctx, FETCH_HANDLER, my_fetcher);
html_setopt(ctx, EVENT_HANDLER, my_event_handler);
/* Get it to process data */
foreach (chunk, len) in data:
html_process_data(ctx, chunk, len);
html_data_done(ctx);
/* Reflow content to desired dimensions */
html_reflow(ctx, width, height);
/* Main client event loop -- processes UI-toolkit events */
do:
on mouse event:
html_mouse_{move,press,release}(ctx, event.x, event.y ...);
on key event:
html_key_{press,release}{ctx, event.key, event.modifiers);
on scroll event:
html_scroll_{x,y}(ctx, event.offset);
on redraw event:
html_redraw(ctx, event.rect, my_plotters);
until quit;
/* Destroy context */
html_destroy(ctx);
/* Finalise library */
html_fini();
/* Event handler for library-generated events */
my_event_handler:
on pointer shape change:
set_pointer_shape(shape);
on redraw request:
redraw_window(window);
on position caret:
position caret(x, y);