Υπηρεσία ScriptForge.UI

Η υπηρεσία UI (διεπαφή χρήστη) απλοποιεί την αναγνώριση και τον χειρισμό των διαφορετικών παραθύρων που συνθέτουν ολόκληρη την εφαρμογή του LibreOffice:

tip

Η υπηρεσία διεπαφής χρήστη είναι το σημείο εκκίνησης για το άνοιγμα, τη δημιουργία ή την πρόσβαση στο περιεχόμενο νέων ή υφιστάμενων εγγράφων από ένα σενάριο χρήστη.


Ορισμοί

WindowName

Ένα παράθυρο μπορεί να οριστεί με διάφορους τρόπους:

Το όνομα του παραθύρου κάνει διάκριση πεζών-κεφαλαίων.

Αντικείμενο εγγράφου

The methods CreateDocument, CreateBaseDocument, GetDocument and OpenDocument, described below, generate document objects. When a window contains a document, an instance of the Document class represents that document. A counterexample the Basic IDE is not a document but is a window in our terminology. Additionally a document has a type: Calc, Impress, Writer, ...

Οι συγκεκριμένες ιδιότητες και μέθοδοι που ισχύουν στα έγγραφα υλοποιούνται σε μια κλάση εγγράφων.

tip

Η υλοποίηση της κλάσης αντικειμένων εγγράφου γίνεται στη συσχετισμένη βιβλιοθήκη SFDocuments. Δείτε την υπηρεσία "Document".


Κλήση υπηρεσίας

Σε Basic

    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
Σε Python

    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  

Ιδιότητες

Όνομα

Μόνο για ανάγνωση

Τύπος

Περιγραφή

ActiveWindow

Ναι

String

ένα έγκυρο και μοναδικό WindowName για το τρέχον ενεργό παράθυρο. Όταν το παράθυρο δεν μπορεί να αναγνωριστεί, επιστρέφεται μια συμβολοσειρά μηδενικού μήκους.

Documents

Ναι

String array

Ο κατάλογος με τα τρέχοντα ανοιχτά έγγραφα. Τα ειδικά παράθυρα αγνοούνται. Αυτός ο κατάλογος αποτελείται από έναν μηδενικό μονοδιάστατο πίνακα είτε ονομάτων αρχείων (σε σημειογραφία SF_FileSystem.FileNaming), είτε από τίτλους παραθύρων για μη αποθηκευμένα έγγραφα.


Σταθερές

Όνομα

Τιμή

Περιγραφή

MACROEXECALWAYS

2

Οι μακροεντολές εκτελούνται πάντα

MACROEXECNEVER

1

Οι μακροεντολές δεν εκτελούνται ποτέ

MACROEXECNORMAL

0

Η εκτέλεση των μακροεντολών εξαρτάται από τις ρυθμίσεις του χρήστη


Παράδειγμα:

Τα παρακάτω παραδείγματα δείχνουν ένα MsgBox με τα ονόματα όλων των ανοιχτών εγγράφων.

Σε Basic

      Dim openDocs as Object, strDocs as String
     Set openDocs = ui.Documents()
     strDocs = openDocs(0)
     For i = 1 to UBound(openDocs)
         strDocs = strDocs & Chr(10) & openDocs(i)
     Next i
     MsgBox strDocs
   
Σε Python

     ui = CreateScriptService("UI")
     bas = CreateScriptService("Basic")
     openDocs = ui.Documents()
     strDocs = "\n".join(openDocs)
     bas.MsgBox(strDocs)
   

Κατάλογος μεθόδων στην υπηρεσία UI

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)

Resize
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

Σημειώστε, κατ' εξαίρεση, ότι οι μέθοδοι με την ένδειξη (*) δεν ισχύουν για έγγραφα Base.


Activate

Ενεργοποιεί το καθορισμένο παράθυρο. Η μέθοδος επιστρέφει True εάν το δεδομένο παράθυρο βρεθεί και μπορεί να ενεργοποιηθεί. Δεν υπάρχει αλλαγή στην πραγματική διεπαφή χρήστη εάν κανένα παράθυρο δεν ταιριάζει με την επιλογή.

Σύνταξη:

svc.Activate(windowname: str): bool

Παράμετροι:

windowname (όνομα παραθύρου): δείτε τους ορισμούς παραπάνω.

Παράδειγμα:

Σε Basic

      ui.Activate("C:\Documents\My file.odt")
    
Σε Python

      ui.Activate(r"C:\Documents\My file.odt")
    

