Edukiak

# ScriptForge.Session zerbitzua

Session zerbitzuak xede orokorreko zenbait metodo biltzen ditu, honakoei lotutakoak:

- instalazioko edo exekuzioko ingurunea

- UNO barne-behaketa

- kanpoko scriptak edo programak deitzea

## Zerbitzuari deitzea

Session zerbitzua erabiltzeko, ScriptForge liburutegia kargatu edo inportatu behar da:

• Basic makroak erabiltzkeo, ScriptForge liburutegia kargatu behar da honako instrukzioa erabiliz:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scriptak erabiltzeko, berriz, scriptforge modulu baten inportazioa behar dute:
from scriptforge import CreateScriptService

##### Basic lengoaian

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim session As Variant
        session = CreateScriptService("Session")

##### Python lengoaian

        from scriptforge import CreateScriptService
        session = CreateScriptService("Session")

## Konstanteak

Behean, deituko den Basic edo Python script bat duen liburutegia izendatzea errazteko erabilgarri dauden konstanteen zerrenda. Erabili horiek session.CONSTANT gisa.

CONSTANT | Balioa | Non dago liburutegia? | Aplikagarria
--- | --- | --- | ---
SCRIPTISEMBEDDED | "document" | dokumentuan | Basic + Python
SCRIPTISAPPLICATION | "application" | partekatutako edozein liburutegitan | Basic
SCRIPTISPERSONAL | "user" | Nire makroak atalean | Python
SCRIPTISPERSOXT | "user:uno_packages" | uneko erabiltzailearentzako instalatutako hedapen batean | Python
SCRIPTISSHARED | "share" | Aplikazio-makroak atalean | Python
SCRIPTISSHAROXT | "share:uno_packages" | erabiltzaile guztientzat instalatutako hedapen batean | Python
SCRIPTISOXT | "uno_packages" | instalazio-parametro ezezagunak dituen hedapen batean | Python

Session zerbitzuaren metodoen zerrenda
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

Session zerbitzuaren Execute... metodoek honela jokatzen dute:
Argumentuak balioaren bidez pasatzen dira. Deitutako funtzioak argumentuei egindako aldaketek ez dituzte beren balioak eguneratzen deitzen duen scriptean.
Deitzen duen scriptean balio bakar bat edo balioen matrize bat itzultzen da.

## ExecuteBasicScript

Exekutatu BASIC scripta bere izena eta kokalekua emanda, eta atzitu emaitza, halakorik balego.

Scriptak ez badu ezer itzultzen, adibidez Sub bidez definitutako prozeduretan gertatzen den moduan, itzulitako balioa Empty izango da.

### Sintaxia:

session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any

### Parametroak:

scope: Scripta non dagoen gordeta zehazten duen katea. Izan daiteke bai "dokumentua" (session.SCRIPTISEMBEDDED konstantea) bai "aplikazioa" (session.SCRIPTISAPPLICATION konstantea).

script: Deituko den scripta zehazten duen katea. Formatua "library.module.method" motakoa da, eta maiuskulak/minuskulak bereizten dira.

- Liburutegia memorian kargatuko da, beharrezkoa bada.

- Moduluak ez du klase-modulua izan behar.

- Metodoa Sub bat edo Function bat izan daiteke.

args: Deitutako scriptari pasatuko zaizkion argumentuak.

### Adibidea:

Begiratu, adibidez, "Standard" liburutegiko "Nire makroak" kokagunean, "Module1" izeneko modulu baten barruan, gordeta dagoen DummyFunction izeneko funtzioa.

Funtzioak bi osoko balio hartzen ditu, v1 eta v2, eta balio guztien batuketa itzultzen du, v1 balioan hasi eta v2 balioan amaitu arte.

        Function DummyFunction(v1 as Integer, v2 as Integer) As Long
            Dim result as Long, i as Integer
            For i = v1 To v2
                result = result + i
            Next i
            DummyFunction = result
        End Function

Beheko adibidean, Basic eta Python scriptetatik DummyFunction nola deitu erakusten da.

##### Basic lengoaian

        Dim session : session = CreateScriptService("Session")
        Dim b_script as String, result as Long
        b_script = "Standard.Module1.DummyFunction"
        result = session.ExecuteBasicScript("application", b_script, 1, 10)
        MsgBox result ' 55

##### Python lengoaian

        session = CreateScriptService("Session")
        bas = CreateScriptService("Basic")
        b_script = 'Standard.Module1.DummyFunction'
        result = session.ExecuteBasicScript('application', b_script, 1, 10)
        bas.MsgBox(result) # 55

## ExecuteCalcFunction

Exekutatu Calc funtzio bat bere ingelesezko izena erabilita eta emandako argumentuetan oinarrituta.
Argumentuak matrizeak badira, funtzioa matrize-formula modura exekutatuko da.

