From 1180d1932480234619163d57a4dc2629c9309f38 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Sun, 19 Oct 2014 19:12:55 +0100 Subject: improve documentation in headers --- desktop/browser.h | 153 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 14 deletions(-) (limited to 'desktop/browser.h') diff --git a/desktop/browser.h b/desktop/browser.h index 935e2425c..e5444164e 100644 --- a/desktop/browser.h +++ b/desktop/browser.h @@ -33,7 +33,6 @@ #include "desktop/frame_types.h" #include "desktop/mouse.h" - struct browser_window; struct hlcache_handle; struct gui_window; @@ -116,7 +115,7 @@ enum browser_window_nav_flags { * * \param flags Flags to control operation * \param url URL to fetch in the new window or NULL for blank - * \param referer The referring uri or NULL if none + * \param referrer The referring uri or NULL if none * \param existing The an existing bw or NULL, required for some flags. * \param bw Updated to created browser window or untouched on error. * \return NSERROR_OK, or appropriate error otherwise. @@ -173,7 +172,7 @@ nserror browser_window_navigate_up(struct browser_window *bw, bool new_window); * \param bw browser window * \return pointer to nsurl. Doesn't create a ref for caller. * - * Note: guaranteed to return a valid nsurl ptr, never returns NULL. + * \note guaranteed to return a valid nsurl ptr, never returns NULL. */ struct nsurl* browser_window_get_url(struct browser_window *bw); @@ -219,15 +218,61 @@ bool browser_window_has_content(struct browser_window *bw); */ struct hlcache_handle *browser_window_get_content(struct browser_window *bw); -void browser_window_get_dimensions(struct browser_window *bw, - int *width, int *height, bool scaled); +/** + * Set the dimensions of the area a browser window occupies + * + * \param bw The browser window to set dimensions of + * \param width Width in pixels + * \param height Height in pixels + */ void browser_window_set_dimensions(struct browser_window *bw, int width, int height); + +/** + * Redraw browser window, set extent to content, and update title. + * + * \param bw browser_window + * \param scroll_to_top move view to top of page + */ void browser_window_update(struct browser_window *bw, bool scroll_to_top); + +/** + * update an area of a browser window. + * + * \param bw The browser window to update. + * \param rect The area to redraw + */ void browser_window_update_box(struct browser_window *bw, struct rect *rect); + +/** + * Stop all fetching activity in a browser window. + * + * \param bw The browser window to stop activity in. + */ void browser_window_stop(struct browser_window *bw); + +/** + * Reload the page in a browser window. + * + * \param bw browser window + * \param all whether to reload all objects associated with the page + */ void browser_window_reload(struct browser_window *bw, bool all); + +/** + * Close and destroy a browser window. + * + * \param bw browser window + */ void browser_window_destroy(struct browser_window *bw); + +/** + * Reformat a browser window contents to a new width or height. + * + * \param bw the browser window to reformat + * \param width new width + * \param height new height + */ void browser_window_reformat(struct browser_window *bw, bool background, int width, int height); @@ -294,12 +339,43 @@ bool browser_window_drop_file_at_point(struct browser_window *bw, void browser_window_set_gadget_filename(struct browser_window *bw, struct form_control *gadget, const char *fn); +/** + * Update URL bar for a given browser window to bw's content's URL + * + * \param bw Browser window to update URL bar for. + */ void browser_window_refresh_url_bar(struct browser_window *bw); +/** + * Handle mouse clicks in a browser window. + * + * \param bw browser window + * \param mouse state of mouse buttons and modifier keys + * \param x coordinate of mouse + * \param y coordinate of mouse + */ void browser_window_mouse_click(struct browser_window *bw, browser_mouse_state mouse, int x, int y); + +/** + * Handle non-click mouse action in a browser window. (drag ends, movements) + * + * \param bw browser window + * \param mouse state of mouse buttons and modifier keys + * \param x coordinate of mouse + * \param y coordinate of mouse + */ void browser_window_mouse_track(struct browser_window *bw, browser_mouse_state mouse, int x, int y); + +/** + * Locate a browser window in the specified stack according. + * + * \param bw the browser_window to search all relatives of + * \param target the target to locate + * \param mouse The current mouse state + * \return The browser window the mouse is in + */ struct browser_window *browser_window_find_target( struct browser_window *bw, const char *target, browser_mouse_state mouse); @@ -322,26 +398,75 @@ nserror browser_window_schedule_reformat(struct browser_window *bw); void browser_select_menu_callback(void *client_data, int x, int y, int width, int height); +/** + * Redraw a rectangular region of a browser window + * + * \param bw browser window to be redrawn + * \param x x co-ord of top-left + * \param y y co-ord of top-left + * \param width width of rectangle + * \param height height of rectangle + */ void browser_window_redraw_rect(struct browser_window *bw, int x, int y, int width, int height); +/** + * Change the status bar of a browser window. + * + * \param bw browser window + * \param text new status text (copied) + */ void browser_window_set_status(struct browser_window *bw, const char *text); + +/** + * Change the shape of the mouse pointer + * + * \param bw Browser window to set shape in + * \param shape The pointer shape to use + */ void browser_window_set_pointer(struct browser_window *bw, browser_pointer_shape shape); + +/** + * Start drag scrolling the contents of the browser window + * + * \param bw browser window + * \param x x ordinate of initial mouse position + * \param y y ordinate + */ void browser_window_page_drag_start(struct browser_window *bw, int x, int y); +/** + * Check availability of Back action for a given browser window + * + * \param bw browser window + * \return true if Back action is available + */ bool browser_window_back_available(struct browser_window *bw); -bool browser_window_forward_available(struct browser_window *bw); -bool browser_window_reload_available(struct browser_window *bw); -bool browser_window_stop_available(struct browser_window *bw); +/** + * Check availability of Forward action for a given browser window + * + * \param bw browser window + * \return true if Forward action is available + */ +bool browser_window_forward_available(struct browser_window *bw); -/* In desktop/textinput.c */ -void browser_window_place_caret(struct browser_window *bw, int x, int y, - int height, const struct rect *clip); -void browser_window_remove_caret(struct browser_window *bw, bool only_hide); -bool browser_window_key_press(struct browser_window *bw, uint32_t key); +/** + * Check availability of Reload action for a given browser window + * + * \param bw browser window + * \return true if Reload action is available + */ +bool browser_window_reload_available(struct browser_window *bw); +/** + * Check availability of Stop action for a given browser window + * + * \param bw browser window + * \return true if Stop action is available + */ +bool browser_window_stop_available(struct browser_window *bw); /** * Redraw an area of a window @@ -413,7 +538,7 @@ void browser_window_scroll_visible(struct browser_window *bw, * \param x The x scroll offset to set * \param y The y scroll offset to set * - * TODO -- Do we really need this and browser_window_scroll_visible? + * \todo Do we really need this and browser_window_scroll_visible? * Ditto for gui_window_* variants. */ void browser_window_set_scroll(struct browser_window *bw, int x, int y); -- cgit v1.2.3