Modules and Plug-ins in SciGraphica
 
   SciGraphica Documentation Team 
 
   Aug 12, 2001
 
   
 
 
     Introduction to the SciGraphica plug-in system
 
   Like many other modern programs, SciGraphica can be extended by third-party plug-ins. Theseplug-ins can currently be written both in Python and C. The easiest way to wite a plug-in, is to write a Python module, in C or Python. In that case the plug-in is loaded by the Python module loader. 
                          
   
       Editing the module list using the Script-Configuration dialog.
   
  
  
 
   Modules can be imported from the SciGraphica terminal command line by typing, or by including the module name in the list of modules in the Scripting-Configuration-Startup dialog. Make sure the module can be found in the Python module search path, which can be determined by doing the follwing in the SciGraphica terminal: 
 
 import sys
print sys.path
 
   One of these paths is set by SciGraphica, which is /usr/share/scigraphica/python if the package is installed under /usr. The rest of this document will describe how to write plug-ins in Python and C.
                          
   
       Editing the module include path list using the Script-Configuration dialog.
   
  
  
 
 
     Writing plug-ins in Python
 
   The simplest way to write a plug-in is to write a Python module in Python. A Python module is simply any text file containing Python code, residing in the Python module import path, sys.path Please see the documentation at www.python.org  for more information. The Python commands available to you for controlling SciGraphica functions are defined in the pysga.py file. Let's look at an example first: 
 
 import sg

def function():
print(Test module)

sg.register_plugin(Test module,Worksheet:,function)
 
   The first line ensures the sg module is included in your module's namespace. This module is the SciGraphica Python binding. The next two lines simply defines a function that will be called when our module gets selected. Save your module source as e.g. mytest.py.
 
   The last line registers the plug-in to be available under the Worksheet menu, displayed by right-clicking in any worksheet. When your module, named just mytest when it is imported, a new item will appear in this menu, named Test module. To test your module, open the SciGraphica terminal from the Scripting-Terminal menu. Then open a worksheet, right-click on one of the cells, and select the Test module item from the menu. If all went well, you should see the words Test module should appear in the terminal.
 
   Two main groups are currently defined, namely Worksheet, and Plot, with the latter denoting the right-click menu for plots.
 
        Writing gtk+ GUIs in Python
  
     If you have the pygtk module installed on your system, you have the full power of gtk+ at your disposal. Two simple rules apply when writing GUIs for your plug-ins using pygtk: 
  
           Do not initialize start your own event loop by calling gtk.mainloop() and 
   
  
         Do not jump out of the event loop by calling gtk.mainquit().This is also true for constructing dialogs: constructing modal dialogs of your own main dialog should be done by creating a new window, and letting the SciGraphica event loop process events for your dialog.
   
  
  
     The next piece of python code creates a menu item named Testmodule and puts it in the Worksheet-Test menu, which can be obtained by right-clicking on any cell in the worksheet.
  
   Import gtk and sg modules
from gtk import * 
import sg		

# Define a callback function
def fl(button): 
  print(Button pressed)		

# Function to be called when our menu item gets selected
def test_window(text=Test): 
  w=GtkWindow() 
  button=GtkButton(text)
  button.connect(clicked, fl)
  w.add(button)
  w.show_all()		

# Create a new plug-in group, which will create a "Test" submenu
sg.new_plugin_group(Worksheet:Test:)		

# Register our plugin
sg.register_plugin(Testmodule,Worksheet:Test:,test_window)
  
  
        Using the SciGraphica wizard interface
  
     You can easily write wizard interfaces by using the using the SGwizard class defined in the sgagtk module. To do this, you have to do the following:
  
           Define a function for each page of the wizard. This function should take two compulsory arguments, namely a dictionary and a GtkVbox, as well as named arguments for the cancel, next, and back buttons: 
def myfunc(params,vbox,next=None,prev=None,cancel=None)
This function should put gtk widgets int the vbox widgets, and make them visible. The first argument will be explained later. Callbacks can be connected to the pressed signal of these buttons.
   
  
         Define a function to be called when the finish button is pressed in the last wizard page, taking only one argument, which is the same as the first argument of the above function:
def finish(params)
This function should not make create any widgets, except if a new dialog window is constructed.
   
  
         Define the dictionary that will be passed as the first argument to the above functions. It has two mandatory elements:
   
               funcs: A list containing the functions to create the dialog pages. 
    
   
            finish: The function called when the finish button is pressed.
    
   
   
  
         This dictionary may also contain an optional list of wizard page titles in the labels element.
   
  
         Finally, create an instance of the sgagtk.SGwizard object with this dictionary as an argument:
