Doxygen XML

  1. Pages
    1. KSpreadScripting
  2. Objects
    1. KoScriptingModule
    2. KoScriptingPart
    3. KSpread::MapAdaptor
    4. KSpread::ScriptingCellListener
    5. ScriptingFunction
    6. ScriptingModule
    7. ScriptingPart
    8. ScriptingReader
    9. ScriptingSheetsListView
    10. ScriptingWriter
    11. KSpread::SheetAdaptor
    12. KSpread::ViewAdaptor

KSpreadScripting

The KSpread scripting plugin offers flexible access to the Kross scripting framework. Languages like Python or Ruby could be used to script KSpread, extend the functionality with script-packages, automate tasks or control the runtime-environment.

  • The ScriptingPart class implements a KPart component to integrate scripting into KSpread.
  • The ScriptingModule class enables access to the KSpread functionality from within the scripting backends.
  • The ScriptingFunction class provides access to the KSpread::Function functionality to deal with formula functions that are written in a scripting language like Python or Ruby.
  • The ScriptingCellListener class implements a listener to changes within cells of a sheet.
  • The ScriptingReader class provides abstract high-level functionality to read content from KSpread sheets.
  • The ScriptingWriter class provides abstract high-level functionality to write content to KSpread sheets and to manipulate the content of cells.
  • The ScriptingSheetsListView provides provides a listview-widget that displays all sheets and lets the user choose 0..n of them plus specify cell-ranges for all of them.
  • http://www.koffice.org/kspread

    http://kross.dipe.org

    http://api.kde.org/4.0-api/kdelibs-apidocs/kross/html/index.html

    Examples

    Python example to write content of a sheet to stdout;

     #!/usr/bin/env kross
     # The OpenDocument Spreadsheet file that we like to read.
     filename = "/home/kde4/invoicetemplate.ods"
     # Import Kross and fetch the KSpread module.
     import Kross
     kspread = Kross.module("kspread")
     # Try to open the file.
     if not kspread.openUrl(filename):
         raise "Failed to open the file \"%s\"." % filename
     # Get the sheet we like to print to stdout.
     sheet = kspread.sheetByName( kspread.sheetNames()[0] )
     # Iterate now through all cells on the sheet.
     for row in range(sheet.maxRow()):
         # Put the content of the row into the record-list.
         record = []
         for col in range(sheet.maxColumn(), 0, -1):
             value = sheet.text(col, row)
             if value or len(record) > 0:
                 record.insert(0,value)
         # If the record has at least one cell print it.
         if len(record) > 0:
             print record
    

    Python example to read template, set content and write new file;

     #!/usr/bin/env kross
     # The OpenDocument Spreadsheet file that we like to read from.
     templatefile = "/home/kde4/invoicetemplate.ods"
     # The OpenDocument Spreadsheet file that we like to write to.
     savefile = "/home/kde4/invoice.ods"
     # Import Kross and fetch the KSpread module.
     import Kross
     kspread = Kross.module("kspread")
     # Try to open the file.
     if not kspread.openUrl(templatefile):
         raise "Failed to open the file \"%s\"." % templatefile
     # Get the sheet we like to manipulate.
     sheet = kspread.sheetByName( kspread.sheetNames()[0] )
     # Set the content of some cells.
     sheet.setText(0,7,"Joe User")
     sheet.setText(0,8,"Userstreet. 1")
     sheet.setText(0,9,"Testcasecity")
     # Finally write the new OpenDocument Spreadsheet file.
     if not kspread.saveUrl(savefile):
         raise "Failed to save the file \"%s\"." % savefile
    

    Legal

  • Copyright (c) 2005 Cyrille Berger <cberger@cberger.net>
  • Copyright (c) 2006 ISaac Clerencia <isaac@warp.es>
  • Copyright (c) 2006-2007 Sebastian Sauer <mail@dipe.org>
  • This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.


    Objects

    KoScriptingModule


    KoScriptingPart


    KSpread::MapAdaptor

    The MapAdaptor class provides additional functionality to deal with sheets.


    KSpread::ScriptingCellListener

    The ScriptingCellListener class implements a listener to changes within cells of a sheet.

    Python sample script that creates a listener for the range of cells A1:F50 within the sheet Sheet1.

     import Kross, KSpread
     listener = KSpread.createListener("Sheet1", "A1:F50")
     if not listener:
         raise "Failed to create listener."
     def regionChanged(regions):
         print "regions=%s" % regions
     def cellChanged(column, row):
         print "column=%i row=%i" % (column,row)
     listener.connect("regionChanged(QVariantList)", regionChanged)
     listener.connect("cellChanged(int,int)", cellChanged)
    


    ScriptingFunction

    The ScriptingFunction class provides access to the KSpread::Function functionality to deal with formula functions that are written in a scripting language like Python or Ruby.

    The following sample scripting formula function written in python displays the current datetime.

     import time, Kross, KSpread
     func = KSpread.function("PYTIME")
     func.minparam = 0
     func.maxparam = 1
     func.comment = "The PYTIME() function displays the current datetime."
     func.syntax = "PYTIME(string)"
     func.addParameter("String", "The datetime format string.")
     func.addExample("PYTIME()")
     func.addExample("PYTIME(\"%Y-%M-%d %H:%M.%S\")")
     def update(args):
         try:
             func.result = time.strftime(args[0] or "%H:%M.%S")
         except:
             func.error = "Invalid format"
     func.connect("called(QVariantList)", update)
     func.registerFunction()
    


    ScriptingModule

    The ScriptingModule class enables access to the KSpread functionality from within the scripting backends.


    ScriptingPart

    The ScriptingPart class implements a KPart component to integrate scripting into KSpread.


    ScriptingReader

    The ScriptingReader class provides abstract high-level functionality to read content from KSpread sheets.

    The following python sample demonstrates how to use the ScriptingReader to read content from KSpread.

     # Import the KSpread module
     import KSpread
    
     # Create a ScriptingReader object
     reader = KSpread.reader()
     # We like to read all of Sheet1
     reader.setSheet("Sheet1")
     # and from Sheet2 only the range A5:F12
     reader.setSheet("Sheet2","A5:F12")
    
     # This function got called in our case two times.
     # One time if we switch to Sheet1 and the other
     # time if switched to Sheet2.
     def changedSheet(sheetname):
         print "sheetname=%s" % sheetname
    
     # This function got called for each row that got
     # readed.
     def changedRow(row):
         values = reader.currentValues()
         print "row=%i values=%s" % (row,values)
    
     # Now let's connect our both functions to matching
     # signals the reader provides.
     reader.connect("changedSheet(QString)",changedSheet)
     reader.connect("changedRow(int)",changedRow)
     # and finally start the reader.
     reader.start()
    


    ScriptingSheetsListView

    The ScriptingSheetsListView provides a listview-widget that displays all sheets and lets the user choose 0..n of them plus specify cell-ranges for all of them.


    ScriptingWriter

    The ScriptingWriter class provides abstract high-level functionality to write content to KSpread sheets and to manipulate the content of cells.

    The following python sample demonstrates how to use the ScriptingWriter to write content to KSpread.

     # Import the KSpread module
     import KSpread
     # Create a writer instance.
     writer = KSpread.writer()
     # Set the sheet we like to write to.
     sheetname = "Sheet2"
     if not writer.setSheet(sheetname):
         raise "Invalid sheet \"%s\" defined." % sheetname
     # Set the cell(s) we like to start to write to. If this
     # is not defined, writing starts from A1.
     cellname = "B12"
     if not writer.setCell(cellname):
         raise "Invalid cell \"%s\" defined." % cellname
     # Now fill the cells with some content.
     for record in [ ["One,"Two"] , ["Three,"Four"] ]:
         # Write the tuple to the current row.
         if not writer.setValues(record):
             raise "Failed to set record %s" % record
         # Go to the next row.
         writer.next()
    


    KSpread::SheetAdaptor


    KSpread::ViewAdaptor

    The ViewAdaptor class provides access to a view on a KSpread document.