### Sintaxia:

session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any

### Parametroak:

calcfunction: Deituko den Calc funtzioaren izena, ingelesez.

args: Deitutako Calc funtzioari emango zaizkion argumentuak. Argumentu bakoitzak katea, zenbakizko balioa edo mota horiek konbinatzen dituzten matrizeen matrizea izan behar du.

### Adibidea:

##### Basic lengoaian

        session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) ' 4
        session.ExecuteCalcFunction("ABS", Array(Array(-1, 2, 3), Array(4, -5, 6), Array(7, 8, -9)))(2)(2) ' 9
        session.ExecuteCalcFunction("LN", -3)
        ' Errore bat sortzen du.

##### Python lengoaian

        session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) # 4
        session.ExecuteCalcFunction("ABS", ((-1, 2, 3), (4, -5, 6), (7, 8, -9)))[2][2] # 9
        session.ExecuteCalcFunction("LN", -3)

## ExecutePythonScript

Exekutatu Python scripta, bere kokalekua eta izena emanda, eta atzitu emaitzak, halakorik badago. Emaitza balio bakarra edo balioen matrizea izan daiteke.

Scripta aurkitzen ez bada edo ezer ez bada itzultzen, itzulitako balioa Empty izango da.

LibreOffice Application Programming Interface (API) scriptgintzako lan-markoak lengoaien arteko scripten exekuzioa onartzen du Python eta Basic lengoaien kasuan, baina baita onartutako beste edozein programazio-lengoaiaren kasuan ere. Argumentuak atzera eta aurrera pasatu daitezke deietan, bi lengoaiek ezagutzen dituzten jatorrizko datu motak ordezkatzen badituzte, eta scriptgintzako lan-markoak haiek modu egokian bihurtuko dituztela onartuta.

### Sintaxia:

session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any

### Parametroak:

scope: One of the applicable constants listed above. The default value is session.SCRIPTISSHARED.

script: "library/module.py$method" edo "module.py$method" edo "myExtension.oxt|myScript|module.py$method", maiuskulak/minuskulak bereizten dituen kate gisa.

- liburutegia: Python modulua dagoen karpetaren bide-izena.

- nireScripta: Python modulua dagoen karpeta.

- modulua.py: Python modulua.

- metodoa: Python funtzioa.

args: Deitutako scriptari pasatuko zaizkion argumentuak.

### Adibidea:

Adibidez, behean definitutako odd_integers Python funtzioak v1 eta v2 arteko osoko zenbaki bakoitien zerrenda bat sortzen du. Demagun funtzio hori zure erabiltzaile-scripten karpetako my_macros.py fitxategian dagoela gordeta.

        def odd_integers(v1, v2):
            odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]
            return odd_list

Irakurri Python scripten antolaketa eta kokalekua laguntza-orria Python scriptak non gorde daitezkeen ikasteko.

Hurrengo adibideetan, Basic eta Python scriptetatik odd_integers funtzioari deitzeko modua erakusten da.

##### Basic lengoaian

        Dim script as String, session as Object
        script = "my_macros.py$odd_integers"
        session = CreateScriptService("Session")
        Dim result as Variant
        result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
        MsgBox SF_String.Represent(result)

##### Python lengoaian

        session = CreateScriptService("Session")
        script = "my_macros.py$odd_integers"
        result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
        bas.MsgBox(repr(result))

## GetPDFExportOptions

PDF aukerak elkarrizketa-koadroan PDFak esportatzeko definitu diren uneko ezarpenak itzultzen ditu. Ezarpen horiek Fitxategia - Esportatu honela - Esportatu PDF gisa aukeratik atzitu daitezkeenak dira.

PDF aukerak elkarrizketa-koadroarekin ezarritako esportazio-aukerak etorkizunerako gordetzen dira. Hortaz, GetPDFExportOptions funtzioak unean definitutako ezarpenak itzultzen ditu. Horrez gain, erabili SetPDFExportOptions PDFak esportatzeko uneko aukerak aldatzeko.

Metodo honek Dictionary objektu bat itzultzen du, non gako bakoitzak esportazio-aukera bat ordezkatzen duen eta hari dagokion balioak PDFa esportatzeko uneko ezarpen bat den.

Irakurri PDF esportazioaren wiki-orria to erabilgarri dauden aukera guztiak ezagutzeko.

### Sintaxia:

session.GetPDFExportOptions(): obj

### Adibidea:

##### Basic lengoaian

        Dim expSettings As Object, msg As String, key As String, optLabels As Variant
        expSettings = session.GetPDFExportOptions()
        optLabels = expSettings.Keys
        For Each key in optLabels
            msg = msg + key & ": " & expSettings.Item(key) & Chr(10)
        Next key
        MsgBox msg
        ' Zoom: 100
        ' Changes: 4
        ' Quality: 90
        ' ...

