Functions


Functions that create objects
Button Checkmark Label MakeObj
MenuItem NewObj String Text
ToggleButton XNewObj
Functions that create spacing objects
HBar HFSpace HSpace HVSpace
HWSpace VBar VFSpace VSpace
VWSpace
Functions that manipulate objects
Add AppMessage AppPushID CoerceMethod
DandD Dispose DoMethod GetAttr
Handle KillNotify MultiGetAttr MultiSetAttr
NewHandle Notify PushMethod Remove
Set SetAttr SetAttrs SetClassAttrs
xget
Various
Child MUIRequest ParseText RxMUIGetVar
RxMUISetVar SetRxMUIStack StripText
Debug
GetRxMUIString Help RxMUIObjExists RxMUIObjList
RxMUIOpt

Add

Adds an object.
Synopsis
res = Add(parent,child,before)
<parent/V>,<child/V>,[pred/V]
Function
Adds child to parent.

The rules are:

  1. child bust be free
  2. parent and child must be compatible
Inputs
parent - the object to add child to
child - the object to add to parent
pred - add child after this (only for Menu and Menuitem)
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_MEM] not enough resources to complete the operation
[NO_OBJ] parent or child not found
[BUSY_OBJ] child is busy
See
Remove()
Example
call DoMethod("group","InitChange")
call Remove("old_obj")
call Add("group","new_obj")
call DoMethod("group","ExitChange")

Index

AppMessage

Instructs RxMUI to receive APPEVENT.
Synopsis
res = AppMessage(obj)
<obj/V>
Function
Tells RxMUI you want to receive APPEVENT when an icon is dropped into obj.

The rules are:

  1. obj can be any kind of object not only a window
  2. obj must be in a window linked to an application
Inputs
obj - the object you want to receive APPEVENT from
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_MEM] not enough resources to complete the operation
[NO_OBJ] obj not found
See
Object handling

Index

AppPushId

Returns an export key.
Synopsis
res = AppPushID(app)
<app/V>
Function
This function returns a key ID to be used with PushMethod().

You pass it the name of an Application object and it will return a key string ID that can be exported to another ARexx macros and used with PushMethod().

The result is NOT of your interest: the only thing you can do is to match it with Null() to see if the function failed (may fail iff its argument is not an application).

This is the mechanism used to control a RxMUI object outside the macro where it was created (remember that MUI in itself is monotask oriented and RxMUI is supposed to be SAFE):

  • in macro A:
    • create your application
    • obtain a key with this function.
    • launch the other macro B and pass it the key
  • in macro B

    Any time PushMethod() is used in B , the macro B is suspended until the method reaches its goal. This makes the all thing very safe.

Inputs
app - the application to export
Result
key - a key or Null() for failure
The function may fail if:
[NO_OBJ] app not found or it is not an application object
Example
let's suppose you created an application object and a text object named "info":
  • in macro A:
        key = AppPushID("app")
        address command "run >nil: <nil: B" c2x(key)
  • in macro B:
        parse arg id
        id = x2c(id)
        call PushMethod(id,"info","set","contents","Ok, I started")
See
PushMethod()

Index

DandD

Instructs RxMUI to be prepared for drag and drop.
Synopsis
res = DandD(from,to,flags)
<from/V>,<to/V>,[options]
Function
Tells RxMUI to install a drag and drop mechanism from from to to .

options is one or more of:

  • AUTO - drag & drop is performed internally by RxMUI itself, between:
    • list <-> list
    • list <-> string
    • list -> text
    • string <-> string
    • string -> text
  • BOTH - the d&d is also from to to from
  • NOSELF - forbid an object (e.g. a List) to perform drag and drop within itself; the other flags are ignored, so d&d must be handled manually
  • REMOVE - remove dragged entries from a Listview
  • SORTED - insert entries sorted in a Listview

If you don't specify AUTO, drag and drop must be handled by yourself in the macro. Look at the examples.

Inputs
from - the drag start from this object
to - the drop goes to this object
options - see above
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_MEM] not enough resources to complete the operation
[NO_OBJ] from or to not found
[BAD_DANDD] objects are not compatible for an AUTO D&D operation
See
Object handling

Index

Dispose

Disposes an object.
Synopsis
res = Dispose(obj)
<obj/V>
Function
Disposes an object.

The rules are:

  1. The object can refuse to be disposed
  2. The object is first removed and then disposed
  3. Any notification to the object is killed
Inputs
obj - the object to dispose
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[BUSY_OBJ] obj is busy

Index

DoMethod

Invokes a method.
Synopsis
res = DoMethod(obj,method,parms)
<obj/V>,<method/V>,{parms}
Function
Invokes a method on an object.

Any class defines the rules for its own methods.

Note that the var RC will contain the real result from the method. It may be useful in some situation.

