Skip to main content

tw5-typed / modules/widgets/navigator / navigator

Class: navigator

modules/widgets/navigator.navigator

Link

https://tiddlywiki.com/dev/#Widgets

Create a widget object for a parse tree node

  • parseTreeNode: reference to the parse tree node to be rendered
  • options: see below

Options include:

  • wiki: mandatory reference to wiki associated with this render tree
  • parentWidget: optional reference to a parent renderer node for the context chain
  • document: optional document object to use instead of global document

Hierarchy

Table of contents

Constructors

Properties

Methods

Constructors

constructor

new navigator(parseTreeNode, options?): navigator

Parameters

NameType
parseTreeNodeIParseTreeNode
options?IWidgetInitialiseOptions

Returns

navigator

Inherited from

widget.constructor

Defined in

src/modules/widgets/index.d.ts:117

Properties

ancestorCount

Optional ancestorCount: number

Inherited from

widget.ancestorCount

Defined in

src/modules/widgets/index.d.ts:106


attributes

attributes: Record<string, string>

Inherited from

widget.attributes

Defined in

src/modules/widgets/index.d.ts:86


children

children: widget[]

Inherited from

widget.children

Defined in

src/modules/widgets/index.d.ts:102


document

document: IFakeDocument

Inherited from

widget.document

Defined in

src/modules/widgets/index.d.ts:82


domNodes

domNodes: Element[]

Inherited from

widget.domNodes

Defined in

src/modules/widgets/index.d.ts:88


eventListeners

eventListeners: Record<string, Function>

Inherited from

widget.eventListeners

Defined in

src/modules/widgets/index.d.ts:93


parentDomNode

parentDomNode: Element

Inherited from

widget.parentDomNode

Defined in

src/modules/widgets/index.d.ts:90


parentWidget

Optional parentWidget: widget

Inherited from

widget.parentWidget

Defined in

src/modules/widgets/index.d.ts:84


parseTreeNode

parseTreeNode: IParseTreeNode

Inherited from

widget.parseTreeNode

Defined in

src/modules/widgets/index.d.ts:78


qualifiers

Optional qualifiers: Record<string, string>

Inherited from

widget.qualifiers

Defined in

src/modules/widgets/index.d.ts:104


variables

variables: Record<string, IWidgetVariable>

Set the value of a context variable

  • name: name of the variable
  • value: value of the variable
  • params: array of {name: string, default: string} for each parameter
  • isMacroDefinition: true if the variable is set via a \define macro pragma (and hence should have variable substitution performed)

Inherited from

widget.variables

Defined in

src/modules/widgets/index.d.ts:115


widgetClasses

widgetClasses: Record<string, typeof widget>

we can use $tw.rootWidget.widgetClasses.xxx to new a widget

This is a set of all widgets defined in tiddlywiki.

Inherited from

widget.widgetClasses

Defined in

src/modules/widgets/index.d.ts:100


wiki

wiki: Wiki

Inherited from

widget.wiki

Defined in

src/modules/widgets/index.d.ts:80

Methods

addEventListener

addEventListener(type, handler): void

Add an event listener. If the handler is sync, then should return a boolean, false means the event is handled and don't propagate, and true will be dispatched to the parent widget. If the handler is async, then it is always propagate to the parent widget.

Parameters

NameType
typestring
handler(event: IWidgetEvent) => boolean | void | Promise<void>

Returns

void

should propagate to parent widget

Inherited from

widget.addEventListener

Defined in

src/modules/widgets/index.d.ts:390


addEventListeners

addEventListeners(listeners): void

Add a list of event listeners from an array [{type:,handler:},...] See also addEventListener.

Parameters

NameType
listeners{ handler: (event: IWidgetEvent) => boolean | void | Promise<void> ; type: string }[]

Returns

void

Inherited from

widget.addEventListeners

Defined in

src/modules/widgets/index.d.ts:377


addToHistory

addToHistory(title, fromPageRect?): void

Add a new record to the top of the history stack title: a title string or an array of title strings fromPageRect: page coordinates of the origin of the navigation

Parameters

