====== Documentation de l'Opener pour développeur ======
Cet article s'adresse à toute personne souhaitant étendre les possibilités de l'Opener. Pour votre bonne compréhension, il est nécessaire d'avoir des connaissances basique en python.

===== Introduction =====
L'opener est un outil ouvert à tous ce qui signifie que vous pouvez l'étendre ou l'adapter selon vos besoins. Le code est structuré de manière à ce que vous puissiez vous repérer à l'aide de cet article.
----
===== Librairie nécessaire =====
L'addon utilise la librairie Naming qui est chargé de réaliser la nomenclature des différents fichiers/dossiers. Dans notre cas, l'addon l'implémente sous sa forme la plus simple possible.
Cette dernière est disponible en téléchargement au lien suivant:
[[https://github.com/LesFeesSpeciales/lib.git|{{ :download.png?150 }}]]

Dans le cas où vous souhaiteriez développer vos propres outils avec, un guide existe sur le wiki à l'adresse suivante: [[kabaret.naming|Guide naming]].
----
===== Structure des fichiers =====
Les fonctions et différentes parties de l'addon sont regroupées dans différents fichiers par catégories. Les différents modules sont les suivants:
  * **init** : Gère l'initialisation de l'addon, c'est lui qui créer les variables de scène (stockant les chemins,séquences...).

  * **files** : Gère l'interaction entre l'addon et les fichiers(Listage des dossiers,fichiers avec vérifications...).

  * **gui** : Ce module est chargé de dessiner la GUI de l'addon dans les tools de blender, si vous souhaitez modifier l'interface de l'addon, cela se passe dans la fonction **naming_panel** de ce module.

  * **interface** : interface.py fait le pont entre blender, le système de fichier et la librairie naming. C'est ses fonctions qui, avec Naming, génère les chemins.

  * **operators** : Operator contient tout les opérateur nécessaires à l'addon, parmis eux, certaint on pour fonction d'ouvrir simplement un explorateur de fichier(OBJECT_OT_custompath), etc... (Voir section opérateurs)

  * **persistence** : Comme son nom l'indique, persistence permet de rendre certains champs de l'interface persistents, c'est-à-dire qu'il va stocker certaines valeur dans des fichers localement.

  * **ressources** : ressources permet la mise en place de variable globale à tout les module.

----
===== Fonctions clefs =====
Dans cette partie, nous allons éclaircir le fonctionnement de certaines fonctions clef de l'addon.

==== a. initSceneProperties ====
C'est ici que ce déroule l'enregistrement des variables de scènes, nécessaires à toutes sortes de choses. On retrouve par exemple tous les champs, que ce soit la séquence, l'asset ou autre sous forme de variable de scène ici.
Cette fonction de divise en deux parties, l'instentiations de variables déstinées à être **dynamiques** ou **statiques**.\\
Ici nous suivrons le code séquentiellement, et donc commencerons par la partie dynamique.\\

Dans Blender, l'actualisation des propriétés de scènes EnumProperty pose toujours problème: il est impossible de les mettres à jour sans les supprimer et les recréer. Ainsi, pour mettre en place les Enum dynamique, j'ai simplement crée une fonction(UpdateEnum) donc l'unique utilité est de supprimer et de recréer les Enums passés en paramètre.\\ 
Dans le cas de l'Opener, les propriétés dynamique servent à mémoriser les assets,séquences,shots,stores,... ajoutés par l'utilisateur. \\
L'exemple qui suit est juste une partie succinte du code de la fonction initSceneProperties concernant la création de la propriété stockant le(s) répertoires choisi par l'utilisateur.\\

<code python>
#DYNAMIC ATTIBS------------------------------------------------->
#Liste contennant toutes les propriétés dynamiques
properties = []

#Valeurs par défaut pour la propriété Store(le repertroire racine)
drives = (('Store',"Store directory",''),('/u/Project/',"/u/Project/",''),('test2_1',"test2_2",''),('',"",''))

#Création de la sceneProperty vide
bpy.types.Scene.drives = EnumProperty(name="none",description="none",items=(('')),update=interface.update_naming)

s = len(properties)

#Ajout de la propriété pour l'enregistrement      
ressources.Items.append(('none',"none","")) 

#Pour chaque propriétés
for i in range(s):
   #Setup store dir
   if properties[i][0][0] == 'Store': #Dans le cas du store
       #Si il n'y a pas de fichier persistent déjà existant, on rempli avec les valeurs par défaut 
       if not persistence.load_config():     
           for line in range(1,len(properties[i])):
                essources.Items.append((str(properties[i][line][0]),str(properties[i][line][1]),str(properties[i][line][2])))         
       #On met à jour la variable grâce à la fonction UpdateEnum
       interface.UpdateEnum(bpy.types.Scene,ressources.Items,properties[i][0][0],properties[i][0][1],ressources.Items[0][0])    
</code>

Ci-dessous, un exemple de déclaration de propriété de scène statique, pour la propriété root.

<code python>
#STATICS ATTIBS------------------------------------------------->
#ROOT----------------------------->
bpy.types.Scene.roots = EnumProperty(
    name="Root",
    description="root",
    items=(('LIB', "LIB", ""),
          ('MOVIE', "MOVIE", ""),
          ('', "", "")),
    default='LIB',
    update = interface.update_naming)  
                
</code>
 
La partie intéressante est la ligne suivante:
<code python>
update = interface.update_naming
</code>
Cette dernière consiste à appeler la fonction **update_naming(self,context)** __à chaque modification de la propriété__. Ce qui nous amène à cette fonction.

==== b. update_naming ====
Comme précédement expliqué, Opener utilise la librairie de Naming. Cette dernière est mise en place dans le module interface.py, la fonction update_naming est chargé de préparer le dictionnaire avec tous les champs avant de le charger avec la librairie.
<code python>
#Copie du dictionnaire pour des vérifications
temp = ressources.path.copy()
    
#Nettoyage du dictionnaire path
ressources.path.clear()
    
#Séparation des éléments en fonction de l'OS
if sys.platform == 'win32':
   dest = bpy.context.scene.drives.split('\\')
else:
   dest = bpy.context.scene.drives.split('/')
#Mise à jour du dictionnaire
if bpy.context.scene.roots == 'LIB':
   ressources.path['Lib'] = 'LIB'
   ressources.path['Family']=bpy.context.scene.famille
   #Si jamais l'asset sélectinné dans la liste est Other lors de la MAJ, on l'ajoute aux assets
   if bpy.context.scene.asset == 'other':
      #Construction du tuple temporaire pour vérifier son unicité dans la liste des asset
      tempAsset = (str(bpy.context.scene.newA),str(bpy.context.scene.newA),'')
      #Si il n'existe pas alors on l'ajoute
      if tempAsset not in ressources.Items_asset:
         #On récupère le nouvel asset à ajouter dans le dictionnaire
         ressources.path['Asset']=bpy.context.scene.newA
         #On ajoute cet asset à la liste
         ressources.Items_asset.append((str(bpy.context.scene.newA),str(bpy.context.scene.newA),''))
         UpdateEnum('',ressources.Items_asset,'asset','','')
         bpy.context.scene.asset = bpy.context.scene.newA
      
      else:
         bpy.context.scene.newA = ""
          
  else:
     ressources.path['Asset']=bpy.context.scene.asset
</code>

Dans les lignes suivantes, les champs dynamique sont mis à jour, si modification il y a eu.
<code python>
#................Quelques lignes plus tard..............
#Si jamais lors de l'execution de la fonction, on se trouve dans la fenêtre MOVIE alors:
elif (bpy.context.scene.roots == 'MOVIE') and (bpy.context.scene.drives != 'none') and (temp['Dept'] == ressources.path['Dept']) and ('Shot' in temp) and ('Sequence' in temp):
   temps = persistence.load_seq()
   for i in range(len(temps)):
      y = (str(temps[i]),str(temps[i]),'')
      if y not in ressources.Items_seq:
        ressources.Items_seq.append((str(temps[i]),str(temps[i]),''))
        change = True
   #Si il y a de nouvelles séquences, on les ajoutes
   if change:
      UpdateEnum('',ressources.Items_seq,'seq','','none')
      bpy.context.scene.shot = ressources.Items_shot[0][0]
   #Si jamais le shot n'a pas changé
   elif temp['Shot'] == bpy.context.scene.shot:
      #On va scanner les dossier pour vérifier la présence de nouveaux shots
      temps = persistence.load_shots()
      ressources.Items_shot.clear()
      ressources.Items_shot.append(('none','none',''))
      for i in range(len(temps)):
         y = (str(temps[i]),str(temps[i]),'')
         #Si jamais il y en a des nouveaux, on les ajoutes
         if y not in ressources.Items_shot:
            ressources.Items_shot.append((str(temps[i]),str(temps[i]),''))
     #On met à jour la liste des shots
     UpdateEnum('',ressources.Items_shot,'shot','','none') 
</code>

Ces dernières lignes sont également très importantes, c'est ici que l'on va appeler la fonction qui, à l'aide de la librairie Naming et du dictionnaire ressource.path va génerer et vérifier l'authenticité du chemin et des nom par rapport à une syntax précise.

<code python>
#................Quelques lignes plus tard..............
try:
   bpy.context.scene.newF = create_naming(self,context,'',ressources.path,ressources.command)   
   files.Update_ListFile(bpy.context.scene.newF)
except:
   print('naming no setup, clearing list')
   #Nettoyage de la liste des fichier
   bpy.context.scene.custom.clear()
   ressources.command.append("! missing field !")
   
</code>

Nous allons maintenant parcourir un des opérateurs crée pour l'addon. Il faut savoir que dans Blender, les Operateurs représentent un des outils les plus pratiques pour le développement pour de nombreuses raisons( ils sont facilement accessible pour l'utilisateur, ils peuvent prendre des arguments,etc,...).\\
Dans l'Opener, j'utilise aussi les opérateurs à des fins ergonomiques pour mettre en place des boutons. En fin de compte, chaque boutons est un opérateur auquel on a assigné une icône lors de son appel dans l'interface.


==== c. custompath operator====

Pour apprendre à faire un opérateur de base, suivez le lien suivant:[[http://www.blender.org/api/blender_python_api_2_57_release/bpy.types.Operator.html|Blender Operator Guide]]\\

La première partie de l'opérateur consiste naturellement à déclarer les différents champs est variables nécessaire:
<code python>
#Entête avec héritage de l'object Operator de blender, nécessaire à chaque fois que l'on créer un opérateur
class OBJECT_OT_custompath(bpy.types.Operator):
 bl_idname = "object.custom_path"
 bl_label = "open"
 __doc__ = ""   
    
 filename_ext = ""
 filter_glob = StringProperty(default="", options={'HIDDEN'},subtype='DIR_PATH')    
        

 #Variable stockant le chemin choisi
 filepath = StringProperty(name="File Path", description="Filepath importing store dir", maxlen= 1024)
 #optionnel, récupère les fichiers séléctionnés 
 files = CollectionProperty(
  name="File Path",
  type=bpy.types.OperatorFileListElement)
</code>

Ici il s'agit du corps de l'opérateur, la fonction execute va s'éxecuter à chaque appel de l'opérateur. Il en est de même ,pour les fonctions draw et invoke. 
<code python>
 def execute(self, context):
  #ajout du chemin sélectionné    
  ressources.Items.append((str(self.properties.filepath),str(self.properties.filepath),""))
  #Création du tuple temporaire
  t=(str(self.properties.filepath),str(self.properties.filepath)))
  #Mise à jour de la liste des dossier racine
  interface.UpdateEnum(bpy.types.Scene,ressources.Items,'Store',t)
        
  #Sauvegarde du dossier sélectionné de manière persistante
  persistence.write_config()
  #Find de fonction
  return {'FINISHED'}
  
  #Fonction d'affichage de l'explorateur de fichier
  def draw(self, context):
   self.layout.operator('file.select_all_toggle')        
  def invoke(self, context, event):
   wm = context.window_manager
   wm.fileselect_add(self)
   return {'RUNNING_MODAL'}     
</code>
----
<WRAP center round important 60%>
En construction
</WRAP>