#!/bin/sh
# the next line restarts using wish \
exec wish "$0" ${1+"$@"}
########################################################################
# fichier preftest
# Test et documentation du package test.tcl 
# voir doc, historique et info complmentaire  la fin de ce fichier
# 
########################################################################
########################################################################
########################################################################
# Complment au package pref.tcl


set pref(doc) {
########################################################################
Historique :
------------

modifi par diam@ensta.fr
07/02/02 : rajout de l'option -postcommand pour Pref_add (merci JL Commeau)
12/06/96 : correction bug de PrefInvokeButton si le bouton invoqu
           par <Escape> detruit la toplevel (effet enfonc puis relev).
20/05/96 : Pref_Add ne peut prendre QU'UNE seule prfrence  la fois.
17/05/96 : rerefonte (structure de donnes).
09/05/96 : refonte (et rduction importante des "A faire"
16/04/96 : modif de la proc Status en PrefStatus et cration d'une 
           variable pref(status) et pref(reportProc)
12/04/96 : modif de savePref pour que le fichier gnr soit du TCL pur.
12/04/96 : ajout d'un champs Type pour chaque prfrence
           le premier mot du champs Type dfinit le type de la preference 
           (boolean, color, geometry, enum, integer, .., string (defaut))
           la signification des mots suivants dpend du type (par exemple
           liste des valeurs possible pour le type "enum")
           Ce champ permet d'une part de personnaliser l'diteur de prfrence 
           en fonction de son type, et d'autre part d'effectuer des 
           controles de valisit.

Bug et modif a faire :
----------------------

- Pref_Init : intgrer option "-sourcePwd" qui source un fichier utilisateur 
  du rpertoire courant.
- Refondre la gestion des options : gnraliser la methode 
      Pref_init -opt1 val1 -bool -- <arg1> <arg2> ...
  ou bien (pour raison d'efficacit) :
      Pref_Init  -key_i val_i  ...  (que des couples option/valeur)
- groupMod listbox : (bug) ameliorer les binding (utilisation fiable des 
  fleches au clavier) voir lib/tcl4.2b1/ browser de fichier
- Utiliser grid au lieu de pack.
- creer les autre mode pour -groupmode (buttons, popup, flat, ..)
- prvoir de rajouter de scrollBar si trop de pref par group (via un
  widget canvas ou text) 
- grer les messages multilingues (creer exemple pour francais / anglais 
  /espagnol)
- demander confirmation au moment de faire "Done" (==? Validate) et 
  proposer la "avec sauvegarde", "sans sauvegarde" , "annuler" (de Done)
  Pour cela utiliser les procedures de Dialogue
- Sauvegarde ultrieure possible  grer par l'application (proposer 
  un menu "Config/Save prefs" qui lance la proc "Pref_save")
- prvoir un champ supplmentaire pour les browser chooser : nom d'un procdure 
  permettant de choisir le type en question.
  Exemples : {COLOR &colorChooser}
             {FONT &fontChooser}
             {FILE {&fileSelect -dfaut $eg(var)}}
- utiliser grid au lieu de pack

Procdures externes utilises :
-------------------------------

   Aucune.
   
Evolution envisage :
---------------------

Orientation objet : 
Pouvoir grer dans une mme application plusieurs 
jeux de prfrence indpendants.
Principe cration de plusieurs tableaux pref0, pref1, ... propre  
une instance particulire.
Le tableau pref() reste ncessaire ne serait-ce que pour grer la 
liste des module pseudo-objets "jeux de prfrences"

########################################################################
########################################################################
########################################################################
BUT DU PACKAGE PREF :
---------------------
Le module "pref" propose un jeux de procdures permettant de faciliter
la gestion complte des prfrences d'une application.

Les fonctionnalits suivantes sont proposes :
----------------------------------------------

    - gestion des fichiers de prfrence propre  l'application
      (i.e.  un site) et du fichier de prfrence utilisateur
      (qui peut tre modifi et sauvegarder)
      
    - initialisation et gestion des valeurs par dfaut des prfrences, 
    
    - exploitation de la notion de ressource xwindow (qui fonctionne 
      galement sur Macintosh et sur PC).
      
    - libert totale pour l'application dans le choix des variables 
      dclars comme prfrence ("MUG(export,vhdl_header)", gred(admin)
      ou tout simplement "FILENAME"). 

    - construction automatique d'une interface graphique permettant 
       l'utilisateur de modifier, sauvegarder, ... les prfrences.
      
    - pollution minimale de l'espace des variable (tout tient dans 
      un seul tableau "pref"
    

########################################################################
########################################################################
########################################################################
Principe :
---------
    L'utilisation de ce package se fait a 2 niveaux :
        1) dfinition meme des attributs de preferences
        2) construction du dialogue
