Add documentation for C and C# calculator examplesdevs/xartigas/calculator_example

2 files changed, 54 insertions, 14 deletions

diff --git a/apps/c/calculator/src/calculator.c b/apps/c/calculator/src/calculator.c
index 6990820..b42c4ba 100644
--- a/apps/c/calculator/src/calculator.c
+++ b/apps/c/calculator/src/calculator.c
@@ -6,17 +6,21 @@
 #include <efl_ui_text.eo.h>
 #include <efl_text_interactive.eo.h>
 
-static Efl_Ui_Text *_screen = NULL;
-static int _prev_value = 0, _curr_value = 0;
-static char _operation = '=';
-static Eina_Bool _must_overwrite = EINA_FALSE;
+static Efl_Ui_Text *_screen = NULL;            // Text widget showing current value
+static int _prev_value = 0;                    // Value introduced before an operation (first operand
+static int _curr_value = 0;                    // Value currently being introduced (second operand)
+static char _operation = '=';                  // Last operation button pressed
+static Eina_Bool _must_overwrite = EINA_FALSE; // Whether next number must be appended to current input
+                                               // or overwrite it
 
+// Quits the application
 static void
 _gui_quit_cb(void *data EINA_UNUSED, const Efl_Event *event EINA_UNUSED)
 {
    efl_exit(0);
 }
 
+// Performs "operation" on "currValue" and "prevValue" and leaves result in "currValue"
 static void
 _operate()
 {
@@ -39,10 +43,12 @@ _operate()
    }
 }
 
+// Called every time a button is pressed
 static void
 _button_pressed_cb(void *data, const Efl_Event *event EINA_UNUSED)
 {
    char button = ((const char *)data)[0];
+   // If it is a number, append it to current input (or replace it)
    if (button >= '0' && button <= '9')
      {
         char str[2] = { button, '\0' };
@@ -60,6 +66,7 @@ _button_pressed_cb(void *data, const Efl_Event *event EINA_UNUSED)
         switch (button)
         {
            case 'C':
+              // Clear current input
               efl_text_set(_screen, "0");
               break;
            case '+':
@@ -67,12 +74,14 @@ _button_pressed_cb(void *data, const Efl_Event *event EINA_UNUSED)
            case '*':
            case '/':
            case '=':
+              // If there was a pending operation, perform it
               if (_operation != '=')
                 {
                    _operate();
                    snprintf(str, sizeof(str), "%d", _curr_value);
                    efl_text_set(_screen, str);
                 }
+              // Store this operation
               _operation = button;
               _must_overwrite = EINA_TRUE;
               _prev_value = _curr_value;
@@ -83,6 +92,10 @@ _button_pressed_cb(void *data, const Efl_Event *event EINA_UNUSED)
      }
 }
 
+// Called every time the content of the screen changes
+// We use it to sanitize input (remove heading zeros, for example)
+// This makes more sense when the Text widget is editable, since the user
+// is free to type anything.
 static void
 _screen_changed_cb(void *data EINA_UNUSED, const Efl_Event *event EINA_UNUSED)
 {
@@ -104,8 +117,10 @@ _screen_changed_cb(void *data EINA_UNUSED, const Efl_Event *event EINA_UNUSED)
      }
 }
 