NameType
titlestring
fromPageRect?DOMRect

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:17


addToStory

addToStory(title, fromTitle?): void

Parameters

NameType
titlestring
fromTitle?string

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:11


allowActionPropagation

allowActionPropagation(): boolean

Returns

boolean

En

invokeActions will invoke the action widgets that are descendents of the current action widget, if this returns true (by default is true, invocation will propagate through through the child). Override this method and return false to stop the propagation down, and handle the invocation of child widgets by yourself.

Inherited from

widget.allowActionPropagation

Defined in

src/modules/widgets/index.d.ts:449


assignAttributes

assignAttributes(domNode, options?): any

Parameters

NameType
domNodeElement
options?Object
options.excludeEventAttributes?boolean

Returns

any

En

Assign the computed attributes of the widget to a domNode options include:

  • excludeEventAttributes: ignores attributes whose name begins with "on"

Zh

将微件的计算属性分配给一个 domNode, 选项包括:

  • excludeEventAttributes: 忽略名称以 "on "开头的属性 一些特殊的属性:
  • xlink:<xlink-name>
  • style.<css-style-name>

Memberof

Widget

Inherited from

widget.assignAttributes

Defined in

src/modules/widgets/index.d.ts:316


computeAttribute

computeAttribute(attribute): string

Parameters

NameType
attributestring

Returns

string

Inherited from

widget.computeAttribute

Defined in

src/modules/widgets/index.d.ts:262


computeAttributes

computeAttributes(): Record<string, true>

Returns

Record<string, true>

Object with keys of the names of the attributes that have changed

En

Compute the current values of the attributes of the widget. Returns a hashmap of the names of the attributes that have changed

Zh

计算微件的属性的当前值。返回一个已经改变的属性名称的哈希图

Memberof

Widget

Inherited from

widget.computeAttributes

Defined in

src/modules/widgets/index.d.ts:260


dispatchEvent

dispatchEvent(widgetEvent): void

Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget Events added via addEventListener, like tm-notify, can be invoked by this.

Parameters

NameType
widgetEventOmit<IWidgetEvent, "widget"> & { widget?: widget }

Returns

void

Inherited from

widget.dispatchEvent

Defined in

src/modules/widgets/index.d.ts:399


evaluateMacroModule

evaluateMacroModule(name, actualParameters, defaultValue): string

Parameters

NameType
namestring
actualParametersIWidgetVariableParameter[]
defaultValuestring

Returns

string

Inherited from

widget.evaluateMacroModule

Defined in

src/modules/widgets/index.d.ts:222


execute

execute(): void

Compute the internal state of the widget. This will be automatically called in the render method.

For example, getAttribute and set them to class members.

Returns

void

Inherited from

widget.execute

Defined in

src/modules/widgets/index.d.ts:160


findFirstDomNode

findFirstDomNode(): Element

Find the first DOM node generated by a widget or its children

Returns

Element

Inherited from

widget.findFirstDomNode

Defined in

src/modules/widgets/index.d.ts:421


findNextSiblingDomNode

findNextSiblingDomNode(startIndex?): Element

Find the next sibling in the DOM to this widget. This is done by scanning the widget tree through all next siblings and their descendents that share the same parent DOM node

Parameters

NameTypeDescription
startIndex?numberRefer to this widget by its index within its parents children

Returns

Element

Inherited from

widget.findNextSiblingDomNode

Defined in

src/modules/widgets/index.d.ts:416


generateDraftTitle

generateDraftTitle(title): void

Parameters

NameType
titleany

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:25


getAncestorCount

getAncestorCount(): number

Returns

number

number of ancestor widgets for this widget

En

Get the number of ancestor widgets for this widget

Zh

获取这个微件的祖先微件的数量

Memberof

Widget

Inherited from

widget.getAncestorCount

Defined in

src/modules/widgets/index.d.ts:330


getAttribute

getAttribute(name): string

Parameters

NameTypeDescription
namestringattribute name, for example, actions in the button widget

Returns

string

parameters

En

Get parameters that user set in the widget

Zh

获取用户在小组件中设置的参数

Memberof

