Python MAEApp

Index Home MAE Python Interface > Python Index > Python MAEApp

Module MAEApp

Public Properties

Public Methods

setfield(device, table, field, value)

Update/Replace the table and field entry with the value provided

Return value: true if sent successfully

settext(device, text, style)

Replace the display region with the text provided.

Return value: true if sent successfully

write(device, text, style)

Append to the display reagion with the provided text for the user specified

Return value: true if sent successfully

writeln(device, text, style)

Append to the display reagion with the provided text for the user specified, followed by a line break.

Return value: true if sent successfully

writewiki(device, text)

Convert the text from wiki text (see wiki2doc) and display to the display region.

Return value: true if sent successfully

addhotspot(device, text, action, cbdata, style)

Append the tagged area with the provided text for the user specified and make it a hot spot that triggers an action.

Return value: true if sent successfully

addhinttext(device, text)

Provide hint text to the end-user for the display region. Exact implementation up to the end interface, but it may be to display text when the user hovers over the display region.

Return value: true if sent successfully

button(device, text, action, cbdata)

Append the tagged area with the provided text on a button for the user on the device specified. When clicked, it triggers a a message with the action and callback data.

format(device, control, on)

DEPRECATED - use style() instead.  Update the current display style state.

Return value: true if sent successfully

newregion(device, newtag, styleName, size)

Create a new display region inside device's current display region.

Return value: true if sent successfully

style(device, styleName)

Set the named display style for device's current display region.  See the configured properties of the style in the appropriate end-user display type (e.g. usergw uses HTML CSS).

Return value: true if sent successfully

attention(device, text)

Display a message to get the user's attention.

Return value: true if sent successfully

selection(device, value)

When a display region contains a selector, set the active selection to the value provided. If the value is not a valid selection, behavior is undefined.

Return value: true if sent successfully

chat(device, from, text)

Send a chat message to the end-user's device.

Return value: true if sent successfully

clear(device)

Clear all displayed objects and text from the current display region of the device.

Return value: true if sent successfully

show(device)

Display the objects and text inside the current display region of the device.

Return value: true if sent successfully

hide(device)

Hide the objects and text inside the current display region of the device. Make them non-visible.

Return value: true if sent successfully

newtable(device, tableName, tableType, rows, columns)

Create a table display region on the user'd device. It will be setup with the rows and columns specified.  Note that referencing one column more to the right will create that column; and referencing one more row below will create that row.

Return value: true if sent successfully

newlist(device, name, items)

Create a bulleted list that can contains items. Note that adding a list item immediately beyond the end will expand the list.

Return value: true if sent successfully

record(device, recordName, idmap, values, overwrite)

Output a record of information using a templte to map old UI ids to new ones.  For idmap, the key is the old id and the value is the new id

Return value: true if sent successfully

report(device, reportName, table, table_id)

FUTURE USE.  Output a report of information

Return value: true if sent successfully

prompt(device, query, value, promptType, xid, style)

Present the user with a question and response (text entry) box. The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

select(device, option0, options, xid, selected)

Present the user with a selection of choices.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

checkbox(device, query, value, xid, style)

Present the user with a selection of choices as checkboxes.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

textarea(device, text, xid, style, saveLabel)

Present the user with an area to type a lot of text.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

form(device, formName, vars, xid)

Present the user with input form template.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

screen(device, name, rows, columns)

Create a terminal screen of the specified size on the user's device.

Return value: true if sent successfully

scrattr(device, attributes)

Set the current terminal screen attributes for the next character(s) to be written.

Return value: true if sent successfully

scrchar(device, row, column, letter, amount)

Write a character to the terminal screen previously defined at device's display region.

Return value: true if sent successfully

setmenu(device, menu, option, command)

Configure the end-user's device with the menu option under the specified menu.  When the end-user selects it, the specified command will be sent as a message request of the app.

Return value: true if sent successfully

unsetmenu(device, menu, option)

Remove the menu option under the specified menu on the end-user's device.

Return value: true if sent successfully

setwindow(device, windowName)

Configure the end-user's device with a window, titled with the name provided.

Return value: true if sent successfully

unsetwindow(device, windowName)

Remove/Close the named window from the end-user's device.

Return value: true if sent successfully

setindex(device, indexName)

Configure the end-user's device with the index (tab).  

Return value: true if sent successfully

unsetindex(device, indexName)

Remove the named index from the end-user's device.

Return value: true if sent successfully

newsection(device, title, sectionType, newtag)

Add a section the the UI.  Sections can be manipulated, for example expanded/collapsed.

