Commit graph

60 commits

Author SHA1 Message Date
Trevor Parscal 7297108a48 Make toolbars, toolgroups and tools toolFactory independent
Objectives:
* Pass a specific tool factory into a toolbar, allowing it to be used
  with different collections of tools and not depend on the
  ve.ui.toolFactory global
* Move syntax highlight editor tools to their own factory

Change-Id: I307bf180bd6817bc044bc474a77861e13f431ddb
2013-10-03 21:49:36 +00:00
Ed Sanders e6f48c5c93 'Config' -> 'Configuration' in all comments
Because the former isn't a real word.

Change-Id: Ie6ed15f9e390b357bbaa768b57f3c3fd7cf21181
2013-09-25 11:23:16 +01:00
Ed Sanders 4d1d632ebd Extend SurfaceToolbar into TargetToolbar
Toolbars may want to control the target as well as the surface (spoiler alert!).
The new TargetToolbar has a pointer to its target as well as its surface.

Change-Id: I928316d9e23ac3f3de3e76c34ef0ac3d27855ab3
2013-09-17 17:05:01 +01:00
Trevor Parscal 8dfbc5baa5 Make tools generic and add fancy tool groups
Objectives:

* Got rid of mw prefixing in tools, inspectors and dialogs
* Simplify tool classes so they can be generically used as items in bars, lists and menus
* Add support for a catch-all toolbar group
* Simplify tool registration, leaning on tool classes' static name property
* Move default commands to command registry
* Move default triggers to trigger registry
* Get language tool working in standalone

Change-Id: Ic97a636f9a193374728629931b6702bee1b3416a
2013-09-03 11:27:39 -07:00
Trevor Parscal 332e31fb00 Toolbar API
Objectives:

* Make it possible to add items to toolbars without having to have all
  toolbars know about the items in advance
* Make it possible to specialize an existing tool and have it be used
  instead of the base implementation

Approach:

* Tools are named using a path-style category/id/ext system, making them
  selectable, the latter component being used to differentiate extended
  tools from their base classes, but is ignored during selection
* Toolbars have ToolGroups, which include or exclude tools by category or
  category/id, and order them by promoting and demoting selections of
  tools by category or category/id

Future:

* Add a way to place available but not yet placed tools in an "overflow"
  group
* Add a mode to ToolGroup to make the tools a multi-column drop-down style
  list with labels so tools with less obvious icons are easier to identify
  - and probably use this as the overflow group

Change-Id: I7625f861435a99ce3d7a2b1ece9731aaab1776f8
2013-08-20 16:08:26 -07:00
Trevor Parscal a51fbbb300 Don't change config during toolbar setup
Problem: When the toolbar is created twice with the same config object,
the second time around the tools are still bound to the old surface

Reason: The tool config is overwritten such that symbolic names of tools
are replaced with instances of tools, bound to a specific surface. The
second time around, the creation fails (silently in a try-catch) and then
the already translated list of tools is used to create a new toolbar
filled with old tools still bound to the wrong surface.

Solution: Leave the config object alone, and instead build a new list of
tool instances while iterating through tool names.

Bonus: Don't fail silently. Using a try-catch to detect whether a
requested tool is supported masks other errors, and is evil. Instead,
just do a lookup and skip tools in which the lookup's result is falsey.

Change-Id: Ic43ec29173e556592bb3db9399ff83787e0a6857
2013-08-19 23:41:22 +00:00
Trevor Parscal 2717ea1645 Add ve.ui.ToolGroup and use within toolbar setup
Objectives:

* Use a class for toolbar groups to add more functionality later
* Rename addTools method to setup

Changes:

*.php
* Add link to new file
* Move ui element classes up for more general use

ve.init.mw.ViewPageTarget.js, ve.init.sa.Target.js, ve.ui.Context.js,
ve.ui.SurfaceWidget.js
* Update use of addTools method

ve.ui.Tool.css, ve.ui.Toolbar.css
* Move styles between sheets

