Diff: Application/Button.h

Revision:

1:46c8df4608c8

Parent:

0:4977187e90c7

Child:

2:efae611de184

--- a/Application/Button.h	Thu Dec 11 11:03:57 2014 +0000
+++ b/Application/Button.h	Thu Dec 11 18:15:52 2014 +0000
@@ -1,21 +1,135 @@
-#ifndef BUTTON_h
-#define BUTTON_h
+/*
+ *  Copyright 2014 Embedded Artists AB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+ 
+#ifndef BUTTON_H
+#define BUTTON_H
 
 #include "lpc_swim.h"
 
+/**
+ * Button example
+ *
+ * @code
+ * #include "mbed.h"
+ * #include "Button.h"
+ *
+ * SWIM_WINDOW_T win;
+ *
+ * static void buttonClicked(uint32_t x)
+ * {
+ *   bool* done = (bool*)x;
+ *   *done = true;
+ * }
+ * 
+ * int main(void) {
+ *    // initialize the display and touch
+ *    DMBoard::instance().init();
+ *    
+ *    // setup the SWIM window to use
+ *    swim_window_open(&win, ...);
+ *
+ *    // create a 60x30 pixels button labeled "Done" at 100,100
+ *    Button btn("Done", win.fb, 100, 100, 60, 30);
+ *    btn.draw();
+ *
+ *    // register a callback for when the button is pressed and pass the
+ *    // done flag for the callback to modify
+ *    bool done = false;
+ *    btn.setAction(buttonClicked, (uint32_t)&done);
+ *
+ *    // keep processing touch events until the button is clicked
+ *    TouchPanel* touch = DMBoard::instance().touchPanel();
+ *    TouchPanel::touchCoordinate_t coord;
+ *    while(!done) {
+ *      touch->read(coord);
+ *      if (btn.handle(coord.x, coord.y, coord.z > 0)) {
+ *        btn.draw();
+ *      }
+ *    }
+ * }
+ * @endcode
+ */
 class Button {
 public:
+
+    /** Creates a new button
+     *
+     *  This button will use a SWIM window to draw on. That window will use
+     *  part of the full size frame buffer to draw on.
+     *
+     *  @param caption the button text
+     *  @param fb      the frame buffer
+     *  @param x       the upper left corner of the button
+     *  @param y       the upper left corner of the button
+     *  @param width   the width of the button
+     *  @param height  the height of the button
+     */
   Button(const char* caption, COLOR_T* fb, uint16_t x, uint16_t y, uint16_t width, uint16_t height);
+  
+    /** Set the function to call when the button is clicked
+     *
+     *  Note that this function can be called with NULL as func to unregister the
+     *  callback function.
+     *
+     *  @param func the function to call
+     *  @param arc the argument to pass to the function when calling
+     */
   void setAction(void (*func)(uint32_t arg), uint32_t arg) { _func = func; _funcArg = arg; }
+
+    /** Changes the caption
+     *
+     *  @param caption the new text on the button
+     */
   void setCaption(const char* caption);
+
+    /** Changes the colors
+     *
+     *  @param bg        background color when not pressed
+     *  @param fg        text color when pressed 
+     *  @param bgPressed background color when pressed
+     *  @param fgPressed text color when pressed
+     */
   void setColors(COLOR_T bg, COLOR_T fg, COLOR_T bgPressed, COLOR_T fgPressed);
+  
+    /** Process the touch event
+     *
+     *  This function will detect if and how the touch event affects it.
+     *  If the event causes the button to be clicked then the registered
+     *  callback function is called before handle() returns.
+     *
+     *  The return value is to let the caller now if the button should be
+     *  redrawn or not.
+     *
+     *  @param x       the touched x coordinate
+     *  @param y       the touched y coordinate
+     *  @param pressed true if the user pressed the display
+     *
+     *  @returns
+     *       true if the button should be redrawn
+     *       false if the event did not affect the button
+     */
   bool handle(uint16_t x, uint16_t y, bool pressed);
+
+    /** Draws the button
+     */
   void draw();
 
 private:
   const char* _caption;
   int _capx, _capy;
-  //uint16_t _x0, _y0, _x1, _y1;
   COLOR_T _bgCol, _fgCol, _bgColPressed, _fgColPressed;
   bool _enabled, _pressed;
   void (*_func)(uint32_t arg);
@@ -23,6 +137,4 @@
   SWIM_WINDOW_T _win;
 };
 
-#endif /* BUTTON_h */
-
-
+#endif /* BUTTON_H */