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
geda:gschem_ug:extensions [2012/01/16 07:21]
vzh Fixed typo
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. |