netsurf/Docs/ideas/render-library.txt

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);