Added API documentation

README.md

@@ -26,10 +26,133 @@ The SSD1306Demo is a very comprehensive example demonstrating the most important
 
 Fonts are defined in a proprietary but open format. I wrote a  program that converts any TrueType font into this format. Once the code is useful enough I will publish it or make it available as Webapplication (SaaS), where you can make any font you like available to the library.
 
-## Demo
+## API
+
+### Display Control
+
+```C++
+// Create the display object connected to pin sda and sdc
+SSD1306(int i2cAddress, int sda, int sdc);
+
+// Initialize the display
+void init();
+
+// Cycle through the initialization
+void resetDisplay(void);
+
+// Connect again to the display through I2C
+void reconnect(void);
+
+// Turn the display on
+void displayOn(void);
+
+// Turn the display offs
+void displayOff(void);
+
+// Clear the local pixel buffer
+void clear(void);
+
+// Write the buffer to the display memory
+void display(void);
+
+// Set display contrast
+void setContrast(char contrast);
+
+// Turn the display upside down
+void flipScreenVertically();
+
+// Send a command to the display (low level function)
+void sendCommand(unsigned char com);
+
+// Send all the init commands
+void sendInitCommands(void);
+```
+
+## Pixel drawing
+
+```C++
+// Draw a pixel at given position
+void setPixel(int x, int y);
+
+// Draw 8 bits at the given position
+void setChar(int x, int y, unsigned char data);
+
+// Draw the border of a rectangle at the given location
+void drawRect(int x, int y, int width, int height);
+
+// Fill the rectangle
+void fillRect(int x, int y, int width, int height);
+
+// Draw a bitmap with the given dimensions
+void drawBitmap(int x, int y, int width, int height, const char *bitmap);
+
+// Draw an XBM image with the given dimensions
+void drawXbm(int x, int y, int width, int height, const char *xbm);
+
+// Sets the color of all pixel operations
+void setColor(int color);
+```
+
+## Text operations
+
+``` C++
+// Draws a string at the given location
+void drawString(int x, int y, String text);
+
+// Draws a String with a maximum width at the given location.
+// If the given String is wider than the specified width
+// The text will be wrapped to the next line at a space or dash
+void drawStringMaxWidth(int x, int y, int maxLineWidth, String text);
+
+// Returns the width of the String with the current
+// font settings
+int getStringWidth(String text);
+
+// Specifies relative to which anchor point
+// the text is rendered. Available constants:
+// TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT
+void setTextAlignment(int textAlignment);
+
+// Sets the current font. Available default fonts
+// defined in SSD1306Fonts.h:
+// ArialMT_Plain_10, ArialMT_Plain_16, ArialMT_Plain_24
+void setFont(const char *fontData);
+```
+
+## Frame Transition Functions
+
+```C++
+// Sets the callback methods of the format void method(x,y)
+void setFrameCallbacks(int frameCount, void (*frameCallbacks[])(int x, int y));
+
+// Tells the framework to move to the next tick. The
+// current visible frame callback will be called once
+// per tick
+void nextFrameTick(void);
+
+// Draws the frame indicators. In a normal setup
+// the framework does this for you
+void drawIndicators(int frameCount, int activeFrame);
+
+// defines how many ticks a frame should remain visible
+// This does not include the transition
+void setFrameWaitTicks(int frameWaitTicks);
+
+// Defines how many ticks should be used for a transition
+void setFrameTransitionTicks(int frameTransitionTicks);
+
+// Returns the current state of the internal state machine
+// Possible values: FRAME_STATE_FIX, FRAME_STATE_TRANSITION
+// You can use this to detect when there is no transition
+// on the way to execute operations that would
+int getFrameState();
+```
+
+## Example: SSD1306Demo
 
 ### Frame 1
 ![DemoFrame1](https://github.com/squix78/esp8266-oled-ssd1306/raw/master/resources/DemoFrame1.jpg)
+
 This frame shows three things:
  * How to draw an xbm image
  * How to draw a static text which is not moved by the frame transition

ssd1306_i2c.h

@@ -73,43 +73,112 @@ private:
    void (**myFrameCallbacks)(int x, int y);
 
 
-   
+
 public:
-   // Empty constructor
+   // Create the display object connected to pin sda and sdc
    SSD1306(int i2cAddress, int sda, int sdc);
+
+   // Initialize the display
    void init();
+
+   // Cycle through the initialization
    void resetDisplay(void);
+
+   // Connect again to the display through I2C
    void reconnect(void);
+
+   // Turn the display on
    void displayOn(void);
+
+   // Turn the display offs
    void displayOff(void);
+
+   // Clear the local pixel buffer
    void clear(void);
+
+   // Write the buffer to the display memory
    void display(void);
+
+   // Set display contrast
+   void setContrast(char contrast);
+
+   // Turn the display upside down
+   void flipScreenVertically();
+
+   // Send a command to the display (low level function)
+   void sendCommand(unsigned char com);
+
+   // Send all the init commands
+   void sendInitCommands(void);
+
+   // Draw a pixel at given position
    void setPixel(int x, int y);
+
+   // Draw 8 bits at the given position
    void setChar(int x, int y, unsigned char data);
+
+   // Draw the border of a rectangle at the given location
+   void drawRect(int x, int y, int width, int height);
+
+   // Fill the rectangle
+   void fillRect(int x, int y, int width, int height);
+
+   // Draw a bitmap with the given dimensions
+   void drawBitmap(int x, int y, int width, int height, const char *bitmap);
+
+   // Draw an XBM image with the given dimensions
+   void drawXbm(int x, int y, int width, int height, const char *xbm);
+
+   // Sets the color of all pixel operations
+   void setColor(int color);
+
+   // Draws a string at the given location
    void drawString(int x, int y, String text);
+
+   // Draws a String with a maximum width at the given location.
+   // If the given String is wider than the specified width
+   // The text will be wrapped to the next line at a space or dash
    void drawStringMaxWidth(int x, int y, int maxLineWidth, String text);
+
+   // Returns the width of the String with the current
+   // font settings
    int getStringWidth(String text);
+
+   // Specifies relative to which anchor point
+   // the text is rendered. Available constants:
+   // TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT
    void setTextAlignment(int textAlignment);
+
+   // Sets the current font. Available default fonts
+   // defined in SSD1306Fonts.h:
+   // ArialMT_Plain_10, ArialMT_Plain_16, ArialMT_Plain_24
    void setFont(const char *fontData);
-   void drawBitmap(int x, int y, int width, int height, const char *bitmap);
-   void drawXbm(int x, int y, int width, int height, const char *xbm);
-   void sendCommand(unsigned char com);
-   void sendInitCommands(void);
-   void setColor(int color);
-   void drawRect(int x, int y, int width, int height);
-   void fillRect(int x, int y, int width, int height);
-   
-   void setContrast(char contrast);
-   void flipScreenVertically();
-   
-   
+
+   // Sets the callback methods of the format void method(x,y)
    void setFrameCallbacks(int frameCount, void (*frameCallbacks[])(int x, int y));
+
+   // Tells the framework to move to the next tick. The
+   // current visible frame callback will be called once
+   // per tick
    void nextFrameTick(void);
+
+   // Draws the frame indicators. In a normal setup
+   // the framework does this for you
    void drawIndicators(int frameCount, int activeFrame);
+
+   // defines how many ticks a frame should remain visible
+   // This does not include the transition
    void setFrameWaitTicks(int frameWaitTicks);
+
+   // Defines how many ticks should be used for a transition
    void setFrameTransitionTicks(int frameTransitionTicks);
+
+   // Returns the current state of the internal state machine
+   // Possible values: FRAME_STATE_FIX, FRAME_STATE_TRANSITION
+   // You can use this to detect when there is no transition
+   // on the way to execute operations that would
    int getFrameState();
-   
+
    const int FRAME_STATE_FIX = 0;
    const int FRAME_STATE_TRANSITION = 1;