scripting:examples:code-completion

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
scripting:examples:code-completion [2018/06/13 14:31] – [Implementing Custom Code Completion] adminscripting:examples:code-completion [2018/06/18 00:47] (current) – [Usage of CompletionSet and CompletionItem] admin
Line 1: Line 1:
 ====== Implementing Custom Code Completion ====== ====== Implementing Custom Code Completion ======
-There is two ways of adding cusomt code completion to HippoEDIT: +There is two ways of adding custom code completion to HippoEDIT: 
-  * Implementing/registering own [[scripting:api:completion-provider|Completion provider]]. Recommended for most of use cases.+  * Implementing/registering own [[scripting:api:completion-provider:start|Completion provider]]. Recommended for most of use cases.
   * Subscribing on [[scripting:api:frame-events:on-completion|Application.onCompletion]] event, and showing completion list by yourself. Can be used if you want to use different UI for completion.    * Subscribing on [[scripting:api:frame-events:on-completion|Application.onCompletion]] event, and showing completion list by yourself. Can be used if you want to use different UI for completion. 
  
Line 10: Line 10:
   * [[scripting:api:frame-events:on-completion|Application.onCompletion]]   * [[scripting:api:frame-events:on-completion|Application.onCompletion]]
 ==== Methods ==== ==== Methods ====
-  * [[scripting:api:view:show-completion-list|View.ShowCompletionList]] - Show Completion list +  * [[scripting:api:text-view:show-completion-list|View.ShowCompletionList]] - Show Completion list 
-  * [[scripting:api:view:hide-completion-list|View.HideCompletionList]] - Hide Completion list+  * [[scripting:api:text-view:hide-completion-list|View.HideCompletionList]] - Hide Completion list
   * [[scripting:api:application:register-completion-provider|Applicaiton.RegisterCompletionProvider]] - Register code completion provider for syntax   * [[scripting:api:application:register-completion-provider|Applicaiton.RegisterCompletionProvider]] - Register code completion provider for syntax
   * [[scripting:api:application:un-register-completion-provider|Applicaiton.UnRegisterCompletionProvider]] - UnRegister code completion provider for syntax by instance   * [[scripting:api:application:un-register-completion-provider|Applicaiton.UnRegisterCompletionProvider]] - UnRegister code completion provider for syntax by instance
-  * [[scripting:api:application:completion-item|Applicaiton.CompletionItem]] - CompletionItem object constructor +  * [[scripting:api:script-application:completion-item|Applicaiton.CompletionItem]] - CompletionItem object constructor 
-  * [[scripting:api:application:completion-set|Applicaiton.CompletionSet]] - CompletionSet object constructor +  * [[scripting:api:script-application:completion-set|Applicaiton.CompletionSet]] - CompletionSet object constructor 
-  * [[scripting:api:application:completion-provider|Applicaiton.CompletionProvider]] - CompletionProvider object constructor+  * [[scripting:api:script-application:completion-provider|Applicaiton.CompletionProvider]] - CompletionProvider object constructor
 ==== Objects ==== ==== Objects ====
-  * [[scripting:api:completion-item|CompletionItem]] - to be added to CompletionSet +  * [[scripting:api:completion-item:start|CompletionItem]] - to be added to CompletionSet 
-  * [[scripting:api:completion-set|CompletionSet]] - used for displaing completion list +  * [[scripting:api:completion-set:start|CompletionSet]] - used for displaing completion list 
-  * [[scripting:api:completion-provider|CompletionProvider]] - implement to be called on building completion list+  * [[scripting:api:completion-provider:start|CompletionProvider]] - implement to be called on building completion list
  
 ===== Examples ===== ===== Examples =====
 ==== Completion using Completion Provider ==== ==== Completion using Completion Provider ====
-<file javascript code-completion.hejs>+Implementing a custom code completion using Completion Providers is a preferred way. You can register to call back only for specific syntax (and all other syntaxes inherited from it) and been called exactly at the moment when items are necessary, with minimum service code from your side, to give items back. In addition to that, usage of completion providers, allows HippoEDIT to call collection from different providers in parallel, that speedups general processing. 
 + 
 +<file javascript code-completion1.hejs>
 function onCompletionCollect(view, selection, set) { function onCompletionCollect(view, selection, set) {
- for (var i = 0; i < 10000; i++) + // if we are not inside of comments or documentation (Style.Text == 1 ), add our items to the list 
- set.Add(CompletionItem("Item2" + i, "variable"));+ if ( view.Document.GetStyleFromPos(selection.Start, true).Style.Text != 1 ) { 
 + // add item as string, ше would be displayed using default style 
 + set.Add("Variable1"); 
 + // or explicitely as completion item, if you want to better item customizing options 
 + // for example, assigning of special style, as below 
 + set.Add(CompletionItem("Variable1", "variable"));  
 + }
  return true;  return true;
 } }
  
 +// create and register completion provider to be used for JavaScript (id="js") and all syntaxes inherited from it
 Application.RegisterCompletionProvider("js", Application.CompletionProvider(onCompletionCollect)); Application.RegisterCompletionProvider("js", Application.CompletionProvider(onCompletionCollect));
 </file> </file>
  
 ==== Subscribing on onCompletion event  ==== ==== Subscribing on onCompletion event  ====
 +If you want to take full control over the completion process, you can subscribe to [[scripting:api:script-application:on-completion|onCompletion]] event and decide by yourself, what shall be the result of the event.\\
 +It can be a display of pre-filled Completion List or maybe, some special dialog or other UI. 
 +Be aware, that [[scripting:api:script-application:on-completion|onCompletion]] event called for any syntax, so, if you want to limit your code completion to only some specific programming language, you need to implement filtering in the event code by yourself. 
 +
 <file javascript code-completion2.hejs> <file javascript code-completion2.hejs>
 //////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////
