User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
geda:gschem_ug:extensions [2011/12/22 16:27]
peterb [Adding an action]
geda:gschem_ug:extensions [2012/02/20 15:14] (current)
Line 1: Line 1:
 +| << [[stroke|Mouse gesture support]] ​ |  **[[geda:​gschem_ug|gEDA gschem User Guide]]** ​ |  [[geda:​gschem_ug|Contents]] >> |
 +===== Extending gschem =====
 +Since the gschem [[config|configuration files]] are Scheme scripts, they provide a way to load additional capabilities into gschem by defining new functions that manipulate objects and pages.
 +gschem (and other gEDA/gaf tools such as [[geda:​gnetlist_ug|gnetlist]]) use [[http://​​s/​guile/​|Guile Scheme]] to provide Scheme scripting capabilities,​ and all of the features of Guile are available to use.  The //Guile Reference Manual// is available as an Info manual (''​[[info://​guile|info guile]]''​ on most systems), or [[http://​​software/​guile/​docs/​docs.html|on the Guile website]].
 +A collection of modules is provided for accessing and modifying gEDA objects and pages, called the gEDA Scheme API.  The //gEDA Scheme Reference Manual// is also available as an Info manual (''​[[info://​geda-scheme|info geda-scheme]]''​).
 +==== Adding an action ====
 +Actions are thunks, i.e. Scheme procedures that take no arguments. ​ For gschem to be able to find them, they must be defined in the top-level [[http://​​software/​guile/​manual/​html_node/​Modules.html|module]],​ so you must do one of the following:
 +  * define the procedure directly in one of your configuration files;
 +  * define the procedure in a Scheme file loaded (using ''​load''​) from one of your configuration files;
 +  * or export the procedure in a Guile module which you load (with ''​use-modules''​) from your configuration files.
 +You can then bind the procedure to a keystroke as normal with ''​global-set-key''​.
 +==== Hooking into built-in actions ====
 +gschem allows you to register functions, called //hooks//, to be executed when a user executes a built-in function. ​ These are provided by the ''​(gschem hook)''​ Guile module. ​ For more information,​ see the //Hooks// page in the //gEDA Scheme Reference Manual//.
 +==== Procedures for extension writers ====
 +In addition to the gEDA Scheme API functions, gschem provides some utility procedures for extension writers.
 +<note important>​The functions described in this section are not guaranteed to remain stable from one release of gEDA/gaf to another. ​ For longer-term stability, use only the gEDA Scheme API.</​note>​
 +^ Function ​                       ^ Description ​ ^
 +| ''​gschem-print''​ | Export PostScript (see [[Printing]]) to the output filename specified with the ''​-o''​ [[command_line|command-line option]], or the default PostScript filename if no option was given. ​ |
 +| ''​gschem-postscript FILENAME''​ | Export PostScript to ''​FILENAME''​. ​ |
 +| ''​gschem-image FILENAME''​ | Export an image (see [[exporting|Exporting images]]) to the output filename specified with the ''​-o''​ command-line option, or to ''​FILENAME''​ if no option was given. ​ |
 +| ''​gschem-exit'' ​ | Exit gschem immediately. ​ **Warning:​** if the user has unsaved changes, he will not be given the opportunity to save them.  |
 +| ''​gschem-log MSG'' ​ | Write ''​MSG''​ to the gschem log.  |
 +| ''​gschem-msg MSG'' ​ | Display a message dialog to the user with the text ''​MSG''​. ​ |
 +| ''​gschem-confirm MSG'' ​ | Display a confirmation dialog to the user, with "​Yes"​ and "​No"​ buttons and the text ''​MSG''​. ​ Return ''#​t''​ if the user selects "​Yes",​ and ''#​f''​ otherwise. ​ |
 +| ''​gschem-filesel MSG TEMPL FLAGS'' ​ | Display a file selector dialog, with ''​MSG''​ in the title and the default filename ''​TEMPL''​. ​ The ''​FLAGS''​ control the file selector behavior, and should be a list of strings. ​ The following strings can be provided in the ''​FLAGS'':​ ''"​may_exist"''​ if the file selected is permitted to already exist; ''"​must_exist"''​ if the file selected must already exist; ''"​must_not_exist"''​ if the file selected must //not// already exist; ''"​save"''​ to show a "Save file..."​ dialog; ''"​open"''​ to show an "Open file..."​ dialog. |