Inputs
obj - the object to invoke method on
method - a valid and direct method for obj
parms - parameters for method
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[NO_METHOD] method is not valid for obj
[METHOD_NOTIFYONLY] method may only be used in notifications
See
CoerceMethod() Methods

Index

CoerceMethod

Invokes a foreign method.
Synopsis
res = CoerceMethod(classObj,obj,method,parms)
<classObj/V>,<obj/V>,<method/V>,{parms}
Function
Invokes the method method of the class of classObj on obj.
Inputs
classObj - method is a method of the class of this object
obj - the object to invoke method on
method - a valid and direct method for classObj
parms - parameters for method
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj or classObj not found
[NO_METHOD] method is not valid for classObj
[METHOD_NOTIFYONLY] method may only be used in notifications
See
DoMethod() Methods

Index

PushMethod

Invokes a method on a foreign object.
Synopsis
res = PushMethod(keyID,obj,method,parms)
<keyID>,<obj/V>,<method/V>,{parms}
Function
Invokes a method on a object outside the macro where it was created.
Inputs
key - the key return by AppPushID()
obj - the object to invoke method on
method - a valid and direct method for obj
parms - parameters for method
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[NO_METHOD] method is not valid for obj
[METHOD_NOTIFYONLY] method may only be used in notifications
See
AppPushID()

Index

GetAttr

Reads an attribute.
Synopsis
res = GetAttr(obj,attr,var)
<obj/V>,<attr/V>,<var/V>
Function
Reads the value of an attribute of an object.
Inputs
obj - the object to read the attribute of
attr - the attribute to read
var - an ARexx var name where the value of attr will be written
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[ATTR_IS_NOT_G] the attribute can't be read
[BAD_SET_GET] the operation failed for some reason
Example
call GetAttr("string","contents","c")
say c
See
MultiGetAttr() xget()

Index

xget

Reads an attribute.
Synopsis
value = xget(obj,attr)
<obj/V>,<attr/V>
Function
Reads an attribute of an object and returns its value.

Warning: if the type of the attribute is String, the result is truncated to the first null char found.

Inputs
obj - the object to read the attribute of
attr - the attribute to read
Result
value - the value of the attribute
Example
say xget("string","contents")
See
MultiGetAttr() GetAttr()

Index

Handle

Handles an Application object.
Synopsis
res = Handle(app,stem,signals)
<app/V>,<stem/V>,[signals/N]
Function
Please, use this function sparely, because it uses many cpu time. Usually, you should use NewHandle(), except when there is a very hard need to wait for signals in the macro itself. I never had such a need.

Handles the object app of class Application.

Handling of applications in RxMUI is done via this function.

The standard cycle to do that 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
            if h.i==... then
            ...
        end
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit
    end

Handle() writes in stem.num the number of the entries to be parsed and in stem.i i=0,...,stem.num-1 the name of the object.

When stem.i is QUIT the application wants to exit and the user should exit from the macro or dispose the application.

Otherwise stem.i is the name of an object that notified the application via a

    res = Notify(obj,attr,value,"APP","RETURNID")

The cycle is very critical: if you do time consuming operation (ARexx is slow !!!) you should invoke the method INPUTBUFFERED on the application as in:

    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
            if h.i=="GO" then
                do i=0 to 1000
                    say i
                    call DoMethod("APP","INPUTBUFFERED")
                end
            end
        end
        s=Wait(or(h.signals,ctrl_c))
        if and(s,ctrl_c)~=0 then exit
    end

If you need to wait for other signals (e.g. for messages on a port) you can pass them to the rmh.library/Wait() function.

Inputs
app - the application to handle
stem - an ARexx stem name the function will fill
signals - signal received by wait()
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] app not found or it is not an application object
See
NewHandle() Object handling

Index

NewHandle

Handles an Application object.
Synopsis
res = NewHandle(app,stem,signals)
<app/V>,<stem/V>,[signals/N]
Function
Handles the object app of class Application.

Handling of applications in RxMUI is done via this function.

The standard cycle to do that is:

    ctrl_c=2**12
    do forever
        call NewHandle("APP","H",ctrl_c)
        if and(h.signals,ctrl_c)>0 then exit
        if h.EventFlag then
            select
                when h.event="QUIT" then exit
                when h.event==... then
                ...
            end
    end

As you can see the difference with Handle() is that NewHandle() always returns just one event and waits internally for the signals.

You should use Handle() only in the case you really have to wait for the signals in your code (e.g. you have to call rxsocket.library/WaitSelect() to wait for sockets events).

NewHandle() reads from stem:

  • .NoWait - a boolean which indicates if the function should wait for signals or not. Default is 0.
    • NewHandle() writes in stem:

      • .EventFlag - a boolean which indicates that there is an event to be dispatched
      • .Event - the name of the event that triggered a notification to the application.
      • .Signals - the signals received

      When stem.event is QUIT the application wants to exit and the user should exit from the macro or dispose the application.

      Otherwise stem.event is the name of an object that notified the application via a

          res = Notify(obj,attr,value,"APP","RETURNID")

      If you need to wait for other signals (e.g. for messages on a port) you can pass them in signals.