Une prfrence est un ensemble d'au maximum sept lments. Ceux-ci 
doivent etre declar lors de la creation des prfrences en utilisant la 
procdure "Pref_Add" :
   -type : type proprement dit de la variable utilise comme prfrence
     (BOOLEAN, ENUM, ... STRING + FILE COLOR TEXT ...),
     La valeur par dfaut est STRING qui correspond  une simple entry
   -typearg : info complmentaires propre  ce type (valeurs possible  
     d'un type numr, hauteur d'un texte, ...)
   -group : exemples "Gnral", "Interface Utilisateur", ...
     La valeur par dfaut est le nom du groupe prcdement dfini.
     Si un seul group est dfini (ou aucun) : aucun groupe n'est affich.
   -var : nom de la variable mmorisant cette prfrence
   -xres : nom de la ressource Xwindows correspondante
   -default : valeur par dfaut de cette prfrence
   -comment : sa description en une ligne
   -help : info complmentaire (plusieurs lignes possibles)


L'utilisation du module "pref" se fait en trois phases :

1 - Initialisation :
--------------------
    Pref_Init  {appPrefsDefault userPrefsDefault args} {}

    - Les deux premiers parametres (obligatoires) sont des noms de 
      fichier TCL qui initialisent les prfrences de l'application
      (userPrefsDefault sera utilis pour la sauvegarde des
      prfrences) 
    - les options suivantes (args) sont par exemple :
        -reportProc <procName> (defaut : "PrefStatus")
         permet de dfinir une procdure pour l'mission de messages par 
         le package,
        -groupmode <mode> 

2 - Initialisation des prfrences :
------------------------------------
    Pref_Add {<prefSpecification>}

    prend en parametre une spcification de prfrences qui est UNE 
    une liste de couple "-option valeur".

    Pref_Add {
      -type COLOR             -group "User Interface"
      -var gred(etapeColor)   -xres etapeColor   -default black
      -comment "Couleur d'une etape"
      -help "La couleur d'une tape peut etre modifier en ..."
    }
   
3 - lancement ventuel de la fenetre de dialogue par l'utilisateur
------------------------------------------------------------------
    Pref_Dialog

########################################################################
Conventions de programmation :
------------------------------

(Voir fichier /doc/methodologie.doc pour les gnralits)
Les variables statiques du package pref sont entirement contenues 
dans le tableau "pref()".
Il permet de manipuler d'autres "objets" internes qui sont les "groupes" 
contenant eux mme des "prefs" qui ont leurs propres donnes.


Procdure publiques disponibles :
---------------------------------

Pref_Init appPrefsDefault userPrefsDefault args
    -reportProc (default: PrefStatus)
        nom d'une procdure appler pour afficher les messages utilisateur 
    -groupmode listbox

Pref_Add SpecOfPref 

