XFRX.FR
Produits Contacts Divers

Manuel XFRX

Préambule

Ne pas inclure la version de démonstration de xfrx dans un projet. (Voir la rubrique FAQ).

Installation

Dé-zipper le fichier archive zip.
Pour un aperçu rapide des possibilités lancez DEMO.SCX.
Consultez la rubrique FAQ et son exemple.

 

XFRX est composé de 4 fichiers :

  • XFRX.APP - C'est l'application XFRX
  • HNDLIB.DLL
  • XFRXLIB.FLL
  • ZLIB.DLL - (Utilitaire de compression "freeware", voir www.zlib.org pour plus d'information)

Remarque : Ces librairies doivent être dans le même répertoire que XFRX.APP ou dans le chemin PATH.

Lancer XFRX


  1. Appeler XFRX avec le paramètre "XFRX#INIT"

    loSession=XFRX("XFRX#INIT")

    Une référence d'objet de la classe XFRXSession sera retournée.

  2. Appeler la méthode SetParams pour fixer les paramètres de génération du document.  

    lnRetVal = loSession.SetParams(, , , , , , )

    Paramètres :

    Le nom du document à créer.
    Répertoire où les fichiers temporaires pourront être créés.
    Si rien n'est précisé alors les fichiers temporaires pourront être créés dans le répertoire courant
    [facultatif]
    si fixé à .T. : les documents ne seront pas ouvert après génération
    [facultatif]
    C'est le 'codepage' du document généré.
    [facultatif].
    Si vous ne spécifiez pas ce paramètre alors cpcurrent() est utilisé.
    si fixé à .T.  : aucun message sera affiché.
    [facultatif]
    Cette option est utile si votre application n'est pas en anglais et/ou vous ne voulez pas voir le message "Processing..." et les message d'erreur dans votre code.
    (Cette option est indispensable si vous générez un COM+ en DLL)
    Par défaut, les documents Word(1) seront générés dans la session Word(1) actuelle, si elle existe.
    Si ce paramètre est fixé à .T., le document sera toujours ouvert dans une nouvelle session de Word(1).
    Cette option n'est pas utilisée pour les documents PDF.
    [facultatif]
    Utilisez :
    "DOC" pour les documents Word(1),
    "PDF" pour les documents PDF,
    "HTML" pour les documents HTML,
    "MHT" pour les documents MHT,
    "CNT" pour les objets 'container' (regardez Prévisualisation des rapports dans un objet "container" pour plus d'information).
    "DOC" est la valeur par défaut.
    [facultatif]


    Valeurs retournées :
    0 ... Tout est OK
    -1 ... n'a pas pu charger Word(1)
    -2 ... la version de Word(1) n'est pas en version 2000 ou ultérieure
    -3 ... impossible d'accéder au fichier destination à créer
    -4 ... destination inconnue
    -5 ... librairie hndlib.dll non trouvée
    -6 ... librairie xfrxlib.fll non trouvée
    -7 ... librairie zlib.dll non trouvée

  3. Appeler la méthode ProcessReport pour transformer le rapport en document Word(1) (vous devrez probablement d'abord préparer des données pour le rapport):

    loSession.ProcessReport(, , , , , )

    Paramètres :

    nom du rapport
    Contenu de la clause FOR
    [facultatif]
    Le commutateur de la clause SUMMARY.
    Si fixé à .T. le rapport est généré comme si la clause SUMMARY était utilisée dans la commande "REPORT FORM"
    [facultatif]
    La chaine correspondante aux clauses de portée du rapport (comme NEXT 4, REST, ALL, RECORD nRecno).
    Par défaut la valeur est "ALL"
    [facultatif]
    La clause "WHILE"
    [facultatif]
    Fixer ce paramètre à .T. pour placer la sortie HTML au format entier. Le format entier ne produit pas de coupure de page au document : une longue page sera produite.
    La valeur par défaut est .F.


    Exemple :

    loSession.ProcessReport("myreport", "customer=30", .f., "NEXT 10", "!empty(invoiceNo")

    Vous pouvez répéter l'appel de la méthode ProcessReport pour différents rapports autant de fois que vous en avez besoin. 

  4. Appeler la méthode Finalize() pour terminer la génération du document :

    loSession.finalize()

    Après cet appel, le fichier souhaité est créé, et, sur option, la visualisation de ce document est lancée.

  5. Vous pouvez aussi appeler la méthode ResetPageNo() si vous voulez remettre à zéro le numéro de page des rapports intermédiaires.

Ajouter des hyperliens

Les hyperliens sont déterminés via la zone Comment (commentaires) de chaque objet du générateur de rapport.
Pour créer un lien, vous avez besoin d'une zone source (le texte souligné que vous cliquerez) et d'une zone de destination (l'endroit que vous obtenez quand vous aurez cliqué sur lien source).
  1. Création d'une zone source
    Saisissez le texte suivant dans la zone 'comment' d'un objet du générateur de rapport :

    #UR A HREF=

    Le nom de destination est une expression, qui est évaluée au moment de la production de l'état. Vous pouvez diriger vers d'autres zones dans le même document, ou vers n'importe quelle URL.
    Les destinations vers des zones du même document doivent être précédées d'un #.

    Exemples :
    #UR A HREF="#top"
    Ajoute un lien cliquable vers le début du document.
    "top" est un mot reservé (ne pas nommer une zone "top" de destination).

    #UR A HREF="#custlist"
    Ajoute un lien cliquable vers une zone du même document nommée "custlist".

    #UR A HREF="#"+customer.id
    Ajoute un lien cliquable vers une zone du même document nommée eval(customer.id).

    #UR A HREF="http://www.xfrx.net"
    Ajoute un lien cliquable vers la page d'accueil du site xfrx.net.

  2. Création d'une zone de destination
    Pour ajouter un nom de zone de destination, saisissez le texte suivant dans la zone 'comment' d'un objet du générateur de rapport :

    #UR A NAME=

    Exemple :
    #UR A NAME="#"+customer.id
    Cette zone sera la destination des liens ayant comme zone source HREF="#"+customer.id

Création de signets

Remarque : la création de signets ne concerne que les documents PDF et HTML

 

Les signets servent de 'table des matières' en permettant de résumer la structure du document. Les utilisateurs peuvent utiliser les signets pour cliquer et se diriger directement vers la partie du document qui les intéresse. Pour ajouter un signet dans une document, il suffit de saisir le texte suivant dans la zone 'comment' d'un objet du générateur de rapport :

#UR OUTLINE=

Le est une expression, qui est évaluée au moment de la génération du rapport et le résultat est utilisé pour créer l'entrée dans la table des signets. Si l'utilisateur clique sur cette entrée de signet, alors il navigue et arrive sur la zone correspondante à ce champ de destination.

Exemple :
Dans un rapport ayant une liste de factures groupées par des clients, un signet contenant la liste des clients peut être créé en ajoutant :

#UR OUTLINE=invoices.customerName

dans la zone 'comment' de l'objet 'client' du générateur de rapport (ou dans n'importe quel autre objet que vous souhaitez, par exemple le premier champ de la page du client).

Pour activer les signets en sortie HTML, appelez

loSession.SetOtherParams("PRINT_BOOKMARKS",.t.)

 

avant d'appeler loSession.ProcessReport()

 

Avec les signets activés, XFRX doit générer 3 pages HTML (3 fichiers): la page principale définissant le cadre de page, la page des signets et la page avec le rapport.

Définir les propriétés des documents

Les méthodes suivantes peuvent être appelées pour définir les propriétés des documents. Pour la génération en document Word(1), les paramètres doivent être fixés avant la génération de la première page. Pour la génération en document PDF, les paramètres doivent être fixés avant l'appel à la méthode "Finalize()".

Propriétés Générales

loSession.setAuthor() : Auteur
loSession.setTitle()
loSession.setSubject() : Sujet
loSession.setKeywords() : Mots clefs


Propriétés pour les document PDF seulement

loSession.setCreator() : Créateur
loSession.setProducer() : Producteur


Propriétés pour les document DOC seulement

loSession.setComments() : Commentaires
loSession.setCategory() : Catégorie
loSession.setManager() : Responsable
loSession.setCompany() : Société

Ajouter une barre de progression

XFRX fournit un mécanisme simple d'appel à un outil permettant l'affichage d'une barre de progression pendant la génération du document.
Tout ce que vous avez à faire, c'est de créer une classe d'objet contenant un méthode "updateProgress()" et de passer une instance de cet objet à XFRX.

Pendant le processus de génération XFRX appellera la méthode "updateProgress()" après chaque page et chaque enregistrement traité.

Voici un exemple simplifié pour afficher la progression de la génération avec un "wait window":

loSession=xfrx("XFRX#Init")
loProgress = createobject("progress")
lnRetVal = loSession.SetParams("document",,,,,,"PDF")
if lnRetVal = 0
  loSession.setProgressObj(loProgress,2)
  loSession.ProcessReport("myReport")
  loSession.finalize()
endif
define class progress as custom
  procedure updateProgress
  lpara ta,tb, tc
    wait window nowait "Page #: "+alltrim(str(tb))+" Report #: "+alltrim(str(ta))+" ("+alltrim(str(tc))+"%)"
enddefine

 

L'objet de barre de progression est attaché à XFRX par l'appel de la méthode "setProgressObj()".
Cette méthode demande deux paramètres : le premier est l'objet de barre de progression et le second définit les informations à retourner à la méthode updateProgress().
  Il peut avoir deux valeurs :
    1 - seuls le numéro de page et le numéro de rapport sont transmis à la méthode updateProgress(),
    2 - le numéro de page, le numéro de rapport et le pourcentage de progression dans le rapport en cours sont transmis.
   L'utilisation du pourcentage est plus précis et plus approprié pour visualiser une barre de progression, mais pour faire cela, XFRX doit calculer le nombre d'enregistrements traités, et cela, peut parfois, demander beaucoup de temps.
La méthode "updateProgress" prend ces trois paramètres respectivement :
  le numéro de rapport actuel, le numéro de page actuel, le pourcentage actuel du rapport en traitement.

Utilisation d'une référence à 'THISFORM'

XFRX supporte l'utilisation de "THISFORM" dans l'expression d'une zone du rapport. Cependant, dans une application VFP normale, XFRX ne peut pas accéder à l'objet "THISFORM" directement. Pour cela, l'objet "THISFORM" peut être explicitement passé à XFRX via la méthode "setThisform()".
L'utilisation est vraiment simple : si vous avez "THISFORM" dans votre rapport, appelez "xfrxSession.setThisform(THISFORM)"
avant l'appel de "ProcessReport()"

Chiffrage des documents PDF

Les documents PDF peuvent être cryptés. Pour activer le cryptage appelez la méthode "setPasswords" : loSession.setPasswords(mot de passe propriétaire, mot de passe utilisateur)Le "mot de passe utilisateur" peut être vide. Si le "mot de passe propriétaire" est vide, alors une chaine aléatoire est générée pour le mot de passe.

 

Le propriétaire peut faire ce qu'il veut du document.
Les permissions données à l'utilisateur peuvent être définies en utilisant la méthode "setPermission" :

 

loSession.setPermissions(tlPrintDocument, tlModifyDocument, ;
tlCopyTextAndGraphics, tlAddOrModifyAnnotations)

 

Les valeurs des permissions par défaut sont fixées à .F. (faux).

 

Exemple :
Le code suivant produira et cryptera un document de pdf. L'utilisateur ne pourra ni imprimer, ni modifier, ni copier le texte du document, mais il pourra ajouter ou modifier des annotations :

 

local loSession, lnRetval
loSession=EVALUATE([report("XFRX#INIT")])
lnRetVal = loSession.SetParams("out.pdf",,,,,,"PDF")
If lnRetVal = 0
  loSession.setPasswords("ownerpassword","userpassword")
  loSession.setPermissions(.f.,.f.,.f.,.t.)
  loSession.ProcessReport("myreport")
  loSession.finalize()
Endif

 

Remarque : pour le calcul MD5 , XFRX utilise "RSA Data Security, Inc. MD5 Message-Digest Algorithm."

Ajout de police de caractères dans les documents PDF (font embedding)

XFRX supporte l'ajout dans un document PDF : d'une police complète de caractères, ou d'une partie de la police (seulement les caractères utilisés).

Pour ajouter tous les caractères de toutes les "fonts" utilisées : loSession.setEmbeddingType(2)

avant de lancer le rapport.

Pour ajouter seulement les caractères utilisés :

loSession.setEmbeddingType(3)

 

L'ajout des caractères utilisés uniquement, réduit la taille du fichier généré.

 

Pour sélectionner uniquement une police de caractères particulière à ajouter, (par exemple quand vous voulez seulement ajouter une police code à barre, où visualiser un document sur une machine qui ne dispose pas de cette police de caractères),  ajouter :

"#UR INCLUDEFONT" (sans les guillements) dans la zone "comment", d'un objet du générateur de rapport, utilisant cette police de caractères.

ajouter :
"#UR INCLUDEFONT SUBSET" pour ajouter seulement les caractères utilisés.

Rotation des objets dans un document PDF

Pour ajouter une rotation à un texte ou une image dans un document PDF,
ajouter :

"#UR ROTATE " (sans les guillements) dans la zone "comment" de l'objet du génération de rapport.

Le texte ou l'image subira une rotation dans le sens inverse des aiguilles d'une montre.
Par exemple pour imprimer verticalement, ajouter :

#UR ROTATE 90

Prévisualisation des rapports dans un objet "container"

  1. Ajouter une instance de la classe XFCONT (de la bibliothèque XFRXLIB.VCX) dans votre formulaire.
  2. Appelez la méthode "Reset" de l'objet XFCONT :
    thisform.xfcont1.reset()
  3. Initialiser l'objet session :
    local loSession, lnRetval
    loSession=EVALUATE([xfrx("XFRX#INIT")])
    lnRetVal = loSession.SetParams(,,,,,,"CNT")
  4. Attacher l'objet XFCONT dans l'objet session :
    loSession.SetOtherParams(thisform.xfcont1)
  5. Lancer la méthode ProcessReport() et Finalize() comme d'habitude : loSession.ProcessReport("demoreps\invinl""customer = '"+ALLTRIM(this.displayvalue)+"'")
    loSession.Finalize()

Regardez le formulaire de démonstration, pour voir un exemple de prévisualisation de rapport dans un objet "container".

Ajouter des mots de passe aux documents Word

Pour ajouter des mots de passe aux documents Word(1),
appelez la méthode SetPasswords() avant d'appeler la méthode ProcessReport() : loSession.setPasswords(tcReadPassword, tcWritePassword, tlRequirePassword)
Vous pouvez omettre l'un ou l'autre des tcReadPassword or tcWritePassword.

 

Le paramètre tlRequirePassword est optionnel (valeur par défaut à .F.)
S'il est fixé à .T., Word(1) demandera le mot de passe lors de l'ouverture du document.

Fractionner les documents Word

Quand les documents a générer sont très longs, l'application Word a des problèmes avec la conversion - cela prend très longtemps pour convertir. Pour éviter ce problème, XFRX permet maintenant de fractionner le document a générer en documents plus petits.

Pour réaliser cela,  appelez la méthode de SplitDocument() avant d'appeler ProcessReport() :loSession.SplitDocument(tnPages)

tnPagesp  étant le nombre de pages de chacun des documents résultant

Impression de certaines pages

Pour imprimer que certaines page, appelez la méthode de setPageRange() avant d'appeler ProcessReport().
Il y a deux manières possibles pour appeler la méthode de setPageRange() :
  • setPageRange(tnFrom, tnTo)
    tnFrom  et  tnTo définissent de la plage de page "From" à la page "To" .
    Si tnTo n'est pas précisé, le nombre total de page est utilisé

    Exemple:  Impression de la page numéro 5 à la page numéro 10loSession.setPageRange(5,10)
  • setPageRange(tcRange)
    tcRange est une chaine, qui peut contenir des numéros de page et des plage de page séparés par des virgules,
    la plage de page est définie comme "de-à".

    Exemple: Impression de la page 1, de la page 4, des pages 10 à 20 et la page 25loSession.setPageRange("1,4,10-20,25")

Spécifier le format de la page

Vous pouvez définir le format de page du document à produire.
Si vous spécifiez le format de page, cela remplace le format de page spécifié dans le rapport.

Pour définir la taille des pages, appelez la méthode de setPaperSize() avec la largeur et la hauteur de papier en paramètres :setPaperSize(nUDPaperWidth, nUDPaperHeight)

 

L'unité est le pouce * 10000.

HTML Ajustement de taille de page

En produisant des documents en HTML, XFRX rend la page un peu plus court par défaut (de 1.65 pouce).

C'est parce qu'en imprimant avec Internet Explorer, deux lignes sont ajoutées à la page : un titre en entête et un texte en bas de page.

En appelant la méthode de ShrinkHeight(), vous pouvez supprimer cette marge en appelant :ShrinkHeight(0)

 

ou placer votre propre valeur de marge de page.
L'unité est le pouce * 10000, ainsi pour rendre la page plus courte de 2 pouces, appellez :

ShrinkHeight(20000)

 

La valeur fixée par la méthode de ShrinkHeight() est appliquée à tous les types de conversions, pas uniquement à HTML.

Interrompre le traitement de XFRX

Le traitement XFRX de la génération des documents peut être interrompu en fixant à 1 la variable globale gnStopXFRX.

Par exemple, vous pouvez, l'employer de cette façon :
ON KEY LABEL Esc gnStopXFRX = 1

Documentation «EQEUS»

Reproduction totale ou partielle strictement interdite • KitWebWan AgainDesign or DeclineValid XHTML 1.0 Transitional