Return value: true if sent successfully

collapseSection(device)

Collapse the section identified as the current display region.

Return value: true if sent successfully

expandSection(device)

Expand the section identified as the current display region.

Return value: true if sent successfully

displayImage(device, imageName, image_type, action, cbdata, append)

Display the referenced buffered image that has already been transferred to display channel. If an action is provided, the image can be clicked on to trigger the action with its callback data.

Return value: true if sent successfully

displayImage(device, image_id, action, cbdata, append)

Display the referenced buffered image that has already been transferred to display channel. If an action is provided, the image can be clicked on to trigger the action with its callback data.

Return value: true if sent successfully

playAudio(device, audioName)

Play the referenced audio sound.  

Return value: true if sent successfully

download(device, query, fileclass, xid)

Request that the user send the app a file.

Return value: true if sent successfully

upload(device, imageName, image_type)

Send a file to the end-user's device that has already been transferred to display channel.  

Return value: true if sent successfully

imagelibpre(device, id)

Pre-fetch and image from ImageLib.  

Return value: true if sent successfully

bufimage(device, imageName, image_type, width, height, size, binary, chunk, totalChunks, chunksize, data)

Send a chunk of data to the display chennel (to fit within a message max size).

Return value: true if sent successfully

setvar(device, variable, value)

Alter a end-user device built-in variable value.

Return value: true if sent successfully

getvar(device, variable, value)

Alter a end-user device built-in variable value.

Return value: true if sent successfully

run(device, appname, startParams)

Switch the user from running one app to a different app using the provided parameters.

Return value: true if sent successfully

stop(device)

Stop running the current application.

Return value: true if sent successfully

userAccountChange(userId, action, value)

Take an action on a user's account.

Return value: true if sent successfully

registerApp(appmode, apptype, action, contentInputType, contentOutputType, operations, msgchannel, privatePages)

Register an app mode with UserGW. This captures all URL activity for URLs that begin with that appmode.

Return value: true if sent successfully

startraw(device, statusCode, contentType)

Declare to UserGW that response output is ready to send.

Return value: true if sent successfully

writeraw(device, text, isBinary)

Output text to the connection without modifying the text at all.  If the text is binary, it is converted from hex codes to binary before transmission.

Return value: true if sent successfully

closeraw(device)

Append to the display reagion with the provided text for the user specified

Return value: true if sent successfully

send(request, params)

simpleEncrypt(text, offset)

Return str value:

simpleEncryptLike(text, likeOtherText)

Return str value:

isSimpleEncrypted(text)

Return bool value:

simpleDecrypt(text)

Return str value:

prompt(device, question, prefillAnswer, queryType, cbapp, cbtag, cbdata, style)

select(device, question, choices, cbtag, cbdata, defaultValue)

textarea(device, question, origText, cbtag, cbdata, style, saveButtonLabel)

checkbox(device, question, cbtag, cbdata, defaultValue, style)

form(device, formName, formDefaults, cbtag, cbdata)

run(device, appname, appparams)

download(device, query, cbtag, cbdata, fileclass)

registerMenu(device, menuname, menuoption, action)

registerKey(device, keystroke, action)

registerHotspot(device, region, action)

redirectHotspot(device, region, otherapp)

error check

registerMouse(device, region, action)

registerCommand(device, cmd, cmdparams)

send(request, params)

htmlize(url)

Converts a string to a string usable inside HTML code.

The returned pointer should be free()ed by the calling routine.

Return str value:

urlize(url)

Operations performed:

change % to %25

change = to nothing

change + to %3b

change space to %20

change # to %23

Return str value:

sendImage(device, iid, errmsg, action, cbdata)

saveToImageLib(device, filename, filetype, filecontent, xid, category)

saveToImageLib(image_id, filename, filetype, filecontent, category)

updateImageLib(image_id)

saveToImageLib(image_id, filecontent)

setImageCategory(image_id, category)

setImageName(image_id, name)

setImageType(image_id, type)

newImage(table, id)

send(request, params)

response(device, xid, text)

chat(device, text)

cmd(device, cmd)

key(device, key)

click(device)

mouse(device, direction, x, y, action, cbdata)

hotspot(device, action, cbdata)

upload(device, fileclass, filetype, imagelibid, xid)

refresh(device)

select(device, value)

online(device, appparams)

withdraw(device)

timeout(device)

send(request, params)

open(name, mode, cbtag, cbdata)

putchar(ioId, c, ioChannel)

write(ioId, text, ioChannel)

