AutoHotkey v1 - Guide de Référence Optimisé LLM

AutoHotkey v1 - Guide de Référence Optimisé LLM

Guide structuré des bonnes pratiques AutoHotkey v1 pour développeurs et assistants IA

---

Structure du Guide

Observability

First: At the start of execution, display:

🔧 Skill "julien-ref-ahk-v1" activated

PARTIE I - RÈGLES CRITIQUES : Erreurs fatales à éviter absolument PARTIE II - STANDARDS FONDAMENTAUX : Encodage, nommage, architecture PARTIE III - DÉVELOPPEMENT : Patterns, GUI, performance PARTIE IV - VALIDATION : Tests et déploiement

---

PARTIE I - RÈGLES CRITIQUES

Erreur #0 : Section Auto-Execute - LA RÈGLE LA PLUS CRITIQUE

QU'EST-CE QUE L'AUTO-EXECUTE?

La section auto-execute est le code qui s'exécute automatiquement au démarrage du script. C'est la source #1 des bugs incompréhensibles en AutoHotkey!

CE QUI TERMINE L'AUTO-EXECUTE

L'auto-execute se termine dès qu'AutoHotkey rencontre:

1. Un return explicite
2. Un Exit
3. UNE FONCTION (ligne commençant par NomFonction() {)
4. UN HOTKEY/​HOTSTRING (ligne contenant ::)
5. UN LABEL (ligne se terminant par :)
6. La fin physique du fichier

ERREUR FATALE - Code après une fonction

#SingleInstance Force
global myVar := "value"

MyFunction() {  ; CETTE FONCTION TERMINE L'AUTO-EXECUTE!
    MsgBox, Function
}

; CE CODE NE S'EXÉCUTERA JAMAIS AU DÉMARRAGE!
MsgBox, Script started  ; Jamais affiché!
Menu, Tray, Icon, icon.ico  ; Jamais chargé!
return

STRUCTURE CORRECTE

#SingleInstance Force
global myVar := "value"

; Code d'initialisation (s'exécute au démarrage)
MsgBox, Script started
Menu, Tray, Icon, icon.ico

; FIN EXPLICITE de l'auto-execute
return

; Fonctions (après le return)
MyFunction() {
    MsgBox, Function
}

; Hotkeys (après les fonctions)
^a::
    MyFunction()
return

STRUCTURE DE FICHIER OBLIGATOIRE