-// text is what is drawn on the button, which might be a multi-byte unicode string.
-// command is a single-char id for the button.
+// Creates an Efl.Ui.Button and positions it in the given position inside the table
+// The button text is colored with "r, g, b"
+// "text" is what is drawn on the button, which might be a multi-byte unicode string.
+// "command" is a single-char id for the button.
 static void
 _button_add(Efl_Ui_Table *table, const char *text, const char *command, int posx, int posy, int r, int g, int b)
 {
@@ -127,11 +142,13 @@ _button_add(Efl_Ui_Table *table, const char *text, const char *command, int posx
    efl_content_set(button, label);
 }
 
+// Creates the UI
 static void
 _gui_setup()
 {
    Eo *win, *table;
 
+   // The window
    win = efl_add(EFL_UI_WIN_CLASS, efl_main_loop_get(),
                  efl_ui_win_type_set(efl_added, EFL_UI_WIN_TYPE_BASIC),
                  efl_text_set(efl_added, "EFL Calculator"),
@@ -140,11 +157,13 @@ _gui_setup()
    // when the user clicks "close" on a window there is a request to delete
    efl_event_callback_add(win, EFL_UI_WIN_EVENT_DELETE_REQUEST, _gui_quit_cb, NULL);
 
+   // The table is the main layout
    table = efl_add(EFL_UI_TABLE_CLASS, win,
                    efl_content_set(win, efl_added),
                    efl_pack_table_size_set(efl_added, 4, 5),
                    efl_gfx_hint_size_min_set(efl_added, EINA_SIZE2D(300, 400)));
 
+   // Create all buttons using the _button_add helper
    _button_add(table, "1", "1", 0, 3, 255, 255, 255);
    _button_add(table, "2", "2", 1, 3, 255, 255, 255);
    _button_add(table, "3", "3", 2, 3, 255, 255, 255);
@@ -162,6 +181,7 @@ _gui_setup()
    _button_add(table, "=", "=", 2, 4, 128, 128, 128);
    _button_add(table, "C", "C", 0, 4,   0,   0,   0);
 
+   // Create a big Efl.Ui.Text screen to display the current input
    _screen = efl_add(EFL_UI_TEXT_CLASS, table,
                      efl_text_set(efl_added, "0"),
                      efl_text_multiline_set(efl_added, EINA_FALSE),
diff --git a/apps/csharp/calculator/src/calculator.cs b/apps/csharp/calculator/src/calculator.cs
index 35e426d..e4711c0 100644
--- a/apps/csharp/calculator/src/calculator.cs
+++ b/apps/csharp/calculator/src/calculator.cs
@@ -1,12 +1,15 @@
+/* Simple calculator using an Efl.Ui.Table to place the buttons
+*/
 using System;
 
 public class Calculator : Efl.Csharp.Application
 {
-    private Efl.Ui.Text screen;
-    private int prevValue = 0;
-    private int currValue = 0;
-    private char operation = '=';
-    private bool mustOverwrite = false;
+    private Efl.Ui.Text screen;         // Text widget showing current value
+    private int prevValue = 0;          // Value introduced before an operation (first operand)
+    private int currValue = 0;          // Value currently being introduced (second operand)
+    private char operation = '=';       // Last operation button pressed
+    private bool mustOverwrite = false; // Whether next number must be appended to current input
+                                        // or overwrite it
 
     // Quits the application
     private void GUIQuitCb(object sender, Efl.Gfx.EntityVisibilityChangedEventArgs ea)
@@ -15,6 +18,7 @@ public class Calculator : Efl.Csharp.Application
             Efl.App.AppMain.Quit(0);
     }
 
+    // Performs "operation" on "currValue" and "prevValue" and leaves result in "currValue"
     private void Operate()
     {
        switch (operation)
@@ -36,8 +40,10 @@ public class Calculator : Efl.Csharp.Application
        }
     }
 
+    // Called every time a button is pressed
     private void ButtonPressedCb(char button)
     {
+        // If it is a number, append it to current input (or replace it)
         if (button >= '0' && button <= '9')
           {
              if (mustOverwrite)
@@ -52,6 +58,7 @@ public class Calculator : Efl.Csharp.Application
              switch (button)
              {
                 case 'C':
+                   // Clear current input
                    screen.SetText("0");
                    break;
                 case '+':
@@ -59,11 +66,13 @@ public class Calculator : Efl.Csharp.Application
                 case '*':
                 case '/':
                 case '=':
+                   // If there was a pending operation, perform it
                    if (operation != '=')
                      {
                         Operate();
                         screen.SetText(currValue.ToString());
                      }
+                   // Store this operation
                    operation = button;
                    mustOverwrite = true;
                    prevValue = currValue;
@@ -74,6 +83,10 @@ public class Calculator : Efl.Csharp.Application
           }
     }
 
+    // Called every time the content of the screen changes
+    // We use it to sanitize input (remove heading zeros, for example)
+    // This makes more sense when the Text widget is editable, since the user
+    // is free to type anything.
     private void ScreenChangedCb(object sender, EventArgs ea)
     {
        string text = "";
@@ -96,8 +109,10 @@ public class Calculator : Efl.Csharp.Application
        if (text != str) screen.SetText(text);
     }
 
-    // text is what is drawn on the button, which might be a multi-byte unicode string.
-    // command is a single-char id for the button.
+    // Creates an Efl.Ui.Button and positions it in the given position inside the table
+    // The button text is colored with "r, g, b"
+    // "text" is what is drawn on the button, which might be a multi-byte unicode string.
+    // "command" is a single-char id for the button.
     private void AddButton(Efl.Ui.Table table, string text, char command, int posx, int posy, int r, int g, int b)
     {
        var button = new Efl.Ui.Button(table);
@@ -107,7 +122,7 @@ public class Calculator : Efl.Csharp.Application
        };
        // Buttons can only have simple text (no font, styles or markup) but can swallow
        // any other object we want.
-       // Therefore we create a more complex Efl_Ui_Text object and use it as content for the button.
+       // Therefore we create a more complex Efl.Ui.Text object and use it as content for the button.
        var label = new Efl.Ui.Text(table);
        label.Editable = false;
        label.Halign = 0.5;
@@ -118,18 +133,22 @@ public class Calculator : Efl.Csharp.Application
        button.Content = label;
     }
 
+    // Called on start up. We use it to create the UI.
     protected override void OnInitialize(string[] args)
     {
+       // The window
        var win = new Efl.Ui.Win(Efl.App.AppMain);
        win.SetText("EFL Calculator");
        win.Autohide = true;
        win.VisibilityChangedEvent += GUIQuitCb;
 
+       // The table is the main layout
        var table = new Efl.Ui.Table(win);
        win.Content = table;
        table.TableSize = (4, 5);
        table.HintSizeMin = new Eina.Size2D(300, 400);
 
+       // Create all buttons using the AddButton helper
        AddButton(table, "1", '1', 0, 3, 255, 255, 255);
        AddButton(table, "2", '2', 1, 3, 255, 255, 255);
        AddButton(table, "3", '3', 2, 3, 255, 255, 255);
@@ -147,6 +166,7 @@ public class Calculator : Efl.Csharp.Application
        AddButton(table, "=", '=', 2, 4, 128, 128, 128);
        AddButton(table, "C", 'C', 0, 4,   0,   0,   0);
 
+       // Create a big Efl.Ui.Text screen to display the current input
        screen = new Efl.Ui.Text(table);
        screen.SetText("0");
        screen.Font = ("Sans", (Efl.Font.Size)48);