start => gschem_ug

« Mouse gesture support | gEDA gschem User Guide | Contents »

## Extending gschem

Since the gschem 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 gnetlist) use 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` on most systems), or 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`).

### 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 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.

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.

Function | Description
--- | ---
`gschem-print` | Export PostScript (see Printing) to the output filename specified with the `-o` 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 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.