| << [[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://www.gnu.org/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://www.gnu.org/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://www.gnu.org/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. |