Doxygen (documenting each built-in rendering function for widgets)

1 files changed, 126 insertions, 96 deletions

diff --git a/src/gwin/gwin_container.h b/src/gwin/gwin_container.h
index 0e75cfb9..5ae23cea 100644
--- a/src/gwin/gwin_container.h
+++ b/src/gwin/gwin_container.h
@@ -48,102 +48,132 @@ typedef GWidgetObject GContainerObject;
 extern "C" {
 #endif
 
-	/**
-	 * @brief	Get the first child window
-	 *
-	 * @return	The first child or NULL if are no children windows
-	 *
-	 * @param[in] gh	The parent container or NULL to get the first top level window
-	 *
-	 * @api
-	 */
-	GHandle gwinGetFirstChild(GHandle gh);
-
-	/**
-	 * @brief	Get the next child window in the z-order
-	 *
-	 * @return	The next window or NULL if no more children
-	 *
-	 * @param[in] gh		The window to obtain the next sibling of.
-	 *
-	 * @note	This returns the next window under the current parent window.
-	 * 			Unlike @p gwinGetNextWindow() it will only return windows that
-	 * 			have the same parent as the supplied window.
-	 *
-	 * @api
-	 */
-	GHandle gwinGetSibling(GHandle gh);
-
-	/**
-	 * @brief	Get the inner width of a container window
-	 *
-	 * @return	The inner width of a container window or zero if this is not a container
-	 *
-	 * @param[in] gh		The window
-	 *
-	 * @api
-	 */
-	coord_t gwinGetInnerWidth(GHandle gh);
-
-	/**
-	 * @brief	Get the inner height of a container window
-	 *
-	 * @return	The inner height of a container window or zero if this is not a container
-	 *
-	 * @param[in] gh		The window
-	 *
-	 * @api
-	 */
-	coord_t gwinGetInnerHeight(GHandle gh);
-
-
-	/**
-	 * @brief	 Flags for gwinContainerCreate()
-	 * @{
-	 */
-	#define GWIN_CONTAINER_BORDER		0x00000001
-	/** @} */
-
-	/**
-	 * @brief   Create a simple container.
-	 * @return  NULL if there is no resultant drawing area, otherwise a window handle.
-	 *
-	 * @param[in] g			The GDisplay to display this window on
-	 * @param[in] gw		The GContainerObject structure to initialise. If this is NULL the structure is dynamically allocated.
-	 * @param[in] pInit		The initialisation parameters
-	 * @param[in] flags		Some flags, see notes
-	 *
-	 * @api
-	 */
-	GHandle gwinGContainerCreate(GDisplay *g, GContainerObject *gw, const GWidgetInit *pInit, uint32_t flags);
-	#define gwinContainerCreate(gc, pInit, flags)			gwinGContainerCreate(GDISP, gc, pInit, flags)
-
-	/**
-	 * @brief				The custom draw routines for a simple container
-	 * @details				These function may be passed to @p gwinSetCustomDraw() to get different frame drawing styles
-	 *
-	 * @param[in] gw		The widget object (in this case a frame)
-	 * @param[in] param		A parameter passed in from the user
-	 *
-	 * @note				In your own custom drawing function you may optionally call these
-	 * 						standard functions and then draw your extra details on top.
-	 *
-	 * @note				gwinContainerDraw_Std() will fill the client area with the background color.<br/>
-	 * 						gwinContainerDraw_Transparent() will not fill the client area at all.<br/>
-	 * 						gwinContainerDraw_Image() will tile the image throughout the client area.<br/>
-	 * 						All these drawing functions draw the frame itself the same way.
-	 *
-	 * @note				The standard functions below ignore the param parameter except for @p gwinContainerDraw_Image().
-	 * @note				The image custom draw function  @p gwinContainerDraw_Image() uses param to pass in the gdispImage pointer.
-	 * 						The image must be already opened before calling  @p gwinSetCustomDraw().
-	 *
-	 * @api
-	 * @{
-	 */
-	void gwinContainerDraw_Std(GWidgetObject *gw, void *param);
-	void gwinContainerDraw_Transparent(GWidgetObject *gw, void *param);
-	void gwinContainerDraw_Image(GWidgetObject *gw, void *param);
-	/** @} */
+/**
+ * @brief	Get the first child window
+ *
+ * @return	The first child or NULL if are no children windows
+ *
+ * @param[in] gh	The parent container or NULL to get the first top level window
+ *
+ * @api
+ */
+GHandle gwinGetFirstChild(GHandle gh);
+
+/**
+ * @brief	Get the next child window in the z-order
+ *
+ * @return	The next window or NULL if no more children
+ *
+ * @param[in] gh		The window to obtain the next sibling of.
+ *
+ * @note	This returns the next window under the current parent window.
+ * 			Unlike @p gwinGetNextWindow() it will only return windows that
+ * 			have the same parent as the supplied window.
+ *
+ * @api
+ */
+GHandle gwinGetSibling(GHandle gh);
+
+/**
+ * @brief	Get the inner width of a container window
+ *
+ * @return	The inner width of a container window or zero if this is not a container
+ *
+ * @param[in] gh		The window
+ *
+ * @api
+ */
+coord_t gwinGetInnerWidth(GHandle gh);
+
+/**
+ * @brief	Get the inner height of a container window
+ *
+ * @return	The inner height of a container window or zero if this is not a container
+ *
+ * @param[in] gh		The window
+ *
+ * @api
+ */
+coord_t gwinGetInnerHeight(GHandle gh);
+
+
+/**
+ * @brief	 Flags for gwinContainerCreate()
+ * @{
+ */
+#define GWIN_CONTAINER_BORDER		0x00000001
+/** @} */
+
+/**
+ * @brief   Create a simple container.
+ * @return  NULL if there is no resultant drawing area, otherwise a window handle.
+ *
+ * @param[in] g			The GDisplay to display this window on
+ * @param[in] gw		The GContainerObject structure to initialise. If this is NULL the structure is dynamically allocated.
+ * @param[in] pInit		The initialisation parameters
+ * @param[in] flags		Some flags, see notes
+ *
+ * @api
+ */
+GHandle gwinGContainerCreate(GDisplay *g, GContainerObject *gw, const GWidgetInit *pInit, uint32_t flags);
+#define gwinContainerCreate(gc, pInit, flags)			gwinGContainerCreate(GDISP, gc, pInit, flags)
+
+
+/**
+ * @defgroup Renderings_Container Container rendering functions
+ *
+ * @brief				Built-in rendering functions for the container widget.
+ *
+ * @details				These function may be passed to @p gwinSetCustomDraw() to get different container drawing styles.
+ *
+ * @note				In your custom container 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 container 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 gwinContainerDraw_Std(GWidgetObject *gw, void *param);
+
+/**
+ * @brief				Renders the container 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 gwinContainerDraw_Transparent(GWidgetObject *gw, void *param);
+
+/**
+ * @brief				Renders the container and uses the specified image for the client area.
+ *
+ * @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 container widget (inner size).
+ *
+ * @param[in] gw		The widget object (must be a container object).
+ * @param[in] param		A parameter passed in from the user. Must be an image handle. See note below.
+ *
+ * @note				The image must be already opened before calling  @p gwinSetCustomDraw(). The handle is passed as the parameter
+ *						to this function.
+ *
+ * @api
+ */
+void gwinContainerDraw_Image(GWidgetObject *gw, void *param);
+/** @} */
 
 #ifdef __cplusplus
 }