Parasol Framework Manual

Provides document display and editing facilities.

The Document class offers a complete page layout engine, providing rich text display features for creating complex documents and text-based interfaces. Internally, document data is maintained as a serial byte stream and all object model information from the source is discarded. This simplification of the data makes it possible to edit the document in-place, much the same as any word processor. Alternatively it can be used for presentation purposes only, similarly to PDF or HTML formats. Presentation is achieved by building a vector scene graph in conjunction with the Vector module. This means that the output is compatible with SVG and can be manipulated in detail with our existing vector API. Consequently, document formatting is closely integrated with SVG concepts and seamlessly inherits SVG functionality such as filling and stroking commands.

The native document format in Parasol is RIPL. Documentation for RIPL is available in the Parasol Wiki. Other document formats may be supported as sub-classes, but bear in mind that document parsing is a one-way trip and stateful information such as the HTML DOM is not supported.

The Document class does not include a security barrier in its current form. Documents that include scripted code should not be processed unless they originate from a trusted source and are confirmed as such. To mitigate security problems, we recommend that the application is built with some form of sandbox that can prevent the system being compromised by bad actors. Utilising a project such as Win32 App Isolation https://github.com/microsoft/win32-app-isolation is one potential way of doing this.

Structure

The Document class consists of the following fields:

Access

Name

Type

Comment

Author STRING The author(s) of the document.

If a document declares the names of its author(s) under a head tag, the author string will be readable from this field. This field is always NULL if a document does not declare an author string.

ClientScript OBJECTPTR Allows an external script object to be used by a document file.

Set ClientScript with a Script object to allow document content to 'breach the firewall' and access functionality outside of its namespace. This feature is primarily intended for applications that need to interact with their own embedded documents.

If a document defines a default script in its content, it will have priority over the one referenced here.

If a document declares copyright information under a head tag, the copyright string will be readable from this field. This field is always NULL if a document does not declare a copyright string.

Description STRING A description of the document, provided by its author.

If the source document includes a description, it will be copied to this field.

Error ERR The most recently generated error code.

The most recently generated error code is stored in this field.

EventCallback FUNCTION Provides callbacks for global state changes.

Set this field with a function reference to receive event notifications. It must be set in conjunction with EventMask so that notifications are limited to those of interest.

The callback function prototype is ERR Function(*Document, DEF EventFlag, KEYVALUE *EventData).

The EventFlag value will indicate the event that occurred. Please see the EventMask field for a list of supported events and additional details.

Error codes returned from the callback will normally be discarded, however in some cases ERR::Skip can be returned in order to prevent the event from being processed any further.

EventMask DEF Specifies events that need to be reported from the Document object.

To receive event notifications, set EventCallback with a function reference and the EventMask field with a mask that indicates the events that need to be received.

Name	Description
DEF::LINK_ACTIVATED	The user has interacted with a hyperlink. This event can be cancelled by returning ERR::Skip.
DEF::ON_CLICK	The user has interacted with an element that has an on-click definition.
DEF::ON_CROSSING	Synonym for `ON_CROSSING_IN \| ON_CROSSING_OUT`
DEF::ON_CROSSING_IN	The mouse pointer has crossed into an element.
DEF::ON_CROSSING_OUT	The mouse pointer has crossed out of an element.
DEF::ON_MOTION	The user has triggered a motion event in an element that supports motion monitoring.
DEF::PATH	The source file path has changed. Useful for detecting when the user has left the page.
DEF::WIDGET_STATE	The state value of a widget has changed (e.g. input, checkbox, text). `name` and `value` keys will be defined in the event parameters.

Flags DCF Optional flags that affect object behaviour.

Name	Description
DCF::DISABLED	This read-only flag is set if the UI has been disabled through the Disable action.
DCF::EDIT	Allow direct keyboard input and document editing.
DCF::NO_LAYOUT_MSG	Turn off debug output produced during document layout and processing - useful on refresh for example.
DCF::NO_SYS_KEYS	System-keys provide standard key support for Ctrl-C, Ctrl-X etc. Set this flag to turn them off.
DCF::OVERWRITE	This flag forces overwrite mode when the user enters information through the keyboard. If the flag is not set, then insert mode is used.
DCF::UNRESTRICTED	Turn off all security measures - may only be set prior to initialisation.

