Fichas de referencia LO Basic

Ficha nº 2.
Las Bases

Nivel: Principiante

Generalidades

• Tiempo de desarrollo: Escritura de Código 20 % – Mantenimiento 80 %

Nombrar las entidades

Las variables, constantes, subrutinas, funciones, módulos y bibliotecas deben estar identificados con un nombre adecuado. Los caracteres permitidos son: letras no acentuadas, cifras, o guión bajo ( _ ).

• Un nombre no puede empezar por una cifra ni contener espacios.

• No use palabras reservadas del lenguaje para nombrar las entidades !

Nombres legibles: «CamelCase» o Intercalar_separadores

Nombres explicitos: LaCelda(), Guardar_Carpeta()

Indentar el código

Se recomienda indentar cada nivel de código con espacios o tabuladores para facilitar la lectura.

Comentarios

Los comentarios solo abarcan una linea y sirven para clarificar o anular las instrucciones de la macro. Son tan importantes como el código

El apóstrofo ' o REM. Indican que lo siguiente es un comentario y por tanto, no se ejecutará el código (si lo escrito son instrucciones).

• Comentar varias líneas

Seleccione las líneas que desee comentar y utilice el atajo de teclado Ctrl+Alt+C

• Varias instrucciones en la misma linea

Para incluir instrucciones distintas en una misma linea se utiliza el carácter de dos puntos ( : )

Dim MiVar As Integer : MiVar = 123

• Continuar una instrucción en la linea siguiente

Se pueden fraccionar líneas muy largas, de manera que una instrucción continúe en la siguiente línea. Los dos últimos caracteres de la linea deben ser espacio + subrayado ( _)

Variables

Variable : se sitúa en memoria, su contenido se puede modificar durante la ejecución.

La declaración de variables no es obligatoria pero no declararlas es una práctica  peligrosa: Se pueden crear duplicados en caso de errores tipográficos.

• Con Option Explicit  al inicio del módulo se muestra un error al ejecutar instrucciones si la variable no ha sido declarada. Esto es muy útil para controlar las variables.

Declaración de variables

Variables sencillas

Dim MiVar As Un_Tipo – Ejemplo : Dim MiTexto As String

Dim A As Byte, B As String – En una misma línea se separan con comas (,).

Dim MiVar As Integer : MiVar = 123 – Declaración y asignación en una única línea.

Variables compuestas (matrices)

• Vea la «Ficha nº 3 Tipos estructurados»

Asignación de variables (no Objeto)

MiVar = UnValor

• Si UnValor no es del mismo tipo que MyVar,  se hace una conversión automática.
  Es preferible convertir el tipo explicitamente (con las funciones Cxxx). Vea la «Ficha n° 6».

Creación/Asignación de variables de tipo Objeto

• Vea la «Ficha nº 3. Tipos estructurados»

Alcance (visibilidad) de las variables

Declaración…	Visibilidad ...
Dim MiVar As UnTipo	En la subrutina o módulo.
Static MiVar As UnTipo	En la subrutina. Persiste entre llamadas a otras rutinas.
Private MiVar As UnTipo	En el módulo.
Public MiVar As UnTipo	En la biblioteca.
Global MiVar As UnTipo	En todas las bibliotecas. Valor persistente entre ejecuciones !

Tipos

Especifican los valores que puede tener una variable o retorno de una función.

Tipos simples predefinidos