Widget

Inherited from

widget.getAttribute

Defined in

src/modules/widgets/index.d.ts:297

getAttribute(name, fallbackText): string

Parameters

NameType
namestring
fallbackTextstring

Returns

string

Inherited from

widget.getAttribute

Defined in

src/modules/widgets/index.d.ts:298


getStateQualifier

getStateQualifier(name): string

Parameters

NameType
namestring

Returns

string

En

Construct a qualifying string based on a hash of concatenating the values of a given variable in the parent chain

Zh

在连接父链中给定变量值的哈希基础上构建一个限定字符串

Memberof

Widget

Inherited from

widget.getStateQualifier

Defined in

src/modules/widgets/index.d.ts:249


getStoryList

getStoryList(): string[]

Returns

string[]

Defined in

src/modules/widgets/navigator.d.ts:3


getVariable

getVariable(name, options?): string

Simplified version of getVariableInfo() that just returns the text

Parameters

NameType
namestring
options?IGetWidgetVariableOptions

Returns

string

Inherited from

widget.getVariable

Defined in

src/modules/widgets/index.d.ts:210


getVariableInfo

getVariableInfo(name, options?): Object

Get the prevailing value of a context variable

Parameters

NameTypeDescription
namestringvariable name, for example, currentTiddler in the widget context
options?IGetWidgetVariableOptionsoptions for getVariableInfo() Options include * params: array of {name: string, default: string} for each parameter * defaultValue: default value if the variable is not defined * source: optional source iterator for evaluating function invocations * allowSelfAssigned: if true, includes the current widget in the context chain instead of just the parent Returns an object with the following fields: * params: array of {name:,value:} of parameters passed to wikitext variables * text: text of variable, with parameters properly substituted * resultList: result of variable evaluation as an array * srcVariable: reference to the object defining the variable

Returns

Object

NameType
isCacheable?boolean
params?IWidgetVariableParameter[]
srcVariable?IWidgetVariable
textstring

Inherited from

widget.getVariableInfo

Defined in

src/modules/widgets/index.d.ts:197


handleCancelTiddlerEvent

handleCancelTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:27


handleCloseAllTiddlersEvent

handleCloseAllTiddlersEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:20


handleCloseOtherTiddlersEvent

handleCloseOtherTiddlersEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:21


handleCloseTiddlerEvent

handleCloseTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:19


handleDeleteTiddlerEvent

handleDeleteTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:23


handleEditTiddlerEvent

handleEditTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:22


handleFoldAllTiddlersEvent

handleFoldAllTiddlersEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:45


handleFoldOtherTiddlersEvent

handleFoldOtherTiddlersEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:44


handleFoldTiddlerEvent

handleFoldTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:43


handleImportTiddlersEvent

handleImportTiddlersEvent(event): void

Import JSON tiddlers into a pending import tiddler

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:41


handleNavigateEvent

handleNavigateEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:18


handleNewTiddlerEvent

handleNewTiddlerEvent(event): void

Create a new draft tiddler event.param can either be the title of a template tiddler, or a hashmap of fields. The title of the newly created tiddler follows these rules:

  • If a hashmap was used and a title field was specified, use that title
  • If a hashmap was used without a title field, use a default title, if necessary making it unique with a *numeric suffix
  • If a template tiddler was used, use the title of the template, if necessary making it unique with a *numeric suffix If a draft of the target tiddler already exists then it is reused

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:37


handlePerformImportEvent

handlePerformImportEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:42


handleSaveTiddlerEvent

handleSaveTiddlerEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:26


handleUnfoldAllTiddlersEvent

handleUnfoldAllTiddlersEvent(event): void

Parameters

NameType
eventIWidgetEvent

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:46


hasAttribute

hasAttribute(attribute): boolean

Parameters

NameType
attributestring

Returns

boolean

En

Check for the presence of an evaluated attribute on the widget. Note that attributes set to a missing variable (ie attr=<<missing>>) will be treated as missing

Zh

检查微件上是否存在一个已评估的属性。请注意,设置为缺失变量的属性(即attr=<<missing>>)将被视为缺失。