write(ioId, data, ioChannel)

seek(ioId, offset, ioChannel)

lock(ioId, exclusive, wait, ioChannel)

unlock(ioId, exclusive, wait, ioChannel)

close(ioId, ioChannel)

fsverify(node, ioChannel)

fsreview(dirResourceId, ioChannel)

fsconfirm(node, size)

fsupdate(node, change, size)

ls(maepath)

stat(maepathandfilename, statbuf)

send(request, params, channel)

Class Cache

Public Methods

__init__(self, objType, size)

Constructor.

__del__(self)

Destructor

add(self, newKey, newOne)

Add a record to the cache. It must be valid().

Return int value:

removeKey(self, key)

Remove a record from the cache

Return bool value:

remove(self, pos)

Remove a record from the cache

Return bool value:

findPos(self, searchKey, fetchIfMissing)

Locate the cache position (-1 if not found)

Note: Pull into cache if fetchIfNotFound is True

Note: key must be a positive (non-zero) number

Return int value:

exists(self, searchKey)

Check if key exists in list

Return bool value:

get(self, key)

Get pointer to data for the key. Check if result is valid().

Note: key must be a positive (non-zero) number

__getitem__(self, pos)

This method allows the class instance to be indexed, e.g. HelloCache[2] to get the second element (not key==2)

Return value: the instance at position

__len__(self)

Return the size of the cache when using the len() function

Class Datastore

Summary

This class abstracts database protocols and allows an app to use this interface to perform database table queries and changes.

This class connects to dbbroker, which actually performs the database manipulation.  Note that dbbroker can be configured to connect to a variety of databases; this gets rid of app responsibility for database connection and syntax; an app can simply use the database.

It is safe (and convenient) to create an instance of this class for each table your program uses.

If you have an existing database table and you want to create a class interface to it, consider using genmae like this:

genmae db2h tablename > classname.h

genmae py classname.h > classname.py

Likewise, if you create .h file with the core class variables, you can use genmae to create the SQL code to setup the table, like this:

genmae h2sql classname.h > tablename.sql

Note that database manipulation commands will block program execution until a response from dbbroker is received.

Public Properties

Public Methods

__init__(self, tableName)

Constructor to initialize our data structure.  This does not yet setup the connection to dbbroker.

valid(self)

Determine status of our connection to database - is it valid?

Return int value: True if connected to db

status(self)

Get the status of the last request

Return int value: the status of the last request (see codes at top of Datastore.py)

statusOK(self)

Determine if the status of the last operator was successful.

Return bool value: True if last operation successful, False otherwise.

isOpen(self)

Determine if the database connection is established and ready.

Return bool value: True if db connection ready

statusMsg(self)

Return human readable status of last request.

Return str value: msg corresponding to last DB request

fieldNameToType(self, name)

fieldTypeToName(self, fieldtype)

Return str value:

errorMsg(self, rcToGetMsgFor)

Get the status message of the specified return code.

Return str value: the text of the error message

open(self, tableName)

Set the currently active table by opening it.

Return int value: the status code of the operation.

select(self, tableName)

Identifical to open().  Set the currently active table by opening it.

Return int value: the status code of the operation.

connected(self)

Check to make sure the database connection is working.

Return bool value: True if db responding to our requests

pack(self)

Pack the database (remove deleted records), if the database supports this.

Otherwise, it is ignored.

Return bool value: True upon success, False upon failure (see statusMsg())

close(self, specifiedTable)

Signal to close this database table.

@param table name of the table to close; if none, then last table used

Return bool value: True upon success, False upon failure (see statusMsg())

getTableList(self)

Get the list of defined tables.

Return value: the list of tables in the database

addField(self, fieldName, type, size, table, isIndex)

Obsolete. Add a field to the named database table.

Return 0 value: field id of new field

getFieldId(self, fieldName, table)

Query field id from field name for the named table.

Return int value: nonzero on success, 0 on failure

addFieldEnum(self, fieldName, enumName, enumId, table)

Obsolete.  Add field enumeration to the nanmed table.

Return int value: new enum value

getFieldType(self, fieldName, table)

Query a field type (string, float, etc) for the provided field name in the provided table.

Return value: the field type

addRecord(self, data, recno, table)

Add/Append a new record to the table provided, populated with the data provided.

Return value: new record number added

deleteRecord(self, recno, table)

Delete a record in the named table.

Return bool value: transaction status (see statusMsg())

lockRecord(self, recno, table)

Lock a record in the named table; prevent other applications from modifying this record until it is unlocked.