Pref_Dialog {args}
   -group <groupName>
       Nom du groupe  afficher (l'utilisateur pourra changer en fonction
       de l'opt
   -groupmode <mode>   
       indique la manire dont les groupes doivent etre proposs.
       valeurs possibles : 
           - listbox : 
           - popup :
           - buttons :
           - auto (default) : 
        
Pref_Save 

   Sauvegarde ultrieur possible si l'utilisateur a  slectionn
   "Done" au lieu de "Save" :

Pref_Reset

   Remise des prfrences  leur valeur par dfaut
    - RAZ des valeurs a leur valeur / default (option -default)
    - lecture des fichiers de preference.

########################################################################

Variable globales utilises :
-----------------------------
pref(Meta) :   touche modificateur "Meta" par dfaut
pref(modified) : initialis  0 puis mise  1 quand on quitte sans 
              avoir sauvegard les prfrences.(A exploiter par l'appli 
              principale pour quitter). Il est possible de faire
              confirmer la sauvegarde lorsque l'on quitte la fenetre preference.
pref(done) : initialis  0 puis mise  1 quand on quitte le panel 
             des prfrences (voir utilisation dans la proc Pref_Test)
    
pref(msg,...) :  messages   afficher  l'utilisateur (dpend de la langue)

pref(reportProc) : nom d'une procdure  utiliser pour l'affichage 
             de l'aide (la proc par dfaut "PrefStatus" pour etre
             remplac par l'utilisateur) 
pref(status) : contient le message affich
pref(status,text) : widget text utilis pour l'affichage de l'aide
pref(status,font) fonte du widget text d'affichage $pref(status,text)
pref(status,height) hauteur (en nmr de ligne) de $pref(status,text)

pref(toplevel) : nom de la frame Toplevel (.pref) sera peut-etre 
             ".pref0", ".pref1", ...
pref(uid) :  contient un nombre utilis une seule fois (Unic IDentif)
pref(null) : valeur dsignant une prfrence inaffecte (pour viter 
             d'utiliser "" (dfaut : "pref_null_value")
             Les noms de la forme "pref(nullxxx)" correspondent  des 
             variables bidon (i.e Pref_Add sans nom de variable)

# Les 2 champs suivants sont a changer par l'utilisateur de ce packege
pref(appPrefsDefault) Fichier TCL des prfrence de l'appli (site)
pref(userPrefsDefault) Fichier TCL des prfrence de l'utilisateur
             utilis pour la sauvegarde des prfrences
     
pref(groupMode) : Mode de slection du groupe "listbox"
             pourra tre "auto" "buttons" "popup"
pref(groupNames) : liste des noms de groupe ({Gnral {Interface ut...}...})
pref(currentGroupName) : Nom du dernier groupe entr par Pref_Add" 
              puis nom du groupe visualis dans Pref_Dialog
pref(defaultGroupName) : "Group1"

Les variables locales "$gn" et "$vn" reprsentent un nom de groupe ou un nom
de variable.


pref(varNames) : liste des noms de variables dans l'ordre de dclaration.
pref(groupNames) : liste des noms de groupe dans l'ordre de dclaration.

pref(gn$groupName,gid) : contient l'id du groupe dont le nom est $gName
     exemple : set "pref(gnInterface Utilisateur,gid)" "3"
pref(gid$gid,groupName) : contient le nom du groupe d'identit $gid
pref(gid$gid,prefs) : liste des id des prefs du group $gid
    Les procdures utilisateurs sont de la forme Pref_Dialog {...}
pref(gid$gid,commentWidth) : contiendra la taille maxi du "comment" 
    pour le groupe $gid

Les variables suivantes contiennent les valeurs relatives  la variable dont le 
nom $vn 

vartmp : variable temporaire image de la variable 
updatePref : commande permettant de mettre  jour une variable de
       prfrence  partir du widget de cette prf (exploite par 
       eval par exemple quand on fait "Done"
updateWidget) : commande permettant de mettre  jour le widget d'une prf
        partir de la variable de prf courante. 
       (ncessaire par exemple aprs avoir fait un "Reset")
       
Exemple pour la preferences admin :
pref(vn$vn,comment)      = Ajout du menu administration
pref(vn$vn,default)      = OFF
pref(vn$vn,postcommand)  = {gred:reconfigureCurrent}
pref(vn$vn,frame)        = .pref.b.g1.v8
pref(vn$vn,group)        = Gnral
pref(vn$vn,help)         = Cette variable permet ...
pref(vn$vn,type)         = BOOLEAN
pref(vn$vn,typearg)      = left right
pref(vn$vn,updatePref)   = set gred(admin) {[set} pref(vngred(admin),vartmp)\]
pref(vn$vn,updateWidget) = set pref(vngred(admin),vartmp) {[set} gred(admin)\]
pref(vn$vn,vartmp)       = 1
pref(vn$vn,xres)         = admin

    exemple :
    
    set "pref(vngred(admin),comment)"   "Ajout du menu administration"


Les variables suivantes contiennent les valeurs relatives au groupe dont le
nom est $gn

pref(gn$gn,commentWidth) : taille maxi du champs comment pour toutes
       les variables du groupe $gn (inutile si on utilise grid a la place de
       pack ?)
pref(gn$gn,frame) : frame rserve au groupe $gn (visible ou nom suivant
       la valeur de pref(currentGroupName)
pref(gn$gn,varNames) : liste des prfrences du groupe $gn

    exemple :
    
    pref(gnUser Interface,commentWidth) = 26
    pref(gnUser Interface,frame)        = .pref.b.g2
    pref(gnUser Interface,varNames)     = gred(etapeColor) gred(geometry)


########################################################################
Evolutions possibles :
----------------------

Pouvoir instancier plusieurs objets "pref" en utilisant alors comme
tableau global "pref0()", pref1(), ...

Application : pouvoir utiliser ce package pour des fonctions totalement
diffrentes et indpendantes (un pour grer les prferences
(utilisation normal), un autres pour controler les differents attributs
d'une tape, un autre pour les transition, ou tout simplement pour 
demander une liste de parametre  l'utilisateur... Cela necessitera la creation
probable d'une couche de procedure intermediaire du style "labeledEnter"
(utilisable egalement comme champs de "adressbook")


#####################################################################
Exemple d'utilisation : 
-----------------------
L'excution de ce test cre (s'il n'existe pas dja) un fichier de
configuration "app-defaults.tcl"  dans le mme rpertoire que ce
package. 
La valeur initiale de ce fichier est contenue dans la variable
"appdef_content". (variable affectee dans le script)

Un exemple de fichier utilisateur "user-defaults.tcl" est galement 
donn en exemple (variable user-defaults.tcl), mais celui-ci n'tant 
pas obligatoire, il n'a pas besoin d'etre gnr  pas ce programme 
de test (il est genere par le package pref lui-mme lorsqu'on clique sur 
"Save"
}

# # lappend auto_path [file dir [info script]]
# # package require pref

proc Pref_Test {} {
    # setup de l'application test
    # Exemple d'utilisation :
    global  auto_path appdef_content userdef_content
    global appdef userdef
    
    # set olddir [pwd]
    # 
    # cd [file dirname [info script]]
    # set prefDir [pwd]
    # cd ..
    # set pistDir [pwd]
    # cd $olddir
    # lappend auto_path $pistDir 
    # package require pref
    
    lappend auto_path [file dir [info script]]
    set prefDir [file dir [info script]]
    package require pref

    #####################################################################
    #####################################################################
    #####################################################################
    # Cration ventuelle du fichier $appdef si inexistant :
    
    wm withdraw .
    set appdef  [file join $prefDir app-tcl.defaults]
    set userdef [file join $prefDir user-tcl.defaults]
    if {![info exist $appdef]}  {
         pref_writeFile $appdef $appdef_content
    }
    # if {![info exist $userdef]} {pref_writeFile $userdef $userdef_content}
    
    Pref_Init  $appdef $userdef
    
    
    Pref_Add { 
         -type  ENUM  
         -typearg  {left right}   
         -group  Gnral
         -var  gred(scrollside) 
         -xres  scrollbarSide 
         -default right
         -postcommand {puts "Modif scrollside ==> $gred(scrollside)"}
         -comment "Position de la scrollBar"
         -help "La barre de dfilement verticale d'un widget text ou d'un\
           canvas peut etre \012place  droit (right) ou  gauche (left)"
    }
    Pref_Add {   -type COLOR    -group "User Interface"
          -var gred(etapeColor)  -xres etapeColor    -default black
          -comment "Couleur d'une etape"
          -help "La couleur d'une tape peut etre modifier en ..."
    }
    Pref_Add {    -type BOOLEAN          -group Gnral
          -var gred(admin)  -xres admin  -default OFF
          -comment "Ajout du menu administration"
          -help "Cette variable permet de rajouter un menu \"admin\" facilitant\
           la maintenance \012de l'application gred"
    }
    Pref_Add {  -type SCALE -typearg {-1 .. 50}    -group Gnral
          -var gred(undonumber) -xres undoNumber -default 15
          -comment "Vitesse de Nombre d'annulations possibles"
          -help "La valeur 0 supprime la fonctionnalit d'annulation\
           \xaMettre -1 pour un nombre infini (limite mmoire)"
    }
    Pref_Add { 
          -type GEOMETRY        -group "User Interface"
          -var gred(geometry)  -xres geometry  -default 10+10x400x700
          -comment "Geometrie de l'application"
          -help "asdfasdasjdhasdasda asd as,dm sad,m as  ,m nasd,mas ,mas a,mn \
          asdasldkjaslk asjlddklksaj aslk jaslkjsalkjas lkaslk jaslk dlkkl kaj \
          asdas;dk ;asl;lak a;slk ;aslkd ;las as "
    }
    Pref_Add {
          -type ENUM  -typearg {A B C D }    -group "Groupe bidon"
          -var gred(PIPO) -xres pipoRessourse  -default AB
          -comment "defaut := AB , ressource := BC pour rire"
          -help "Rien a voir"
    }
    Pref_Dialog
   
}

########################################################################
# Exemple de fichier app-tcl.defaults (doit exister) :
########################################################################
set appdef_content {
option add   *geometry         150x50+6565-2   startupFile
option add   *admin            0               startupFile
option add   *scrollbarSide    left            startupFile
option add   *pipoRessourse    D               startupFile
}

########################################################################
# Exemple de fichier user-tcl.defaults :
########################################################################
set userdef_content {# # # option add *foreground green

###!!! START of automatically added text
###!!! Do not edit between these two "###!!!..." lines
###!!! Modified on 16/05/96 at T
#########################################
# Group name : Gnral

# Position de la scrollBar :
option add *scrollbarSide right

# Ajout du menu administration :
option add *admin 1

# Vitesse de Nombre d'annulations possibles :
option add *undoNumber 1523\ \{sPI\ sPO

#########################################
# Group name : User Interface

# Couleur d'une etape :
option add *etapeColor { p p p sdfg p p pps}

# Geometrie de l'application :
option add *geometry {150x50+6565-2dfghdfhg }

#########################################
# Group name : Groupe bidon

# defaut := AB , ressource := BC pour rire :
option add *pipoRessourse A

###!!! END of automatically added text


# You can put any valid TCL commands outside of these automatically 
# lines :
# option add *background red
# option add *Pref*background blue
# option add *Pref*Listbox*background #f88
}
########################################################################
########################################################################
########################################################################

# Execution du test
Pref_Test
bind all <$pref(Meta)-q> {exit}
# relance le script
bind all <$pref(Meta)-O> {exec [info script] &}
vwait pref(done)
set olddir [pwd]
cd $olddir
exit
# ./
