Create Reports with Gambas

Brouillon non corrigé

Créer des états d'impression avec Gambas

Cela fait près de dix ans que j'ai commencé a programmer le composant gb.Report. Et comme beaucoup de développeur passionné j'ai bien entendu oublié de communiquer autour de celui-ci. Je vais donc essayer à partir d'aujourd'hui de combler ce vide.

Les états d'impression à la Gambas ?

Il faut commencer par bien se mettre en tête que on ne va pas concevoir un état d'impression avec gb.report comme avec les autres éditeurs d'état existants. En effet, gb.Report réutilise le principe d'arrangement automatique sous contrainte de l'éditeur de formulaire de l'IDE et l'étend à un environnement physique qu'est l'impression. Pour faire simple, on ne manipule pas des sections mais des objets (conteneurs, widgets) qui vont fournir un contexte grâce à un ensemble de propriétés.

Nous allons donc commencer par étudier les deux types d'objets de base qui sont les conteneurs (ReportContainer) et les contrôles (ReportControl) sachant bien sur qu'un conteneur est un contrôle aussi.

Les contrôles

Un contrôle ReportControl va fournir un ensemble de propriétés de placement comme suit :

  • Left

  • Right

  • Width

  • Height

Ainsi que des propriétés de comportement :

  • Ignore

  • Expand

  • Autoresize

  • Fixed

Et des propriétés d'espacement :

  • Padding

  • Margins

Les propriétés de placement

Il s'agit de valeurs dans certaines unités. Elles peuvent être définies dans la fenêtre de propriété ou bien dans le code. 

MyReportLabel.Left = "1cm"
MyReportLabel.Top = "10mm"
MyReportLabel.Width = "50%"
MyReportLabel.Height = "1in"

Seules quelques unités sont supportées... on va dire les plus standards et donc pratiquement celles existantes en html. Soit : "m", "cm", "mm", "in", "pt", "px". Pour ce qui est de la définition des tailles ou placement, les valeurs relatives en % sont acceptées. Mais pour toutes autres tailles elle généreront une erreur.

Les valeurs Left et Top n'auront d'effet que si la propriété Ignore du contrôle est à True ou bien si son conteneur a une propriété arrangement à none. (Seule le container panel fournit cette propriété pour le moment). De plus ces valeurs sont relatives à la position du conteneur. Donc les valeurs de l'ensemble des conteneurs d'un contrôle vont se cumuler.

Si les valeurs Width et Height sont Null, alors le contrôle se comporte comme si sa propriété Autoresize = True.

Les propriétés de comportement

Elles sont essentielles.

  • Autoresize: va indiquer au contrôle qu'il doit demander à son contenu de lui fournir la taille Hauteur/Largeur minimale pour l'afficher.

  • Ignore: demande au moteur d'arrangement d'ignorer les instructions du conteneur pour ce contrôle. Attention, cependant le placement est toujours relatif au conteneur.

  • Expand: de loin la propriété la plus utile. Elle indique au moteur d'arrangement que le contrôle veux partager l'espace vacant du conteneur. Il va donc s'étendre sur cette place disponible. Si plusieurs contrôles font la même demande dans un même conteneur, alors l'espace libre est partagé entre eux.

  • Fixed: et bien non ... Celle-ci aussi est très utilisée, elle indique à un conteneur de ré-afficher le contrôle à chaque fois que l'instance du dit conteneur est rappelée. C'est un peu obscur comme concept mais je vais l'expliquer dans un autre chapitre concernant le déroulement de l’exécution de l'état.

Les propriétés d'espacement

  • Padding: la propriété padding retourne un instance vers un objet ReportPadding. Cet objet a 4 propriétés Left, Right, Top, Bottom. Il définit l'espace séparant le contenu du contrôle ; de son contour. Il peut être défini via la zone de propriété de l'IDE ou bien via le code : 
    MyReportLabel.Padding.Left = "5mm"'
    ou 
    Setup the 4 properties at the same size in one shot
MyReportLabel.Padding = ReportPadding["5mm"]
    ou 
    MyReportLabel.Padding = ReportPadding["Top:1mm;Bottom:1mm;Left:1mm;Right:1mm"]

  • Margin: la propriété padding retourne un instance vers un objet ReportMargin. Cet objet a 4 propriétés Left, Right, Top, Bottom. Il définit l'espace. séparant la bordure du contrôle de son conteneur et des autres éléments contenus dans le même conteneur. Il s'agit d'un espace minimal. Ainsi deux élément se suivant dans un conteneur seront séparés par le plus grand espace défini par les éléments ou bien par la valeur de Spacing du conteneur si elle est supérieure. Il peut être défini via la zone de propriété de l'IDE ou bien via le code : 
    MyReportLabel.Margin.Left = "5mm"
    ou 
    Setup the 4 properties at the same size in one shot
MyReportLabel.Margin = ReportMargin["5mm"]
    ou 
    MyReportLabel.Margin = ReportMargin["Top:1mm;Bottom:1mm;Left:1mm;Right:1mm"]

Les Conteneurs

Ils hérites tous de la classe ReportContainer:
  • ReportVbox

  • ReportHBox

  • ReportPanel

  • ReportVPanel(Pas Stable)

  • ReportHPanel (A Faire)

ReportPanel a une propriété Arrangement qui permet de définir la routine d'arrangement. En fait les autres conteneurs ne sont que des versions statiques de chacune des options mise à par la valeur None qui n'existe que dans ce conteneur.

Ces conteneurs fournissent la propriété Spacing qui permet de définir l'espacement entre les contrôles contenus dans ceux-ci. (Vous pouvez relire la partie concernant la propriété Margin pour en comprendre le fonctionnement).

La classe Report hérite du reportVBox.

Arrangement = None

Cette valeur indique au moteur de rendu que les éléments contenus dans ce conteneur ne seront pas organisés par celui-ci. Ceci permet le placement manuel d'élément dans ce conteneur à l'aide des propriétés de placement.

Cette fonction est très utile pour le remplissage de formulaires pré-imprimés par exemple.

Arrangement = Horizontal ou ReportHBox

Cette valeur indique au moteur de rendu que les contrôles contenus dans ce conteneur doivent être rangés horizontalement. La hauteur des contrôles sera alors celle du conteneur moins le Padding haut et bas moins le Margin haut et bas du contrôle.

Si un élément ne loge pas dans le conteneur alors il est ignoré.

Quel que soit le mode d'arrangement, l'ordre des éléments suit l'ordre hiérarchique des enfants du conteneur (zorder).

Arrangement = Vertical ou ReportVBox

Cette valeur indique au moteur de rendu que les contrôles contenus dans ce conteneur doivent être rangés verticalement. La largeur des contrôles contenus sera alors celle du conteneur moins le Padding droite et gauche moins le Margin Droite et Gauche du contrôle.

C'est le mode par défaut du Report.

Si un élément ne loge pas dans le conteneur alors le moteur génère une nouvelle page et répète le conteneur et ses parents puis continue à lister les éléments. Si vraiment il n'y a pas de solution alors l'élément est affiché tronqué.

Arrangement = Fill

Cette valeur indique au moteur de rendu que les contrôles doivent complètement couvrir le conteneur moins bien sur les Padding et Margin.

Arrangement = Row

Pas encore vraiment stable. Il permettra aux contrôles de s'organiser en lignes. La hauteur de chaque ligne est définie par l'élément le plus haut de celle-ci.