Return bool value: transaction status (see statusMsg())

unlockRecord(self, recno, table)

Unlock a record in the named table, allowing other applications to now modify it.

Return bool value: transaction status (see statusMsg())

clearField(self, recno, fieldName, table)

clear/empty the value for the field with this field name

Return bool value: transaction status (see statusMsg())

setValue(self, recno, fieldName, value, table)

change a string value identified by field ID

@param field name of the field in which to set the value

Return bool value: transaction status (see statusMsg())

setRecord(self, recno, newValues, table)

change several field values at once

@param newValue key/value pairs for new field/value changes

Return bool value: transaction status (see statusMsg())

getFieldInt(self, recno, fieldName, table)

get an int field value identified by field name

Return int value: the int value or -1 if unsuccessful

getFieldString(self, recno, fieldName, table)

get a string field value identified by field name

Return str value: the string value or zero length string if unsuccessful

getFieldFloat(self, recno, fieldName, table)

get a float field value identified by field name

Return float value: the float value or ??? if unsuccessful

getFieldEnumValue(self, recno, fieldName, table)

get an enum value identified by field name

Return str value: the enum value or zero length string if unsuccessful

getRecord(self, recno, fields, table)

get an int field value identified by field name

@param fieldName name of the field to get

Return value: key/value pairs of field/value values from record.  Error if empty, check status()/statusMsg().

getFieldEnumValueAsInt(self, recno, fieldName, table)

get an enum value as an int identified by field name

Return int value: the enum value or zero length string if unsuccessful

queryRecordsEnum(self, fieldName, value, sortby, table)

simple query for enum value by field name

Return list value: list of record numbers matching criteria

queryRecords(self, fieldName, value, sortby, table)

simple query for string value by field name

Return list value: list of record numbers matching criteria

queryRecords2(self, criteria, ANDed, sortby, table)

compound query for a field value

@param list list of field key/value pairs to be searched for

Return list value: list of record numbers matching criteria

queryExpr(self, expression, fields, sortby, table)

Using an expression, query records and return the requested fields, sorted if specified.

@param results - (output) a list of records and their fields that matched

Return bool value: True upon success

queryAllRecords(self, sortby, table)

query for all records in the named (or current) table

Return list value: recList with results which will be empty if unsuccessful

queryFieldNames(self, table)

query for all field names and types

Return value: XMLData which will be empty if unsuccessful. Otherwise key is field name, value is field type.

queryFieldIds(self, table)

query for all field names and types

connect(self)

Connect to database server.

In actuality, this only checks to make sure we're connected to the MAE daemon, commhub.

Return bool value: True on success; False on failure

doCommand(self, cmd, params)

Send a command for dbbroker that has no parameters. And wait for the reply.

Return bool value: True on success; False on failure

send(self, params)

Send data to commhub for DB operation

Return bool value: True if sent; False if failed

receive(self)

Wait for a dbbroker response from commhub.

Return bool value: True if reply received; False if not

encodeNewline(self, text)

commhub wants a comment to have new \n characters, so encode them

unencodeNewline(self, text)

commhub didn't let dbbroker send any \n characters, so unencode them

Class HashArray

Super class: dict

Summary

This class behaves a lot like the dict class, but with more control over the value types.

Note that all keys are strings.

Using HashArray

The HashArray data type is a key-value container.

It is typeless, but a specific type can be asserted (e.g. setBool()) or retrieved (e.g. getBool(), getInt(), etc).  It is up the the application to store/retrieve by type consistently.

This data type is very convenient for messaging.  Calling the toString() method converts the HashArray into a string.  Using the fromString() method or constructor converts it back.

Caveats

1. Numerical keys are not handled rigorously; unless numerical keys are set sequentially, you may get inconsistencies.
2. When used inside XMLData, keys must be identifers with alphanumeric characters; if non-alphanumerics are given, they will be converted to underscores when converted using toString().  XMLData requires keys to be valid XML tag identifiers.

Public Methods

__init__(self, value, separator)

Constructor

setProps(self, other)

Set the properties of the other HashArray into this HashArray, replacing any previous values

size(self)

Return the number of key-value pairs.

Return int value: # keys in hash array

empty(self)

Determine if there are no key-value pairs in the hash array.

Return bool value: True if there are no key-value pairs, False if there's at least one

set(self, key, value)

Assign a value into the dict

setBool(self, key, value)

Assign a boolean value to a key.

unset(self, key)

Remove a key/value pair from the dict

get(self, key)

Get a string value from the dict key

