summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2016-10-24 16:17:44 (GMT)
committer Vincent Sanders <vince@kyllikki.org>2016-10-24 16:17:44 (GMT)
commitaf5f4a570453c2d0b1dcfd06044ad3abb3bd4325 (patch)
treedd0c2c6e057b2edb104c0e5cb85afb51fde3f396
parentf814edee75db5158f8fbb1930e25e0877d5448de (diff)
downloadnetsurf-af5f4a570453c2d0b1dcfd06044ad3abb3bd4325.tar.gz
netsurf-af5f4a570453c2d0b1dcfd06044ad3abb3bd4325.tar.bz2
Initial attempt to document the core window interface
-rw-r--r--Docs/core-window-interface108
1 files changed, 108 insertions, 0 deletions
diff --git a/Docs/core-window-interface b/Docs/core-window-interface
new file mode 100644
index 0000000..0d5f7bc
--- a/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