Creazione di una semplice macro

From Apache OpenOffice Wiki
Jump to: navigation, search






Traduzione in corso - translation in progress




Supponete di dover inserire ripetutamente sempre le stesse informazioni. Sebbene sia possibile memorizzare le informazioni negli appunti, se questi nel frattempo vengono utilizzati, il loro contenuto cambia. Una semplice soluzione consiste nel memorizzare i dati in una macro (in alcuni semplici casi, come l'esempio utilizzato in questa sede, una soluzione migliore consiste nell'utilizzo del completamento automatico).

  1. Fate clic su Strumenti > Macro > Registra Macro per cominciare la registrazione di una macro. Comparirà una piccola finestra, per far sapere che OpenOffice.org sta registrando.
  2. Macro termina reg it.png

  3. Digitate l'informazione desiderata, o eseguite la serie di operazioni desiderata. In questo caso, ho digitato il mio nome, Andrew Pitonyak.
  4. Fate clic sul pulsante Termina registrazione per interrompere la registrazione, salvate la macro, e visualizzate la finestra di dialogo Macro OpenOffice.org Basic (vedi sotto).
  5. Finestra di dialogo OOo Macro Organizer, con la libreria DBInspection selezionata.
  6. Assicuratevi di selezionare la cartella di libreria denominata Macro personali. Cercate la libreria denominata Standard all'interno di Macro personali. Notate che tutte le cartelle di libreria hanno una libreria denominata Standard. Selezionate la libreria standard e fate clic su Nuovo modulo per creare un nuovo modulo che conterrà la macro.
  7. Il nome predefinito del modulo è Module1; scegliete un nome appropriato. Sebbene non sia ancora descrittivo, ho utilizzato il nome Registrato. Digitate un nome descrittivo e fate clic su OK per creare il modulo. Verrà visualizzata nuovamente la finestra di dialogo Macro Openoffice.org Basic, mostrando il nuovo modulo.
  8. Selezionate il modulo appena creato. Nella casella di testo in alto a sinistra, digitate il nome della macro, come "InserisciMioNome", e dopo fate clic su Registra per salvare la macro.
  9. Dare al modulo un nome descrittivo

Se avete eseguito tutti i passi correttamente, la libreria Standard adesso conterrà un modulo chiamato Registrato, che contiene la macro InserisciMioNome, come mostrato sotto. OOo, quando crea un nuovo modulo, aggiunge automaticamente la macro Main.

Esecuzione di una macro

Fate clic su Strumenti > Macro > Esegui Macro per aprire la finestra di selezione della macro. Selezionate la macro appena creata e fate clic su Esegui.

Selezionate la vostra macro e fate clic su Esegui.

Ci sono altri metodi per eseguire una macro. Per esempio, potete fare clic su Strumenti > Macro > Organizza Macro > OpenOffice.org Basic per aprire la finestra di gestione delle macro, la quale contiene il pulsante Esegui come nel caso precedente. L'autore, uno scrittore avanzato di macro, preferisce il gestore di macro perché la finestra di dialogo di solito appare più velocemente, ma il processo di selezione può essere più lento.

Visualizzazione e modifica della macro

Potete visualizzare e modificare la macro che avete appena creato. Fate clic su Strumenti > Macro > Organizza Macro > OpenOffice.org Basic per aprire la finestra di dialogo Macro OpenOffice.org Basic Macro. Selezionate la nuova macro e fate clic su Modifica per aprire la macro nell'IDE (Integrated Development Environment, Ambiente di Sviluppo Integrato) di Basic.

Listato 1: La macro "InserisciMioNome"” creata.

 REM  *****  BASIC  *****
 Sub Main
 
 End Sub
 
 sub InserisciMioNome
 rem ---------------------------------------------------------------
 rem definizione variabili
 dim document   as object
 dim dispatcher as object
 rem ---------------------------------------------------------------
 rem accesso al documento
 document   = ThisComponent.CurrentController.Frame
 dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
 
 rem ---------------------------------------------------------------
 dim args1(0) as new com.sun.star.beans.PropertyValue
 args1(0).Name = "Text"
 args1(0).Value = "Andrew Pitonyak"
 
 dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())
 end sub






