1# 2# francy: Interactive Discrete Mathematics in GAP 3# 4 5#! @Chapter Francy Callbacks 6#! 7#! <C>Callbacks</C> are objects that hold a function, a list of arguments 8#! and a trigger event. <C>Callbacks</C> are used to execute GAP code 9#! from a remote client using the <C>Trigger</C> Operation. 10#! <P/> 11#! <C>Callbacks</C> can be added directly to <C>Menus</C> and/or <C>Shapes</C>. 12#! <P/> 13#! Please see Francy-JS for client implementation. 14 15 16#! @Section Categories 17#! In this section we show all Francy Callback Categories. 18 19#! @Description 20#! Identifies <C>Callback</C> objects. 21DeclareCategory("IsCallback", IsFrancyObject); 22 23#! @Description 24#! Identifies <C>RequiredArg</C> objects. 25DeclareCategory( "IsRequiredArg", IsFrancyObject); 26 27#! @Description 28#! Identifies <C>ArgType</C> objects. 29DeclareCategory("IsArgType", IsFrancyTypeObject); 30 31#! @Description 32#! Identifies <C>TriggerType</C> objects. 33DeclareCategory("IsTriggerType", IsFrancyTypeObject); 34 35 36#! @Section Families 37#! In this section we show all Francy Callback Families. 38 39#! @Description 40#! This Family identifies all <C>Callback</C> objects 41#! @Returns <C>CallbackFamily</C> 42BindGlobal("CallbackFamily", NewFamily("CallbackFamily", IsCallback)); 43 44 45#! @Section Representations 46#! In this section we show all Francy Callback Representations. 47 48#! @Description 49#! Checks whether an <C>Object</C> has a <C>Callback</C> internal representation. 50DeclareRepresentation("IsCallbackRep", IsComponentObjectRep, [], IsCallback); 51 52#! @Description 53#! Checks whether an <C>Object</C> has a <C>RequiredArg</C> internal representation. 54DeclareRepresentation("IsRequiredArgRep", IsComponentObjectRep, [], IsRequiredArg); 55 56#! @Description 57#! Checks whether an <C>Object</C> has a <C>ArgType</C> internal representation. 58DeclareRepresentation("IsArgTypeRep", IsComponentObjectRep, [], IsArgType); 59 60#! @Description 61#! Checks whether an <C>Object</C> has a <C>TriggerType</C> internal representation. 62DeclareRepresentation("IsTriggerTypeRep", IsComponentObjectRep, [], IsTriggerType); 63 64#! @Description 65#! Creates a new type for <C>Callback/C> objects. 66BindGlobal("CallbackObjectType", NewType(CallbackFamily, IsCallback and IsCallbackRep)); 67 68#! @Description 69#! Creates a new type for <C>RequiredArg/C> objects. 70BindGlobal("RequiredArgObjectType", NewType(CallbackFamily, IsRequiredArg and IsRequiredArgRep)); 71 72#! @Description 73#! Creates a new type for <C>ArgType/C> objects. 74BindGlobal("ArgTypeObjectType", NewType(CallbackFamily, IsArgType and IsArgTypeRep)); 75 76#! @Description 77#! Creates a new type for <C>TriggerType/C> objects. 78BindGlobal("TriggerTypeObjectType", NewType(CallbackFamily, IsTriggerType and IsTriggerTypeRep)); 79 80 81#! @Section Operations 82#! In this section we show all Francy Callback Operations. 83 84#! @Description 85#! Creates a Callback object that holds a function and args to be executed 86#! by a trigger based on a trigger type. 87#! <P/> 88#! **Please note, the Function must Return!** 89#! <P/> 90#! Examples: 91#! <P/> 92#! Create a simple <C>Callback</C> with no arguments: 93#! @InsertChunk Example_Create_Callback_1 94#! <P/> 95#! Create a <C>Callback</C> with one required argument of type string: 96#! @InsertChunk Example_Create_Callback_2 97#! <P/> 98#! Create a <C>Callback</C> with one known argument of type string: 99#! @InsertChunk Example_Create_Callback_3 100#! <P/> 101#! Create a <C>Callback</C> with one known argument and one required argument of type string: 102#! @InsertChunk Example_Create_Callback_4 103#! <P/> 104#! Create a <C>Callback</C> with one known argument and one required argument of type string and double click trigger Type: 105#! @InsertChunk Example_Create_Callback_5 106#! <P/> 107#! In order to see the output of the previous examples, we have to simulate the external call to <C>Trigger</C> operation: 108#! @InsertChunk Example_Create_Callback_6 109#! <P/> 110#! Create a Noop Callback, useful for Menu holders, where no function is required: 111#! @InsertChunk Example_Create_Callback_7 112#! <P/> 113#! @Arguments IsTriggerType, IsFunction, IsList(object) 114#! @Returns <C>Callback</C> 115DeclareOperation("Callback", [IsTriggerType, IsFunction, IsList]); 116 117#! @Description 118#! Creates an empty Callback object that does nothing. 119#! Useful to create menu holders. 120#! @Returns <C>Callback</C> 121DeclareOperation("NoopCallback", []); 122 123#! @Description 124#! Creates a <C>Callback</C> <C>RequiredArg</C>. 125#! <C>RequiredArg</C> is user input driven and required for the execution of a <C>Callback</C> 126#! This value will be provided by the user. 127#! @Arguments IsArgType, IsString(title) 128#! @Returns <C>RequiredArg</C> 129DeclareOperation("RequiredArg", [IsArgType, IsString]); 130 131#! @Description 132#! Triggers a callback function in GAP. 133#! Gets a JSON String object representation of the callback to execute. 134#! @Arguments IsString(JSON) 135#! @Returns the result of the execution of the <C>Callback</C> defined <C>Function</C> 136DeclareOperation("Trigger", [IsString]); 137 138#! @Description 139#! Adds a <C>RequiredArg</C> to a specific <C>Callback</C>. 140#! @Arguments IsCallback, [IsRequiredArg, List(IsRequiredArg)] 141#! @Returns <C>Callback</C> 142#DeclareOperation("Add", [IsCallback, IsRequiredArg]); 143 144#! @Description 145#! Removes a <C>RequiredArg</C> from a specific callback. 146#! @Arguments IsCallback, [IsRequiredArg, List(IsRequiredArg)] 147#! @Returns <C>Callback</C> 148#DeclareOperation("Remove", [IsCallback, IsRequiredArg]); 149 150 151#! @Section Globals 152#! In this section we show the Global Callback Francy Records for multi purpose. 153 154#! @Description 155#! This <C>rec</C> holds all the records registered within a <C>Menu</C> or <C>Shape</C>. 156#! This way it's possible to handle asynchronous calls to execute <C>Functions</C> 157#! @Returns <C>rec</C> of <C>Callback</C> 158BindGlobal("FrancyCallbacks", rec()); 159 160#! @Description 161#! This <C>rec</C> holds all the <C>ArgType</C> supported by Francy. 162#! The available <C>ArgType</C> specify the type of argument a <C>Callback</C> is expecting. 163#! @Returns <C>rec</C> of <C>ArgType</C>: <C>ArgType.SELECT</C>,<C>ArgType.INTEGER</C>,<C>ArgType.BOOLEAN</C>,<C>ArgType.STRING</C>,<C>ArgType.NUMBER</C> 164BindGlobal("ArgType", rec( 165 BOOLEAN := Objectify(ArgTypeObjectType, rec(value := "boolean")), 166 SELECT := Objectify(ArgTypeObjectType, rec(value := "select")), 167 STRING := Objectify(ArgTypeObjectType, rec(value := "text")), 168 NUMBER := Objectify(ArgTypeObjectType, rec(value := "number")) 169)); 170 171#! @Description 172#! This <C>rec</C> holds all the <C>TriggerType</C> supported by Francy. 173#! The available <C>TriggerType</C> specify the Type that will trigger this <C>Callback</C>. 174#! Supported types are: 175#! - <C>TriggerType.DOUBLE_CLICK</C> mouse event, double click, 176#! - <C>TriggerType.RIGHT_CLICK</C> mouse event, right click or context-menu, 177#! - <C>TriggerType.CLICK</C> mouse event, left click and **default for <C>Menu</C> <C>Callback</C>** 178#! @Returns <C>rec</C> of <C>TriggerType</C> 179BindGlobal("TriggerType", rec( 180 DOUBLE_CLICK := Objectify(TriggerTypeObjectType, rec(value := "dblclick")), 181 RIGHT_CLICK := Objectify(TriggerTypeObjectType, rec(value := "context")), 182 CLICK := Objectify(TriggerTypeObjectType, rec(value := "click")) 183)); 184 185 186#! @Section Attributes 187#! In this section we show the Francy Callback Attributes 188 189#! @Description 190#! A title on a required arg is used to ask the user what is expected from his input. 191#! @Returns <C>IsString</C> with the title of the object 192DeclareAttribute("Title", IsRequiredArg); 193InstallMethod(Title, "requiredArg", [IsRequiredArg], o -> o!.title); 194#! @Description 195#! Sets the title of the required arg. 196#! @Arguments IsRequiredArg, IsString 197InstallMethod(SetTitle, "requiredArg, string", [IsRequiredArg, IsString], function(o, s) o!.title := s; end); 198 199#! @Description 200#! A value on a required arg is the actual input to be passed to gap. 201#! These values are stored as <C>String</C> for convenience, 202#! even if the <C>ArgType</C> specified for the <C>RequiredArg</C> is another. 203#! Explicit conversion is required within the <C>Callback</C>function. 204#! @Returns <C>IsString</C> with the value of the object 205DeclareAttribute("Value", IsRequiredArg); 206InstallMethod(Value, "requiredArg", [IsRequiredArg], o -> o!.value); 207#! @Description 208#! Sets the value of the required arg. 209#! @Arguments IsRequiredArg, IsString 210InstallMethod(SetValue, "requiredArg, string", [IsRequiredArg, IsString], function(o, s) o!.value := s; end); 211 212#! @Description 213#! This will display a confirmation message before any callback is executed. 214#! @Returns <C>IsString</C> with the message oto be shown to the user prior to the callback execution 215DeclareAttribute("ConfirmMessage", IsCallback); 216InstallMethod(ConfirmMessage, "callback", [IsCallback], o -> o!.confirm); 217#! @Description 218#! Sets the value of the message to display to the user. 219#! @Arguments IsRequiredArg, IsString 220InstallMethod(SetConfirmMessage, "callback, string", [IsCallback, IsString], function(o, s) o!.confirm := s; end);