Metodo hau Basic scriptetan soilik dago erabilgarri.

## HasUnoMethod

True itzultzen du UNO objektu batek metodoa badauka. False itzultzen du metodoa aurkitzen ez bada edo argumentu bat baliogabea bada.

### Sintaxia:

session.HasUnoMethod(unoobject: uno, methodname: str): bool

### Parametroak:

unoobject: Ikuskatuko den objektua.

methodname: Metodoaren izena, maiuskulak/minuskulak bereizten dituen kate gisa

### Adibidea:

##### Basic lengoaian

        Dim a As Variant
        a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox session.HasUnoMethod(a, "callFunction") ' True

##### Python lengoaian

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoMethod(a, "callFunction")
        bas.MsgBox(result) # True

## HasUnoProperty

True itzultzen du UNO objektu batek propietatea badauka. False itzultzen du propietatea aurkitzen ez bada edo argumentu bat baliogabea bada.

### Sintaxia:

session.HasUnoProperty(unoobject: uno, propertyname: str): bool

### Parametroak:

unoobject: Ikuskatuko den objektua.

propertyname: Propietatea, maiuskulak/minuskulak bereizten dituen kate gisa

### Adibidea:

##### Basic lengoaian

        Dim svc As Variant
        svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox session.HasUnoProperty(svc, "Wildcards")

##### Python lengoaian

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoProperty(a, "Wildcards")
        bas.MsgBox(result) # True

## OpenURLInBrowser

Ireki Uniform Resource Locator (URL) bat nabigatzaile lehenetsian.

### Sintaxia:

session.OpenURLInBrowser(url: str)

### Parametroak:

url: Irekiko den URLa.

### Adibidea:

        ' Basic
        session.OpenURLInBrowser("help.libreoffice.org/")

        # Python
        session.OpenURLInBrowser("help.libreoffice.org/")

## RunApplication

Sistemako komando bat ausaz exekutatzen du eta True itzultzen du ongi abiarazi bada.

### Sintaxia:

session.RunApplication(command: str, parameters: str): bool

### Parametroak:

command: Exekutatuko den komandoa. Fitxategi exekutagarri bat izan daiteke edo aplikazio batekin erregistratuta dagoen dokumentu bat, sistemak jakin dezan zein aplikazio abiarazi behar den dokumentu horretarako. Komandoa uneko SF_FileSystem.FileNaming notazioan adierazi behar da.

parameters: Zuriunez bereizitako parametroen zerrenda ba, kate bakar gisa. Metodoak ez ditu emandako parametroak balioztatzen, zehaztutako komandoari haiek pasatu besterik ez du egiten.

### Adibidea:

##### Basic lengoaian

        session.RunApplication("Notepad.exe")
        session.RunApplication("C:\myFolder\myDocument.odt")
        session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux

##### Python lengoaian

        session.RunApplication("Notepad.exe")
        session.RunApplication(r"C:\myFolder\myDocument.odt")
        session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux

## SendMail

Bidali mezua -aukeran eranskinak gehituta- erabiltzailearen posta elektronikoko bezeroko hartzaileei. Erabiltzaileak mezua editatu dezake hura bidali baino lehen edo, bestela, berehala bidali dezake.

### Sintaxia:

session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)

### Parametroak:

recipient: Posta elektronikoko helbide bat ("Nori" hartzailea).

cc: Posta elektronikoko helbideen zerrenda bat, komaz bananduta ("carbon copy" hartzaileak).

bcc: Posta elektronikoko helbideen zerrenda bat, komaz bananduta ("blind carbon copy" hartzaileak).

subject: Mezuaren gaia.

body: Mezuaren edukia, formaturik gabeko testu gisa.

filenames: Fitxategi-izenen zerrenda bat, komaz bananduta. Fitxategi-izen bakoitzak SF_FileSystem.FileNaming notazioa jarraitu behar du.

editmessage: True (lehenetsia) bada, mezua editatu egingo da bidalia izan baino lehen.

### Adibidea:

##### Basic lengoaian

        session.SendMail("someone@example.com" _
            , Cc := "b@other.fr, c@other.be" _
            , FileNames := "C:\myFile1.txt, C:\myFile2.txt")

##### Python lengoaian

        session.SendMail("someone@example.com",
                         cc="john@other.fr, mary@other.be"
                         filenames=r"C:\myFile1.txt, C:\myFile2.txt")

## SetPDFExportOptions

PDF aukerak elkarrizketa-koadroan PDFak esportatzeko definitu diren uneko ezarpenak aldatzen ditu. Ezarpen horiek Fitxategia - Esportatu honela - Esportatu PDF gisa aukeratik atzitu daitezkeenak dira.