Line 40: Line 53:
 Application.onCompletion = function(/*IRange*/ selection ) { Application.onCompletion = function(/*IRange*/ selection ) {
  if ( ActiveDocument.Syntax.IsInheritedFrom("js") ) {  if ( ActiveDocument.Syntax.IsInheritedFrom("js") ) {
- //var aSuggestions = ["Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10"]; +                // simplest, just pass a list of strings 
- //this.ShowCompletionList(selection, aSuggestions, false); + var aSuggestions = ["Item1", "Item2", "Item3", "Item4", "Item5"]; 
-  + this.ShowCompletionList(selection, aSuggestions, false); 
- var item5 = CompletionItem("Item5"); + return true; // event is handled 
- item5.Pattern = "%CurrentWord%(%|%)"; + } 
- item5.onDescription = function () { return this.Text + "() ..."; }; + // event is not handled, editor shall execute default logic 
- var item6 = CompletionItem("Item6"); + return false;   
- item6.onExpand = onExpand; +};</file> 
- item6.SubMenu = true; + 
- var aSuggestions = [CompletionItem("Item1", "js:methods"), CompletionItem("Item2", "variable"), CompletionItem("Item3"), CompletionItem("Item4", null, 11, 1, "Item4 Description", onExpand), item5, item6];  +If for some reason, in your plugin you cannot create JS like array, to pass a list of strings, you can pass it as [[scripting:api:completion-set:start|CompletionSet]]. 
-  +<file javascript code-completion2.hejs> 
- var completion_set = CompletionSet(aSuggestions); +//////////////////////////////////////////////////////////////////////// 
 +// Register Code Completion Handler 
 +Application.onCompletion = function(/*IRange*/ selection ) { 
 + if ( ActiveDocument.Syntax.IsInheritedFrom("js") ) { 
 + var completion_set = CompletionSet(); 
 +                // add as a string 
 +                completion_set.Add("Variable1"); 
 +                // add as a completion item. To refer style you can use relative syntax e.g. "variable",  
 +                // absolute "js:method" or at all pass Syntax object directly 
 +                completion_set.Add(CompletionItem("Variable2", "js:methods"));
  this.ShowCompletionList(selection, completion_set, true);  this.ShowCompletionList(selection, completion_set, true);
- return true; // processed + return true; // event is handled
  }  }
- + // event is not handled, editor shall execute default logic
  return false;    return false;  
 };</file> };</file>
  
 +==== Usage of CompletionSet and CompletionItem  ====
 +
 +When you construct [[scripting:api:completion-set:start|CompletionSet]], you can initialize an object by another [[scripting:api:completion-set:start|CompletionSet]] object (items would be copied) or by JS array with strings or CompletionItems.
 +<code javascript>
 +var completion_set = CompletionSet([
 +CompletionItem("Item1", "js:methods"), 
 +CompletionItem("Item2", "variable"), 
 +CompletionItem("Item3") 
 +]);
 +
 +// or
 +var completion_set2 = CompletionSet(["Item1", "Item2", "Item3"]);
 +</code>
 +
 +<note important>Do not mix strings and CompletionItems in the same set - it is not supported, and editor will use a type of first object</note>
 +
 +If you need more customization of your item displayed in CompletionList, there are several options you can use when constructing explicit [[scripting:api:completion-item:start|CompletionItem]] and passing it to the list.
 +
 +<code javascript>
 +var item5 = CompletionItem("Item5");
 +// custom insetion pattern, with code template syntax. 
 +// %CurrentWord% - inserted text
 +item5.Pattern = "%CurrentWord%(%|%)";
 +// custom description tooltip, shown when user scrolls over items and stops on one of them
 +item5.onDescription = function () { return this.Text + "() ..."; };
 +
 +function onExpand(view, selection) {
 + ActiveDocument.ReplaceText(selection, this.Text + "(...)");
 +}
 +
 +var item6 = CompletionItem("Item6");
 +// adding of custom handler, which is called when item is selected and inserted
 +// default, inserts item Text property
 +item6.onExpand = onExpand;
 +// add small arrow icon on the right of the item, indicating that items expands
 +item6.SubMenu = true;
 +
 +var aSuggestions = [
 +// add completion items with text and style, from which color/image/style of item shall be derived 
 +CompletionItem("Item1", "js:methods"), 
 +CompletionItem("Item2", "variable"), 
 +
 +// use default style for item display
 +CompletionItem("Item3"), 
  
 +// define an item witthout style, but with explicit image, subimage (public/protected/private)
 +// description and selection call-back
 +CompletionItem("Item4", null, 11, 1, "Item4 Description", onExpand), 
 +item5, 
 +item6]; 
 +</code>