Object handling


Once you have created your application, with windows as children, and you have defined the contents of any windows, you are ready to open them and handle your world.

The first operation is to set all the notifications that will occurs.

Any attributes of type N can be used to take care of events.

E.g. if you have a Menuitem AboutMUI that has only to open the MUI about requester, all you have to do is set up a notification on that event via the call

   call Notify("AboutMUI","MenuTrigger","EveryTime","app","AboutMUI","win")

Remember that the more notifications among objects you set up the less you have to care about your work.

 

Obviously, there are events that must be handled by yourself in the main handle cycle.

If you want an object to just return its name when an attribute of it changes, you must do

   call Notify(obj,attr,value,app,"ReturnID") 

E.g.

   call Notify("button","Pressed",0,"app","ReturnID") 

 

As you can see, events to be dispatched by yourself are always notified to an application objects.

 

An application objects accepts the following methods to handle events that may occur on objects:

ReturnID
It is used when you want the application to return you the name of the object; the special parameter QUIT means that the event is a application killer one
   call Notify("win","CloseRequest",1,"app","ReturnID","QUIT")
Return
It is used when you want to return custom strings to the application (with len <=64 chars) and when you want to read the value of the triggering attribute any time it changes
   call Notify("cycle","active","EveryTime","app","return",
               "Cycle changed","TriggerAttr")

It accept any G attribute as second parameter plus the special string TriggerAttr that means the same attribute that triggers the notification.

InLine
It is used in notification such as:
    call Notify("slider","Value","EveryTime","app","InLine",
                "parse arg name,value;...","TriggerAttr")

When attr changes to value, fun, an inline ARexx function macro, is called with arguments:

  1. the name of the notifier
  2. the value of attr; the attribute must be G; a special value is TriggerAttr that means the triggering attribute; if no attribute is supplied, the function receives just one argument.

The function is called in the same process of the running macro and so in it there can be used any RxMUI functions on any object, but it is called as a separate ARexx macro and HASN'T GOT the environment of the running macro (e.g. ala INTEPRET command). It means mainly that the existing variables are not valid in the function (they just don't exist).

SETVAR
It is used when you want to set a variable to the value of the attribute that triggers the notification
   call Notify("cycle","active","everytime","app","SET","CYCLEACTIVE")   

Classes may define their own methods to return events.

 

After that, you enter in the main cycle, THAT IS:

   ctrl_c=2**12
    do forever
        call NewHandle("app","h",ctrl_c)
        if and(h.signals,ctrl_c)~=0 then exit /* user break */
        if h.EventFlag
            select
                when h.event="QUIT" then exit /* quit event */
                when h.event=...
                ...
            end
    end

When you receive a QUIT you must exit. If you have to complete other operations before exiting, you should get the attribute ForceQuit of the application to see if you can loose time.

In h.event there will be the name of the object that triggered the event via ReturnID or the string you set up via Return In the case of e.g.

   call Notify("cycle","Active","EveryTime","app","Return","CYCLE","TriggerAttr")

you will have in h.active the active entry of cycle.

If you set up a SetVar notification, nothing is returned, but you can be sure that in the specified var there is the value you need.

RxMUI may receive 3 special events:

APPEVENT
After you have declared a window AppWindow with that attribute set to 1, you will receive a APPEVENT anytime an icon is dropped into the window or into any object of the window, you have previously enabled to receive dropped icon via AppMessage() . You will find the name of the object in h.to and the complete path to the icon in h.name
 
DROPEVENT
User Drag & Drop: a manual drag and drop must be performed. The interested objects are in h.from and h.to .
 
AREXXCMD
You set WantARexxCmd at Application Init time and an unknown to MUI ARexx command came to the Application ARexx port. Anytime someone sends a message to the Application ARexx port and MUI doesn't know what to do with it, it is notified to the Application via this event. Note that at this time, the message was already replied and you can't set any return code or result to send back.

 

Similar to NewHandle() is Handle(). The differences are:

  1. NewHandle() just returns ONE event;
    Handle() may returns one or MORE events
  2. NewHandle() waits for signals internally;
    Handle() doesn't wait for signal and you have to wait for them manually in the macro, e.g. via rmh.library/wait()

So the default cycle using Handle() is:

   ctrl_c=2**12
    s=0
    do forever
        call Handle("APP","H",s)
        do i=0 to h.num-1
            if h.i="QUIT" then exit /* quit event */
            if h.i==... then
            ...
        end
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit /* user break */
    end

Or if you manage any kind of manual drag and drop:

   ctrl_c=2**12
    s=0
    do forever
        ws=1
        call handle("APP","H",s)
        do i=0 to h.num-1
            if h.i="QUIT" then exit /* quit event */
            if h.i=="DROPEVENT" then do
                /* handle drag and drop from h.i.from to h.i.to */
                ws=0
            end
            if h.i==... then
            ...
        end
        if ~ws then iterate
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit /* user break */
    end

Handle() should be used only in peculiar situations, when you really have to wait for signals in the macro, e.g. you have to wait for non-blocking sockets events via rxsocket.library/WaitSelect(). In ordinary situations you should always use NewHandle().

 

So the event you may receive are:

Name in h.i or h.event Caused by Note More fields
[user-defined] RETURN An object notified the application .ATTRIBUTE
[name of an object] RETURNID An object notified the application -
QUIT RETURNID The application wants to exit -
APPEVENT AppMessage() An icon was dropped into an object .to .name
DROPEVENT DandD() Manual D&D .from .to
AREXXCMD An ARexx msg An ARexx message came .cmd