ve.ui.Toolbar.js
* Rename addTools to setup
* Use ve.ui.ToolGroup objects when building tools

ve.ui.ToolGroup.js
* New class, encapsulates tools

Change-Id: Ic3a643634a80a8ac7d6f6f47f031d001c7efaee7
2013-08-07 05:08:20 +00:00
Trevor Parscal a226716d70 Split ve.ui.Toolbar and ve.ui.SurfaceToolbar
Objective:

* Make it possible to make a toolbar without a surface

Changes:

*.php
* Links to new file

ve.ui.Toolbar.js, ve.ui.SurfaceToolbar.js
* Split toolbar into generic and surface specific classes

*.js
* Update symbol names

Change-Id: Ice063a2fb67b5ce5155cdc96a0d47af49eee48cb
2013-08-02 14:33:25 -07:00
Timo Tijhof 19a705de87 ve.ui.Toolbar: Use closure instead of ve.bind for event handlers
Code speaks for itself, see also bug 52441.
Though not introduced by 14343c7bf7, that made the bug worse.

Bug: 52441
Change-Id: Ie2b80b22df03eb563de8812a47fb25152527e786
2013-08-02 09:36:43 +02:00
Timo Tijhof c9cd496fdc ve.ui.Toolbar: Emit position event on toolbar instead of surface
mw.ViewPageTarget is currently getting events from both the
platform target toolbar and context menu toolbar because the
event is emitted from within the toolbar to the surface.

Instead we're now emitting it on the toolbar itself and it is up
to the binder to access the correct one and listen to its events.

Bug: 52317
Change-Id: Ibd8053768e82b1df91081bd77a172628ea855db7
2013-07-31 21:59:30 +00:00
Timo Tijhof 14343c7bf7 ve.ui.Toolbar: Refactor floating logic for performance
== Renamed methods ==

* enableFloating  -> enableFloatable
* disableFloating -> disableFloatable
* setPosition     -> float
* resetPosition   -> unfloat

== Scroll and resize event ==

Timeline for scroll event reduced from about half a dozen
"Recalculate style" and various forced "Paint" down to 0.

New timeline for scroll is clean (for me: from ~35 to ~59 fps):
* 1 Event (scroll)
* 1 Composite Layer

The composite layer action is the browser changing the viewport
to a different portion of the document drawing. Exactly the one
thing a simple scroll should do.

Timeline for resize event is still pretty crowded and low fps,
but it has improved. Further improvement would likely be around
using requestAnimation and going outside ve.ui.Toolbar.

== Changes ==

* New: ve.ui.Toolbar#initialize.
  Similar to what surface has. Users of Toolbar should decide
  whether to call enableFloatable, append it to the DOM at some
  point and then call initialize() once.

* Don't compute offset() every time.
  Eliminated by doing it once in #initialize. These 'top' and
  'left' offsets do not change.

* Don't compute outerWidth() and $window.width() every time.
  Reduced by doing it once in #initialize to compute the 'right'
  offset. Updating it only on resize.

* Don't set 'top' every time.
  This is already in the stylesheet. It was never set to anything
  else so the abstraction for it in #float has been removed.
  This also made it obvious that code for "ve-ui-toolbar-bottom"
  was unused and left behind. Tha class was only ever being
  removed from something (never added).
  The one addClass call for it was in a condition that is always
  false ("if top > 0").

* Don't set 'left' every time.
  Eliminated by doing it once in #float.

* Don't set 'right' every time.
  Reduced by no longer doing it on scroll. Done once in #float,
  and on resize after computing the new value for it.

* Remove no-op style operations.
  Wrapped methods in if-floatable, if-floated etc. to reduce a
  fair amount of easily avoided re-paint overhead.

