How to install COMETs

You will need to download and install the TCL interpretor. Install it on the C: root. You can also download a distribution from the official website of ActiveTCL. You now have to add two environment variable (at least if you use window) , TCL_LIBRARY (value c:/TCL/lib/tcl8.4), and TK_LIBRARY (value c:/TCL/lib/tk8.4). Those variables are used by TCL to load some behaviors when the interpretor is launched.
you also need of course the COMET framework ^_^. If you want to avoid problems of paths, put it in C:/These/Projet Interface/COMETS/devCOMETS... (yes I know, it's bad to hardcode path...maybe one day...).
Last, you may optionnaly want to install the B207 toolkit (based on OpenGL, windows only) to use COMET on multitouch surfaces for instance. Again, to avoid surprises, uncompress this thing into C:/These/Projet Interface/BIGre

Now you can launch a classical TCL interpreter (to be found in C:/TCL/bin/wish84.exe or use a better UI for the interpretor by using C:/TCL/bin/tkcon-2.4/tkcon.tcl_e, open the latest which is not executable with wish84.exe...).
You can also use the B207 environment, which embed a TCL interpretor, if you want to use B207 renderings. You can then start by launching some small "applications" by sourcing some code :

cd "C:/These/Projet Interface/COMETS/devCOMETS"
source test_MetaUIExchanger.tcl
# or
source demo_DSVIS2008.tcl

Ask me questions if something unclear (which is certainly the case for many things!).

Overview of COMET architecture

COMET is driven by three principles: (1) Separation of concerns, (2) Reuse of existing toolkits (e.g., AJAX/HTML, TK, vocal, OpenGL), and (3) Recursivity so that a COMET can recursively be composed of COMETs. A COMET is composed of three facets. Each of them is responsible of one specific concern (Separation of concerns principle):

A Logical Consistency (LC) represents the user’s task (e.g., control the slides) or the task operator (e.g., interleaving) that the COMET supports. It denotes the semantics of the service that the COMET provides. The semantics gives rise to a specific API, called semantic API (e.g., next slide, previous slide...). The LC is associated to one or many Logical Models (LM). If many, LC is in charge of maintaining consistency between these LMs.
A Logical Model (LM) is in charge of a specific concern related to the realization of the semantics. Usually, a distinction is made between the presentation and the abstraction (i.e., functional core). Whatever the concern is, each LM has to implement the semantic API of the corresponding LC (e.g., next slide...): this semantic API is the language that LC and LM share. The API can be extended to take into account specific concerns (e.g., blurring the slide). In turn, a LM is associated to one or many Physical Models (PM). If many, LM is in charge of maintaining consistency between these PMs. It also provides PM factories for instantiating PMs on the fly.
A Physical Model (PM) is a specific means for realizing a LM. A presentation PM encapsulates the code of primitive toolkits such as OpenGL, HTML, SAPI, etc. (Reuse principle). A functional PM would encapsulate network protocols (e.g., AIM, MSN, YAHOO, IRC, etc.) in case of a Chat COMET. Encapsulated codes are called technological primitives. A PM has to implement its LM semantic API: this API is the shared language. A PM also describes the context of use it requires (e.g. JAVA, screen size, etc.).

Have a look at the DSVIS 2008 paper... Here is a UML schema of COMET architecture:

Getting inline help while using COMETs

Write "Aide_nom OBJET_TCL REGULAR_EXPR" to get names of the methods of OBJET_TCL corresponding to the regular expression REGULAR_EXPR.
Example: Aide_nom cr get_

Creating a new COMET

Let's take the example of a COMET computing and displaying the path between two locations. We will call it the CometTravel. To create such a COMET, there are some steps to follow

Create a sub-directory called CometTravel under devComet/COMETs.
Define a semantic API in a file called CometTravel_CFC, CFC stands for Common functional Core. Let's suppose that the API has to deal with a starting point and a destination point. It is able to compute and give a travel. First, we inherit from the CommonFC class:
```
inherit CometTravel_CFC CommonFC
```
Second, we define the constructor, we need here at least 3 attributes:
```
method CometTravel_CFC constructor {} {  
  set this(loc_src) ""       
  set this(loc_dst) ""       
  set this(travel)  ""  
}
			
```
We can automatically generate accessors by using Generate_accessors command like that:
```
Generate_accessors CommonFC_Activator [list loc_src loc_dst travel]
```
We define the others methods of the API:
```
method CommonFC_Activator Compute_travel {} {}
```
Finally we define explicitely what is the API. The API is divided between getters (which do not modify the internal state) and setter (which do modify the internal state). Both are defined using a procedure that return a list <method name, parameters>:
```
proc P_L_methodes_get_CometTravel {} {return [list {get_loc_src { }} {get_loc_dst { }} {get_travel { }} ]}                      
proc P_L_methodes_set_CometTravel {} {return [list {set_loc_src {l}} {set_loc_dst {l}} {set_travel {t}} {Compute_travel {}} ]}  
			
```

Next step is to define the "core" of the COMET, the logical consistency (LC) in a news file nammed CometTravel_LC. We first inherit from the Logical_consistency

inherit CometTravel_LC Logical_consistency

Then we define the constructor, it instantiate the previously defined CFC and the related Logical Models (LM). Here there are 2 LM, one for presentation (named by suffixing "_LM_LP" to the name of the LC), the other for computation (this is the functional core part, named by suffixing _LM_FC to the name of the LC).

method CometTravel_LC constructor {name descr args} {
  this inherited $name $descr     
  this set_GDD_id CT_CometTravel  


  set CFC "${objName}_CFC"; CometTravel_CFC $CFC 
  this set_Common_FC $CFC 


  set this(LM_LP) "${objName}_LM_LP"; 
  CometTravel_LM_LP $this(LM_LP) $this(LM_LP) "The logical presentation of $name" 
  this Add_LM $this(LM_LP); 
  set this(LM_FC) "${objName}_LM_FC";
  CometTravel_LM_FC $this(LM_FC) $this(LM_FC) "The logical functional core of $name" 
  this Add_LM $this(LM_FC); 


  eval "$objName configure $args" 
  return $objName 
}

Don't forget to send back the name of the created object, and just before to interpret arguments:

  eval "$objName configure $args" 

  return $objName

The semantic API can be automatically generated. Getters refer to the Common functional functional Core (CFC) with $this(FC). Setters refer to the CFC and the list of LM ($this(L_LM)):

Methodes_get_LC CometTravel_LC [P_L_methodes_get_CometTravel] {$this(FC)}               
Methodes_set_LC CometTravel_LC [P_L_methodes_set_CometTravel] {$this(FC)} {$this(L_LM)}

That's ALL for the LC! :)

Next step is about the definition of the LM. We detail here the creation of the presentation LM, the functional LM is pretty similar. First we create a sub-directory nammed LMs in which we create the files related to the LMs; CometTravel_LM_LP.tcl and CometTravel_LM_FC.tcl. We detail here what to put in CometTravel_LM_LP.tcl. First we inherit from Logical_presentation:

inherit CometTravel_LM_LP Logical_presentation

We define the constructor, here the constructor mainly define Physical Models (PM) factories:

method CometTravel_LM_LP constructor {name descr args} {
  this inherited $name $descr
 # Adding some physical presentations
  this Add_PM_factories [Generate_factories_for_PM_type [list {CometTravel_PM_P_TK_base Ptf_TK} \
               {CometTravel_PM_P_U Ptf_ALL}      \
              ] $objName]


  eval "$objName configure $args"
  return $objName
}

We can generate the semantic API automatically again. Getters refers to the CFC. Setters do not modify the CFC (only the LC can) but propagate calls to the active PMs ($this(L_actives_PM)):

Methodes_set_LC CometTravel_LM_LP [P_L_methodes_set_CometTravel] {} {$this(L_actives_PM)}
Methodes_get_LC CometTravel_LM_LP [P_L_methodes_get_CometTravel] {$this(FC)}

In the LM, we can define a new list of methods that will support COMET/RE (basic support of multimodality notions of Redundancy and Equivalence bewteens the different PMs of a same LM, generally about presentation, but not necessarily) expressions:

proc P_L_methodes_set_CometTravel_COMET_RE {} {return [list {set_loc_src {l}} {set_loc_dst {l}} {Compute_travel {}}]}

We generate automatically the code that will manage these methods:

Generate_LM_setters CometTravel_LM_LP [P_L_methodes_set_CometTravel_COMET_RE]

We can overload the set_PM_active of the LM to update each new PM:

method CometTravel_LM_LP set_PM_active {PM} {
  this inherited $PM
  if {[string equal [this get_LC] {}]} {return}
  $PM set_loc_src [this get_loc_src]
  $PM set_loc_dst [this get_loc_dst]
  $PM set_travel  [this get_travel]
}

That's all for a LM :)

Next step is coding some PMs. We will detail here how to code a dedicated/tailored presentation PM for the TK technology. In next step, we will illustrate the creation of a composite PM for the CometTravel. PMs can be stored in a sub-directory PMs. Let's create the file CometTravel_PM_P_TK_base. We first inherit from PM_TK:

inherit CometTravel_PM_P_TK_base PM_TK

Then we define the constructor. Basically for a TK PM, a root is defined (this(top_frame)):

method CometTravel_PM_P_TK_base constructor {name descr args} { 
  this inherited $name $descr 
  this set_GDD_id CometTravel_PM_P_TK_base 
  set this(top_frame) "" 
  eval "$objName configure $args" 
  return $objName 
}

Then we generate automatically the semantic API...

Methodes_set_LC CometTravel_PM_P_TK_base [P_L_methodes_set_CometTravel] {} {} 
Methodes_get_LC CometTravel_PM_P_TK_base [P_L_methodes_get_CometTravel] {$this(FC)}

and the API related to COMET/RE:

Generate_PM_setters CometTravel_PM_P_TK_base [P_L_methodes_set_CometTravel_COMET_RE]

The biggest thing to do for a PM TK is to overload the get_or_create_prims method. This method define the TK primitives...COME BACK !...it's just TK code!

method CometTravel_PM_P_TK_base get_or_create_prims {root} {
  set this(top_frame) "$root.tk_${objName}_topframe"
  if {![winfo exists $this(top_frame)]} {
    frame   $this(top_frame)
    frame   $this(top_frame).f_src
    pack     $this(top_frame).f_src -side top -expand 1 -fill x
    label   $this(top_frame).f_src.lab -text "From : "
    pack     $this(top_frame).f_src.lab -side left -expand 0 -fill none
    global ${objName}_tk_txt_from; set ${objName}_tk_txt_from ""
    entry   $this(top_frame).f_src.ent -text ${objName}_tk_txt_from
    pack     $this(top_frame).f_src.ent -side left -expand 1 -fill x
    frame   $this(top_frame).f_dst                 
    pack     $this(top_frame).f_dst -side top  -expand 1 -fill x
    label   $this(top_frame).f_dst.lab -text "To : "
    pack     $this(top_frame).f_dst.lab -side left -expand 0 -fill none
    global ${objName}_tk_txt_to; set ${objName}_tk_txt_to ""
    entry   $this(top_frame).f_dst.ent -text ${objName}_tk_txt_to
    pack     $this(top_frame).f_dst.ent -side left -expand 1 -fill x
    button $this(top_frame).bt_compute -text "GO !" -command "$objName Do_Compute"
    pack     $this(top_frame).bt_compute -side top -fill x


    set this(img_tk_name) "[this get_LM]_Activator_PM_P_button_TK_TK_img_ressource"
    image create photo $this(img_tk_name)
    label $this(top_frame).lab_img -image $this(img_tk_name)
    pack   $this(top_frame).lab_img -side top -fill none
    text   $this(top_frame).txt_travel -height 4 -width 40 -state disabled
    pack   $this(top_frame).txt_travel -side top -fill both
   }
  this set_root_for_daughters $this(top_frame)
  this set_loc_src [this get_loc_src]
  this set_loc_dst [this get_loc_dst]
  this set_travel  [this get_travel]


  return [this set_prim_handle $this(top_frame)]
}

Notice that the TK button do call a method nammed Do_compute...we defined it as:

method CometTravel_PM_P_TK_base Do_Compute {} {
  if {![winfo exists $this(top_frame)]} {return}
  global ${objName}_tk_txt_from
  global ${objName}_tk_txt_to
  this prim_set_loc_src [subst $${objName}_tk_txt_from]
  this prim_set_loc_dst [subst $${objName}_tk_txt_to]
  this prim_Compute_travel
}

Basically we call prim_* methods (prim_set_loc_src, prim_set_loc_dst, prim_Compute_travel). These methods have been generated automatically before to manage COMET/RE expression.
Of course, the PM has to implement the effects of semantic API on TK primitives:

method CometTravel_PM_P_TK_base set_loc_src {l} {
  if {![winfo exists $this(top_frame)]} {return}
  global ${objName}_tk_txt_from
  set ${objName}_tk_txt_from $l
}

method CometTravel_PM_P_TK_base set_loc_dst {l} {
  if {![winfo exists $this(top_frame)]} {return}
  global ${objName}_tk_txt_to
  set ${objName}_tk_txt_to $l
}

method CometTravel_PM_P_TK_base set_travel {t} {
  if {![winfo exists $this(top_frame)]} {return}
  image create photo $this(img_tk_name) -file [lindex $t 0]
  $this(top_frame).txt_travel configure -state normal
    $this(top_frame).txt_travel delete 0.0 end
    $this(top_frame).txt_travel insert 0.0 [lindex $t 1]
  $this(top_frame).txt_travel configure -state disabled
}

method CometTravel_PM_P_TK_base Compute_travel {} {}

Notice that the Compute_travel method don't do anything...it's normal, the job of a presentation PM is simply to interact with the user. The real computation job will be done by functional PMs.

Last for the presentation part, let's examine how to realize a composite presentation PM (file CometTravel_PM_P_U).
First we inherit from PM_U_Container:

inherit CometTravel_PM_P_U PM_U_Container

Then, in the constructor, we define the composite graph of COMET:

method CometTravel_PM_P_U constructor {name descr args} {
  this inherited $name $descr
  this set_GDD_id N_CometTravel_PM_P_U


  # Nested COMET graph
  set this(cont_root)   [CPool get_a_comet CometContainer -Add_style_class root]
    set this(spec_from) [CPool get_a_comet CometSpecifyer -Add_style_class from]
    set this(spec_to)   [CPool get_a_comet CometSpecifyer -Add_style_class from]
    set this(act_go)    [CPool get_a_comet CometActivator -Add_style_class compute_travel]
    set this(img_trav)  [CPool get_a_comet CometImage     -Add_style_class travel]
    set this(txt_trav)  [CPool get_a_comet CometText      -Add_style_class travel]
    set this(cont_dght) [CPool get_a_comet CometContainer -Add_style_class root]
    $this(cont_root) Add_daughters_R [list $this(spec_from) $this(spec_to) $this(act_go) $this(img_trav) $this(txt_trav) $this(cont_dght)]


  # Specify where are the handles 
  this set_L_nested_handle_LM    $this(cont_root)_LM_LP
  this set_L_nested_daughters_LM $this(cont_dght)_LM_LP


  # Subscribe to events...
  $this(act_go) Subscribe_to_activate $objName "$objName Do_Compute" UNIQUE


  eval "$objName configure $args"
  return $objName
}

Notice that we have to specify the root COMET and the COMET under which daughters of the composite will be plugged. This is done by indicating the presentation LM of the corresponding COMETs:

  this set_L_nested_handle_LM    $this(cont_root)_LM_LP
  this set_L_nested_daughters_LM $this(cont_dght)_LM_LP

As for the primitive PM TK, an activator COMET trigger the method Do_Compute that we have to implement. Basically we call the very same prim_* methods...

method CometTravel_PM_P_U Do_Compute {} {
  this prim_set_loc_src [$this(spec_from) get_text]
  this prim_set_loc_dst [$this(spec_to)   get_text]
  this prim_Compute_travel
}

As for a primitive PM, we have to implement the semantic API, it is pretty much faster here due to higher level of abstraction used (the composing COMETs instead of TK primitives):

method CometTravel_PM_P_U set_loc_src {l} {
  $this(spec_from) set_text $l
}

method CometTravel_PM_P_U set_loc_dst {l} {
  $this(spec_to) set_text $l
}

method CometTravel_PM_P_U set_travel {t} {
  $this(img_trav) load_img [lindex $t 0]
  $this(txt_trav) set_text [lindex $t 1]
}

method CometTravel_PM_P_U Compute_travel {} {}

That's ALL :) You now have 2 presentation PM that you can test. The composite one can be used with any technology (TK, OpenGL, HTML, vocal, etc.). The advantage of using a tailored TK PM is that you are able to specify very precisely how it should be displayed and how it should interact with the user.

Let's now look at the code of the functional part, first the functional LM, which inherit from Logical_model:

inherit CometTravel_LM_FC Logical_model

The constructor basically instantiate some functional PM, here only one. Unlike the presentations PMs, the others PMs have to be instantiated explicitely as there is no automatical mechanism that create a graph of PM except for the presentation PMs.

method CometTravel_LM_FC constructor {name descr args} {
  this inherited $name $descr
  # Adding some physical models
  set name ${objName}_PM_FC_pipo_[this get_a_unique_id]
  CometTravel_PM_FC_pipo $name "Pipo FC for testing" ""
    this Add_PM        $name
    this set_PM_active $name


  eval "$objName configure $args"
  return $objName
}

We generate automatically the code of the semantic API:

Methodes_set_LC CometTravel_LM_FC [P_L_methodes_set_CometTravel] {} {$this(L_actives_PM)} 
Methodes_get_LC CometTravel_LM_FC [P_L_methodes_get_CometTravel] {$this(FC)}

We define a list of methods that will support COMET/RE expressions:

proc P_L_methodes_set_CometTravel_FC_COMET_RE {} {return [list {set_travel {t}}]}

And finally we generate these methods:

Generate_LM_setters CometTravel_LM_FC [P_L_methodes_set_CometTravel_FC_COMET_RE]

That's all for the functional LM :)

In this last step we just illustrate the creation of a functional PM. These PMs are in charge of doing the computation of the travel. We detail here a "fake" functional PM that return always the same travel information whatever starting and ending points are. It inherits from Physical_model:
```
inherit CometTravel_PM_FC_pipo Physical_model
```
The constructor do nothing special:
```
method CometTravel_PM_FC_pipo constructor {name descr args} { 
  this inherited $name $descr                     
  this set_GDD_id N_CometTravel_PM_FC_pipo        
  eval "$objName configure $args"                 
  return $objName                                 
}
			
```
Semantic API can be generated automatically...
```
Methodes_set_LC CometTravel_PM_FC_pipo [P_L_methodes_set_CometTravel] {} {}      
Methodes_get_LC CometTravel_PM_FC_pipo [P_L_methodes_get_CometTravel] {$this(FC)} 
			
```
...as for the API managing COMET/RE expression. Note that we use here a list of methods nammed P_L_methodes_set_CometTravel_FC_COMET_RE. This list has been defined in the functional LM.
```
Generate_PM_setters CometTravel_PM_FC_pipo [P_L_methodes_set_CometTravel_FC_COMET_RE]
```
The ONLY method that has to be overloaded in the semantic API of the CometTravel functional PMs is Compute_travel:
```
method CometTravel_PM_FC_pipo Compute_travel {} {
  this prim_set_travel [list "[Comet_files_root]Comets/CometTravel/PM_Ps/FC/pipo_trajet.gif" "Turn left, then you are arrived...BRAVO !!!!"]
}
			
```
Of course a real functional PM would have to do some more serious stuff, such as querying google map...
Notice the call the prim_set_travel to set the travel information (a list composed by an image and a text) that will be propagated to the presentations PM which will render the travel information this way.