Apache OpenOffice Wiki - User contributions [en]

Database/FR/Database

2008-03-27T23:49:37Z

Wurzel: New page: = OpenOffice.org Base = Cette page sert comme page d'accueil pour de la documentation sur l'utilisation du module Base de la suite bureautique OpenOffice.org. Comme tout n'est pas encore...

= OpenOffice.org Base =

Cette page sert comme page d'accueil pour de la documentation sur l'utilisation du module Base de la suite bureautique OpenOffice.org.

Comme tout n'est pas encore traduit, il y a pour l'instant de nombreux pages encore en anglais. Ceci devrait changer au fur et à mesure de la progression de la traduction.

La page sera essentiellement constitué de liens vers des documents existants ou vers d'autres pages du projet de documentation française.

Ressources realtifs à OpenOffice.org Base:

== Manuels ==
=== Général ===
* Base
: [http://wiki.services.openoffice.org/wiki/Base Base]
: Description de Base (synthèse)

* Guides d'Utilisateur (Getting started with Base) - ''PDF''
: [http://documentation.openoffice.org/manuals/oooauthors2/0110GS-GettingStartedWithBase.pdf Getting started with Base]
: Apprendre comment créer une base de données, des requêtes, des formulaires, et des rapports et se connecter à, et utiliser, d'autres sources de données dans le module OOo-Base.

* Manuel OpenOffice.org Base
: [http://nothickmanuals.info/doku.php/articles:ooobaseprimer OpenOffice.org Base Primer]
: Initial Authors: Andre 'Drew' Jensen, Frank Schoenheit, et al.
: Un bref résumé avec captures d'écran sur l'utilisation de Base.

* Débutants - Base de Données Exemple - Tutoriel Base
: [http://www.oooforum.org/forum/viewtopic.phtml?t=25060 Example]
: Initial author: Andrew 'Drew' Jensen
: Ce tutoriel couvre la création d'une première base de données avec OOoBase. Il est destiné à ceux qui n'ont jamais utilisé OOoBase ou qui n'ont jamais utilisé de gestionnaire de base de données.

* Tutoriel OOoBase de Niveau Moyen
: [http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Tutorials/Base_%28Mariano%29 Base Tutorial]
: Initial author: Mariano
: ''-- en cours d'édition --''

* Base et Macros
: [http://www.pitonyak.org/database/ Pitonyak's document]
: Initial author: Andrew Pitonyak
: Cette documentation traite du pilotage d'une base de données avec des macros OpenOffice.org.

* Database: "ooBase", aka "Base"
: [http://sheepdogguides.com/fdb/fdb1main.htm Base Tutorial by Sheepdogguides.com]
: Initial author: TK Boyd
: Après une courte introduction, ce document explique comment faire des taches courantes telles qu'importer des données depuis d'autres tables.

* Importer des données dans le module de Base de Données OpenOffice 2.0
: [http://searchenterpriselinux.techtarget.com/tip/0,289483,sid39_gci1222186,00.html Database]
: Initial author: Solveig Haugland
: Tutoriel avec captures d'écran sur l'importation de données dans OOoBase.

=== Tables ===

* [[Standard Distributed Schema]]

=== Requêtes ===
* [[Built-in functions and Stored Procedures]]

=== Rapports ===
* [[SUN Report Builder]]
Il existe un assistant de création de rapports intégré directement dans la suite bureautique au niveau du module Base, mais celui-ci provient d'une programmation assez ancienne (du temps de StarOffice, c'est-à-dire avant la naissance du projet OpenOffice.org) et ne permet pas une grande flexibilité dans la réalisation de rapports. Toutefois, il peut servir pour des rapports simples dont la présentation est peu variable ou sophistiquée.

Sun a ainsi développé un outil supplémentaire, qui s'installe dans la suite comme une extension et dont les origines se trouvent dans les projets FreeReport et Pentaho, basés sur Java. Vous aurez compris qu'il est nécessaire, comme d'ailleurs pour d'autres fonctions du module Base, que votre système ait au préalable un environnement Java installé et fonctionnel compatible avec OpenOffice.org. Pour la plupart des systèmes d'exploitation, l'environnement Java qui convient le mieux est celui fourni par Sun et disponible en téléchargement gratuitement.

L'extension développé par Sun s'appelle Sun Report Builder (ou SRB). Il est disponible en libre téléchargement ici

Son utilisation est expliquée ici

* Sun Report Builder (Reference)
: [http://wiki.pentaho.org/display/Reporting/Pentaho+Reporting+Latest Reference]

* Fonctions dans le Générateur de Rapports
: [http://wiki.pentaho.org/display/Reporting/08.+Functions+and+Expressions Functions and Expressions]

* Fonctions dans les Rapports
: [http://wiki.services.openoffice.org/wiki/Base/Reports/Functions Funktions]

=== Développeur ===
* Base de travail pour améliorer le guide d'utilisateur
: [http://wiki.services.openoffice.org/wiki/Documentation/OOoAuthors_User_Manual/Getting_Started/Getting_Started_with_Base Getting_Started/Getting_Started_with_Base]

* Utilisation de Macros dans des Fichiers de Bases de Données
: [http://wiki.services.openoffice.org/wiki/Macros_in_Database_Documents Macros_in_Database_Documents]
: 'Specification to develop this functionality

=== FAQ ===
* Tâches courantes
: [http://wiki.services.openoffice.org/wiki/Common_tasks Common_tasks]
: Initial author: Andrew 'Drew' Jensen
: Beaucoup de questions, peu de réponses.

=== Divers ===
* HSQLDB Trucs et Astuces
: [http://wiki.services.openoffice.org/wiki/HSQLDB:Tips_and_Tricks Tips_and_Tricks]
: ''description followed''

* [http://nothickmanuals.info/doku.php/articles:ooobaseprimer http://nothickmanuals.info/doku.php/articles:ooobaseprimer]

* [http://www.baseusers.com/index.html http://www.baseusers.com/index.html]

== Connexions ==
* Nouveau Tutoriel OOoBase

[http://wiki.services.openoffice.org/wiki/Base_New_Driver_Tutorial http://wiki.services.openoffice.org/wiki/Base_New_Driver_Tutorial]

Initial author: Robert Vojta

This small How-To contains a simple step-by-step introduction on how to put your driver inside the connectivity module. The second part of this document covers differences between a driver in connectivity module and a driver in an UNO package.

* Amélioration des Pilotes de Bases de Données

[http://wiki.services.openoffice.org/wiki/BetterDatabaseDrivers http://wiki.services.openoffice.org/wiki/BetterDatabaseDrivers]

Initial author:Eric Bischoff

Quelques idées pour une infrastructure améliorée et plus simple pour des pilotes améliorés

* Connexion aux Bases de Données Microsoft Access

[http://wiki.services.openoffice.org/wiki/Connecting_to_Microsoft_Access http://wiki.services.openoffice.org/wiki/Connecting_to_Microsoft_Access]

Initial author: Regina Henschel

Ces articles décrivent comment se connecter à un fichier de base de données Access, si vous utilisez un système d'exploitation Windows.

* OpenOffice.org Base - Pilotes de Bases de Données

[http://dba.openoffice.org/drivers/ http://dba.openoffice.org/drivers/]

* Connexion aux Bases MySQL

[http://wiki.services.openoffice.org/wiki/Connect_MySQLandBase http://wiki.services.openoffice.org/wiki/Connect_MySQLandBase]

Sommaire

* Pilote PostgreSQL

[http://dba.openoffice.org/drivers/postgresql/index.html http://dba.openoffice.org/drivers/postgresql/index.html]

* Pilote SQL-lite

http://dba.openoffice.org/drivers/sqlite/index.html

* Pilote mdb

[http://dba.openoffice.org/drivers/mdb/index.html http://dba.openoffice.org/drivers/mdb/index.html]

Initial author: Wind Li (yl146652 [at] openoffice [dot] org)

Il s'agit d'une tentative de créer un pilote sous Linux pour se connecter à une base de données MS Access. Le développement a été arrêté.

* Page de Travail

[http://wiki.services.openoffice.org/wiki/MDB_Driver_Integration http://wiki.services.openoffice.org/wiki/MDB_Driver_Integration]

* FAQ MSA-Base

[http://wiki.services.openoffice.org/wiki/MSA-Base_Faq http://wiki.services.openoffice.org/wiki/MSA-Base_Faq]

* Pilote Firebird
[http://jaybirdwiki.firebirdsql.org/jaybird/doku.php?id=config:oobase Jaybird OpenOffice.org Base support]

== Exemples ==
=== Général ===
* Base Exemple (Overview)

[http://wiki.services.openoffice.org/wiki/Category:Base_Example http://wiki.services.openoffice.org/wiki/Category:Base_Example]

Initial author: Frank Schönheit

* Standard Distributed Schema

[http://wiki.services.openoffice.org/wiki/Standard_Distributed_Schema http://wiki.services.openoffice.org/wiki/Standard_Distributed_Schema]

=== Exemples Concrets ===
* Base de Données Membres d'un Club / Association

[http://wiki.services.openoffice.org/wiki/A_club_membership_database http://wiki.services.openoffice.org/wiki/A_club_membership_database]

Initial author: Andrew 'Drew' Jensen

Description de la création d'une base de données d'exemple

* OpenOffice.org API - Code snippets: [http://codesnippets.services.openoffice.org/Database/index.xml http://codesnippets.services.openoffice.org/Database/index.xml] Useful code snippets solving frequently asked questions.

* Exemple de Base de Données

http://wiki.services.openoffice.org/wiki/Help_Files

http://wiki.services.openoffice.org/wiki/Standard_Distributed_Schema

== Divers ==
== Tests ==
* [http://wiki.services.openoffice.org/wiki/Database_Automatic_Testing http://wiki.services.openoffice.org/wiki/Database_Automatic_Testing]
* [http://wiki.services.openoffice.org/wiki/Documentation/OOoAuthors_User_Manual/Base_Guide/Planning http://wiki.services.openoffice.org/wiki/Documentation/OOoAuthors_User_Manual/Base_Guide/Planning]
* [http://wiki.services.openoffice.org/wiki/FAQ_%28Base%29 http://wiki.services.openoffice.org/wiki/FAQ_%28Base%29]

* [http://wiki.services.openoffice.org/wiki/OOoHelpOutline#Base_and_Database http://wiki.services.openoffice.org/wiki/OOoHelpOutline#Base_and_Database]

*
* [http://ericzander.com/Publications/OO_MySQL_Tutorial/index.htm http://ericzander.com/Publications/OO_MySQL_Tutorial/index.htm]
Connecting OpenOffice.org To A Remote MySQL Database] (event. 1.x)

Documentation/Dashboard/Tutorials/Base (Mariano)

2008-02-26T16:46:21Z

Wurzel: /* Scope */

==Scope==

<cite>The tutorial is aimed at persons that have little or no knowledge in
database design and that need to develop a functional application of
mid-level complexity. This application would stand alone in their
computers (as opposed to becoming a front end for a MySQL application
harbored in some server with multiple users, for example).</cite>

The tutorial is centered on the problem of establishing and using primary keys for populating and retrieving records in several tables. Of course, this requires understanding the concept of functional dependency and data normalization and how to implement them in an application.

Other concepts that are relevant to understanding these topics are also summarily reviewed.

The following is a draft proposal for this tutorial:

1. Introduction: some words to calm the anxiety of the reader and offer an overview of the paper.

1.1 Working with Base: advantages, feel and the implications of an integrated suite

1.2 Description and definition of a relational database

1.3 Purpose and goals of appropriate database design

1.4 The importance of functional dependency and the primary key

1.5 The importance of normalized data entry

1.6 The importance of proper design in forms and reports

1.7 Why you can expect to spend more time thinking about your database design that actually implementing it (and why this is a good thing!)

2. Tools of the trade:

2.1 Elements of UML

2.2 Phases in database design

2.3 Brief -brief- approximation to first, second and third normal form

2.4 Using OOo during design phase

3. Putting it all together: Working example in OOo Base

3.1 Presenting problem and possible solution

3.2 The tables and their relationships

3.3 Making sure that records are properly linked

3.4 Entering data for one subject in several tables

3.5 Entering data for one subject in several records in another table

3.6 Masking data entry and other ways to check data entry

3.7 Using drop-down lists for data entry

3.7.1 Dynamically populating drop down-lists from fields in another table

3.8 Timestamping data entry

3.9 Retrieving data from one table

3.10 Updating data for one record showing previously entered data

3.11 Retrieving data for one subject spread in several tables

3.12 Retrieving individual data from a collection of subjects

3.13 Retrieving summary data from a collection of subjects

Documentation/Dashboard/Tutorials/Base (Mariano)

2008-02-26T16:45:29Z

Wurzel: /* Scope */

==Scope==

<cite>The tutorial is aimed at persons that have little or no knowledge in
database design and that need to develop a functional application of
mid-level complexity. This application would stand alone in their
computers (as opposed to becoming a front end for a MySQL application
harbored in some server with multiple users, for example).</cite>

The tutorial is centered on the problem of establishing and using primary keys for populating and retrieving records in several tables. Of course, this requires understanding the concept of functional dependency and data normalization and how to implement them in an application.

Other concepts that are relevant to understanding these topics are also summarily reviewed.

The following is a draft proposal for this tutorial:

1. Introduction: some words to calm the anxiety of the reader and offer an overview of the paper.

1.1 Working with Base: advantages, feel and the implications of an integrated suite
1.2 Description and definition of a relational database
1.3 Purpose and goals of appropriate database design
1.4 The importance of functional dependency and the primary key
1.5 The importance of normalized data entry
1.6 The importance of proper design in forms and reports
1.7 Why you can expect to spend more time thinking about your database design that actually implementing it (and why this is a good thing!)

2. Tools of the trade:

2.1 Elements of UML
2.2 Phases in database design
2.3 Brief -brief- approximation to first, second and third normal form
2.4 Using OOo during design phase

3. Putting it all together: Working example in OOo Base

3.1 Presenting problem and possible solution
3.2 The tables and their relationships
3.3 Making sure that records are properly linked
3.4 Entering data for one subject in several tables
3.5 Entering data for one subject in several records in another table
3.6 Masking data entry and other ways to check data entry
3.7 Using drop-down lists for data entry
3.7.1 Dynamically populating drop down-lists from fields in another table
3.8 Timestamping data entry
3.9 Retrieving data from one table
3.10 Updating data for one record showing previously entered data
3.11 Retrieving data for one subject spread in several tables
3.12 Retrieving individual data from a collection of subjects
3.13 Retrieving summary data from a collection of subjects

FR/Documentation/Base/SUN Report Builder

2008-02-26T09:50:19Z

Wurzel: /* Syntaxe */

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport. La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" de part et d'autre de la chaîne de caractères pour la citer
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définies par l'Utilisateur''' 
Mapped, Null

Une explication détaillée peut être trouvée [http://wiki.services.openoffice.org/wiki/Documentation/FR/Base/Rapports/Fonctions ici.]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/SUN Report Builder

2008-02-26T09:47:03Z

Wurzel: /* Fonctions Supportées */

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport. La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définies par l'Utilisateur''' 
Mapped, Null

Une explication détaillée peut être trouvée [http://wiki.services.openoffice.org/wiki/Documentation/FR/Base/Rapports/Fonctions ici.]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/SUN Report Builder

2008-02-26T09:44:49Z

Wurzel: /* Fonctions Supportées */

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport. La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définies par l'Utilisateur''' 
Mapped, Null

Une [[Base/Rapports/Fonctions|explication]] détaillée peut être trouvée [[Base/Rapports/Fonctions|ici.]]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/SUN Report Builder

2007-12-22T22:48:13Z

Wurzel:

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport. La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définies par l'Utilisateur''' 
Mapped, Null

Une [[Base/Reports/Functions|explanation]] détaillée peut être trouvée [[Base/Reports/Functions|ici.]]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/SUN Report Builder

2007-12-22T22:45:41Z

Wurzel:

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport. La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définis par l'Utilisateur''' 
Mapped, Null

Une [[Base/Reports/Functions|explanation]] détaillée peut être trouvée [[Base/Reports/Functions|ici.]]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/SUN Report Builder

2007-12-22T22:41:44Z

Wurzel:

{{Documentation/FR}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport.La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définis par l'Utilisateur''' 
Mapped, Null

Une [[Base/Reports/Functions|explanation]] détaillée peut être trouvée [[Base/Reports/Functions|ici.]]

[[Category: Project]][[Category: Documentation]]

{{Documentation/Hook}}
{{PDL1}}

FR/Documentation/Base/Rapports/Fonctions

2007-12-22T22:18:01Z

Wurzel:

{{Documentation/Candidate}}

Le Sun Report Builder intègre les fonctions suivantes:

'''Arrondir''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| INT
| Cette fonction renvoit une valeur correspondant à l'entier inférieur le plus proche
|
|}
 
'''Informations''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| CHOOSE
| Cette fonction utilise un indexe pour renvoyer une valeur à partir d'une liste de valeurs.
|

|-
| HASCHANGED
| Cette fonction vérifie si les colonnes spécifiées par le nom donné ont changé.
|

|-
| ISBLANK
| Cette fonction vérifie si la valeur est indéfinie (null).
|

|-
| ISERR
| Cette fonction vérifie si le paramètre est du type "Erreur", mais renvoit "Faux" si l'erreur est du type "NA".
|

|-
| ISERROR
| Cette fonction vérifie si le paramètre est du type "Erreur" et renvoit "Faux".
|

|-
| ISEVEN
| Cette fonction vérifie s'il s'agit d'une valeur qui est un nombre pair.
|

|-
| ISLOGICAL
| Cette fonction vérifie s'il s'agit d'une valeur de type "Logique".
|

|-
| ISNA
| Cette fonction vérifie s'il s'agit d'une erreur de type "NA".
|

|-
| ISNONTEXT
| Cette fonction vérifie s'il s'agit d'une valeur qui n'est pas du type "Texte".
|

|-
| ISNUMBER
| Cette fonction vérifie s'il s'agit d'une valeur qui n'est pas du type "Nombre".
|

|-
| ISODD
| Cette fonction vérifie s'il s'agit d'une valeur qui est un nombre impair.
|

|-
| ISREF
| Cette fonction vérifie s'il s'agit d'une valeur qui est une référence.
|

|-
| ISTEXT
| Cette fonction vérifie s'il s'agit d'une valeur est du type "Texte".
|

|-
| NA
| Cette fonction renvoit la constante d'erreur NA.
|
|}
 
'''Date/Temps''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| DATE
| Cette fonction renvoit le nombre de jours écoulé depuis le 01.01.1900
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Month
| Mois
|-
| Day
| Jour
|}

|

|-
| DATEDIF
| Cette fonction renvoit le nombre de jours entre une première date et une deuxième date.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Date2
| Deuxième date.
|-
| Format
| Code de Formatage.
|}

|

|-
| DATEVALUE
| Cette fonction renvoit un numéro de série correspondant à une date à partir d'un texte donné.
|

|-
| DAY
| Cette fonction renvoit le jour d'une date donnée
|

|-
| HOUR
| Cette fonction renvoit l'heure (de 0 jusqu'à 23) à partir d'une heure donnée.
|

|-
| MONTH
| Cette fonction renvoit le mois d'une date donnée
|

|-
| NOW
| Cette fonction renvoit l'heure actuelle
|

|-
| TIME
| Cette fonction renvoit l'heure
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Minute.
| Minutes
|-
| Second
| Secondes
|}

|

|-
| TODAY
| Cette fonction renvoit la date actuelle
|

|-
| WEEKDAY
| Cette fonction renvoit le jour de la semaine à partir d'une date.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Type
| Cette fonction définit le type de résultat (de 1 à 3)
|}

|

|-
| YEAR
| Cette fonction renvoit l'année à partir d'une date donnée
|
|}
 
'''Text''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| EXACT
| Cette fonction indique si deux valeurs de texte sont identiques en effectuant une comparaison sensible à la casse.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Text2
| Le deuxième texte.
|}

|

|-
| FIND
| Returns the starting position of a given text.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Text
| Le texte d'origine.
|-
| Index
| L'indexe de départ.
|}

|

|-
| LEFT
| Cette fonction renvoit une chaîne de caractères en partant du caractère numéro "n" vers la gauche, où "n" est la position du caractère à partir duquel s'applique la fonction.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Length
| Cette fonction renvoit la longueur d'une chaîne de caractères.
|}

|

|-
| LEN
| Cette fonction renvoit la longueur de la chaîne de caractères qui lui est passée.
|

|-
| LOWER
| Cette fonction renvoit la chaîne en minuscules.
|

|-
| MID
| Cette fonction renvoit une chaîne de caractère, à partir d'une chaîne initiale, de la position de départ, et de la longueur de la chaîne.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Start
| L'indexe de départ.
|-
| Length
| La longueur de la chaîne.
|}

|

|-
| REPLACE
| Remplace une chaîne de caractères d'origine par une autre chaîne passé en paramètre, et dans l'indexe de départ et la fourchette de longueur.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Start
| L'indexe de départ.
|-
| Len
| La longueur.
|-
| New
| La nouvelle chaîne à insérer.
|}

|

|-
| REPT
| Cette fonction renvoit un texte répété par un nombre de fois défini par "Count".
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Count
| Le nombre de fois à répéter le texte.
|}

|

|-
| RIGHT
| Cette fonction renvoit une chaîne de caractères en partant du caractère "Count" vers la droite, où "Count" est la position du caractère à partir duquel s'applique la fonction.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Count
| Le numéro de la position du caractère de départ.
|}

|

|-
| SUBSTITUTE
| Remplace une chaîne de texte par une nouvelle chaîne. Par défaut chaque fois que la chaîne est rencontrée, elle sera remplacée par la nouvelle chaîne. Autrement, on peut préciser le nombre de remplacements par le paramètre "Which".
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Old
| La chaîne de caractères à remplacer.
|-
| New
| La chaîne de caractères à insérer.
|-
| Which
| Le nombre de fois que la chaîne à remplacer doit être recherchée.
|}

|

|-
| T
| Cette fonction renvoit la valeur du texte recherché ou bien une chaîne de longueur zéro pour des valeurs qui ne sont pas des chaînes de caractères de type "Texte".
|

|-
| TEXT
| Renvoit la valeur passée en tant que texte.
|

|-
| TRIM
| Renvoit la chaîne de caractères passée en enlevant tous les espaces devant et après la chaîne. Des espaces multiples sont remplacés par une seule espace.
|

|-
| UPPER
| Renvoit la chaîne de caractères passée en majuscules.
|

|-
| URLENCODE
| Applique l'encodage URL à une chaîne de caractères passée en premier paramètre en utilisant l'encodage indiqué en deuxième paramètre. Si aucun encodage n'est précisé, ISO-8859-1 est appliqué.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Encoding
| L'encodage à utiliser.
|}

|
|}
 
'''Mathematical''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| ABS
| Renvoit la valeur absolue (non négative) de la valeur à laquelle est appliquée la fonction.
|

|-
| AVERAGE
| Renvoit la moyenne d'une liste de valeurs numériques.
|

|-
| Even
| Renvoit une valeur arrondie au nombre entier pair supérieur.
|

|-
| MAX
| Renvoit la valeur maximale à partir d'un ensemble de valeurs.
|

|-
| MIN
| Renvoit la valeur minimale à partir d'un ensemble de valeurs.
|

|-
| MOD
| Renvoit le modulo lorsqu'un nombre est divisé par un autre.
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Divisor
| Le diviseur.
|-
|-
|-
|-
|-
|-
|-
|-
|-
|-
|}

|

|-
| ODD
| Renvoit une valeur arrondie au nombre entier impair supérieur.
|

|-
| SUM
| Faire la somme d'une liste de valeurs.
|
|}
 
'''Logical''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom de la Fonction'''''
| '''''Description'''''
| '''''Exemple '''''

|-
| AND
| ET logique
|

|-
| FALSE
| FAUX logique
|

|-
| IF
| Exécution Conditionnelle
{| class="prettytable" cellpadding="10" border="1"
| '''''Nom du Paramètre'''''
| '''''Description du Paramètre'''''

|-
| Une expression qui est évaluée si la condition est remplie.
| True-Term
|-
| Une expression qui est évaluée si la condition n'est pas remplie.
| False-Term
|}

|

|-
| AND
| ET logique
|

|-
| OR
| OU logique
|

|-
| TRUE
| VRAI logique
|

|-
| XOR
| XOR logique
|
|}
 
''Code nécessaire pour obtenir la fonction à partir du fichier jar libformula
<code>[java]
import java.util.Locale;
import org.jfree.formula.DefaultFormulaContext;

/*
* Si vous voulez changer ce modèle, choisissez Outils | Modèles
* et ouvrez le modèle dans l'éditeur.
*/
import org.jfree.formula.function.FunctionCategory;
import org.jfree.formula.function.FunctionDescription;
import org.jfree.formula.function.FunctionRegistry;

/**
*
* @author Ocke Janssen
*/
public class NewMain {

/**
* @param args the command line arguments
*/
public static void main(String[] args) {
DefaultFormulaContext obj = new DefaultFormulaContext();
FunctionRegistry func = obj.getFunctionRegistry();
FunctionCategory[] categories = func.getCategories();
for ( int i = 0 ; i < categories.length;++i)
{
String display = categories[i].getDisplayName(Locale.ENGLISH);
System.out.println( "'''" + display +"''' ");
System.out.println( "{| class=\"prettytable\" cellpadding=\"10\" border=\"1\"");
System.out.println( "| '''''Function Name'''''");
System.out.println( "| '''''Description''''' ");
System.out.println( "| '''''Example '''''");

String[] functions = func.getFunctionNamesByCategory(categories[i]);
for(int j= 0; j < functions.length;++j)
{
FunctionDescription desc = func.getMetaData(functions[j]);
System.out.println( "");
System.out.println( "|-");
System.out.println("| "+ desc.getDisplayName(Locale.ENGLISH));
System.out.println("| "+ desc.getDescription(Locale.ENGLISH));
int count = desc.getParameterCount();
if ( count > 1 ){
System.out.println( "{| class=\"prettytable\" cellpadding=\"10\" border=\"1\"");
System.out.println( "| '''''Parameter Name''''' ");
System.out.println( "| '''''Parameter Description''''' ");
System.out.println( "");
}
for(int k= 1;k < count;++k){
try{
System.out.println( "|-");
System.out.println("| " + desc.getParameterDisplayName(k,Locale.ENGLISH) );
System.out.println("| " + desc.getParameterDescription(k,Locale.ENGLISH) );
} catch(Exception e){
}
}
if ( count > 1 ){
System.out.println("|}");
System.out.println("");
}

System.out.println("| ");
}
System.out.println("|}");
System.out.println(" ");
}
}

}
</code>

[[Category: Database]]
[[Category: Base Documentation]]

FR/Documentation/Base/Reports/Functions

2007-12-22T22:04:59Z

Wurzel: Documentation/FR/Base/Reports/Functions moved to Documentation/FR/Base/Rapports/Fonctions: Correcting from English to French

#REDIRECT [[Documentation/FR/Base/Rapports/Fonctions]]

FR/Documentation/Base/Rapports/Fonctions

2007-12-22T22:04:59Z

Wurzel: Documentation/FR/Base/Reports/Functions moved to Documentation/FR/Base/Rapports/Fonctions: Correcting from English to French

{{Documentation/Candidate}}

Le Sun Report Builder intègre les fonctions suivantes:

'''Rounding''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| INT
| Cette fonction renvoit une valeur correspondant à l'entier inférieur le plus proche
|
|}
 
'''Information''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| CHOOSE
| Cette fonction utilise un indexe pour renvoyer une valeur à partir d'une liste de valeurs.
|

|-
| HASCHANGED
| Cette fonction vérifie si les colonnes spécifiées par le nom donné ont changé.
|

|-
| ISBLANK
| Cette fonction vérifie si la valeur est indéfinie (null).
|

|-
| ISERR
| Cette fonction vérifie si le paramètre est du type "Erreur", mais renvoit "Faux" si l'erreur est du type "NA".
|

|-
| ISERROR
| Cette fonction vérifie si le paramètre est du type "Erreur" et renvoit "Faux".
|

|-
| ISEVEN
| Cette fonction vérifie s'il s'agit d'une valeur qui est un nombre pair.
|

|-
| ISLOGICAL
| Cette fonction vérifie s'il s'agit d'une valeur de type "Logique".
|

|-
| ISNA
| Cette fonction vérifie s'il s'agit d'une erreur de type "NA".
|

|-
| ISNONTEXT
| Cette fonction vérifie s'il s'agit d'une valeur qui n'est pas du type "Texte".
|

|-
| ISNUMBER
| Cette fonction vérifie s'il s'agit d'une valeur qui n'est pas du type "Nombre".
|

|-
| ISODD
| Cette fonction vérifie s'il s'agit d'une valeur qui est un nombre impair.
|

|-
| ISREF
| Cette fonction vérifie s'il s'agit d'une valeur qui est une référence.
|

|-
| ISTEXT
| Cette fonction vérifie s'il s'agit d'une valeur est du type "Texte".
|

|-
| NA
| Cette fonction renvoit la constante d'erreur NA.
|
|}
 
'''Date/Time''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| DATE
| Cette fonction renvoit le nombre de jours écoulé depuis le 01.01.1900
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Month
| Month
|-
| Day
| Day
|}

|

|-
| DATEDIF
| Cette fonction renvoit le nombre de jours entre une première date et une deuxième date.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Date2
| Deuxième date.
|-
| Format
| Code de Formatage.
|}

|

|-
| DATEVALUE
| Cette fonction renvoit un numéro de série correspondant à une date à partir d'un texte donné.
|

|-
| DAY
| Cette fonction renvoit le jour d'une date donnée
|

|-
| HOUR
| Cette fonction renvoit l'heure (de 0 jusqu'à 23) à partir d'une heure donnée.
|

|-
| MONTH
| Cette fonction renvoit le mois d'une date donnée
|

|-
| NOW
| Cette fonction renvoit l'heure actuelle
|

|-
| TIME
| Cette fonction renvoit l'heure
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Minute.
| Minutes
|-
| Second
| Secondes
|}

|

|-
| TODAY
| Cette fonction renvoit la date actuelle
|

|-
| WEEKDAY
| Cette fonction renvoit le jour de la semaine à partir d'une date.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Type
| Cette fonction définit le type de résultat (de 1 à 3)
|}

|

|-
| YEAR
| Cette fonction renvoit l'année à partir d'une date donnée
|
|}
 
'''Text''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| EXACT
| Cette fonction indique si deux valeurs de texte sont identiques en effectuant une comparaison sensible à la casse.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Text2
| Le deuxième texte.
|}

|

|-
| FIND
| Returns the starting position of a given text.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Text
| Le texte d'origine.
|-
| Index
| L'indexe de départ.
|}

|

|-
| LEFT
| Cette fonction renvoit une chaîne de caractères en partant du caractère numéro "n" vers la gauche, où "n" est la position du caractère à partir duquel s'applique la fonction.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Length
| Cette fonction renvoit la longueur d'une chaîne de caractères.
|}

|

|-
| LEN
| Cette fonction renvoit la longueur de la chaîne de caractères qui lui est passée.
|

|-
| LOWER
| Cette fonction renvoit la chaîne en minuscules.
|

|-
| MID
| Cette fonction renvoit une chaîne de caractère, à partir d'une chaîne initiale, de la position de départ, et de la longueur de la chaîne.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Start
| L'indexe de départ.
|-
| Length
| La longueur de la chaîne.
|}

|

|-
| REPLACE
| Remplace une chaîne de caractères d'origine par une autre chaîne passé en paramètre, et dans l'indexe de départ et la fourchette de longueur.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Start
| L'indexe de départ.
|-
| Len
| La longueur.
|-
| New
| La nouvelle chaîne à insérer.
|}

|

|-
| REPT
| Cette fonction renvoit un texte répété par un nombre de fois défini par "Count".
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Count
| Le nombre de fois à répéter le texte.
|}

|

|-
| RIGHT
| Cette fonction renvoit une chaîne de caractères en partant du caractère "Count" vers la droite, où "Count" est la position du caractère à partir duquel s'applique la fonction.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Count
| Le numéro de la position du caractère de départ.
|}

|

|-
| SUBSTITUTE
| Remplace une chaîne de texte par une nouvelle chaîne. Par défaut chaque fois que la chaîne est rencontrée, elle sera remplacée par la nouvelle chaîne. Autrement, on peut préciser le nombre de remplacements par le paramètre "Which".
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Old
| La chaîne de caractères à remplacer.
|-
| New
| La chaîne de caractères à insérer.
|-
| Which
| Le nombre de fois que la chaîne à remplacer doit être recherchée.
|}

|

|-
| T
| Cette fonction renvoit la valeur du texte recherché ou bien une chaîne de longueur zéro pour des valeurs qui ne sont pas des chaînes de caractères de type "Texte".
|

|-
| TEXT
| Renvoit la valeur passée en tant que texte.
|

|-
| TRIM
| Renvoit la chaîne de caractères passée en enlevant tous les espaces devant et après la chaîne. Des espaces multiples sont remplacés par une seule espace.
|

|-
| UPPER
| Renvoit la chaîne de caractères passée en majuscules.
|

|-
| URLENCODE
| Applique l'encodage URL à une chaîne de caractères passée en premier paramètre en utilisant l'encodage indiqué en deuxième paramètre. Si aucun encodage n'est précisé, ISO-8859-1 est appliqué.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Encoding
| L'encodage à utiliser.
|}

|
|}
 
'''Mathematical''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| ABS
| Renvoit la valeur absolue (non négative) de la valeur à laquelle est appliquée la fonction.
|

|-
| AVERAGE
| Renvoit la moyenne d'une liste de valeurs numériques.
|

|-
| Even
| Renvoit une valeur arrondie au nombre entier pair supérieur.
|

|-
| MAX
| Renvoit la valeur maximale à partir d'un ensemble de valeurs.
|

|-
| MIN
| Renvoit la valeur minimale à partir d'un ensemble de valeurs.
|

|-
| MOD
| Renvoit le modulo lorsqu'un nombre est divisé par un autre.
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Divisor
| Le diviseur.
|-
|-
|-
|-
|-
|-
|-
|-
|-
|-
|}

|

|-
| ODD
| Renvoit une valeur arrondie au nombre entier impair supérieur.
|

|-
| SUM
| Faire la somme d'une liste de valeurs.
|
|}
 
'''Logical''' 
{| class="prettytable" cellpadding="10" border="1"
| '''''Function Name'''''
| '''''Description'''''
| '''''Example '''''

|-
| AND
| ET logique
|

|-
| FALSE
| FAUX logique
|

|-
| IF
| Exécution Conditionnelle
{| class="prettytable" cellpadding="10" border="1"
| '''''Parameter Name'''''
| '''''Parameter Description'''''

|-
| Une expression qui est évaluée si la condition est remplie.
| True-Term
|-
| Une expression qui est évaluée si la condition n'est pas remplie.
| False-Term
|}

|

|-
| AND
| ET logique
|

|-
| OR
| OU logique
|

|-
| TRUE
| VRAI logique
|

|-
| XOR
| XOR logique
|
|}
 
''Code nécessaire pour obtenir la fonction à partir du fichier jar libformula
<code>[java]
import java.util.Locale;
import org.jfree.formula.DefaultFormulaContext;

/*
* Si vous voulez changer ce modèle, choisissez Outils | Modèles
* et ouvrez le modèle dans l'éditeur.
*/
import org.jfree.formula.function.FunctionCategory;
import org.jfree.formula.function.FunctionDescription;
import org.jfree.formula.function.FunctionRegistry;

/**
*
* @author Ocke Janssen
*/
public class NewMain {

/**
* @param args the command line arguments
*/
public static void main(String[] args) {
DefaultFormulaContext obj = new DefaultFormulaContext();
FunctionRegistry func = obj.getFunctionRegistry();
FunctionCategory[] categories = func.getCategories();
for ( int i = 0 ; i < categories.length;++i)
{
String display = categories[i].getDisplayName(Locale.ENGLISH);
System.out.println( "'''" + display +"''' ");
System.out.println( "{| class=\"prettytable\" cellpadding=\"10\" border=\"1\"");
System.out.println( "| '''''Function Name'''''");
System.out.println( "| '''''Description''''' ");
System.out.println( "| '''''Example '''''");

String[] functions = func.getFunctionNamesByCategory(categories[i]);
for(int j= 0; j < functions.length;++j)
{
FunctionDescription desc = func.getMetaData(functions[j]);
System.out.println( "");
System.out.println( "|-");
System.out.println("| "+ desc.getDisplayName(Locale.ENGLISH));
System.out.println("| "+ desc.getDescription(Locale.ENGLISH));
int count = desc.getParameterCount();
if ( count > 1 ){
System.out.println( "{| class=\"prettytable\" cellpadding=\"10\" border=\"1\"");
System.out.println( "| '''''Parameter Name''''' ");
System.out.println( "| '''''Parameter Description''''' ");
System.out.println( "");
}
for(int k= 1;k < count;++k){
try{
System.out.println( "|-");
System.out.println("| " + desc.getParameterDisplayName(k,Locale.ENGLISH) );
System.out.println("| " + desc.getParameterDescription(k,Locale.ENGLISH) );
} catch(Exception e){
}
}
if ( count > 1 ){
System.out.println("|}");
System.out.println("");
}

System.out.println("| ");
}
System.out.println("|}");
System.out.println(" ");
}
}

}
</code>

[[Category: Database]]
[[Category: Base Documentation]]

FR/Documentation/Base/Rapports/Fonctions

2007-12-22T22:04:26Z

Wurzel:

FR/Documentation/BAse/SUN Report Builder

2007-12-22T20:52:23Z

Wurzel: Documentation/FR/BAse/SUN Report Builder moved to Documentation/FR/Base/SUN Report Builder: Correcting link to remove capital letter in Base subsection

#REDIRECT [[Documentation/FR/Base/SUN Report Builder]]

FR/Documentation/Base/SUN Report Builder

2007-12-22T20:52:23Z

Wurzel: Documentation/FR/BAse/SUN Report Builder moved to Documentation/FR/Base/SUN Report Builder: Correcting link to remove capital letter in Base subsection

{{Documentation/Candidate}}
== Sun Report Builder ==
Vous trouverez ce module complémentaire en téléchargement [http://extensions.services.openoffice.org/project/reportdesign ici]. C'est une extension qui s'installe de la même manière que les autres.

== Expression d'Impression Conditionnelle ==
Une expression d'impression conditionnelle permet à l'utilisateur de limiter les données qui sont visibles lorsqu'on génère un rapport. Si la condition est remplie, alors l'élément (par exemple, une section ou un élément individuel) sera imprimé dans le rapport.La syntaxe d'utilisation est identique à celle des fonctions.

== Fonctions ==
Une fonction peut être créée lors de l'ouverture du navigateur de rapport. Dans le menu contextuel de l'entrée '''Fonctions''', il vous est possible de créer une fonction.

Cette fonction peut être soit globale dans le contexte du rapport, soit particulière à un regroupement.

Le schéma ci-dessous montre comment créer des champs de sous-total dans le Report Builder, en utilisant des fonctions :

[[Image:SumFieldInReportBuilder.jpg]]

La table constituant la source de données est illustrée en haut à gauche de l'image.

L'agencement du rapport est illustré en-dessous de la table. Un regroupement a été défini pour le champ plProductType. Le champ Somme a été créé au pied du regroupement. La partie la plus à droite de l'image montre la définition de la fonction, qui sert à générer la source de données pour le champ Somme.

== Champs Calculés ==
Les champs calculés peuvent être créés en entrant la formule correspondante directement dans le champ de données.

Exemple : 100*[Population]/[PopulationCount], pour obtenir le pourcentage de la population actuelle

== Syntaxe ==

* lorsqu'on veut citer "[" on utilise "\"
* \\
* [] pour indiquer une référence de formule ou un nom de champ
* les guillemets doubles "" pour mettre des chaînes to quote strings
* le point "." en tant que séparateur décimal
* date, conformément aux spécifications Java
* le séparateur de paramètres est le point-virgule ";". Il est possible de laisser certains paramètres vides, par exemple : XYZ(;kk;;kkb)

== Fonctions Supportées ==
De manière générale, toutes les fonctions définies dans [http://wiki.oasis-open.org/office/About_OpenFormula OpenFormula] devraient devraient être supportées. Toutefois, l'étendue de ce support peut évoluer avec le temps, car l'équipe de développement continue à travailler dessus. Du coup, le nombre et types de fonctions supportés peuvent changer en fonction des versions du Sun Report Builder.

Le Sun Report Builder Verson 1.0.x intègre des fonctions appartenant aux catégories suivantes:

'''Date/Temps''' 
Date, Datetime, Day, Hour, Month, Now, Year, Today, Weekday, Time,

'''Finances''' 
Financial

'''Informations''' 
Choose, HasChanged, Information, IsBlank, IsErr, IsError, IsEven, IsLogical, IsNA, IsNonText, IsNumber, IsOdd, IsRef, IsText, Na

'''Logiques''' 
And, False, If, Not, Or, True, Xor

'''Maths''' 
Abs, Average, Even, Odd, Sum

'''Arrondir''' 
Int

'''Textes''' 
Exact, Find, Left, Len, Lower, Mid, Replace, Rept, Right, Substitute, Text, T, Trim, Upper, URL

'''Définis par l'Utilisateur''' 
Mapped, Null

Une [[Base/Reports/Functions|explanation]] détaillée peut être trouvée [[Base/Reports/Functions|ici.]]

[[Category: Database]]
[[Category: Base Documentation]]

FR/Documentation/SUN Report Builder

2007-12-22T20:50:39Z

Wurzel: Documentation/FR/SUN Report Builder moved to Documentation/FR/BAse/SUN Report Builder: Déplacement dans un sous-répertoire Base

#REDIRECT [[Documentation/FR/BAse/SUN Report Builder]]

FR/Documentation/Base/SUN Report Builder

2007-12-22T20:50:39Z

Wurzel: Documentation/FR/SUN Report Builder moved to Documentation/FR/BAse/SUN Report Builder: Déplacement dans un sous-répertoire Base

FR/Documentation/Base/SUN Report Builder

2007-12-22T20:49:03Z

Wurzel:

Connect MySQL and Base

2007-12-15T21:23:14Z

Wurzel: /* Using JDBC on Linux */

Here is a tutorial to connect MySQL database with OpenOffice.org Base.

== Using JDBC on Windows ==

== Using ODBC on Windows ==

== Using JDBC on Linux ==
OpenOffice.org comes directly with support of JDBC connectivity to multiple databases. OpenOffice.org needs [http://www.java.com/en/download/index.jsp Java Runtime Environment] to be able to use JDBC. Verify that you have JRE on your OOo by going to '''Tools - Options - OpenOffice.org General - Java'''.

Next step is to download the [http://www.mysql.com/products/connector/j/ mysql-connector-J] which you can download from the [http://www.mysql.com MySQL website]. [http://www.mysql.com/products/connector/j/ MySQL Connector/J] adds JDBC connectivity to MySQL. Unpack, untar or unzip the downloaded file anywhere where you can access it as a normal user, for example, to your desktop. On KDE, you can use Ark, on Gnome FileRoller, or even the Nautilus scripts that are included in some Linux distributions, or the usual "tar -zvf" from a console. A directory is created at the desired location named mysql-connector-java-x.x.x, where the x.x.x represents the version number of the JDBC connector you have downloaded. Inside this directory, you will find a file called mysql-connector-x.x.x-java-bin.jar.

Start OpenOffice.org and go to the menu '''Tools - Options - OpenOffice.org General Java'''. Click on the button '''Add Archive''' and navigate to where the mysql-connector-x.x.x-java-bin.jar file is located. Click on '''Open''', and the file should then appear in the list of '''Assigned folders and Archives'''. You can then click on '''OK''' and close OpenOffice.org completely. You may receive a message indicating that you have to do that anyway in order for OpenOffice.org to be able recognize your changes correctly. If the OpenOffice.org quickstarter is running, you should close that application as well.

Instead of downloading the connector from the MySQL download site, you can also use the corresponding packages of your distribution like
* libmysql-java for debian and ubuntu

When you restart OpenOffice.org, you should now be able to create a new database document that can connect to your existing mysql database, i.e. you need to have created your database first on your mysql server, for example with the CREATE DATABASE command from the mysql command line client or from within PHPMyAdmin if you are using that graphical user interface to administer your mysql server.

Now do the following :

1) '''File > New > Database'''

2) Click on the radio button '''Connect''' to an existing database and choose '''MySQL''' from the dropdown menu. Click on '''Next'''.

3) In the next dialog, you should accept the default choice of '''Connect using JDBC''', and then click on '''Next'''.

4) In the following dialog, enter the name of your mysql database as it is called on the mysql server, paying attention to the spelling. In the '''Address''' field, enter either the fully qualified internet domain name of the server on which your mysql server is running, or its IP address or, if you are running the mysql server locally on your own computer, simply type localhost. Click on '''Test Class''' just to make sure that you have correctly set up the access to the JDBC connector as detailed above. If the connector has been set up correctly, you will get a message that says '''The JDBC driver was loaded correctly'''. Now click on '''Next'''.

5) Now enter the name of the user and the password (if required by the mysql server) that you have previously created for use of the database on the mysql server. If you click on '''Test Connection''', you will be asked for a password if you have ticked the password box beforehand. If the connection to the database succeeds, you will get a message '''The connection was established successfully'''. Click on '''Next'''.

6) On the final screen of the database wizard dialog, you can in general leave the default settings as they are, i.e. '''Yes, register the database for me''' and '''Open the database for editing'''. Click on '''Finish'''.

7) You will be asked for a file name to give to your database document. Once you have done this and clicked on '''Save''', the database document will open, and the Forms button on the left will be highlighted. Congratulations, you have now connected to your MySQL database via the JDBC connector.

== Using ODBC on Linux ==
OpenOffice.org also support ODBC connectivity to MySQL, you will need [http://www.unixodbc.org/ Unix-ODBC] in order to make a connection through it.

== Recommendations settings ==

Known issues regarding MySQL and OpenOffice.org can be avoided by having specific settings here are some of those:

=== MySQL settings ===

* Make sure that MySQL is using TCP/IP as opposed to sockets. Edit the my.cnf file at /etc/ and comment '''skip-networking'''

=== OpenOffice.org settings ===

* OpenOffice.org uses Java for JDBC, please make sure you have JRE at Tools - Options - OpenOffice.org General - Java
* Declare the '''mysql-connector-j.bin''' at the classpath at Tools - Options - OpenOFfice.org General - Java

[[Category:Database]]

Connect MySQL and Base

2007-12-15T21:19:52Z

Wurzel: /* Using JDBC on Linux */

Here is a tutorial to connect MySQL database with OpenOffice.org Base.

== Using JDBC on Windows ==

== Using ODBC on Windows ==

== Using JDBC on Linux ==
OpenOffice.org comes directly with support of JDBC connectivity to multiple databases. OpenOffice.org needs [http://www.java.com/en/download/index.jsp Java Runtime Environment] to be able to use JDBC. Verify that you have JRE on your OOo by going to '''Tools - Options - OpenOffice.org General - Java'''.

Next step is to download the [http://www.mysql.com/products/connector/j/ mysql-connector-J] which you can download from the [http://www.mysql.com MySQL website]. [http://www.mysql.com/products/connector/j/ MySQL Connector/J] adds JDBC connectivity to MySQL. Unpack, untar or unzip the downloaded file anywhere where you can access it as a normal user, for example, to your desktop. On KDE, you can use Ark, on Gnome FileRoller, or even the Nautilus scripts that are included in some Linux distributions, or the usual "tar -zvf" from a console. A directory is created at the desired location named mysql-connector-java-x.x.x, where the x.x.x represents the version number of the JDBC connector you have downloaded. Inside this directory, you will find a file called mysql-connector-x.x.x-java-bin.jar.

Start OpenOffice.org and go to the menu '''Tools - Options - OpenOffice.org General Java'''. Click on the button Add Archive and navigate to where the mysql-connector-x.x.x-java-bin.jar file is located. Click on Open, and the file should then appear in the list of Assigned folders and Archives. You can then click on OK and close OpenOffice.org completely. You may receive a message indicating that you have to do that anyway in order for OpenOffice.org to be able recognize your changes correctly. If the OpenOffice.org quickstarter is running, you should close that application as well.

Instead of downloading the connector from the MySQL download site, you can also use the corresponding packages of your distribution like
* libmysql-java for debian and ubuntu

When you restart OpenOffice.org, you should now be able to create a new database document that can connect to your existing mysql database, i.e. you need to have created your database first on your mysql server, for example with the CREATE DATABASE command from the mysql command line client or from within PHPMyAdmin if you are using that graphical user interface to administer your mysql server.

Now do the following :

1) File > New > Database

2) Click on the radio button Connect to an existing database and choose MySQL from the dropdown menu. Click on Next.

3) In the next dialog, you should accept the default choice of Connect using JDBC, and then click on Next.

4) In the following dialog, enter the name of your mysql database as it is called on the mysql server, paying attention to the spelling. In the address field, enter either the fully qualified internet domain name of the server on which your mysql server is running, or its IP address or, if you are running the mysql server locally on your own computer, simply type localhost. Click on Test Class just to make sure that you have correctly set up the access to the JDBC connector as detailed above. If the connector has been set up correctly, you will get a message that says '''The JDBC driver was loaded correctly'''. Now click on Next.

5) Now enter the name of the user and the password (if required by the mysql server) that you have previously created for use of the database on the mysql server. If you click on Test Connection, you will be asked for a password if you have ticked the password box beforehand. If the connection to the database succeeds, you will get a message '''The connection was established successfully'''. Click on Next.

6) On the final screen of the database wizard dialog, you can in general leave the default settings as they are, i.e. '''Yes, register the database for me''' and '''Open the database for editing'''. Click on Finish.

7) You will be asked for a file name to give to your database document. Once you have done this and clicked on Save, the database document will open, and the Forms button on the left will be highlighted. Congratulations, you have now connected to your MySQL database via the JDBC connector.

== Using ODBC on Linux ==
OpenOffice.org also support ODBC connectivity to MySQL, you will need [http://www.unixodbc.org/ Unix-ODBC] in order to make a connection through it.

== Recommendations settings ==

Known issues regarding MySQL and OpenOffice.org can be avoided by having specific settings here are some of those:

=== MySQL settings ===

* Make sure that MySQL is using TCP/IP as opposed to sockets. Edit the my.cnf file at /etc/ and comment '''skip-networking'''

=== OpenOffice.org settings ===

* OpenOffice.org uses Java for JDBC, please make sure you have JRE at Tools - Options - OpenOffice.org General - Java
* Declare the '''mysql-connector-j.bin''' at the classpath at Tools - Options - OpenOFfice.org General - Java

[[Category:Database]]

Connect MySQL and Base

2007-12-15T21:01:58Z

Wurzel: /* Using JDBC on Linux */

Here is a tutorial to connect MySQL database with OpenOffice.org Base.

== Using JDBC on Windows ==

== Using ODBC on Windows ==

== Using JDBC on Linux ==
OpenOffice.org comes directly with support of JDBC connectivity to multiple databases. OpenOffice.org needs [http://www.java.com/en/download/index.jsp Java Runtime Environment] to be able to use JDBC. Verify that you have JRE on your OOo by going to '''Tools - Options - OpenOffice.org General - Java'''.

Next step is to download the [http://www.mysql.com/products/connector/j/ mysql-connector-J] which you can download from the [http://www.mysql.com MySQL website]. [http://www.mysql.com/products/connector/j/ MySQL Connector/J] adds JDBC connectivity to MySQL. Unpack, untar or unzip the downloaded file anywhere where you can access it as a normal user, for example, to your desktop. On KDE, you can use Ark, on Gnome FileRoller, or even the Nautilus scripts that are included in some Linux distributions, or the usual "tar -zvf" from a console. A directory is created at the desired location named mysql-connector-java-x.x.x, where the x.x.x represents the version number of the JDBC connector you have downloaded. Inside this directory, you will find a file called mysql-connector-x.x.x-java-bin.jar.

Start OpenOffice.org and go to the menu '''Tools - Options - OpenOffice.org General Java'''. Click on the button Add Archive and navigate to where the mysql-connector-x.x.x-java-bin.jar file is located. Click on Open, and the file should then appear in the list of Assigned folders and Archives. You can then click on OK and close OpenOffice.org completely. You may receive a message indicating that you have to do that anyway in order for OpenOffice.org to be able recognize your changes correctly. If the OpenOffice.org quickstarter is running, you should close that application as well.

Instead of downloading the connector from the MySQL download site, you can also use the corresponding packages of your distribution like
* libmysql-java for debian and ubuntu

When you restart OpenOffice.org, you should now be able to create a new database document that can connect to your existing mysql database, i.e. you need to have created your database first on your mysql server, for example with the CREATE DATABASE command from the mysql command line client or from within PHPMyAdmin if you are using that graphical user interface to administer your mysql server.

Now do the following :
1) File > New > Database

2) Click on the radio button Connect to an existing database and choose MySQL from the dropdown menu. Click on Next.

3) In the next dialog, you should accept the default choice of Connect using JDBC, and then click on Next.

4) In the following dialog, enter the name of your mysql database as it is called on the mysql server, paying attention to the spelling. In the address field, enter either the fully qualified internet domain name of the server on which your mysql server is running, or its IP address or, if you are running the mysql server locally on your own computer, simply type localhost. Click on Test Class just to make sure that you have correctly set up the access to the JDBC connector as detailed above. If the connector has been set up correctly, you will get a message that says '''The JDBC driver was loaded correctly'''. Now click on Next.

5) Now enter the name of the user and the password (if required by the mysql server) that you have previously created for use of the database on the mysql server. If you click on Test Connection, you will be asked for a password if you have ticked the password box beforehand. If the connection to the database succeeds, you will get a message '''The connection was established successfully'''. Click on Next.

6) On the final screen of the database wizard dialog, you can in general leave the default settings as they are, i.e. '''Yes, register the database for me''' and '''Open the database for editing'''. Click on Finish.

7) You will be asked for a file name to give to your database document. Once you have done this and clicked on Save, the database document will open, and the Forms button on the left will be highlighted. Congratulations, you have now connected to your MySQL database via the JDBC connector.

== Using ODBC on Linux ==
OpenOffice.org also support ODBC connectivity to MySQL, you will need [http://www.unixodbc.org/ Unix-ODBC] in order to make a connection through it.

== Recommendations settings ==

Known issues regarding MySQL and OpenOffice.org can be avoided by having specific settings here are some of those:

=== MySQL settings ===

* Make sure that MySQL is using TCP/IP as opposed to sockets. Edit the my.cnf file at /etc/ and comment '''skip-networking'''

=== OpenOffice.org settings ===

* OpenOffice.org uses Java for JDBC, please make sure you have JRE at Tools - Options - OpenOffice.org General - Java
* Declare the '''mysql-connector-j.bin''' at the classpath at Tools - Options - OpenOFfice.org General - Java

[[Category:Database]]

FR/Documentation/TableauBord/Organisation

2007-12-08T09:24:56Z

Wurzel: /* Utilisation des Categories */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Réflexions sur les Categories].

Il est possible, mais pas recommandé, d'utiliser des Gabarits pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Gabarit n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Gabarit, jusqu'à ce qu'on édite une page qui utilise ce dernier. Pour d'autres informations, voir la section MediaWiki Help:Category [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Utilisation de gabarits pour peupler des Categories].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le statut légal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editez l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Gardez à l'esprit que d'autres personnes pourraient traduire la page où vous mettez une image. Essayez de ne pas inclure des bulles d'affichage ou d'autre texte supplémentaire sur l'image.
# Le format JPG est général le mieux adapté pour les photos, SVG, pour des icones, logos etc, et PNG pour des captures d'écran. Dans la mesure du possible, n'utilisez pas du BMP.

Il est possible d'utiliser la fonction MediaWiki Image thumb pour "emballer" vos illustrations dans un cadre à image. Ce cadre à image comprend un emplacement pour la légende de l'image. La syntaxe est la suivante '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', où:
* thumb = mettre en vignette l'image et l'inclure dans un cadre à image
* position = la position sur la page. "none" met l'image sur la gauche du cadre sans entrelacement du texte. "left" et "right" met l'image respectivement à gauche ou à droite sur la page avec entrelacement complet du texte.
* size = la largeur maximale en pixels pour l'image. Si l'image est plus grande que cette valeur, elle est réduite à l'échelle. Si l'image est plus petite que cette valeur, elle demeure inchangée.
Si vous ne déclarez ni position ni taille, l'image est transformée en petite vignette, et se met par défaut sur la droite de la page avec un entrelacement complet du texte.

Un exemple d'utilisation <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

FR/Documentation/TableauBord/Organisation

2007-12-08T09:24:03Z

Wurzel: /* Utilisation des Categories */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Category considerations].

Il est possible, mais pas recommandé, d'utiliser des Gabarits pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Gabarit n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Gabarit, jusqu'à ce qu'on édite une page qui utilise ce dernier. Pour d'autres informations, voir la section MediaWiki Help:Category [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Utilisation de gabarits pour peupler des Categories].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le statut légal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editez l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Gardez à l'esprit que d'autres personnes pourraient traduire la page où vous mettez une image. Essayez de ne pas inclure des bulles d'affichage ou d'autre texte supplémentaire sur l'image.
# Le format JPG est général le mieux adapté pour les photos, SVG, pour des icones, logos etc, et PNG pour des captures d'écran. Dans la mesure du possible, n'utilisez pas du BMP.

Il est possible d'utiliser la fonction MediaWiki Image thumb pour "emballer" vos illustrations dans un cadre à image. Ce cadre à image comprend un emplacement pour la légende de l'image. La syntaxe est la suivante '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', où:
* thumb = mettre en vignette l'image et l'inclure dans un cadre à image
* position = la position sur la page. "none" met l'image sur la gauche du cadre sans entrelacement du texte. "left" et "right" met l'image respectivement à gauche ou à droite sur la page avec entrelacement complet du texte.
* size = la largeur maximale en pixels pour l'image. Si l'image est plus grande que cette valeur, elle est réduite à l'échelle. Si l'image est plus petite que cette valeur, elle demeure inchangée.
Si vous ne déclarez ni position ni taille, l'image est transformée en petite vignette, et se met par défaut sur la droite de la page avec un entrelacement complet du texte.

Un exemple d'utilisation <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

FR/Documentation/TableauBord/Organisation

2007-12-08T09:22:57Z

Wurzel: /* Utilisation des Categories */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Category considerations].

Il est possible, mais pas recommandé, d'utiliser des Gabarits pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Gabarit n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Gabarit, jusqu'à ce qu'on édite une page qui utilise ce dernier. Pour d'autres informations, voir la section MediaWiki Help:Category [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Disponble ici].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le statut légal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editez l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Gardez à l'esprit que d'autres personnes pourraient traduire la page où vous mettez une image. Essayez de ne pas inclure des bulles d'affichage ou d'autre texte supplémentaire sur l'image.
# Le format JPG est général le mieux adapté pour les photos, SVG, pour des icones, logos etc, et PNG pour des captures d'écran. Dans la mesure du possible, n'utilisez pas du BMP.

Il est possible d'utiliser la fonction MediaWiki Image thumb pour "emballer" vos illustrations dans un cadre à image. Ce cadre à image comprend un emplacement pour la légende de l'image. La syntaxe est la suivante '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', où:
* thumb = mettre en vignette l'image et l'inclure dans un cadre à image
* position = la position sur la page. "none" met l'image sur la gauche du cadre sans entrelacement du texte. "left" et "right" met l'image respectivement à gauche ou à droite sur la page avec entrelacement complet du texte.
* size = la largeur maximale en pixels pour l'image. Si l'image est plus grande que cette valeur, elle est réduite à l'échelle. Si l'image est plus petite que cette valeur, elle demeure inchangée.
Si vous ne déclarez ni position ni taille, l'image est transformée en petite vignette, et se met par défaut sur la droite de la page avec un entrelacement complet du texte.

Un exemple d'utilisation <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

FR/Documentation/TableauBord/Organisation

2007-12-08T09:19:29Z

Wurzel: /* Utilisation des Categories */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Category considerations].

Il est possible, mais pas recommandé, d'utiliser des Gabarits pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Gabarit n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Gabarit, jusqu'à ce qu'on édite une page qui utilise ce dernier. Pour d'autres informations, voir la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Using templates to populate categories].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le statut légal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editez l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Gardez à l'esprit que d'autres personnes pourraient traduire la page où vous mettez une image. Essayez de ne pas inclure des bulles d'affichage ou d'autre texte supplémentaire sur l'image.
# Le format JPG est général le mieux adapté pour les photos, SVG, pour des icones, logos etc, et PNG pour des captures d'écran. Dans la mesure du possible, n'utilisez pas du BMP.

Il est possible d'utiliser la fonction MediaWiki Image thumb pour "emballer" vos illustrations dans un cadre à image. Ce cadre à image comprend un emplacement pour la légende de l'image. La syntaxe est la suivante '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', où:
* thumb = mettre en vignette l'image et l'inclure dans un cadre à image
* position = la position sur la page. "none" met l'image sur la gauche du cadre sans entrelacement du texte. "left" et "right" met l'image respectivement à gauche ou à droite sur la page avec entrelacement complet du texte.
* size = la largeur maximale en pixels pour l'image. Si l'image est plus grande que cette valeur, elle est réduite à l'échelle. Si l'image est plus petite que cette valeur, elle demeure inchangée.
Si vous ne déclarez ni position ni taille, l'image est transformée en petite vignette, et se met par défaut sur la droite de la page avec un entrelacement complet du texte.

Un exemple d'utilisation <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

FR/Documentation/TableauBord/Organisation

2007-12-08T09:15:58Z

Wurzel: /* Contenu Graphique */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Category considerations].