Focus *VectorViewport Refers to the object that will be monitored for user focusing.

By default, a document object will become active (i.e. capable of receiving keyboard input) when its surface container receives the focus. If you would like to change this so that a document becomes active when some other object receives the focus, refer to that object by writing its ID to this field.

Keywords STRING Includes keywords declared by the source document.

If a document declares keywords under a head tag, the keywords string will be readable from this field. This field is always NULL if a document does not declare any keywords. It is recommended that keywords are separated with spaces or commas. It should not be assumed that the author of the document has adhered to the accepted standard for keyword separation.

Origin STRING Similar to the Path field, but does not automatically load content if set.

This field is identical to the Path field, with the exception that it does not update the content of a document object if it is set after initialisation. This may be useful if the location of a loaded document needs to be changed without causing a load operation.

Page *VectorViewport The Page contains the document content and is hosted by the View

PageHeight INT Measures the page height of the document, in pixels.

The exact height of the document is indicated in the PageHeight field. This value includes the top and bottom page margins.

PageWidth INT Measures the page width of the document, in pixels.

The page width indicates the width of the longest document line, including left and right page margins. Although the PageWidth can be pre-defined by the client, a document can override this value at any time when it is parsed. If imposing fixed page dimensions is desired, consider setting the Width and Height values of the View viewport object instead.

Path STRING Identifies the location of a document file to load.

To load a document file into a document object, set the Path field. Valid string formats for setting the path are:

volume:folder/filename.rpl

#page_name?param1&param2=value

volume:folder/filename.rpl#page_name?param1&param2=value

Setting this field post-initialisation will cause a complete reload unless the path begins with a hash to signal a change to the current page and parameters. Note: if a requested page does not exist in the currently loaded document, a dialog is displayed to bring the error to the user's attention).

To leap to a bookmark in the page that has been specified with the <index> element, use the colon as a separator after the pagename, i.e. #pagename:bookmark.

Other means of opening a document include loading the data manually and passing it via the DataFeed() action.

Pretext STRING Execute the XML defined here prior to loading new pages.

Use the Pretext field to execute document code prior to the loading of a new document. This feature is commonly used to configure a document in advance, such as setting default font values and background graphics. It is functionally equivalent to embedding an statement at the top of a document, but with the benefit of guaranteeing continued execution if the user navigates away from the first page.

A Pretext will always survive document unloading and resets. It can be removed only by setting this field with NULL.

TabFocus OBJECTID Allows the user to hit the tab key to focus on other GUI objects.

If this field points to a TabFocus object, the user will be able to move between objects that are members of the TabFocus by pressing the tab key. Please refer to the TabFocus class for more details.

Title STRING The title of the document.

If a document declares a title under a head tag, the title string will be readable from this field. This field is always NULL if a document does not declare a title.

View *VectorViewport The viewing area of the document.

The view is an internally allocated viewport that hosts the document Page. Its main purpose is to enforce a clipping boundary on the page. By default, the view dimensions will always match that of the parent Viewport. If a fixed viewing size is desired, set the Width and Height fields of the View's VectorViewport after the initialisation of the document.

Viewport *VectorViewport A client-specific viewport that will host the document graphics.

The Viewport field must refer to a VectorViewport that will host the document graphics. If undefined by the client, the nearest viewport container will be determined based on object ownership.

WorkingPath STRING Defines the working path (folder or URI).

The working path for a document is defined here. By default this is defined as the location from which the document was loaded, without the file name. If this cannot be determined, the working path for the parent task is used (this is usually set to the location of the parasol executable).

The working path is always fully qualified with a slash or colon at the end of the string.

The client can manually change the working path by setting the Origin field without affecting the loaded document.

Actions

The following actions are currently supported:

Activate Activates all child objects of the document.

ERR acActivate(*Object)

Calling the Activate() action on a document object will forward Activate() calls to its child objects.

Clear Clears all content from the object.

ERR acClear(*Object)

Using the Clear() action will delete all of the document's content. The UI will be updated to reflect a clear document.

Clipboard Full support for clipboard activity is provided through this action.

ERR acClipboard(*Object, OBJECTID Clipboard, CLIPMODE Mode)

