Scripting:

Scripting Manager

Table of Contents    1. Classes required:    2. Description      2.1 EventsManager      2.2 FormScript      2.3 ScriptIO (certainly moved into Kross)      2.4 Event and EventList (moved into Kross)      2.5 ConnectionEditor    3. Storing code and connections      3.1 Events    4. Connections      4.1 What objects provide signals and slots?      4.2 Connection Editor inside Kexi Property Pane      4.2.1 Other Design for Connection Editor inside own tab      4.2.2 Another iteration      4.3 KexiConnectionDialog

1. Classes required:

• EventsManager: global class, takes care of connecting with Kross. Only class used by other libs.
• Script : one per form; store connection for this form, connects after form loading. Pointer to KFD::Form* instance needed to pass it to Kross.
• ScriptIO: Load/saves events/connections/scripts
• Event (Connection?) and EventList classes to deal with events. Kross::Api::ScriptContainer provides connect() and disconnect() to connect a signal with a kross function. Kross::Api::EventManager is the Kross-internal handler for signals and slots.
• ConnectionEditor: treeview to edit/add/remove current connections.

2. Description

2.1 EventsManager

• Should create Kross::Api::Manager to communicate with Kross.
• Allow a form to access external scripts.

2.2 FormScript

• Stores the Form script code. Use Kross::Api::ScriptContainer.
• Stores a list of all connections in this form.
• Used by event editor to get list of events, add or delete events.

2.3 ScriptIO (certainly moved into Kross)

• Saves all the connections in a form and the code in <action> tag.
• Reads <action> tag in UI file and create/fill a FormScript object from this.

2.4 Event and EventList (moved into Kross)

• Simple classes to store events. Already such class in formeditor/event.{cpp|h}
• Signals can be connected to slots, user slots (in any scripting language) and KActions (or user-created actions later). Signals can also be application signals.

2.5 ConnectionEditor

• Display connections created for selected widget: one top item for each signal, and child item for connected slot/action.
• Small toolbar (as in navigator) on top to add/edit/remove connections.
• Clicking on a connection opens editor to edit function and optional function parameters (Kross::Api::List*). Read 4.

3. Storing code and connections

3.1 Events

• External storing: all <events> tags are stored in separate <event> tag, at the same level as <UI>. (This is the method used by Qt Designer)
  • Pros: FormIO (and all kfd libs) don't have to know about Kross classes responsible for loading/saving events
  • Cons: When copying widget or undoing insertion, FormIo will have to call Kross class to save all events related to a widget

• Inline storing: <events> are stored inside the <widget> tag of the widget they belong to
  • Pros: More confortable when copying and undoing.
  • Cons: what about form events (ex aboutToShowForm) or Kexi events? Where should they be stored?

  // Whatever tags we've around <script/> and <event>...
  <form>
    // We could have multiple <script/> items. One for each
    // Kross::Api::ScriptContainer.
    <script name="myscriptname1" language="python">
      python script code</script>
    // 0..n <event/> could be defined.
    <event>
      // Qt signal.
      <sender widget="pushButton1" signal="clicked()" />
      // We are able to reference to a <script/> and optional
      // functionname and functionparameters.
      <receiver script="myscriptname1" function="myfunctionname1"
       arguments="my optional arguments" />
      // or to execute a KAction
      <receiver object="Kexi" action="closeFormAction" />
      // or just to connect the sender with another slot
      <receiver object="Kexi" slot="closeForm()" />
    </event>
  </form>

4. Connections

Connections between senders and receivers are handled inside of Kexi and are used 1) in the KexiPropertyEditor and 2) the KexiConnectionDialog. They share a codebase that does

• marshal "key=value" string pairs like "button1.onclick = field1.clear();field2.clear()"
  into a Connection object with sender, signal, receiver, slot strings to use QObject::connect() to connect such signals.
• both, key and value, contain with a simple dot splitted namespaces. We could have following namespaces as example;
  * 'Kexi' for Kexi internal KAction's like 'exit', etc. Such actions could be referenced with something like 'Kexi.exit'.
  * 'Forms' for all formulas. A widget in a Form would be referenced with something like 'Forms.myform1.mybutton1'.
  *'Scripts' for global scripts. Use e.g. `Scripts.myscript1.myfunction1' to reference a script function.

4.1 What objects provide signals and slots?

• KFD: signals and slots from the form itself or child-widgets.
• Query: signals like if a query got executed or slots like callquery().
• Table: would it make sense to have signals and slots there?
• Scripts: Each script could spend functions used as slots. It's also possible to emit signals from within scripts.

4.2 Connection Editor inside Kexi Property Pane

The editor displays the listview with columns 'event' and 'action' in an own tab. At the bottom of the is a button to call the KexiConnectionDialog. Each item in the list has a key like 'onClicked()' representing the events the selected widget implements. If displayed at a Scriptmodule the editor will display all events the script implements.

(a mockup)

source: http://iidea.pl/~js/kexi/src/ui/conneditor_in_propeditor.ui

Advantages of having Connection Editor inside KexiPropertyEditor is that a user can see a list of conenctions of currently clicked widget within a form design, i.e. faster access, no modal dialog needed.

4.2.1 Other Design for Connection Editor inside own tab

4.2.2 Another iteration

(a mockup)

source: http://iidea.pl/~js/kexi/src/ui/conneditor_in_propeditor2.ui

Notes:

• This widget could rather be a part of KROSS than form plugin. It could have be built on top of a simple class interface (e.g. providing just form's XML) and thus form plaugin can stay indep. of KROSS.
• list view items are selectable
• Both combo boxes:
  • are only visible for currently selected list item (just like in propertyeditor)
  • offer autocompletion and are editable
  • can have items with icons for improved readability
• "Connect to" combo box can contain following items (on this order):
  • "<this form>" or "<this report>" (the default)
  • a list of widgets within a form (display both widget's name and widget's class)
  • a separator
  • a list of scripts
  • a separator
  • a list of macros
• "Action" combo box is filled with appropriate contents after selection in "Connect to" combo box changes:
• "Action" combo box can contain following items (on this order):
  • If "Connect to" has selected <this form> <this report> or a script: a list of actions (slots) with compatible interface (appriopriate # of args and types)
  • If "Connect to" has selected a macro: nothing (it could be disabled)
• only insert a new connetion item in a data structure if valid connection has been defined; thus, clicking [+] key 100 times wont add 100 invalid connections
• add a warning kmessage if somebody entered invalud value to any of the combos: offer to [Fix it] (then focus the combo box allowing user to do a fix) or [Remove the connection].
• [+] and [-] buttons are always visible for every item

4.3 KexiConnectionDialog

The dialog provides a more powerfull UI to display and edit connections. It uses a tree of all forms and widgets the forms provide, scripts and script signals/slots and so on... Each leaf is an event (sender/signal combination) that could be connected to an action (receiver/slot combination). Filters could spend some nice ways to hide/show parts of the tree. We could use the default filterrule according from who called. If the dialog was called with a selected form-widget, then only signals of those form-widget could be shown.