From 4c7ef66128e09ae3800ee5d4ddea657fad3437c8 Mon Sep 17 00:00:00 2001 From: Joshua Granick Date: Tue, 10 Jul 2018 12:06:04 -0700 Subject: [PATCH] Some docs work --- .gitignore | 1 + docs/api/build.hxml | 27 +++-- src/lime/app/Application.hx | 17 +-- src/lime/app/Event.hx | 204 ++++++++---------------------------- 4 files changed, 75 insertions(+), 174 deletions(-) diff --git a/.gitignore b/.gitignore index a1c3ab8a9..de45c08c1 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ haxedoc.xml docs/api/*.xml docs/api/xml docs/api/pages* +docs/api/dump docs/.sass-cache docs/_site legacy/ndll/*/lime* diff --git a/docs/api/build.hxml b/docs/api/build.hxml index 3a91b4ab5..031d1bdf7 100644 --- a/docs/api/build.hxml +++ b/docs/api/build.hxml @@ -5,6 +5,7 @@ -swf-version 17.0 -D display -D doc_gen +-D lime-doc-gen -D lime_opengl ImportAll -lib lime @@ -19,6 +20,7 @@ ImportAll -D lime-cffi -D windows -D doc_gen +-D lime-doc-gen ImportAll -lib lime --no-output @@ -32,6 +34,7 @@ ImportAll -D lime-cffi -D mac -D doc_gen +-D lime-doc-gen ImportAll -lib lime --no-output @@ -45,21 +48,22 @@ ImportAll -D lime-cffi -D linux -D doc_gen +-D lime-doc-gen ImportAll -lib lime --no-output ---next +# --next --xml xml/Neko.xml --neko obj/docs --D display --D native --D lime-cffi --D doc_gen -ImportAll --lib lime ---no-output +# -xml xml/Neko.xml +# -neko obj/docs +# -D display +# -D native +# -D lime-cffi +# -D doc_gen +# ImportAll +# -lib lime +# --no-output --next @@ -70,6 +74,7 @@ ImportAll -D lime-cffi -D ios -D doc_gen +-D lime-doc-gen ImportAll -lib lime --no-output @@ -83,6 +88,7 @@ ImportAll -D lime-cffi -D android -D doc_gen +-D lime-doc-gen ImportAll -lib lime --no-output @@ -129,6 +135,7 @@ ImportAll -D display -D html5 -D doc_gen +-D lime-doc-gen -D lime_opengl ImportAll -lib lime diff --git a/src/lime/app/Application.hx b/src/lime/app/Application.hx index d09c9c096..35bc8b688 100644 --- a/src/lime/app/Application.hx +++ b/src/lime/app/Application.hx @@ -15,6 +15,14 @@ import lime.ui.Window; import lime.ui.WindowAttributes; import lime.utils.Preloader; + +/** + * The Application class forms the foundation for most Lime projects. + * It is common to extend this class in a main class. It is then possible + * to override "on" functions in the class in order to handle standard events + * that are relevant. + */ + @:access(lime.ui.Window) #if !lime_debug @@ -23,12 +31,6 @@ import lime.utils.Preloader; #end -/** - * The Application class forms the foundation for most Lime projects. - * It is common to extend this class in a main class. It is then possible - * to override "on" functions in the class in order to handle standard events - * that are relevant. - */ class Application extends Module { @@ -52,6 +54,9 @@ class Application extends Module { */ public var onUpdate = new EventVoid> (); + /** + * Dispatched when a new window has been created by this application + **/ public var onCreateWindow = new EventVoid> (); /** diff --git a/src/lime/app/Event.hx b/src/lime/app/Event.hx index 7310c611b..d6061fbc0 100644 --- a/src/lime/app/Event.hx +++ b/src/lime/app/Event.hx @@ -1,12 +1,22 @@ package lime.app; -#if macro -import haxe.macro.Context; -import haxe.macro.Expr; -import haxe.macro.Type; -using haxe.macro.Tools; -#end +/** + Event is a strictly-typed signals and slots implementation, used for + core event dispatching. + + For example: + + ``` + var event = new EventVoid> (); + event.add (function (value:Int):Void { trace (value); }); + event.dispatch (100); + + var event = new EventVoid> (); + event.add (function () { trace ("callback"); }); + event.dispatch (); + ``` +**/ #if (!macro && !display) @:genericBuild(lime._internal.macros.EventMacro.build()) @@ -21,6 +31,9 @@ using haxe.macro.Tools; class Event { + /** + * Whether the event was canceled during the previous dispatch + **/ public var canceled (default, null):Bool; @:noCompletion @:dox(hide) public var __listeners:Array; @@ -28,6 +41,9 @@ class Event { @:noCompletion private var __priorities:Array; + /** + * Creates a new Event instance + **/ public function new () { #if !macro @@ -40,6 +56,12 @@ class Event { } + /** + Adds a new event listener + @param listener A callback that matches the signature of the event + @param once Whether to receive an event dispatch only once, or each time it is fired + @param priority The priority for this listener, a higher priority will be dispatched sooner + **/ public function add (listener:T, once:Bool = false, priority:Int = 0):Void { #if !macro @@ -64,158 +86,9 @@ class Event { } - #if macro - private static function build () { - - var typeArgs; - var typeResult; - - switch (Context.follow (Context.getLocalType ())) { - - case TInst (_, [ Context.follow (_) => TFun (args, result) ]): - - typeArgs = args; - typeResult = result; - - case TInst (localType, _): - - Context.fatalError ("Invalid number of type parameters for " + localType.toString (), Context.currentPos ()); - return null; - - default: - - throw false; - - } - - var typeParam = TFun (typeArgs, typeResult); - var typeString = ""; - - if (typeArgs.length == 0) { - - typeString = "Void->"; - - } else { - - for (arg in typeArgs) { - - typeString += arg.t.toString () + "->"; - - } - - } - - typeString += typeResult.toString (); - typeString = StringTools.replace (typeString, "->", "_"); - typeString = StringTools.replace (typeString, ".", "_"); - typeString = StringTools.replace (typeString, "<", "_"); - typeString = StringTools.replace (typeString, ">", "_"); - - var name = "_Event_" + typeString; - - try { - - Context.getType ("lime.app." + name); - - } catch (e:Dynamic) { - - var pos = Context.currentPos (); - var fields = Context.getBuildFields (); - - var args:Array = []; - var argName, argNames = []; - - for (i in 0...typeArgs.length) { - - if (i == 0) { - - argName = "a"; - - } else { - - argName = "a" + i; - - } - - argNames.push (Context.parse (argName, pos)); - args.push ({ name: argName, type: typeArgs[i].t.toComplexType () }); - - } - - var dispatch = macro { - - canceled = false; - - var listeners = __listeners; - var repeat = __repeat; - var i = 0; - - while (i < listeners.length) { - - listeners[i] ($a{argNames}); - - if (!repeat[i]) { - - this.remove (cast listeners[i]); - - } else { - - i++; - - } - - if (canceled) { - - break; - - } - - } - - } - - var i = 0; - var field; - - while (i < fields.length) { - - field = fields[i]; - - if (field.name == "__listeners" || field.name == "dispatch") { - - fields.remove (field); - - } else { - - i++; - - } - - } - - fields.push ( { name: "__listeners", access: [ APublic ], kind: FVar (TPath ({ pack: [], name: "Array", params: [ TPType (typeParam.toComplexType ()) ] })), pos: pos } ); - fields.push ( { name: "dispatch", access: [ APublic ], kind: FFun ( { args: args, expr: dispatch, params: [], ret: macro :Void } ), pos: pos } ); - - Context.defineType ({ - - pos: pos, - pack: [ "lime", "app" ], - name: name, - kind: TDClass (), - fields: fields, - params: [ { name: "T" } ], - meta: [ { name: ":dox", params: [ macro hide ], pos: pos }, { name: ":noCompletion", pos: pos } ] - - }); - - } - - return TPath ( { pack: [ "lime", "app" ], name: name, params: [ TPType (typeParam.toComplexType ()) ] } ).toType (); - - } - #end - - + /** + Marks the event as canceled, and stops the current event dispatch + **/ public function cancel ():Void { canceled = true; @@ -223,6 +96,12 @@ class Event { } + /** + Dispatches a new event callback to all listeners. The signature for the + `dispatch` method depends upon the type of the `Event`. For example, an + `Event` of type `Int->Int->Void` will create a `dispatch` method that + takes two `Int` arguments, like `dispatch (1, 2);` + **/ public var dispatch:Dynamic; //macro public function dispatch (ethis:Expr, args:Array):Void { @@ -254,6 +133,11 @@ class Event { //} + /** + Checks whether a callback is a listener to this event + @param listener A callback that matches the signature of the event + @return Whether the callback is a listener + **/ public function has (listener:T):Bool { #if !macro @@ -269,6 +153,10 @@ class Event { } + /** + Removes an event listener + @param listener A callback that matches the signature of the event + **/ public function remove (listener:T):Void { #if !macro