First readMe

README.md

@@ -0,0 +1,143 @@
+# Visionneuse de Vignettes en PureBasic / Thumbnail Viewer in PureBasic
+
+Ce projet est un composant d'interface utilisateur avancé pour PureBasic qui permet d'afficher des centaines ou des milliers de vignettes d'images de manière fluide et efficace. Il est conçu pour être facilement intégré dans n'importe quelle application nécessitant une galerie d'images performante.
+
+*This project is an advanced UI component for PureBasic that allows displaying hundreds or thousands of image thumbnails smoothly and efficiently. It is designed to be easily integrated into any application requiring a high-performance image gallery.*
+
+## Fonctionnalités / Features ✨
+
+  * **Chargement Asynchrone :** Les images sont chargées en arrière-plan grâce au multithreading, ce qui évite de figer l'application.
+
+      * ***Asynchronous Loading:*** *Images are loaded in the background using multithreading, which prevents the application from freezing.*
+
+  * **Système de Cache :** Un cache intelligent conserve les images chargées en mémoire pour un réaffichage instantané et gère la libération de la mémoire pour les images qui ne sont plus visibles.
+
+      * ***Caching System:*** *An intelligent cache keeps loaded images in memory for instant redisplay and manages memory release for images that are no longer visible.*
+
+  * **Défilement Fluide :** Le défilement vertical est optimisé pour une expérience utilisateur agréable, même avec de nombreuses vignettes.
+
+      * ***Smooth Scrolling:*** *Vertical scrolling is optimized for a pleasant user experience, even with many thumbnails.*
+
+  * **Modes d'Affichage :** Les images peuvent être ajustées pour s'adapter, remplir ou s'étirer dans l'espace de la vignette (`#Image_Style_Fit`, `#Image_Style_Fill`, `#Image_Style_Stretch`).
+
+      * ***Display Modes:*** *Images can be adjusted to fit, fill, or stretch within the thumbnail area (`#Image_Style_Fit`, `#Image_Style_Fill`, `#Image_Style_Stretch`).*
+
+  * **Dessin Vectoriel :** L'utilisation du sous-système `VectorDrawing` assure un rendu de haute qualité et une bonne compatibilité avec les écrans à haute résolution (HiDPI).
+
+      * ***Vector Drawing:*** *The use of the `VectorDrawing` subsystem ensures high-quality rendering and compatibility with high-resolution (HiDPI) displays.*
+
+  * **Sélection Multiple :** Support de la sélection d'une ou plusieurs vignettes (y compris la sélection de plage avec la touche **Majuscule**).
+
+      * ***Multiple Selection:*** *Supports selecting one or more thumbnails (including range selection with the **Shift** key).*
+
+-----
+
+## Structure du Projet / Project Structure 🏗️
+
+Le code est organisé en plusieurs modules logiques pour une meilleure clarté et maintenance.
+*The code is organized into several logical modules for better clarity and maintainability.*
+
+  * **`Core`** : Définit les structures de données de base utilisées dans le projet. / *Defines the basic data structures used in the project.*
+  * **`ImgTools`** : Fournit des fonctions utilitaires pour le redimensionnement et le positionnement des images. / *Provides utility functions for image resizing and positioning.*
+  * **`Cache`** : Gère toute la logique de chargement en arrière-plan et de mise en cache des images. / *Manages all the background loading and image caching logic.*
+  * **`Thumbs`** : Contient le gadget principal (`ThumbsGadget`) et gère l'affichage, les événements et les interactions utilisateur. / *Contains the main gadget (`ThumbsGadget`) and handles display, events, and user interactions.*
+
+-----
+
+## Prérequis et Compilation / Prerequisites and Compilation ⚙️
+
+Pour compiler et utiliser ce projet, vous aurez besoin de :
+*To compile and use this project, you will need:*
+
+  * **PureBasic 6.04 LTS (x64)** ou une version plus récente. / *or a more recent version.*
+  * **Système d'exploitation / OS :** Windows (testé principalement sur cette plateforme / *tested mainly on this platform*).
+
+### Options du Compilateur / Compiler Options
+
+Assurez-vous que les options suivantes sont activées dans les paramètres de votre compilateur.
+*Make sure the following options are enabled in your compiler settings.*
+
+  * ✅ **Activer le support des threads (Thread-Safe)** : Essentiel pour le système de cache. / *Essential for the caching system.*
+  * ✅ **Activer la prise en charge DPI (DPI-Aware)** : Pour un affichage correct sur les écrans modernes. / *For correct display on modern screens.*
+
+-----
+
+## Comment l'utiliser ? / How to Use It? 🚀
+
+L'intégration du gadget dans votre propre fenêtre est simple. Voici un exemple de base.
+*Integrating the gadget into your own window is simple. Here is a basic example.*
+
+```purebasic
+;- Incorporez les modules du projet ici / Include the project's modules here
+
+Global NewList CurrentList.s()
+Global CurrentListMutex.i = CreateMutex()
+
+; 1. Créez une fonction de rappel (callback) pour charger les chemins d'images
+; 1. Create a callback function to load the image paths
+Procedure CallBackLoadFiles(GadgetId.i, Index.i, Length.l)
+  Protected n.l, TmpIndex.i
+  Protected *Ptr.Core::FileData
+
+  LockMutex(CurrentListMutex)
+  For n = 1 To Length
+    TmpIndex = Index + n - 1
+    If TmpIndex >= 0 And TmpIndex < ListSize(CurrentList())
+      SelectElement(CurrentList(), TmpIndex)
+      
+      ; On demande au cache de préparer le fichier / Ask the cache to prepare the file
+      *Ptr = Cache::GetFileDataFromCache(CurrentList())
+      ; On lie le pointeur de données à l'index de la vignette / Link the data pointer to the thumbnail index
+      Thumbs::AddImageToThumb(GadgetId, TmpIndex, *Ptr)
+    EndIf
+  Next
+  Thumbs::LimitIndex(GadgetId, ListSize(CurrentList()))
+  UnlockMutex(CurrentListMutex)
+EndProcedure
+
+
+; 2. Créez votre fenêtre et le gadget / Create your window and the gadget
+If OpenWindow(0, 0, 0, 800, 600, "Exemple de Vignettes / Thumbnail Example", #PB_Window_SystemMenu | #PB_Window_ScreenCentered | #PB_Window_SizeGadget)
+  
+  ; Créez le gadget en spécifiant la taille des vignettes et la fonction de rappel
+  ; Create the gadget, specifying the thumbnail size and the callback function
+  Thumbs::ThumbsGadget(1, 0, 0, WindowWidth(0), WindowHeight(0), 128, @CallBackLoadFiles())
+  
+  ; 3. Remplissez votre liste de chemins d'images / Populate your list of image paths
+  LockMutex(CurrentListMutex)
+  ExamineDirectory(0, "C:\Your\Images", "*.jpg")
+  While NextDirectoryEntry(0)
+    AddElement(CurrentList())
+    CurrentList() = "C:\Your\Images\" + DirectoryEntryName(0)
+  Wend
+  FinishDirectory(0)
+  UnlockMutex(CurrentListMutex)
+  
+  ; 4. Forcez la mise à jour pour afficher les nouvelles images / Force an update to display the new images
+  Thumbs::ForceUpdate(1)
+
+  ; Boucle d'événements classique / Classic event loop
+  Repeat
+    Select WaitWindowEvent()
+      Case #PB_Event_CloseWindow
+        Quit = 1
+      Case #PB_Event_SizeWindow
+        ResizeGadget(1, 0, 0, WindowWidth(0), WindowHeight(0))
+    EndSelect
+  Until Quit = 1
+  
+  Thumbs::FreeThumbsGadget(1)
+EndIf
+```
+
+-----
+
+## Auteur / Author ✍️
+
+  * **Thyphoon**
+
+## Licence / License 📜
+
+Ce projet est distribué sous une licence libre et non restrictive. Vous pouvez l'utiliser, le modifier et le distribuer sans contrainte. Un crédit est apprécié mais non obligatoire.
+
+*This project is distributed under a free and unrestricted license. You can use, modify, and distribute it without constraints. Credit is appreciated but not required.*