Memberof

Widget

Inherited from

widget.hasAttribute

Defined in

src/modules/widgets/index.d.ts:273


hasParseTreeNodeAttribute

hasParseTreeNodeAttribute(attribute): boolean

Parameters

NameType
attributestring

Returns

boolean

En

Check for the presence of a raw attribute on the widget parse tree node. Note that attributes set to a missing variable (ie attr=<<missing>>) will NOT be treated as missing

Zh

检查微件解析树节点上是否存在原始属性。注意,设置为缺失变量的属性(即ttr=<<missing>>)不会被视为缺失。

Memberof

Widget

Inherited from

widget.hasParseTreeNodeAttribute

Defined in

src/modules/widgets/index.d.ts:284


hasVariable

hasVariable(name, value): boolean

Parameters

NameType
namestring
valuestring

Returns

boolean

En

Check whether a given context variable value exists in the parent chain

Zh

检查一个给定的上下文变量值是否存在于父链中

Memberof

Widget

Inherited from

widget.hasVariable

Defined in

src/modules/widgets/index.d.ts:238


initialise

initialise(parseTreeNode, options?): void

Parameters

NameType
parseTreeNodeIParseTreeNode
options?IWidgetInitialiseOptions

Returns

void

En

Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses

Zh

初始化 widget 属性。这些步骤被拉出构造函数,以便我们可以在子类中重复使用它们

Inherited from

widget.initialise

Defined in

src/modules/widgets/index.d.ts:128


invokeAction

invokeAction(triggeringWidget, event): boolean | void

Invoke the action associated with this widget

No every widget has this method, but some do, like action-xxx widget, e.g., action-sendmessage

Parameters

NameType
triggeringWidgetwidget
eventIWidgetEvent

Returns

boolean | void

handled

Inherited from

widget.invokeAction

Defined in

src/modules/widgets/index.d.ts:439


invokeActionString

invokeActionString(actions, triggeringWidget, event, variables): boolean

Parameters

NameType
actionsstring
triggeringWidgetwidget
eventIWidgetEvent
variablesRecord<string, IWidgetVariable>

Returns

boolean

En

Invoke the action widgets defined in a string

Memberof

Widget

Inherited from

widget.invokeActionString

Defined in

src/modules/widgets/index.d.ts:471


invokeActions

invokeActions(triggeringWidget, event): boolean

Parameters

NameType
triggeringWidgetwidget
eventIWidgetEvent

Returns

boolean

En

Invoke the action widgets that are descendents of the current widget.

Memberof

Widget

Inherited from

widget.invokeActions

Defined in

src/modules/widgets/index.d.ts:459


makeChildWidget

makeChildWidget(parseTreeNode, options?): widget

Construct the widget object for a parse tree node, and return the new widget options include: variables: optional hashmap of variables to wrap around the widget

Parameters

NameType
parseTreeNodeIParseTreeNode
options?Object
options.variables?unknown

Returns

widget

Inherited from

widget.makeChildWidget

Defined in

src/modules/widgets/index.d.ts:347


makeChildWidgets

makeChildWidgets(parseTreeNodes?, options?): void

Make child widgets correspondng to specified parseTreeNodes And push them to this.children

Parameters

NameTypeDescription
parseTreeNodes?IParseTreeNode[]default to this.parseTreeNode.children, can be undefined
options?Object-
options.variables?unknown-

Returns

void

Inherited from

widget.makeChildWidgets

Defined in

src/modules/widgets/index.d.ts:337


makeDraftTiddler

makeDraftTiddler(targetTitle): void

Parameters

NameType
targetTitleany

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:24


nextSibling

nextSibling(): widget

Returns

widget

En

Get the next sibling of this widget

Memberof

Widget

Inherited from

widget.nextSibling

Defined in

src/modules/widgets/index.d.ts:358


previousSibling

previousSibling(): widget

Returns

widget

En

Get the previous sibling of this widget

Memberof

Widget

Inherited from

widget.previousSibling

Defined in

src/modules/widgets/index.d.ts:366


refresh

refresh(changedTiddlers): boolean | void

