summaryrefslogtreecommitdiff
path: root/Docs
diff options
context:
space:
mode:
Diffstat (limited to 'Docs')
-rw-r--r--Docs/ideas/render-library.txt121
1 files changed, 121 insertions, 0 deletions
diff --git a/Docs/ideas/render-library.txt b/Docs/ideas/render-library.txt
new file mode 100644
index 000000000..db645c427
--- /dev/null
+++ b/Docs/ideas/render-library.txt
@@ -0,0 +1,121 @@
+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);
+