fullscreen/MenuGraphr
0
0
Fork 0
mirror of https://github.com/FullScreenShenanigans/MenuGraphr.git synced 2026-08-12 02:18:35 -07:00
Code Issues Packages Projects Releases Wiki Activity

Removed typedoc docs generation

Browse Source
This commit is contained in:
Josh Goldberg
2019-04-14 16:49:35 -04:00
parent 4fc2f83097
commit e505dcf395
8 changed files with 20 additions and 753 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
-1
View File
@@ -1,5 +1,4 @@
dist/
docs/generated/
test/
node_modules/
*.d.ts
docs/dialogs.md
-120
View File
@@ -1,120 +0,0 @@
# Dialogs
Menu dialogs refer to any amount of text on a menu.
Some dialogs are static, and just used to display text Things on top of a menu.
Others are dynamic and can advance through formatted lines of interactive text.
## `addMenuDialog`
Adds dialog-style text to a menu.
If the text would overflow the menu's size, excess horizontal lines are delayed.
The user can advance through the menu with "A" button presses.
Parameters:
* `menuName`: Name of the menu.
* `dialog`: Raw dialog to add to the menu, as strings, arrays of strings, or complex placement commands.
* `onCompletion`: Optional callback for when the text is done.
### Dialogs
The actual type for menu dialogs is weirdly flexible:
```typescript
type IMenuDialogRaw = string | (string | string[] | (string | string[])[] | IMenuWordCommandBase)[];
```
#### String Dialogs
The simplest dialogs will typically just contain strings:
When provided as a raw string, the dialog is split across whitespace to generate words.
This forces the dialog to not wrap words across lines.
```typescript
// Creates a new GeneralText menu, deleting any existing one
menuGrapher.createMenu("GeneralText");
// Adds the dialog to GeneralText
menuGrapher.addMenuDialog("GeneralText", "Hello world!");
// Sets GeneralText as the active, input-receiving menu
menuGrapher.setActiveMenu("GeneralText");
```
#### Array Dialogs
Dialogs will show as many consecutive lines on "A" press as possible by default.
You can force a "break" in the sections by providing an array of dialog strings.
The dialog will clear any lines on the screen when moving across a break.
```typescript
menuGrapher.addMenuDialog("GeneralText", ["Hello world!", "Me again!"]);
```
### Advanced Commands
It's allowed to provide advanced "commands" to dialogs along with words in the dialogs.
These commands can insert "floating" text or change position offsets or alignments of the dialog text.
Alas, these command types aren't well fleshed out in `IMenuGraphr.ts` and not recommended until documentation is solidified.
See [#52](https://github.com/FullScreenShenanigans/MenuGraphr/issues/52).
## `IMenuSchema`
These options are available on `IMenuSchema` generally, but only useful once the menu is given a dialog.
### `deleteOnFinish`
Whether the menu should be deleted when its dialog finishes.
```typescript
{
deleteOnFinish: true,
}
```
### `finishAutomatically`
Whether the dialog should finish when the last word is displayed,
instead of waiting for user input.
```typescript
{
finishAutomatically: true,
},
```
### `finishAutomaticSpeed`
How many game ticks to delay completion by when `finishAutomatically` is true.
Defaults to `0`.
```typescript
{
finishAutomaticSpeed: 100,
}
```
### `finishLinesAutomatically`
Whether individual lines of dialog should finish when the last word is displayed,
instead of waiting for user input.
```typescript
{
finishLinesAutomatically: true,
},
```
### `finishLinesAutomaticSpeed`
How many game ticks to delay completion by when `finishLinesAutomatically` is true.
Defaults to `0`.
```typescript
{
finishLinesAutomaticSpeed: 100,
}
```
See [`lists.md`](./lists.md) for examples of lists intermixed with dialogs.
docs/lists.md
-214
View File
@@ -1,214 +0,0 @@
# Lists
Menus can have scrollable lists of selectable text options in them.
Users can use direction inputs to scroll through the items.
Lists can be one-dimensional or two-dimensional.
This is determined by the computed height of list options within the menu's height.
If enough options are added to a list to pass the bottom, unless the menu specifies `singleColumnList`, they will overflow to a column to the right.
## `IListMenuSchema`
When creating or declaring schemas for list menus, there are some additional properties you can apply to them.
These are all optional.
### `saveIndex`
Whether the last selected index should be saved.
When `true`, the parent EightBittr's ItemsHoldr will save the selected index of the menu under the menu's name.
Recreating the menu will read from that stored index if available.
```typescript
{
saveIndex: true,
},
```
### `clearedIndicesOnDeletion`
Names of menus whose whose selected indices that should be cleared when this menu is deleted.
Use this when there are multiple related list menus open at once, and finishing one clears another.
```typescript
{
clearedIndicesOnDeletion: [
"KeyboardKeys",
"NameCollection",
],
},
```
### `scrollingItems`
How many scrolling items should be visible within the menu vertically.
List menus will by default show all the items at once, which is bad if there are many options and not enough menu height to display them all.
Specify a `scrollingItems` number to hardcode a maximum to display at once.
If the user shifts their selected index to below the lowest displayed item or above the highest displayed item,
the menu will "scroll" items vertically.
It does this by shifting their Things vertically and setting `hidden` on items not allowed to be seen.
```typescript
{
scrollingItems: 10,
},
```
> There is no equivalent for horizontal items.
### `scrollingItemsComputed`
As an alternative to `scrollingItems`, you can have the maximum displayed number of items computed as a function of menu height and expected height per list option.
This will set the `scrollingItems` member of the menu on list creation.
```typescript
{
scrollingItemsComputed: true,
},
```
### `singleColumnList`
Whether the list should always be a single column, rather than auto-flow.
```typescript
{
singleColumnList: true,
},
```
## `addMenuList`
Adds a list of text options to a menu.
Parameters:
* `menuName`: Name of the menu.
* `settings`: Settings for the list, particularly its options.
### `IListMenuOption`
Individual option within a list.
Only `text` is required.
#### `callback`
Callback for when the option is triggered.
Receives just the menu name.
```typescript
{
options: [
{
callback: () => console.log("First!"),
text: "First",
},
],
},
```
#### `position`
Position offsets to shift the option by, allowing top, right, bottom, left.
```typescript
{
options: [
{
position: {
top: 30,
right: -20,
},
text: "First",
},
],
},
```
#### `text`
Text displayed as the option.
This text will be rendered all in one row, similar to dialogs.
### `IListMenuOptions`
Settings to create a new list menu.
Only
#### `bottom`
A bottom option to display underneath displayed options.
If the list is two-dimensional, this will span across all rows.
```typescript
{
bottom: {
callback: () => console.log("Cancelled."),
text: "Cancel",
},
},
```
#### `options`
Options within the menu, or a function to generate them.
This is a flat list of options regarldess of whether the menu is one- or two-dimensional.
```typescript
{
options: [
{
callback: () => console.log("First!"),
text: "First",
},
],
},
```
See `IListMenuOption` above.
#### `selectedIndex`
Each list contains a `selectedIndex: [number, number]` of the position of the currently selected index.
This option overrides the starting selected index.
It defaults to `[0, 0]`.
## Examples
Showing a simple "Yes/No" menu after a general text dialog that stays alive:
```typescript
const finalize = (choice) => {
console.log("Choice:", choice);
menuGrapher.deleteMenu("Yes/No");
};
const createOptions = () => {
menuGrapher.createMenu("Yes/No", {
killOnB: ["GeneralText"],
});
menuGrapher.addMenuList("Yes/No", {
options: [
{
text: "YES",
callback: () => finalize(true),
},
{
text: "NO",
callback: () => finalize(false),
}
],
});
menuGrapher.setActiveMenu("Yes/No");
};
menuGrapher.createMenu("GeneralText", {
finishAutomatically: true,
keepOnBack: true,
});
menuGrapher.addMenuDialog("GeneralText", "Are you sure?", createOptions);
menuGrapher.setActiveMenu("GeneralText");
```
docs/schemas.md
-337
View File
@@ -1,337 +0,0 @@
# Menu Schemas
## `IMenuSchema`
Attributes describing menu appearance and behavior.
These may be specified in the default schemas on a MenuGraphr instance or overriden with `createMenu`.
All properties are optional.
> See [`dialogs.md`](./dialogs.md) for properties specific to menu dialogs.
> See [`lists.md`](./lists.md) for properties specific to menu lists.
> See [`text.md`](./text.md) for properties around displaying text in dialog and list menus.
### `backMenu`
Name of a menu to set as active when this one is deleted.
```typescript
{
backMenu: "GeneralText",
},
```
### `callback`
Callback for when this menu is set as active.
Called with the menu name.
```typescript
{
callback: (menuName) => {
console.log("Set", menuName, "as active.");
},
},
```
### `childrenSchemas`
Schemas of children to add on creation.
These will be directly passed to `createMenuChild`, which will call `createMenu`, `createMenuWord`, or `createMenuThing` as per the child type.
As with regular menu schemas, these allow all properties as overrides.
```typescript
{
childrenSchemas: [
{
type: "text",
words: ["Hello", "world!"],
},
{
type: "thing",
thing: "PlayerPortrait",
position: {
horizontal: "right",
},
},
{
type: "menu",
name: "PlayerStats",
},
],
},
```
> See `IMenuChildSchema`.
### `container`
Name of a containing menu to position within.
If not provided, this defaults to the entire game canvas.
```typescript
{
container: "GeneralText",
},
```
### `height`
How tall the menu should be, as Thing height.
This will also set the general Thing height of the menu.
```typescript
{
height: 80,
},
```
### `ignoreA`
Whether user selection events should be ignored.
These "A" events normally advance menu dialogs forward or trigger selected items in lists.
```typescript
{
ignoreA: true,
},
```
### `ignoreB`
Whether user deselection events should be ignored.
These "B" events normally exit out of menus.
```typescript
{
ignoreB: true,
},
```
### `ignoreProgressB`
Whether deselection events should count as selection during dialogs.
Menus with "progress" are in the middle of dialog or list creation.
Pressing B during progress would normally advance the menu forward.
```typescript
{
ignoreProgressB: true,
},
```
### `keepOnBack`
Whether this should be kept alive when deselected.
Useful for switching active state between multiple menus on B.
```typescript
{
keepOnBack: true,
},
```
### `killOnB`
Other menus to kill when this is deselected.
Commonly used with "Yes/No"-style dialogs that appear along with text descriptions in other menus.
```typescript
{
killOnB: ["GeneralText", "OtherDecorations"],
},
```
### `onActive`
Callback for when the menu becomes active.
Receives just the menu name.
```typescript
{
onActive: (menuName) => {
console.log("Menu", menuName, "is now active.");
},
},
```
### `onBPress`
Callback for when the "B" button is pressed while the menu is active.
Receives just the menu name.
Does not fire if `ignoreB` is true.
Also does not fire if the menu is mid-progress and `ignoreProgressB` is not true, as that simulates an "A" press.
```typescript
{
onBPress: (menuName) => {
console.log("Menu", menuName, "received a B press.");
},
},
```
### `onDown`
Callback for when the "down" button is pressed.
Receives just the menu name.
```typescript
{
onDown: (menuName) => {
console.log("Menu", menuName, "received a down event.");
},
},
```
### `onInactive`
Callback for when the menu becomes inactive.
Receives just the menu name.
```typescript
{
onActive: (menuName) => {
console.log("Menu", menuName, "is now active.");
},
},
```
### `onLeft`
Callback for when the "left" button is pressed.
Receives just the menu name.
```typescript
{
onLeft: (menuName) => {
console.log("Menu", menuName, "received a left event.");
},
},
```
### `onMenuDelete`
Callback for when the menu is deleted.
Receives just the menu name.
This is called _after_ the menu is deleted, but _before_ menu children are deleted.
```typescript
{
onMenuDelete: (menuName) => {
console.log("Menu", menuName, "was deleted.");
},
},
```
### `onRight`
Callback for when the "right" button is pressed.
Receives just the menu name.
```typescript
{
onRight: (menuName) => {
console.log("Menu", menuName, "received a right event.");
},
},
```
### `onUp`
Callback for when the "up" button is pressed.
Receives just the menu name.
```typescript
{
onUp: (menuName) => {
console.log("Menu", menuName, "received an up event.");
},
},
```
### `size`
Sizing description, including `height` and `width`.
This will override the native Thing `height` and `width` on the Menu.
```typescript
{
size: {
height: 80,
width: 40,
},
},
```
```typescript
{
},
```
> This allows menus to act as containers at a different size from their visual Things.
### `width`
How wide the menu should be, as Thing width.
This will also set the general Thing width of the menu.
```typescript
{
width: 40,
},
```
### `position`
How the menu should be positioned within its container.
Defaults to the menu aligning itself to the top-left corner of its container and no width or height.
#### `horizontal`
Modifies how the schema lays itself out horizontally.
* If `"center"`, aligns to the horizontal midpoint of its container.
* If `"right"`, its right aligns with its container's right.
* If `"stretch"`, stretches to fit its container horizontally.
```typescript
position: {
horizontal: "right",
},
```
#### `offset`
Horizontal and vertical offsets to shift the menu by.
These are allowed to be negative numbers, are calculated relative to the menu's container, and each reduce the menu's size horizontally or vertically.
```typescript
position: {
offset: {
top: -1,
right: 2,
bottom: 3,
left: -4,
},
},
```
#### `vertical`
Modifies how the schema lays itself out vertically.
* If `"center"`, aligns to the vertical midpoint of its container.
* If `"bottom"`, its bottom aligns with its container's bottom.
* If `"stretch"`, stretches to fit its container vertically.
```typescript
position: {
vertical: "bottom",
},
```
docs/text.md
-74
View File
@@ -1,74 +0,0 @@
# Text
Text within menu dialogs and lists can be displayed with granular controls over paddings and spacing.
## `IMenuSchema`
These options will be used when the menu has a dialog or list added.
### `textPaddingRight`
How much padding there is between the right of the text and the right side of the box.
Text in dialogs will return to the next line instead of crossing the menu's `right` minus `textPaddingRight`.
Defaults to `0` (none) if not provided.
Allowed to be negative.
```typescript
{
textPaddingRight: 8,
},
```
### `textPaddingX`
How much horizontal padding should be between characters.
Defaults to the `"Text"` Thing prototype's `paddingX` if it exists, or `0` otherwise.
Characters placed next to each other in dialogs and lists will be placed this number of game pixels to the right each subsequent character.
```typescript
{
textPaddingX: 4,
},
```
### `textPaddingY`
How much vertical padding should be between lines of text.
Defaults to the `"Text"` Thing prototype's `paddingY` if it exists, or `0` otherwise.
Lines of text in dialogs and lists will start this number of game pixels lower each line.
```typescript
{
textPaddingY: 12,
},
```
### `textSpeed`
How long to delay between placing characters and words.
If `0` or not provided, characters and words will be placed immediately.
Otherwise, each character will wait a `textSpeed` delay before displaying.
Words will wait a `textSpeed` delay before appearing after each other as well, which gives the illusion of spaces between words also adhering to the delay.
### `textXOffset`
Horizontal offset for the text placement area.
All text will be offset horizontally by this amount.
```typescript
{
textXOffset: 2,
},
```
### `textYOffset`
Vertical offset for the text placement area.
All text will be offset vertically by this amount.
```typescript
{
textYOffset: -2,
},
```
package-lock.json
Generated
+3 -3
View File
@@ -5491,9 +5491,9 @@
}
},
"shenanigans-manager": {
"version": "0.2.39",
"resolved": "https://registry.npmjs.org/shenanigans-manager/-/shenanigans-manager-0.2.39.tgz",
"integrity": "sha512-Lr/JMUWQF35tkLryRhIcxGg05meh7wdX9bipqfd7YfxRw0t02dEG4sohViX15NhZd58rTKzUGSdiL7CrAXMIwA==",
"version": "0.2.40",
"resolved": "https://registry.npmjs.org/shenanigans-manager/-/shenanigans-manager-0.2.40.tgz",
"integrity": "sha512-sVP3iUrhE2/ro3KD+/MtvEyEcUmL6kfMFB6Exr9Ks4GyLV3sSKO7PEEMuO9zwZa3UQnNwOOrZtYi8G820wD8qw==",
"dev": true,
"requires": {
"chalk": "^2.4.2",
package.json
+4 -4
View File
@@ -30,7 +30,7 @@
"npm-check-updates": "^3.1.7",
"requirejs": "^2.3.6",
"run-for-every-file": "^1.1.0",
"shenanigans-manager": "^0.2.39",
"shenanigans-manager": "^0.2.36",
"sinon": "^7.3.1",
"sinon-chai": "^3.3.0",
"tslint": "5.15.0",
@@ -77,8 +77,8 @@
"test:setup:dir": "mkdirp test",
"test:setup:html": "shenanigans-manager generate-test-html",
"test:setup:tsc": "tsc -p test",
"verify": "npm run src && npm run test && npm run dist && npm run docs",
"verify:coverage": "npm run src && npm run test:setup && npm run test:coverage && npm run dist && npm run docs",
"verify": "npm run src && npm run test && npm run dist",
"verify:coverage": "npm run src && npm run test:setup && npm run test:coverage && npm run dist",
"watch": "concurrently \"tsc -p . -w\" --raw \"chokidar src/**/*.test.t* --command \"\"npm run test:setup:html\"\" --silent\" --raw"
},
"shenanigans": {
@@ -86,4 +86,4 @@
},
"types": "./src/index.d.ts",
"version": "0.7.11"
}
}
settings.json
+13
View File
@@ -0,0 +1,13 @@
{
"editor.tabSize": 4,
"editor.trimAutoWhitespace": true,
"files.exclude": {
"**/*.d.ts": true,
"**/*.js.map": true,
"**/*.js": { "when": "$(basename).ts" },
"**/*?.js": { "when": "$(basename).tsx" }
},
"tslint.alwaysShowRuleFailuresAsWarnings": true,
"tslint.autoFixOnSave": true,
"typescript.tsdk": "node_modules/typescript/lib"
}