C++ SDK Reference  12.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguyVariable.h
Go to the documentation of this file.
1 
2 /*
3  * Copyright (C) 1992-2013 Boston Dynamics
4  * ALL RIGHTS RESERVED.
5  *
6  * These coded instructions, statements, and computer programs
7  * contain unpublished proprietary information of Boston Dynamics
8  * and are protected by Copyright Laws of the United States.
9  * They may not be used, duplicated, or disclosed in any form, in
10  * whole or in part, without the prior written consent from Boston
11  * Dynamics.
12  *
13  * RESTRICTED RIGHTS LEGEND
14  * Use, duplication, or disclosure by the government is subject
15  * to restrictions as set forth in FAR 52.227.19(c)(2) or
16  * subparagraph (c)(1)(ii) of the Rights in Technical Data and
17  * Computer Software clause at DFARS 252.227-7013 and/or in
18  * similar or successor clauses in the FAR, or the DOD or NASA
19  * FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the
20  * Commercial Computer Software--Restricted Rights at 48 CFR
21  * 52.227-19, as applicable. Unpublished-rights reserved under
22  * the Copyright Laws of the United States.
23  * Contractor/Manufacturer is:
24  * Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.
25  */
26 
27 /*********************************************************************
28  **
29  *t diguyVariable
30  **
31  *b Link against: libdiguy
32  */
33 
34 #ifndef __diguyVariable_H
35 #define __diguyVariable_H
36 
37 #ifdef SWIG
38 %module diguyVariable
39 #else
40 #define CPLUSPLUS_ONLY
41 #endif
42 
43 #ifdef CPLUSPLUS_ONLY
44 
45 class bdiScenarioVariable;
46 class diguyCharacter;
47 class diguyScenario;
48 class diguyVariable;
49 
50 #include <stdio.h> // for NULL
51 #include <diguy_constants.h>
52 #include <diguy_typedefs.h>
53 
54 #endif /* CPLUSPLUS_ONLY */
55 
56 #include <declspec_diguy.h>
57 
58 
59 /****************************************************************************/
60 class BDI_DECLSPEC_diguy diguyVariable
61 {
62 
63 public:
64 
65  /*l
66  *b Description:
67  **
68  ** Returns the name of the variable. This pointer will
69  ** never be NULL.
70  **
71  *b Returns:
72  **
73  ** name of the variable
74  **
75  *b Callable From:
76  **
77  *- - C++
78  *- - Script
79  */
80  const char* get_name();
81 
82  /*l
83  *b Description:
84  **
85  ** This function sets the name of this object.
86  **
87  *b Returns:
88  **
89  ** 0 on success, -1 on failure
90  **
91  *b Callable From:
92  **
93  *- - C++
94  *- - Script
95  */
96  int set_name(const char* name);
97 
98  /*l
99  *b Description:
100  **
101  ** Returns the type name of the object. This pointer will
102  ** never be NULL.
103  **
104  *b Returns:
105  **
106  ** type name of the object
107  **
108  *b Callable From:
109  **
110  *- - C++
111  *- - Script
112  */
113  const char* get_type_name();
114 
115  /*l
116  *b Description:
117  **
118  ** Returns the scenario that this variable belongs to. This
119  ** pointer will never be NULL. Note that if this variable
120  ** belongs to a character, a pointer to the scenario that the
121  ** character belongs to will be returned.
122  **
123  *b Returns:
124  **
125  ** pointer of type diguyScenario
126  **
127  *b Callable From:
128  **
129  *- - C++
130  *- - Script
131  */
132  diguyScenario* get_scenario();
133 
134  /*l
135  *b Description:
136  **
137  ** Returns the character that this variable belongs to, if any.
138  ** This pointer might be NULL is this variable is not a
139  ** character variable.
140  **
141  *b Returns:
142  **
143  ** pointer of type diguyCharacter; NULL if this variable is
144  ** not a character variable
145  **
146  *b Callable From:
147  **
148  *- - C++
149  *- - Script
150  */
151  diguyCharacter* get_character();
152 
153  /*l
154  *b Description:
155  **
156  ** Copies the contents of the passed variable.
157  **
158  *b Returns:
159  **
160  ** 0 on success, -1 on failure
161  **
162  *b Callable From:
163  **
164  *- - C++
165  *- - Script
166  */
167  int copy(diguyVariable* rhs);
168 
169  /*l
170  *b Description:
171  **
172  ** Returns the value of the variable as an integer.
173  **
174  *b Returns:
175  **
176  ** value of the variable
177  **
178  *b Callable From:
179  **
180  *- - C++
181  *- - Script
182  */
183  int get_value_as_int();
184 
185  /*l
186  *b Description:
187  **
188  ** Returns the value of the variable as a floating point number.
189  **
190  *b Returns:
191  **
192  ** value of the variable
193  **
194  *b Callable From:
195  **
196  *- - C++
197  *- - Script
198  */
199  float get_value_as_float();
200 
201  /*l
202  *b Description:
203  **
204  ** Returns the value of the variable as a string. This pointer will
205  ** never be NULL.
206  **
207  *b Returns:
208  **
209  ** value of the variable
210  **
211  *b Callable From:
212  **
213  *- - C++
214  *- - Script
215  */
216  const char* get_value_as_string();
217 
218  /*l
219  *b Description:
220  **
221  ** This function sets the value as an integer.
222  **
223  *b Arguments:
224  **
225  *a value - new value of variable
226  **
227  *b Returns:
228  **
229  ** 0 on success, -1 on failure
230  **
231  *b Callable From:
232  **
233  *- - C++
234  *- - Script
235  *- - Decision Bead
236  */
237  int set_value_as_int(int value);
238 
239  /*l
240  *b Description:
241  **
242  ** This function sets the value as a floating point number.
243  **
244  *b Arguments:
245  **
246  *a value - new value of variable
247  **
248  *b Returns:
249  **
250  ** 0 on success, -1 on failure
251  **
252  *b Callable From:
253  **
254  *- - C++
255  *- - Script
256  *- - Decision Bead
257  */
258  int set_value_as_float(float value);
259 
260  /*l
261  *b Description:
262  **
263  ** This function sets the value as a string.
264  **
265  *b Arguments:
266  **
267  *a value - new value of variable
268  **
269  *b Returns:
270  **
271  ** 0 on success, -1 on failure
272  **
273  *b Callable From:
274  **
275  *- - C++
276  *- - Script
277  *- - Decision Bead
278  */
279  int set_value_as_string(const char* value);
280 
281  /*l
282  *b Description:
283  **
284  ** This function increments the value as an int.
285  **
286  *b Arguments:
287  **
288  *a increment_amount - the value by which to increment
289  **
290  *b Returns:
291  **
292  ** 0 on success, -1 on failure
293  **
294  *b Callable From:
295  **
296  *- - C++
297  *- - Script
298  *- - Decision Bead
299  */
300  int increment_value_as_int(int increment_amount = 1);
301 
302  /*l
303  *b Description:
304  **
305  ** This function decrements the value as an int.
306  **
307  *b Arguments:
308  **
309  *a decrement_amount - the value by which to decrement
310  **
311  *b Returns:
312  **
313  ** 0 on success, -1 on failure
314  **
315  *b Callable From:
316  **
317  *- - C++
318  *- - Script
319  *- - Decision Bead
320  */
321  int decrement_value_as_int(int decrement_amount = 1);
322 
323  /*l
324  *b Returns:
325  **
326  ** 1 if the variable as an int is equal to the passed value;
327  ** 0 if not
328  **
329  *b Arguments:
330  **
331  *a value - the value to compare against
332  **
333  *b Returns:
334  **
335  ** 0 on success, -1 on failure
336  **
337  *b Callable From:
338  **
339  *- - C++
340  *- - Script
341  *- - Decision Bead
342  */
343  int equal_to_int(int value);
344 
345  /*l
346  *b Returns:
347  **
348  ** 1 if the variable as an int is greater than the passed value;
349  ** 0 if not
350  **
351  *b Arguments:
352  **
353  *a value - the value to compare against
354  **
355  *b Callable From:
356  **
357  *- - C++
358  *- - Script
359  *- - Decision Bead
360  */
361  int greater_than_int(int value);
362 
363  /*l
364  *b Returns:
365  **
366  ** 1 if the variable as an int is less than the passed value;
367  ** 0 if not
368  **
369  *b Arguments:
370  **
371  *a value - the value to compare against
372  **
373  *b Callable From:
374  **
375  *- - C++
376  *- - Script
377  *- - Decision Bead
378  */
379  int less_than_int(int value);
380 
381  /*l
382  *b Returns:
383  **
384  ** 1 if the variable as a float is equal to the passed value;
385  ** 0 if not
386  **
387  *b Arguments:
388  **
389  *a value - the value to compare against
390  **
391  *b Callable From:
392  **
393  *- - C++
394  *- - Script
395  *- - Decision Bead
396  */
397  int equal_to_float(float value);
398 
399  /*l
400  *b Returns:
401  **
402  ** 1 if the variable as a float is greater than the passed value;
403  ** 0 if not
404  **
405  *b Arguments:
406  **
407  *a value - the value to compare against
408  **
409  *b Callable From:
410  **
411  *- - C++
412  *- - Script
413  *- - Decision Bead
414  */
415  int greater_than_float(float value);
416 
417  /*l
418  *b Returns:
419  **
420  ** 1 if the variable as a float is less than the passed value;
421  ** 0 if not
422  **
423  *b Arguments:
424  **
425  *a value - the value to compare against
426  **
427  *b Callable From:
428  **
429  *- - C++
430  *- - Script
431  *- - Decision Bead
432  */
433  int less_than_float(float value);
434 
435  /*l
436  *b Returns:
437  **
438  ** 1 if the variable as a string is equal to the passed value;
439  ** 0 if not
440  **
441  *b Arguments:
442  **
443  *a value - the value to compare against
444  **
445  *b Callable From:
446  **
447  *- - C++
448  *- - Script
449  *- - Decision Bead
450  */
451  int equal_to_string(const char* value);
452 
453  /*l
454  *b Returns:
455  **
456  ** 1 if the variable as a string is alphabetically greater than
457  ** the passed value;
458  ** 0 if not
459  **
460  *b Arguments:
461  **
462  *a value - the value to compare against
463  **
464  *b Callable From:
465  **
466  *- - C++
467  *- - Script
468  *- - Decision Bead
469  */
470  int greater_than_string(const char* value);
471 
472  /*l
473  *b Returns:
474  **
475  ** 1 if the variable as a string is alphabetically less than
476  ** the passed value;
477  ** 0 if not
478  **
479  *b Arguments:
480  **
481  *a value - the value to compare against
482  **
483  *b Callable From:
484  **
485  *- - C++
486  *- - Script
487  *- - Decision Bead
488  */
489  int less_than_string(const char* value);
490 
491  /*l
492  *b Description:
493  **
494  ** Returns the initial value of the variable as an integer.
495  **
496  *b Returns:
497  **
498  ** initial value of the variable
499  **
500  *b Callable From:
501  **
502  *- - C++
503  *- - Script
504  */
505  int get_initial_value_as_int();
506 
507  /*l
508  *b Description:
509  **
510  ** Returns the initial value of the variable as a floating point
511  ** number.
512  **
513  *b Returns:
514  **
515  ** initial value of the variable
516  **
517  *b Callable From:
518  **
519  *- - C++
520  *- - Script
521  */
522  float get_initial_value_as_float();
523 
524  /*l
525  *b Description:
526  **
527  ** Returns the initial value of the variable as a string. This
528  ** pointer will never be NULL.
529  **
530  *b Returns:
531  **
532  ** initial value of the variable
533  **
534  *b Callable From:
535  **
536  *- - C++
537  *- - Script
538  */
539  const char* get_initial_value_as_string();
540 
541  /*l
542  *b Description:
543  **
544  ** This function sets the initial value as an integer.
545  ** The current value will be set to the initial value when the
546  ** scenario containing this variable is reset.
547  **
548  *b Arguments:
549  **
550  *a initial value - new initial value of variable
551  **
552  *b Returns:
553  **
554  ** 0 on success, -1 on failure
555  **
556  *b Callable From:
557  **
558  *- - C++
559  *- - Script
560  */
561  int set_initial_value_as_int(int initial_value);
562 
563  /*l
564  *b Description:
565  **
566  ** This function sets the initial value as a floating point number.
567  ** The current value will be set to the initial value when the
568  ** scenario containing this variable is reset.
569  **
570  *b Arguments:
571  **
572  *a initial value - new initial value of variable
573  **
574  *b Returns:
575  **
576  ** 0 on success, -1 on failure
577  **
578  *b Callable From:
579  **
580  *- - C++
581  *- - Script
582  */
583  int set_initial_value_as_float(float initial_value);
584 
585  /*l
586  *b Description:
587  **
588  ** This function sets the initial value as a string.
589  ** The current value will be set to the initial value when the
590  ** scenario containing this variable is reset.
591  **
592  *b Arguments:
593  **
594  *a initial value - new initial value of variable
595  **
596  *b Returns:
597  **
598  ** 0 on success, -1 on failure
599  **
600  *b Callable From:
601  **
602  *- - C++
603  *- - Script
604  */
605  int set_initial_value_as_string(const char* initial_value);
606 
607 
608 /*****************************************************************************/
613  /*l
614  *b Description:
615  **
616  ** This is an enumeration of the different callbacks
617  ** that can be registered with add_callback() and
618  ** add_callback_script().
619  **
620  *b Usable From:
621  **
622  *- - C++
623  *- - Script
624  */
625  enum {
626  CALLBACK_ID_VALUE_CHANGED = 1
627  };
628 
629 #ifdef CPLUSPLUS_ONLY
630 
631  /*l
632  *b Description:
633  **
634  ** This function adds a user callback.
635  **
636  *b Arguments:
637  **
638  *a callback - pointer to function with prototype
639  *a diguyVariableCallback (typedefed above)
640  *a callback_id - integer id of when this callback is to be called
641  *a callback_params - not currently used; pass NULL
642  *a callback_user_data - pointer for user's own use; DI-Guy will
643  *a do nothing to the contents of this pointer
644  *a beyond passing it back when the callback is
645  *a invoked
646  **
647  ** callback_id should be one of the following values:
648  **
649  *i CALLBACK_ID_VALUE_CHANGED
650  **
651  ** This callback will be called whenever the value of the
652  ** variable changes.
653  **
654  ** There are no parameters for this callback.
655  **
656  *i Callback Return Values:
657  **
658  ** Callbacks return a value of type diguyCallbackReturn,
659  ** which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
660  ** If the callback returns DIGUY_CALLBACK_STOP, the default handler
661  ** of the function will not be called; the callback is asserting
662  ** that it has done everything necessary for the function call.
663  ** If the callback returns DIGUY_CALLBACK_CONTINUE, the default
664  ** handler for the function will be called after the callback.
665  **
666  *b Returns:
667  **
668  ** 0 on success, -1 on failure
669  **
670  *b Callable From:
671  **
672  *- - C++
673  */
674  int add_callback(int callback_id,
675  diguyVariableCallback* callback,
676  void* callback_params = 0,
677  void* callback_user_data = 0);
678 
679  /*l
680  *b Description:
681  **
682  ** This function removes a user callback. All callbacks matching
683  ** the specified callback_id and callback function will be removed.
684  **
685  *b Arguments:
686  **
687  *a callback_id - integer id of when this callback is to be called
688  *a callback - pointer to function with prototype
689  *a diguyVariableCallback (typedefed above)
690  **
691  *b Returns:
692  **
693  ** 0 on success, -1 on failure
694  **
695  *b Callable From:
696  **
697  *- - C++
698  */
699  int remove_callback(int callback_id,
700  diguyVariableCallback* callback);
701 
702  /*l
703  *b Description:
704  **
705  ** This function removes a user callback. All callbacks matching
706  ** the specified callback_id and callback_user_data pointer will
707  ** be removed.
708  **
709  *b Arguments:
710  **
711  *a callback_id - integer id of when this callback is to be called
712  *a callback_user_data - pointer for user's own use
713  **
714  *b Returns:
715  **
716  ** 0 on success, -1 on failure
717  **
718  *b Callable From:
719  **
720  *- - C++
721  */
722  int remove_callback_with_user_data(int callback_id,
723  void* callback_user_data);
724 
725 #endif /* CPLUSPLUS_ONLY */
726 
727  /*l
728  *b Description:
729  **
730  ** This function adds a user callback script. Callback scripts can
731  ** be removed with remove_callback_script().
732  **
733  ** See diguyCharacter::add_callback_script() for an example
734  ** of use.
735  **
736  *b Arguments:
737  **
738  *a callback_id - integer id of the callback
739  *a callback_script - script text of callback to be added
740  *a callback_script_type - the type of script contained in
741  *a callback_script
742  **
743  ** If NULL is passed for callback_script_type, a default script type
744  ** will be derived based on the default script interpreter of the
745  ** scenario.
746  **
747  *i Lua specific:
748  **
749  ** When the script is called, the object for which it is being called
750  ** will be in the callback_object global.
751  **
752  ** To pass NULL when calling from a lua script, use nil.
753  **
754  *b Returns:
755  **
756  ** 0 on success, -1 on failure
757  **
758  *b Callable From:
759  **
760  *- - C++
761  *- - Script
762  */
763  int add_callback_script(int callback_id,
764  const char* callback_script,
765  const char* callback_script_type = NULL);
766 
767  /*l
768  *b Description:
769  **
770  ** This function removes a user callback script previously added with
771  ** add_callback_script().
772  **
773  ** See diguyCharacter::remove_callback_script() for an example
774  ** of use.
775  **
776  *b Arguments:
777  **
778  *a callback_id - integer id of the callback
779  *a callback_script - script text of callback previously added
780  *a callback_script_type - the type of script contained in
781  *a callback_script
782  **
783  ** If NULL is passed for callback_script, all callback
784  ** scripts whose ids match callback_id and whose types match
785  ** callback_script_type will be removed.
786  **
787  ** If NULL is passed for callback_script_type, a default script type
788  ** will be derived based on the default script interpreter of the
789  ** scenario.
790  **
791  *i Lua specific:
792  **
793  ** To pass NULL when calling from a lua script, use nil.
794  **
795  *b Returns:
796  **
797  ** 0 on success, -1 on failure
798  **
799  *b Callable From:
800  **
801  *- - C++
802  *- - Script
803  */
804  int remove_callback_script(int callback_id,
805  const char* callback_script,
806  const char* callback_script_type = NULL);
807 
808 
809 /*****************************************************************************/
815  /*l
816  *b Description:
817  **
818  ** This function maps the event handler with the given name
819  ** to a callback id. This mapping will be saved in the .dss
820  ** file and restored when the .dss file is loaded.
821  **
822  ** Mappings can also be made via the DI-Guy Scenario UI.
823  **
824  ** The event handler is one of the following:
825  **
826  *- - a variable callback function registered by
827  *- diguyScenario::register_variable_event_handler() or
828  *- diguyScenario::register_variable_event_handler_from_library()
829  *- - a script registered by
830  *- diguyScenario::register_variable_event_handler_script()
831  *- - a Script, Decision, or Library Function in the scenario
832  *- whose "Event Type" is "Variable"
833  **
834  *b Arguments:
835  **
836  *a callback_id - integer id of callback
837  *a handler_name - name of the event handler to map
838  **
839  *b Returns:
840  **
841  ** 0 on success, -1 on failure
842  **
843  *b Callable From:
844  **
845  *- - C++
846  *- - Script
847  */
848  int map_event_handler_to_callback_id(int callback_id,
849  const char* handler_name);
850 
851  /*l
852  *b Description:
853  **
854  ** This function unmaps the event handler with the given name
855  ** from a callback id.
856  **
857  *b Arguments:
858  **
859  *a callback_id - integer id of callback
860  *a handler_name - name of the event handler to map
861  *a unmap_all_matches - pass 0 to unmap only the first match,
862  *a pass 1 to unmap all matches
863  **
864  *b Returns:
865  **
866  ** 0 on success, -1 on failure
867  **
868  *b Callable From:
869  **
870  *- - C++
871  *- - Script
872  */
873  int unmap_event_handler_from_callback_id(int callback_id,
874  const char* handler_name,
875  int unmap_all_matches = 0);
876 
877 
882 #ifdef CPLUSPLUS_ONLY
883 
884  bdiScenarioVariable* get_scripted_object() {return m_scripted_object;}
885 
886 private:
887 
888  /*l
889  ** A private constructor.
890  */
891  diguyVariable(bdiScenarioVariable* variable);
892 
893  /*l
894  ** A pointer to internal data.
895  */
896  bdiScenarioVariable* m_scripted_object;
897 
898  friend class bdiScenarioVariable;
899 
900 #endif /* CPLUSPLUS_ONLY */
901 
902 };
903 
904 #endif /* __diguyVariable_H */
905