Inputs
  • app - the Application object to handle
  • stem - stem name the function will fill
  • signals - user signals to wait for
Result
res - 0 for success or >0 for failure
See
Handle() Object handling

Index

Notify

Adds a notification.
Synopsis
res = Notify(notifier,attr,value,target,method,parms)
<notifier/V>,<attr/V>,<value/V>,<target/V>,<method/V>,{parms}
Function
Adds a notification from notifier to target triggered by attr when it changes to value invoking method on target with parms.
Inputs
notifier - the object that notifies
attr - the attribute that triggers the notification
value - the value of attr that causes the notification
target - the target of the notification. Specials values are:
  • _app - the application notifier belongs to
  • _win - the window notifier belongs to
  • _self - notifier itself
method - a valid an indirect method to invoke on target
parms - parameters for method 
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] notifier or target not found
[NO_METHOD] method is not valid for target
[METHOD_NONOTIFY] method is direct-only
[BAD_NOTIFY] the notification can't be added for some reason
See
Notification

Index

Help

Returns RxMUI functions help strings.
Synopsis
string = help(fun)
<fun>
Function
Returns the help string associated with the function fun.

The same string can be obtained with rxhelp.

Inputs
fun - a RxMUI function name
Result
string - the help string for fun

Index

KillNotify

Kills notifications.
Synopsis
res = KillNotify(from,to)
<from/V>,<to/V>
Function
Kills any notification from from to to.
Inputs
from - the notifier
to - the notified
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] from or to not found
See
Notification

Index

NewObj

Creates an object.
Synopsis
res = NewObj(className,objName,stem,freeChild)
<class/V>,[name/O],[stem/V],[freeChild/N]
Function
Create an object of class class named name reading its attributes from stem, if present, or name.

freeChild makes NewObj() destroy all the internal buffers and resets child stems.

Note that during object creation, all the objects defined in name itself or stem, if supplied, are created.

Inputs
class - the class the object is istance of
name - the name of the object
stem - Init attribute are here, if present
freeChild - reset children - default 1
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_MEM] not enough mem to complete the operation
[BAD_VALUE] some Init attributes was set to a bad value
[BAD_NUMBER] some Init attributes was set to a bad number
[NO_CLASS] class not found
[NO_MUI] a required MUI class not found
[NO_MCC] a required MCC not found
[NO_RXMEC] a required rxmec not found
See
Objects creation

Index

XNewObj

Creates an object.
Synopsis
name = XNewObj(className,objName,stem,freeChild)
<class>,[name/O],[stem/V],[freeChild/N]
Function
Create an object of class class named name reading its attributes from stem, if present, or name.

freeChild makes XNewObj() destroy all the internal buffers and resets child stems.

Inputs
class - the class the object is istance of
name - the name of the object
stem - Init attribute are here, if present
freeChild - reset children - default 1
Result
name - the name of the object or an empty string on failure
The function may fail if:
[NO_MEM] not enough mem to complete the operation
[BAD_VALUE] some Init attributes was set to a bad value
[BAD_NUMBER] some Init attributes was set to a bad number
[NO_CLASS] class not found
[NO_MUI] a required MUI class not found
[NO_MCC] a required MCC not found
[NO_RXMEC] a required rxmec not found
See
Objects creation

Index

Remove

Removes an object.
Synopsis
res = Remove(obj)
<obj/V>
Function
Remove obj from its parent.

The rules are:

  1. The object may refuse to be removed
Inputs
obj - the object to remove
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[BUSY_OBJ] obj is busy
See
Objects creation

Index

Set

Writes the value of an attribute of an object.
Synopsis
res = set(obj,attr,value)
<obj/V>,<attr/V>,<value>,[NoNotify/N]
Function
Sets ONE attribute of ONE object.
SetAttr() is a synonymous for set().
Inputs
obj - the object to set the attribute of
attr - the S-attribute to set
value - the value of the attribute
NoNotify - an ARexx boolean that indicates to the function to perform a nnset rather that a set
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[BAD_NUMBER] bad integral number format
[BAD_VALUE] the type of value is not compatible with the type of attr
[BAD_SET_GET] the attributes can't be set for some reason
Example
call set("win","open",1)
See
MultiSetAttrs() SetAttrs() SetClassAttrs()

Index

SetAttrs

Sets many attributes of an object.
Synopsis
res = SetAttrs(obj,stem)
<obj/V>,<stem/V>
Function
Sets many attributes of an object at once.
Inputs
obj - the object to set the attributes of
stem - an ARexx stem name
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] obj not found
[BAD_NUMBER] bad integral number format
[BAD_VALUE] the type of a value is not compatible with the type of an attribute
[BAD_SET_GET] the attributes can't be set for some reason
Example
set.Disabled=1
set.Contents="I am disabled"
call SetAttrs("string","set")
See
MultiSetAttrs() set() SetClassAttrs()

