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);