Parameter	Description
Mode	The mode that will be used to shift data between the target object and clipboard system.

DataFeed Document data can be sent and consumed via feeds.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, INT Size)

Parameter	Description
Object	Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID.
Datatype	The type of data being sent.
Buffer	The data being sent to the target object.
Size	The size of the data in Buffer.

Appending content to an active document can be achieved via the data feed feature. The Document class currently supports the DATA::TEXT and DATA::XML types for this purpose.

Error Codes

Okay	Operation successful.
AllocMemory	The Document's memory buffer could not be expanded.
Mismatch	The data type that was passed to the action is not supported by the Document class.
NullArgs	Function call missing argument value(s)

Disable Disables user interactivity.

Draw Force a page layout update (if changes are pending) and redraw to the display.

ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)

Parameter	Description
X	The X position of the region to be drawn.
Y	The Y position of the region to be drawn.
Width	The width of the region to be drawn.
Height	The height of the region to be drawn.

Enable Enables object functionality.

Focus Sets the user focus on the document page.

GetKey Retrieves global variables and URI parameters.

ERR acGetKey(*Object, CSTRING Key, STRING Value, INT Size)

Parameter	Description
Key	The name of a key value.
Value	Pointer to a buffer space large enough to hold the retrieved value.
Size	Indicates the byte size of the Buffer.

Use GetKey() to access the global variables and URI parameters of a document. Priority is given to global variables if there is a name clash.

The current value of each document widget is also available as a global variable accessible from GetKey(). The key-value will be given the same name as that specified in the widget's element.

Refresh Reloads the document data from the original source location.

SaveToObject Use this action to save edited information as an XML document file.

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

SetKey Set a global key-value in the document.

ERR acSetKey(*Object, CSTRING Key, CSTRING Value)

Parameter	Description
Key	The name of the target key.
Value	The string value to associate with Key.

Methods

The following methods are currently supported:

AddListener Adds a listener to a document trigger for receiving special callbacks.

ERR doc::AddListener(OBJECTPTR Object, DRT Trigger, FUNCTION * Function)

Parameter	Description
Trigger	The unique identifier for the trigger.
Function	The function to call when the trigger activates.

Use the AddListener() method to receive feedback whenever a document event is triggered. Triggers are a fundamental part of document page development, accessible through the <trigger/> tag. Triggers are normally configured within the document's page code, however if you need to monitor triggers from outside the loaded document's code, then AddListener() will give you that option.

The following triggers are supported:

Name	Description
BEFORE_LAYOUT	Document layout is about to be processed. C/C++: `void BeforeLayout(Caller, Document, LONG ViewWidth, LONG ViewHeight)`
AFTER_LAYOUT	Document layout has been processed. C/C++: `void AfterLayout(Caller, Document, LONG ViewWidth, LONG ViewHeight, LONG PageWidth, LONG PageHeight)`
USER_CLICK	User has clicked the document.
USER_CLICK_RELEASE	User click has been released.
USER_MOVEMENT	User is moving the pointer over the document.
REFRESH	Page has been refreshed. C/C++: `void Refresh(Caller, Document)`
GOT_FOCUS	The document has received the focus. C/C++: `void GotFocus(Caller, Document)`
LOST_FOCUS	The document has lost the focus. C/C++: `void LostFocus(Caller, Document)`
LEAVING_PAGE	The currently loaded page is closing (either a new page is being loaded, or the document object is being freed). C/C++: `void LeavingPage(Caller, Document)`

A listener can be removed by calling RemoveListener(), however this is normally unnecessary. Listeners are removed automatically if a new document source is loaded, or the document object is terminated.

Note that a trigger can have multiple listeners attached to it, so a new subscription will not replace any prior subscriptions, nor is there any handling for multiple copies of a subscription to a trigger.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

CallFunction Executes any registered function in the currently open document.

ERR doc::CallFunction(OBJECTPTR Object, CSTRING Function, struct ScriptArg * Args, INT TotalArgs)

Parameter	Description
Function	The name of the function that will be called.
Args	Pointer to an optional list of parameters to pass to the procedure.
TotalArgs	The total number of entries in the `Args` array.

This method will execute any registered function in the currently open document. The name of the function must be specified in the first parameter and that function must exist in the document's default script. If the document contains multiple scripts, then a specific script can be referenced by using the name format script.function where script is the name of the script that contains the function.