Il est possible, mais pas recommandé, d'utiliser des Templates pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Template n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Template, jusqu'à ce qu'on édite une page qui utilise ce Template." Pour d'autres informations, voir la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Using templates to populate categories].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le statut légal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editez l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Gardez à l'esprit que d'autres personnes pourraient traduire la page où vous mettez une image. Essayez de ne pas inclure des bulles d'affichage ou d'autre texte supplémentaire sur l'image.
# Le format JPG est général le mieux adapté pour les photos, SVG, pour des icones, logos etc, et PNG pour des captures d'écran. Dans la mesure du possible, n'utilisez pas du BMP.

Il est possible d'utiliser la fonction MediaWiki Image thumb pour "emballer" vos illustrations dans un cadre à image. Ce cadre à image comprend un emplacement pour la légende de l'image. La syntaxe est la suivante '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', où:
* thumb = mettre en vignette l'image et l'inclure dans un cadre à image
* position = la position sur la page. "none" met l'image sur la gauche du cadre sans entrelacement du texte. "left" et "right" met l'image respectivement à gauche ou à droite sur la page avec entrelacement complet du texte.
* size = la largeur maximale en pixels pour l'image. Si l'image est plus grande que cette valeur, elle est réduite à l'échelle. Si l'image est plus petite que cette valeur, elle demeure inchangée.
Si vous ne déclarez ni position ni taille, l'image est transformée en petite vignette, et se met par défaut sur la droite de la page avec un entrelacement complet du texte.

