Also removed a few redundant headings in class documentation
comments. There is already an @class and it looks a bit odd in
the generated pages:
<h2>TextString</h2>
<p>TextString</p>
<p>This class provides a ...</p>
Change-Id: Ie311c6993ed02e79272dbde71f6a1bc252ef3037
* Document them consistently between secetions Inheritance and
Static Properties under their own (new) section Events.
* Removed any quotes or brackets around the event name in existing
@emit annotations
Search: @emit.*['"{}(){}]
* For every call to this.emit() anywhere, added @emits.
* Fixed all warnings for references to undefined events
(introduced as a result of the previous point).
Event handler parameter documented based on the emit() call
and actual handlers using the event. Usually the latter is
more elaborate.
* Extend coverage of jQuery as needed
(copied from mwcore/maintenance/jsduck/external.js
written by me, hereby implicitly and explicitly released under MIT).
Specifics
* ve.ce.Surface#onContentChange: Fixed type of range from Object to ve.Range.
* ve.ce.SurfaceObserver#poll: Fix syntax for code from {} to `backticks`.
* ve.ui.Toolbar#onContextChange: Doesn't actually emit "clearState" event.
Removed #onClearState in Tool, ButtonTool and DropdownTool.
Bug: 45872
Change-Id: Id879aa769b2c72d86a0322e75dddeb868211ce28
This is a major refactor of user interface context, frame, dialog
and inspector classes, including adding several new classes which
generalize managing inspectors/dialogs (which are now subclasses
of window).
New classes:
* ve.ui.Window.js - base class for inspector and dialog classes
* ve.ui.WindowSet.js - manages mutually exclusive windows, used
by surface and context for dialogs and inspectors respectively
* ve.ui.DialogFactory - generates dialogs
* ve.ui.IconButtonWidget - used in inspector for buttons in the head
Refactored classes:
* ve.ui.Context - moved inspector management to window set
* ve.ui.Frame - made iframes initialize asynchronously
* ve.ui.Dialog and ve.ui.Inspector - moved initialization to async
initialize method
Other interesting bits:
ve.ui.*Icons*.css, *.svg, *.png, *.ai
* Merged icon stylesheets so all icons are available inside windows
* Renamed inspector icon to window
ve.ui.*.css
* Reorganized styles so that different windows can include only
what they need
* Moved things to where they belonged (some things were in strange places)
ve.init.Target.js, ve.init.mw.ViewPageTarget.js, ve.init.sa.Target.js
* Removed dialog management - dialogs are managed by the surface now
ve.ui.*Dialog.js
* Renamed title message static property
* Added registration
ve.ui.*Inspector.js
* Switch to accept surface object rather than context, which conforms
to the more general window class without losing any functionality
(in fact, most of the time the surface was what we actually wanted)
ve.ui.MenuWidget.js, ve.ui.MWLinkTargetInputWidget.js
* Using surface overly rather than passing an overlay around
through constructors
Change-Id: Ifd16a1003ff44c48ee7b2c66928cf9cc858b2564
Heading and Preformatted nodes have rules that should only
exist under a document node in MediaWiki.
Two new node types have been created as has a new DropdownTool which
uses these. The MW init options have been changed to use the new
DropdownTool.
Bug: 45295
Change-Id: I3f47e1ae1f5c1415bde58a75385e4bf5f4b8fffc
Objective:
Refactor UI widgets, improve usability and accessibility of menus, general cleanup and style improvements.
Extras:
Fixed documentation in a few other files to make descriptions of jQuery event arguments more consistent, classes inherit correctly, and made use of the @cfg functionality in jsduck.
Changes:
.docs/config.json
* Added window, HTMLDocument, HTMLElement, DocumentFragment and XMLHttpRequest to externals, so jsduck doesn't throw warnings when they are used
demos/ve/index.php, modules/ve/test/index.php, VisualEditor.php
* Moved widgets above tools (since tools use widgets)
demos/ve/index.php
* Refactored widget initialization to use options
* Renamed variables to match widget names
ve.init.mw.ViewPageTarget.css
* Adjusted text sizes to make widgets work normally
* Added margins for buttons in toolbar (since button widgets
don't have any)
* Removed styles for init buttons (button widgets now)
ve.init.mw.ViewPageTarget.js
* Switched to using button widgets (involved moving things around
a bit)
ve.ui.LinkInspector.js, ve.ui.MWLinkInspector.js
* Renamed static property "inputWidget" to
"linkTargetInputWidget" to better reflect the required base class
for the properties value
icons.ai, check.png, check.svg
* Added "check" icon, used in menu right now to show which item
is selected
ve.ui.Icons-raster.css, ve.ui.Icons-vector.css
* Added check icon
* Removed :before pseudo selectors from most of the icon classes (not need by button tool anymore, makes them more reusable now)
ve.ui.Tool.css
* Adjusted drop down tool styles so menu appears below, instead
of on top, of the label
* Adjusted paragraph font size to better match actual content
* Updated class names to still work with menu widget changes
(items are their own widgets now)
* Updated selectors as per changes in the structure of button tools
ve.ui.Widget.css
* Added styles for buttons and menu items
* Adjusted menu styles
ve.ui.*ButtonTool.js
* Added config options argument passthrough
ve.ui.ButtonTool.js
* Moved var statement to the top inside constructor
* Switched to using "a" tag to get cross-browser :active support
* Added icon to inside of button to make icon styles more reusable
* Removed disabled support (now provided by widget parent class)
ve.ui.FormatDropDownTool.js
* Updated options initialization to construct menu item objects
* Modified handling of items to account for changes in menu and
item classes
* Optimized onUpdateState method a bit, adding early exit to
inner loop
ve.ui.ButtonTool.js, ve.ui.DropdownTool.js, ve.ui.Context.js,
ve.ui.Frame, ve.ui.Tool.js, ve.ui.Widget.js
* Added chain ability to non-getter methods
ve.ui.DropdownTool.js
* Removed items argument to constructor
* Updated code as per changes in menu class
* Fixed inconsistent naming of event handler methods
* Removed item event handling (now handled by items directly)
* Made use of this.$$ to ensure tool works in other frames
ve.ui.Tool.js
* Made tools inherit from widget
* Moved trigger registry event handler to a method
ve.ui.Context.js
* Switched from using menu to contain toolbar to a simple wrapper
ve.ui.js
* Added get$$ method, a convenience function for binding jQuery
to a specific document context
ve.ui.*Widget.js
* Switched to using a config options object instead of individual arguments
* Added options
* Factored out flags and labels into their own classes
* Refactored value setting methods for inputs
ve.ui.MenuWidget.js, ve.ui.MenuItemWidget.js
* Broke items out into their own classes
* Redesigned API
* Updated code that uses these classes
* Added support for keyboard interaction
* Made items flash when selected (delaying the hiding of the menu for 200ms)
ve.ui.LinkTargetInputWidget.js, ve.ui.MWLinkTargetInputWidget
* Refactored annotation setting methods
Change-Id: I7769bd5a5b79f1ab36f258ef9f2be583ca503ce6
Objective: Simplify the registration and use of triggers
Changes:
* Renamed ve.Command to ve.Trigger
* Renamed command demo to trigger demo
* Removed language prefixing of triggers
* Generating trigger tooltips rather than hard-coding them in i18n
* Added documentation to clarify that only 'mac' and 'pc' are supported platforms, and how the default is chosen
* Simplified trigger registry's register command
* Updated trigger registrations
Change-Id: Ibab6ad5b5c86f24707f064967dc2119a81125392
Objective:
* Put command shortcuts in button title attributes. (Bug 42919)
* Provide a registry for platform specific command triggers and their
corresponding i18n messages. (Bug 44012)
* Enable loading of triggers after ve.Surface is created. (lazy load)
Changes:
VisualEditor.i18n.php
* Add default trigger i18n messags for mac and pc system platforms
VisusalEditor.php, demos/ve/index.php
* Add links to files
ve.init.mw.Platform.js
* Define getUserLanguage and getSystemPlatform methods.
ve.init.sa.Platform.js
* Define getUserLanguage and getSystemPlatform methods.
ve.init.Platform.js
* Define abstract methods: getUserLangauge, getSystemPlatform
ve.ui.BoldBUttonTool.js, ve.ui.IndentButtonTool.js, ve.ui.ItalicButtonTool.js,
ve.ui.LinkButtonTool.js, ve.ui.OutdentButtonTool.js, ve.ui.RedoButtonTool.js,
ve.ui.UndoButtonTool.js
* Add registration for command triggers.
ve.Surface.js
* Methodize loading of triggers.
* Bind register event to ve.triggerRegistry to allow lazy loading of triggers.
ve.ui.Tool.js
* Init pre-registered tooltip messages.
* Update tool titles when new triggers are loaded.
ve.CommandRegistry.js
* Remove command registration ( moved to buttons themselves )
ve.TriggerRegistry.js
* New class for registering triggers.
ve.init.mw.ViewPageTarget.js
* Changed instance of unindent command to outdent.
Change-Id: Id8580a3f81aac751db0b7482422a73912648dfed
* Made method descriptions imperative: "Do this" rather than "Does this"
* Changed use of "this object" to "the object" in method documentation
* Added missing documentation
* Fixed incorrect documentation
* Fixed incorrect debug method names (as in those VeDmClassName tags we add to functions so they make sense when dumped into in the console)
* Normalized use of package names throughout
* Normalized class descriptions
* Removed incorrect @abstract tags
* Added missing @method tags
* Lots of other minor cleanup
Change-Id: I4ea66a2dd107613e2ea3a5f56ff54d675d72957e
Objectives:
* Make the link inspector easier to use
* Try to resolve a few bugs (bug 43841, bug 43063, bug 42986)
* Stop using jquery.multiSuggest (which didn't really understand annotations)
* Better divide MediaWiki specifics from generic implementations
Changes:
VisualEditor.php, modules/ve/test/index.php, demos/ve/index.php
* Updated links to files
ve.Registry
* Fixed mistake where registry was initialized as an array - this didn't cause any errors because you can add arbitrary properties to an array and use it like any other object
ve.Factory
* Removed duplicate initialization of registry property
* Added entries property, which is an array that's appended to for tracking the order of registrations
ve.CommandRegistry
* Added mwLink command which opens the mwLink inspector
ve.ui.TextInputWidget
* Added basic widget class for text inputs
ve.ui.TextInputMenuWidget
* Added widget that provides a menu of options for a text input widget
ve.ui.MWLinkTargetInputWidget
* Added MediaWiki specific link target widget
ve.ui.MenuWidget
* Converted ve.ui.Menu into a widget
* Moved the body of onSelect to onMouseUp
ve.ui.LinkTargetInputWidget
* Added link target widget which adds link annotation functionality to a normal text input
ve.ui.InputWidget
* Added generic input widget which emits reliable and instant change events and synchronizes a value property with the DOM value
ve.ui.Widget
* Added base widget class
* Widgets can be used in any frame
ve.ui.Tool
* Fixed line length issues
ve.ui.InspectorFactory
* Made use of new entries property for factories to select the most recently added inspector if more than one match a given annotation
ve.ui.Inspector
* Added auto-focus on the first visible input element on open
* Moved afterClose event to after re-focus on document on close
* Added documentation
ve.ui.Frame
* Adjusted documentation
* Added binding of $$ to the frame context so it can be passed around
* Added documentation
ve.ui.Context
* Added ve.ui.Widget.css to iframes
* Updated code as per moving of ve.ui.Menu to ve.ui.MenuWidget
* Removed unused positionBelowOverlay method
* Added CSS settings to set overlay left and width properties according to context size
* Added documentation
ve.ui.DropdownTool
* Updated code as per moving of ve.ui.Menu to ve.ui.MenuWidget
ve.ui.FormatDropdownTool
* Added documentation
ve.ui.MWLinkButtonTool
* Added MediaWiki specific version of ve.ui.LinkButtonTool, which opens the mwLink inspector
ve.ui.Widget.css
* Added styles for all widgets
ve.ui.Tool.css, ve.init.sa.css, ve.init.mw.ViewPageTarget.css, ve.init.mw.ViewPageTarget-apex.css
* Updated code as per moving of ve.ui.Menu to ve.ui.MenuWidget
ve.ui.Menu.css
* Deleted (merged into ve.ui.Widget.css)
ve.ui.Menu.css
* Deleted suggest styles (no longer used)
pending.gif, pending.psd
* Added diagonal stripe animation to indicate a pending request to the API
ve.ui.MWLinkInspector
* Added MediaWiki specific inspector which uses MediaWiki specific annotations and widgets
ve.ui.LinkInspector
* Removed mw global hint (not needed anymore)
* Switched from comparing targets to annotations (since the target text is ambiguous in some situations)
* Switched to using input widget, which is configured using a static property
* Removed use of jquery.multiSuggest
* Moved MediaWiki specifics to their own class (ve.ui.MWLinkInspector)
ve.init.mw.ViewPageTarget
* Added MediaWiki specific toolbar and command options
Change-Id: I859b5871a9d2f17d970c002067c8ff24f3513e9f
See CODING.md for how to run it.
Mistakes fixed:
* Warning: Unknown type function
-> Function
* Warning: Unknown type DOMElement
-> HTMLElement
* Warning: Unknown type DOM Node
-> HTMLElement
* Warning: Unknown type Integer
-> Mixed
* Warning: Unknown type Command
-> ve.Command
* Warning: Unknown type any
-> number
* Warning: Unknown type ve.Transaction
-> ve.dm.Transaction
* Warning: Unknown type ve.dm.AnnotationSet
-> ve.AnnotationSet
* Warning: Unknown type false
-> boolean
* Warning: Unknown type ve.dm.AlienNode
ve.dm doesn't have a generic AlienNode like ve.ce
-> Unknown type ve.dm.AlienInlineNode|ve.dm.AlienBlockNode
* Warning: Unknown type ve.ve.Surface
-> ve.ce.Surface
* ve.example.lookupNode:
-> Last @param should be @return
* ve.dm.Transaction.prototype.pushReplace:
-> @param {Array] should be @param {Array}
* Warning: ve.BranchNode.js:27: {@link ve.Node#hasChildren} links to non-existing member
-> (removed)
* Warning: ve.LeafNode.js:21: {@link ve.Node#hasChildren} links to non-existing member
-> (removed)
Differences fixed:
* Variadic arguments are like @param {Type...} [name]
instead of @param {Type} [name...]
* Convert all file headers from /** to /*! because JSDuck tries
to parse all /** blocks and fails to parse with all sorts of
errors for "Global property", "Unnamed property", and
"Duplicate property".
Find: \/\*\*([^@]+)(@copyright)
Replace: /*!$1$2
* Indented blocks are considered code examples.
A few methods had documentation with numbered lists that were
indented, which have now been updated to not be intended.
* The free-form text descriptions are parsed with Markdown,
which requires lists to be separated from paragraphs by an
empty line.
And we should use `backticks` instead of {braces} for inline
code in text paragraphs.
* Doc blocks for classes and their constructor have to be
in the correct order (@constructor, @param, @return must be
before @class, @abstract, @extends etc.)
* `@extends Class` must not have Class {wrapped}
* @throws must start with a {Type}
* @example means something else. It is used for an inline demo
iframe, not code block. For that simply indent with spaces.
* @member means something else.
Non-function properties are marked with @property, not @member.
* To create a link to a class or member, in most cases the name
is enough to create a link. E.g. Foo, Foo.bar, Foo.bar#quux,
where a hash stands for "instance member", so Foo.bar#quux,
links to Foo.bar.prototype.quux (the is not supported, as
"prototype" is considered an implementation detail, it only
indexes class name and method name).
If the magic linker doesn't work for some case, the
verbose syntax is {@link #target label}.
* @property can't have sub-properties (nested @param and @return
values are supported, only @static @property can't be nested).
We only have one case of this, which can be worked around by
moving those in a new virtual class. The code is unaltered
(only moved down so that it isn't with the scope of the main
@class block). ve.dm.TransactionProcessor.processors.
New:
* @mixins: Classes mixed into the current class.
* @event: Events that can be emitted by a class. These are also
inherited by subclasses. (+ @param, @return and @preventable).
So ve.Node#event-attach is inherited to ve.dm.BreakNode,
just like @method is.
* @singleton: Plain objects such as ve, ve.dm, ve.ce were missing
documentation causing a tree error. Documented those as a
JSDuck singleton, which they but just weren't documented yet.
NB: Members of @singleton don't need @static (if present,
triggers a compiler warning).
* @chainable: Shorthand for "@return this". We were using
"@return {classname}" which is ambiguous (returns the same
instance or another instance?), @chainable is specifically
for "@return this". Creates proper labels in the generated
HTML pages.
Removed:
* @mixin: (not to be confused with @mixins). Not supported by
JSDuck. Every class is standalone anyway. Where needed marked
them @class + @abstract instead.
Change-Id: I6a7c9e8ee8f995731bc205d666167874eb2ebe23
* Moved to tool specific configuration to static properties (left tool instance specific stuff in the constructors)
* Added documentation for tool configurations
* Centralized typePattern matching for inspectors
Change-Id: Ieacf61b320c10fd37ea69a05e543313fa990b403
* Rewrite of all tools, dramatically simplifiying them and decreasing
duplication
* Tools are now created using a tool factory instead of
a make-shift facility built into the toolbar
* All UI object have a surface or a toolbar reference instead of a
surface view
Change-Id: I589ecba36bf715b452d03c8fd5c0547dc3c1dc61
Rather than each tool requesting annotations, and nodes pertaining to selection,
Emitted event supplies annotations and nodes to each tool's update method.
Using select vs. of traverseLeafNodes for code optimization.
Better documentation for updateTools()
Removed unneeded code.
Change-Id: I7c0baa1cc0f7fb731d6e28b175a76e931e9e2961
* For the most common case:
- replace ve.extendClass with ve.inheritClass (chose slightly
different names to detect usage of the old/new one, and I
like 'inherit' better).
- move it up to below the constructor, see doc block for why.
* Cases where more than 2 arguments were passed to
ve.extendClass are handled differently depending on the case.
In case of a longer inheritance tree, the other arguments
could be omitted (like in "ve.ce.FooBar, ve.FooBar,
ve.Bar". ve.ce.FooBar only needs to inherit from ve.FooBar,
because ve.ce.FooBar inherits from ve.Bar).
In the case of where it previously had two mixins with
ve.extendClass(), either one becomes inheritClass and one
a mixin, both to mixinClass().
No visible changes should come from this commit as the
instances still all have the same visible properties in the
end. No more or less than before.
* Misc.:
- Be consistent in calling parent constructors in the
same order as the inheritance.
- Add missing @extends and @param documentation.
- Replace invalid {Integer} type hint with {Number}.
- Consistent doc comments order:
@class, @abstract, @constructor, @extends, @params.
- Fix indentation errors
A fairly common mistake was a superfluous space before the
identifier on the assignment line directly below the
documentation comment.
$ ack "^ [^*]" --js modules/ve
- Typo "Inhertiance" -> "Inheritance".
- Replacing the other confusing comment "Inheritance" (inside
the constructor) with "Parent constructor".
- Add missing @abstract for ve.ui.Tool.
- Corrected ve.FormatDropdownTool to ve.ui.FormatDropdownTool.js
- Add function names to all @constructor functions. Now that we
have inheritance it is important and useful to have these
functions not be anonymous.
Example of debug shot: http://cl.ly/image/1j3c160w3D45
Makes the difference between
< documentNode;
> ve_dm_DocumentNode
...
: ve_dm_BranchNode
...
: ve_dm_Node
...
: ve_dm_Node
...
: Object
...
without names (current situation):
< documentNode;
> Object
...
: Object
...
: Object
...
: Object
...
: Object
...
though before this commit, it really looks like this
(flattened since ve.extendClass really did a mixin):
< documentNode;
> Object
...
...
...
Pattern in Sublime (case-sensitive) to find nameless
constructor functions:
"^ve\..*\.([A-Z])([^\.]+) = function \("
Change-Id: Iab763954fb8cf375900d7a9a92dec1c755d5407e
* Switched a lot of classes from es-* to ve-ui-*
* Removed all the DOM structure left over from the old sandbox demo
* Got rid of transparent backgrounds
* Added menu font-size rule to stand-alone target
* Moved some rules around that were in the wrong places
* Got rid of some unused/unneeded methods in the mw target (attach and detach surface methods)
* Added active class to context icon with shallower shadow effect so it doesn't break your spacial perception when you click on it
* Renamed the iframe and iframe wrapper elements so it's easier to see where they came from
* Removed unused CSS rules
* Fixed some uses of prop( 'class', … ) to addClass
Change-Id: I54a660ca0baf0baa4463faca7a1edcf648130b6b
Stack traces, line numbers, etc. All the approaches I've seen are bad hacks. This is the best way to go.
Change-Id: Ib12e9d2ecfe610bcc89d046005e35cc13efa3d99
Throwing strings is bad because it doesn't include a lot of important
information that an error object does, such as a stack trace or where
the error was actually thrown from.
ve.Error inherits directly from Error. In the future we may create
more specific subclasses and/or do custom stuff.
Some interesting reading on the subject:
* http://www.devthought.com/2011/12/22/a-string-is-not-an-error/
Change-Id: Ib7c568a1dcb98abac44c6c146e84dde5315b2826
This license change is aimed at maximizing the reusability of this code
in other projects. VisualEditor is more than just an awesome editor for
MediaWiki, it's the new editor for the entire internet.
Added license and author files, plus mentions of the license to all
VisualEditor PHP, JavaScript and CSS files. Parser files have not been
modified but are effectively re-licensed since there's no overriding
license information. 3rd party libraries are not changed, but are all
already MIT licensed.
Change-Id: I895b256325db7c8689756edab34523de4418b0f2
