;;; uko-scanning.el -- scanning modes in UKO-II

;; Copyright (C) 2003 Michael Kuehn, Universität Koblenz-Landau

;; Author: Michael Kuehn <kuehn@uni-koblenz.de>
;; Maintainer: Michael Kuehn <kuehn@uni-koblenz.de>
;; Created: August 2003
;; 
;; $Id: uko-scanning.el,v 1.12 2003/10/10 11:27:57 deee Exp $



;;;; UKO_SCANNING

;;;; Scanning allows the use of UKO-II with only two physical switches.
;;;; By default they are set to the keypad numbers 7 and 9.
;;;; they are customizable and can be changed to any other key.
;;;; The first button switches to the next button and highlights it.
;;;; The second executes the assigned function(s).

;;;; Single-button-scanning (automatic scanning) allows the use of only one button.
;;;; Scanning is performed automatically.
;;;; Execution button to perform the action of the highlighted button
;;;; ------------------------------------------------------------------------



;; variable for the active button. Set to 0 by default.
(defvar uko-scanning-active-button 0 
  "Active button while scanning.")

;; variable for the last active button. Set to 0 by default.
(defvar uko-scanning-former-active-button 0
  "Former active button while scanning.")

;; defines an itimer for single button scanning
(defvar uko-scanning-single-button-itimer nil
  "Timer for single button scanning.")


;; interactive function to activate scanning mode with the M-x command
(defun uko-scanning-on ()
  "Interactive function activating scanning."
  (interactive)
  (setq uko-scanning t)
  (uko-scanning-initialize)
  )

;; interactive function to activate automatic scanning
(defun uko-scanning-single-button-on ()
  "Interactive function activating automatic scanning."
  (interactive)
  (setq uko-scanning-single-button t)
   (uko-scanning-single-button-initialize)
   )


;; interactive function to deactivate scanning mode with the M-x command
;; sets the customizable variable uko-scanning to nil
;; deletes the timer if automatic scanning was active
;; deactivates scanning and automatic scanning
;; turns off the highlighting
(defun uko-scanning-off ()
  "Interactive function deactivating scanning and automatic scanning."
(interactive)
(when uko-scanning-single-button-itimer
    (delete-itimer uko-scanning-single-button-itimer)
    )
  (setq uko-scanning nil)
  (setq uko-scanning-single-button nil)
  (uko-scanning-hilight-off uko-scanning-active-button)
  )

;; initialization function setting active button and former avtive button to "0"
;; turning on highlighting for active button
;; setting all global keys
;; calls initializing function for automatic scanning, if wanted
(defun uko-scanning-initialize ()
  "Perform the necessary initialization steps for linear scanning.
Set the active button to 0. Set the former active button to 0.
Activate Highlighting for the active button. Set all global keys."
  (setq uko-scanning-active-button 0)
  (setq uko-scanning-former-active-button 0)
  (uko-scanning-hilight-on uko-scanning-active-button)
  (global-set-key uko-scanning-physical-switch-move 'uko-scanning-key-a)
  (global-set-key uko-scanning-physical-switch-strike 'uko-scanning-key-b)
 ; (global-set-key uko-physical-switch-m 'uko-scanning-key-b)
  (when uko-scanning-single-button 
    (uko-scanning-single-button-initialize)
   )
  )


;; SINGLE BUTTON SCANNING: function performed repetedly with the delay of seconds defined in the itimer-function
(defun uko-scanning-single-button-initialize ()
  "Start a new itimer which performs the function of uko-scanning-key-a repetedly.
With the delay of seconds defined in the variable uko-scanning-single-button-delay-time."
  (when uko-scanning-single-button-itimer
    (delete-itimer uko-scanning-single-button-itimer)
    ) 
  (setq uko-scanning-single-button-itimer (start-itimer "UKO Single Button Scanning Timer." 'uko-scanning-key-a uko-scanning-single-button-delay-time uko-scanning-single-button-delay-time))
)

;; function executed when letter scanning key a is pressed:
;; assinginng value of active button to former active button
;; turning off highlight for former active button
;; selecting the next button
;; turning on highlight for active button 
(defun uko-scanning-key-a ()
  "Execute when button for scanning is pressed.
Change value of former active button, assign new value to active button
and switche the highlight to the new active button."
  (interactive)
  (setq uko-scanning-former-active-button uko-scanning-active-button)
  (uko-scanning-hilight-off uko-scanning-former-active-button)
  (uko-scanning-next-button uko-scanning-active-button)
  (uko-scanning-hilight-on uko-scanning-active-button)
)

;; function executed when letter 'b' is pressed:
;; turning off highlight for pressed button
;; executing assigned function
;; setting active button to its default state (0) and highlight it
(defun uko-scanning-key-b ()
  "Executed when active button is pressed.
Turn off highlight of active button.
Execute the assigned function of the active button.
Set active button to 0 and turns on highlight."
  (interactive)
  (uko-scanning-hilight-off uko-scanning-active-button)
  (uko-key-x uko-scanning-active-button)
  (setq uko-scanning-active-button 0)
  (uko-scanning-hilight-on uko-scanning-active-button)
;;  (setq uko-scanning-former-button 0)

) 

;; function switching the active button to the next
;; evaluation to switch keys in folloing manner: 0, 1, 2, 3, 0, 1, 2, 3, 0, 1 .....
;; scanning from left to right (mod (+ button 1) 4)
;; scanning from right to left (mod (- button 1) 4)
(defun uko-scanning-next-button (button)
  "Change the value of the active button."
  (setq uko-scanning-active-button (mod (- button 1) 4) )
)

;; function for highlighting: changing the background color of the active button window
;; to the highight color
(defun uko-scanning-hilight-on (k)
  "Change the background color of the window of a button to the highlight color. (turn highlight on)."
  (let ((button (aref uko-button-windows k)))
    (set-face-background 'default uko-scanning-hilight-color button)
    )
  )

;; function for turning off highlight: changing the background color of the last active button window
;; to the default color
(defun uko-scanning-hilight-off (k)
  "Change the background color of the window of a button to the default color. (turn highlight off)."
  (let ((button (aref uko-button-windows k)))
    (set-face-background 'default uko-scanning-default-color button)
    )
  )