Arguments can be passed to the function by setting the Args and TotalArgs parameters. These need to be specially formatted - please refer to the Script class' Exec method for more information on how to configure these parameters.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

Edit Activates a user editing section within a document.

ERR doc::Edit(OBJECTPTR Object, CSTRING Name, INT Flags)

Parameter	Description
Name	The name of the edit cell that will be activated.
Flags	Optional flags.

The Edit() method will manually activate an editable section in the document. This results in the text cursor being placed at the start of the editable section, where the user may immediately begin editing the section via the keyboard.

If the editable section is associated with an OnEnter trigger, the trigger will be called when the Edit method is invoked.

Error Codes

Okay	Operation successful.
Search	The cell was not found.
NullArgs	Function call missing argument value(s)

FindIndex Searches the document stream for an index, returning the start and end points if found.

ERR doc::FindIndex(OBJECTPTR Object, CSTRING Name, INT * Start, INT * End)

Parameter	Description
Name	The name of the index to search for.
Start	The byte position of the index is returned in this parameter.
End	The byte position at which the index ends is returned in this parameter.

Use the FindIndex() method to search for indexes that have been declared in a loaded document. Indexes are declared using the <index/> tag and must be given a unique name. They are useful for marking areas of interest - such as a section of content that may change during run-time viewing, or as place-markers for rapid scrolling to an exact document position.

If the named index exists, then the start and end points (as determined by the opening and closing of the index tag) will be returned as byte indexes in the document stream. The starting byte will refer to an SCODE::INDEX_START code and the end byte will refer to an SCODE::INDEX_END code.

Error Codes

Okay	The index was found and the `Start` and `End` parameters reflect its position.
Search	The index was not found.
NullArgs	Function call missing argument value(s)

HideIndex Hides the content held within a named index.

ERR doc::HideIndex(OBJECTPTR Object, CSTRING Name)

Parameter	Description
Name	The name of the index.

The HideIndex() and ShowIndex() methods allow the display of document content to be controlled at code level. To control content visibility, start by encapsulating the content in the source document with an <index> tag and ensure that it is named. Then make calls to HideIndex() and ShowIndex() with the index name to manipulate visibility.

The document layout is automatically updated and pushed to the display when this method is called.

Error Codes

Okay	Operation successful.
Search	A search routine in this function failed.
NullArgs	Function call missing argument value(s)

InsertText Inserts new content into a loaded document (raw text format).

ERR doc::InsertText(OBJECTPTR Object, CSTRING Text, INT Index, INT Char, INT Preformat)

Parameter	Description
Text	A UTF-8 text string.
Index	Reference to a `TEXT` control code that will receive the content. If `-1`, the text will be inserted at the end of the document stream.
Char	A character offset within the `TEXT` control code that will be injected with content. If `-1`, the text will be injected at the end of the target string.
Preformat	If `true`, the text will be treated as pre-formatted (all whitespace, including consecutive whitespace will be recognised).

Use the InsertText() method to insert new content into an initialised document.

Caution must be exercised when inserting document content. Inserting an image in-between a set of table rows for instance, would cause unknown results. Corruption of the document data may lead to a program crash when the document is refreshed.

The document view will not be automatically redrawn by this method. This must be done manually once all modifications to the document are complete.

Error Codes

Okay	Operation successful.
Failed	General failure.
OutOfRange	A specified number is outside of the valid range.
NullArgs	Function call missing argument value(s)

InsertXML Inserts new content into a loaded document (XML format).

ERR doc::InsertXML(OBJECTPTR Object, CSTRING XML, INT Index)

Parameter	Description
XML	An XML string in RIPL format.
Index	The byte position at which to insert the new content.

Use the InsertXML() method to insert new content into an initialised document.

The document view will not be automatically redrawn by this method. This must be done manually once all modifications to the document are complete.

Error Codes

Okay	Operation successful.
NoData	No data is available for use.
OutOfRange	A specified number is outside of the valid range.
CreateObject	A call to CreateObject() failed.
NullArgs	Function call missing argument value(s)

ReadContent Returns selected content from the document, either as plain text or original byte code.

ERR doc::ReadContent(OBJECTPTR Object, DATA Format, INT Start, INT End, STRING * Result)