Index

SetClassAttrs

Sets many foreign attributes of an object.
Synopsis
res = SetAttrs(class,obj,stem)
<class/V>,<obj/V>,<stem/V>
Function
Sets many attributes of the class class of an object at once.
Inputs
class - the class the attributes to set belong to
obj - the object to set the attributes of
stem - an ARexx stem name
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_CLASS] class not found
[NO_OBJ] obj not found
[BAD_NUMBER] bad integral number format
[BAD_VALUE] the type of a value is not compatible with the type of an attribute
[BAD_SET_GET] the attributes can't be set for some reason
Example
set.Value=0
call SetAttrs("Slider","group","set")
See
MultiSetAttrs() set() SetAttrs()

Index

MultiGetAttr

Reads the values of an attribute of many objects.
Synopsis
res = MultiGetAttr(stem)
<stem/V>
Function
Reads the values of an attribute of many objects at once.
Inputs
stem - a stem name where to set the couple object/attribute in the field .N .n.attr and where the function will write the values in .N.value (n=0,...).
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] one object not found
[BAD_SET_GET] one attribute can't be read for some reason
Example
get.0="host";     get.0.attr="Contents"
get.1="hostport"; get.1.attr="Integer"
call MultiGetAttr("get")
say get.0.value
say get.1.value
See
GetAttr() xget()

Index

MultiSetAttr

Writes an attribute of many objects.
Synopsis
res = MultiSetAttr(stem)
<stem/V>,[NoNotify/N]
Function
Writes an attribute of many objects at once.
Inputs
stem - a stem name where to specify the object/attribute/value to set
NoNotify - an ARexx boolean that indicates to the function to perform a nnset rather that a set
Result
res - 0 for success or >0 for failure
The function may fail if:
[NO_OBJ] one object not found
[BAD_NUMBER] bad integral number format
[BAD_VALUE] the type of a value is not compatible with the type of an attribute
[BAD_SET_GET] one attribute can't be set for some reason
Example
set.0="host"; set.0.attr="contents";set.0.value="www.amiga.org"
set.1="hostport"; set.1.attr="integer"; set.1.value = 80
call MultiSetAttr("set")
See
set() SetAttrs()

Index

Button

Creates a button.
Synopsis
oname = button(name,text)
[name/O],[text];
Function
Creates a button object named name with text as label.
Inputs
name - the name of the button
text - the label of the button
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
See
Text class

Index

ToggleButton

Creates a toggle button.
Synopsis
oname = ToggleButton(name,text,selected)
[name/O],[text],[selected/N]
Function
Creates a toggle button object named name with text as label in selected state.
Inputs
name - the name of the button
text - the label of the button
selected - the state of the button
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
See
Text class

Index

Checkmark

Creates a checkmark.
Synopsis
oname = checkmark(name,selected)
[name/O],[selected/N],[cchar]
Function
Creates a checkmark object named name in selected state.
Inputs
name - the name of the checkmark
selected 0 the object is not selected, 1 the object is selected 
cchar - the control char for the object
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
See
Image class

Index

HBar

Creates a HBar.
Synopsis
oname = HBar(pixels)
[pixels/N]
Function
Creates a HBar object.
Inputs
pixels - the width in pixels; if not supplied or 0, the bar will be horiz unlimited
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

VBar

Creates a VBar.
Synopsis
oname = VBar(pixels)
[pixels/N]
Function
Creates a VBar object.
Inputs
pixel - the height in pixels; if not supplied or 0, the bar will be vert unlimited
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

HSpace

Creates a horiz space.
Synopsis
oname = HSpace(pixels)
[pixels/N]
Function
Creates a horiz rectangle object.
Inputs
pixels - the width in pixels; if not supplied or 0, the object will be horiz unlimited
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

HFSpace

Creates a horiz space.
Synopsis
oname = HFSpace(string)
[string]
Function
Creates a horiz rectangle object with a fixed width as the width of the given string.
Inputs
string - the rectangle width (default X)
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

VFSpace

Creates a vert space.
Synopsis
oname = VFSpace(string)
[string]
Function
Creates a vert rectangle object with a fixed height as the height of the given string.
Inputs
string - define the rectangle height (default A)
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

VSpace

Creates a vert rectangle object.
Synopsis
oname = VSpace(pixels)
[pixels/N]
Function
Creates a vert rectangle object.
Inputs
pixels - the height in pixels; if not supplied or 0, the object will be vert unlimited
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

HVSpace

Creates a rectangle object.
Synopsis
oname = HVSpace(hpixels,vpixels)
[hpixels/N],[vpixels/N]
Function
Creates a rectangle object.
Inputs
hpixels - the width in pixels; if not supplied or 0, the object will be horiz unlimited
vpixels - the height in pixels; if not supplied or 0, the object will be vert unlimited
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

