Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | Download | RSS feed

  1. Rendering library
  2. =================
  3.  
  4. General notes
  5. -------------
  6.  
  7.  + Potentially long-running routines probably want to exit early and
  8.    ask to be resumed (or similar)
  9.  + There's loads of stuff missing from here (like a typesystem :)
  10.  
  11. Possible API
  12. ------------
  13.  
  14.   /* Initialise library */
  15.   error html_init(void);
  16.   /* Finalise library */
  17.   error html_fini(void);
  18.  
  19.   /* Create a context */
  20.   ctx   html_create(void);
  21.   /* Destroy a context */
  22.   void  html_destroy(ctx);
  23.  
  24.   /* Configure a context
  25.    *
  26.    * Things that need configuring:
  27.    *
  28.    * Callbacks from library -> client:
  29.    *
  30.    * + Handler for embedded object fetch requests (how to handle frames?)
  31.    * + Event notification handler (e.g. form submission / link navigation,
  32.    *   mouse pointer shape changing, redraw request, position caret, etc)
  33.    *
  34.    * Other stuff:
  35.    *
  36.    * + Scale? (should this be handled by the client?)
  37.    * + Whether to run scripts? (possibly, not needed yet)
  38.    */
  39.   error html_setopt(ctx, opttype, optparams);
  40.  
  41.   /* Feed HTML data to a context */
  42.   error html_process_data(ctx, data, len);
  43.   /* Flag end of data to context */
  44.   error html_data_done(ctx);
  45.  
  46.   /* Reflow context, to given width/height */
  47.   error html_reflow(ctx, width, height);
  48.  
  49.   /* Redraw context, using provided plotters */
  50.   error html_redraw(ctx, rect, plot_table);
  51.  
  52.   /* Some kind of input event notification APIs.
  53.    * These are called by the client to notify the library
  54.    * that something's happened.
  55.    *
  56.    * e.g.:
  57.    */
  58.   error html_mouse_move(ctx, x, y);
  59.   error html_mouse_press(ctx, x, y, buttons, modifiers);
  60.   error html_mouse_release(ctx, x, y, buttons, modifiers);
  61.   error html_key_press(ctx, key, modifiers);
  62.   error html_key_release(ctx, key, modifiers);
  63.   error html_scroll_x(ctx, offset);
  64.   error html_scroll_y(ctx, offset);
  65.  
  66.   /* Retrieve properties of document in context
  67.    *
  68.    * e.g.:
  69.    */
  70.   error html_get_title(ctx, title);
  71.  
  72. Example usage
  73. -------------
  74.  
  75. /* Main routine */
  76. main:
  77.   /* Initialise library */
  78.   html_init();
  79.  
  80.   /* Create a context */
  81.   ctx = html_create();
  82.  
  83.   /* Configure the context */
  84.   html_setopt(ctx, FETCH_HANDLER, my_fetcher);
  85.   html_setopt(ctx, EVENT_HANDLER, my_event_handler);
  86.  
  87.   /* Get it to process data */
  88.   foreach (chunk, len) in data:
  89.     html_process_data(ctx, chunk, len);
  90.   html_data_done(ctx);
  91.  
  92.   /* Reflow content to desired dimensions */
  93.   html_reflow(ctx, width, height);
  94.  
  95.   /* Main client event loop -- processes UI-toolkit events */
  96.   do:
  97.     on mouse event:
  98.       html_mouse_{move,press,release}(ctx, event.x, event.y ...);
  99.     on key event:
  100.       html_key_{press,release}{ctx, event.key, event.modifiers);
  101.     on scroll event:
  102.       html_scroll_{x,y}(ctx, event.offset);
  103.     on redraw event:
  104.       html_redraw(ctx, event.rect, my_plotters);
  105.    until quit;
  106.  
  107.   /* Destroy context */
  108.   html_destroy(ctx);
  109.  
  110.   /* Finalise library */
  111.   html_fini();
  112.  
  113. /* Event handler for library-generated events */
  114. my_event_handler:
  115.   on pointer shape change:
  116.     set_pointer_shape(shape);
  117.   on redraw request:
  118.     redraw_window(window);
  119.   on position caret:
  120.     position caret(x, y);
  121.  
  122.