Gitweb links:
...log
http://git.netsurf-browser.org/netsurf.git/shortlog/bc42b2980115850ce93ee7cfa73460a63d25e444
...commit
http://git.netsurf-browser.org/netsurf.git/commit/bc42b2980115850ce93ee7cfa73460a63d25e444
...tree
http://git.netsurf-browser.org/netsurf.git/tree/bc42b2980115850ce93ee7cfa73460a63d25e444
The branch, master has been updated
via bc42b2980115850ce93ee7cfa73460a63d25e444 (commit)
from 6f7b5e3f221b4da4ff5da07281e0f2074b9e57fd (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commitdiff
http://git.netsurf-browser.org/netsurf.git/commit/?id=bc42b2980115850ce93ee7cfa73460a63d25e444
commit bc42b2980115850ce93ee7cfa73460a63d25e444
Author: Vincent Sanders <[email protected]>
Commit: Vincent Sanders <[email protected]>
improve documentation comments in browser window interface table
diff --git a/include/netsurf/window.h b/include/netsurf/window.h
index 81fc067..53d9b30 100644
--- a/include/netsurf/window.h
+++ b/include/netsurf/window.h
@@ -56,7 +56,7 @@ typedef enum {
typedef enum {
GW_CREATE_NONE = 0, /**< New window */
GW_CREATE_CLONE = (1 << 0), /**< Clone existing window */
- GW_CREATE_TAB = (1 << 1) /**< In same window as existing */
+ GW_CREATE_TAB = (1 << 1) /**< Create tab in same window as existing */
} gui_window_create_flags;
struct browser_window;
@@ -79,15 +79,25 @@ struct gui_window_table {
/**
* Create and open a gui window for a browsing context.
*
- * \param bw bw to create gui_window for
- * \param existing an existing gui_window, may be NULL
- * \param flags flags for gui window creation
- * \return gui window, or NULL on error
+ * The implementing front end must create a context suitable
+ * for it to display a window referred to as the "gui window".
+ *
+ * The frontend will be expected to request the core redraw
+ * areas of the gui window which have become invalidated
+ * either from toolkit expose events or as a result of a
+ * invalidate() call.
+ *
+ * Most core operations used by the frontend concerning browser
+ * windows require passing the browser window context therefor
+ * the gui window must include a reference to the browser
+ * window passed here.
*
* If GW_CREATE_CLONE flag is set existing is non-NULL.
*
- * Front end's gui_window must include a reference to the
- * browser window passed in the bw param.
+ * \param bw The core browsing context associated with the gui window
+ * \param existing An existing gui_window, may be NULL.
+ * \param flags flags to control the gui window creation.
+ * \return gui window, or NULL on error.
*/
struct gui_window *(*create)(struct browser_window *bw,
struct gui_window *existing,
@@ -115,22 +125,22 @@ struct gui_window_table {
* redraw operations as a result of this callback because the
* core redraw functions may already be threaded.
*
- * \param g gui_window
+ * \param gw The gui window to invalidate.
* \param rect area to redraw or NULL for the entire window area
* \return NSERROR_OK on success or appropriate error code
*/
- nserror (*invalidate)(struct gui_window *g, const struct rect *rect);
+ nserror (*invalidate)(struct gui_window *gw, const struct rect *rect);
/**
* Get the scroll position of a browser window.
*
- * \param g gui_window
- * \param sx receives x ordinate of point at top-left of window
- * \param sy receives y ordinate of point at top-left of window
+ * \param gw The gui window to obtain the scroll position from.
+ * \param sx receives x ordinate of point at top-left of window
+ * \param sy receives y ordinate of point at top-left of window
* \return true iff successful
*/
- bool (*get_scroll)(struct gui_window *g, int *sx, int *sy);
+ bool (*get_scroll)(struct gui_window *gw, int *sx, int *sy);
/**
@@ -142,12 +152,12 @@ struct gui_window_table {
* the contents will be scrolled so the specified point in the
* content is at the top of the viewport.
* If the size of the rectangle is non zero the frontend may
- * add padding or center the defined area or it may simply
+ * add padding or centre the defined area or it may simply
* align as in the zero size rectangle
*
- * \param gw gui_window to scroll
+ * \param gw The gui window to scroll.
* \param rect The rectangle to ensure is shown.
- * \return NSERROR_OK on success or apropriate error code.
+ * \return NSERROR_OK on success or appropriate error code.
*/
nserror (*set_scroll)(struct gui_window *gw, const struct rect *rect);
@@ -156,15 +166,15 @@ struct gui_window_table {
* Find the current dimensions of a browser window's content area.
*
* This is used to determine the actual available drawing size
- * in pixels. This is used to allow contents that can be
- * dynamicaly reformatted, such as HTML, to better use the
- * available space.
+ * in pixels. This allows contents that can be dynamically
+ * reformatted, such as HTML, to better use the available
+ * space.
*
* \param gw The gui window to measure content area of.
* \param width receives width of window
* \param height receives height of window
* \param scaled whether to return scaled values
- * \return NSERROR_OK on sucess and width and height updated
+ * \return NSERROR_OK on success and width and height updated
* else error code.
*/
nserror (*get_dimensions)(struct gui_window *gw, int *width, int
*height, bool scaled);
@@ -177,9 +187,9 @@ struct gui_window_table {
* @todo this is used to update scroll bars does it need
* renaming? some frontends (windows) do not even implement it.
*
- * \param g gui_window to update the extent of
+ * \param gw The gui window to update the extent of.
*/
- void (*update_extent)(struct gui_window *g);
+ void (*update_extent)(struct gui_window *gw);
/* Optional entries */
@@ -187,10 +197,10 @@ struct gui_window_table {
/**
* Set the title of a window.
*
- * \param g window to update
- * \param title new window title
+ * \param gw The gui window to set title of.
+ * \param title new window title
*/
- void (*set_title)(struct gui_window *g, const char *title);
+ void (*set_title)(struct gui_window *gw, const char *title);
/**
* Set the navigation url.
@@ -287,34 +297,50 @@ struct gui_window_table {
/**
* Called when the gui_window has new content.
*
- * \param g the gui_window that has new content
+ * \param gw The gui window that has new content
*/
- void (*new_content)(struct gui_window *g);
+ void (*new_content)(struct gui_window *gw);
/**
* create a form select menu
+ *
+ * \param gw The gui window to open select menu form gadget in.
+ * \param control The form control gadget handle.
*/
void (*create_form_select_menu)(struct gui_window *gw, struct
form_control *control);
/**
* Called when file chooser gadget is activated
+ *
+ * \param gw The gui window to open file chooser in.
+ * \param hl The content of the object.
+ * \param gadget The form control gadget handle.
*/
- void (*file_gadget_open)(struct gui_window *g, struct hlcache_handle
*hl, struct form_control *gadget);
+ void (*file_gadget_open)(struct gui_window *gw, struct hlcache_handle
*hl, struct form_control *gadget);
/**
* object dragged to window
+ *
+ * \param gw The gui window to save dragged object of.
+ * \param c The content of the object.
+ * \param type the type of save.
*/
- void (*drag_save_object)(struct gui_window *g, struct hlcache_handle
*c, gui_save_type type);
+ void (*drag_save_object)(struct gui_window *gw, struct hlcache_handle
*c, gui_save_type type);
/**
* drag selection save
+ *
+ * \param gw The gui window to save dragged selection of.
+ * \param selection The selection to save.
*/
- void (*drag_save_selection)(struct gui_window *g, const char
*selection);
+ void (*drag_save_selection)(struct gui_window *gw, const char
*selection);
/**
* selection started
+ *
+ * \param gw The gui window to start selection in.
*/
- void (*start_selection)(struct gui_window *g);
+ void (*start_selection)(struct gui_window *gw);
};
#endif
-----------------------------------------------------------------------
Summary of changes:
include/netsurf/window.h | 88 ++++++++++++++++++++++++++++++----------------
1 file changed, 57 insertions(+), 31 deletions(-)
diff --git a/include/netsurf/window.h b/include/netsurf/window.h
index 81fc067..53d9b30 100644
--- a/include/netsurf/window.h
+++ b/include/netsurf/window.h
@@ -56,7 +56,7 @@ typedef enum {
typedef enum {
GW_CREATE_NONE = 0, /**< New window */
GW_CREATE_CLONE = (1 << 0), /**< Clone existing window */
- GW_CREATE_TAB = (1 << 1) /**< In same window as existing */
+ GW_CREATE_TAB = (1 << 1) /**< Create tab in same window as existing */
} gui_window_create_flags;
struct browser_window;
@@ -79,15 +79,25 @@ struct gui_window_table {
/**
* Create and open a gui window for a browsing context.
*
- * \param bw bw to create gui_window for
- * \param existing an existing gui_window, may be NULL
- * \param flags flags for gui window creation
- * \return gui window, or NULL on error
+ * The implementing front end must create a context suitable
+ * for it to display a window referred to as the "gui window".
+ *
+ * The frontend will be expected to request the core redraw
+ * areas of the gui window which have become invalidated
+ * either from toolkit expose events or as a result of a
+ * invalidate() call.
+ *
+ * Most core operations used by the frontend concerning browser
+ * windows require passing the browser window context therefor
+ * the gui window must include a reference to the browser
+ * window passed here.
*
* If GW_CREATE_CLONE flag is set existing is non-NULL.
*
- * Front end's gui_window must include a reference to the
- * browser window passed in the bw param.
+ * \param bw The core browsing context associated with the gui window
+ * \param existing An existing gui_window, may be NULL.
+ * \param flags flags to control the gui window creation.
+ * \return gui window, or NULL on error.
*/
struct gui_window *(*create)(struct browser_window *bw,
struct gui_window *existing,
@@ -115,22 +125,22 @@ struct gui_window_table {
* redraw operations as a result of this callback because the
* core redraw functions may already be threaded.
*
- * \param g gui_window
+ * \param gw The gui window to invalidate.
* \param rect area to redraw or NULL for the entire window area
* \return NSERROR_OK on success or appropriate error code
*/
- nserror (*invalidate)(struct gui_window *g, const struct rect *rect);
+ nserror (*invalidate)(struct gui_window *gw, const struct rect *rect);
/**
* Get the scroll position of a browser window.
*
- * \param g gui_window
- * \param sx receives x ordinate of point at top-left of window
- * \param sy receives y ordinate of point at top-left of window
+ * \param gw The gui window to obtain the scroll position from.
+ * \param sx receives x ordinate of point at top-left of window
+ * \param sy receives y ordinate of point at top-left of window
* \return true iff successful
*/
- bool (*get_scroll)(struct gui_window *g, int *sx, int *sy);
+ bool (*get_scroll)(struct gui_window *gw, int *sx, int *sy);
/**
@@ -142,12 +152,12 @@ struct gui_window_table {
* the contents will be scrolled so the specified point in the
* content is at the top of the viewport.
* If the size of the rectangle is non zero the frontend may
- * add padding or center the defined area or it may simply
+ * add padding or centre the defined area or it may simply
* align as in the zero size rectangle
*
- * \param gw gui_window to scroll
+ * \param gw The gui window to scroll.
* \param rect The rectangle to ensure is shown.
- * \return NSERROR_OK on success or apropriate error code.
+ * \return NSERROR_OK on success or appropriate error code.
*/
nserror (*set_scroll)(struct gui_window *gw, const struct rect *rect);
@@ -156,15 +166,15 @@ struct gui_window_table {
* Find the current dimensions of a browser window's content area.
*
* This is used to determine the actual available drawing size
- * in pixels. This is used to allow contents that can be
- * dynamicaly reformatted, such as HTML, to better use the
- * available space.
+ * in pixels. This allows contents that can be dynamically
+ * reformatted, such as HTML, to better use the available
+ * space.
*
* \param gw The gui window to measure content area of.
* \param width receives width of window
* \param height receives height of window
* \param scaled whether to return scaled values
- * \return NSERROR_OK on sucess and width and height updated
+ * \return NSERROR_OK on success and width and height updated
* else error code.
*/
nserror (*get_dimensions)(struct gui_window *gw, int *width, int
*height, bool scaled);
@@ -177,9 +187,9 @@ struct gui_window_table {
* @todo this is used to update scroll bars does it need
* renaming? some frontends (windows) do not even implement it.
*
- * \param g gui_window to update the extent of
+ * \param gw The gui window to update the extent of.
*/
- void (*update_extent)(struct gui_window *g);
+ void (*update_extent)(struct gui_window *gw);
/* Optional entries */
@@ -187,10 +197,10 @@ struct gui_window_table {
/**
* Set the title of a window.
*
- * \param g window to update
- * \param title new window title
+ * \param gw The gui window to set title of.
+ * \param title new window title
*/
- void (*set_title)(struct gui_window *g, const char *title);
+ void (*set_title)(struct gui_window *gw, const char *title);
/**
* Set the navigation url.
@@ -287,34 +297,50 @@ struct gui_window_table {
/**
* Called when the gui_window has new content.
*
- * \param g the gui_window that has new content
+ * \param gw The gui window that has new content
*/
- void (*new_content)(struct gui_window *g);
+ void (*new_content)(struct gui_window *gw);
/**
* create a form select menu
+ *
+ * \param gw The gui window to open select menu form gadget in.
+ * \param control The form control gadget handle.
*/
void (*create_form_select_menu)(struct gui_window *gw, struct
form_control *control);
/**
* Called when file chooser gadget is activated
+ *
+ * \param gw The gui window to open file chooser in.
+ * \param hl The content of the object.
+ * \param gadget The form control gadget handle.
*/
- void (*file_gadget_open)(struct gui_window *g, struct hlcache_handle
*hl, struct form_control *gadget);
+ void (*file_gadget_open)(struct gui_window *gw, struct hlcache_handle
*hl, struct form_control *gadget);
/**
* object dragged to window
+ *
+ * \param gw The gui window to save dragged object of.
+ * \param c The content of the object.
+ * \param type the type of save.
*/
- void (*drag_save_object)(struct gui_window *g, struct hlcache_handle
*c, gui_save_type type);
+ void (*drag_save_object)(struct gui_window *gw, struct hlcache_handle
*c, gui_save_type type);
/**
* drag selection save
+ *
+ * \param gw The gui window to save dragged selection of.
+ * \param selection The selection to save.
*/
- void (*drag_save_selection)(struct gui_window *g, const char
*selection);
+ void (*drag_save_selection)(struct gui_window *gw, const char
*selection);
/**
* selection started
+ *
+ * \param gw The gui window to start selection in.
*/
- void (*start_selection)(struct gui_window *g);
+ void (*start_selection)(struct gui_window *gw);
};
#endif
--
NetSurf Browser
_______________________________________________
netsurf-commits mailing list
[email protected]
http://listmaster.pepperfish.net/cgi-bin/mailman/listinfo/netsurf-commits-netsurf-browser.org