La macro del Listato 1 è più semplice di come compare a prima vista. Per capire meglio la macro generata sono necessarie solo alcune nozioni. La spiegazione comincia con la descrizione degli elementi della macro che sono presenti all'inizio del listato. Se preferite saltare questi dettagli, allora basta cambiare il testo “Andrew Pitonyak” con quello che volete inserire nella posizione corrente del cursore all'interno del documento.

I commenti cominciano con REM

La parola chiave REM, abbreviazione di remark, si trova all'inizio della riga di commento. Tutto il testo che segue REM (nella stessa riga) viene ignorato. Si può utilizzare come scorciatoia anche il carattere di apice singolo ' per scrivere un commento.


Suggerimento
StarBasic non è sensibile alle maiuscole per le parole chiave, quindi REM, Rem, rem danno tutte inizio ad un commento. Se utilizzate le costanti simboliche definite dalle API, è buona norma supporre che i nomi siano sensibili alle maiuscole—le costanti simboliche sono un argomento avanzato che di solito può essere ignorato dagli utenti che utilizzano il registratore macro.

Definizione delle subroutine con SUB

Le singole macro sono memorizzate in subroutine tramite la parola chiave SUB. La fine di una subroutine è indicata dalle parole chiave END SUB. Il codice comincia dalla definizione di una subroutine denominata Main, che è vuota e non fa niente. La subroutine seguente, InserisciMioNome, contiene il codice generato.


Suggerimento
OpenOffice.org crea una subroutine vuota, denominata Main, quando si crea un modulo.

Questi sono argomenti avanzati che vanno al di là degli scopi di questo documento, ma la loro conoscenza potrebbe essere utile:

  • Potete scrivere una macro in maniera tale da poter passare dei valori alla subroutine. Questi valori sono chiamati argomenti. Le macro registrate non accettano argomenti.
  • Un altro tipo di subroutine è la funzione. Una funzione è una subroutine che restituisce un valore. Per definire una funzione si utilizza la parola chiave FUNCTION al posto di SUB. Le macro generate cominciano sempre con la parola chiave SUB.

Definizione delle variabili mediante l'utilizzo di DIM

Potete scrivere le informazioni sopra un foglio, per riutilizzarle in seguito. Una variabile, come un foglio, contiene informazioni che possono essere lette e modificate. Utilizzare il costrutto DIM è come preparare un foglio che verrà utilizzato per memorizzare dei messaggi o degli appunti.

La macro InserisciMioNome definisce le variabili document e dispatcher di tipo object. Altri tipi di variabili comunemente utilizzati sono string, integer, e date. Una terza variabile, denominata args1, è un vettore di valori. Una variabile di tipo array permette ad una singola variabile di contenere più valori, in maniera simile ad avere molte pagine per un solo libro. I valori in un vettore sono solitamente numerati a partire da zero. Il numero racchiuso dalle parentesi indica il numero più elevato utilizzabile per accedere ad una locazione di memoria. In questo esempio c'è solo un valore e il suo indice è zero.

Assemblare più macro

L'argomento seguente è molto dettagliato, non è necessario comprenderlo a fondo. La prima riga definisce l'inizio della macro.

sub InserisciMioNome

Qui vengono dichiarate due variabili:

dim document   as object
dim dispatcher as object

ThisComponent fa riferimento al documento corrente.

La proprietà CurrentController di un documento si riferisce al servizio che “controlla” il documento stesso. Per esempio, quando scrivete qualcosa, è questo il controller che viene attivato. Il controller corrente poi abilita i cambiamenti nella finestra del documento.

La proprietà Frame di un controller restituisce il contenitore principale del documento. Inoltre, la variabile denominata document fa riferimento alla contenitore del documento stesso, che riceve i comandi da eseguire.

document = ThisComponent.CurrentController.Frame

La maggior parte dei compiti in OpenOffice.org sono eseguiti dall'invocazione di un comando. La versione 2.0 di OOo introduce il servizio dispatch helper il quale esegue la maggior parte del lavoro necessario per utilizzare le esecuzioni delle macro. Il metodo CreateUnoService accetta come argomento il nome di un servizio, e cerca di crearne un'istanza. Per finire, la variabile dispatcher contiene un riferimento a DispatchHelper.

dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