Parameters

NameTypeDescription
changedTiddlersIChangedTiddlersObject key is tiddler title, value is metadata about the change

Returns

boolean | void

En

Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering. You can do some cleanup or buildup before return true.

Zh

如果需要的话,有选择地刷新该微件。如果该微件或其任何子项需要重新渲染,则返回 true。 你可以在返回 true 之前做一些清理或构建工作。

Link

https://tiddlywiki.com/dev/#Selective%20Update

Inherited from

widget.refresh

Defined in

src/modules/widgets/index.d.ts:152


refreshChildren

refreshChildren(changedTiddlers?): boolean

Refresh all the children of a widget, will call this.render. Need to call this after setVariable

Parameters

NameType
changedTiddlers?IChangedTiddlers

Returns

boolean

Inherited from

widget.refreshChildren

Defined in

src/modules/widgets/index.d.ts:410


refreshSelf

refreshSelf(): boolean | void

Rebuild a previously rendered widget

Returns

boolean | void

Inherited from

widget.refreshSelf

Defined in

src/modules/widgets/index.d.ts:404


removeChildDomNodes

removeChildDomNodes(): void

Remove any DOM nodes created by this widget or its children

If this widget has directly created DOM nodes, delete them and exit. This assumes that any child widgets are contained within the created DOM nodes, which would normally be the case. Otherwise, ask the child widgets to delete their DOM nodes

Returns

void

Inherited from

widget.removeChildDomNodes

Defined in

src/modules/widgets/index.d.ts:429


removeLocalDomNodes

removeLocalDomNodes(): void

Returns

void

Inherited from

widget.removeLocalDomNodes

Defined in

src/modules/widgets/index.d.ts:478


removeTitleFromStory

removeTitleFromStory(storyList, title): void

Parameters

NameType
storyListstring[]
titlestring

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:5


render

render(parent, nextSibling): void

Parameters

NameType
parentElement
nextSiblingElement

Returns

void

En

Lifecycle method: Render this widget into the DOM

Zh

生命周期方法:将这个微件渲染到 DOM 中; 只会在首次渲染、销毁后重新渲染时自动调用,或者通过 refreshSelf 等方法主动调用

Inherited from

widget.render

Defined in

src/modules/widgets/index.d.ts:140


renderChildren

renderChildren(parent, nextSibling): void

Render the children of this widget into the DOM

Parameters

NameType
parentElement
nextSiblingElement

Returns

void

Inherited from

widget.renderChildren

Defined in

src/modules/widgets/index.d.ts:371


replaceFirstTitleInStory

replaceFirstTitleInStory(storyList, oldTitle, newTitle): void

Parameters

NameType
storyListstring[]
oldTitlestring
newTitlestring

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:6


resolveVariableParameters

resolveVariableParameters(formalParameters?, actualParameters?): IWidgetVariableParameter[]

Parameters

NameType
formalParameters?IWidgetVariableParameter[]
actualParameters?IWidgetVariableParameter[]

Returns

IWidgetVariableParameter[]

Inherited from

widget.resolveVariableParameters

Defined in

src/modules/widgets/index.d.ts:212


saveStoryList

saveStoryList(storyList): void

Parameters

NameType
storyListstring[]

Returns

void

Defined in

src/modules/widgets/navigator.d.ts:4


setVariable

setVariable(name, value, parameters?, isMacroDefinition?): void

Parameters

NameTypeDescription
namestringname of the variable
valuestringvalue of the variable
parameters?IWidgetVariableParameter[]-
isMacroDefinition?booleantrue if the variable is set via a \define macro pragma (and hence should have variable substitution performed)

Returns

void

En

Set the value of a context variable

Zh

设置一个上下文变量的值

Inherited from

widget.setVariable

Defined in

src/modules/widgets/index.d.ts:173


substituteVariableReferences

substituteVariableReferences(text, options): string

Parameters

NameType
textstring
optionsObject
options.variablesRecord<string, string>

Returns

string

Inherited from

widget.substituteVariableReferences

Defined in

src/modules/widgets/index.d.ts:217