HWSpace

Creates a rectangle object.
Synopsis
oname = HWSpace(hpixels,vpixels)
[weight/N]
Function
Creates a rectangle object.
Inputs
width - the weight; default 100
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

VWSpace

Creates a rectangle object.
Synopsis
oname = VWSpace(hpixels,vpixels)
[weight/N]
Function
Creates a rectangle object.
Inputs
width - the vert weight; default 100
Result
oname - an empty string on failure; on success, the name of the object as an internal string
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Rectangle class

Index

MenuItem

Create a menuitem
Synopsis
oname = MenuItem(name,title,shortcut,checked,checkit,enabled)
[name/O],[title],[shortcut],[flags],[exclude/N]
Function
Creates a Menuitem object. title can be the special value "BAR" to create a bar. If no argument or just name is supplied, a bar is created.
Inputs
name - the name of the object
title - the title of the item
shortcut - the shortcut for the item
flags - One or more of:
  • CHECKED
  • CHECKIT
  • DISABLED
  • TOGGLE
exclude - the mutual exclude mask
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
See
MakeObj Menu class

Index

Label

Creates a label. 
Synopsis
oname = label(text,flags)
<text>,[flags]
Function
Creates un unnamed label object.
The text is right aligned by default. The char _ may be used to underline a char.

flags is one or more of:

  • Left - the text is left aligned
  • Centered - the text is centered
  • Single - the object gets a phantom single frame
  • Double - the object gets a phantom double frame
  • Free - the object is horiz/vert unlimited (otherwise it is limited by its text width/height)
The function has also the alternative forms:
  • label1(text) -> label(text,SINGLE)
  • llabel1(text) -> label(text,LEFT SINGLE)
  • clabel1(text) -> label(text,CENTERED SINGLE)
  • label2(text) -> label(text,DOUBLE)
  • llabel2(text) -> label(text,LEFT DOUBLE)
  • clabel2(text) -> label(text,CENTERED DOUBLE)
Inputs
text - the text of the label
flags - see above
Result
oname - an empty string on failure; an internal string on success
The function may fail if:
there are not enough resources to complete the operation
See
Text class MakeObj()

Index

MakeObj

Creates a MUI object. 
Synopsis
oname = MakeObj(name,type,parms)
[name/O],[type],{parms}
Function
Creates a MUI Object.

