diff --git a/markdown/dev/reference/api/part/copy/en.md b/markdown/dev/reference/api/part/copy/en.md deleted file mode 100644 index 31d7929de79..00000000000 --- a/markdown/dev/reference/api/part/copy/en.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: copy() ---- - -```js -Part part.copy(Part original) -``` - -This will copy the points, paths, and snippets from a part you pass into it. - - - -This method is used internally, you are unlikely to need this. - -If you want one part to build on another, you should set -up [part inheritance](/advanced/inject) in your pattern's [configuration](../config) file. - - - diff --git a/markdown/dev/reference/api/part/en.md b/markdown/dev/reference/api/part/en.md index 5fb0ead2d82..a15932f9e3f 100644 --- a/markdown/dev/reference/api/part/en.md +++ b/markdown/dev/reference/api/part/en.md @@ -3,15 +3,19 @@ title: Part order: 20 --- -Part objects hold the actual information, and together they make up your pattern. +The `Part` object in FreeSewing's core library holds all data and logic of a pattern part. +A pattern part is what holds the actual information about points and paths, +and multiple parts together typically make up a pattern. -Each Part object comes with the following properties: +## Part properties - - `paths` : A plain object to store your paths in - - `points` : A plain object to store your points in - - `render` : A flag that controls whether to include the part in the render output - - `snippets` : A plain object to store your snippets in +| Property | Description | +| --------:| ----------- | +| `paths` | A plain object to store your paths in | +| `points` | A plain object to store your points in | +| `render` | A flag that controls whether to include the part in the render output | +| `snippets` | A plain object to store your snippets in | -In addition, a Part object exposes the following methods: +## Part methods diff --git a/markdown/dev/reference/api/part/getid/en.md b/markdown/dev/reference/api/part/getid/en.md index ef08ea28e60..59df01a9403 100644 --- a/markdown/dev/reference/api/part/getid/en.md +++ b/markdown/dev/reference/api/part/getid/en.md @@ -1,13 +1,34 @@ --- -title: getId() +title: Part.getId() --- +A part's `getId()` method will return an integer the can be used as an +ID Points/Paths/Snippets. This method will ensure the ID is unique be +keeping an internal record of the ID that have been used. +It is typically used when programatically adding points, paths, or snippets. + +## Part.getId() signature + ```js int part.getId(prefix='') ``` -Returns a integer as an available ID that you can use as for Points/Paths/Snippets. -Takes an options `prefix` to prefix the ID with. +This methiod takes an optional parameter that will be used as a prefix for the ID. + +## Part.getId() example + +```js +export default function (part) { + const { Point, points } = part.shorthand() + + for (let i=0;i<10;i++) { + const id= part.getId() + points[id] = new Point(i*10, i*10) + } + + // You would do more useful stuff before returning + return part +} +``` -This is typically used when adding points programmatically. diff --git a/markdown/dev/reference/api/part/raise/debug/en.md b/markdown/dev/reference/api/part/raise/debug/en.md index 6d2efb73a44..59f5016420e 100644 --- a/markdown/dev/reference/api/part/raise/debug/en.md +++ b/markdown/dev/reference/api/part/raise/debug/en.md @@ -1,12 +1,10 @@ --- -title: raise.debug() +title: Part.raise.debug() --- -```js -raise.debug(data) -``` - -The `raise.debug()` method adds an event of type `debug` to the pattern. +A part's `raise.debug()` method will log a debug-level event. +Debug events are typically used to pass information to pattern developers +so that can troubleshoot issues with the pattern. What happens with this data is entirely up to the frontend developer. As such, data can by anything you like. A string is common, but you @@ -18,3 +16,23 @@ use in your frontend. All raise methods are available via [the shorthand method](/reference/api/part/shorthand) + +## Part.raise.debug() signature + +```js +raise.debug(data) +``` + +## Part.raise.debug() example + +```js +export default function (part) { + const { raise } = part.shorthand() + + raise.debug('Entered the draft method of partmyPart') + + // You would do more useful stuff before returning + return part +} +``` + diff --git a/markdown/dev/reference/api/part/raise/en.md b/markdown/dev/reference/api/part/raise/en.md index d679dc36558..37f08d903e3 100644 --- a/markdown/dev/reference/api/part/raise/en.md +++ b/markdown/dev/reference/api/part/raise/en.md @@ -1,9 +1,19 @@ --- -title: raise methods +title: Part raise methods --- -The various `raise` methods are used to bring information to the attention -of the user, or developer. +A part's different `raise` methods are used to bring information to the attention +of the user, or developer. You can think of them as logging methods the register +data. + + + +##### FreeSewing v3 breaking changes + +This behavior is likely to change in FreeSewing v3. Refer to [the +roadmap](https://github.com/freesewing/freesewing/discussions/1278) for details. + + There are four different types of information with their own method: diff --git a/markdown/dev/reference/api/part/raise/error/en.md b/markdown/dev/reference/api/part/raise/error/en.md index 0c3c477d26c..00c9c3078fd 100644 --- a/markdown/dev/reference/api/part/raise/error/en.md +++ b/markdown/dev/reference/api/part/raise/error/en.md @@ -1,27 +1,35 @@ --- -title: raise.error() +title: Part.raise.error() --- -```js -raise.error(data) -``` - -The `raise.error()` method adds an event of type `error` to the pattern. - - - -##### Raising an error will prevent the pattern from being completed - -Unlike other events, which have no side-effects, if there is one or more +A part's `raise.error()` method will log a error-level event. +Unlike other raised events which have no side-effects, if there is one or more events of type `error`, the pattern will not be completed. - -In other words, you should only use this when the situation is unrecoverable. -If not, [raise a warning](/reference/api/part/raise/warning). - - +In other words, you should only use this when end up in a situation +you cannot recover from. If not, [raise a warning](/reference/api/part/raise/warning). All raise methods are available via [the shorthand method](/reference/api/part/shorthand) + +## Part.raise.error() signature + +```js +raise.error(data) +``` + +## Part.raise.error() example + +```js +export default function (part) { + const { raise, measurements } = part.shorthand() + + if (measurements.hips > measurements.chest) { + raise.warning('Chest circumference smaller than hip circumference is currently unsupported. Aborting.') + return part + } +} +``` + diff --git a/markdown/dev/reference/api/part/raise/info/en.md b/markdown/dev/reference/api/part/raise/info/en.md index 535918fd785..0b3c9f40e53 100644 --- a/markdown/dev/reference/api/part/raise/info/en.md +++ b/markdown/dev/reference/api/part/raise/info/en.md @@ -1,12 +1,10 @@ --- -title: raise.info() +title: Part.raise.info() --- -```js -raise.info(data) -``` - -The `raise.info()` method adds an event of type `info` to the pattern. +A part's `raise.info()` method will log a ingo-level event. +Info events are typically used to pass information to users +that is informative to them. What happens with this data is entirely up to the frontend developer. As such, data can by anything you like. A string is common, but you @@ -18,3 +16,22 @@ use in your frontend. All raise methods are available via [the shorthand method](/reference/api/part/shorthand) + +## Part.raise.info() signature + +```js +raise.info(data) +``` + +## Part.raise.info() example + +```js +export default function (part) { + const { raise, options } = part.shorthand() + + if (options.shortSleeves) { + raise.info('Not drafting french cuffs because you opted for short sleeves') + return part + } +} +``` diff --git a/markdown/dev/reference/api/part/raise/warning/en.md b/markdown/dev/reference/api/part/raise/warning/en.md index 8af93d58bb6..6345b3bd24b 100644 --- a/markdown/dev/reference/api/part/raise/warning/en.md +++ b/markdown/dev/reference/api/part/raise/warning/en.md @@ -1,12 +1,11 @@ --- -title: raise.warning() +title: Part.raise.warning() --- -```js -raise.warning(data) -``` - -The `raise.warning()` method adds an event of type `warning` to the pattern. +A part's `raise.warning()` method will log a warning-level event. +Warning events are typically used to pass information to pattern developers +so that can troubleshoot issues with the pattern, or users to warn them +that something is sub-optimal. What happens with this data is entirely up to the frontend developer. As such, data can by anything you like. A string is common, but you @@ -18,3 +17,28 @@ use in your frontend. All raise methods are available via [the shorthand method](/reference/api/part/shorthand) + +## Part.raise.warning() signature + +```js +raise.warning(data) +``` + +## Part.raise.warning() example + +```js +export default function (part) { + const { raise, measurements } = part.shorthand() + + if (measurements.hips > measurements.chest) { + raise.warning(` + Chest circumference is smaller than hip circumference. + This might lead to unexpected results + `) + } + + // You would do more useful stuff before returning + return part +} +``` + diff --git a/markdown/dev/reference/api/part/shorthand/en.md b/markdown/dev/reference/api/part/shorthand/en.md index f7cfc432b10..cee551d0941 100644 --- a/markdown/dev/reference/api/part/shorthand/en.md +++ b/markdown/dev/reference/api/part/shorthand/en.md @@ -1,63 +1,80 @@ --- -title: shorthand() +title: Part.shorthand() --- +A part's `shorthand()` method provides easy access to a number of +internal objects and properties. It does so be returning an object +that contains all you need to draft your pattern parts. It is +typically combined with object destructuring to pull out those +properties you need. + +As the name implies, this method can save you a bunch of typing, and keep your +code concise. We highly recommend you use it. + +## Part.shorthand() signature + ```js object Part.shorthand(); ``` -This method returns a plain object with the following properties: +The `Part.shorthand()` method returns a plain object with the following properties: - - `complete` = `pattern.settings.complete` - - `events` : An object holding the raised events (see `raise`) - - `final` : `true` is this is a full draft, or `false` if this is a sample. - - `macro` : The macro runner - - `measurements` = `pattern.settings.measurements` - - `paperless` = `pattern.settings.paperless` - - `Path` : the [Path](/reference/api/path) constructor - - `paths` = `part.paths` - - `Point` : the [Point](/reference/api/point) constructor - - `points` = `part.points` - - `Snippet` : the [Snippet](/reference/api/snippet) constructor - - `snippets` = `part.snippets` - - `options` = `pattern.settings.options` - - `raise` : An object holding the various methods that allow you to [raise events](/reference/api/part/raise/) - - `sa` = `pattern.settings.sa` - - `store` = `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts - - `utils` : A [Utils](/reference/api/utils) instance with utility methods - - `units` : A context-aware version of `utils.units` +| Property | Description | +| --------:| ----------- | +| `config` | The pattern configuration | +| `complete` | Holds `pattern.settings.complete` | +| `events` | An object holding the raised events (see [Part.raise](/reference/api/part/raise/)) | +| `final` | `true` is this is a full draft, or `false` if this is a sample. | +| `macro` | The macro runner. See [the macros documentation](/reference/macros/) | +| `measurements` | Holds `pattern.settings.measurements` | +| `paperless` | Holds `pattern.settings.paperless` | +| `Path` | The [Path constructor](/reference/api/path) | +| `paths` | Holds `part.paths` | +| `Point` | The [Point constructor](/reference/api/point) | +| `points` | Holds `part.points` | +| `Snippet` | The [Snippet constructor](/reference/api/snippet) | +| `snippets` | Holds `part.snippets` | +| `options` | Holds `pattern.settings.options` | +| `raise` | Holds [Part.raise](/reference/api/part/raise/) thus giving you access to the various raise methods | +| `sa` | Holds `pattern.settings.sa` | +| `store` | Holds `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts | +| `utils` | A [Utils](/reference/api/utils) instance with utility methods | +| `units` | A context-aware version of `utils.units` | -As the name implies, this method can save you a bunch of typing, and keep your -code concise. We highly recommend it. Below are some examples: +## Part.shorthand() example ```js{16} // You could write this: part.points.from = new part.Point( - pattern.measurements.chestCircumference / 2, - pattern.options.armholeDepth); + pattern.measurements.chest / 2, + pattern.options.armholeDepth +) part.points.to = new part.Point( part.points.from.x + pattern.settings.sa, - part.points.from.y); + part.points.from.y +) part.paths.example = new part.Path() .move(parts.points.from) - .line(parts.points.to); + .line(parts.points.to) -// Or use shorthand: -let { Point, points, measurements, options, sa } = part.shorthand(); +// Or use shorthand: +const { Point, points, measurements, options, sa } = part.shorthand() points.from = new Point( - measurements.chestCircumference / 2, - options.armholeDepth); + measurements.chest / 2, + options.armholeDepth +) points.to = new part.Point( points.from.x + sa, - points.from.y); + points.from.y +) paths.example = new Path() .move(points.from) - .line(points.to); + .line(points.to) ``` diff --git a/markdown/dev/reference/api/part/units/en.md b/markdown/dev/reference/api/part/units/en.md index 84cbde17321..9c082d1c24b 100644 --- a/markdown/dev/reference/api/part/units/en.md +++ b/markdown/dev/reference/api/part/units/en.md @@ -1,12 +1,11 @@ --- -title: units() +title: Part.units() --- -```js -string part.units(float number) -``` - -Formats input (in mm) as the units requested by the user. +A part's `units()` method will formats a float you pass it, which should +represent a value in mm, into the units requested by the user. +The returned value is to be used in presentation only, as it will be +a string that includes the user's units. @@ -20,3 +19,19 @@ let { units } = part.shorthand(); +## Part.units() signature + +```js +string part.units(float number) +``` + +## Part.units() example + +```js +export default function (part) { + const { raise, units, measurements } = part.shorthand() + + raise.info(`Pattern drafted for a ${units(measurements.chest)} chest`) +} +``` + diff --git a/markdown/dev/reference/api/pattern/apply/en.md b/markdown/dev/reference/api/pattern/apply/en.md deleted file mode 100644 index 21d5c283610..00000000000 --- a/markdown/dev/reference/api/pattern/apply/en.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Pattern.apply() ---- - -A pattern's `apply()` method merges the settings passed to it with -the current pattern settings. It is used internally to merge the -settings that are passed to the pattern constructor with the default settings. - -This method is chainable as it returns the Pattern object - -## Pattern.apply() signature - -```js -Pattern pattern.apply(object settings) -``` - - -You are unlikely to ever user this method directly. - - diff --git a/markdown/dev/reference/api/pattern/needs/en.md b/markdown/dev/reference/api/pattern/needs/en.md deleted file mode 100644 index 73265cfb6ea..00000000000 --- a/markdown/dev/reference/api/pattern/needs/en.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Pattern.needs() ---- - -A pattern's `needs()` method will return `true` or `false` -depending on whether a pattern part is a requirement for the -pattern to be drafted in its current configuration. In other -words, it will return `true` of the part is *needed*. - -A part is needed if: - - - it is requested by the user in [the `only` pattern setting](/reference/settings/only/) - - it is a dependency of a part requested by the user in [the `only` pattern setting](/reference/settings/only/) - - [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden - - - -You don't typically use this method. Instead, you configure part -dependencies in your [configuration file](/reference/config/). - - - -## Pattern.needs() signature - -```js -bool pattern.needs(string partName) -``` - -## Pattern.needs() example - -```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" - -const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 -}) - -if (pattern.needs('front')) console.log('Front is needed') -else console.log('Front is not needed') -``` - - - diff --git a/markdown/dev/reference/api/pattern/wants/en.md b/markdown/dev/reference/api/pattern/wants/en.md deleted file mode 100644 index 8b5f0f7a977..00000000000 --- a/markdown/dev/reference/api/pattern/wants/en.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: wants() ---- - -A pattern's `wants()` method will return `true` or `false` -depending on whether a pattern part is requested in the -current pattern configuration. In other words, it will -return `true` of the part is *wanted* by the user. - -A part is wanted if: - - - it is requested by the user in [the `only` pattern setting](/reference/settings/only/) - - [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden - - - -You don't typically use this method. Instead, you configure part -dependencies in your [configuration file](/reference/config/). - - - -## Pattern.wants() signature - -```js -bool pattern.wants(string partName) -``` - -## Pattern.wants() example - -```js -import Aaron from "@freesewing/aaron" -import models from "@freesewing/models" - -const pattern = new Aaron({ - settings: { - embed: true, - }, - measurements: models.manSize38 -}) - -if (pattern.wants('front')) console.log('Front is wanted') -else console.log('Front is not wanted') -``` - diff --git a/markdown/dev/reference/api/svg/en.md b/markdown/dev/reference/api/svg/en.md index 7c23ebdef8c..625fa7d5104 100644 --- a/markdown/dev/reference/api/svg/en.md +++ b/markdown/dev/reference/api/svg/en.md @@ -11,7 +11,7 @@ While the methods exposed by this object are only used internally, its attributes are useful for situations where you want to develop a plugin, or use a custom layout: -## Properties +## Svg properties