CreateBaseDocument

Δημιουργεί και αποθηκεύει ένα νέο έγγραφο του LibreOffice Base που ενσωματώνει μια κενή βάση δεδομένων του συγκεκριμένου τύπου. Η μέθοδος επιστρέφει μια παρουσία υπηρεσίας Document.

Σύνταξη:

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

Παράμετροι:

filename (όνομα αρχείου): Προσδιορίζει το αρχείο προς δημιουργία. Πρέπει να ακολουθεί τη σημειογραφία SF_FileSystem.FileNaming. Εάν το αρχείο υπάρχει ήδη, αντικαθίσταται χωρίς προειδοποίηση

embeddeddatabase (ενσωματωμένη βάση δεδομένων): Είτε "HSQLDB" (προεπιλογή), "FIREBIRD" ή "CALC".

registrationname (όνομα καταχώρησης): Το όνομα που χρησιμοποιείται για την αποθήκευση της νέας βάσης δεδομένων στο μητρώο βάσεων δεδομένων. Όταν = "" (προεπιλογή), δεν πραγματοποιείται εγγραφή. Εάν το όνομα υπάρχει ήδη, αντικαθίσταται χωρίς προειδοποίηση.

filename (όνομα αρχείου calc): Μόνο όταν η embeddeddatabase = "CALC", το calcfilename αντιπροσωπεύει το αρχείο που περιέχει τους πίνακες ως φύλλα Calc. Το αρχείο πρέπει να υπάρχει διαφορετικά εμφανίζεται σφάλμα.

Παράδειγμα:

Σε Basic

      Dim myBase As Object, myCalcBase As Object
      Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
      Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
          "CALC", , "C:\Databases\MyCalcFile.ods")
   
Σε Python

     myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
     myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
         "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")
   

CreateDocument (*)

Δημιουργία νέου εγγράφου του LibreOffice συγκεκριμένου τύπου ή με βάση ένα δεδομένο πρότυπο. Η μέθοδος επιστρέφει ένα αντικείμενο εγγράφου.

Σύνταξη:

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

Παράμετροι:

documenttype (τύπος εγγράφου): "Calc", "Writer" κ.λπ. Εάν δεν υπάρχει, πρέπει να υπάρχει το όρισμα templatefile.

templatefile (αρχείο προτύπου): Το πλήρες FileName (Όνομα αρχείου) του προτύπου για τη δημιουργία του νέου εγγράφου. Εάν το αρχείο δεν υπάρχει, το όρισμα αγνοείται. Η υπηρεσία FileSystem παρέχει τις ιδιότητες TemplatesFolder και UserTemplatesFolder για να βοηθήσει στη δημιουργία του ορίσματος.

hidden (κρυφό): εάν είναι True, ανοίξτε το νέο έγγραφο στο παρασκήνιο (προεπιλογή = False). Να χρησιμοποιείται με προσοχή: η ενεργοποίηση ή το κλείσιμο κατόπιν, μπορεί να γίνει μόνο μέσω προγραμματισμού.

Παράδειγμα:

Και στα δύο παρακάτω παραδείγματα, η πρώτη κλήση στη μέθοδο CreateDocument δημιουργεί ένα κενό έγγραφο Calc, ενώ η δεύτερη δημιουργεί ένα έγγραφο από ένα αρχείο προτύπου.

Σε Basic

      Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
      Set myDoc1 = ui.CreateDocument("Calc")
      Set FSO = CreateScriptService("FileSystem")
      Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
   
Σε Python

     myDoc1 = ui.CreateDocument("Calc")
     FSO = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
   

GetDocument

Returns a document object referring to either the active window, a given window or the active document.

Σύνταξη:

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

Παράμετροι:

windowname (όνομα παραθύρου): Δείτε τους παραπάνω ορισμούς. Εάν αυτό το όρισμα απουσιάζει, χρησιμοποιείται το ενεργό παράθυρο. Γίνονται επίσης αποδεκτά αντικείμενα UNO των τύπων com.sun.star.lang.XComponent ή com.sun.star.comp.dba.ODatabaseDocument. Έτσι, μεταβιβάζοντας το ThisComponent ή το ThisDatabaseDocument ως όρισμα δημιουργείται μια νέα υπηρεσία SFDocuments.Document, Base ή Calc.

Παράδειγμα:

Σε Basic

      Dim myDoc As Object
      Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
      Set myBase = ui.GetDocument(ThisDatabaseDocument)
   