Dichiarazione di un vettore di proprietà. Ogni proprietà ha un nome e un valore. In altre parole, è una coppia nome/valore. Il vettore creato ha una proprietà nella posizione zero.

dim args1(0) as new com.sun.star.beans.PropertyValue

Date alla proprietà il nome “Text” e create come valore “Andrew Pitonyak”, che è il testo che verrà inserito quando verrà eseguita la macro.

args1(0).Name = "Text"
args1(0).Value = "Andrew Pitonyak"

Qui è dove avviene la magia. Il dispatch helper manda una richiesta al contenitore del documento (memorizzato nella variabile denominata document) mediante l'utilizzo del comando .uno:InsertText. I due argomenti successivi, frame name e search flags, vanno al di là dello scopo di questo documento. L'ultimo argomento è il vettore di proprietà che verrà utilizzato durante l'esecuzione del comando InsertText.

dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())

Finalmente, si arriva alla fine della subroutine.

end sub











The macro in Listing 1 is not as complicated as it first appears. Learning a few things helps significantly in understanding the generated macros. The discussion starts with features near the top of the macro listing and describes them. If you like to avoid details, then simply change the text “Andrew Pitonyak" to what you want to insert at the current cursor position.

Comments start with REM

The keyword REM, short for remark, starts a macro comment. All text after REM (on the same line) is ignored. As a short cut, the single quote character can also be used to start a comment.

Template:Documentation/Tip

Defining subroutines with SUB

Individual macros are stored in subroutines defined with the keyword SUB. The end of a subroutine is indicated by the words END SUB. The code starts by defining the subroutine named Main, which is empty and does nothing. The next subroutine, EnterMyName, contains the generated code.

Template:Documentation/Tip

There are advanced topics that are beyond the scope of this document, but knowing about them might be of interest:

  • You can write a macro so that values can be passed to the subroutine. The values are called arguments. Recorded macros do not accept arguments.
  • Another kind of subroutine is called a function. A function is a subroutine that returns a value. The keyword FUNCTION is used rather than SUB to define a function. Generated macros are always of type SUB.

Defining variables using DIM

You can write information on a piece of paper so that you can look at it later. A variable, like a piece of paper, contains information that can be changed and read. The DIM statement is similar to setting aside a piece of paper to be used to store a message or note.

The EnterMyName macro defines the variables document and dispatcher as type object. Other common variable types include string, integer, and date. A third variable, named args1, is an array of property values. A variable of type array allows a single variable to contain multiple values, similar to storing multiple pages in a single book. Values in an array are usually numbered starting from zero. The number in the parentheses indicates the highest usable number to access a storage location. In this example, there is only one value, and it is numbered zero.

Pulling the macro together

The following details are very complete; it is not important to understand all of the details. The first line defines the start of the macro.

sub EnterMyName

Declare two variables:

dim document as object
dim dispatcher as object

ThisComponent refers to the current document.

The CurrentController property of a document refers to a service that "controls" the document. For example, when you type, it is the current controller that notices. The current controller then dispatches the changes to the document's frame.

The Frame property of a controller returns a main frame for a document. Therefore, the variable named document refers to a document's frame, which receives dispatched commands.

document = ThisComponent.CurrentController.Frame

Most tasks in OpenOffice.org are accomplished by dispatching a command. OOo version 2.0 introduced the dispatch helper service, which does most of the work to use dispatches in macros. The method CreateUnoService accepts the name of a service and it tries to create an instance of that service. On completion, the dispatcher variable contains a reference to a DispatchHelper.

dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

Declare an array of properties. Each property has a name and a value. In other words, it is a name/value pair. The created array has one property at index zero.

dim args1(0) as new com.sun.star.beans.PropertyValue

Give the property the name "Text" and the value "Andrew Pitonyak", which is the text that is inserted when the macro is run.

args1(0).Name = "Text"
args1(0).Value = "Andrew Pitonyak"

This is where the magic happens. The dispatch helper sends a dispatch to the document's frame (stored in the variable named document) with the command .uno:InsertText>/tt>. The next two arguments, frame name and search flags, are beyond the scope of this document. The last argument is the array of property values to be used while executing the command InsertText.

<tt>dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())

Finally, the end of the subroutine.

end sub
Content on this page is licensed under the Creative Common Attribution 3.0 license (CC-BY).
Personal tools