Parameter	Description
Format	Set to `TEXT` to receive plain-text, or `RAW` to receive the original byte-code.
Start	An index in the document stream from which data will be extracted.
End	An index in the document stream at which extraction will stop.
Result	The data is returned in this parameter as an allocated string.

The ReadContent() method extracts content from the document stream, covering a specific area. It can return the data as a RIPL binary stream, or translate the content into plain-text (control codes are removed).

If data is extracted in its original format, no post-processing is performed to fix validity errors that may arise from an invalid data range. For instance, if an opening paragraph code is not closed with a matching paragraph end point, this will remain the case in the resulting data.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
NoData	Operation successful, but no data was present for extraction.
OutOfRange	The Start and/or End indexes are not within the stream.
NullArgs	Function call missing argument value(s)

RemoveContent Removes content from a loaded document.

ERR doc::RemoveContent(OBJECTPTR Object, INT Start, INT End)

Parameter	Description
Start	The byte position at which to start the removal.
End	The byte position at which the removal ends.

This method will remove all document content between the Start and End indexes provided as parameters. The document layout will also be marked for an update for the next redraw.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
OutOfRange	The area to be removed is outside the bounds of the document's data stream.
NullArgs	Function call missing argument value(s)

RemoveListener Removes a previously configured listener from the document.

ERR doc::RemoveListener(OBJECTPTR Object, INT Trigger, FUNCTION * Function)

Parameter	Description
Trigger	The unique identifier for the trigger.
Function	The function that is called when the trigger activates.

This method removes a previously configured listener from the document. The original parameters that were passed to AddListener() must be provided.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

SelectLink Selects links in the document.

ERR doc::SelectLink(OBJECTPTR Object, INT Index, CSTRING Name)

Parameter	Description
Index	Index to a link (links are in the order in which they are created in the document, zero being the first link). Ignored if the `Name` parameter is set.
Name	The name of the link to select (set to `NULL` if an `Index` is defined).

This method will select a link in the document. Selecting a link will mean that the link in question will take on a different appearance (e.g. if a text link, the text will change colour). If the user presses the enter key when a hyperlink is selected, that link will be activated.

Selecting a link may also enable drag and drop functionality for that link.

Links are referenced either by their Index in the links array, or by name for links that have named references. It should be noted that objects that can receive the focus - such as input boxes and buttons - are also treated as selectable links due to the nature of their functionality.

Error Codes

Okay	Operation successful.
OutOfRange	A specified number is outside of the valid range.
NullArgs	Function call missing argument value(s)

ShowIndex Shows the content held within a named index.

ERR doc::ShowIndex(OBJECTPTR Object, CSTRING Name)

Parameter	Description
Name	The name of the index.

The document layout is automatically updated and pushed to the display when this method is called.

Error Codes

Okay	Operation successful.
Search	The index could not be found.
NullArgs	Function call missing argument value(s)

Name	Description
DATA::AUDIO	Audio file data, recognised by the Sound class
DATA::CONTENT	Document content (between XML tags) - sent by document objects only
DATA::DEVICE_INPUT	Device activity
DATA::FILE	File location (the data will reflect the complete file path)
DATA::IMAGE	Image file data, recognised by the Image class
DATA::INPUT_READY	Device input that has been transformed into user input
DATA::RAW	Raw unprocessed data
DATA::RECEIPT	Receipt for item data, in response to an earlier request
DATA::RECORD	Database record
DATA::REQUEST	Make a request for item data
DATA::TEXT	Standard ASCII text
DATA::XML	Markup based text data. NOTE - For clipboard data, the top-level encapsulating tag must declare the type of XML, e.g. 'html', 'ripple'. For plain XML, use 'xml'

Name	Description
DRT::AFTER_LAYOUT
DRT::BEFORE_LAYOUT
DRT::END
DRT::GOT_FOCUS
DRT::LEAVING_PAGE
DRT::LOST_FOCUS
DRT::PAGE_PROCESSED
DRT::REFRESH
DRT::USER_CLICK
DRT::USER_CLICK_RELEASE
DRT::USER_MOVEMENT

Document Class

Structure

Actions

Methods

DATA Type

DCF Type

DEF Type

DRT Type