Tipo	Descripción	V. inicial
Boolean	Valores lógicos True / False (Verdadero / Falso) Puede verse como False = 0 ; True = 1 (u otros enteros)	False
Byte	Números enteros (8 bits), de 0 a 255.	0
Currency	Números moneda (4 decimales).	0.0000
(Decimal)	Sub-tipo de variant, obtenido por Cdec(string) 28 cifras (p.entera + p.decimal). De 1 x 10-28  a 7.9 x 1028 (precisión máxima 28 decimales). Utilizado con las funciones de la API (en enteros de 64bits). Los desbordamientos no provocan errores de ejecución.	n/a
Date	Fechas y horas. En realidad : números reales. La fecha de referencia (0.0) es el 30/12/1899 a las 00:00.	0.0
Double	Números reales (64 bits).	0.0
Integer	Números enteros (16 bits), de -32.768 a +32.767	0
Long	Enteros de (32 bits), de -2.147.483.648 a + 2.147.483.647	0
Object	Objetos. Permite la manipulación de los objetos de LibreOffice.	Null
Single	Números reales (32 bits).	0.0
String	Texto (0 a 65.545 caracteres). Las cadenas se delimitan con comillas dobles rectas (") (no tipográficas ).	""
Variant	Sirve para cualquier tipo, incluye también el objeto.	Empty

Vea también la tabla de  Compatibilidad de los tipos principales.

• Si un tipo no se declara : obtendrá un tipo Variant  de manera implícita.
  Los valores enteros pueden expresarse en base hexadecimal. Prefije estos valores con &H.
  Ejemplo: &HFF (= 255 en decimal). Útil para los colores.
  Asigne valores iniciales en lugar de contar con su iniciación implícita.

• Cuidado con los errores de redondeo en los cálculos con números reales

Matrices, tipos personalizados, Colecciones y Objetos

• Vea la «Ficha nº 3, Tipos estructurados»

Empty, Null y Nothing

Empty	Variable no inicializada. Posible asignación Empty.
Null	Contenido no válido. Posible asignación Null.
Nothing	Sólo en objetos, sin referencia al objeto. Posible asignación.

Comprobaciones

Con la función IsEmpty(UnaVariable) se puede comprobar si la variable está vacía.

Con la función IsNull(UnObjeto) se puede comprobar si se puede utilizar (existe) un objeto.

Operadores

Booleanos

NOT

No

AND

Y

OR

O (inclusivo)

XOR

O exclusivo

Comparaciones (devuelven True o False)

=	Estrictamente igual	<	Estrictamente menor	<=	Menor o igual
<>	Distinto de	>	Estrictamente mayor	>=	Mayor o igual

• Atención a las comparaciones de números reales (pueden producir errores por los redondeos)

Numéricos

+	Suma	-	Resta
*	Multiplicación	/	División
\	División entera	Mod	Módulo (resto de división entera)
^	Elevación a una potencia

Texto

&	Concatenación de texto

• También se puede usar el signo + pero no es recomendable porque es la suma y puede dar un resultado no deseado al intentar concatenar números.

Constantes

Constante : se sitúan en memoria, tienen un valor fijo (inmutable durante toda la ejecución).

Declación de constantes

Const MI_CONSTANTE = UnValor

• UnValor debe ser de un tipo simple, no puede ser matriz ni objeto

Nombre de las constantes

Es habitual nombrar las constantes con todos los caracteres en mayúsculas.

Alcance (visibilidad) de las constantes

Const MICONST = UnValor – Visible en la subrutian o módulo actual.

Public MICONST = UnValor – Visible en la biblioteca actual.

Global MICONST = UnValor –  Visible en todas las bibliotecas.

Rutas de los archivos

Al ser multi plataforma, las rutas a los archivos pueden visualizarse en formato nativo o URL :

file:///soporte/ruta/al/archivo.txt.

• En las instrucciones se debe usar siempre el formato URL

Hay dos funciones para pasar de un formato a otro :

De nativo a URL – NombreURL = ConvertToURL(NombreArchivoNativo)

De URL a nativo – Nombre = ConvertFromURL(NombreArchivoURL)

Ejemplo:

Nombre nativo (en Windows): C:\MiDirectorio\Archivo.odt

Nobre URL: file:///C:/MiDirectorio/Archivo.odt

• El formato URL: Un URL (Uniform Resource Locator) indica la dirección de un documento o servidor. Estructura general  : servicio://anfitrión:puerto/ruta/página#marca
  (según el caso, ciertos elementos pueden no estar presentes). Un URL puede ser una dirección FTP, de internet (HTTP), de archivo o de correo electrónico.

Subrutinas

• Respete la concordancia de argumentos ↔  en número, en orden y en tipo.

• Salida prematura de subrutina o función : Exit Sub, Exit Function

Sub

Las Subrutinas ejecutan una acción.

• Sugerencia de Nombre : verbo en infinitivo ; HacerXxx, LeerXxx, etc.

Declaración

Sub NombreDeLaSub(parámetros)

Estructura

Sub NombreDeLaSub(parámetros)
 'instrucciones
End Sub

Uso

 NombreDeLaSub(argumentos) o si no hay argumentos: NombreDeLaSub()

Function

Las funciones ejecutan una acción y también devuelven un valor.

• Sugerencia de Nombre : verbo en indicativo : ListaXxx(), EstXxx(), etc.

Declaración

Function NombreFuncion(parámetros) As UnTipo

Estructura

Function N_Funcion(parámetros) As UnTipo
 'instrucciones
 'definir el valor de retorno en algún punto:
 NombreFuncion = UnValor
End Function

Uso

UnaVariable = N_Funcion(arg) O si no hay argumentos: UnaVariable = N_Funcion()

• Se puede llamar a una Función como una subrutina (sin necesidad de usar su valor de retorno).

Parámetros o argumentos

Realmente un parámetro es lo mismo que un argumento. La diferencia está en el nombre que está condicionado por dónde se presenta:

Argumento – Al hacer una llamada a otra subrutina, se pasa el valor como argumento

Parámetro – El valor que ha pasado una subrutina, necesario para la función o subrutina .

Ejemplo de Uso

MiSub(ByRef Param1 As Long, ByVal Param2 As Long, Optional ByRef Param3 As Object)

ByRef (Por referencia - es el valor predeterminado). El parámetro recibido apunta al argumento pasado por la llamada.

• Toda modificación del valor de un parámetro ByRef dentro de la llamada repercute en la subrutina que hace la llamada. Es decir:
  Si desde una subrutina se hace una llamada a otra subrutina con un argumento de valor 1 y la segunda subrutina cambia ese valor a 5, al volver a la primera, el valor es 5

ByVal (Por valor). El parámetro es una copia del argumento pasado

• Las modificaciones de valor se quedan dentro de la subrutina que hace la llamada.

Optional (Parámetro opcional)

• Comprobar su ausencia con If IsMissing(UnParam) Then …
  El Identificador siempre es utilizable dentro de la subrutina

• Dar un valor predeterminado a un parámetro opcional :
  If IsMissing(UnParam) Then UnParam = UnValor

Estructuras de control

Bucles

Repetición de una serie de instrucciones según una condición.

• Es posible salir del bucle prematuramente mediante Exit For o Exit Do

For … Next (Para cada valor del contador …)

Es necesario saber los límites del contador.Por defecto el paso de incremento es 1.

For i = inicio To Fin [incremento]
 'instrucciones
Next i

• Los contadores suelen ser i, j, k, etc.

• El contador no debe ser nunca modificado por las instrucciones del bucle !

For Each … Next (Por cada elemento …)

No es necesario saber el número de elementos. Elemento debe ser un tipo compatible.

For Each Elemento In UnObjeto
 'hacer algo con el elemento
Next

Do While … Loop / While … Wend (Hacer algo … Mientras que)

Condición evaluada al principio de cada pasada.

Do While Condición
 'instrucciones
Loop

o también la sintaxis antigua:

While Condición
 'instrucciones
Wend

• La sintaxis antigua, está permitida por compatibilidad pero se debe evitar su uso. No acepta salida de bucle (Exit).

Do Loop ... Until (Hacer algo … hasta que)

Condición evaluada al final de cada pasada..

Do
 'instrucciones
Loop Until Condición

• Tenga Cuidado con los bucles infinitos (Condición que nunca se cumple)

Comprobaciones condicionales

Derivación que permite actuar según un estado o una situación.

If en una línea (If … Then)

Si se cumple la condición se ejecuta una instrucción

If Condición Then UnaInstrucción

If en varias líneas (If … Then … [Else] .. End If)

Si se cumple la condición se ejecutan unas instrucciones.

If Condición Then
 'Instrucciones si se cumple
Else ' La instrucción Else es facultariva.
 'Instrucciones si la condición no se cumple
End If

If… Then … ElseIf … Else … End If

Permite evitar la anidación de varios  If

If Condición Then
 'Instrucciones1
ElseIf OtraCondición Then
 'Instrucciones2
Else
 'Instrucciones en otro caso
End If

Select Case … End Select

Elección entre varias posibilidades en función del valor de «UnaVariable».

Select Case UnaVariable
 Case Valor : 'Instrucciones para «Valor»
 Case otro_Valor
   instrucciones para «otro_Valor»
 Case Val1, Val2 To Val3
   'instrucciones para varios valores
 Case Else
   'instrucciones para otros casos
End Select

Cargar bibliotecas de código Basic

Para una mejor lectura, organice su código en varias bibliotecas (Ficha nº1, El EDI).

• Al abrir un documento, sólo se carga la biblioteca de código Standard. Las otras deben ser cargadas explicitamente para usar su código.

• Los nombres de las bibliotecas son sensibles a las Mayúsculas !

Cargar desde un contenedor local (en el documento)

If BasicLibraries.hasByName("Mibiblioteca")then 'Verificar si existe
  BasicLibraries.loadLibrary("Mibiblioteca")'Carga

Cargar desde un contenedor global (En el programa)

Igual,  pero BasicLibraries se debe reemplazar por GlobalScope.BasicLibraries.

• Cuidado con las colisiones de indentificadores entre bibliotecas ! Puede calificar los nombres de la siguiente manera : contenedor.biblioteca.modulo.nombre (parcial o totalmente).
  Ejemplo : GlobalScope.Tools.Strings.ClearMultiDimArray(MiTabla,3)

Llamar a un comando asociado a un menú LibreOffice

Principio

Uso del Dispatcher, asociado al comando del menu UNO elegido.

Conocer los comandos de menú UNO

Hay un listado de comandos de menú UNO: ver archivos menubar.xml el el directorio de instalación de LibreOffice (según  S.O.), en share/config/soffice.cfg/modules. Subdirectorio menubar del módulo (ej. : sglobal/menubar/menubar.xml, etc.). También se puede consultar la siguiente página https://wiki.documentfoundation.org/Development/DispatchCommands

Todos los comandos comienzan por .uno: Ej : .uno:Open (= Archivo ► Abrir), .uno:OptionsTreeDialog (= Herramientas ► Opciones), etc.

Esqueleto del programa a ejecutar

Dim Frame As Variant
Dim Dispatch As Object
Dim Args() As Variant 'contenido dependiente del contexto
Dim UnoCmd As String
 Frame  = ThisComponent.CurrentController.Frame
 UnoCmd = 'El comando UNO a ejecutar entrecomillado
 Dispatch = createUnoService("com.sun.star.frame.DispatchHelper")
 Dispatch.executeDispatch(Frame, UnoCmd, "", 0, Args())

Ejemplos

En los ejemplos sólo se muestran las partes modificadas

Ej.1 Llamada a la vista previa de Impresión

Dispatch.executeDispatch(Frame, ".uno:PrintPreview", "", 0, Args())

Ej.2 Mostrar/ocultar la barra lateral

Algunos comandos Uno necesitan argumentos:

Dim Args(0) As New com.sun.star.beans.PropertyValue
 Args(0).Name  = "Sidebar"
 Args(0).Value = True  'o False según objetivo
 Dispatch.executeDispatch(Frame, ".uno:Sidebar", "", 0, Args())

Gestión de errores

En Basic la gestión de errores se basa en :

• las instrucciones On Error Xxx ( y On Local Error Xxx) : interceptan los errores;

• las funciones Err, Erl y Error : informan del último error encontrado.

Funciones de información de error

Err – El código del error intervenido.

Error – El texto del mensaje descriptivo del error.

Erl – El número de linea donde se produjo el error.

1. El código de error 0 (cero) es igual a  «sin errores».
   Utilice : If Err = [#] Then … para comprobar existencia de un error de número #.

Interceptación global de errores

On Error

• La interceptación de errores con OnError queda activa hasta que se anula.

On Error Goto MiEtiqueta : Activa la interceptación de errores. En caso de error la ejecución continua en MiEtiqueta:.En el bloque de código se debe definir la etiqueta MiEtiqueta:

(usando los dos puntos al final del nombre de la etiqueta).

On Error Resume Next – Activa la interceptación de errores. En caso de error la ejecución continua en la siguiente instrucción.

On Error Goto 0 – Anula la interceptación de errores.

On Local Error

En una subrutina, se puede utilizar On Local Error Xxx (misma sintaxis). En bastantes casos es preferible puesto que no necesita recurrir a On Error Goto 0  para anular la interceptación de errores : la anulación es automática al salir de la rutina o función.

• On Local Error Goto Xxx tiene precedencia sobre On Error Goto Xxx .

Métodos de ejecución de una macro

▼ Método	LibreOffice	Tipo de documento	Documento activo
Barra de herramientas		✔	✔
Menú		✔	✔
Atajo de teclado	✔	✔
Por evento	✔		✔

Compatibilidad de los tipos principales

Destino ▶ Origen ▼	Integer	Long	Single	Double	Currency	Decimal	Date	String	Object	Boolean	Variant	Byte
Integer	✔	✔	✔	✔	✔	✔	✔	✔	x	✔	✔	!
Long	!	✔	✔	✔	✔	✔	✔	✔	x	✔	✔	!
Single	○!	○!	✔	✔	✔	✔	✔	✔	x	!	✔	○!
Double	○!	○!	○!	✔	✔	✔	✔	✔	x	!	✔	○!
Currency	○!	○!	!	✔	✔	✔	○	✔	x	!	✔	○!
Decimal	○!	○!	○!	○	○!	✔	○	✔	x	○!	✔	○!
Date	○!	○!	!	✔	✔	○!	✔	✔	x	!	✔	○!
String	○!	○!	○!	○!	○!	✔	○!	✔	x	○!	✔	○!
Object	x	x	x	x	x	x	x	x	✔	x	✔	x
Boolean	✔	✔	✔	✔	✔	✔	✔	✔	x	✔	✔	○
Variant	○!	○!	○!	○!	○!	✔	○!	○!	✔	○!	✔	○!
Byte	✔	✔	✔	✔	✔	✔	✔	✔	x	✔	✔	✔

✔

Compatible

○

Posible pérdida

!

Posible desbordamiento

x

incompatible

Lectura

• El contenido de una variable origen de tipo Double puede ser asignada a una variable destino de tipo Double, Currency, Date, o Variant, sin pérdida.

• Una variable destino de tipo doble puede recibir sin pérdida de datos los tipos Integer, Long, Single, Double, Date o Byte.

Contenido

• Generalidades

• Variables

• Tipos

• Empty, Null y Nothing

• Operadores

• Constantes

• Rutas de los archivos

• Subrutinas

• Estructuras de control

• Cargar bibliotecas de código Basic

• Llamar a un comando asociado a un menú LibreOffice

• Gestión de errores

• Métodos de ejecución de una macro

• Compatibilidad de los tipos principales