Σε Python

     myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
     from scriptforge import CreateScriptService
     bridge = CreateScriptService("Basic")
     myDoc = ui.GetDocument(bridge.ThisComponent)
   
tip

Για πρόσβαση στο όνομα του ενεργού παραθύρου, ανατρέξτε στην ιδιότητα ActiveWindow.


Maximize

Μεγιστοποιεί το ενεργό παράθυρο ή το δεδομένο παράθυρο.

Σύνταξη:

svc.Maximize(windowname: str)

Παράμετροι:

windowname (όνομα παραθύρου): δείτε τους ορισμούς παραπάνω. Εάν αυτό το όρισμα απουσιάζει, το ενεργό παράθυρο μεγιστοποιείται.

Παράδειγμα:

Σε Basic

      ui.Maximize("Untitled 1")
   
Σε Python

     ui.Maximize("Untitled 1")
   

Minimize

Ελαχιστοποιεί το ενεργό παράθυρο, ή το δεδομένο παράθυρο.

Σύνταξη:

svc.Minimize(windowname: str)

Παράμετροι:

windowname (όνομα παραθύρου): δείτε τους ορισμούς πιο πάνω. Εάν αυτό το όρισμα απουσιάζει, το ενεργό παράθυρο ελαχιστοποιείται.

Παράδειγμα:

Σε Basic

     ui.Minimize()
   
Σε Python

     ui.Minimize()
   

OpenBaseDocument

Ανοίξτε ένα υπάρχον έγγραφο της LibreOffice Base. Η μέθοδος επιστρέφει ένα αντικείμενο εγγράφου.

Σύνταξη:

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

Παράμετροι:

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation. If the file already exists, it is overwritten without warning

registrationname (όνομα καταχώρησης): Το όνομα που θα χρησιμοποιηθεί για την εύρεση της βάσης δεδομένων στο μητρώο βάσεων δεδομένων. Αγνοείται εάν FileName <> "".

macroexecution (εκτέλεση μακροεντολών): 0 = η συμπεριφορά ορίζεται από τη διαμόρφωση του χρήστη, 1 = οι μακροεντολές δεν είναι εκτελέσιμες, 2 = οι μακροεντολές είναι εκτελέσιμες.

Παράδειγμα:

Σε Basic

      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
Σε Python

     ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)
   
tip

Για να βελτιώσετε την αναγνωσιμότητα του κώδικα, μπορείτε να χρησιμοποιήσετε προκαθορισμένες σταθερές για το όρισμα macroexecution , όπως στα παραπάνω παραδείγματα.


OpenDocument (*)

Άνοιγμα υφιστάμενου εγγράφου LibreOffice με τις δεδομένες επιλογές. Επιστρέφει ένα αντικείμενο εγγράφου, ή μία από τις υποκλάσεις του. Η μέθοδος επιστρέφει Nothing (στη Basic) / None (στην Python) εάν το άνοιγμα απέτυχε, ακόμη και όταν η αποτυχία προκαλείται από απόφαση του χρήστη.

Σύνταξη:

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

Παράμετροι:

filename (όνομα αρχείου): Προσδιορίζει το αρχείο που θα ανοίξει. Πρέπει να ακολουθεί τη σημειογραφία FileNaming της υπηρεσίας FileSystem.

password (κωδικός πρόσβασης): Για χρήση όταν το έγγραφο είναι προστατευμένο. Εάν είναι λάθος ή απουσιάζει ενώ το έγγραφο είναι προστατευμένο, θα ζητηθεί από τον χρήστη να εισαγάγει έναν κωδικό πρόσβασης.

readonly (μόνο για ανάγνωση): Προεπιλογή = False.

hidden (κρυφό): εάν είναι True, ανοίξτε το νέο έγγραφο στο παρασκήνιο (προεπιλογή = False). Να χρησιμοποιείται με προσοχή: η ενεργοποίηση ή το κλείσιμο κατόπιν, μπορεί να γίνει μόνο μέσω προγραμματισμού.

macroexecution (εκτέλεση μακροεντολών): 0 = η συμπεριφορά ορίζεται από τη διαμόρφωση του χρήστη, 1 = οι μακροεντολές δεν είναι εκτελέσιμες, 2 = οι μακροεντολές είναι εκτελέσιμες.

filtername (όνομα φίλτρου): Το όνομα ενός φίλτρου που πρέπει να χρησιμοποιηθεί για τη φόρτωση του εγγράφου. Εάν υπάρχει, το φίλτρο πρέπει να υπάρχει.

