GoFiler Legato Script Reference
Legato v 1.5b Application v 5.24b
|
Table of Contents | < < Previous | Next >> |
Chapter Eight — Data Functions (continued)
The Data Sheet Object is an underlying component to a number of views and data controls within the application. It is essentially a mini spreadsheet/database specifically designed to control a matrix of data. Unlike a simple table of strings within Legato, a Data Sheet Object manages a collection of cells that can contain a wide variety of data.
Data Sheet Objects can be used without controls and views and can be a convenient way to work with complex table data. When working windows employing Data Sheets, scripts use high-level function since they will manage undo as well as many other high-level functions.
A Data Sheet Object can also be useful for managing large chunks tabular data and interchanging such data with HTML, CSV, text and Excel.
The sheet is essentially a two-dimensional array of cells (table). The above is a visual representation of a Data Sheet Object as part of a Data Control or Data View. The control can be part of a dialog control while many view employ Data View as a basic that will then employ multiple Data Sheets Objects.
In each of the above examples, the underlying data management object is the Data Sheet. Each tab of the form or workbook is a Data View which in turn relies on a Data Sheet Object. As a control:
With the Data Control, a single Data Sheet supports the window.
A principal difference in the characteristics between a simple string table and a data sheet is that data sheets allows cells (elements) to be merged (spanned). Cells can also have many more attributes ranging from names, styles, typing and other characteristics. Further, optional column and row array information can be used to control the cell matrix. Finally, while a Legato array can have key names, a Data Sheet can have row and column names and each cell can have a name.
The Data Sheet object stores the information as 8-bit null terminated strings, normal as UTF-8 encoding. While object does not concern itself with the content, Data Control and Data View treat the content as UTF-8. The maximum size of the data is 2MB.
Each cell can have the following data components:
Display Data — This is generally what is being display on the screen or the cell’s data. Depending on the type of cell, it can be as simple as 1 or 0 for checkbox or up to 2MB text such as of HTML data. This is considered the cell’s text.
Aggregate Attributes — Up to 2MB total of fields supporting the cell. So far as the actual Data Sheet Object, the only field that is directly referenced and used is the cell name. All other fields are arbitrarily named to support activities of the function that rely on the Data Sheet Object. The fields are as follows:
Field Type Data — Used to support complex cell display types.
Edit/Native Data — The native data as entered. for reformatted cells, the text is the displayed data, this value would be the raw data. For example, the display may be ‘50%’ while the raw data is ‘.5’.
Cell Name — The cell’s name. Not that uniqueness is not enforced by the Data Sheet Object.
Description — A general description.
Tip — A general tip. Can be used for hover popup windows.
Comment — A general comment.
Review — Review information.
Caller Private A — General data.
Caller Private B — General data.
Script Events — Events, if enabled by the view.
Flags (Type) — Control flags including the cell’s type;
Style Index — An index to the Data Sheet Style Table.
Cell Dimensions — The measured height and width of the cell’s display content.
Cell Span Data — Spanning information for columns and rows.
The DataSheetGetCell function will retrieve all the cells characteristics.
A Data Sheet object is accessed via a Data Sheet Object Handle which can be retrieved from a related objects such as Data Controls or Data View windows. A Data Sheet can also be created using the DataSheetCreate function.
Obviously, as a spreadsheet database, the Data Sheet contains rows and columns. However, the rows and columns can also have arrays to control column and row characteristics. For certain objects, such as one obtained from a Data View window, the Data Sheet will always have column and row array.
The column array gives each column physical display characteristics such as width and visibility. If unnamed, columns are lettered from A to ZZZ and rows from 1 to x (like a spread sheet) but are accessed programmatically by zero-based index position.
Display dimensions are not relevant to the Data Sheet Object but are used by any display object using a data sheet. The dimensions are measured in screen pixels but can be specified as CSS style units. It is up to the display window to interpret and adjust such dimensions.
Each entry in the column array has flags that control certain behaviors, these are as follows:
Definition | Bitwise Flags | Description | |||||
User Settable | |||||||
DS_CC_NO_RESIZE | 0x00000001 | User Cannot Resize | |||||
DS_CC_ALLOW_DRAG | 0x00000002 | User Can Drag and Drop Columns | |||||
DS_CC_ALLOW_SELECT | 0x00000004 | User Can Select | |||||
DS_CC_ALLOW_RENAME | 0x00000008 | User Can Rename | |||||
DS_CC_ALLOW_PRESS | 0x00000010 | User Can Press Button (sort) | |||||
Contents | |||||||
DS_CC_DEFAULT_NAME | 0x00000020 | Default Name (A, B, C) | |||||
DS_CC_DIRTY | 0x00000040 | Column Needs Recalculation | |||||
Select (Highlight) | |||||||
DS_CC_HIGHLIGHT | 0x00000080 | Column is Highlighted (legend) | |||||
Column (match DC_ style) Text | |||||||
DS_CC_TEXT_MODE_MASK | 0x00000C00 | Text Mode Mask (Left, Right, etc) | |||||
DS_CC_TEXT_DEFAULT | 0x00000000 | Default (Left Text) | |||||
DS_CC_TEXT_LEFT | 0x00000400 | Left Text | |||||
DS_CC_TEXT_CENTER | 0x00000800 | Center Text | |||||
DS_CC_TEXT_RIGHT | 0x00000C00 | Right Text | |||||
Protection | |||||||
DS_CC_READ_ONLY | 0x00001000 | Column is Read-Only | |||||
DS_CC_PROTECTED | 0x00002000 | Column is Protected (password) | |||||
Sorting | |||||||
DS_CC_SORT_TYPE_MASK | 0x000F0000 | Sort Type Mask | |||||
DS_CC_SORT_NONE | 0x00000000 | Sort Not Allows | |||||
DS_CC_SORT_TEXT | 0x00010000 | Sort Text (w/ case sensitivity) | |||||
DS_CC_SORT_TEXT_NO_CASE | 0x00020000 | Sort Text (no case sensitivity) | |||||
DS_CC_SORT_TEXT_NUMERIC | 0x00030000 | Sort Text/Numbers (as File List) | |||||
DS_CC_SORT_NUMERIC | 0x00040000 | Sort Treat as Auto Number | |||||
DS_CC_SORT_DATE_AUTO | 0x00050000 | Sort Treat as Auto Date | |||||
Control (Private) | |||||||
DS_CC_HIDDEN | 0x00100000 | Column is Hidden | |||||
DS_CC_DISABLED | 0x00200000 | Column is Disabled | |||||
DS_CC_SORT_MASK | 0x00C00000 | Column Sort Mask | |||||
DS_CC_SORT_ACTIVE | 0x00400000 | Column Sort is Active (only one) | |||||
DS_CC_SORT_DESCEND | 0x00800000 | Sort Descending/Ascending | |||||
Reserved | |||||||
DS_CC_RESERVED | 0xFF000000 | Reserved (internal flags) |
Each entry in the row array has flags that control certain behaviors, these are as follows:
Definition | Bitwise Flags | Description | |||||
Masks | |||||||
DS_RC_SHEET_FLAG_MASK | 0x0000FFFF | Mask for Data Sheet Flags | |||||
DS_RC_CALLER_FLAG_MASK | 0xFFFF0000 | Mask for Caller Flags (row legend button) | |||||
User Settable | |||||||
DS_RC_NO_RESIZE | 0x00000001 | User Cannot Resize | |||||
DS_RC_ALLOW_DRAG | 0x00000002 | User Can Drag and Drop Rows | |||||
DS_RC_ALLOW_SELECT | 0x00000004 | User Can Select | |||||
DS_RC_ALLOW_RENAME | 0x00000008 | User Can Rename | |||||
DS_RC_ALLOW_PRESS | 0x00000010 | User Can Press Button | |||||
Display Label Mode | |||||||
DS_RC_LABEL_MASK | 0x00000C00 | Vertical Text Mode Mask | |||||
DS_RC_LABEL_LEFT | 0x00000000 | Left Text (default) | |||||
DS_RC_LABEL_CENTER | 0x00000400 | Center Text | |||||
DS_RC_LABEL_RIGHT | 0x00000800 | Right Text | |||||
Display Label Mode | |||||||
DS_RC_TEXT_VERT_MASK | 0x00000300 | Vertical Text Mode Mask | |||||
DS_RC_TEXT_DEFAULT | 0x00000000 | Default (middle) | |||||
DS_RC_TEXT_MIDDLE | 0x00000100 | Middle (default) | |||||
DS_RC_TEXT_TOP | 0x00000200 | Top Text | |||||
DS_RC_TEXT_BOTTOM | 0x00000300 | Bottom Text | |||||
Protection | |||||||
DS_RC_READ_ONLY | 0x00001000 | Row is Read-Only | |||||
DS_RC_PROTECTED | 0x00002000 | Row is Protected | |||||
Control (Private) | |||||||
DS_RC_CARET | 0x00000020 | Row is Caret Position | |||||
DS_RC_HIDDEN | 0x00000040 | Row is Hidden | |||||
DS_RC_DISABLED | 0x00000080 | Row is Disabled | |||||
DS_RC_SELECTED | 0x00004000 | Row is Selected | |||||
DS_RC_DIRTY | 0x00008000 | Row Needs Recalculation |
Each cell is an x/y or row/col position in the cell matrix. When a sheet is created, the matrix exists but actual cell records may not. A cell is considered null if there is no data associated with it. As soon as any property or data is applied to a cell, a cell record is created. When a null cell is accessed, the data return will be the same as if all data was reset. Accessing a null cell does not create a cell record.
The cell record contains three main pieces of data: display data, cell attributes and cell type. The Data Sheet object generally is not concerned with the cell contents except in the case of controls such as combo boxes which require cell object data. The display data is usually the text that is displayed. If the data sheet is treated as a simple matrix, a script may simply be concerned with the display data. Display data can also be very simple, such as 0 or 1 for a check box. The legend of the checkbox is stored as an attribute.
There are numerous attributes that can be associated with a cell. These include the edit data, cell name, tip, comments, extended type data and private information. In addition, the display style of the cell can be specified as an index to a style table.
Finally, the cell type specifies to the display window how the cell is displayed and edited.
Cell flags are defined as follows:
Definition | Bitwise Flags | Description | |||||
Display Type | |||||||
DS_CF_DISPLAY_TYPE_MASK | 0x0000000F | Mask for Type Data | |||||
DS_CF_DISPLAY_TEXT | 0x00000000 | Text Cell (multiple, icons) | |||||
DS_CF_DISPLAY_CHECKBOX | 0x00000001 | Display Check Box | |||||
DS_CF_DISPLAY_CHECKBOX_AUTO | 0x00000002 | Display Check Box (auto) | |||||
DS_CF_DISPLAY_RADIO | 0x00000003 | Display Radio Button | |||||
DS_CF_DISPLAY_RADIO_AUTO | 0x00000004 | Display Radio Button (auto) | |||||
DS_CF_DISPLAY_PUSHBUTTON | 0x00000005 | Display Push Button | |||||
DS_CF_DISPLAY_PUSHBUTTON_TOGGLE | 0x00000006 | Display Push Button (auto) | |||||
DS_CF_DISPLAY_COMBOBOX | 0x00000007 | Display Combo Box Select | |||||
DS_CF_DISPLAY_COMBOBOX_EDIT | 0x00000008 | Display Combo Box and Edit | |||||
DS_CF_DISPLAY_LISTBOX | 0x00000009 | Display List Box | |||||
DS_CF_DISPLAY_IMAGE | 0x0000000A | Display Image/Picture | |||||
DS_CF_DISPLAY_V_SCROLL | 0x0000000B | Display Vertical Scroll | |||||
DS_CF_DISPLAY_H_SCROLL | 0x0000000C | Display Horizontal Scroll | |||||
DS_CF_DISPLAY_HTML | 0x0000000D | Display HTML | |||||
DS_CF_DISPLAY_NUMERIC | 0x0000000E | Display Numeric (original in edit) | |||||
DS_CF_DISPLAY_PROGRESS | 0x0000000F | Display As Progress | |||||
Display Attributes | |||||||
DS_CF_NULL_CELL | 0x00000010 | Cell is not Displayed or Navigated | |||||
DS_CF_CALCULATE | 0x00000020 | Field is Calculable (by caller) | |||||
DS_CF_NO_CLIP | 0x00000040 | Display can Extend Outside of Cell | |||||
Protection | |||||||
DS_CF_READ_ONLY | 0x00000100 | Cell is Read-Only | |||||
DS_CF_PROTECTED | 0x00000200 | Cell is Protected (password) | |||||
DS_CF_OPEN_AS_DISABLED | 0x00001000 | Cell Open as Disabled (Saved) | |||||
DS_CF_OPEN_AS_HIDDEN | 0x00002000 | Cell Open as Hidden (Saved) | |||||
d_data Control Items | |||||||
DS_CF_D_DATA_LINES | 0x00000400 | Specifies Wrapped Line Count | |||||
Display and Cell Control | |||||||
DS_CF_CONTROL_MASK | 0x000F0000 | Cell Control Mask | |||||
Dereferenced Pointers (Offset) | |||||||
DS_CF_DRP_MASK | 0x00030000 | Dereferenced Pointers Mask | |||||
DS_CF_DRP_DISPLAY | 0x00010000 | Display is a Non-Pool Pointer | |||||
DS_CF_DRP_AA | 0x00020000 | Attributes is a Non-Pool Pointer | |||||
Cell Highlighting/State | |||||||
DS_CF_HIGHTLIGHT_MASK | 0x00F00000 | Highlight Index Mask | |||||
DS_CF_DISABLED | 0x01000000 | Cell Disabled | |||||
DS_CF_HIDDEN | 0x02000000 | Cell is Hidden (transparent) | |||||
DS_CF_DOG_EAR_MASK | 0x3C000000 | Cell Dog Ear Mask | |||||
DS_CF_DOG_EAR_TIP_NW | 0x04000000 | Cell has Top Left Dog Ear Tip | |||||
DS_CF_DOG_EAR_TIP_NE | 0x08000000 | Cell has Top Right Dog Ear Tip | |||||
DS_CF_DOG_EAR_TIP_SE | 0x10000000 | Cell has Bottom Right Dog Ear Tip | |||||
DS_CF_DOG_EAR_TIP_SW | 0x20000000 | Cell has Bottom Left Dog Ear Tip | |||||
Cell Processing | |||||||
DS_CF_DIRTY | 0x80000000 | Cell Size/Data Must be Calculated |
Display data flags are as follows (note these are context sensitive):
Definition | Bitwise Flags | Description | |||||
As Text Field | |||||||
DS_CD_TEXT_LINES_MASK | 0x0000FFFF | Specifies Wrapped Line Count | |||||
DS_CD_TEXT_ALLOW_WRAP | 0x00080000 | Cell Data Can Wrap | |||||
DS_CD_TEXT_LINK | 0x00100000 | Cell is a link (href in type) | |||||
As Combo Box or List | |||||||
DS_CD_OBJECT_INDEX_MASK | 0x00FFFFFF | Mask for Object Index | |||||
DS_CD_OBJECT_CONTROL_MASK | 0xFF000000 | Mask for Object Control | |||||
DS_CD_OBJECT_FLAG | 0x80000000 | Is Object | |||||
Specific Types | |||||||
DS_CD_LIST_COMBO_NOTIFY | 0x10000000 | Notify on Combo Actions (drop) | |||||
DS_CD_LIST_MULTI_SELECT | 0x20000000 | Allow Multi-Select (list only) | |||||
DS_CD_LIST_STORE_SELECT_INDEX | 0x40000000 | Store List Indices (else string) | |||||
As Numeric Field (matches DV Codes) | |||||||
DS_CD_NUMERIC_DECIMAL_PLACE_MASK | 0x000000FF | Precise Digit (- rounds number) | |||||
Display Options | |||||||
DS_CD_NUMERIC_INVERT_CREDIT_DEBIT | 0x00000100 | Treat Numbers as Credit/Debit Values | |||||
DS_CD_NUMERIC_NEG_IN_HOLE | 0x00000200 | Show Negative Numbers in Hole (123) | |||||
DS_CD_NUMERIC_NEG_IN_RED | 0x00000400 | Show Negative Numbers As Red | |||||
DS_CD_NUMERIC_USE_1000 | 0x00000800 | Use Thousand Separators | |||||
DS_CD_NUMERIC_ZERO_AS_DASH | 0x00001000 | Replace Zero with '--' | |||||
Sub Types | |||||||
DS_CD_NUMERIC_SUB_MASK | 0x0F000000 | Numeric Sub Type Mask | |||||
DS_CD_NUMERIC_ACCOUNTING | 0x00000000 | Accounting Numbers | |||||
DS_CD_NUMERIC_PERCENTAGE | 0x01000000 | Percentage | |||||
DS_CD_NUMERIC_FRACTION | 0x02000000 | Fractions | |||||
DS_CD_NUMERIC_WHOLE | 0x03000000 | Whole Numbers | |||||
DS_CD_NUMERIC_REAL | 0x04000000 | Real (float) Numbers | |||||
DS_CD_NUMERIC_SCIENTIFIC | 0x05000000 | Scientific Exp Numbers | |||||
Currency (accounting only) | |||||||
DS_CD_NUMERIC_CURRENCY_MASK | 0x00F00000 | Currency Mask | |||||
DS_CD_NUMERIC_NO_CURRENCY | 0x00000000 | Currency None | |||||
DS_CD_NUMERIC_US_DOLLAR | 0x00100000 | Currency Dollars | |||||
DS_CD_NUMERIC_EURO | 0x00200000 | Currency Euros | |||||
DS_CD_NUMERIC_POUND | 0x00300000 | Currency Pounds | |||||
DS_CD_NUMERIC_YEN | 0x00400000 | Currency Yen |
A style index is stored as part of a Data Sheet Object. The styles can be edited, added and enumerated. Certain views such as the raw Data View will allow the style information to be edited by the user. In other cases, such as various EDGAR views, the style information shapes how that display appears to the user.
As part of the base functionality of a data sheet, edit transaction and undo management is supplied. When enabled, certain actions to the data sheet can be undone. When the Data Sheet is used with a view, the editing should be performed via the view which will handle its own edit management.
Page revised 2024-10-21
Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.