svgedit/docs/tutorials/Events.md

129 lines
4.2 KiB
Markdown
Raw Normal View History

- Security fix: 'extPath', 'imgPath', 'extIconsPath', 'canvgPath', 'langPath', 'jGraduatePath', and 'jspdfPath' were not being prevented - Breaking change: Rename "svgutils.js" to "utilities.js" (make in conformity with JSDoc module naming convention) - Breaking change: Rename "svgedit.js" to "namespaces.js" (to make clear purpose and avoid confusing with editor) - Breaking change: Rename "jquery-svg.js" to "jQuery.attr.js" - Breaking change: Rename "jquery.contextMenu.js" to "jQuery.contextMenu.js" - Breaking change: Rename "jquery.jpicker.js" to "jQuery.jPicker.js" - Breaking change: Rename "JQuerySpinBtn.css" to "jQuery.SpinButton.css" - Breaking change: Rename "JQuerySpinBtn.js" to "jQuery.SpinButton.js" (to have file name more closely reflect name) - Breaking change: Rename "jquery.svgicons.js" to "jQuery.svgIcons.js" - Breaking change: Rename "jquery.jgraduate.js" to "jQuery.jGraduate.js" - Breaking change: Rename "pathseg.js" to "svgpathseg.js" (as it is a poyfill of SVGPathSeg) - Breaking change: Rename `addSvgElementFromJson()` to `addSVGElementFromJson` for consistency - Breaking change: Rename `changeSvgContent()` to `changeSVGContent()` for consistency - Breaking change: Have `exportPDF` resolve with `output` and `outputType` rather than `dataurlstring` (as type may vary) - Breaking change: Rename `extensions/mathjax/MathJax.js` to `extensions/mathjax/MathJax.min.js` - Breaking change: Avoid recent change to have editor ready callbacks return Promises (we're not using and advantageous to keep sequential) - Breaking change: Avoid recent addition of locale-side function in ext-imagelib for l10n - Breaking change: Change name of ext-arrows.js from `Arrows` to `arrows` for sake of file path (not localized anyways). - Breaking change: Change `addlangData` extension event to `addLangData` for consistency with method name - Breaking change: Have `readLang` return lang and data but do not call `setLang` - Fix: Have general locales load first so extensions may use - Fix: Provide `importLocale` to extensions `init` so it may delay adding of the extension until locale data loaded - Fix: Ensure call to `rasterExport` without `imgType` properly sets MIME type to PNG - Fix: Wrong name for moinsave - Update: Update WebAppFind per new API changes - Enhancement: Make `setStrings` public on editor for late setting (used by `ext-shapes.js`) - Enhancement: Add `extensions_added` event - Enhancement: Add `message` event (Relay messages including those which have been been received prior to extension load) - Enhancement: Allow SVGEdit to work out of the box--avoid need for copying sample config file. Should also help with Github-based file servers - Enhancement: Allow avoiding "name" in extension export (just extract out of file name) - Enhancement: Add stack blur to canvg by default (and refactoring it) - Enhancement: Return `Promise` for `embedImage` (as with some other loading methods) - Enhancement: Supply `importLocale` to `langReady` to facilitate extension locale loading - Enhancement: Recover if an extension fails to load (just log and otherwise ignore) - Enhancement: More i18n of extensions (also fixed issue with some console warnings about missing locale strings); i18nize Hello World too - Enhancement: Allowing importing of locales within `addLangData` - npm: Update devDeps - Docs: Migrate copies of all old wiki pages to docs/from-old-wiki folder; intended for a possible move to Markdown, so raw HTML (with formatting) was not preserved, though named links had their absolute URL links preserved - Docs: Begin deleting `SvgCanvas.md` as ensuring jsdoc has replacements - Docs: Add Edtior doc file for help to general users - Docs: Clarify/simplify install instructions - npm/Docs (JSDoc): Add script to check for overly generic types - Docs (JSDoc): For config/prefs and extension creating, link to tutorials (moved tutorials to own directory to avoid recursion problems by jsdoc) - Docs (JSDoc): Add modules (upper case for usual main entrance files or regular names) - Docs (JSDoc): Fill out missing areas; indicate return of `undefined`; consistency with `@returns` - Docs (JSDoc): Add our own layout template to support overflow - Docs (JSDoc): Use cleverLinks and disallow unknown tags - Docs (JSDoc): Insist on "pedantic" flag; put output directory in config - Docs (JSDoc): Use more precise Integer/Float over number, the specific type of array/function/object - Docs (JSDoc): Use `@throws`, `@enum`, `@event`/`@fires`/`@listens` - Docs: Generally update/improve docs (fixes #92) - Docs: Update links to `latest` path (Avoid needing to update such references upon each release) - Docs: 80 chars max - Refactoring: Drop code for extension as function (already requiring export to be an object) - Refactoring: Object destructuring, `Object.entries`, Object shorthand, array extras, more camelCase variable names - Refactoring: Add a `Command` base class - Refactoring: Simplify svgicons `callback` ready detection - Refactoring: Put `let` or `const` closer to scope - Refactoring: Remove unneeded `delimiter` from regex escaping utility - Refactoring: Clearer variable names - Refactoring: Use (non-deprecated) Event constructors - Testing: Use new Sinon
2018-06-06 07:26:20 +00:00
# Introduction
## `save`, `open`, `exportImage` (`setCustomHandlers`)
You can hook to the save event (e.g. in an extension), to handle saving
the SVG file differently:
### Example
```js
svgEditor.setCustomHandlers({
save (win, data) {
// Save svg
}
- Security fix: 'extPath', 'imgPath', 'extIconsPath', 'canvgPath', 'langPath', 'jGraduatePath', and 'jspdfPath' were not being prevented - Breaking change: Rename "svgutils.js" to "utilities.js" (make in conformity with JSDoc module naming convention) - Breaking change: Rename "svgedit.js" to "namespaces.js" (to make clear purpose and avoid confusing with editor) - Breaking change: Rename "jquery-svg.js" to "jQuery.attr.js" - Breaking change: Rename "jquery.contextMenu.js" to "jQuery.contextMenu.js" - Breaking change: Rename "jquery.jpicker.js" to "jQuery.jPicker.js" - Breaking change: Rename "JQuerySpinBtn.css" to "jQuery.SpinButton.css" - Breaking change: Rename "JQuerySpinBtn.js" to "jQuery.SpinButton.js" (to have file name more closely reflect name) - Breaking change: Rename "jquery.svgicons.js" to "jQuery.svgIcons.js" - Breaking change: Rename "jquery.jgraduate.js" to "jQuery.jGraduate.js" - Breaking change: Rename "pathseg.js" to "svgpathseg.js" (as it is a poyfill of SVGPathSeg) - Breaking change: Rename `addSvgElementFromJson()` to `addSVGElementFromJson` for consistency - Breaking change: Rename `changeSvgContent()` to `changeSVGContent()` for consistency - Breaking change: Have `exportPDF` resolve with `output` and `outputType` rather than `dataurlstring` (as type may vary) - Breaking change: Rename `extensions/mathjax/MathJax.js` to `extensions/mathjax/MathJax.min.js` - Breaking change: Avoid recent change to have editor ready callbacks return Promises (we're not using and advantageous to keep sequential) - Breaking change: Avoid recent addition of locale-side function in ext-imagelib for l10n - Breaking change: Change name of ext-arrows.js from `Arrows` to `arrows` for sake of file path (not localized anyways). - Breaking change: Change `addlangData` extension event to `addLangData` for consistency with method name - Breaking change: Have `readLang` return lang and data but do not call `setLang` - Fix: Have general locales load first so extensions may use - Fix: Provide `importLocale` to extensions `init` so it may delay adding of the extension until locale data loaded - Fix: Ensure call to `rasterExport` without `imgType` properly sets MIME type to PNG - Fix: Wrong name for moinsave - Update: Update WebAppFind per new API changes - Enhancement: Make `setStrings` public on editor for late setting (used by `ext-shapes.js`) - Enhancement: Add `extensions_added` event - Enhancement: Add `message` event (Relay messages including those which have been been received prior to extension load) - Enhancement: Allow SVGEdit to work out of the box--avoid need for copying sample config file. Should also help with Github-based file servers - Enhancement: Allow avoiding "name" in extension export (just extract out of file name) - Enhancement: Add stack blur to canvg by default (and refactoring it) - Enhancement: Return `Promise` for `embedImage` (as with some other loading methods) - Enhancement: Supply `importLocale` to `langReady` to facilitate extension locale loading - Enhancement: Recover if an extension fails to load (just log and otherwise ignore) - Enhancement: More i18n of extensions (also fixed issue with some console warnings about missing locale strings); i18nize Hello World too - Enhancement: Allowing importing of locales within `addLangData` - npm: Update devDeps - Docs: Migrate copies of all old wiki pages to docs/from-old-wiki folder; intended for a possible move to Markdown, so raw HTML (with formatting) was not preserved, though named links had their absolute URL links preserved - Docs: Begin deleting `SvgCanvas.md` as ensuring jsdoc has replacements - Docs: Add Edtior doc file for help to general users - Docs: Clarify/simplify install instructions - npm/Docs (JSDoc): Add script to check for overly generic types - Docs (JSDoc): For config/prefs and extension creating, link to tutorials (moved tutorials to own directory to avoid recursion problems by jsdoc) - Docs (JSDoc): Add modules (upper case for usual main entrance files or regular names) - Docs (JSDoc): Fill out missing areas; indicate return of `undefined`; consistency with `@returns` - Docs (JSDoc): Add our own layout template to support overflow - Docs (JSDoc): Use cleverLinks and disallow unknown tags - Docs (JSDoc): Insist on "pedantic" flag; put output directory in config - Docs (JSDoc): Use more precise Integer/Float over number, the specific type of array/function/object - Docs (JSDoc): Use `@throws`, `@enum`, `@event`/`@fires`/`@listens` - Docs: Generally update/improve docs (fixes #92) - Docs: Update links to `latest` path (Avoid needing to update such references upon each release) - Docs: 80 chars max - Refactoring: Drop code for extension as function (already requiring export to be an object) - Refactoring: Object destructuring, `Object.entries`, Object shorthand, array extras, more camelCase variable names - Refactoring: Add a `Command` base class - Refactoring: Simplify svgicons `callback` ready detection - Refactoring: Put `let` or `const` closer to scope - Refactoring: Remove unneeded `delimiter` from regex escaping utility - Refactoring: Clearer variable names - Refactoring: Use (non-deprecated) Event constructors - Testing: Use new Sinon
2018-06-06 07:26:20 +00:00
});
```
Other methods corresponding to UI events that may be supplied are `open`
and `exportImage`.
See [`CustomHandler`]{@link module:SVGEditor.CustomHandler} for the required
format of the object to be passed to
[`setCustomHandlers`]{@link module:SVGEditor.setCustomHandlers}.
## Parent/Opening window events
### `svgEditorReady`
The `svgEditorReady` event is triggered on a containing `document` (of
`window.opener` or `window.parent`) when the editor is loaded.
See [svgEditorReadyEvent]{@link module:SVGEditor#event:svgEditorReadyEvent}
for the JSDocs.
### Example
```js
$(document).bind('svgEditorReady', function () {
const svg = `
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="50">
<ellipse cx="50" cy="25" rx="50" ry="25" style="fill:blue;"/>
</svg>`;
$('iframe.svgedit')[0].contentWindow.svgCanvas.setSvgString(svg);
});
```
If you are acting within the frame, you may use `svgEditor.ready`
(see [Within-frame events](#Editor-within-frame-events-svgEditor) below).
## Editor (within-frame) events (`svgEditor`)
### `svgEditor.canvas`
- Canvas object. See [Canvas events](#Canvas-events).
### `svgEditor.canvas.bind(eventName, function () {})`
- Method for listening to canvas events. See [Canvas events](#Canvas-events).
### `svgEditor.ready(function () {})`
Method for listening to editor callbacks. Used internally as well.
No arguments passed to callback.
See [`SVGEditor.ready`]{@link module:SVGEditor.ready}.
## Extension events
Most extensions will want to run functions when certain events are
triggered. This is a list of the current events that can be hooked
onto. All events are optional.
See the `vars` param of
[`runExtensions`]{@link module:svgcanvas.SvgCanvas#runExtensions}
for some of the available extension events and their descriptions and types.
See [`ExtensionStatus`]{@link module:svgcanvas.ExtensionStatus} for the
values to be returned by the corresponding extension methods listening
for these extension event types.
## Canvas events
Canvas events are listened to with the bind method
([JSDocs API]{@link module:svgcanvas.SvgCanvas#bind}):
```js
canvas.bind(eventName, callback);
```
Canvas events are passed between the editor and canvas and should mostly
only of be of interest to those working with the [Canvas]{@tutorial CanvasAPI}
alone or those developing SVGEdit).
`callback` (see [`EventHandler`]{@link module:svgcanvas.EventHandler}) will be passed the
`window` object and a single argument specific to the event
(see [`GenericCanvasEvent`]{@link module:svgcanvas.SvgCanvas#event:GenericCanvasEvent}).
The `bind` method will return any previous callback attached to the given
event name.
The method used to trigger these bound events is `call()`
([JSDocs]{@link module:svgcanvas.SvgCanvas#call}).
All events below are currently called from within `svgcanvas.js` except where
noted. All events are also defined internally within `svg-editor.js` except
where noted.
|Event|Where bound/defined (besides editor)|Where called/triggered (besides canvas)|
|-----|------------------------------------|-----------------------------|
|`changed` | | (Also called from `draw.js`, `ext-arrows.js`, `ext-foreignObject.js`, `ext-markers.js`, `ext-polygon.js`, `ext-star.js`, and `path.js`) |
|`cleared` | Not bound/defined in SVGEdit. | |
|`contextset` | | Only called from `draw.js`|
|`exported` | | |
|`exportedPDF` | | |
|`extension_added` | | |
|`extensions_added` | | Only called from `svg-editor.js` |
|`message` | Only bound/defined in `ext-webappfind.js` | Only called from `svg-editor.js` |
|`pointsAdded` | Not bound/defined in SVGEdit. | |
|`saved` | | |
|`selected` | | Also called from `path.js` |
|`setnonce` | Only bound/defined in `ext-arrows.js` | |
|`transition` | | |
|`updateCanvas` | | |
|`unsetnonce` | Only bound/defined in `ext-arrows.js` | |
|`zoomed` | | |
|`zoomDone` | | |