* Avoid double re-paint in mw.ViewPageTarget.
  Though we prevent a lot of redundant re-paints now, whenever
  we do repaint we want to do it in 1 repaint instead of 2.

  ve.ui.Toolbar emits #toolbarPosition, which tells
  mw.ViewPageTarget to update toolbarTracker which would read
  the new $bar style properties and copy them over to the
  $toolbarTracker. However, this read operation forces the browser
  to do an immediate re-paint half-way just for $bar.

  Browsers only repaint when style properties are changed and
  JS has yielded. The exception to this is JS reading style
  properties: in that case the browser is forced to do those
  deferred repaints directly and reflect the new values.

  We can avoid this double repaint by passing the updated values
  as data instead of requiring the receiver to read the DOM (and
  thus a keep the deferred repaint). Now toolbarTracker can use
  them directly whilst the browser hasn't even repainted $bar yet.

== Clean up ==

* Redundant "border-radius: 0". This would reset something, but
  it never does. None of the things it inherits from set a
  border-radius. There is one subclass where toolbar is used
  with a border-radius (".ve-ui-surfaceWidget .ve-ui-toolbar-bar"
  sets a border-radius) which overrides this on purpose, so the
  default of 0 is redundant.

* Pattern "if ( .. ) addClass() else removeClass()" changed to:
  "toggleClass( , .. )"

Bug: 52014
Change-Id: I9be855148962eee068a77fe83e98eb20bbdcfeec
2013-07-30 01:47:54 +02:00
Rob Moen 31104d5788 Bind listener to keyup to capture arrows & better math for scrolling.
Listen to keyup to properly capture and respond to up and down arrows.
Rewrite calculation for scroll to better follow toolbar obscured cursor.

Bug: 48787
Change-Id: Ia46fb15ec9a8c07b3945b53a6545897ca23e59fa
2013-07-10 14:21:03 -07:00
Rob Moen a3e2507cfe Listen to keypress in ve.ce.surface.$ rather than window
Bug: 50538
Change-Id: Ifddf1bae1ee799ec3467a81c597702fc3f8be089
2013-07-03 22:28:17 +00:00
Rob Moen 1b9c077b83 If cursor is obscured by toolbar, on keypress scroll to cursor.
Bug: 48735
Change-Id: I45028ed2f13148332518badd5f4647d4d652884e
2013-06-27 14:09:22 -07:00
Ed Sanders bc04b08892 Position toolbar if loading with non-zero scroll offset
The scroll event doesn't fire if the page is already scrolled
when ve is loaded.

Change-Id: I5b5a2dff2055d9ff1a8b2a2e0016a3fe7aaf22fb
2013-06-26 13:16:20 +01:00
Ed Sanders 2352613b66 Code style fix: (X) -> ( X )
Change-Id: I7f3ac95621f70d9a89e70e9a51905673240cb51f
2013-06-24 18:51:59 +01:00
Timo Tijhof 85c4ebf373 mw.ViewPageTarget: Move save dialog out of toolbar tree
Bug: 49275
Bug: 49361
Change-Id: I2fbc4c8af943f1b096b8912191924961405d5c47
2013-06-20 14:16:50 -07:00
Ed Sanders 0072e66183 Always float toolbar to top of page, not last branch node
The check for the toolbar not overlapping the last branch node
'fixes' an edge case where the user has scrolled too far, and
the viewport is shorter than the last branch. A more common
problem caused by this is that if the last branch is very tall
the toolbar disappears whenever you scroll past it.

Bug: 48662
Change-Id: I1c7662f2b6f1ced6f80dec16c6ed69a8cc0c06c8
2013-06-19 18:44:38 +00:00
Ed Sanders dcbea2328c Code style fix: @return -> @returns
Change-Id: I26daca6313bf09055af8f980ba0065782257fd54
2013-06-17 11:50:24 +01:00
Ed Sanders 626a8c60f2 Make MW meta dialog experimental
Also remove the exception thrown when we try to add an non-existent
toolbar button, as it may just be experimental and not loaded.

Change-Id: I0a60421f45d7a3941c510defc60d1fbf9469e784
2013-05-24 17:53:06 +02:00
Ed Sanders 026af0d6c0 Remove unused toolbar group name.
Can't see why we'd need to style toolbar groups differently.

