summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2016-10-26 12:58:51 (GMT)
committer Vincent Sanders <vince@kyllikki.org>2016-10-26 12:58:51 (GMT)
commit2adf0a9c44a0ebb0dc9060aa5f3e27f65e21875d (patch)
tree467d8ad210907f1f7acacaa4088bfb2a20c1b3e3
parentaf5f4a570453c2d0b1dcfd06044ad3abb3bd4325 (diff)
downloadnetsurf-2adf0a9c44a0ebb0dc9060aa5f3e27f65e21875d.tar.gz
netsurf-2adf0a9c44a0ebb0dc9060aa5f3e27f65e21875d.tar.bz2
clean up documentation of GTK core window interfaces
-rw-r--r--frontends/gtk/cookies.c8
-rw-r--r--frontends/gtk/corewindow.c131
-rw-r--r--frontends/gtk/corewindow.h6
-rw-r--r--frontends/gtk/ssl_cert.c6
4 files changed, 126 insertions, 25 deletions
diff --git a/frontends/gtk/cookies.c b/frontends/gtk/cookies.c
index d0fae97..dc77e1c 100644
--- a/frontends/gtk/cookies.c
+++ b/frontends/gtk/cookies.c
@@ -183,7 +183,7 @@ static void nsgtk_cookies_init_menu(struct nsgtk_cookie_window *ncwin)
* \param mouse_state netsurf mouse state on event
* \param x location of event
* \param y location of event
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_cookies_mouse(struct nsgtk_corewindow *nsgtk_cw,
@@ -200,7 +200,7 @@ nsgtk_cookies_mouse(struct nsgtk_corewindow *nsgtk_cw,
*
* \param nsgtk_cw The nsgtk core window structure.
* \param nskey The netsurf key code
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_cookies_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
@@ -216,7 +216,7 @@ nsgtk_cookies_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
*
* \param nsgtk_cw The nsgtk core window structure.
* \param r The rectangle of the window that needs updating.
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_cookies_draw(struct nsgtk_corewindow *nsgtk_cw, struct rect *r)
@@ -235,7 +235,7 @@ nsgtk_cookies_draw(struct nsgtk_corewindow *nsgtk_cw, struct rect *r)
/**
* Creates the window for the cookies tree.
*
- * \return NSERROR_OK on success else appropriate error code on faliure.
+ * \return NSERROR_OK on success else appropriate error code on failure.
*/
static nserror nsgtk_cookies_init(void)
{
diff --git a/frontends/gtk/corewindow.c b/frontends/gtk/corewindow.c
index e60f2c4..a992601 100644
--- a/frontends/gtk/corewindow.c
+++ b/frontends/gtk/corewindow.c
@@ -23,7 +23,6 @@
* Provides interface for core renderers to the gtk toolkit drawable area.
* \todo should the interface really be called coredrawable?
*
-
* This module is an object that must be encapsulated. Client users
* should embed a struct nsgtk_corewindow at the beginning of their
* context for this display surface, fill in relevant data and then
@@ -54,6 +53,9 @@
/**
* Convert GDK mouse event to netsurf mouse state
+ *
+ * \param event The GDK mouse event to convert.
+ * \return The netsurf mouse state.
*/
static browser_mouse_state nsgtk_cw_gdkbutton_to_nsstate(GdkEventButton *event)
{
@@ -92,12 +94,16 @@ static browser_mouse_state nsgtk_cw_gdkbutton_to_nsstate(GdkEventButton *event)
return ms;
}
+
/**
* gtk event on mouse button press.
*
- * \param widget The gtk widget the event occoured for.
- * \param event The event that occoured.
- * \param g The context pointer passed when teh event was registered.
+ * Service gtk event for a mouse button transition to pressed from
+ * released state.
+ *
+ * \param widget The gtk widget the event occurred for.
+ * \param event The event that occurred.
+ * \param g The context pointer passed when the event was registered.
*/
static gboolean
nsgtk_cw_button_press_event(GtkWidget *widget,
@@ -122,6 +128,17 @@ nsgtk_cw_button_press_event(GtkWidget *widget,
return TRUE;
}
+
+/**
+ * gtk event on mouse button release.
+ *
+ * Service gtk event for a mouse button transition from pressed to
+ * released state.
+ *
+ * \param widget The gtk widget the event occurred for.
+ * \param event The event that occurred.
+ * \param g The context pointer passed when the event was registered.
+ */
static gboolean
nsgtk_cw_button_release_event(GtkWidget *widget,
GdkEventButton *event,
@@ -185,9 +202,20 @@ nsgtk_cw_button_release_event(GtkWidget *widget,
return TRUE;
}
+
+/**
+ * gtk event on mouse movement.
+ *
+ * Service gtk motion-notify-event for mouse movement above a widget.
+ *
+ * \param widget The gtk widget the event occurred for.
+ * \param event The motion event that occurred.
+ * \param g The context pointer passed when the event was registered.
+ */
static gboolean
nsgtk_cw_motion_notify_event(GtkWidget *widget,
- GdkEventMotion *event, gpointer g)
+ GdkEventMotion *event,
+ gpointer g)
{
struct nsgtk_corewindow *nsgtk_cw = (struct nsgtk_corewindow *)g;
struct nsgtk_corewindow_mouse *mouse = &nsgtk_cw->mouse_state;
@@ -265,11 +293,11 @@ nsgtk_cw_motion_notify_event(GtkWidget *widget,
/**
- * Deal with keypress events not handled but input method or callback
+ * Deal with keypress events not handled buy input method or callback
*
* \param nsgtk_cw nsgtk core window key event happened in.
* \param nskey The netsurf keycode of the event.
- * \return NSERROR_OK on sucess otherwise an error code.
+ * \return NSERROR_OK on success otherwise an error code.
*/
static nserror nsgtk_cw_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
{
@@ -359,9 +387,12 @@ static nserror nsgtk_cw_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
/**
* gtk event on key press.
*
- * \param widget The gtk widget the event occoured for.
- * \param event The event that occoured.
- * \param g The context pointer passed when teh event was registered.
+ * Service gtk key-press-event for key transition on a widget from
+ * released to pressed.
+ *
+ * \param widget The gtk widget the event occurred for.
+ * \param event The event that occurred.
+ * \param g The context pointer passed when the event was registered.
*/
static gboolean
nsgtk_cw_keypress_event(GtkWidget *widget, GdkEventKey *event, gpointer g)
@@ -397,6 +428,16 @@ nsgtk_cw_keypress_event(GtkWidget *widget, GdkEventKey *event, gpointer g)
}
+/**
+ * gtk event on key release.
+ *
+ * Service gtk key-release-event for key transition on a widget from
+ * pressed to released.
+ *
+ * \param widget The gtk widget the event occurred for.
+ * \param event The event that occurred.
+ * \param g The context pointer passed when the event was registered.
+ */
static gboolean
nsgtk_cw_keyrelease_event(GtkWidget *widget, GdkEventKey *event, gpointer g)
{
@@ -406,6 +447,15 @@ nsgtk_cw_keyrelease_event(GtkWidget *widget, GdkEventKey *event, gpointer g)
}
+/**
+ * gtk event handler for input method commit.
+ *
+ * Service gtk commit for input method commit action.
+ *
+ * \param ctx The gtk input method context the event occurred for.
+ * \param str The resulting string from the input method.
+ * \param g The context pointer passed when the event was registered.
+ */
static void
nsgtk_cw_input_method_commit(GtkIMContext *ctx, const gchar *str, gpointer g)
{
@@ -428,7 +478,15 @@ nsgtk_cw_input_method_commit(GtkIMContext *ctx, const gchar *str, gpointer g)
#if GTK_CHECK_VERSION(3,0,0)
-/* signal handler for core window redraw */
+
+/**
+ * handler for gtk draw event on a nsgtk core window for GTK 3
+ *
+ * \param widget The GTK widget to redraw.
+ * \param cr The cairo drawing context of the widget
+ * \param data The context pointer passed when the event was registered.
+ * \return FALSE indicating no error.
+ */
static gboolean
nsgtk_cw_draw_event(GtkWidget *widget, cairo_t *cr, gpointer data)
{
@@ -458,7 +516,15 @@ nsgtk_cw_draw_event(GtkWidget *widget, cairo_t *cr, gpointer data)
#else
-/* signal handler for core window redraw */
+
+/**
+ * handler for gtk draw event on a nsgtk core window for GTK 2
+ *
+ * \param widget The GTK widget to redraw.
+ * \param event The GDK expose event
+ * \param g The context pointer passed when the event was registered.
+ * \return FALSE indicating no error.
+ */
static gboolean
nsgtk_cw_draw_event(GtkWidget *widget,
GdkEventExpose *event,
@@ -485,8 +551,12 @@ nsgtk_cw_draw_event(GtkWidget *widget,
#endif
+
/**
- * callback from core to request a redraw
+ * redraw window core window callback
+ *
+ * \param cw core window handle.
+ * \param r rectangle that needs redrawing.
*/
static void
nsgtk_cw_redraw_request(struct core_window *cw, const struct rect *r)
@@ -499,6 +569,13 @@ nsgtk_cw_redraw_request(struct core_window *cw, const struct rect *r)
}
+/**
+ * update window size core window callback
+ *
+ * \param cw core window handle.
+ * \param width New widget width.
+ * \param height New widget height.
+ */
static void
nsgtk_cw_update_size(struct core_window *cw, int width, int height)
{
@@ -509,6 +586,12 @@ nsgtk_cw_update_size(struct core_window *cw, int width, int height)
}
+/**
+ * scroll window core window callback
+ *
+ * \param cw core window handle.
+ * \param r rectangle that needs scrolling.
+ */
static void
nsgtk_cw_scroll_visible(struct core_window *cw, const struct rect *r)
{
@@ -536,6 +619,13 @@ nsgtk_cw_scroll_visible(struct core_window *cw, const struct rect *r)
}
+/**
+ * get window size core window callback
+ *
+ * \param cw core window handle.
+ * \param[out] width The width value to update
+ * \param[out] height The height value to update
+ */
static void
nsgtk_cw_get_window_dimensions(struct core_window *cw, int *width, int *height)
{
@@ -554,9 +644,16 @@ nsgtk_cw_get_window_dimensions(struct core_window *cw, int *width, int *height)
vadj = gtk_scrolled_window_get_vadjustment(nsgtk_cw->scrolled);
g_object_get(vadj, "page-size", &page, NULL);
*height = page;
- }}
+ }
+}
+/**
+ * update window drag status core window callback
+ *
+ * \param cw core window handle.
+ * \param ds The new drag status.
+ */
static void
nsgtk_cw_drag_status(struct core_window *cw, core_window_drag_status ds)
{
@@ -565,7 +662,10 @@ nsgtk_cw_drag_status(struct core_window *cw, core_window_drag_status ds)
}
-struct core_window_callback_table nsgtk_cw_cb_table = {
+/**
+ * core window callback table for nsgtk
+ */
+static struct core_window_callback_table nsgtk_cw_cb_table = {
.redraw_request = nsgtk_cw_redraw_request,
.update_size = nsgtk_cw_update_size,
.scroll_visible = nsgtk_cw_scroll_visible,
@@ -626,6 +726,7 @@ nserror nsgtk_corewindow_init(struct nsgtk_corewindow *nsgtk_cw)
return NSERROR_OK;
}
+/* exported interface documented in gtk/corewindow.h */
nserror nsgtk_corewindow_fini(struct nsgtk_corewindow *nsgtk_cw)
{
g_object_unref(nsgtk_cw->input_method);
diff --git a/frontends/gtk/corewindow.h b/frontends/gtk/corewindow.h
index cfb865e..90bfd61 100644
--- a/frontends/gtk/corewindow.h
+++ b/frontends/gtk/corewindow.h
@@ -58,7 +58,7 @@ struct nsgtk_corewindow {
*
* \param nsgtk_cw The nsgtk core window structure.
* \param r The rectangle of the window that needs updating.
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
nserror (*draw)(struct nsgtk_corewindow *nsgtk_cw, struct rect *r);
@@ -69,7 +69,7 @@ struct nsgtk_corewindow {
* \param nskey The netsurf key code.
* \return NSERROR_OK if key processed,
* NSERROR_NOT_IMPLEMENTED if key not processed
- * otherwise apropriate error code
+ * otherwise appropriate error code
*/
nserror (*key)(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey);
@@ -80,7 +80,7 @@ struct nsgtk_corewindow {
* \param mouse_state mouse state
* \param x location of event
* \param y location of event
- * \return NSERROR_OK on sucess otherwise apropriate error code.
+ * \return NSERROR_OK on success otherwise appropriate error code.
*/
nserror (*mouse)(struct nsgtk_corewindow *nsgtk_cw, browser_mouse_state mouse_state, int x, int y);
};
diff --git a/frontends/gtk/ssl_cert.c b/frontends/gtk/ssl_cert.c
index 8270b15..5388f01 100644
--- a/frontends/gtk/ssl_cert.c
+++ b/frontends/gtk/ssl_cert.c
@@ -104,7 +104,7 @@ nsgtk_crtvrfy_delete_event(GtkWidget *w, GdkEvent *event, gpointer data)
* \param mouse_state netsurf mouse state on event
* \param x location of event
* \param y location of event
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_crtvrfy_mouse(struct nsgtk_corewindow *nsgtk_cw,
@@ -125,7 +125,7 @@ nsgtk_crtvrfy_mouse(struct nsgtk_corewindow *nsgtk_cw,
*
* \param nsgtk_cw The nsgtk core window structure.
* \param nskey The netsurf key code
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_crtvrfy_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
@@ -146,7 +146,7 @@ nsgtk_crtvrfy_key(struct nsgtk_corewindow *nsgtk_cw, uint32_t nskey)
*
* \param nsgtk_cw The nsgtk core window structure.
* \param r The rectangle of the window that needs updating.
- * \return NSERROR_OK on success otherwise apropriate error code
+ * \return NSERROR_OK on success otherwise appropriate error code
*/
static nserror
nsgtk_crtvrfy_draw(struct nsgtk_corewindow *nsgtk_cw, struct rect *r)