More doxygen improvements

1 files changed, 149 insertions, 116 deletions

diff --git a/src/gwin/gwin_tabset.h b/src/gwin/gwin_tabset.h
index f1d98adb..7d970c5d 100644
--- a/src/gwin/gwin_tabset.h
+++ b/src/gwin/gwin_tabset.h
@@ -62,140 +62,173 @@ typedef struct GTabsetObject {
 extern "C" {
 #endif
 
-	/**
-	 * @brief				Create a tabset widget
-	 *
-	 * @details				This widget provides a set of tabs.
-	 *
-	 * @param[in] g			The GDisplay to display this window on
-	 * @param[in] fo		The GTabsetObject structure to initialize. If this is NULL the structure is dynamically allocated.
-	 * @param[in] pInit		The initialization parameters
-	 * @param[in] flags		Some flags, see notes.
-	 *
-	 * @note				Possible flags are: GWIN_TABSET_BORDER
-	 *
-	 * @return				NULL if there is no resulting widget. A valid GHandle otherwise.
-	 *
-	 * @api
-	 */
-	GHandle gwinGTabsetCreate(GDisplay *g, GTabsetObject *fo, GWidgetInit *pInit, uint32_t flags);
-	#define gwinTabsetCreate(fo, pInit, flags)	gwinGTabsetCreate(GDISP, fo, pInit, flags);
+/**
+ * @brief				Create a tabset widget
+ *
+ * @details				This widget provides a set of tabs.
+ *
+ * @param[in] g			The GDisplay to display this window on
+ * @param[in] fo		The GTabsetObject structure to initialize. If this is NULL the structure is dynamically allocated.
+ * @param[in] pInit		The initialization parameters
+ * @param[in] flags		Some flags, see notes.
+ *
+ * @note				Possible flags are: GWIN_TABSET_BORDER
+ *
+ * @return				NULL if there is no resulting widget. A valid GHandle otherwise.
+ *
+ * @api
+ */
+GHandle gwinGTabsetCreate(GDisplay *g, GTabsetObject *fo, GWidgetInit *pInit, uint32_t flags);
+#define gwinTabsetCreate(fo, pInit, flags)	gwinGTabsetCreate(GDISP, fo, pInit, flags);
 
-	/**
-	 * @brief				Add a tab-page to the tabset
-	 * @returns				The GHandle of the tab-page container.
-	 *
-	 * @param[in] gh		The tabset handle
-	 * @param[in] title		The text to set. This must be a constant string unless useAlloc is set.
-	 * @param[in] useAlloc	If TRUE the string specified will be copied into dynamically allocated memory.
-	 *
-	 * @api
-	 */
-	GHandle gwinTabsetAddTab(GHandle gh, const char *title, bool_t useAlloc);
+/**
+ * @brief				Add a tab-page to the tabset
+ * @returns				The GHandle of the tab-page container.
+ *
+ * @param[in] gh		The tabset handle
+ * @param[in] title		The text to set. This must be a constant string unless useAlloc is set.
+ * @param[in] useAlloc	If TRUE the string specified will be copied into dynamically allocated memory.
+ *
+ * @api
+ */
+GHandle gwinTabsetAddTab(GHandle gh, const char *title, bool_t useAlloc);
 
-	/**
-	 * @brief   			Delete a tab-page.
-	 * @details				Any widgets on the page will also be destroyed
-	 *
-	 * @param[in] gh		The tab-page handle
-	 *
-	 * @note				The index position of all tabs after this tab in the tabset are automatically renumbered.
-	 *
-	 * @api
-	 */
-	#define gwinTabsetDeleteTab(gh)	gwinDestroy(gh)
+/**
+ * @brief   			Delete a tab-page.
+ * @details				Any widgets on the page will also be destroyed
+ *
+ * @param[in] gh		The tab-page handle
+ *
+ * @note				The index position of all tabs after this tab in the tabset are automatically renumbered.
+ *
+ * @api
+ */
+#define gwinTabsetDeleteTab(gh)	gwinDestroy(gh)
 
-	/**
-	 * @brief				Count the number of tabs in the tabset
-	 * @returns				The number of tabs or zero if none exist.
-	 *
-	 * @param[in] gh		The tabset handle
-	 *
-	 * @api
-	 */
-	int gwinTabsetCountTabs(GHandle gh);
+/**
+ * @brief				Count the number of tabs in the tabset
+ * @returns				The number of tabs or zero if none exist.
+ *
+ * @param[in] gh		The tabset handle
+ *
+ * @api
+ */
+int gwinTabsetCountTabs(GHandle gh);
 
-	/**
-	 * @brief				Get the GHandle of a tab based on its position
-	 * @returns				The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
-	 *
-	 * @param[in] gh		The tabset handle
-	 * @param[in] index		The tab-page handle to return (0 to number of pages - 1)
-	 *
-	 * @api
-	 */
-	GHandle gwinTabsetGetTabByIndex(GHandle gh, int index);
+/**
+ * @brief				Get the GHandle of a tab based on its position
+ * @returns				The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
+ *
+ * @param[in] gh		The tabset handle
+ * @param[in] index		The tab-page handle to return (0 to number of pages - 1)
+ *
+ * @api
+ */
+GHandle gwinTabsetGetTabByIndex(GHandle gh, int index);
 
-	/**
-	 * @brief				Get the GHandle of a tab based on its title
-	 * @returns				The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
-	 *
-	 * @param[in] gh		The tabset handle
-	 * @param[in] title		The title to search for
-	 *
-	 * @api
-	 */
-	GHandle gwinTabsetGetTabByTitle(GHandle gh, const char *title);
+/**
+ * @brief				Get the GHandle of a tab based on its title
+ * @returns				The GHandle of the tab-page container or NULL if that tab-page doesn't exist.
+ *
+ * @param[in] gh		The tabset handle
+ * @param[in] title		The title to search for
+ *
+ * @api
+ */
+GHandle gwinTabsetGetTabByTitle(GHandle gh, const char *title);
 
-	/**
-	 * @brief   Set the title of a tab-page.
-	 *
-	 * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
-	 * @param[in] title		The text to set. This must be a constant string unless useAlloc is set.
-	 * @param[in] useAlloc	If TRUE the string specified will be copied into dynamically allocated memory.
-	 *
-	 * @note				This function should be used to change the text associated with a tab-page
-	 * 						rather than @p gwinSetText().
-	 *
-	 * @api
-	 */
-	void gwinTabsetSetTitle(GHandle gh, const char *title, bool_t useAlloc);
+/**
+ * @brief   Set the title of a tab-page.
+ *
+ * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
+ * @param[in] title		The text to set. This must be a constant string unless useAlloc is set.
+ * @param[in] useAlloc	If TRUE the string specified will be copied into dynamically allocated memory.
+ *
+ * @note				This function should be used to change the text associated with a tab-page
+ * 						rather than @p gwinSetText().
+ *
+ * @api
+ */
+void gwinTabsetSetTitle(GHandle gh, const char *title, bool_t useAlloc);
 
-	/**
-	 * @brief   Get the title of a tab-page.
-	 * @return	The title of the tab.
-	 *
-	 * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
-	 *
-	 * @api
-	 */
-	#define gwinTabsetGetTitle(gh)			gwinGetText(gh)
+/**
+ * @brief   Get the title of a tab-page.
+ * @return	The title of the tab.
+ *
+ * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
+ *
+ * @api
+ */
+#define gwinTabsetGetTitle(gh)			gwinGetText(gh)
 
-	/**
-	 * @brief   Set the active tab in a tabset.
-	 *
-	 * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
-	 *
-	 * @api
-	 */
-	void gwinTabsetSetTab(GHandle gh);
+/**
+ * @brief   Set the active tab in a tabset.
+ *
+ * @param[in] gh		The tab-page handle (NB: Use the page handle NOT the tabset handle)
+ *
+ * @api
+ */
+void gwinTabsetSetTab(GHandle gh);
+
+/**
+ * @defgroup Renderings_Tabset Renderings
+ *
+ * @brief				Built-in rendering functions for the tabset widget.
+ *
+ * @details				These function may be passed to @p gwinSetCustomDraw() to get different tabset drawing styles.
+ *
+ * @note				In your custom tabset drawing function you may optionally call these
+ * 						standard functions and then draw your extra details on top.
+ * @note				These custom drawing routines don't have to worry about setting clipping as the framework
+ * 						sets clipping to the object window prior to calling these routines.
+ *
+ * @{
+ */
+
+/**
+ * @brief				The default rendering function for the tabset widget.
+ *
+ * @details				Fills the client area with the background color.
+ *
+ * @param[in] gw		The widget object (must be a container object).
+ * @param[in] param		A parameter passed in from the user. Ignored by this function.
+ *
+ * @api
+ */
+void gwinTabsetDraw_Std(GWidgetObject *gw, void *param);
 
+/**
+ * @brief				Renders the tabset but leaves the client area transparent.
+ *
+ * @details				Will not fill the client area at all.
+ *
+ * @param[in] gw		The widget object (must be a container object).
+ * @param[in] param		A parameter passed in from the user. Ignored by this function.
+ *
+ * @api
+ */
+void gwinTabsetDraw_Transparent(GWidgetObject *gw, void *param);
+
+#if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
 	/**
-	 * @brief				The custom draw routines for a frame window
-	 * @details				These function may be passed to @p gwinSetCustomDraw() to get different frame drawing styles
+	 * @brief				Renders the tabset and uses the specified image for the client area.
 	 *
-	 * @param[in] gw		The widget object (in this case a frame)
-	 * @param[in] param		A parameter passed in from the user
+	 * @details				The image will be tiled throghout the client area. Therefore, to archive the best looking result the
+	 *						supplied image needs to be of the same size as the client area size of the tabset widget (inner size).
 	 *
-	 * @note				In your own custom drawing function you may optionally call these
-	 * 						standard functions and then draw your extra details on top.
+	 * @param[in] gw		The widget object (must be a tabset object).
+	 * @param[in] param		A parameter passed in from the user. Must be an image handle. See note below.
 	 *
-	 * @note				gwinTabsetDraw_Std() will fill the client area with the background color.<br/>
-	 * 						gwinTabsetDraw_Transparent() will not fill the client area at all.<br/>
-	 * 						gwinTabsetDraw_Image() will tile the image throughout the client area.<br/>
-	 * 						All these drawing functions draw the frame itself the same way.
+	 * @note				The image must be already opened before calling  @p gwinSetCustomDraw(). The handle is passed as the parameter
+	 *						to this function.
 	 *
-	 * @note				The standard functions below ignore the param parameter except for @p gwinTabsetDraw_Image().
-	 * @note				The image custom draw function  @p gwinTabsetDraw_Image() uses param to pass in the gdispImage pointer.
-	 * 						The image must be already opened before calling  @p gwinSetCustomDraw().
+	 * @pre					GDISP_NEED_IMAGE must be set to TRUE
 	 *
 	 * @api
-	 * @{
 	 */
-	void gwinTabsetDraw_Std(GWidgetObject *gw, void *param);
-	void gwinTabsetDraw_Transparent(GWidgetObject *gw, void *param);
 	void gwinTabsetDraw_Image(GWidgetObject *gw, void *param);
-	/** @} */
+#endif /* GDISP_NEED_IMAGE */
+/** @} */
 
 #ifdef __cplusplus
 }