Classe Application

Module :	WinLib.Application
Héritée de :	object
Version :	1.0 - 2024
Classes dérivées :

Cette classe définit le fonctionnement de la fenêtre principale d'une application Window.

L'application peut être localisée en passant l'acronyme du langage souhaité à l'instanciation. Les paramètres de localisation sont fournis dans un fichier json. La bibliothèque WinLib fournit deux fichier de localisation qui embarquent les fonctionnalités de base : fr.json pour le français et en.json pour l'anglais. Mais il est possible d'ajouter et de traduire d'autres fichiers à volonté selon les langues souhaitées. Voir l'article sur la localisation pour la compréhension de la structure de ces fichiers.

Attributs d'instance

self.local

Cet attribut est le dictionnaire des données de localisation. Voir l'article sur la localisation pour l'usage.

self.root

Cet attribut est l'instance de la class tk.Tk du module TkInter utilisée par l'application. Elle constitue la racine de l'arobrescence des Widgets constitutifs de l'application.

self.menuBar

C'est l'instance de la classe tk.Menu relative au menu principal de la fenêtre de l'application. En principe, ce menu est chargé à partir du fichier de localisation. Mais il peut être modifié par programmation en utilisant les primitives de TkInter en surchargeant la méthode self.createTopMenu.

self.toolBar

C'est la barre d'outils affichée en haut de la fenêtre principale. Il s'agit d'une instance de la classe WinLib.ToolBar. Cette barre d'outils est composée de boutons. Par défaut, les boutons sont relatifs aux commandes des menus Fichier et Edition. Mais elle peut être modifiée en surchargeant la commande self.createToolBar.

self.statusBar

C'est la barre de status affichée en bas la la fenêtre principale. Il s'agit d'une instance de la classe WinLib.StatusBar. Cette barre de status est composée de zones d'affichage dérivées de la classe StatusItem. Elle fonctionne comme un dictionnaire. Par défaut, une zone est déjà installée pour aficher les coordonnées de la souris (indexée par la clef "position"). Elle peut être complétée et modifiée en surchargeant la commande self.createStatusBar.

self.mainView

C'est typiquement la fenêtre qui affiche le fonctionnement réel de l'application. Par défaut, c'est une instance de la classe tk.Frame qui est est affichée. Cette instance ne fait absolument rien. C'est au développeur de créer une classe dérivée pour son application et de l'instancier dans la méthode self.createMainView. :attribute mainView: Instance du Frame princpal de l'application.

self.resources

Cet attribut est un dictionnaire de toutes les images utilisées par l'application. Les images doivent être contenues dans un dossier nommé ./resources situé à la racine du projet Python. Elles sont chargée automatiquement dans le dictionnaire à l'initialisation de l'application. Des dossiers alternatifs ou supplémentaires peuvent être chargés en invoquant la méthode self.loadResources dans la methode self.__init__ de l'application.

Les images contenues dans le dictionnaire sont des instances de ImageTk.PhotoImage (classe du module Pillow de Python) pour être prêtes à l'emploi dans les paramètres image de TkInter.

Méthodes publiques

self.init(self, localization='en')

Par défaut, le construteur de la classe Application effectue les opérations suivantes :

Chargement du fichier de localisation ddont l'acronyme est passé en paramètre.
Instanciation de la classe tk.Tk de TkInter. Cette instance est accessible par l'attribut self.root.
Chargement du dictionnaire des ressources images à partir du répertoire ./resources. Les ressources images sont accessibles par l'attibut self.resources["fichier"], où fichier est le nom du fichier contenant l'image.
Initialisation des paramètres de la fenêtre principale à partir des données de localisation.
Instanciation des widgets qui composent la fenêtre principale.
Lancement de la boucle des événements par l'invocation de la méthode mainloop() de la classe tk.Tk.

Il n'y a qu'un seul paramètre :

Paramètre	Type	Signification	Défaut
localization	String	Acronyme de la langue utilisée, 'fr' pour français, 'en' pour anglais, etc.	'en'

self.loadResources(pathname)

Cette méthode charge les ressources images dans le dictionnaire des ressources à partir du dossier passé en paramètre. Elle peut être invoquée dans le constructeur des classes dérivées pour charger des ressources supplémentaires ou alternatives à celle déjà chargée en standard. Son fonctionnement s'appuie sur le module Pillow de Python pour s'assurer sue les photos soient dans un format acceptable par TkInter.

Paramètre	Type	Signification	Défaut
pathname	String	Chemin relatif à la racine du projet du répertoire dans lequel se trouvent les fichiers images.

def __init__(self, localization="fr"):
super().__init__(localization)
self.loadResources(self, './mesresources')

self.createTopMenu(self, root)

