From af5f4a570453c2d0b1dcfd06044ad3abb3bd4325 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Mon, 24 Oct 2016 17:17:44 +0100
Subject: Initial attempt to document the core window interface

---
 Docs/core-window-interface | 108 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 Docs/core-window-interface

diff --git a/Docs/core-window-interface b/Docs/core-window-interface
new file mode 100644
index 000000000..0d5f7bccb
--- /dev/null
+++ b/Docs/core-window-interface
@@ -0,0 +1,108 @@
+Core Window Interface
+=====================
+
+The NetSurf core provides an optional API to frontend implementations
+which allows a number of "standard" window content interfaces to be
+provided.
+
+The currently available user interfaces are:
+
+ - Cookies
+ - Global history
+ - Hotlist
+ - SSL certificate view
+
+Although not currently included in future additional user interfaces
+will be available for:
+
+ - local history
+ - browser render
+
+To be clear these are generic implementations of this functionality
+that any frontend may use. Frontends are free to implement these
+interfaces in any manner as they see fit, the corewindow interface
+simply provides a default.
+
+core window API
+---------------
+
+The API is fairly simple and simply involves passing a callback table
+and context pointer to the interface element being constructed.
+
+The header that defines the callback interface is netsurf/core_window.h 
+
+The callback table contains five function pointer interfaces which the
+frontend must implement for the core.
+
+ - redraw_request
+      request a redraw an area of a window
+
+ - update_size
+      Update the limits of the window 
+
+ - scroll_visible
+      Scroll the window to make area visible
+
+ - get_window_dimensions
+      Get window viewport dimensions
+
+ - drag_status
+      Inform corewindow owner of drag status
+
+Each callback will be passed the context pointer for the corewindow
+instance and the relevant additional information necessary to perform
+the operation.
+
+Each exported user interface element wraps this generic interface with
+a concrete implementation. For example the SSL certificate viewer is
+initialised with:
+
+nserror sslcert_viewer_init(struct core_window_callback_table *cw_t,
+                            void *core_window_handle,
+                            struct sslcert_session_data *ssl_d);
+
+This call creates a context which will display and navigate the ssl
+session data passed. The frontend must service the callbacks from the
+core to provide the necessary interactions with the frontend windowing
+system.
+
+These actions should ideally use the standard frontend window
+processing. So for the GTK frontend when the core calls the redraw
+operation it simply marks the area passed as damaged (using
+gtk_widget_queue_draw_area()) and lets the standard expose event cause
+the redraw to occour.
+
+If the frontend needs to redraw an area of a window (perhaps an expose
+event occoured) it must call the corewindoe API wrappers
+implementation e.g in the case of ssl certificate viewer
+
+void sslcert_viewer_redraw(struct sslcert_session_data *ssl_d,
+		           int x, int y, struct rect *clip,
+		           const struct redraw_context *ctx);
+
+which will perform the plot operations required to update an area of
+the window for that SSL data.
+
+Usage
+-----
+
+The usage pattern that is expected is for a frontend to create a core
+window impementation that implements the necessary five API in a
+generic way and allows the frontend to provide the specific
+specialisation for each of the user interface elements it wishes to
+use (cookies, SSL viewer etc).
+
+The GTK frontend for example:
+
+has source corewindow.[ch] which implement the five core callbacks
+using generic GTK operations (redraw_request calls
+gtk_widget_queue_draw_area() etc.) and then provides additional
+operations on a GTK drawing area object to attach expose event
+processing, keypress processing etc.
+
+The GTK corewindow (not to be confused with the core window API
+itself, this is purely the gtk wrapper) is used by ssl_cert.c which
+creates a nsgtk_crtvrfy_window structure containing the
+nsgtk_corewindow structure. It attaches actual GTK window handles to
+this structure and populates elements of nsgtk_corewindow and then
+calls sslcert_viewer_init() directly.
\ No newline at end of file
-- 
cgit v1.2.3