Metodo honi deitzen bazaio, PDF aukerak elkarrizketa-koadroan ezarritako uneko balioak aldatuko dra. Document zerbitzuko ExportAsPDF metodoak balio horiek erabiliko ditu.

Metodoak True itzultzen du arrakasta duenean.

Irakurri PDF esportazioaren wiki-orria to erabilgarri dauden aukera guztiak ezagutzeko.

### Sintaxia:

session.SetPDFExportOptions(pdfoptions: obj): bool

### Parametroak:

pdfoptions: Aldatuko diren PDF esportazioko ezarpenak definitzen dituen Dictionary objektua. Gako-balio bikote bakoitzak esportazio-aukera bat eta elkarrizketa-koadroan ezarriko zaion balioa ordezkatzen ditu.

### Adibidea:

##### Basic lengoaian

Hurrengo adibidean, gehieneko irudi-bereizmena 150 dpi-ra aldatzen da eta uneko dokumentua PDF fitxategi gisa esportatzen da.

        Dim newSettings As Object, oDoc As Object
        Set oDoc = CreateScriptService("Document")
        Set newSettings = CreateScriptService("Dictionary")
        newSettings.Add("ReduceImageResolution", True)
        newSettings.Add("MaxImageResolution", 150)
        session.SetPDFExportOptions(newSettings)
        oDoc.ExportAsPDF("C:\Documents\myFile.pdf", Overwrite := True)

Metodo hau Basic scriptetan soilik dago erabilgarri.

## UnoMethods

UNO objektu batetik deitu daitezkeen metodoen zerrenda itzultzen du. Zerrenda zeron oinarritutako matrize bat da, katez osatutakoa, eta hutsik egon daiteke.

### Sintaxia:

session.UnoMethods(unoobject: uno): str[0..*]

### Parametroak:

unoobject: Ikuskatuko den objektua.

### Adibidea:

##### Basic lengoaian

        Dim svc : svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        Dim methods : methods = session.UnoMethods(svc)
        Dim msg as String
        For Each m in methods
            msg = msg & m & Chr(13)
        Next m
        MsgBox msg

##### Python lengoaian

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        methods = session.UnoMethods(a)
        msg = "\n".join(methods)
        bas.MsgBox(msg)

## UnoProperties

UNO objektu baten propietateen zerrenda itzultzen du. Zerrenda zeron oinarritutako matrize bat da, katez osatutakoa, eta hutsik egon daiteke.

### Sintaxia:

session.UnoProperties(unoobject: uno): str[0..*]

### Parametroak:

unoobject: Ikuskatuko den objektua.

### Adibidea:

##### Basic lengoaian

        Dim svc As Variant
        svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True

##### Python lengoaian

        bas = CreateScriptService("Basic")
        svc = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        properties = session.UnoProperties(a)
        b = "Wildcards" in properties
        bas.MsgBox(str(b)) # True

## UnoObjectType

Identifikatu UNO objektu baten mota kate gisa.

### Sintaxia:

session.UnoObjectType(unoobject: uno): str

### Parametroak:

unoobject: Identifikatuko den objektua.

### Adibidea:

##### Basic lengoaian

        Dim svc As Variant, txt As String
        svc = CreateUnoService("com.sun.star.system.SystemShellExecute")
        txt = session.UnoObjectType(svc) ' "com.sun.star.comp.system.SystemShellExecute"
        svc = CreateUnoStruct("com.sun.star.beans.Property")
        txt = session.UnoObjectType(svc) ' "com.sun.star.beans.Property"

##### Python lengoaian

        bas = CreateScriptService("Basic")
        svc = bas.CreateUnoService("com.sun.star.system.SystemShellExecute")
        txt = session.UnoObjectType(svc) # "com.sun.star.comp.system.SystemShellExecute"
        svc = bas.CreateUnoService("com.sun.star.beans.Property")
        txt = session.UnoObjectType(svc) # "com.sun.star.beans.Property"

## WebService

Eskuratu web-edukia URI batetik.

### Sintaxia:

session.WebService(uri: str): str

### Parametroak:

uri: Web-zerbitzuaren URI helbidea.

### Adibidea:

##### Basic lengoaian

        session.WebService("wiki.documentfoundation.org/api.php?" _
            & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")

##### Python lengoaian

        session.WebService(("wiki.documentfoundation.org/api.php?"
                           "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))

Azpimarraren karaktere bat, "_", aurrizki gisa duten ScriptForge Basic errutina edo identifikatzaile guztiak barneko erabilerarako erreserbatuta daude. Ez dira Basic makroetan edo Python scriptetan erabili behar.

Erlazionatutako gaiak

Array funtzioa

Calc funtzioak makroetan erabiltzea

Python scriptak Basic-etik deitzea

ScriptForge.Basic zerbitzua

ScriptForge.FileSystem zerbitzua