filteroptions (επιλογές φίλτρου): Μια προαιρετική συμβολοσειρά επιλογών που σχετίζεται με το φίλτρο.

Παράδειγμα:

Σε Basic

      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
Σε Python

     ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   

Resize

Αλλάζει το μέγεθος και/ή μετακινεί το ενεργό παράθυρο. Τα απόντα και τα αρνητικά ορίσματα αγνοούνται. Εάν το παράθυρο ελαχιστοποιηθεί ή μεγιστοποιηθεί, η κλήση του Resize (Αλλαγή μεγέθους) χωρίς ορίσματα το επαναφέρει.

Σύνταξη:

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

Παράμετροι:

left, top (αριστερά, επάνω): Οι αποστάσεις της επάνω αριστερής γωνίας από το επάνω και το αριστερό άκρο της οθόνης, σε εικονοστοιχεία.

width, height (πλάτος, ύψος): Νέες διαστάσεις του παραθύρου, σε εικονοστοιχεία.

Παράδειγμα:

Στα παρακάτω παραδείγματα, το width (πλάτος)και το height (ύψος) του παραθύρου αλλάζουν, ενώ τα top (επάνω) και left (αριστερά) παραμένουν αμετάβλητα.

Σε Basic

      ui.Resize(, ,500, 500)
   
Σε Python

     ui.Resize(width = 500, height = 500)
   
tip

Για να αλλάξετε το μέγεθος ενός παραθύρου που δεν είναι ενεργό, πρώτα ενεργοποιήστε το χρησιμοποιώντας τη μέθοδο Activate.


SetStatusbar (*)

Εμφανίστε ένα κείμενο και μια γραμμή προόδου στη γραμμή κατάστασης του ενεργού παραθύρου. Οποιεσδήποτε επόμενες κλήσεις στην ίδια εκτέλεση μακροεντολής αναφέρονται στην ίδια γραμμή κατάστασης του ίδιου παραθύρου, ακόμα κι αν το παράθυρο δεν είναι πλέον ορατό. Μια κλήση χωρίς ορίσματα επαναφέρει τη γραμμή κατάστασης στην κανονική της κατάσταση.

Σύνταξη:

svc.SetStatusbar(text: str = '', percentage: int = -1)

Παράμετροι:

text (κείμενο): Ένα προαιρετικό κείμενο που θα εμφανίζεται μπροστά από τη γραμμή προόδου.

percentage (ποσοστό): ένας προαιρετικός βαθμός προόδου μεταξύ 0 και 100.

Παράδειγμα:

Σε Basic

      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Επαναφέρει τη γραμμή κατάστασης
      ui.SetStatusbar
   
Σε Python

     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   

ShowProgressBar

Εμφανίζει ένα μη αναγκαστικό πλαίσιο διαλόγου. Καθορίστε τον τίτλο του, ένα επεξηγηματικό κείμενο και ένα ποσοστό προόδου που θα αναπαρασταθεί σε μια γραμμή προόδου. Το παράθυρο διαλόγου θα παραμείνει ορατό μέχρι να κληθεί η μέθοδος χωρίς ορίσματα, ή έως ότου ο χρήστης κλείσει χειροκίνητα το παράθυρο διαλόγου.

Σύνταξη:

svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -1)

Παράμετροι:

title (τίτλος): Ο τίτλος που εμφανίζεται στην κορυφή του πλαισίου διαλόγου. Προεπιλογή = "ScriptForge".

text (κείμενο): Ένα προαιρετικό κείμενο που θα εμφανίζεται πάνω από τη γραμμή προόδου.

percentage (ποσοστό): ένας προαιρετικός βαθμός προόδου μεταξύ 0 και 100.

Παράδειγμα:

Σε Basic

      Dim i As Integer
      For i = 0 To 100
          ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
          Wait 50
      Next i
      ' Κλείνει το παράθυρο της γραμμής προόδου
      ui.ShowProgressBar
   
Σε Python

     from time import sleep
     for i in range(101):
         ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     # Κλείνει το παράθυρο της γραμμής προόδου
     ui.ShowProgressBar()
   

WindowExists

Επιστρέφει True εάν το δεδομένο παράθυρο μπορεί να αναγνωριστεί.

Σύνταξη:

svc.WindowExists(windowname: str): bool

Παράμετροι:

windowname (όνομα παραθύρου): δείτε τους ορισμούς παραπάνω.

Παράδειγμα:

Σε Basic

      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
Σε Python

     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...