add backlight example

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 82 insertions, 0 deletions

diff --git a/examples/backlight b/examples/backlight
new file mode 100644
index 0000000..59673bb
--- /dev/null
+++ b/examples/backlight
@@ -0,0 +1,82 @@
+# -*- python -*-
+
+# This example demonstrates how to use adjust backlight
+# without interfering to much with manual adjustments.
+# The example with oscillate the backlight between 50 %
+# and 100 % but include any manual adjustments.
+
+import math
+
+
+# Get backlight controller.
+controller = list_backlights()[0]
+controller = Backlight(controller, adjbacklight = True, minimum = 0)
+# `adjbacklight = True` requires the `adjbacklight` command/package
+# and lets us avoid hassling with permissions.
+# `minimum = 0` is optional.
+
+# The users brightness adjustment
+user_adjustment = controller.brightness / controller.maximum
+
+
+# Do not fade in or out, apply settings immediately.
+fadein_time, fadeout_time = None, None
+
+# Update the backlight ten times per second.
+wait_period = 0.1
+
+
+cycle, adj, last = 0, 1, controller.brightness
+def periodically(year, month, day, hour, minute, second, weekday, fade):
+    '''
+    :(int, int, int, int, int, int, int, float?)?→void  Place holder for periodically invoked function
+    
+    Invoked periodically
+    
+    If you want to control at what to invoke this function next time
+    you can set the value of the global variable `wait_period` to the
+    number of seconds to wait before invoking this function again.
+    The value does not need to be an integer.
+    
+    @param   year:int     The year
+    @param   month:int    The month, 1 = January, 12 = December
+    @param   day:int      The day, minimum value is 1, probable maximum value is 31 (*)
+    @param   hour:int     The hour, minimum value is 0, maximum value is 23
+    @param   minute:int   The minute, minimum value is 0, maximum value is 59
+    @param   second:int   The second, minimum value is 0, probable maximum value is 60 (**)
+    @param   weekday:int  The weekday, 1 = Monday, 7 = Sunday
+    @param   fade:float?  Blueshift can use this function to fade into a state when it start
+                          or exits. `fade` can either be negative, zero or positive or `None`,
+                          but the magnitude of value cannot exceed 1. When Blueshift starts,
+                          this function will be invoked multiple with the time parameters
+                          of the time it is invoked and each time `fade` will increase towards
+                          1, starting at 0, when the value is 1, the settings should be applied
+                          to 100 %. After this this function will be invoked once again with
+                          `fade` being `None`. When Blueshift exits the same behaviour is used
+                          except, `fade` decrease towards -1 but start slightly below 0, when
+                          -1 is reached all settings should be normal. Then Blueshift will NOT
+                          invoke this function with `fade` being `None`, instead it will by
+                          itself revert all settings and quit.
+    
+    (*)  Can be exceeded if the calendar system is changed, like in 1712-(02)Feb-30
+    (**) See https://en.wikipedia.org/wiki/Leap_second
+    '''
+    global cycle, adj, last, user_adjustment
+    
+    if not controller.brightness == last:
+        user_adjustment = controller.brightness / (controller.maximum * adj)
+    
+    cycle = (cycle + 0.5) % 1
+    adj = (1 + math.cos(cycle * 2 * math.pi)) / 2
+    adj = (1 + adj) / 2
+    controller.brightness = adj * user_adjustment * controller.maximum
+    last = controller.brightness
+    
+
+
+def reset():
+    '''
+    Invoked to reset the displays
+    '''
+    controller.brightness = round(user_adjustment * controller.maximum)
+