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.
-
Safety
-
The Document class is intended to be safe to use when loading content from an unknown source. Processing will be aborted if a problem is found or the document appears to be unrenderable. It is however, not guaranteed that exploits are impossible. Consideration should also be given to the possibility of exploits that target third party libraries such as libpng and libjpeg for instance.
-
By default, script execution is not enabled when parsing a document source. If support for scripts is enabled, there is no meaningful level of safety on offer when the document is processed. This feature should not be used unless the source document has been written by the client, or has otherwise been received from a trusted source.
-
To mitigate security problems, we recommend that the application is built with some form of sandbox that will stop 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 | |
+ 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. StructureThe 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.
@@ -44,7 +42,7 @@ Safety
| 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. |
|---|
+ | 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. |
|---|
@@ -116,7 +114,10 @@ Safety
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) | Input | 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, LONG Size) | Input | 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) | Input | 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 script parameters. |
|---|
| ERR acGetKey(*Object, CSTRING Key, STRING Value, LONG Size) | Input | 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. |
| | 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) | Input | 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 | Passes variable parameters to loaded documents. |
|---|
| ERR acSetKey(*Object, CSTRING Key, CSTRING Value) | Input | Description |
|---|
| Key | The name of the target key. | | Value | The string value to associate with Key. |
|
MethodsThe following methods are currently supported: | Name | Comment | | AddListener | Adds a listener to a document trigger for receiving special callbacks. |
|---|
ERR doc::AddListener(OBJECTPTR Object, DRT Trigger, FUNCTION * Function) | Input | Description |
|---|
| Trigger | The unique identifier for the trigger. | | Function | The function to call when the trigger activates. |
+ 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) | Input | 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, LONG Size) | Input | 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) | Input | 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) | Input | Description |
|---|
| Key | The name of the target key. | | Value | The string value to associate with Key. |
|
MethodsThe following methods are currently supported: | Name | Comment | | AddListener | Adds a listener to a document trigger for receiving special callbacks. |
|---|
ERR doc::AddListener(OBJECTPTR Object, DRT Trigger, FUNCTION * Function) | Input | 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) |
|---|
@@ -156,7 +157,7 @@ Error CodesError 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) | Input | 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 | The index could not be found. |
|---|
| NullArgs | Function call missing argument value(s) |
|---|
|
DATA TypeData codes | 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' |
|---|
DCF TypeDocument flags | 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. |
|---|
DEF TypeEvent flags for selectively receiving events from the Document object. | 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. |
|---|
DRT TypeInternal trigger codes | 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 | |
|---|
Class Info | | ID | ID_DOCUMENT |
|---|
| Category | GUI |
|---|
| Include | modules/document.h |
|---|
| Version | 1 |
|---|
Class List- Audio
- Core
- Data
- Effects
- Extensions
- Graphics
- Network
- Vectors
|
|