diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/gdisp/gdisp.h | 5 | ||||
| -rw-r--r-- | include/gdisp/lld/gdisp_lld_msgs.h | 2 | ||||
| -rw-r--r-- | include/gevent/gevent.h | 144 | ||||
| -rw-r--r-- | include/ginput/dial.h | 71 | ||||
| -rw-r--r-- | include/ginput/ginput.h | 6 | ||||
| -rw-r--r-- | include/ginput/keyboard.h | 24 | ||||
| -rw-r--r-- | include/ginput/lld/mouse.h | 5 | ||||
| -rw-r--r-- | include/ginput/lld/toggle.h | 5 | ||||
| -rw-r--r-- | include/ginput/mouse.h | 67 | ||||
| -rw-r--r-- | include/ginput/toggle.h | 40 | ||||
| -rw-r--r-- | include/gtimer/gtimer.h | 113 | ||||
| -rw-r--r-- | include/gwin/button.h | 11 | ||||
| -rw-r--r-- | include/gwin/console.h | 11 | ||||
| -rw-r--r-- | include/gwin/graph.h | 8 | ||||
| -rw-r--r-- | include/gwin/gwin.h | 13 | ||||
| -rw-r--r-- | include/gwin/options.h | 6 |
16 files changed, 430 insertions, 101 deletions
diff --git a/include/gdisp/gdisp.h b/include/gdisp/gdisp.h index 117f865a..f8d5745f 100644 --- a/include/gdisp/gdisp.h +++ b/include/gdisp/gdisp.h @@ -23,6 +23,11 @@ * @brief GDISP Graphic Driver subsystem header file.
*
* @addtogroup GDISP
+ *
+ * @details The GDISP module provides high level abstraction to interface pixel oriented graphic displays.
+ *
+ * @pre GFX_USE_GDISP must be set to TRUE in gfxconf.h
+ *
* @{
*/
diff --git a/include/gdisp/lld/gdisp_lld_msgs.h b/include/gdisp/lld/gdisp_lld_msgs.h index 31a82237..6fe78567 100644 --- a/include/gdisp/lld/gdisp_lld_msgs.h +++ b/include/gdisp/lld/gdisp_lld_msgs.h @@ -19,7 +19,7 @@ */
/**
- * @file include/lld/gdisp/gdisp_lld_msgs.h
+ * @file include/gdisp/lld/gdisp_lld_msgs.h
* @brief GDISP Graphic Driver subsystem low level driver message structures.
*
* @addtogroup GDISP
diff --git a/include/gevent/gevent.h b/include/gevent/gevent.h index a68a5fc0..67a6185a 100644 --- a/include/gevent/gevent.h +++ b/include/gevent/gevent.h @@ -22,6 +22,12 @@ * @brief GEVENT GFX User Event subsystem header file.
*
* @addtogroup GEVENT
+ *
+ * @details GEVENT provides a simple to use but yet powerful event
+ * system.
+ *
+ * @pre GFX_USE_GEVENT must be set to TRUE in your gfxconf.h
+ *
* @{
*/
#ifndef _GEVENT_H
@@ -31,13 +37,9 @@ #if GFX_USE_GEVENT || defined(__DOXYGEN__)
-/**
- * @brief Data part of a static GListener initializer.
- */
+/* Data part of a static GListener initializer */
#define _GLISTENER_DATA(name) { _SEMAPHORE_DATA(name.waitqueue, 0), _BSEMAPHORE_DATA(name.eventlock, FALSE), 0, 0, {0} }
-/**
- * @brief Static GListener initializer.
- */
+/* Static GListener initializer */
#define GLISTENER_DECL(name) GListener name = _GLISTENER_DATA(name)
/*===========================================================================*/
@@ -120,79 +122,118 @@ extern "C" { /*---------- Listener Functions --------------------------------------------*/
-/* Initialise a Listener.
+/**
+ * @brief Create a Listener
+ * @details If insufficient resources are available it will either assert or return NULL
+ * depending on the value of GEVENT_ASSERT_NO_RESOURCE.
+ *
+ * @param[in] pl A listener
*/
void geventListenerInit(GListener *pl);
-/* Attach a source to a listener.
- * Flags are interpreted by the source when generating events for each listener.
- * If this source is already assigned to the listener it will update the flags.
- * If insufficient resources are available it will either assert or return FALSE
- * depending on the value of GEVENT_ASSERT_NO_RESOURCE.
+/**
+ * @brief Attach a source to a listener
+ * @details Flags are interpreted by the source when generating events for each listener.
+ * If this source is already assigned to the listener it will update the flags.
+ * If insufficient resources are available it will either assert or return FALSE
+ * depending on the value of GEVENT_ASSERT_NO_RESOURCE.
+ *
+ * @param[in] pl The listener
+ * @param[in] gsh The source which has to be attached to the listener
+ * @param[in] flags The flags
+ *
+ * @return TRUE if succeeded, FALSE otherwise
*/
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags);
-/* Detach a source from a listener
- * If gsh is NULL detach all sources from this listener and if there is still
- * a thread waiting for events on this listener, it is sent the exit event.
+/**
+ * @brief Detach a source from a listener
+ * @details If gsh is NULL detach all sources from this listener and if there is still
+ * a thread waiting for events on this listener, it is sent the exit event.
+ *
+ * @param[in] pl The listener
+ * @param[in] gsh The source
*/
void geventDetachSource(GListener *pl, GSourceHandle gsh);
-/* Wait for an event on a listener from an assigned source.
- * The type of the event should be checked (pevent->type) and then pevent should be typecast to the
- * actual event type if it needs to be processed.
- * timeout specifies the time to wait in system ticks.
- * TIME_INFINITE means no timeout - wait forever for an event.
- * TIME_IMMEDIATE means return immediately
- * Returns NULL on timeout or if a callback function is already registered.
- * Note: The GEvent buffer is staticly allocated within the GListener so the event does not
+/**
+ * @brief Wait for an event on a listener from an assigned source.
+ * @details The type of the event should be checked (pevent->type) and then pevent should
+ * be typecast to the actual event type if it needs to be processed.
+ * timeout specifies the time to wait in system ticks.
+ * TIME_INFINITE means no timeout - wait forever for an event.
+ * TIME_IMMEDIATE means return immediately
+ * @note The GEvent buffer is staticly allocated within the GListener so the event does not
* need to be dynamicly freed however it will get overwritten by the next call to
* this routine.
+ *
+ * @param[in] pl The listener
+ * @param[in] timeout The timeout
+ *
+ * @return NULL on timeout
*/
GEvent *geventEventWait(GListener *pl, systime_t timeout);
-/* Register a callback for an event on a listener from an assigned source.
- * The type of the event should be checked (pevent->type) and then pevent should be typecast to the
- * actual event type if it needs to be processed.
- * Note: The GEvent buffer is valid only during the time of the callback. The callback MUST NOT save
- * a pointer to the buffer for use outside the callback.
- * Note: An existing callback function is de-registered by passing a NULL for 'fn'. Any existing
- * callback function is replaced. Any thread currently waiting using geventEventWait will be sent the exit event.
- * Note: Callbacks occur in a thread context but stack space must be kept to a minumum and
- * the callback must process quickly as all other events are performed on a single thread.
- * Note: In the callback function you should never call ANY event functions using your own GListener handle
- * as it WILL create a deadlock and lock the system up.
- * Note: Applications should not use this call - geventEventWait() is the preferred mechanism for an
- * application. This call is provided for GUI objects that may not have their own thread.
+/* @brief Register a callback for an event on a listener from an assigned source.
+ * @details The type of the event should be checked (pevent->type) and then pevent should be typecast to the
+ * actual event type if it needs to be processed.
+ *
+ * @params[in] pl The Listener
+ * @params[in] fn The function to call back
+ * @params[in] param A parameter to pass the callback function
+ *
+ * @note The GEvent buffer is valid only during the time of the callback. The callback MUST NOT save
+ * a pointer to the buffer for use outside the callback.
+ * @note An existing callback function is de-registered by passing a NULL for 'fn'. Any existing
+ * callback function is replaced. Any thread currently waiting using geventEventWait will be sent the exit event.
+ * @note Callbacks occur in a thread context but stack space must be kept to a minumum and
+ * the callback must process quickly as all other events are performed on a single thread.
+ * @note In the callback function you should never call ANY event functions using your own GListener handle
+ * as it WILL create a deadlock and lock the system up.
+ * @note Applications should not use this call - geventEventWait() is the preferred mechanism for an
+ * application. This call is provided for GUI objects that may not have their own thread.
*/
void geventRegisterCallback(GListener *pl, GEventCallbackFn fn, void *param);
/*---------- Source Functions --------------------------------------------*/
-/* Sources create their own GSourceHandles which are pointers to any arbitrary structure
- typecast to a GSourceHandle.
-*/
-
-/* Called by a source with a possible event to get a listener record.
- * 'lastlr' should be NULL on the first call and thereafter the result of the previous call.
- * It will return NULL when there are no more listeners for this source.
+/**
+ * @brief Called by a source with a possible event to get a listener record.
+ * @details @p lastlr should be NULL on the first call and thereafter the result of the previous call.
+ *
+ * @param[in] gsh The source handler
+ * @param[in] lastlr The source listener
+ *
+ * @return NULL when there are no more listeners for this source
*/
GSourceListener *geventGetSourceListener(GSourceHandle gsh, GSourceListener *lastlr);
-/* Get the event buffer from the GSourceListener.
- * Returns NULL if the listener is not currently listening.
- * A NULL return allows the source to record (perhaps in glr->scrflags) that the listener has missed events.
- * This can then be notified as part of the next event for the listener.
- * The buffer can only be accessed untill the next call to geventGetSourceListener or geventSendEvent
+/**
+ * @brief Get the event buffer from the GSourceListener.
+ * @details A NULL return allows the source to record (perhaps in glr->scrflags) that the listener
+ * has missed events. This can then be notified as part of the next event for the listener.
+ * The buffer can only be accessed untill the next call to geventGetSourceListener
+ * or geventSendEvent
+ *
+ * @param[in] psl The source listener
+ *
+ * @return NULL if the listener is not currently listening.
*/
GEvent *geventGetEventBuffer(GSourceListener *psl);
-/* Called by a source to indicate the listener's event buffer has been filled.
- * After calling this function the source must not reference in fields in the GSourceListener or the event buffer.
+/**
+ * @brief Called by a source to indicate the listener's event buffer has been filled.
+ * @details After calling this function the source must not reference in fields in the GSourceListener or the event buffer.
+ *
+ * @param[in] psl The source listener
*/
void geventSendEvent(GSourceListener *psl);
-/* Detach any listener that has this source attached */
+/**
+ * @brief Detach any listener that has this source attached
+ *
+ * @param[in] gsh The source handle
+ */
void geventDetachSourceListeners(GSourceHandle gsh);
#ifdef __cplusplus
@@ -203,3 +244,4 @@ void geventDetachSourceListeners(GSourceHandle gsh); #endif /* _GEVENT_H */
/** @} */
+
diff --git a/include/ginput/dial.h b/include/ginput/dial.h index 90db94ac..5679685e 100644 --- a/include/ginput/dial.h +++ b/include/ginput/dial.h @@ -21,7 +21,15 @@ * @file include/ginput/dial.h
* @brief GINPUT GFX User Input subsystem header file.
*
- * @addtogroup GINPUT
+ * @defgroup Dial Dial
+ * @ingroup GINPUT
+ *
+ * @details A dial provides a powerful way to navigate through menus
+ * on a display.
+ *
+ * @pre GFX_USE_GINPUT must be set to TRUE in your gfxconf.h
+ * @pre GINPUT_NEED_DIAL must be set to TRUE in your gfxconf.h
+ *
* @{
*/
#ifndef _GINPUT_DIAL_H
@@ -50,15 +58,58 @@ typedef struct GEventDial_t { extern "C" {
#endif
- /* Dial Functions */
- GSourceHandle ginputGetDial(uint16_t instance); // Instance = 0 to n-1
- void ginputResetDialRange(uint16_t instance); // Reset the maximum value back to the hardware default.
- uint16_t ginputGetDialRange(uint16_t instance); // Get the maximum value. The readings are scaled to be 0...max-1. 0 means over the full uint16_t range.
- void ginputSetDialRange(uint16_t instance, uint16_t max); // Set the maximum value.
- void ginputSetDialSensitivity(uint16_t instance, uint16_t diff); // Set the level change required before a dial event is generated.
- // - This is done after range scaling
- /* Get the current keyboard button status.
- * Returns FALSE on error (eg invalid instance)
+ /**
+ * @brief Create a dial input instance
+ *
+ * @param[in] instance The ID of the dial input instance (from 0 to 9999)
+ *
+ * @return The soure handle of the created dial instance
+ */
+ GSourceHandle ginputGetDial(uint16_t instance);
+
+ /**
+ * @brief Reset the value back to the hardware default
+ *
+ * @param[in] instance The ID of the dial input instance
+ */
+ void ginputResetDialRange(uint16_t instance);
+
+ /**
+ * @brief Get the maximum value
+ * @details The readings are scaled to be 0 ... max-1.
+ * 0 means over the full uint16_t range.
+ *
+ * @param[in] instance The ID of the dial input instance
+ *
+ * @return The maximum value
+ */
+ uint16_t ginputGetDialRange(uint16_t instance);
+
+ /**
+ * @brief Set the maximum value
+ * @note This shouldn't be set higher that the hardwares possible maximum value
+ *
+ * @param[in] instance The ID of the dial input instance
+ * @param[in] max The maximum value to be set
+ */
+ void ginputSetDialRange(uint16_t instance, uint16_t max);
+
+ /**
+ * @brief Set the level change required before a dial even is generated (threshold)
+ * @note This is done after range scaling
+ *
+ * @param[in] instance The ID of the dial input instance
+ * @param[in] diff The amount of level changes
+ */
+ void ginputSetDialSensitivity(uint16_t instance, uint16_t diff);
+
+ /**
+ * @brief Get the current dial status
+ *
+ * @param[in] instance The ID of the dial input instance
+ * @param[in] pdial The dial event struct
+ *
+ * @return Returns FALSE on an error (eg invalid instance)
*/
bool_t ginputGetDialStatus(uint16_t instance, GEventDial *pdial);
diff --git a/include/ginput/ginput.h b/include/ginput/ginput.h index ec8acca7..59f7640c 100644 --- a/include/ginput/ginput.h +++ b/include/ginput/ginput.h @@ -22,6 +22,12 @@ * @brief GINPUT GFX User Input subsystem header file.
*
* @addtogroup GINPUT
+ *
+ * @details GINPUT provides an easy and common interface to use different input devices
+ * such as touchscreens and mices.
+ *
+ * @pre GFX_USE_GINPUT must be set to TRUE in your gfxconf.h
+ *
* @{
*/
#ifndef _GINPUT_H
diff --git a/include/ginput/keyboard.h b/include/ginput/keyboard.h index cbb11194..9f5df32e 100644 --- a/include/ginput/keyboard.h +++ b/include/ginput/keyboard.h @@ -21,9 +21,11 @@ * @file include/ginput/keyboard.h
* @brief GINPUT GFX User Input subsystem header file.
*
- * @addtogroup GINPUT
+ * @defgroup Keyboard Keyboard
+ * @ingroup GINPUT
* @{
*/
+
#ifndef _GINPUT_KEYBOARD_H
#define _GINPUT_KEYBOARD_H
@@ -108,11 +110,22 @@ typedef struct GEventKeyboard_t { extern "C" {
#endif
- /* Keyboard Functions */
- GSourceHandle ginputGetKeyboard(uint16_t instance); // Instance = 0 to n-1
+ /**
+ * @brief Create a keyboard input instance
+ *
+ * @param[in] instance The ID of the keyboard input instance (from 0 to 9999)
+ *
+ * @return The source handle of the created input instance
+ */
+ GSourceHandle ginputGetKeyboard(uint16_t instance);
- /* Get the current keyboard button status.
- * Returns FALSE on error (eg invalid instance)
+ /**
+ * @brief Get the current keyboard status
+ *
+ * @param[in] instance The ID of the keyboard input instance
+ * @param[in] pkeyboard The keyboard event struct
+ *
+ * @return Returns FALSE on an error (eg invalid instance)
*/
bool_t ginputGetKeyboardStatus(uint16_t instance, GEventKeyboard *pkeyboard);
@@ -124,3 +137,4 @@ extern "C" { #endif /* _GINPUT_KEYBOARD_H */
/** @} */
+
diff --git a/include/ginput/lld/mouse.h b/include/ginput/lld/mouse.h index 09a0fb6a..5f4ba52c 100644 --- a/include/ginput/lld/mouse.h +++ b/include/ginput/lld/mouse.h @@ -21,9 +21,11 @@ * @file include/ginput/lld/mouse.h
* @brief GINPUT LLD header file for mouse/touch drivers.
*
- * @addtogroup GINPUT_MOUSE
+ * @defgroup Mouse Mouse
+ * @ingroup GINPUT
* @{
*/
+
#ifndef _LLD_GINPUT_MOUSE_H
#define _LLD_GINPUT_MOUSE_H
@@ -116,3 +118,4 @@ extern "C" { #endif /* _LLD_GINPUT_MOUSE_H */
/** @} */
+
diff --git a/include/ginput/lld/toggle.h b/include/ginput/lld/toggle.h index 2b437ed9..a75a670f 100644 --- a/include/ginput/lld/toggle.h +++ b/include/ginput/lld/toggle.h @@ -21,9 +21,11 @@ * @file include/ginput/lld/toggle.h
* @brief GINPUT header file for toggle drivers.
*
- * @addtogroup GINPUT_TOGGLE
+ * @defgroup Toggle Toggle
+ * @ingroup GINPUT
* @{
*/
+
#ifndef _LLD_GINPUT_TOGGLE_H
#define _LLD_GINPUT_TOGGLE_H
@@ -68,3 +70,4 @@ extern "C" { #endif /* _LLD_GINPUT_TOGGLE_H */
/** @} */
+
diff --git a/include/ginput/mouse.h b/include/ginput/mouse.h index 0aaea77b..5385ff17 100644 --- a/include/ginput/mouse.h +++ b/include/ginput/mouse.h @@ -21,9 +21,18 @@ * @file include/ginput/mouse.h
* @brief GINPUT GFX User Input subsystem header file for mouse and touch.
*
- * @addtogroup GINPUT
+ * @defgroup Mouse Mouse
+ * @ingroup GINPUT
+ *
+ * @details GINPUT allows it to easily interface touchscreens and mices to
+ * your application.
+ *
+ * @pre GFX_USE_GINPUT must be set to TRUE in your gfxconf.h
+ * @pre GINPUT_NEED_MOUSE must be set to TRUE in your gfxconf.h
+ *
* @{
*/
+
#ifndef _GINPUT_MOUSE_H
#define _GINPUT_MOUSE_H
@@ -85,17 +94,34 @@ typedef struct GEventMouse_t { extern "C" {
#endif
- /* Mouse Functions */
- GSourceHandle ginputGetMouse(uint16_t instance); // Instance = 0 to n-1
+ /**
+ * @brief Creates an instance of a mouse and returns the Source handler
+ * @note hack: if the instance is 9999, no calibration will be performed!
+ *
+ * @param[in] instance The ID of the mouse input instance (from 0 to 9999)
+ *
+ * @return The source handle of the created instance
+ */
+ GSourceHandle ginputGetMouse(uint16_t instance);
- /* Get the current mouse position and button status.
- * Unlike a listener event, this status cannot record meta events such as "CLICK"
- * Returns FALSE on error (eg invalid instance)
+ /**
+ * @brief Get the current mouse position and button status
+ * @note Unlinke a listener event, this status cannot record meta events such as
+ * "CLICK".
+ *
+ * @param[in] instance The ID of the mouse input instance
+ * @param[in] pmouse The mouse event
+ *
+ * @return FALSE on an error (eg. invalid instance)
*/
bool_t ginputGetMouseStatus(uint16_t instance, GEventMouse *pmouse);
- /* Run a calibration.
- * Returns FALSE if the driver doesn't support it or if the handle is invalid.
+ /**
+ * @brief Performs a calibration
+ *
+ * @param[in] instance The ID of the mouse input instance
+ *
+ * @return FALSE if the driver dosen't support a calibration of if the handle is invalid
*/
bool_t ginputCalibrateMouse(uint16_t instance);
@@ -107,9 +133,31 @@ extern "C" { */
typedef void (*GMouseCalibrationSaveRoutine)(uint16_t instance, const uint8_t *calbuf, size_t sz); // Save calibration data
typedef const char * (*GMouseCalibrationLoadRoutine)(uint16_t instance); // Load calibration data (returns NULL if not data saved)
+
+ /**
+ * @brief Set the routines to store and restore calibration data
+ *
+ * @details This function should be called before first calling ginputGetMouse() for a particular instance
+ * as the gdispGetMouse() routine may attempt to fetch calibration data and perform a startup calibration if there is no way to get it.
+ * If this is called after gdispGetMouse() has been called and the driver requires calibration storage, it will immediately save the
+ * data is has already obtained.
+ * The 'requireFree' parameter indicates if the fetch buffer must be free()'d to deallocate the buffer provided by the Fetch routine.
+ *
+ * @param[in] instance The ID of the mouse input instance
+ * @param[in] fnsave The routine to save the data
+ * @param[in] fnload The routine to restore the data
+ * @param[in] requireFree ToDo
+ */
void ginputSetMouseCalibrationRoutines(uint16_t instance, GMouseCalibrationSaveRoutine fnsave, GMouseCalibrationLoadRoutine fnload, bool_t requireFree);
- /* Test if a particular mouse/touch instance requires routines to save its calibration data. */
+ /**
+ * @brief Test if a particular mouse/touch instance requires routines to save it's alibration data
+ * @note Not implemented yet
+ *
+ * @param[in] instance The ID of the mouse input instance
+ *
+ * @return TRUE if needed
+ */
bool_t ginputRequireMouseCalibrationStorage(uint16_t instance);
#ifdef __cplusplus
@@ -120,3 +168,4 @@ extern "C" { #endif /* _GINPUT_MOUSE_H */
/** @} */
+
diff --git a/include/ginput/toggle.h b/include/ginput/toggle.h index f0bbf203..bec4ed32 100644 --- a/include/ginput/toggle.h +++ b/include/ginput/toggle.h @@ -21,9 +21,18 @@ * @file include/ginput/toggle.h
* @brief GINPUT GFX User Input subsystem header file.
*
- * @addtogroup GINPUT
+ * @defgroup Toggle Toggle
+ * @ingroup GINPUT
+ *
+ * @details GINPUT allows it to interface toggle buttons easily to your
+ * application.
+ *
+ * @pre GFX_USE_GINPUT must be set to TRUE in your gfxconf.h
+ * @pre GINPUT_NEED_TOGGLE must be set to TRUE in your gfxconf.h
+ *
* @{
*/
+
#ifndef _GINPUT_TOGGLE_H
#define _GINPUT_TOGGLE_H
@@ -65,12 +74,30 @@ typedef struct GEventToggle_t { extern "C" {
#endif
- /* Hardware Toggle/Switch/Button Functions */
- GSourceHandle ginputGetToggle(uint16_t instance); // Instance = 0 to n-1
- void ginputInvertToggle(uint16_t instance, bool_t invert); // If invert is true, invert the on/off sense for the toggle
+ /**
+ * @brief Create a toggle input instance
+ *
+ * @param[in] instance The ID of the toggle input instance (from 0 to 9999)
+ *
+ * @return The source handle of the created instance
+ */
+ GSourceHandle ginputGetToggle(uint16_t instance);
- /* Get the current toggle status.
- * Returns FALSE on error (eg invalid instance)
+ /**
+ * @brief Can be used to invert the sense of a toggle
+ *
+ * @param[in] instance The ID of the toggle input instance
+ * @param[in] invert If TRUE, will be inverted
+ */
+ void ginputInvertToggle(uint16_t instance, bool_t invert);
+
+ /**
+ * @brief Get the current toggle status
+ *
+ * @param[in] instance The ID of the toggle input instance
+ * @param[in] ptoggle The toggle event struct
+ *
+ * @return Returns FALSE on an error (eg invalid instance)
*/
bool_t ginputGetToggleStatus(uint16_t instance, GEventToggle *ptoggle);
@@ -82,3 +109,4 @@ extern "C" { #endif /* _GINPUT_TOGGLE_H */
/** @} */
+
diff --git a/include/gtimer/gtimer.h b/include/gtimer/gtimer.h index 623120dc..95ab6ba7 100644 --- a/include/gtimer/gtimer.h +++ b/include/gtimer/gtimer.h @@ -22,8 +22,21 @@ * @brief GTIMER GFX User Timer subsystem header file.
*
* @addtogroup GTIMER
+ *
+ * @details The reason why ChibiOS/GFX has it's own timer abstraction is because
+ * virtual timers provided by ChibiOS/RT are interrupt context only.
+ * While great for what they are designed for, they make coding of the input
+ * drivers much more complex.
+ * For non-performance critical drivers like these input drivers, it would also
+ * hog an in-ordinate amount of critical (interrupt locked) system time.
+ * This contrary to the goals of a real-time operating system. So a user-land
+ * (thread based) timer mechanism is also required.
+ *
+ * @pre GFX_USE_GTIMER must be set to TRUE in your gfxconf.h
+ *
* @{
*/
+
#ifndef _GTIMER_H
#define _GTIMER_H
@@ -35,19 +48,13 @@ /* Type definitions */
/*===========================================================================*/
-/**
- * @brief Data part of a static GTimer initializer.
- */
+/* Data part of a static GTimer initialiser */
#define _GTIMER_DATA() {0,0,0,0,0,0,0}
-/**
- * @brief Static GTimer initializer.
- */
+/* Static GTimer initialiser */
#define GTIMER_DECL(name) GTimer name = _GTIMER_DATA()
-/**
- * @brief A callback function (executed in a thread context).
- */
+/* A callback function (executed in a thread context) */
typedef void (*GTimerFunction)(void *param);
/**
@@ -61,7 +68,7 @@ typedef struct GTimer_t { uint16_t flags;
struct GTimer_t *next;
struct GTimer_t *prev;
- } GTimer;
+} GTimer;
/*===========================================================================*/
/* External declarations. */
@@ -71,11 +78,97 @@ typedef struct GTimer_t { extern "C" {
#endif
+/**
+ * @brief Initialise a timer.
+ *
+ * @param[in] pt pointer to a GTimer structure
+ *
+ * @api
+ */
void gtimerInit(GTimer *pt);
+
+/**
+ * @brief Set a timer going or alter its properties if it is already going.
+ *
+ * @param[in] pt Pointer to a GTimer structure
+ * @param[in] fn The callback function
+ * @param[in] param The parameter to pass to the callback function
+ * @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer.
+ * @param[in] millisec The timer period. The following special values are allowed:
+ * TIME_IMMEDIATE causes the callback function to be called asap.
+ * A periodic timer with this value will fire once only.
+ * TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
+ *
+ * @note If the timer is already active its properties are updated with the new parameters.
+ * The current period will be immediately canceled (without the callback function being
+ * called) and the timer will be restart with the new timer properties.
+ * @note The callback function should be careful not to over-run the thread stack.
+ * Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
+ * change the default size.
+ * @note The callback function should return as quickly as possible as all
+ * timer callbacks are performed by a single thread. If a callback function
+ * takes too long it could affect the timer response for other timers.
+ * @note A timer callback function is not a replacement for a dedicated thread if the
+ * function wants to perform computationally expensive stuff.
+ * @note As the callback function is called on GTIMER's thread, the function must make sure it uses
+ * appropriate synchronisation controls such as semaphores or mutexes around any data
+ * structures it shares with other threads such as the main application thread.
+ *
+ * @api
+ */
void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, systime_t millisec);
+
+/**
+ * @brief Stop a timer (periodic or otherwise)
+ *
+ * @param[in] pt Pointer to a GTimer structure
+ *
+ * @note If the timer is not active this does nothing.
+ *
+ * @api
+ */
void gtimerStop(GTimer *pt);
+
+/**
+ * @brief Test if a timer is currently active
+ *
+ * @param[in] pt Pointer to a GTimer structure
+ *
+ * @return TRUE if active, FALSE otherwise
+ *
+ * @api
+ */
bool_t gtimerIsActive(GTimer *pt);
+
+/**
+ * @brief Jab a timer causing the current period to immediate expire
+ * @details The callback function will be called as soon as possible.
+ *
+ * @pre Use from a normal thread context.
+ *
+ * @param[in] pt Pointer to a GTimer structure
+ *
+ * @note If the timer is not active this does nothing.
+ * @note Repeated Jabs before the callback function actually happens are ignored.
+ *
+ * @api
+ */
void gtimerJab(GTimer *pt);
+
+/**
+ * @brief Jab a timer causing the current period to immediate expire
+ * @details The callback function will be called as soon as possible.
+ *
+ * @pre Use from an interrupt routine context.
+ *
+ * @param[in] pt Pointer to a GTimer structure
+ *
+ * @note If the timer is not active this does nothing.
+ * @note Repeated Jabs before the callback function actually happens are ignored.
+ *
+ * @iclass
+ * @api
+ */
void gtimerJabI(GTimer *pt);
#ifdef __cplusplus
diff --git a/include/gwin/button.h b/include/gwin/button.h index 6fc564c7..698c840a 100644 --- a/include/gwin/button.h +++ b/include/gwin/button.h @@ -21,9 +21,18 @@ * @file include/gwin/button.h
* @brief GWIN Graphic window subsystem header file.
*
- * @addtogroup GWIN
+ * @defgroup Button Button
+ * @ingroup GWIN
+ *
+ * @details GWIN allows it to easily create buttons with different styles
+ * and check for different meta states such as: PRESSED, CLICKED,
+ * RELEASED etc.
+ *
+ * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
+ * @pre GWIN_NEED_BUTTON must be set to TRUE in your gfxconf.h
* @{
*/
+
#ifndef _GWIN_BUTTON_H
#define _GWIN_BUTTON_H
diff --git a/include/gwin/console.h b/include/gwin/console.h index 4e78d747..9fa867c8 100644 --- a/include/gwin/console.h +++ b/include/gwin/console.h @@ -21,9 +21,18 @@ * @file include/gwin/console.h
* @brief GWIN Graphic window subsystem header file.
*
- * @addtogroup GWIN
+ * @defgroup Console Console
+ * @ingroup GWIN
+ *
+ * @details GWIN allows it to create a console/terminal like window.
+ * You can simply use chprintf() to print to the terminal.
+ *
+ * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
+ * @pre GWIN_NEED_CONSOLE must be set to TRUE in your gfxconf.h
+ *
* @{
*/
+
#ifndef _GWIN_CONSOLE_H
#define _GWIN_CONSOLE_H
diff --git a/include/gwin/graph.h b/include/gwin/graph.h index 58c5fdee..155fd9a9 100644 --- a/include/gwin/graph.h +++ b/include/gwin/graph.h @@ -22,7 +22,13 @@ * @file include/gwin/graph.h
* @brief GWIN GRAPH module header file.
*
- * @addtogroup GWIN_GRAPH
+ * @defgroup Graph Graph
+ * @ingroup GWIN
+ *
+ * @details GWIN allows it to easily draw graphs.
+ * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
+ * @pre GWIN_NEED_GRAPH must be set to TRUE in your gfxconf.h
+ *
* @{
*/
diff --git a/include/gwin/gwin.h b/include/gwin/gwin.h index cca02d7e..e109dd83 100644 --- a/include/gwin/gwin.h +++ b/include/gwin/gwin.h @@ -21,9 +21,20 @@ * @file include/gwin/gwin.h
* @brief GWIN Graphic window subsystem header file.
*
- * @addtogroup GWIN
+ * @defgroup Window Window
+ * @ingroup GWIN
+ *
+ * @details GWIN provides a basic window manager which allows it to easily
+ * create and destroy different windows on runtime. Each window
+ * will have it's own properties such as colors, brushes as well as
+ * it's own drawing origin.
+ * Moving the windows around is not supported yet.
+ *
+ * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
+ *
* @{
*/
+
#ifndef _GWIN_H
#define _GWIN_H
diff --git a/include/gwin/options.h b/include/gwin/options.h index 899da5a4..e5e335bb 100644 --- a/include/gwin/options.h +++ b/include/gwin/options.h @@ -19,7 +19,7 @@ */
/**
- * @file include/gwin_options.h
+ * @file include/gwin/options.h
* @brief GWIN sub-system options header file.
*
* @addtogroup GWIN
@@ -45,9 +45,9 @@ * @details Defaults to FALSE
* @note To use chprintf() for printing in a console window you need to
* include in your application source file...
- * #include "chprintf.h"
+ * #include "chprintf.h"
* Also in your makefile, as part of your list of C source files, include
- * ${CHIBIOS}/os/various/chprintf.c
+ * ${CHIBIOS}/os/various/chprintf.c
*/
#ifndef GWIN_NEED_CONSOLE
#define GWIN_NEED_CONSOLE FALSE
|