Type can be one of:

  • Balance - creates a Balance object.
    oname = MakeObj(oname,"Balance")
    -
  • BarTitle - creates a Bar with a title.
    oname = MakeObj(oname,"BarTitle",text)
    [text]
  • BetterBalance - creates a BetterBalance object.
    oname = MakeObj(oname,"BetterBalance",ObjectID)
    <ObjectID/N>
  • Busy - creates a Busy object.
    oname = MakeObj(oname,"Busy")
    -
  • ColGroup - creates a columned Group.
    oname = MakeObj(oname,"ColGroup",obj1,obj2,...)
    <cols/N>,<obj1>,{obj}
  • Cycle - creates a Cycle object.
    oname = MakeObj(oname,"Cycle",entries,key,active)
    <entries>,[key],[active/N]
  • Gauge - creates a horiz Gauge object.
    oname = MakeObj(oname,"Gauge",FixHeightTxt,max,current,InfoText)
    [FixHeightTxt],[max/N],[current/N],[InfoText]
  • HBar - creates a horiz Bar.
    oname = MakeObj(oname,"HBar",pixels)
    [pixels/N]
  • HCenter - center one object in a horiz Group.
    oname = MakeObj(oname,"HCenter",obj)
    <obj>
  • HFrameGroup - incapsulate one object in a horiz framed Group.
    oname = MakeObj(oname,"HFrameGroup",title,obj,class)
    [title],<obj>,[class]
  • HGroup - creates a horiz Group.
    oname = MakeObj(oname,"HGroup",obj)
    <obj1>,{obj}
  • HLeft - incapsulate one object in a horiz Group with a hspace at the right.
    oname = MakeObj(oname,"HLeft",obj)
    <obj>
  • HRight - incapsulate one object in a horiz Group with a hspace at the left.
    oname = MakeObj(oname,"HRight",obj)
    <obj>
  • HSpace - creates a horiz Space.
    oname = MakeObj(oname,"HSpace",pixels)
    [pixels/N]
  • ImageButton - creates an Image button.
    oname = MakeObj(oname,"ImageButton",ImgSpec,key,selected)
    [ImgSpec],[key],[selected/N]
  • Knob - creates a Knob.
    oname = MakeObj(oname,"Knob",keymin,max,val,default)
    [key],[min/N],[max/N],[val/N],[default/N]
  • Levelmeter - creates a Levelmeter.
    oname = MakeObj(oname,"Levelmeter",key,min,max,val,default)
    [key],[min/N],[max/N],[val/N],[label],[default/N]
  • Menu - creates a Menu.
    oname = MakeObj(oname,"Menu",title,obj1,...)
    <title>,{obj}
  • Menuitem - adds Menuitems to a Menuitem.
    oname = MakeObj(oname,"Menuitem",parent,child1,...)
    <parent>,{children}
  • Menustrip - creates a Menu strip.
    oname = MakeObj(oname,"Menustrip",menu1,...)
    {menus}
  • Numericbutton - creates a Numericbutton.
    oname = MakeObj(oname,"Numericbutton",key,min,max,val,format,default)
    [key],[min/N],[max/N],[val/N],[format],[default/N]
  • NumericString - creates a numeric String.
    oname = MakeObj(oname,"NumericString",key,min,max,MaxLen,val)
    [key],[min/N],[max/N],[MaxLen/N],[val/N]
  • Radio - creates a Radio object.
    oname = MakeObj(oname,"Radio",entries,key,active,horiz)
    <entries>,[key],[active/N],[horiz/N]
  • RowGroup - creates a rowed group.
    oname = MakeObj(oname,"RowGroup",rows,obj1,obj2,...)
    <rows/N>,<obj1>,{obj}
  • Scale - creates a Scale object.
    oname = MakeObj(oname,"Scale")
    -
  • Slider - creates a Slider.
    oname = MakeObj(oname,"Slider",key,min,max,val,format,default)
    [key],[min/N],[max/N],[val/N],[format],[default/N]
  • VBar - creates a vert Bar.
    oname = MakeObj(oname,"VBar",pixels)
    [pixels/N]
  • VCenter - center one object in a vert Group.
    oname = MakeObj(oname,"VCenter",obj)
    <obj>
  • VDown - incapsulate one object in a vert Group with a vspace at the bottom.
    oname = MakeObj(oname,"VDown",obj)
    <obj>
  • VFrameGroup - incapsulate one object in a vert framed Group.
    oname = MakeObj(oname,"VFrameGroup",title,obj,class)
    [title],<obj>,[class]
  • VGroup - creates a vert Group.
    oname = MakeObj(oname,"VGroup",obj1,...)
    <obj1>,{obj}
  • VSpace - creates a vert Space.
    oname = MakeObj(oname,"VSpace",pixels)
    [pixels/N]
  • VUp - incapsulate one object in a vert Group with a vspace at the top.
    oname = MakeObj(oname,"VUp",obj)
    <obj>