wizard=sgagtk.SGwizard(params)
This can be done in the function registered using the sg.register_plugin function.
   
  
  
     The following example constructs a wizard that lets the user select a column name from the current worksheet. The example is available in the test_wizard module.
  
   Import some standard modules
from gtk import *
from Numeric import *
from Scientific.Statistics import *		

 Import the sg and related modules
import sg
import sgagtk  The wizard class
import pysga   The python binding for sheets and plots		

 The function that gets called when the wizard finishes
def finish_func(params): 
  pass			



 Our GUI setup function. Just add a widget to the provided page_box widget
 and use the 'params' dictionary to pass around variables to other functions
def first_func(params,page_box,next=None,prev=None,cancel=None):
   active_sheet=sg.active_worksheet_name()
   paramssheet=active_sheet
   cols=sg.column_names(active_sheet)
   active=sg.get_selection(active_sheet)'col0'
   paramscolname=colsactive

   frame=GtkFrame(Worksheet: +active_sheet)
 
   page_box.pack_start(frame)
   vbox=GtkVBox()
   frame.add(vbox)

   vbox.pack_start(GtkLabel(Pick a column:),padding=5)

   menu=GtkCombo()
   menu.set_popdown_strings(cols)
   menu.set_value_in_list(TRUE,FALSE)
   menu.entry.set_text(colsactive)
   vbox.pack_start(menu,padding=5)
   frame.show_all()			


 The second function: displays the column name that was picked 
def second_func(params,page_box,next=None,prev=None,cancel=None):
   frame=GtkFrame(Worksheet: +paramssheet)
   page_box.pack_start(frame)
   vbox=GtkVBox()
   frame.add(vbox)
   vbox.pack_start(GtkLabel(You picked the column named '+paramscolname+"'"),
   padding=5)			


 The function that gets called when the menu option is selected
def pick_init():
   params=
 These are compulsory
   funcs:first_func,second_func,
   finish:finish_func,
 This is optional
   labels:Pick a column,Column results,
   
 Use this dictionary to construct the wizard
   wizard=sgagtk.SGwizard(params)				

 Module registration, make sure the group (second parameter) exists, 
 and ends in a colon.
if (sg):
   sg.register_plugin(Column picker,Worksheet:",pick_init)
  
     This should produce these two pages:
  
     
            First wizard page
    


   
   
            Second wizard page
    


   
   
  
  
        The SciGraphica Python API
  
     The functionality provied by SciGraphica is available from Python in three different modules: sg, pysga, and sgagtk. The sg module is written in C, as part of the main application, and is always available. When writing your own modules, this module should still be imported into your own module's namespace.
  
     The pysga, and sgagtk modules are written in Python, and must be loaded by the interpreter from one of the directories in the search path. The pysga module presents and object-oriented view of worksheets, worsheet columns, plots, plot layers, and plot datasets. The sgagtk module contains pygtk convenience functions and classes, currently the SGwizard class is implemented in this module.
  
     The next paragraphs will document the function calls and classes in these three modules in more depth.
  
           The sg module
   
       The sg module provides a low-level binding of a few essential functions defined in SciGraphica. It is by no means complete, but it is very functional already, and being expanded continously.
   
   
           The pysga module
   
       The pysga module provides the classes SGworksheet, SGcolumn, SGplot, SGlayer, and SGaxis for a more convenient object-oriented interface to the sg module.
   
   
           The sgagtk module
   
       This module defines the SGwizard class, which is initialized as
   
       follows:
   
   def __init__(self,params,title="Scigraphica wizard",modal=TRUE,
tabs=FALSE,tab_pos=POS_TOP,with_labels=TRUE):
   
       For a description of the params dictionary parameter, please see
   
       paragraph wiztut. The other parameters are:
   
               title: The title of the dialog window. If tabs isset to false, this will be the only text appearing in the window title bar,otherwise, a window title will be constructed using this title, and the individual wizard page titles, separated by a colon.
    
   
            modal: If set to TRUE, the wizard dialog window will be the only one accepting input among the windows created by SciGraphica.
    
   
            tabs: Wizard pages are created as pages in a notebook. If set, this parameter will cause the notebook tabs to be displayed.
    
   
            tab_pos: The position of notebook tabs, if enabled. Options are POS_TOP, POS_RIGHT, POS_LEFT, and POS_BOTTOM.
    
   
            with_labels: If set, and the labels element of the params dictionary is a list of strings of the same length as the number of pages, the labels in this list will be used either in the dialog window title bar, or in the notebook tabs.
    
   
   
       No public methods are currently available for SGwizard objects.