Change-Id: I0646b8cf37ab19e34a8ed2eb8558773365403610
2013-05-24 15:36:00 +00:00
Trevor Parscal 55b5f30edb ve.ui.Context: Add embedding feature
Objectives:

* Make the context menu display in the top right corner of the currently
  focused inspectable node (if there is one)
* Prevent clicking on anything to do with the toolbar or popup from doing
  anything at all, ever

Bonus:

* While we are using the clever feature in jQuery's on method which allows
  passing boolean false to cancel the event - may as well do that in
  ve.ui.Dialog as well

Changes:

ve.ui.FocusableNode
* Add ability to specify the focusable element so that dimensions can be
  derived from it

ve.ce.Surface
* Add quotes to object keys

ve.ui.MediaDialog
* Change association from being MW specific to handling images in general

ve.ui.Context
* Add embedded styles for context
* Add embedded mode, which is triggered when the context is a single
  focusable node, and the node is large enough to fit the context
  reasonably

ve.ui.Dialog
* Inline mousedown handler

ve.ui.Toolbar, ve.ui.PopupWidget
* Cancel stray mousedown events

Change-Id: I4b25d33f64b4bcb8a3ecfd7e9728f54a2d4886f3
2013-05-16 11:23:59 -07:00
Trevor Parscal a56e795f58 ve.Editor
Objectives:

* Split ve.Surface into ve.Editor and ve.ui.Surface
* Move actions, triggers and commands to ve.ui
* Move toolbar wrapping, floating, shadow and actions functionality to configurable options of ve.ui.Toolbar
* Make ve.ce.Surface and ve.ui.Surface inherit ve.Element and use this.$$ for iframe friendliness
* Make the toolbar separately initialized so it's possible to have a surface without one, as well as control where the toolbar is

Some change notes:

VisualEditor.php
* Added standalone module for mediawiki integrated unit testing

ve.ce.Surface.js
* Remove requirement to pass in an attached container to construct object
* Inherit ve.Element and use this.$$ instead of $
* Make getSelectionRect iframe friendly
* Move most of the initialize stuff to a new initialize method to be called after the surface is attached to the DOM