Inputs
name - the name of the object
type - the type of the object
parms - parameters
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
same sub object creation failure; it may happens especially if:
[NO_MUI] a required MUI class not found
[NO_MCC] a required MCC not found
[NO_RXMEC] a required rxmec not found
Example
  1. Imagebutton
    po.Button=MakeObj(,"Imagebutton","PopUp")
  2. Menustrip
    app.Menustrip=MakeObj(,"Menustrip",,
        MakeObj(,"Menu","Project",,
            Menuitem("mabout","About...","?"),,
            Menuitem("maboutrxmui","About RxMUI..."),,
            Menuitem("maboutmui","About MUI..."),,
            Menuitem("","BAR"),,
            Menuitem("mhide","Hide","H"),,
            Menuitem("","BAR"),,
            Menuitem("mquit","Quit","Q")),,
        MakeObj("medit","Menu","Editor",,
            MakeObj(,"Menuitem",Menuitem("mtest","Test"),,
                Menuitem("mtest1","Show all",,"CHECKED CHEKIT TOGGLE",6),,
                Menuitem("mtest2","Show left",,"CHEKIT TOGGLE",5),,
                Menuitem("mtest3","Show right",,"CHEKIT TOGGLE",3))))
  3. A complex group
    group = MakeObj(,"HFrameGroup","Numeric Buttons",,
        MakeObj(,"HCenter",,
            MakeObj(,"ColGroup",2,,
                Label("Low:"),,
                MakeObj(,"HGroup",,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%")),,
                Label("Mid:"),,
                MakeObj(,"HGroup",,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%")),,
                Label("High:"),,
                MakeObj(,"HGroup",,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%"),,
                    MakeObj(,"NumericButton",,,,,"%ld %%")))))

Index

String

Creates a string.
Synopsis
oname = string(name,cchar,contents,max)
[name/O],[cchar],[contents],[max/N]
Function
Creates a string object.
Inputs
name - the name of the object
cchar - the control char for the object
content - the initial content
max - max number of chars
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
[NO_MCC] a required MCC not found
[NO_RXMEC] a required rxmec not found
See
MakeObj String class

Index

Text

Creates a text object. 
Synopsis
oname = text(name,text,frame,background,preparse)
[name/O],[text],[frame],[background],[preparse]
Function
Creates a text object.
Inputs
name - the name of the object
text - the initial content of the object
frame - the frame for the object - default TEXT
background - the background for the object - default TEXTBACK
preparse - the preparse for the object - default \\33c
Result
oname - an empty string on failure; on success, the name of the object, as an internal string if name was omitted or it was specified as an empty string, name itself otherwise
The function may fail if:
there are not enough resources to complete the operation
See
Text class

Index

ParseText

Parses text.
Synopsis
parsedtext = ParseText(text)
<text>
Function
Parses a text, translating it to the MUI text engine format.

Refer to the MUI text class autodoc.

The changes made on text are:

  • %c is changed to \\33c ("1B"x || c) (where c is ANY char)
  • \n is changed to "0A"x
  • \r is changed to "0D"x

To display:

  • \ use \\
  • % use \%

Without this function the strings to pass as Contents attribute of Text class, as Text argument in Button() or as entry of a List object would be too complicated.

Inputs
text - the text to parse 
Result
parsedText - the text parsed

Index

StripText

Strip dangerous codes from text.
Synopsis
stripped = StripText(text)
<text>
Function
Anytime you are going to set a Contents of a Text object or you are adding an entry to a (N)List and so on, and the text comes from a non trustable source (e.g. from the Internet), you should strip dangerous MUI Text Engine codes via this function. It will return a clean text that may be used with no worries.

Note that the function may not fail: if no mem is available it just returns an empty string.

Inputs
text - the text to strip
Result
stripped - the text stripped

Index

Child

Defines a child. 
Synopsis
call child(parent,name,class)
<parent/V>,<name/V>,[class/O]
Function
To use at object specification phase.
    call child("G","S","STRING")

just tells RxMUI to:

  • init g.0 to S - if it is the first time that child("G" ... ) is used
  • init g.i to S - if it the i-th time that child("G" ...) is used s.class="STRING"

A often used form is as in

    call child("MPROJECT",Menuitem("MOPEN","Open","O"))
Inputs
parent - the container, parent of name
name - the name of the object, child of parent
class - the class of name
Result
none
See
NewObj()

Index

MUIRequest

Shows a requester. 
Synopsis
res = MUIRequest(app,win,title,gadgets,text)
[app/O],[win/O],[title],[gadgets],[text]
Function
Shows a MUI requester.

This function is discouraged. Use it sparely, just to show errors and then exit.

If you have to report messages to the user, you should better open a little window with a text (floattext) object and use it.

Inputs
app - the name of an application object
win - the name of a window object that belongs to app
title - the title of the requester
gadgets - a string containing the text for the gadgets separated with a |
text - the MUI text of the requester
Result
res - the number of the gadget the user pressed to exit from the requester, with the usual requester-gadgets convection.

Index

SetRxMUIStack

Set RxMUI stack size. 
Synopsis
call SetRxMUIStack(size)
<size/N>
Function
Sets the RxMUI swap-stack size of the macro.

Every RxMUI function is executed under a stack swap.

Default stack size is 24k, but in certain situation with some object, e.g. with NListview, a very large stack is required. You can set the stack size with this function. RxMUI will allocate the new stack iff size is >16k bytes. If the stack can not be allocated error 3 is generated.

Inputs
size - the new stack size
Result
none

Index

GetRxMUIString

Returns an error string. 
Synopsis
res = GetRxMUIString(id)
<id/N>
Function
The strings are read from the catalog rxmui.catalog if present.

At this moment RxMUI errors code are:

51 NO_MEM too few memory
Not enough resources to perform the required operation, e.g. no mem or no Exec signal available.
52 ARG_MISS required argument missed
A required arguments was not supplied, e.g. attempt to create a Cycle object without defining the attribute Entries.
53 BAD_NUMBER bad number
The format of an integral number is not valid.
54 BAD_VALUE bad value
The value of an argument is not valid, or not in the range of the accepted values and so on.
55 NO_CLASS can't find class
Attempt to create an object of a class that can't be found. It might also mean that an external RxMUI class is missed.
56 OBJ_EXISTS object already exists
Not used.
57 NO_OBJ can't find object
An object can't be found.
58 BUSY_OBJ object is busy
An object is currently busy, e.g. attempt to add an object that was already added or attempt to use a Menustrip, used by an Application object as Menustrip, as Contextmenu of another object and so on.
59 OBJ_CANT_BE_ADDED incompatible objects
A couple of objects was interested in an operation but the objects are not compatible for that operation, e.g. attempt to add a Window object to a Group and so on.
60 CANT_CREATE_OBJ object not created
The object was not created for some reason.
61 BAD_SET_GET bad attribute set or get
The reading/setting attributes operation failed for some reason.
62 OBJ_CANT_BE_DISPOSED object can't be disposed
Attempt to dispose an object failed, because the object is in use somewhere, e.g. it is a Contextmenu or it is part of a Popstring object and so on.
63 OBJ_CANT_BE_REMOVED object can't be removed
Attempt to remove an object failed, because the object is in use somewhere, e.g. it is part of a Popstring object and so on.
64 BAD_DANDD incompatible objects for D&D
Attempt to set up an automatic Drag and Drop failed, because RxMUI doesn't know how to handle the Drag and Drop between the two objects.
65 BAD_ATTRS incompatible attributes
Attempt to set up a notification triggered by an attribute Everytime its value changes, invoking a method with a Triggervalue parameter that has a different type than the triggering attribute.
66 NO_ATTR can't find attribute
Attempt to perform an operation with an unknown attribute.
67 ATTR_IS_NOT_S attribute is not settable
Attempt to set an attribute that is not S.
68 ATTR_IS_NOT_G attribute is not readable
Attempt to read an attribute that is not G.
69 ATTR_IS_NOT_N attribute is not notificated
Attempt to set up a notification with a triggering attribute that is not N.
70 NO_METHOD can't find method
A method can't be found.
71 METHOD_NOTIFY_ONLY the method can be notified only
Attempt to directly use a notify-only method in DoMethod().
72 METHOD_NONOTIFY the method can't be notified
Attempt to set up a notification with a direct-only-method.
73 BAD_NOTIFY can't add notify
Attempt to set up a notification failed for some reason.
74 BAD_TRIG_ATTR notify condition never true
Attempt to set up a notification with a triggering condition that can't be never true, e.g. the trigger attribute has type S and the trigger value is not Everytime.
75 NO_MCC can't find MUI custom class
Attempt to create an object of a class that is a subclass of a MUI Custom Class that can't be found. E.g. attempt to create a HTLMview object and HTMLview.mcc is not present in MUI:Libs/MUI drawer.
76 NO_MUI can't find MUI class
Attempt to create an object of a class that is a subclass of a MUI Class that can't be found. E.g. attempt to create a Knob object and Knob.mui is not present in MUI:Libs/MUI drawer.
77 NO_RXMEC a required rxmec not found
Attempt to create an object of a class that is a subclass of a RxMUI class, which can't be init or found. It might mean that a RxMUI external class is missed or that there are not enough resources to perform the operation.

If an error is returned the var RxMUIErr is set to something meaningful, if possible.

Inputs
id - the id of the error string 
Result
res - the string associated with id

Index

RxMUIOpt

Sets or reads RxMUI options. 
Synopsis
res = RxMUIOpt(options)
<options>
Function
options is one or more of:
  • DebugMode - Default 1
  • ShowErr - Default 1

When many objects are created via one single NewObj() call, if an object anywhere can not be created, all the created objects are disposed and NewObj() returns an error code.

You have no way to know where the creation process stopped and the error was generated. During debugging of a macro is very useful to know exactly which object had problem and or where the problem appeared.

Setting DebugMode makes RxMUI to remember the first error it discovered in NewObj().

Setting ShowErr make RxMUI to show a MUI requester with info inside.

options may also be ASK in which case the string
rxmui.library ver.rev (date) [user] DefStack GlobalStack LocalStack DefMinStack GlobalMinStack LocalMinStack DefDebugMode GlobalDebugMode LocalDebugMode DefShowErr GlobalShowErr LocalShowErr
is returned.

Note that everytime rxmui.library is load, it checks for the environment vars:

  • RxMUI/DebugMode
  • RxMUI/ShowErr

You might change them to have personal global defaults.

Inputs
options - the options to set or ASK
Result
res - 1 or an info string

Index

RxMUIObjExists

Checks if an object exists. 
Synopsis
res = RxMUIObjExists(obj)
<obj/V>
Function
Checks if obj exists.
Inputs
obj - an object name
Result
res - An ARexx boolean

Index

RxMUIObjList

Returns the objects list. 
Synopsis
res = RxMUIObjList(obj)
[obj/V]
Function
Returns an object list string. For debugging porpoise.
Inputs
obj - returns the list of the child of this object
Result
res - The objects list.

Index

RxMUIGetVar

Gets a parent macro var.
Synopsis
value = RxMUIGetVar(var)
<var/S>
Function
Many classes permit you to define a inline-macro function to be execute on some events. It is the case of Application/Inline method or Popstring/OpenFun attribute. In the macro you have no access to the vars of the parent macro, but you may still obtain the value of a var via this function.
Inputs
var - the var to read
Result
value - the value of var

Index

RxMUISetVar

Sets a parent macro var.
Synopsis
value = RxMUIGetVar(var,value)
<var/S>,<value>
Function
Many classes permit you to define a inline-macro function to be execute on some events. It is the case of Application/Inline method or Popstring/OpenFun attribute. In the macro you have no access to the vars of the parent macro, but you may still set the value of a var via this function.
Inputs
var - the var to set
value - the value to set var to
Result
value - value itself

Index