Return str value:

getInt(self, key)

Get a integer value from the dict key

Return int value:

getFloat(self, key)

Get a floating point value from the dict key

Return float value:

getDouble(self, key)

Get a double precision floating point value from the dict key. Same as getFloat().

Return float value:

getBool(self, key)

Get a boolean value from the dict key

Return bool value:

toString(self, separator)

Serialize the HashArray into a string.

isHashArray(text)

Examine the text string provided and determine if it's a HashArray or not.

Return bool value: True if text string is a serialized HashArray, False otherwise

fromString(self, text, separatorCharacter)

Take a text string that was generated by toString() and restore the data inside HashArray.

Return bool value: True if text could be fully decoded.

Class ImageLib

Using ImageLib

This class holds a reference to and then ultimately delivers the binary content of an image in the Image Library (the ImageLib table).  This class holds the image id, name, category, image type, height and width of the image.

Public Methods

__init__(self, id)

__init__(self, name, category)

clear(self)

__init__(self, data)

set(self, data)

append(self)

save(self)

toHashArray(self, forDB)

load(self, id)

Return bool value:

toString(self)

Return str value:

fromString(self, data)

Return bool value:

calcChecksum(self)

Return int value:

getName(self, id)

Return str value:

getHeightWidth(self, id, height, width)

Return bool value:

getType(self, id)

Return str value:

find(self, name, category)

Class Image

Summary

This class represents images within the MAE system.

Images may be drawn by the app or pulled from ImageLib database table.

Drawn images draw into a coordinate system with the size (height, width) and origin specified by the application.  For example, to create an image with a coordinate system that is 5 units wide and 4 units tall with the origin(0,0) in the center, you specify setSize(5, 4) and setOrigin(-2.5,-2).  How large the image is when it is displayed depends upon the unit size. If you'd like your 5 unit wide image to be 50 pixes wide, then specify setSize(5, 4, 10).

To display an image to the user, see the UserDevice class.

Use this class to communicate with imager, which renders them appropriately for the user.

Using Image

This data structure abstracts a vector image.  The API is used to describe the image.  It is not rendered into JPG, PNG, SVG, or other specific image technology until it is ready to be rendered to the end-user.  Rendering is performed by the imager daemon.

The API could be richer, but the API must be able to render to each of the ultimate image types.

The Image class may refer to an existing image file in a specific format via ImageLib class, which specifies where to retrieve the image and the image's size.

Graphics Commnds

setSize()

setSize(double newWidth, double newHeight, int newUnitSize)

Set the canvas dimensions and specify how many pixes per unit.  For example, a 4.0x5.0 image where unit size is 10 would create a 40x50 pixel image.

setOrigin()

setOrigin(double newOriginX, double newOriginY)

Specify how many units over the origin should be located if (0,0) is the lower left

setWindow()

setWindow(double minX, double minY, double maxX, double maxY, int newUnitSize)

Specify the width and origin implicitly by specifying the window into the view.  Use this instead of setSize() setOrigin()

drawBox()

drawBox([[#Point]] corner1, Point corner2, string color, bool fill, string link)

Draw a rectangle with the corners specified.  Default color is black.  The box may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawLine()

drawLine([[#Point]] p1, Point p2, string color, string link)

Draw a line from p1 to p2 of the color specified.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawCircle()

drawCircle([[#Point]] center, double radius, string color, bool fill, string link)

Draw a full circle with the specified center and radius.  The default color is black.  The circle may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawText()

drawText([[#Point]] start, string text, string color, string link)

Draw text into the image with the lower left corner of the text at the start point.

drawArc()

bool drawArc([[#Point]] center, double startang, double endang, double radius, string color, bool fill)

drawPolygon()

drawPolygon([[#Point]]List p, string color, bool fill, string link)

Given a series of points, draw the enclosed polygon.  The default color is black.  The polygon may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawPolyline()

drawPolyline([[#Point]]List p, string color, string link)

Given a series of points, the the line that connects them from start to end.  The default color is black.

An optional link (e.g. URL) may be provided if resulting image supports linking.

Public Methods

__init__(self, group_id, imageName, module)

Construct an empty image.

valid()

Query if the current image is valid.

Return bool value: True if valid; False if invalid

Class MAEApp

Super class: MAE

Summary

This class builds on top of the MAE class. It ensures MAE knows that your MAE task is an app and supports it appropriately. An app is a persistent program servicing user requests via UI.

Public Methods

__init__(self, programName, appchannels)

Declare your app MAE instance of this task.