ve.init.mw.ViewPageTarget.js
* Merge toolbar functions into setup/teardown methods
* Add toolbar manually (since it's not added by the surface anymore)

ve.init.sa.Target.js
* Update new init procedure for editor, surface and toolbar separately
* Move toolbar floating stuff to ve.Toolbar

Change-Id: If91a9d6e76a8be8d1b5a2566394765a37d29a8a7
2013-05-15 10:39:12 -07:00
Trevor Parscal 7233ea8f1b EventEmitter API cleanup
The EventEmitter API we inherited from Node.js and then bastardized was
getting awkward and cumbersome. The number of uses of ve.bind was getting
out of control, and removing events meant caching the bound method in a
property. Many of the "features" of EventEmitter wasn't even being used,
some causing overhead, others just causing bloat. This change cleans up
how EventEmitter is used throughout the codebase.

The new event emitter API includes:
* emit - identical to the previous API, no longer throws an error if you
  emit error without a handler
* once - identical to the previous API, still introduces a wrapper* on -
  compatible with the previous API but has some new features
* off - identical to removeListener in the previous API
* connect - very similar to addListenerMethods but doesn't wrap callbacks
  in closures anymore
* disconnect - new, basically the opposite of addListenerMethods

Another change that is made in this commit is mixing in rather than
inheriting from EventEmitter.

Finally, there are changes throughout the codebase anywhere
connect/disconnect could be used.

Change-Id: Ic3085d39172a8a719ce7f036690f673e59848d3a
2013-05-02 15:05:59 -07:00
Ed Sanders 8b09dd7650 The resurrection
By removing the transaction listeners from surface fragments we
no longer have to make sure they are always manually destroyed.

In order to retain the functionality of having fragments update
with transactions elsewhere we keep a pointer to a place in the
new complete history stack in the surface. The complete history
stack records all transactions, even undone ones.

Whenever getRange is called we replay all transactions in the
complete history (in the correct order) since the fragment was
last updated.

Also in this commit:
* Updated Format/IndentationAction to test undo(). This increases
  coverage of surface fragment behaviour.
* .range is always accessed by .getRange now, although as an
  optimisation we can use the noCopy mode when we a sure the
  returned range will not be modified.
* Added undo test to .update (previously .onTransact)

Bug: 47343
Change-Id: I9e9818da1baa8319a3002f6d74fd1aad6732a8f5
2013-04-22 12:50:23 +01:00
Trevor Parscal 2419f7638c Death and/or destruction
So. It turns out that the design of SurfaceFragment is a little -
shall we say - wonky.

One of the best things about ve.dm.SurfaceFragment is its magical
ability to retain the intention of its range, even as transactions
are being processed. This ability is granted by each fragment
listening to the surface's change event, and responding by using
translateRange for each transaction that gets processed. Surface
fragments also have these clever methods that allow you to get a
fragment based on another, which makes adjusting the range easy to do
inline without having to manually store multiple fragments or
modifying the original.

This sounded good, and we seemed to all be convinced it was well
designed. But if you add a console.log( 'hello' ); to the first line
of ve.dm.SurfaceFragment.prototype.onTransact, and then start using
the bold tool on various selections of text, you will find that there
may indeed be a flaw. What you will probably realize is that the
number of times that particular line of code is being called is
disturbingly large, and increases each time you do just about anything
in the editor. What's going on? How did we get here? Read on…

It turns out that fragments are immortal. We create them, they listen
to the surface's transact event, we are done with them, but the
surface keeps on emitting events to the now long forgotten about
fragments. They continue to build up over time, never go out of scope,
and bloat the hell out of our program.

The same ended up being true of toolbars - and each time the context
menu fired up a new one the old one was left in limbo, still
responding to events, still taking up memory, but not being visible to
the user.

All of this immortality was causing strange and difficult to track
down problems. This patch fixes this by introducing a destroy method.
This method unbinds events, allowing the object to finally fall out of
scope and die - and more importantly stop receiving notifications of
changes.

This is a hack, but Ed will no doubt get this situation sorted out
properly by making fragments lazy-evaluate their selections by only
storing an identifier of the most recent transaction they were based
on, see bug 47343.

Change-Id: I18bb986001a44732a7871b9d79dc3015eedfb168
2013-04-18 13:56:20 -07:00
Trevor Parscal 504a1bafd0 Filter our zero-coverage updateState nodes
Added filter for nodes being passed to update state event - this
ensures that nodes are not being included with zero-length coverage, a
side effect of how selectNodes handles the virtual boundaries of text
nodes.

Change-Id: I6362114b57469b1108da11f94dc345a2bcdfc7cd
2013-04-14 02:50:01 +00:00
Ed Sanders fdf30b1ac8 Store data in LinearData class with an index-value store for objects
Created an IndexValueStore class which can store any object and return
an integer index to its hash map.

Linear data is now stored in ve.dm.LinearData instances. Two subclasses
for element and meta data contain methods specific to those data types
(ElementLinearData and MetaLinearData).

The static methods in ve.dm.Document that inspected data at a given
offset are now instance methods of ve.dm.ElementLinearData.

AnnotationSets (which are no longer OrderedHashSets) have been moved
to /dm and also have to be instantiated with a pointer the store.

Bug: 46320
Change-Id: I249a5d48726093d1cb3e36351893f4bff85f52e2
2013-03-30 10:06:34 +00:00
Timo Tijhof 4e64187beb Document and clean up events in all the things
* 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
2013-03-20 09:58:27 -07:00
Trevor Parscal 1572ec1569 Context, frame, window, dialog and inspector refactor
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
2013-03-14 00:03:31 +00:00
James D. Forrester 82114467f1 Bump copyright notice year range to -2013 over -2012
199 files touched. Whee!

Change-Id: Id82ce4a32f833406db4a1cc585674f2bdb39ba0d
2013-02-19 15:37:34 -08:00
Trevor Parscal 8d33a3de0d Major Documentation Cleanup
* 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
2013-01-16 15:37:59 -08:00
Timo Tijhof b11bbed7a6 JSDuck: Generated code documentation!
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
2013-01-05 01:16:32 +01:00
Trevor Parscal 2cc8f09204 Added contextChange event to surface model, replacing annotationChange
The contextChange event is fired when:
* Changes to insertion annotations
* Changes to which nodes are selected (start/end nodes have changed)
* Attributes have changed on any element (it's probably more expensive to detect if the changes are relevant than to just emit the event and let listeners do their thing)

This fixes most of the strange behavior with the toolbar not updating properly.

Change-Id: I5321d2e30bebd80987e0c779a9d8e061d8aa80bc
2012-11-26 15:57:02 -08:00
Trevor Parscal 238feeb881 Tools changes
* 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
2012-10-26 14:48:27 -07:00
Christian Williams ffefe63063 Insert Annotations
Change-Id: Ibc927730a668cdcea9c90fe4fc2cb3db4d20480e
2012-09-28 13:28:47 -07:00
Rob Moen 96d97c2aa8 Optimize UI tool state updates.
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
2012-09-19 11:16:10 -07:00
Catrope 74ed8e8766 Rename ve_foo_bar back to VeFooBar per discussion
Change-Id: Ibf6d4f08c4761727b2e3952a76e474c8221b38f9
2012-09-06 16:15:55 -07:00
Timo Tijhof b1d9c83b5d Object management: Object create/inherit/clone utilities
* 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
2012-09-06 15:29:31 -07:00
Timo Tijhof 71020f7175 Remainder JSHint fixes on modules/ve/*
[jshint]
ce/ve.ce.Surface.js: line 670, col 9, Too many var statements.
ce/ve.ce.Surface.js: line 695, col 6, Missing semicolon.
ce/ve.ce.Surface.js: line 726, col 22, Expected '===' and instead saw '=='.
ce/ve.ce.Surface.js: line 726, col 41, Expected '===' and instead saw '=='.
ce/ve.ce.Surface.js: line 733, col 13, Too many var statements.
ce/ve.ce.Surface.js: line 734, col 24, Expected '===' and instead saw '=='.
ce/ve.ce.Surface.js: line 1013, col 13, Too many var statements.
ce/ve.ce.Surface.js: line 1019, col 17, Too many var statements.
ce/ve.ce.Surface.js: line 1023, col 18, Too many ar statements.
ce/ve.ce.Surface.js: line 1027, col 13, Too many var statements.
dm/annotations/ve.dm.LinkAnnotation.js: line 70, col 52, Insecure '.'.
dm/ve.dm.Converter.js: line 383, col 29, Empty block.
dm/ve.dm.Converter.js: line 423, col 33, Empty block.

Commands:
 * jshint .
 * ack '(if|else|function|switch|for|while)\('
 * Sublime Text 2:
   Find(*): (if|else|function|switch|for|while)\(
   Replace: $1 (
 * ack '  ' -Q # double spaces, except in certain comments

Change-Id: I8e34bf2924bc8688fdf8acef08bbc4f6707e93be
2012-09-05 13:45:09 -07:00
Trevor Parscal d208ca9002 Cleaned up uses of jQuery to create and appendTo/prependTo
* Separated DOM changes from creation of elements
* Always using parsing for element creation with known attributes
* Always using attr or addClass for variable attributes

Change-Id: Id101f56594014786892d382d06c658f416224a9c
2012-08-29 18:43:48 +02:00
Trevor Parscal a52d7ff65a Finally getting rid of all the es-* stuff and other cruft
* 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
2012-08-28 13:59:35 -07:00
Timo Tijhof f06952f2f3 Refactor ve.js utilities and improve documentation
Refactor:
* ve.indexOf
  Renamed from ve.inArray.
  This was named after the jQuery method which in turn has a longer
  story about why it is so unfortunately named. It doesn't return
  a boolean, but an index. Hence the native method being called
  indexOf as well.

* ve.bind
  Renamed from ve.proxy.
  I considered making it use Function.prototype.bind if available.
  As it performs better than $.proxy (which doesn't use to the native
  bind if available). However since bind needs to be bound itself in
  order to use it detached, it turns out with the "call()" and
  "bind()"  it is slower than the $.proxy shim:
  http://jsperf.com/function-bind-shim-perf
  It would've been like this:
  ve.bind = Function.prototype.bind ?
      Function.prototype.call.bind( Function.prototype.bind ) :
      $.proxy;
  But instead sticking to ve.bind = $.proxy;

* ve.extendObject
  Documented the parts of jQuery.extend that we use. This makes it
  easier to replace in the future.

Documentation:
* Added function documentation blocks.
* Added annotations to  functions that we will be able to remove
  in the future in favour of the native methods.
  With "@until + when/how".
  In this case "ES5". Meaning, whenever we drop support for browsers
  that don't support ES5. Although in the developer community ES5 is
  still fairly fresh, browsers have been aware for it long enough
  that thee moment we're able to drop it may be sooner than we think.
  The only blocker so far is IE8. The rest of the browsers have had
  it long enough that the traffic we need to support of non-IE
  supports it.

Misc.:
* Removed 'node: true' from .jshintrc since Parsoid is no longer in
  this repo and thus no more nodejs files.
 - This unraveled two lint errors: Usage of 'module' and 'console'.
   (both were considered 'safe globals' due to nodejs, but not in
   browser code).

* Replaced usage (before renaming):
 - $.inArray -> ve.inArray
 - Function.prototype.bind -> ve.proxy
 - Array.isArray -> ve.isArray
 - [].indexOf -> ve.inArray
 - $.fn.bind/live/delegate/unbind/die/delegate -> $.fn.on/off

Change-Id: Idcf1fa6a685b6ed3d7c99ffe17bd57a7bc586a2c
2012-08-12 20:32:45 +02:00
Timo Tijhof 23c5b0d02c Make use of new jshint options
* Restricting "camelcase":
  No changes, we were passing all of these already

* Explicitly unrestricting "forin" and "plusplus"
  These are off by default in node-jshint, but some distro of jshint
  and editors that use their own wrapper around jshint instead of
  node-jshint (Eclipse?) may have different defaults. Therefor
  setting them to false explicitly. This also serves as a reminder
  for the future so we'll always know we don't pass that, in case
  we would want to change that.

* Fix order ("quotemark" before "regexp")

* Restricting "unused"
  We're not passing all of this, which is why I've set it to false
  for now. But I did put it in .jshintrc as placeholder.
  I've fixed most of them, there's some left where there is no clean
  solution.

* While at it fix a few issues:
 - Unused variables ($target, $window)
 - Bad practices (using jQuery context for find instead of creation)
 - Redundant /*global */ comments
 - Parameters that are not used and don't have documentation either
 - Lines longer than 100 chars @ 4 spaces/tab

* Note:
 - ve.ce.Surface.prototype.onChange takes two arguments but never
   uses the former. And even the second one can be null/undefined.
   Aside from that, the .change() function emits
   another event for the transaction already. Looks like this
   should be refactored a bit, two more separated events probably
   or one that is actually used better.
 - Also cleaned up a lot of comments, some of which were missing,
   others were incorrect
 - Reworked the contentChange event so we are no longer using the
   word new as an object key; expanded a complex object into multiple
   arguments being passed through the event to make it easier to work
   with and document

Change-Id: I8490815a508c6c379d5f9a743bb4aefd14576aa6
2012-08-10 02:50:30 +02:00
Trevor Parscal 255ce870e2 Puttin' em white-spacers where they aught'a be
function() -> function ()
){ -> ) {

Change-Id: I20a85fcf79d7aec64f7f2559e84c0279550d4eea
2012-08-06 18:52:19 -07:00
Trevor Parscal 13ccb68ae1 Cleanup - all jshint conditions are now met
Also:
* Removed a lot of dead code in Surface that was used in the now dead and gone sandbox.
* Changed from throwing an exception when calling getBalancedData on a range that produces no results from selectNodes to just returning []

Change-Id: Icf27094724eae5b90eec21308f9e26afe877e3ee
2012-08-03 18:56:04 -07:00
Timo Tijhof 88f6089952 Kranitor #1: On-boarding
'''Kranitor commits''' are commits by Krinkle with his janitor hat on.
Must never contain functional changes mixed with miscellaneous changes.

.gitignore:
 * Add .DS_Store to the ignore list so that browsing the directories
   on Mac OS X, will not add these files to the list of untracked
   files.
 * Fix missing newline at end of file

.jshintrc
 * raises -> throws
 * +module (QUnit.module)
 * remove 'Node' (as of node-jshint 1.7.2 this is now part of
   'browser:true', as it should be)

Authors:
 * Adding myself

MWExtension/VisualEditor.php
 * Fix default value of wgVisualEditorParsoidURL to not
   point to the experimental instance in WMF Labs.

Issues:
 * ve.ce.TextNode:
  - Fix TODO: Don't perform a useless clone of an already-jQuerified object.
  - Use .html() to set html content instead of encapsulating between
    two strings. This is slightly faster but more importantly safer,
    and prevents situations where the resulting jQuery collection
    actually contains 2 elements instead of 1, thus messing up
    what .contents() is iterating over.
 * ve.ce.Document.test.js
  - Fix: ReferenceError: assert is not defined
 * ve.dm.Document.test.js
  - Fix: ReferenceError: assert is not defined
 * ve.dm.Transaction.test.js
  - Fix: ReferenceError: assert is not defined
 * ve.dm.TransactionProcessor.test.js
  - Fix: ReferenceError: assert is not defined
 * ext.visualEditor.viewPageTarget
  - Missing dependency on 'mediawiki.Title'

Code conventions / Misc cleanup
 * Various JSHint warnings.
 * Whitespace
 * jQuery(): Use '<tag>' for element creation,
   use '<valid><xml/></valid>' for parsing
 * Use the default operator instead of ternary when the condition and
   first value are the same.
   x = foo ? foo : bar; -> x = foo || bar;
   Because contrary to some programming language (PHP...), in JS the
   default operator does not enforce a boolean result but returns the
   original value, hence it being called the 'default' operator, as
   opposed to the 'or' operator.
 * No need to call addClass() twice, it takes a space-separated list
   (jQuery splits by space and adds if needed)
 * Use .on( event[, selector], fn ) instead of the deprecated
   routers to it such as .bind(), .delegate() and .live().
   All these three are now built-in and fully compatible with .on()
 * Add 'XXX:' comments for suspicious code that I don't want to change
   as part of a clean up commit.
 * Remove unused variables (several var x = this; where x was not
   used anywhere, possibly from boilerplate copy/paste)
 * Follows-up Trevor's commit that converts test suites to the new
   QUnit format. Also removed the globals since we no longer use those
   any more.

Change-Id: I7e37c9bff812e371c7f65a6fd85d9e2af3e0a22f
2012-07-27 14:40:00 -07:00
Trevor Parscal a0f537712e Converted some instances of "var\t" to "var "
Change-Id: I02154e0381d5ae65b482bbcfc21ac93d0bf30d86
2012-07-19 17:24:54 -07:00
Trevor Parscal 6b34f09df2 Removed some whitespace
And added a license to some files that didn't have it yet

Change-Id: I3a7e60374d1198d369a0475b8f65f7415012a337
2012-07-19 14:25:16 -07:00
Trevor Parscal c40174b60c Changed to use MIT license per agreement with the VisualEditor team
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
2012-07-19 13:25:45 -07:00