This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
geda:gschem_ug:extensions [2011/12/24 05:49] peterb Add info |
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://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. | |