Cette méthode est invoquée par le constructeur de l'application pour créer le menu principal. En fonction des environnements, le menu principal de l'application est embarqué dans la fenêtre principale, commme c'est le cas sous Windows, ou apparait en haut de l'écran, comme c'est le cas pour Mac-OS.

En principe, il n'est pas nécesssaire de surcharger cette méthode dans les classes dérivées, car le menu principal de l'application est construit automatiquement à partir des données enregistrée dans le fichier de localisation par la méthode self.parseMenu().

Paramètre	Type	Signification	Défaut
root	tk.Tk	Instance racine de la fenêtre principale de l'application.
retour	tk.Menu	Instance de la barre du menu principal.

self.parseMenu(self, menuBar, menudef)

Cette méthode est invoquée pour construire la structure d'un menu à partir de la définition JSON du menu. Cette méthode n'est utilisée que par la méthode self.createTopMenu() pour construire le menu principal de l'application à partir du fichier de localisation.

Paramètre	Type	Signification	Défaut
menuBar	Tk.Menu	Instance de la classe tk.Menu dans laquelle les items doivent être créés.
menuDef	Dictionnaire	Dictionnaire des commandes du mene définies au format JSON.

self.createToolBar(self, parent)

Cette méthode est invoquée par le constructeur de l'application pour créer la barre d'outils située en haut de la fenêtre principale de l'application.

Cette méthode peut être surchargée pour y ajouter ou y remplacer des boutons. Les boutons doivent être des innstance le la classe WinLib.ToolBarItem. La méthode doit renvoyer en résultat l'instance de la barre d'outil WinLib.ToolBar modifiée ou nouvellement créée.

Paramètre	Type	Signification	Défaut
parent	tk.Tk	Instance de la classe tk.Tk de la fenêtre principale.
retour	WinLib.ToolBar	Instance de la barre d'outil créée ou modifiée.

def createToolBar(self, parent):
    bar = super().createToolBar(parent)
    BarSeparator(bar)
    ToolBarItem(bar, self.resources['mon_outil.png'], command=self.mon_outil_action)
    return bar

self.createMainView(self, parent)

Cette méthode est invoquée par le constructeur de l'application pour instancier la fenêtre principale de l'application.

Cette méthode DOIT être surcharger pour implémenter effectivement les fonctionnalités de l'application. Son role est de créer une instance de la classe tk.Frame ou dérivée pour embarquer les interactions de l'utilisateur sur l'application. La méthode doit renvoyer cette instance en résultat.

Paramètre	Type	Signification	Défaut
parent	tk.Tk	Instance de la classe tk.Tk de la racine de la fenêtre principale.
retour	tk.Frame	Instance de la fenêtre principale.

def createMainView(self, parent):
    view = tk.Frame(parent, bg='ivory', relief='sunken', border="2")
    view.bind("<Button-1>", self.on_mouse_down)
    view.bind("<Button1-Motion>", self.on_mouse_move)
    view.bind("<Button1-ButtonRelease>", self.on_mouse_up)
    return view

self.createStatusBar(self, parent)

Cette méthode est invoquée par le constructeur de l'application pour créer la barre de status qui se trouve en bas de la fenêtre principale.

Cette méthode peut être surcharger pour y ajouter ou remplaccer des zones d'information suplémentaires.

La barre de status est une instance de la classe WinLib.StatusBar. Elle fonctionne comme un dictionnaire où chaque zone d'information est indexée par une clef. Pour être enregistrée dans le dictionnaire, chaque zone, instance de la classe WinLib.StatusBarItem, doit être ajoutée par l'invocation de la méthode addBarItem() de la classe StatusBar. Si la clef passée en paramètre existe déjà, le nouvel item remplace l'ancien.

Paramètre	Type	Signification	Défaut
parent	tk.Tk	Instance de la classe tk.Tk de la racine de la fenêtre principale.
retour	tk.Frame	Instance de la barre de status.

def createStatusBar(self, parent):
    bar = StatusBar(parent)
    bar.addBarItem('position', StatusBarItem(bar, text="Position: "))
    bar.addBarItem('taille', StatusBarItem(bar, image=self.resources['Size24.png']))
    return bar

self.createEmptyDocument(self)

Cette méthode est invoquée par la constructeur de l'application, ou lorsque l'utilisateur clique sur la commande Fichier/Nouveau.

Un document est un conteneur d'objets métier géré par l'application. Son contenu peut être enregistré dans un ficher selon le pattern Open/Save.

self.clearContent(self)

Cette méthode est invoquée chaque fois qu'un nouveau document vide est créé. Tous les widgets relatifs à l'affichage des objets métier doivent être supprimés.

Cette méthode doit être surchargée pour définir le mécanisme de suppréssion des widgets associés aux objets métier.

self.updateUI(self)

Cette méthode est invoquée chaque fois que le document a été modifié pour ajuster l'affichage des objets métier au contenu actualisé du document.