#Directives (#SingleInstance, #Persistent, etc.)
↓
Variables globales
↓
AUTO-EXECUTE (code qui s'exécute au démarrage)
↓
return  ← FIN EXPLICITE de l'auto-execute
↓
Fonctions
↓
Labels
↓
Hotkeys/​Hotstrings
↓
#Include (À LA TOUTE FIN!)

PLACEMENT DES #INCLUDE - RÈGLE ABSOLUE

Les #Include DOIVENT être À LA TOUTE FIN du fichier, après:

• Toutes les fonctions
• Tous les labels
• Tous les hotkeys

POURQUOI? Les modules appellent souvent des fonctions du fichier principal (comme Logger_Info). Si l'include est placé avant la définition de ces fonctions, le script plantera!

---

Erreur #1 : Includes Manquants ou Incorrects

SOLUTION OBLIGATOIRE

#Include %A_ScriptDir%\VA.ahk      ; Chemin absolu TOUJOURS

RÈGLE ABSOLUE

• Tous les includes doivent utiliser %A_ScriptDir%\ pour les chemins absolus

---

Erreur #2 : Syntaxe Variables dans %var%

SYNTAXE INVALIDE

MsgBox, Device: %devices[1].name%     ; ERREUR FATALE

SOLUTION OBLIGATOIRE

deviceName := devices[1].name         ; Extraire la propriété
MsgBox, Device: %deviceName%          ; Utiliser la variable simple

---

Erreur #3 : Usage Incorrect de global

USAGE CORRECT

MyFunction() {
    global ; En DÉBUT de fonction seulement
    ; OU global var1, var2 pour variables spécifiques
}

MyLabel:
    ; Les variables sont globales par défaut dans les labels
    ; PAS de déclaration global nécessaire
return

---

Erreur #4 : Gestion Tableaux Vides

.MaxIndex retourne "" (chaîne vide) pour un tableau vide, pas 0.

VÉRIFICATION CORRECTE

ArrayCount := Array.MaxIndex
if (ArrayCount = "") {
    ArrayCount := 0         ; Conversion explicite
}
Loop % ArrayCount {
    Element := Array[A_Index]
}

---

PARTIE II - STANDARDS FONDAMENTAUX

Encodage : UTF-8 avec BOM OBLIGATOIRE

Sans UTF-8 avec BOM, les caractères accentués deviennent illisibles.

SOLUTION UNIQUE

1. Éditeur : Sauvegarder en UTF-8 AVEC BOM
2. Lecture : FileRead, var, *t *p65001 %file%
3. Écriture : FileAppend, content, %file%, UTF-8

---

Architecture de Projet

PROJET SIMPLE (≤ 200 lignes)

MonScript.ahk                      # Tout en un seul fichier

PROJET MODULAIRE (200-1000 lignes)

Projet/
├── Main.ahk                       # Point d'entrée
├── Config.ahk                     # Variables globales
├── Modules/
│   ├── Module1.ahk               # Fonctionnalités
│   └── Module2.ahk
└── logs/                         # Logs (auto-créé)

---

Standards de Nommage

; Fichiers et dossiers : PascalCase
MyModule.ahk, Utils/, Core/

; Variables globales : MAJUSCULES
global LOG_ENABLED := true
global EMAIL_ADDRESS := "[email protected]"

; Fonctions : PascalCase
SendEmailGmail()
GetAudioDevicesList()

; Variables locales : camelCase
local deviceName := "Speakers"
currentTime := A_Now

---

PARTIE III - DÉVELOPPEMENT

Gestion des Objets COM (Audio/​System)

PATTERN OBLIGATOIRE

FunctionWithCOM() {
    ; 1. Créer les objets
    if !(enumerator := VA_GetDeviceEnumerator()) {
        return "Erreur création enumerator"
    }

    VA_IMMDeviceEnumerator_EnumAudioEndpoints(enumerator, 0, 1, devices)

    ; 2. Traitement
    VA_IMMDeviceCollection_GetCount(devices, count)
    Loop, %count% {
        VA_IMMDeviceCollection_Item(devices, A_Index - 1, device)
        ; Traiter device...
        ObjRelease(device)    ; LIBÉRER CHAQUE OBJET
    }

    ; 3. Nettoyage OBLIGATOIRE
    ObjRelease(devices)
    ObjRelease(enumerator)
}

Chaque objet COM créé DOIT être libéré avec ObjRelease().

---

Interface Graphique

SOLUTIONS SIMPLES ET ROBUSTES

Edit Control avec Scroll Natif

Gui, Add, Edit, x10 y10 w500 h300 ReadOnly VScroll HScroll vContentArea
GuiControl,, ContentArea, %LongText%  ; Scroll automatique

RÈGLES GUI ESSENTIELLES

• Simplicité : Privilégier les contrôles natifs (Edit, ListBox)
• Séparation : GUI distinctes pour différentes fonctions
• Scroll natif : Laisser AutoHotkey gérer le scroll
• Boutons fixes : Placer les boutons hors des zones scrollables

---

PARTIE IV - VALIDATION

Checklist Pré-Déploiement

VALIDATION TECHNIQUE OBLIGATOIRE

• Encodage : UTF-8 avec BOM sur tous les fichiers .ahk
• Includes : Tous les chemins utilisent %A_ScriptDir%\
• Tableaux : Vérification MaxIndex = "" pour tableaux vides
• COM : Tous les objets libérés avec ObjRelease()
• Global : Utilisé uniquement en début de fonctions
• Variables : Pas d'accès propriétés dans %var%

---

Règles d'Or à Retenir

1. UTF-8 avec BOM : Obligatoire pour les accents
2. Includes absolus : Toujours avec %A_ScriptDir%\
3. Variables simples : Dans %var%, pas de propriétés d'objets
4. Global correct : Fonctions seulement, jamais dans labels
5. Tableaux vides : Vérifier MaxIndex = ""
6. COM cleanup : ObjRelease() obligatoire
7. Log unique : Un seul fichier actif par session
8. Hotkeys à la fin : Convention et bonne pratique
9. Auto-execute : Toujours terminer par return explicite
10. Includes en dernier : À la fin du fichier principal