Un exemple d'utilisation <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

FR/Documentation/TableauBord/Organisation

2007-12-08T09:02:11Z

Wurzel: /* Utilisation des Categories */

__NOTOC__
{{Documentation/Banner}}
{{Documentation/FR/EnCours|[[User:Flepennu|Flepennu]] Decembre 2007 (CEST)}}

Cet article a pour but de vous aider a contribuer a la section Documentation/FR de ce wiki.

=Structure du Wiki Documentation =

==Hiérarchie==

La section Documentation est une partie du Wiki. Le projet doc.oo.o cherche a présenter les informations dans cette section d'une facon accessible et a une structure qui permet la navigation pour les utilisateurs et les contributeurs.

Toutes les pages documentation ne sont pas des sous-pages de la page Documentation principale, certaines renvoient vers des sous pages, d'autres vers des liens de la documentation anglaise.

L'arborescence de la page documentation/FR du wiki presente pour l'instant :

wiki.services.openoffice.org/wiki/Documentation/FR/
|
+---Foire Aux Questions (FAQ)
+---Manuels de l'utilisateur (OOoAuthors) (en)
+---How-to
+---Chercher/Télécharger
+---Guides pour l'administration de OpenOffice.org
+---Guide (en anglais) de programmation BASIC

==Utilisation des Categories==

