Ringhio Notifications Arexx Interface

From wiki.amiga.org
Jump to navigation Jump to search

Introduction

Your application / script may comunicate with Ringhio via an AREXX interface instead of using IApplication->NotifyA()


AREXX interface

Ringhio accept the following AREXX commands:

REGISTERAPP APP/K, AREXXPORT/K, ICON/K, TEXT/F

The command shown above registers a new application with the server.


APP/K = application name (mandatory)

AREXXPORT = application AREXX port to be used in case of "back" message (optional)

ICON = full path to the application icon, without the ".info" appendix, to be used in the preference editor (optional)

TEXT = a short message describing the application purpose


The server will reply with one of the following messages:

OK, APP REGISTERED
ERROR: APP ALREADY REGISTERED
ERROR: NO APP NAME
ERROR: OUT OF MEMORY
ERROR: UNDEFINED ERROR
RINGHIO APP/K, UPDATE/S, CLOSEONDC/S, PRI/K, SCREEN/K, IMG/K, IMGVALIGN/K/N, LOGONLY/S, NOLOG/S, TITLE/K, 
BACKRXMSG/K, PAUSEBACKRXMSG/K,  STOPBACKRXMSG/K, PERCENTAGE/K, TEXT/F

The command shown above sends a message to the server to be displayed.


APP = application generating the message (application need to be registered first) (mandatory)

UPDATE = allows an application to delete all previous currently displayed or queued popup messages and show a new one with updated information

CLOSEONDC = the pop-up message may be closed upon double-clicking on it

PRI = priority of the message (from 0 to 10), notifications with a priority = 10 will remain on screen until the user explicity close it

SCREEN = name of the public screen where to show the pop-up message, if omitted it will use the WB screen. as additional parameter, could be used SCREEN=FRONT to use the front screen (optional)

IMG = full path to an image to be displayed within the pop-up message, max dimension 32 x 32, any format supported by datatypes (optional)

IMGVALIGN = vertical alignment for the image to be displayed within the pop-up message, the allowed values are: 0=TOP, 1=MIDDLE, 2=BOTTOM

LOGONLY = Informes the server to log the message, no pop-up will be showed

NOLOG = Informes the server to not log the message

TITLE = title of the text message to be displayed, will be rendered in BOLD (optional) Currently max 64 chars are displayed, if the text is longer it will be cutted.

BACKRXMSG = an AREXX message to be sent back to the calling application when double clicking on the pop-up message, the application need to provide an AREXXPORT when registering with the server (optional) In alternative, it's possible to open an url into a browser, just use it that way: BACKRXMSG="URL:http://www.yoururl.net" In this case, an AREXX Port isn't needed but requires launch-handler or OpenUrl installed.

PAUSEBACKRXMSG = an AREXX message to be sent back when the user click on the PAUSE button, the PAUSE button will be displayed when this back message is specified

STOPBACKRXMSG = an AREXX message to be sent back when the user click on the STOP button, the STOP button will be displayed when this back message is specified

PERCENTAGE = show a notification message with a progress bar, (value from 0 to 100)

TEXT = text message to be displayed, currently max 160 chars are displayed, if the text is longer it will be cutted.


To be noted, the server may reject incoming messages if there are too many messages in queue, or if there are other errors such has low memory etc.

The server will reply with one of the following messages:

OK, MSG QUEUED
ERROR: TOO MANY MESSAGES QUEUED
ERROR: APP NOT ALLOWED
ERROR: APP NOT REGISTERED
ERROR: NO APP NAME
ERROR: OUT OF MEMORY
ERROR: UNDEFINED ERROR

Check the rx_testringhio.rexx script in the archive for a basic example on how register your app with Ringhio, show pop-up messages, or log a message.