[litwindow-users] Re: Anatomy of a RULE

[Hajo K. <mai...@ha...>]

Hi,

> Could you explain the rules for making a RULE?

rules generally have the form

name = expression

and are evaluated by the constraint solver in the lit window base library.

The name is the name of an entity passed to the RapidUI mediator object. 
  There are two namespaces, windows and data, that can be explicitly 
specified with wnd:: or data::. If no namespace is given, the wnd:: 
namespace is searched first, then the data namespace::

The name search is recursively. If you specify "m_widget" and m_widget 
is a child of a child of a child of a child of a window you have passed 
to the RapidUI mediator object, it will be found. Same applies for data 
objects. Search is always top-down.

Entities can have properties, similar to C++ class members. In fact in 
most cases there will be a 1:1 relationship between the class member and 
a property. Frame.Caption for example is wxFrame::Get/SetCaption.

In some cases the original widget has been enhanced and has properties 
for which no corresponding C++ function exists. This is done through the 
Co-Object mechanism we already wrote about. Example:: ListBox.Current 
contains a reference to the currently object (!) of the list box. Not to 
be confused with CurrentSelection, which contains the selection index.

Properties can be dereferenced as well, just like C++ members. So

MyListBox.Current.m_option is a valid name and references the "m_option" 
property (member variable or get/set functions) of the currently 
selected object.

The most basic rule is

a = b

This is a one-way rule meaning that when b changes, a will be updated 
but not vice versa. If you want a two-way rule, you must specify

a = b
b = a

The macro TWOWAY(a,b) does this.

To bind a boolean variable "m_option" to a checkbox "mycheckbox", write

mycheckbox = m_option    and
m_option = mycheckbox

> The rule seems to consist of strings with a reference to a UI element on the
Not neccessarily UI elements, but the window namespace is searched 
first. But it is possible to use a data entity on the left side as well.

> left hand side and some type of data on the right hand side.  The left hand
> expression consists of a XRC name followed by a .{Name} for which there
> exists functions names Get{Name}() and Set{Name}().  There are some RapidUI
> defined {Name}s like Current, Items, Column, Title and some others.  Most of
> the {Name}s seem defined within RapidUI but sometimes it seems like {Name}s
> for which there exists a Get{Name} and Set{Name} in the wxWidgets class is
> also acceptable.

The idea is that there should be a corresponding RapidUI property for 
every wxWidgets GetName/SetName or member variable.

> The right-hand side seems to be a either a constant or a specific data
> member.  All of the examples use make_const or make_expr to construct the

Not neccessarily data member. You can use window properties as well.

> data.  The data type used for make_const or make_expr on the right hand side
> must be equal to the parameter data type for the left-hand side's Set{Name}
> function.

Correct.

The reason behind make_expr and make_const is to let the C++ compiler 
parse and build the expression tree that is then evaluated at runtime. 
This will later be done with a parser. Until then

make_const<type>(constant_value) must be used when you want to use a 
constant in the right hand expression. make_expr<type>("name") must be 
used when you want to access a property - either in the window or in the 
data namespace -

make_expr<wxString>("MyObject.FileName") returns the (fictional) 
"FileName" property of an object named "MyObject".

The expression

make_const<wxString>("Document: ") + 
make_expr<wxString>("MyObject.FileName")

will return something like "Document: myfile.txt".

The rule

"FrameWindow.Caption" = make_const<wxString>(... )

will show the "Document: ..." string in the titlebar. And will always 
keep the titlebar in sync with the current filename.

The <type> specification in make_const/make_expr is neccessary only if 
the compiler cannot automatically determine the type of the parameter.

> is selected, then a new element.  Perhaps this means that .Current is only a
> right-hand expression name.

No. Current is a property like any other property and can be used on the 
left or right side.

> I have also observed that in addition to specific classes, make_expr can
> cast to an accessor.  Not being very familiar with stl, I'm not sure if
> there are any restrictions on what can be cast as an accessor.  (Are there
> other special casts?  Can one cast to an aggregate too?)

accessors have nothing to do with the STL. They are a fundamental part 
of the litwindow library and are documented there. Basically an accessor 
is a pointer with runtime type information.


> So for lists, it is necessary to know that the predefined 'Items' {Name}
> exists and is an accessor.  Then it follows that the

Yes. What is still missing is a class-like documentation of the 
properties of a class. The Lit Window libary introduces a new view on 
the usual widgets.

The C++ documentation contains
class wxListBox
{
    void SetSelection(int i);
    int  GetSelection() const;
};

The RapidUI object documentation would read

class wxListBox:
   property(int) Selection

   property(accessor) Items
     Contains the list of items shown in the list box. If Items is a 
container, all elements of the container will be shown. If Items is an 
aggregate, all elements of the aggregate will be shown. If Items is 
neither, the listbox will contain only one element: the "AsString" 
representation of the element.

   property(accessor) Current
     Contains the currently selected object.


> make_expr<accessor>("some_rapid_ui_data_member"), where
> "some_rapid_ui_data_member" could be a collection or an aggregate depending
> on what was expected.

Yes.

> Is this correct so far?  There are suggestions that the syntax will be
> extended further.  For instance, the .Delete that I've seen on the left hand
> side doesn't make sense expanding to GetDelete, SetDelete function calls.

Yes. Delete will be an action. I haven't designed actions yet, but 
Delete will probably expand to a DeleteCurrent call or something.

Hajo