[http://www.mediawiki.org/wiki/Help:Categories/fr Allez voir ici] si vous n'etes pas familier des Categories Wiki.

Quelles exemples simples pour utiliser des Categories dans un Wiki :
# Creer une Categorie du nom du chapitre courant.
# Ajouter toutes les pages de ce chapitre dans une Categorie du nom de ce chapître.
# Ajouter le nom de cette Categorie dans le wiki.

Le lecteur peut ainsi voir la Categorie du livre. Le livre Categorie indique tous les chapitres du livre. Si le lecteur clique sur un chapitre Categorie, il verra toutes les pages dans ce chapitre (par ordre alphabétique).

Il ne faut pas ajouter une Categorie et une sous-categorie à la même page du wiki. Pour plus d'informations, consultez la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Category_considerations Category considerations].

Il est possible, mais pas recommandé, d'utiliser des Templates pour ajouter une Categorie commune à un ensemble important de pages. Cela donnerait l'impression de gagner du temps, mais l'ajout ou la suppression d'un tag de categorie dans le Template n'ajoute, ni supprime les listages à ou de la page Categorie des pages qui utilisent ce Template, jusqu'à ce qu'on édite une page qui utilise ce Template." Pour d'autres informations, voir la section MediaWiki Help:Category disponible [http://meta.wikimedia.org/wiki/Help:Category#Using_templates_to_populate_categories Using templates to populate categories].

=Utilisation des gabarits (Templates)=

[http://www.mediawiki.org/wiki/Help:Templates/fr allez voir ici] si vous n'êtes pas familier des gabarits (mediawiki templates).

Si vous créer des nouveaux gabarits , nommez les commes des sous-pages de documentation/FR :
* Mauvais: '''montemplate'''
* Bon: '''Documentation/FR/montemplate'''

==Gabarits existants (Templates) ==

{|border=1 style="border-collapse:collapse;" cellpadding=3 cellspacing=4
|-
!Nom!!Usage!!Exemple
|-
|[[Template:Documentation/Abstract]]|| ||
|-
|[[Template:Documentation/Banner]]|| ||
|-
|[[Template:Documentation/FR/EnCours]]|| ||{{Documentation/FR/EnCours}}
|-
|[[Template:Documentation/FR/Attention]]|| ||{{Documentation/FR/Attention|Ne faite jamais ce qui est écrit ici.}}
|-
|[[Template:Documentation/FR/PertinenceVerifiee]]|| ||{{Documentation/FR/PertinenceVerifiee|Jean Dupond}}
|-
|[[Template:Documentation/FR/PremierJet]]|| || {{Documentation/FR/PremierJet}}
|-
|[[Template:Documentation/hbar]]|| || {{Documentation/hbar|100}}
|-
|[[Template:Documentation/FR/AideDemandee]]|| || {{Documentation/FR/AideDemandee|Verifiez le texte et l'orthographe}}
|-
|[[Template:Documentation/Hook]]|| ||
|-
|[[Template:Documentation/Imported]]|| ||
|-
|[[Template:Documentation/LastEdited]]|| || Only works after update of mw engine to > 1.8
|-
|[[Template:Documentation/Linux]]|| || {{Documentation/Linux}}
|-
|[[Template:Documentation/MasterTOC]]|| ||
|-
|[[Template:Documentation/FR/EnAttente]]|| || {{Documentation/FR/EnAttente}}
|-
|[[Template:Documentation/FR/Note]]|| || {{Documentation/FR/Note|Information notable}}
|-
|[[Template:Documentation/OOo]]|| || {{Documentation/OOo}}
|-
|[[Template:Documentation/FR/PlusValable]]|| || {{Documentation/FR/PlusValable|0.5}}
|-
|[[Template:Documentation/PDF]]|| || {{Documentation/PDF}}
|-
|[[Template:Documentation/PRODUCTNAME]]|| || {{Documentation/PRODUCTNAME}}
|-
|[[Template:Documentation/FR/Astuce]]|| ||{{Documentation/FR/Astuce|Essayez cette astuce.}}
|-
|Template:Documentation/*TOC|| ||
|-
|[[Template:Documentation/Windows]]|| ||{{Documentation/Windows}}
|}

=Contenu Graphique=

Pour les images , voici quelques principes généraux :
# Utilisez la page des descriptions des images pour préciser le status legal de l'image et de son usage.
# Utilisez une description et un titre unique.
# Si possible n'adaptez pas le format et la taille de l'image avant de l'envoyer sur le serveur, utilisez la vignette MediaWiki pour faire figurer l'image.
# Editer l'image si necessaire pour etre sur de ne faire apparaitre que ce qui est important d'une facon claire et visible.
# Keep in mind that people may be translating the page where you are placing an image. Try not to include callouts or other extra text on the image.
# JPG is usually best for photos, SVG, for icons, logos etc, and PNG for screen captures. Try not to use BMP.

You can use the MediaWiki Image thumb feature to "wrap" your illustrations in an image box. This image box includes a spot for an image caption. The syntax is '''<nowiki>[[Image:image.png|thumb|position|size|Image caption]]</nowiki>''', where:
* thumb = thumbnail the image and wrap in an image box
* position = position on page. "none" places the image on the left of the frame with no text wrapping. "left" and "right" places the image on the left or right of the page with full text wrapping.
* size = max width in pixels for the image. If the image is larger than this value it is scaled down. If the image is smaller it is left as is.
If you do not declare a position and size, the image is scaled to a small thumbnail, and defaults to the right hand side of the page with full text wrapping.

An example using <nowiki>[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]</nowiki>

[[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

=Linking=

Non-code extensions FR

2006-10-14T12:40:37Z

Wurzel: /* Packages du Gallery */

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt ici]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement ou [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

= Packages du Gallery =

Tout ce qui a été écrit ci-dessus s'applique également aux packages du Gallery. Le fichier Paths.xcu contient cette fois-ci une valeur relative au chemin du "Gallery" à place de celui des "Template". Un exemple d'un package Gallery se trouve [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt ici]. On peut ainsi le remplir avec les thèmes de Gallery qu'on souhaite. Comme cet aspect des choses n'est pas aussi facile à maîtriser que cela puisse paraître, et le code a souvent tendance à provoquer des conflits de noms entre les différents fichiers de thème, il est déconseillé ne pas mettre en oeuvre des packages de Gallery tant que le bug référencé [http://www.openoffice.org/issues/show_bug.cgi?id=70412 ici] n'est pas résolu.

= Packages pour dictionaires et wordbooks utilisateurs =

Ce travail n'est pas encore achevé parce qu'il nécessite une refonte de l'accès aux fichiers se rapportant aux outils linguistiques. Revenez de temps en temps pour voir où cela en est.

Non-code extensions FR

2006-10-14T12:40:05Z

Wurzel: /* Packages du Gallery */

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt ici]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement ou [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

= Packages du Gallery =

Tout ce qui a été écrit ci-dessus s'applique également aux packages du Gallery. Le fichier Paths.xcu contient cette fois-ci une valeur relative au chemin du "Gallery" à place de celui des "Template". Un exemple d'un package Gallery se trouve ici: [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt here]. On peut ainsi le remplir avec les thèmes de Gallery qu'on souhaite. Comme cet aspect des choses n'est pas aussi facile à maîtriser que cela puisse paraître, et le code a souvent tendance à provoquer des conflits de noms entre les différents fichiers de thème, il est déconseillé ne pas mettre en oeuvre des packages de Gallery tant que le bug référencé [http://www.openoffice.org/issues/show_bug.cgi?id=70412 ici] n'est pas résolu.

= Packages pour dictionaires et wordbooks utilisateurs =

Ce travail n'est pas encore achevé parce qu'il nécessite une refonte de l'accès aux fichiers se rapportant aux outils linguistiques. Revenez de temps en temps pour voir où cela en est.

Non-code extensions FR

2006-10-14T12:39:33Z

Wurzel: /* Packages Autotexte */

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt ici]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement ou [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

= Packages du Gallery =

Tout ce qui a été écrit ci-dessus s'applique également aux packages du Gallery. Le fichier Paths.xcu contient cette fois-ci une valeur relative au chemin du "Gallery" à place de celui des "Template". Un exemple d'un package Gallery se trouve ici: [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt here]. On peut ainsi le remplir avec les thèmes de Gallery qu'on souhaite. Comme cet aspect des choses n'est pas aussi facile à maîtriser que cela puisse paraître, et le code a souvent tendance à provoquer des conflits de noms entre les différents fichiers de thème, il est déconseillé ne pas mettre en oeuvre des packages de Gallery tant que le bug référencé ici [http://www.openoffice.org/issues/show_bug.cgi?id=70412 bug] n'est pas résolu.

= Packages pour dictionaires et wordbooks utilisateurs =

Ce travail n'est pas encore achevé parce qu'il nécessite une refonte de l'accès aux fichiers se rapportant aux outils linguistiques. Revenez de temps en temps pour voir où cela en est.

Non-code extensions FR

2006-10-14T12:38:03Z

Wurzel:

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt ici]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

= Packages du Gallery =

Tout ce qui a été écrit ci-dessus s'applique également aux packages du Gallery. Le fichier Paths.xcu contient cette fois-ci une valeur relative au chemin du "Gallery" à place de celui des "Template". Un exemple d'un package Gallery se trouve ici: [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt here]. On peut ainsi le remplir avec les thèmes de Gallery qu'on souhaite. Comme cet aspect des choses n'est pas aussi facile à maîtriser que cela puisse paraître, et le code a souvent tendance à provoquer des conflits de noms entre les différents fichiers de thème, il est déconseillé ne pas mettre en oeuvre des packages de Gallery tant que le bug référencé ici [http://www.openoffice.org/issues/show_bug.cgi?id=70412 bug] n'est pas résolu.

= Packages pour dictionaires et wordbooks utilisateurs =

Ce travail n'est pas encore achevé parce qu'il nécessite une refonte de l'accès aux fichiers se rapportant aux outils linguistiques. Revenez de temps en temps pour voir où cela en est.

Non-code extensions FR

2006-10-14T12:31:17Z

Wurzel:

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve ici : [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt here]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

= Packages du Gallery =

Tout ce qui a été écrit ci-dessus s'applique également aux packages du Gallery. Le fichier Paths.xcu contient cette fois-ci une valeur relative au chemin du "Gallery" à place de celui des "Template". Un exemple d'un package Gallery se trouve ici: [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt here]. On peut ainsi le remplir avec les thèmes de Gallery qu'on souhaite. Comme cet aspect des choses n'est pas aussi facile à maîtriser que cela puisse paraître, et le code a souvent tendance à provoquer des conflits de noms entre les différents fichiers de thème, il est déconseillé ne pas mettre en oeuvre des packages de Gallery tant que le bug référencé ici [http://www.openoffice.org/issues/show_bug.cgi?id=70412 issue] n'est pas résolu.

= Packages pour dictionaires et wordbooks utilisateurs =

Ce travail n'est pas encore achevé parce qu'il nécessite une refonte de l'accès aux fichiers se rapportant aux outils linguistiques. Revenez de temps en temps pour voir où cela en est.

Non-code extensions FR

2006-10-14T10:25:35Z

Wurzel:

traduction en cours ... sur la base de :
http://wiki.services.openoffice.org/wiki/Non-code_extensions

{{Extensions}}
[[Category:Extensions]]
__TOC__

= Packages UNO: Principes de base =

Le concept de déploiement des extensions OpenOffice.org basé sur les packages UNO n'est pas limité au code. Il est également possible d'installer d'autres choses dans des packages faciles d'utilisation, comme des modèles, des autotextes etc. Vous trouverez ci-dessous une explication du fonctionnement de base. Elle est destinée aux utilisateurs avancés et aux administrateurs système. La plupart des points abordés ici sont expliqués de façon plus détaillée et plus compréhensible à d'autres endroits. Le sujet de la documentation ci-dessous est de présenter une vue générale et d'expliquer les principes de base. Si vous souhaitez en savoir plus sur UNO, vous pouvez consulter notre [http://wiki.services.openoffice.org/wiki/Uno wiki UNO] ou les pages web du [http://udk.openoffice.org project UDK].

Toutes les informations fournies ici se rapportent à OpenOffice.org 2.0.4. Les différences pouvant exister avec des versions plus anciennes ne sont pas expliquées ici, bien que l'on puisse mentionner explicitement les choses apparues pour la première fois dans la 2.0.4.

Les packages UNO ne sont rien d'autre que des dossiers zippés avec des données supplémentaires et des méta-données décrivant le contenu. Il peuvent être déployés par l'interface du Gestionnaire de packages intégré à OOo ("Outils - Gestionnaire de packages") ou grace à l'outil en ligne de commande “unopkg” qui se trouve dans le répertoire "program" de OOo. Ce dernier permet non seulement le déploiement d'un package pour un utilisateur, mais également pour tous les utilisateurs avec le paramètre optionnel "--shared”. Quand les packages sont installés, leur contenu est recopié à des emplacements privés bien définis sous “share/uno_packages” ou “user/uno_packages”, selon la portée de l'installation du package (installation système ou simple utilisateur). On entend par "Privé" : ne pas écrire de code qui se fie à la structure particulière du composant UNO décompressé, l'accès aux fichiers compressés doit utiliser un API défini qui se charge des détails pour l'appelant. Des fichiers en dehors des dossiers "uno_packages" ne devraient jamais être affectés, à la seule exception dont l'explication se trouve ici [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Des macros Basic dans des packages UNO doivent toujours être enregistrées dans un fichier xlc se trouvant dans l'un des répertoires "basic".

== Extensions comportant des services UNO (code) ==

Si un package UNO comporte un composant écrit en Java, C++ ou Python, ce dernier doit rendre publique sa fonctionnalité afin d'être fonctionnel au sein de OpenOffice.org. Dans les développements basés sur UNO, un ensemble de fonctionnalités défini est appelé un "service". Ceux-ci sont identifiés et on y accède par leurs noms de service. Un composant qui met en oeuvre de tels services doit informer les autres de son identification. Aujourd'hui tous les composants exportent une fonction qui peut être appélée par unopkg et qui va obliger le composant à écrire toutes les informations nécessaires dans le fichier de registre des services qui est créé et maintenu à l'intérieur d'un dossier „uno_package“. Lorsque OpenOffice.org se sert de son gestionnaire de service pour rechercher des services UNO disponibles, il regardera non seulement dans le registre des services (services.rdb) au sein du répertoire principal du programme (contenant toutes les informations sur les "services internes"), mais également dans tous les fichiers de registre se trouvant dans les dossiers “uno_packages”.

OOo n'est capable d'instancier des services UNO par leurs noms que s'il en connaît l'existence. Ceci est facile pour des services qui remplacent ceux déjà présents en "interne" puisqu'OOo les connaît déjà et s'en sert couramment, mais comme la plupart des composants fournissent de nouveaux services, il doit exister autre chose qui permet à OOo de s'en servir bien que lui étant inconnus lors de la compilation. Pour ces cas précis, les composants UNO doivent fournir des données complémentaires sur le moment auquel le chargement d'un service donné doit s'effectuer. Ces "données de composant additionnelles" sont fournies dans les fichiers de configuration de OOo.

Un exemple serait un composant de filtre de document dans lequel les données complémentaires qui doivent être fournies consistent (entre autres) en le type de fichier que le filtre sait charger. Un composant de filtre précis pourrait se déclarer capable de charger des fichiers WordPerfect. Ainsi, si un utilisateur choisit ce filtre pour charger un ficher dans l'application alors OOo trouverait les données déclarées en recherchant toutes données contenant le type de fichier souhaité (wps), instancierait le composant de filtre par son nom de service tel que découvert dans ces données et ensuite s'en servir pour charger le fichier dans l'application. Chaque filtre déjà présent dans OOo a ses propres données de configuration et les filtres de conversion de documents dans les packages UNO fournissent leurs propres données de configuration de manière à complémenter celles déjà présentes dans le produit.

== Support des Packages dans le Gestionnaire de Configuration ==
Le Gestionnaire de Configuration d'OpenOffice.org possède également la capacité à rechercher dans un ensemble de dossiers extensibles de la même manière que le Gestionnaire de Services. S'il trouve plusieurs fichiers de configuration dans ces dossiers contenant des données pour les mêmes éléments dans l'arborescence des entrées de configuration, soit il les fusionnera, soit il remplacera des données d'ordre hiérarchique inférieur par des données d'ordre hiérarchique supérieur, selon le type de données de configuration. Les données de configuration "utilisateur" ont toujours précédence sur les données de configuration préinstallées se trouvant dans la couche partagée ("share"). Les données de configuration des packages UNO se situent entre ces deux extrêmes : les données de configuration partagées des packages UNO ont un ordre hiérarchique supérieur à la couche partagée pré-installée, mais un ordre hiérarchique inférieur aux données de configuration "utilisateur".

Il demeure la question suivante : quelles données sont fusionnées lorsqu'il y a au moins deux couches de configuration ?

Le Gestionnaire de Configuration a tendance à prendre ses informations dans des fichiers xml (portant l'extension de fichier xcu) avec des éléments typés. Il supporte quelques types de base, des types structurés qui doivent être définis dans des fichiers de schéma (portant l'extension de fichier xcs) et fait une liste de tous ces types. Ceux-ci ne peuvent pas être étendus. Si la configuration découvre des valeurs différentes de celles dans les différentes couches, c'est la valeur de l'ordre hiérarchique supérieur qui est retenue. Pour la fusion d'éléments de configuration et par ce biais l'extension de la fonctionnalité qui en dépend nécessite le type "set". Pour mieux comprendre son fonctionnement, regardez dans [[Configuration_schema_path_settings|configuration schema]] mentionné dans la section "Configuration des Chemins".

Un composant peut étendre ou modifier la configuration de OpenOffice.org en lui fournissant des fichiers xcu dans son package qui remplaceront ou étendront (fusion) des entrées de configuration dans OpenOffice.org. Il peut également disposer de ses propres entrées de configuration s'il fournit des fichiers de schéma (xcs) dans son package.

Il existe un autre cas d'utilisation (relativement évident) du principe de couches du gestionnaire de configuration : le remplacement des entrées de configuration de OpenOffice.org au niveau de tous les utilisateurs ("all users"). Un administrateur peut personnaliser l'installation de OpenOffice.org dans son propre compte utilisateur, et puis ensuite prendre les fichiers xcu créés contenant les personnalisations et les inclure dans un package qu'il installera par la suite avec "unopkg add --shared" chaque fois qu'il installera, réinstallera ou mettra à jour OpenOffice.org. Il n'y aura ainsi aucun besoin d'éditer les fichiers xcu dans "share/registry" à la main !

Le principe des couches du registre de services et de la configuration sont les principes de base qui rendent le système de packages UNO à la fois solide et flexible.

= Configuration des Chemins =
Quelques données d'OpenOffice.org ne sont pas stockées dans les fichiers de configuration xcu mais ailleurs dans le système de fichiers, comme, par exemple, les modèles de documents, l'autotexte, le contenu de la galerie, etc. Bien entendu ce contenu doit pouvoir être déployé dans des packages, mais dans ce cas, d'ordinaire, vous ne souhaitez pas remplacer le contenu existant, vous souhaitez lui ajouter quelque chose. Aussi l'accès à ces fichiers doit également respecter un principe de couches. OpenOffice.org dispose de quelques composants qui gèrent l'accès aux fichiers. Nous aurions pu étendre ces composants de la même façon que nous avons étendu le Gestionnaire de Configuration ou le Gestionnaire de Services (en les rendant capables d'utiliser explicitement des couches), mais nous avons décidé de réutiliser la capacité déjà disponible du Gestionnaire de Configuration.

L'endroit où sont recherchés ces fichiers est défini dans la configuration soit comme un simple chemin, soit comme une liste de chemins ("multichemin"). Malheureusement, une telle liste ne peut qu'être remplacée dans les couches les plus hautes et non étendue, aussi avons-nous besoin d'un nouveau schéma de configuration pour les chemins, nouveau schéma qui utilise des "ensembles" au lieu de "listes" comme ils peuvent être étendus par des packages. Nous utilisons ce nouveau schéma pour les chemins à partir d'OpenOffice.org 2.0.4. Nous avons gardé l'ancien schéma et ses données pour des raisons de compatibilité et porterons ces réglages vers les nouvelles données. L'ancien schéma sera supprimé dans OpenOffice.org 3.0.

Si vous jetez un coup d'oeil aux entrées des "Chemins" dans la boîte de dialogue "Options" dans OOo2.0.4 vous remarquerez que toutes les parties des multichemins n'y sont pas montrées. Dans les versions antérieures d'OOo, vous pouviez voir habituellement deux dossiers pour les modèles par exemple : $(share)/templates et $(user)/templates, où "$(share)" et "$(user) sont des variables pour les dossiers partage (share) et utilisateur (user) de l'installation particulière. Vous pourriez voir de même tous les dossiers supplémentaires que l'administrateur ou l'utilisateur ont pu ajouter. Dans OOo2.0.4 vous continuerez de voir $(user)/templates et ces dossiers additionnels (si jamais il y en a), mais vous ne verrez plus $(share)/templates à cet endroit-ci. Si des packages contenant des modèles de documents sont installés, leur dossier ne sera pas montré ici non plus, ce dialogue n'est désormais qu'un outil pour permettre à l'utilisateur d'adapter les réglages qui sont sous son contrôle direct.

[[Image:Dialog_Tools_Options_204.png]]

=Packages de Modèles=

Un package UNO pour les modèles de documents est plutôt simple. Il contient principalement les modèles, organisés en des répertoires qui définissent les catégories de modèles pour le Gestionnaire de Modèles de Documents. De plus, un fichier Paths.xcu doit être fourni, fichier qui enregistre le package dans l'ensemble des dossiers de modèles de documents. Ce fichier contient l'URL du dossier où les modèles du package seront décompressés. Comme il s'agit là d'une inconnue lors de la création du package, une variable est utilisée dans l'URL, remplacée par le gestionnaire de packages quand il copie le fichier xcu à son emplacement final. L'avantage réside en ce que cette variable sera toujours la même pour chaque package de modèles et qu'ainsi le créateur d'un tel package n'aura aucun besoin de la créer lui-même :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</code>

== Exemple de Package ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt À cet endroit] se trouve un package vide pour modèles de documents prêt à être rempli de modèles.

Le conteneur au format zip possède un dossier nommé "template". Tout sous-dossier que vous y créerez apparaîtra comme une catégorie de modèles dans les dialogues de modèles d'OOo. Les modèles peuvent être déposés dans ces sous-dossiers. Le titre du modèle sera emprunté aux métadonnées du document (les propriétés du document) ou au nom du fichier si le titre n'est pas positionné dans les métadonnées. Si un de vos sous-dossiers a le nom d'une catégorie de modèles déjà présente, les modèles du package seront ajoutés à cette catégorie par le composant des modèles d'OpenOffice.org. Essayez, c'est plus simple à faire qu'à expliquer.

== Localisation des modèles et des catégories de modèles ==
Les titres des catégories et modèles peuvent être pris aux noms des dossiers et fichiers. Ces noms peuvent être traduits et utiliser tous les caractères que le conteneur zip et le (ou les) système de fichiers cible autorisent. Il peut arriver que les modèles soient installés sur des systèmes de fichiers où l'on rencontre des problèmes avec les noms de catégories (les noms de dossiers) traduits. Le composant des Modèles de Documents permet de fournir ces noms traduits dans un fichier différent. Les noms traduits des modèles de documents peuvent être enregistrés dans les métadonnées du document (les propriétés du document) de façon à ce qu'aucun problème ne survienne ici.

Le fichier de localisation s'appelle "groupuinames.xml" et prend place dans le sous-dossier "template" du package. Son contenu s'appréhende directement. Voici un exemple d'adaptation française de quelques dossiers qui utilisent des noms de fichiers en anglais :

'''groupuinames.xml'''
<code> [xml]
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Éducation" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Arrière-plans de présentation" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Divers" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Correspondance d'affaires" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Autres documents d'affaires" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Correspondance privée et documents" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Présentations" />
</groupuinames:template-group-list>
</code>

== Packages multilingues de modèles ==
Des packages multilingues de modèles sont également possibles. Ils nécessitent d'une part une légère modification de la ligne 13 du fichier Paths.xcu :

'''Paths.xcu'''
<code> [xml]
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</code>

et, d'autre part, la création de dossiers supplémentaires. Il s'agit des dossiers qui contiendront les modèles, sous-dossiers du dossier "template", et qui auront comme nom les codes ISO des langages fournis par les packs de langues d'OOo. Vous trouverez [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt un deuxième package vide] qui fournit l'infrastructure d'un tel package. Utilisez-le et placez les modèles en allemand dans le dossier "de", ceux en anglais dans le dossier "en-US", ceux en français dans le dossier "fr" etc. Des dossiers vides ne posent pas de problème. Chaque fichier de localisation (groupuinames.xml) doit désormais être placé dans le dossier correspondant au langage qu'il utilise et non plus directement dans le dossier "template" comme dans le cas d'un package monolingue.

= Packages Autotexte =

Tout ce qui a été expliqué ci-dessus par rapport aux pacakges de modèles s'applique également aux packages autotextes. Le fichier comporte alors, à la place d'une valeur pour le chemin du "Template", une valeur correspondant au chemin "AutoTexte". Un exemple d'un tel package se trouve ici : [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt here]. Cet exemple peut être utilisé pour fournir des fichiers autotexte. A l'heure actuelle, il n'existe aucune méthode d'export pour ces fichiers, il est donc aussi simple de copier les fichiers "*.bau" à la main qui ont été créés directement dans le package. De la même manière, on peut créer des packages d'autotextes localisés dans la langue de son choix: il suffit de placer les fichiers dans des sous-dossiers portant des noms conformes aux codes langue ISO, comme cela est indiqué dans le dossier "share/autotext". Contrairement aux packages de modèles, le chemin de l'autotexte ne nécessite pas d'inclure "$(vlang)" pour obtenir des packages multilingues puisque le composant gérant les autotextes implémente déjà en interne l'accès indépendamment de la langue.

Une remarque toutefois qui pose parfois des problèmes lors du déploiement de packages autotextes: l'interface graphique de l'utilisateur permet à l'heure actuelle d'enregistrer les autotextes dans des endroits arbitraires. Ceci est une erreur de fonctionnement [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] qui devrai être corrigée dans des versions futures de OpenOffice.org. Tout changement appliqué à des autotextes présents dans un package seront perdus lors de la désinstallation du package. Il n'est pas prévu qu'on puisse changer le contenu des packages!

Extensions development basic fr

2006-10-13T13:07:24Z

Wurzel: /* To open a document */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces est une fonction OpenOffice.org Basic utilisée pour l'introspection. Ce document [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] permettra d'apprendre ce que l'on entend par introspection dans d'autres langages de programmation.

HasUnoInterfaces renvoie une valeur "vrai" si toutes les interfaces spécifiées sont disponibles pour l'objet appelant.

La plupart des objets OpenOffice.org fournissent la méthode supportsService parce qu'ils disposent également de l'interface com.sun.star.lang.XServiceInfo.

Dans l'exemple ci-dessus, la commande OpenOffice.org Basic, '''HasUnoInterfaces''' vérifie si le document actif dispose de l'interface com.sun.star.lang.XServiceInfo, car si cette interface n'est pas présente, alors le document n'aura pas non plus la méthode supportsService, et une erreur d'exécution se produirait lorsqu'un objet tentait d'accéder à une méthode inexistante.

'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, et current selection==
StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

==Création de Nouveaux Documents==
Pour créer un nouveau document Writer, on écrit le code suivant:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>

De la même manière, pour un nouveau document Calc:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>

Il serait sans doute plus facile d'écrire une fonction simple:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>

Ensuite, on pourra créer de nouveaux documents ainsi:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>

Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==Ouverture d'un document==
Le code suivant donne un exemple permettant d'ouvrir un fichier. Pour plus d'informations sur l'utilisation d'URL au sein de OpenOffice.org, voir [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>

Ici encore, il peut être plus rationnel de simplifier le code en écrivant une fonction:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>

Exemples d'utilisation de la fonction:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Extensions development basic fr

2006-10-13T13:04:21Z

Wurzel: /* Desktop, documents, and current selection */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces est une fonction OpenOffice.org Basic utilisée pour l'introspection. Ce document [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] permettra d'apprendre ce que l'on entend par introspection dans d'autres langages de programmation.

HasUnoInterfaces renvoie une valeur "vrai" si toutes les interfaces spécifiées sont disponibles pour l'objet appelant.

La plupart des objets OpenOffice.org fournissent la méthode supportsService parce qu'ils disposent également de l'interface com.sun.star.lang.XServiceInfo.

Dans l'exemple ci-dessus, la commande OpenOffice.org Basic, '''HasUnoInterfaces''' vérifie si le document actif dispose de l'interface com.sun.star.lang.XServiceInfo, car si cette interface n'est pas présente, alors le document n'aura pas non plus la méthode supportsService, et une erreur d'exécution se produirait lorsqu'un objet tentait d'accéder à une méthode inexistante.

'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, et current selection==
StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

==Création de Nouveaux Documents==
Pour créer un nouveau document Writer, on écrit le code suivant:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>

De la même manière, pour un nouveau document Calc:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>

Il serait sans doute plus facile d'écrire une fonction simple:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>

Ensuite, on pourra créer de nouveaux documents ainsi:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>

Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Extensions development basic fr

2006-10-13T13:03:51Z

Wurzel: /* Création de nouveaux documents */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces est une fonction OpenOffice.org Basic utilisée pour l'introspection. Ce document [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] permettra d'apprendre ce que l'on entend par introspection dans d'autres langages de programmation.

HasUnoInterfaces renvoie une valeur "vrai" si toutes les interfaces spécifiées sont disponibles pour l'objet appelant.

La plupart des objets OpenOffice.org fournissent la méthode supportsService parce qu'ils disposent également de l'interface com.sun.star.lang.XServiceInfo.

Dans l'exemple ci-dessus, la commande OpenOffice.org Basic, '''HasUnoInterfaces''' vérifie si le document actif dispose de l'interface com.sun.star.lang.XServiceInfo, car si cette interface n'est pas présente, alors le document n'aura pas non plus la méthode supportsService, et une erreur d'exécution se produirait lorsqu'un objet tentait d'accéder à une méthode inexistante.

'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, and current selection==
StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

==Création de Nouveaux Documents==
Pour créer un nouveau document Writer, on écrit le code suivant:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>

De la même manière, pour un nouveau document Calc:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>

Il serait sans doute plus facile d'écrire une fonction simple:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>

Ensuite, on pourra créer de nouveaux documents ainsi:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>

Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Extensions development basic fr

2006-10-13T13:00:32Z

Wurzel: /* Introspection */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces est une fonction OpenOffice.org Basic utilisée pour l'introspection. Ce document [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] permettra d'apprendre ce que l'on entend par introspection dans d'autres langages de programmation.

HasUnoInterfaces renvoie une valeur "vrai" si toutes les interfaces spécifiées sont disponibles pour l'objet appelant.

La plupart des objets OpenOffice.org fournissent la méthode supportsService parce qu'ils disposent également de l'interface com.sun.star.lang.XServiceInfo.

Dans l'exemple ci-dessus, la commande OpenOffice.org Basic, '''HasUnoInterfaces''' vérifie si le document actif dispose de l'interface com.sun.star.lang.XServiceInfo, car si cette interface n'est pas présente, alors le document n'aura pas non plus la méthode supportsService, et une erreur d'exécution se produirait lorsqu'un objet tentait d'accéder à une méthode inexistante.

'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, and current selection==
StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Extensions development basic fr

2006-10-13T12:51:47Z

Wurzel: /* Desktop, documents, et current selection */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, and current selection==
StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Extensions development basic fr

2006-10-13T12:41:46Z

Wurzel: /* L'Outil X-Ray */

'''Comment démarrer'''

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaisance préalable de la programmation est un pré-requis. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le [[CookBook]] qui donne des exemples et des (wrappers).

=Où le code est-il enregistré ?=
Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

*Partagée (pour une installation en réseau - OOo Macros & Dialogues)
*Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
*Incorporée à un document ou à un modèle de telle manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle '''Bibliothèques OpenOffice.org'''.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir : '''Outils > Options… > OpenOffice.org > Chemins > BASIC'''.

{| border="1"
|'''Note'''
|Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.
|-
|}

La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubrique : Modules et bibliothèques.

=Accéder à l'IDE=
Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: '''Outils > Macros > Macro… >'''

OpenOffice.org 1.9.x et ultérieur : '''Outils > Macros > Gérer les macros > OpenOffice.org Basic… >'''

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement :

Entrons un nom pour notre nouvelle macro : '''HelloWorld'''

Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.

Cliquons '''Nouveau'''

Nous devons maintenant trouver quelque chose comme çà :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.

{| border="1"
|'''Note'''
|Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.
|-
|}

=Saisie de code=
Selectionnons et effaçons :

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1. Les commande OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents. Les chaînes sont entourées de guillements doubles.
|-
|}

=Exécution du code=
Le code Basic peut être exécuté de plusieurs façons :

Directement dans l'IDE. La barre des macro comprte un bouton Exécter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.

Depuis le menu Outils :

(Version 1.1.x) '''Outils > Macros > Macro…''';

(Version 1.9.x et supérieures) '''Outils > Macros > Exécuter la macro…'''

Par assignation de la macro à une [[ touche]].

Par assignation de la macro à une [[ entrée de menu]].

Par assignation de la macro à un bouton de barre d'outil.

En créant un [[ contrôle dans un document]].

Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

=Les variables=
Nous pouvons forcer la déclaration des variables en insérant <tt>Option Explicit</tt> au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 cette discussion]].

Dans cette discussion, on voit que l'auteur de [NdT : la version anglaise de] cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

{| border="1"
|'''''Lettre'''''
|'''''Signification'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE ou FALSE)
|-
|e
|Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
|-
|f
|Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets) Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets) Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
|-
|m
|Array (aka sequence aka matrice)
|-
|n
|Integer (de -32768 à 32767.) ou Long (de -2147483648 à 2147483647).
|-
|o
|Object, service ou interface
|-
|s
|String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
|-
|x
|Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
|-
|v
|Variant, N'importe quel valeur
|-
|}

Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

{| border="1"
|'''Note :'''
|Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.
|}

Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

<code>[oobas]
sub HelloWorld
dim i as integer 'ligne optionnelle
for i = 0 to 2
'Ces lignes sont indentées par souci de lisiblité uniquement
'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
msgbox "Hello World " & i
next i
end sub
</code>
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "utilisation des variables".

=L'API OpenOffice.org=
Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et à l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Texte"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Feuille de calcul"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Dessin"
else
fnWhichComponent = "Oops le document ouvert est autre chose"
end if
else
fnWhichComponent = "Ce n'est pas un document"
end if
End function
</code>

==Convention de nommage des routines==
Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

==Présentation de l'API OpenOffice.org==
Cette section introduit les termes :

* Interface
* Module
* Service
* Méthode
* Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une '''interface''' est la ''définition'' d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en '''modules''' pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface <tt>com.sun.star.beans.XPropertySet</tt>. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une '''propriété''' est une valeur tandis qu'une '''méthode''' défiti une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==L'Outil X-Ray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".

'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

= See also=
* [[Programming_OooWriter |Programming OOoWriter in C++]] where OOoBascic record are used in C++
* A [[XIntrospection_Interface|XIntrospection Interface]] short description. XRay uses this interface.
* Download Bernard Marcelly's [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool]

[[Category:Basic:Tutorials]]

Non-code extensions FR

2006-10-11T21:34:58Z

Wurzel: /* Extensions conmportant des services UNO (code) */

Non-code extensions FR

2006-10-11T21:16:39Z

Wurzel: /* Packages UNO: Principes de base */

Talk:Non-code extensions FR

2006-10-11T20:24:38Z

Wurzel: Commentaires début trad extensions

Il me semblerait normal de parler de "paquetages", comme on le voit traduit en français sous Linux, mais il est vrai que cela n'a pas été traduit ainsi au niveau de l'interface d'OOo. Par exemple, dans le menu Outils, il est écrit "Gestionnaire de packages". Si on veut que les trads soient homogènes, il faut alors laisser le mot tel qu'il apparaît dans le produit, sinon les lecteurs risquent de se perdre.

Printing problems with OpenOffice.org 2.0 for Mac OS X

2006-03-03T14:38:43Z

Wurzel: /* [ verified : 1 times ] Network printing */

Please, use the part corresponding to your problem, or create one if needed. To help us, please describe as completely as possible the description of your problem, giving just the most important informations.

In order to be able to recense the most important issues, every problem type MUST BEGIN using this syntax :

[ verified : number times]

means the first entering the problem put 1, next people will simply increment the counter
Thank's in advance to put

1) your name ( without personnal informations, please)

2) the version of OpenOffice.org you are using, your locale

3) the printer you are using : Mark Model ... whatever you think usefull for this field

4) in a few words, the problem you have

== [ verified : 0 times ] Cannot configure my printer ==

== [ verified : 0 times ] Printer configured but not found ==

== [ verified : 1 times ] Network printing ==
Hi,

I'm having problems with :

Network Printer : HP4730 multifunction printer / photocopier /scanner
The printer is a standalone network printer serving a group of workers, with a fixed IP address.

The MacOSX is 10.3 Panther
Locale : FR

The printer can be seen and printed to from OOo 2.0.x from the Linux workstations.

The printer does not appear in the list of CUPS printers in the OOo print dialog under OOo 2.0.x for the MacOSX workstations.

The printer is available and the print options configurable from OOo 1.1.x on MacOSX.

alex

== [ verified : 0 times ] Printing stops before the end ==

== [ verified : 0 times ] Features not available ==

Printing problems with OpenOffice.org 2.0 for Mac OS X

2006-03-03T14:38:03Z

Wurzel:

Please, use the part corresponding to your problem, or create one if needed. To help us, please describe as completely as possible the description of your problem, giving just the most important informations.

In order to be able to recense the most important issues, every problem type MUST BEGIN using this syntax :

[ verified : number times]

means the first entering the problem put 1, next people will simply increment the counter
Thank's in advance to put

1) your name ( without personnal informations, please)

2) the version of OpenOffice.org you are using, your locale

3) the printer you are using : Mark Model ... whatever you think usefull for this field

4) in a few words, the problem you have

== [ verified : 0 times ] Cannot configure my printer ==

== [ verified : 0 times ] Printer configured but not found ==

== [ verified : 1 times ] Network printing ==
Hi,

I'm having problems with :

Network Printer : HP4730 multifunction printer / photocopier /scanner
The printer is a standalone network printer serving a group of workers, with a fixed IP address.

The MacOSX is 10.3 Panther

The printer can be seen and printed to from OOo 2.0.x from the Linux workstations.

The printer does not appear in the list of CUPS printers in the OOo print dialog under OOo 2.0.x for the MacOSX workstations.

The printer is available and the print options configurable from OOo 1.1.x on MacOSX.

alex

== [ verified : 0 times ] Printing stops before the end ==

== [ verified : 0 times ] Features not available ==

Printing problems with OpenOffice.org 2.0 for Mac OS X

2006-03-03T14:34:57Z

Wurzel: /* [ verified : 0 times ] Printing stops before the end */

Please, use the part corresponding to your problem, or create one if needed. To help us, please describe as completely as possible the description of your problem, giving just the most important informations.

In order to be able to recense the most important issues, every problem type MUST BEGIN using this syntax :

[ verified : number times]

means the first entering the problem put 1, next people will simply increment the counter
Thank's in advance to put

1) your name ( without personnal informations, please)

2) the version of OpenOffice.org you are using, your locale

3) the printer you are using : Mark Model ... whatever you think usefull for this field

4) in a few words, the problem you have

== [ verified : 0 times ] Cannot configure my printer ==

== [ verified : 0 times ] Printer configured but not found ==

== [ verified : 0 times ] Network printing ==
Hi,

I'm having problems with :

Network Printer : HP4730 multifunction printer / photocopier /scanner
The printer is a standalone network printer serving a group of workers, with a fixed IP address.

The MacOSX is 10.3 Panther

The printer can be seen and printed to from OOo 2.0.x from the Linux workstations.

The printer does not appear in the list of CUPS printers in the OOo print dialog under OOo 2.0.x for the MacOSX workstations.

The printer is available and the print options configurable from OOo 1.1.x on MacOSX.

alex

== [ verified : 0 times ] Printing stops before the end ==
Forgot to mention the locale : FR

alex

== [ verified : 0 times ] Features not available ==

Printing problems with OpenOffice.org 2.0 for Mac OS X

2006-03-03T14:33:56Z

Wurzel: /* [ verified : 0 times ] Network printing */

Please, use the part corresponding to your problem, or create one if needed. To help us, please describe as completely as possible the description of your problem, giving just the most important informations.

In order to be able to recense the most important issues, every problem type MUST BEGIN using this syntax :

[ verified : number times]

means the first entering the problem put 1, next people will simply increment the counter
Thank's in advance to put

1) your name ( without personnal informations, please)

2) the version of OpenOffice.org you are using, your locale

3) the printer you are using : Mark Model ... whatever you think usefull for this field

4) in a few words, the problem you have

== [ verified : 0 times ] Cannot configure my printer ==

== [ verified : 0 times ] Printer configured but not found ==

== [ verified : 0 times ] Network printing ==
Hi,

I'm having problems with :

Network Printer : HP4730 multifunction printer / photocopier /scanner
The printer is a standalone network printer serving a group of workers, with a fixed IP address.

The MacOSX is 10.3 Panther

The printer can be seen and printed to from OOo 2.0.x from the Linux workstations.

The printer does not appear in the list of CUPS printers in the OOo print dialog under OOo 2.0.x for the MacOSX workstations.

The printer is available and the print options configurable from OOo 1.1.x on MacOSX.

alex

== [ verified : 0 times ] Printing stops before the end ==

== [ verified : 0 times ] Features not available ==