Cette méthode doit être surcharée pour afficher le contenu du document dans la fenêtre principale.

self.canCloseDocument(self)

Si le document a été modifié, une boite de dialogue est ouverte pour demander à l'utilisateur d'assumer de fermer le document sans l'enregistrer.

Cette méthode peut être invoquée pour savoir si le document peut être fermé. La méthode revoit True si le document peut être fermé, False sinon.

self.menu_file_new(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Nouveau. Il n'est pas nécessaire de la surchargée car le fonctionnement du modèle Open/Save est déjà implémenté dans la classe Application.

self.menu_file_open(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Ouvrir. Il n'est pas nécessaire de la surchargée car le fonctionnement du modèle Open/Save est déjà implémenté dans la classe Application.

self.menu_file_save(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Enregistrer. Il n'est pas nécessaire de la surchargée car le fonctionnement du modèle Open/Save est déjà implémenté dans la classe Application.

self.menu_file_save_as(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Enregistrer sous. Il n'est pas nécessaire de la surchargée car le fonctionnement du modèle Open/Save est déjà implémenté dans la classe Application.

self.menu_file_print(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Imprimer. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour définir le mécanisme d'impression du document métier qui dépend des données métier enregistrées dans le document.

self.menu_file_print_preview(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Fichier/Mise en page. Elle n'est pas implémenté par défaut dans la classe Application. Il faut donc la surcharger pour définir la vue de ce qui va être imprimé qui dépend des données métier enregistrées dans le document.

self.menu_application_exit(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande Fichier/Quitter. Il n'est pas nécessaire de la surcharger car le fonctionnement du modèle Open/Save est déjà implémenté dans la classe Application. Cette commande invoque la méthode canCloseDocument() pour éviter de quitter une application sans avoir enregistré le document auparavant.

self.menu_edit_undo(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Annuler. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

La mécanique Annuler/Rétablir est assez complexe à implémenter et dépend, d'une part des données métier gérées dans le document, et d'autre part des opérations possibles sur ces données pour lesquelles il faut définir un modèle numérique empilable. Un article ultérieur décrira l'implémentation d'une telle mécanique.

self.menu_edit_redo(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Rétablir. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

self.menu_edit_cut(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Couper. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

La mécanique du presse-papier est assez complexe à implémenter et dépend des données métier gérées dans le document. Un article ultérieur décrira l'implémentation d'une telle mécanique.

self.menu_edit_copy(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Copier. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

La mécanique du presse-papier est assez complexe à implémenter et dépend des données métier gérées dans le document. Un article ultérieur décrira l'implémentation d'une telle mécanique.

self.menu_edit_paste(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Coller. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

La mécanique du presse-papier est assez complexe à implémenter et dépend des données métier gérées dans le document. Un article ultérieur décrira l'implémentation d'une telle mécanique.

self.enu_edit_delete(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Supprimer. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir. Son implémentation dépend des données gérées dans le document.

self.menu_edit_select_all(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Edition/Sélectionner tout. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir. Son implémentation dépend des données gérées dans le document.

self.menu_help(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Aide/Aide. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

La mécanique d'aide dépend des opérations et de l'expérience utilisateur de l'appplication. Un article ultérieur décrira l'implémentation d'une telle mécanique.

self.menu_about(self, event=None)

Cette méthode est invoquée lorsque l'utilisateur clique la commande du menu Aide/A propos de. En principe, cette commande affiche la boite de dialogue qui expose les crédits de l'application. Elle n'est pas implémentée par défaut dans la classe Application. Il faut donc la surcharger pour la définir.

self.display_not_implemented_command(self)

Cette méthode déclenche l'affichage d'une boite d'alerte pour indiquer qu'une commande ou une fonctionnalité n'est pas encore implémentée. Elle est utilisée en interne par la classe application. Mais le développeur peut l'invoquer au cours du développement de l'application pour éviter un plantage lorsque une partie de l'application n'est pas encore terminée.

Le message affiché se trouve à la rubrique application/not_implemented_command dans le fichier de localisation.

self.displayExceptionMessageBox(self, caption, message, error, *args)

Cette méthode déclenche l'affichage d'une boite d'alerte. Elle peut être utilisée lorsque l'application lève une exception.

Le paramètre args est un tuple de valeurs qui peuvent être insérées dans le paramètre message.

Paramètre	Type	Signification
caption	String	Titre de la Message Box.
message	String	Message affiché dans la Message Box. Celui-ci doit comporter autant de champs {} qu'il y a de paramètre suppélentaires passés.
error	Exception	Exception levée dans une séquence try...except.
args	tuple	Liste de paramètres supplémentaires.

infos = self.local["operation1"]
try:
#...
except Exception as err:
self.displayExceptionMessageBox(infos["title"], infos["error_message"], err, param1, param2)