4D v14. Upgrade Windows /OS X. 4D D SAS. All Rights Reserved.

Transcription

1 4D v14 Upgrade Windows /OS X 4D D SAS. All Rights Reserved.

2 4D v14 - Upgrade Windows and OS X Versions Copyright D SAS. All Rights Reserved. The software described in this manual is governed by the grant of license provided in this package. The software and the manual are copyrighted and may not be reproduced in whole or in part except for the personal licensee s use and solely in accordance with the contractual terms. This includes copying the electronic media, archiving, or using the software in any manner other than that provided for in the Software license Agreement. 4D, 4D Write, 4D View, 4D Server and the 4D logos are registered trademarks of 4D SAS. Windows, Windows XP, Windows 7, Windows Vista and Microsoft are registered trademarks of Microsoft Corporation. Apple, Macintosh, imac, Mac OS X and QuickTime are trademarks or registered trademarks of Apple Computer Inc. Mac2Win Software Copyright is a product of Altura Software, Inc. ICU Copyright International Business Machines Corporation and others. All rights reserved. ACROBAT Copyright , Secret Commercial Adobe Systems Inc. All rights reserved. ACROBAT is a registered trademark of Adobe Systems Inc. This product includes software developed by the Apache Software Foundation ( 4th Dimension includes cryptographic software written by Eric Young ([email protected]) 4th Dimension includes software written by Tim Hudson ([email protected]). Spellchecker Copyright SYNAPSE Développement, Toulouse, France, All other referenced trade names are trademarks, registered trademarks, or copyrights of their respective holders. IMPORTANT LICENSE INFORMATION Use of this software is subject to its license agreement included with the software. Please read the License Agreement carefully before using the software.

3 Contents Chapter 1 Welcome Conversion of earlier databases Databases in versions < Databases in versions 11 or Databases in version Components in versions 11, 12 or Support for 64-bit plug-ins under Windows Support of IPv Functional compatibility Obsolete functions Removed functions Minimum configuration Chapter 2 Development workshop New data journaling "Include in Log File" Option Default primary key field Primary key error window Primary key manager Viewing the primary key in the MSC Debugging help Ignoring errors Real Time Monitor Starting log files D components Application builder Automating updating of server applications New automatic updating procedure for client applications.. 36 Update log New "AutoUpdate" XML keys (Windows) New "SignApplication" XML keys D v14 Upgrade 3

4 Contents New query editor Access to editor Editor menus Building queries Query by formula Support of Mecab (Japanese version) Chapter 3 Forms and objects Placeholder text Combo boxes Automatic insertion of values Excluded List Mouseover of values under OS X Multi-style areas Mouseover Context Menu New tags Allowing color and font pickers Hierarchical lists List boxes New Wordwrap property New graphic column properties Priority of styles and colors Support of standard actions New properties Choice lists associated with objects Pop-up menus and combo boxes associated with fields and variables Storage of references Rotation of text Objects eligible to rotate Setting the rotation Rotation of fields and variables Modifying an object with rotation Memorization of window geometry Save Geometry option Save Value option Storage and use of information Examples Spell checking Choice of dictionary Checking process D v14 Upgrade

5 Contents Web Areas Accessing 4D methods Access to Web inspector Chapter 4 SQL Support for SQL views CREATE VIEW DROP VIEW New system tables on the views New options using ALTER TABLE ALTER TABLE New columns for system tables Support of date and time constants Chapter 5 4D Mobile D Mobile Architecture Step-by-step example Creating and configuring the 4D database Creating the Wakanda application Displaying 4D data using a Wakanda widget Creating and calling a 4D method Configuring the 4D database Starting Wakanda REST services Control of REST accesses On REST Authentication Setting 4D objects exposed in REST Explorer Configuration of Wakanda application Execution of the mergeoutsidecatalog() method Calling 4D tables Using relations Calling 4D methods openremotestore() and addremotestore() About 4D Mobile application security Chapter 6 Language D Environment New commands Get last update log path RESTART 4D SET UPDATE FOLDER Modified commands D v14 Upgrade 5

6 Contents GET MEMORY STATISTICS SET DATABASE PARAMETER, Get database parameter Version type Arrays ARRAY BLOB ARRAY OBJECT ARRAY TIME ARRAY TO LIST LIST TO ARRAY SELECTION TO ARRAY, SELECTION RANGE TO ARRAY Backup INTEGRATE MIRROR LOG FILE BLOB BLOB TO VARIABLE, VARIABLE TO BLOB Compiler C_OBJECT Database methods On Host Database Event On REST Authentication Date and Time Conversion of JavaScript dates Time Display of null dates Design Object Access FORM GET NAMES METHOD GET CODE METHOD SET ATTRIBUTE METHOD SET CODE Drag and Drop SET DRAG ICON Form Events Form event Forms Current form name FORM LOAD FORM UNLOAD Graphs GRAPH GRAPH SETTINGS GRAPH TABLE Hierarchical Lists Association with form objects HTTP Client HTTP Get HTTP Get certificates folder D v14 Upgrade

7 Contents HTTP Request HTTP SET CERTIFICATES FOLDER JSON Introduction to JSON JSON Parse JSON PARSE ARRAY JSON Stringify JSON Stringify array JSON TO SELECTION Selection to JSON List Box LISTBOX DUPLICATE COLUMN LISTBOX Get array LISTBOX GET OBJECTS LISTBOX Get row color LISTBOX Get row font style LISTBOX MOVE COLUMN LISTBOX SET ARRAY LISTBOX SET ROW COLOR LISTBOX SET ROW FONT STYLE Messages DISPLAY NOTIFICATION Object Properties Objects (Forms) New commands GET STYLE SHEET INFO LIST OF STYLE SHEETS OBJECT Get action OBJECT Get border style OBJECT Get context menu OBJECT Get data source OBJECT GET EVENTS OBJECT Get indicator type OBJECT Get list reference OBJECT GET MAXIMUM VALUE OBJECT GET MINIMUM VALUE OBJECT Get multiline OBJECT Get placeholder OBJECT GET PRINT VARIABLE FRAME OBJECT Get style sheet OBJECT Get text orientation OBJECT Get three states checkbox OBJECT Get type OBJECT Is styled text OBJECT SET ACTION D v14 Upgrade 7

8 Contents OBJECT SET BORDER STYLE OBJECT SET CONTEXT MENU OBJECT SET COORDINATES OBJECT SET DATA SOURCE OBJECT SET EVENTS OBJECT SET INDICATOR TYPE OBJECT SET LIST BY REFERENCE OBJECT SET PLACEHOLDER OBJECT SET PRINT VARIABLE FRAME OBJECT SET MAXIMUM VALUE OBJECT SET MINIMUM VALUE OBJECT SET MULTILINE OBJECT SET STYLE SHEET OBJECT SET TEXT ORIENTATION OBJECT SET THREE STATES CHECKBOX Modified commands OBJECT Get choice list name OBJECT Get list name OBJECT GET RGB COLORS OBJECT SET CHOICE LIST NAME OBJECT SET FONT OBJECT SET LIST BY NAME OBJECT SET RGB COLORS Interaction of generic commands with multi-style areas Objects (Language) Structure of 4D objects OB Copy OB Is defined OB Is empty OB Get OB GET ARRAY OB GET PROPERTY NAMES OB Get type OB REMOVE OB SET OB SET ARRAY OB SET NULL Picture operators "&" operator (exclusive superimposition) " " operator (inclusive superimposition) Printing OPEN PRINTING FORM Processes Execute on server D v14 Upgrade

9 Contents Quick Report QR REPORT QR SET DESTINATION Spell Checker SPELL CHECK TEXT SPELL GET DICTIONARY LIST SPELL SET CURRENT DICTIONARY String String Structure Access PAUSE INDEXES RESUME INDEXES Styled Text New commands ST COMPUTE EXPRESSIONS ST FREEZE EXPRESSIONS ST Get content type ST Get expression ST GET OPTIONS ST GET URL ST INSERT EXPRESSION ST INSERT URL ST SET OPTIONS Modified command ST Get plain text Automatic normalization of line endings Using constants for selection limits Renamed commands System Documents COPY DOCUMENT Document to text TEXT TO DOCUMENT System Environment Modified commands FONT LIST Font name Font number New commands OPEN COLOR PICKER OPEN FONT PICKER SET RECENT FONTS Tools Generate digest GET ACTIVITY SNAPSHOT D v14 Upgrade 9

10 Contents User Interface SHOW TOOL BAR, HIDE TOOL BAR Tool bar height Users and Groups Validate password Web Area WA Evaluate JavaScript WA EXECUTE JAVASCRIPT FUNCTION WA SET PREFERENCE Web Server WEB SEND TEXT Web Services (Client) WEB SERVICE CALL WEB SERVICE Get info Windows Window types (OS X) Renamed constant D Internet Commands Unicode by default SMTP_Attachment SMTP_Body SMTP_MessageID SMTP_QuickSend SMTP_Subject D Pack Commands removed from 4D Pack TimePicker Widget Clock Digital clock TimePicker DISPLAY SECOND HAND TimePicker LCD DISPLAY AMPM TimePicker LCD DISPLAY SECONDS TimePicker LCD SET COLOR TimePicker LCD SET MODE D v14 Upgrade

11 1 Welcome Welcome to 4D v14. This new version is characterized by major evolutions in its architecture as well as numerous additions to enrich the interfaces of your applications, while still maintaining maximum compatibility with existing databases. Modernization of 4D core: internally, rewriting of code that used the former carbon libraries now allows 4D v14 to overcome performance limitations imposed by these libraries; in return, older-generation technologies such as QuickTime, 4D Chart or the Pict picture format are no longer supported. Forms in 4D v14 have many new features in particular concerning list objects (list boxes, hierarchical lists, combo boxes, etc.), Web areas (new JavaScript bridges, debugger) and also text areas (rotation of static text, extension of styled text function). The development workshop has also been enhanced by simplifying the procedure for updating versions, new query dialog boxes, extended debugging help, and the new On Host Database Event database method. Specific functions are implemented at the core of 4D to let Wakanda applications make direct use of data in 4D databases. And finally, 4D s programming language has been enriched with numerous new commands, in particular to allow greater control over object properties; it also welcomes a new data type: objects (see the C_OBJECT command) as well as "JSON" type data (new theme). 4D v14 Upgrade 11

12 Chapter 1 Welcome Conversion of earlier databases Databases created with versions 11.x, 12.x and 13.x of 4D or 4D Server are compatible with 4D version 14 (structure and data files). Database files for versions earlier than version 11 must be converted using a wizard and can no longer be opened with their original version. Database files in version 11 or 12 are converted directly into version 14 and can no longer be opened with their original version. Structure files in version 13 are converted directly into version 14 and can no longer be opened with their original version. However, data files in version 13 can be opened in version 14 without conversion and can still be opened again in version 13. Note: You can convert any interpreted structure file. The file can contain compiled code; in this case, you must compile the database again after conversion. Note: If the database that you are converting is missing primary keys, the primary key error window will appear. This is covered in the New data journaling paragraph on page 21. Databases in versions < 11 Structural changes made at the 4D database engine level require indepth conversion of both the structure and data for databases prior to version 11. This conversion is performed using a specific wizard. For more information, refer to the 4D v11 SQL Upgrade and Conversion to 4D v11 SQL manuals available for download here: D v14 Upgrade

13 Conversion of earlier databases Databases in versions 11 or12 Version 11 or version 12 databases are converted directly when you open their structure file with 4D v14. Two successive warnings let you know that the files are being converted and that you can no longer open them using an earlier version: Note that when you convert a data file, its indexes are rebuilt. Databases in version 13 A database from version 13 is converted directly when you open it with 4D v14. A warning dialog box lets you know that the structure file is going to be converted and that you can no longer open it with an earlier version: Data files, however, are opened without conversion so they can still be opened again in version 13. 4D v14 Upgrade 13

14 Chapter 1 Welcome Components in versions 11, 12 or 13 4D v14 can open v13, v12 or v11 components (compiled or interpreted) directly without conversion or displaying confirmation dialog boxes. Remember that components are always opened in readonly. You do not need to recompile components but conversion to v14 is only possible for.4db files and not.4dc ones. Support for 64-bit plug-ins under Windows In v14, 4D plug-ins are available in 64-bit Windows version. This way you can take advantage of the 64-bit architecture in a configuration using the 64-bit Windows version of 4D Server. 64-bit versions are included in the plug-in bundles. No specific installation is required. The following plug-ins are available in a 64-bit Windows version: 64-bit plug-ins in Notes v14 4D Write - 4D View - 4D Internet Commands 4D Pack The 4D Internet Commands v14 plug-in also includes new features. For more information, refer to the 4D Internet Commands paragraph on page 323 Modifications were made to the 4D Pack plug-in in v14. For more information, refer to the 4D Pack paragraph on page 327 4D ODBC Pro - 4D For OCI You must install the 64-bit OCI before the 64-bit 4D For OCI plug-in. You can get this version of the OCI from Oracle, Inc. Note: The functioning of 32-bit and 64-bit plug-ins is identical. However, note that the Open external window command cannot be used on a 64- bit 4D Server. 14 4D v14 Upgrade

15 Support of IPv6 Support of IPv6 4D v14 supports IPv6 address notation. This new feature concerns integrated servers of 4D v14, i.e.: the Web server as well as the SOAP server, the SQL server. Note For more information about IPv6, refer to the following specification: RFC Support of IPv6 is transparent for users and for 4D developers: the program accepts either IPv6 or IPv4 connections indiscriminately when the listening "IP address" of the server is set to All. However, you should pay attention to the following points: Indication of port numbers Since IPv6 notation uses colons (:), adding port numbers may lead to some confusion, for example: 2001:0DB8::85a3:0:ac1f:8001 // IPv6 address 2001:0DB8::85a3:0:ac1f:8001:8081 // IPv6 address with port 8081 To avoid this confusion, we recommend using the [ ] notation whenever you combine an IPv6 address with a port number, for instance: [2001:0DB8::85a3:0:ac1f:8001]:8081 //IPv6 address with port 8081 No longer any warning when TCP port is occupied Unlike previous versions of 4D, when the server is set to respond on "all" IP addresses with 4D v14, if the TCP port is being used by another application, this is no longer indicated when the server is started. In fact, 4D server does not detect any error in this case because the port remains free on the IPv6 address. However, it is not possible to access it using the IPv4 address of the machine, nor by means of the local address: If your 4D server does not seem to be responding on the port defined, you can test the address [::1] on the server machine (equivalent to for IPv6, add :portnum to test another port number). If 4D responds, it is likely that another application is using the port in IPv4. 4D v14 Upgrade 15

16 Chapter 1 Welcome Functional compatibility This section describes the new features of 4D v14 that could modify the functioning of applications converted from previous versions. Obsolete functions Pictures in PICT format The following functions are still supported in 4D v14 but they are now obsolete and their use is not recommended. The PICT format will not be supported in the next major releases of 4D and you must no longer use it in 4D v14. The AP Is Picture deprecated function, provided via 4D Pack beginning with version 13.2, is intended to help you migrate your applications. Note: The Mac "PICT" format has already been deprecated by Apple since several prior Mac OS versions (see the description of PICT format on Wikipedia). QuickTime Support for the picture codecs related to QuickTime is now obsolete. By default, the use of QuickTime is disabled in 4D v14. However for compatibility reasons, you can enable it using the new QuickTime support option of the SET DATABASE PARAMETER, Get database parameter commands. Dynamic assignment of variables received through HTTP In previous versions of 4D, the Web server automatically recopied the value of variables sent through a Web form or a URL into 4D variables when they had the same name. For reasons of optimization and control, this principle is not maintained starting with 4D v14: the value of Web variables are no longer automatically assigned to the 4D variables. To recover variables sent using a POST or a GET, you must use the WEB GET VARIABLES command exclusively. To recover the posted files, you must use the WEB GET BODY PART/WEB Get body part count commands. Note: Dynamic assignment is also disabled by default in 4D databases created beginning with version D v14 Upgrade

17 Functional compatibility However, for compatibility, this mechanism is maintained by default in databases created with a version of 4D earlier than In this case, you can disable it using the Automatic variable assignment compatibility option: Since this mechanism is obsolete, we strongly recommend that you uncheck this option in your converted databases (and adapt your code if necessary) so as to facilitate future evolutions. Query by formula Font numbers Removed functions Discontinuation of 4D Chart The query by formula editor has been merged with the standard query editor in 4D v14 (see the New query editor paragraph on page 42). The menu commands associated with it have been removed from the interface. Using QuickDraw ID numbers to designate fonts is obsolete and must no longer be used. The Font name and Font number commands are kept in 4D v14 for compatibility but will be removed in subsequent versions. The OBJECT SET FONT command now only accepts font names. As announced at the release of 4D version 13, certain obsolete functions have been removed from the 4D product line starting with 4D v14. The 4D Chart plug-in is no longer provided in version 14 and its development and maintenance have been permanently discontinued. 4D commands in the "Graphs" theme only work with the SVG syntax and the GRAPH TABLE command has been removed. 4D v14 Upgrade 17

18 Chapter 1 Welcome Tool bar in Application mode "Cordial" spell check The automatic tool bar that was available when switching to the Application mode has been removed. In 4D v14, the SHOW TOOL BAR, HIDE TOOL BAR commands are disabled and the Tool bar height command always returns 0 in Application mode. The "Display toolbar" option has been removed from the Interface page of the Database Settings. Cordial dictionaries are no longer supported in 4D v14. Only Hunspell dictionaries (as well as the native dictionary under OS X) can be used. For more information, refer to the Spell checking paragraph on page 84. & and picture operators The & and picture operators that performed XOR and OR operations (monochrome pictures) are no longer supported. The functioning of these operators in 4D v14 is new (see the Picture operators paragraph on page 273). Picture library editor The Picture library s bitmap mode editor has been removed in 4D v14. Only the display of pictures, along with the sorting, importing and splitting functions are maintained in the Tool box. Windows in noncompositing mode (OS X) The compositing mode is now used systematically for all windows created by 4D v14 under OS X. In previous versions of 4D, it was possible to create windows using a former internal management mode (based on QuickDraw). This mode is now abandoned. Thanks to compositing mode, 4D windows have new behavior and functions under OS X: animation when windows are resized windows can be resized using any wall and there is no longer a resize box in the bottom right of the windows compatibility with HiDPI screen mode (or "Retina" mode), "full screen" mode with auto-hide of main menu bar (beginning with OS X 10.7) (see the Full screen button paragraph on page 322). 18 4D v14 Upgrade

19 Functional compatibility supports for the DISPLAY NOTIFICATION command under OS X (beginning with OS X 10.8). Note: Plug-ins requiring QuickDraw must be adapted in order to be compatible with compositing mode. To ensure compatibility with plug-ins that still require QuickDraw, an emulation layer was implemented. For more information, please contact 4D technical support. Text rendering (Mac OS) In accordance with Apple's recommendations (abandoning of obsolete QD/MLTE frameworks and generalization of the use of CoreText), we updated and unified the frameworks used for text rendering in 4D under OS X beginning in version Despite our efforts to limit its impact, using the new CoreText framework may cause slight variations in the rendering of text areas under OS X for converted applications, particularly as concerns line spacing. These variations may make it necessary to resize certain form objects during conversion. 4D Pack Option+F shortcut (OS X) Alt+click shortcut for close box (Windows) Several commands found in previous versions of 4D Pack were removed from 4D Pack v14. These command are detailed in the Commands removed from 4D Pack paragraph on page 328. The Option+F shortcut, which let you "force" the switch from Application to Design mode on OS X, is removed in 4D v14. It is up to the developer to add a menu command associated with the "Return to Design mode" standard action and a custom shortcut in order to manage this operation. Note that the Option+Shift+right click shortcut can still be used to access the debug menu. The Alt+click shortcut on the close box of a window under Windows, used to close all the windows of the Design mode, is removed in 4D v14. This was a non-standard shortcut. You can use the standard shortcut for closing all windows under Windows: Ctrl+Alt+W. "Automatic Transactions during Data Entry" compatibility option This former compatibility option is no longer supported in recent versions of 4D and has been removed from the "Compatibility" page of the Database Settings in 4D 14. 4D v14 Upgrade 19

20 Chapter 1 Welcome Minimum configuration 4D version 14 product line applications require the following minimum configurations: Windows OS X Processor Intel Core Duo Intel Core 2 Duo System Windows 7 and higher OS X 10.7 (Lion) and higher RAM memory 4 GB (8 GB recommended for 64-bit 4D Server) 20 4D v14 Upgrade

21 2 Development workshop In 4D v14, many development workshop functions have been redesigned and extended for the benefit of both 4D developers and their users: On the developer side, modifications and improvements are made to functions for data journaling and maintenance, as well as debugging, component development and deployment of applications. On the user side, 4D v14 provides a new query and query by formula editor. Note that many new features specifically concern form objects. These new features are detailed in chapter 3, Forms and objects page 51. New data journaling In 4D v14, mechanisms for generating and using the log file of the data (.journal file) have been modified. These modifications bring the following benefits: allows you to set up a secured architecture using cascading backup mirrors (mirrors of mirrors), lets you choose the tables whose data must be journaled, makes the procedure for integrating a log file less linear and therefore more resistant. For example, a read error in the file concerning a recorded operation will no longer prevent the global integration of the log file (using the MSC). To do this, new principles are implemented in 4D v14: It is mandatory that each table whose data is journaled contains a primary key. 4D v14 Upgrade 21

22 Chapter 2 Development workshop You must indicate each table whose data must be journaled by means of a new option. These new rules apply to databases created with 4D v14 as well as to converted databases. They involve modifications in the Structure editor as well as new options in SQL language commands of 4D. The INTEGRATE MIRROR LOG FILE command accepts a new parameter used to manage mechanisms for mirror databases. A new assistant is provided in 4D v14 to accompany the updating of tables that do not have primary keys. The principles of how this assistant works are described in the Primary key manager paragraph on page 27. Note This assistant is also provided as a 4D v13 component so that you can prepare 4D databases to migrate to v14. "Include in Log File" Option The new Include in Log File option is available in the table Inspector of the Structure editor: New option By default, this option is checked for all new tables created in 4D v14 and for all tables in converted databases. Check this option in order for operations performed on the table s data to be included in the database log file (when it is generated). This option must generally be checked for most tables. 22 4D v14 Upgrade

23 New data journaling However, for optimization purposes, you can uncheck it, for example for temporary tables or tables used for importing data. Note This option is grayed out when the table does not have a primary key. It is important to note that this option only indicates that the table s data must be journaled if the database uses a log file; it does not enable the journaling procedure itself at the database level. Warning messages 4D displays a warning icon to the right of the Include in Log File option. As long as this icon is shown, journaling is not yet enabled. You can place your mouse over this icon to find out the cause for the warning: The following messages may be shown: Message Cause Correction needed Waiting to create a primary key Waiting for primary key values to be fixed Waiting to enable journaling at the database level Impossible to journal operations if the table does not have a primary key (new rule in 4D v14) Primary key values have been verified and include anomalies The global option for enabling journaling is not checked Create a primary key in the table using SQL or the context menu of the table Remove any duplicate or null values in the records for the field (or use another primary key) Check the Use Log File option on the Backup/Configuration page of the Database Settings Default primary key field In 4D v14, every new table created in the database contains a primary key by default: 4D v14 Upgrade 23

24 Chapter 2 Development workshop This field, named "ID" by default, is of the Longint type, and has, in particular, the following attributes: Unique, Reject NULL value input, Autoincrement, Automatic index Note In the Preferences of the 4D application, you can modify the name and type of the primary keys that are created by default. For more information, refer to the "Primary Key" preferences paragraph on page 24. You can use this field as is, or change its name and/or its properties if you want (for example, you may want to use an UUID field). You can also delete it if you want to use another field (or fields) as primary key(s). However, it is strongly recommended to keep at least one primary key in each 4D table. Note A primary key is used to uniquely identify each record in a table. It may consist of one or more fields. For more information about creating primary keys, refer to the "Table properties" section of the 4D Design Reference manual. Note Default primary keys are not added to tables that are created using the SQL CREATE TABLE command, or tables that are imported into the database. "Primary Key" preferences Two new options in the preferences can modify the default name and type of the primary key fields that are added automatically by 4D when new tables are created or by means of the Primary key manager. 24 4D v14 Upgrade

25 New data journaling These options are available on the "Structure" page of the 4D Preferences: New options The following options are available: Name ("ID" by default): Sets the default name of primary key fields. You can use any name you want, as long as it respects the naming rules for standard 4D tables. Type (Longint by default): Sets the default type of primary key fields. You can choose the UUID type. In this case, the primary key fields created by default are of the Alpha type and have the "UUID format" and "Auto UUID" properties checked. Primary key error window In 4D v14, the use of a log file requires all the journaled tables to have a valid primary key. An error dialog box is displayed when at least one table in the database does not have a valid primary key. This dialog box can appear: on opening, or after conversion to v14 of a database where the Use Log File option is checked, after checking the Use Log File option in a v14 database. 4D v14 Upgrade 25

26 Chapter 2 Development workshop If you have access to the database structure, the dialog box provides several options and displays, when you expand the lower area, the list of tables that do not have a primary key: The following message only appears if the database was using a log file: You then have the following options: Copy: copies information from the window into the clipboard for analysis. Close database: leaves the database intact and closes it. Continue: opens the database without processing the errors. In this case, journaling is disabled for the database (if the Use Log File option was checked, it is unchecked) and the database works perfectly in v14. You can use this option if you do not want to use the log file with your database. Run assistant: displays the Primary key manager window, used to update all the tables of the database. We recommend choosing this option in order to evolve the database. This assistant is described in the following section. 26 4D v14 Upgrade

27 New data journaling If you do not have access to the database structure, it is not possible to enable journaling and 4D will display a message suggesting you contact the database administrator. Primary key manager 4D v14 provides a new assistant, the "Primary key manager", intended to facilitate the resolution of errors related to the presence of tables without primary keys, in the context of a journaled database: You can use this assistant to: diagnose the compatibility of each database table with the 4D v14 journaling mechanism, propose a correction for each table found that is not compatible, more particularly by creating a primary key. Note The Primary key manager is also provided as a v13 component that you can use to prepare 4D v13 databases for conversion to v14. 4D v14 Upgrade 27

28 Chapter 2 Development workshop Displaying the assistant There are two ways to display the Primary key manager window: from the Primary key error window: click on the Run assistant button to display the assistant window: Note The assistant is displayed in Design mode. If the database starts in Application mode, the assistant does not appear right away and you will need to switch to Design mode. from the Structure window: a new button in the tool bar of this window displays the assistant: Access to Primary key manager Using the assistant The Primary key manager window displays a line for every table in the database. Note The assistant does not take tables placed in the Trash into account. The icon at the head of each line indicates whether the table requires the attention of the user: OK A valid primary key is set for the table. No primary key, eligible field(s) No primary key, no eligible fields Warning The table does not have a primary key but contains at least one field that could become the primary key. The table does not have a primary key and does not have any fields that could become one (you will have to create a primary key field). The table does not have a primary key but it is not journaled ("Include in Log File" option disabled for the table). It is possible to hide tables that have this status by unchecking the option to display warnings 28 4D v14 Upgrade

29 New data journaling For each journaled table that does not have a primary key, the assistant displays a menu to set the action to be performed. You can choose from the following options: Ignore: does not modify the table. The errors are not corrected and the status of the table is not changed. Use this option if you wish to intervene later, or if you want to create the primary key outside of the assistant. This option is necessary in particular when you want to create a primary key based on several fields in the table. Use existing field (only shown for tables with at least one field eligible to be a primary key): designates one of the table fields as the primary key. When you choose this option, the assistant suggests the most appropriate field by default. If you want to use another field or if the assistant fails to identify a particularly suitable field (the assistant displays "Select a field"), click on the second menu in the row to display the list of eligible fields. Create a new field: creates a new primary key field in the table. This field will have the same characteristics as the one added by default when a new table is created (see the Default primary key field paragraph on page 23). By default, the assistant proposes to create a field of the Longint type, named "ID". You can modify the name and type of default primary key fields in the Preferences (see the "Primary Key" preferences paragraph on page 24). You can access this page of the Preferences by clicking on the button in the Primary key manager. You can also change the name and/or type of the field directly in the Primary key manager window. Do not log this table: unchecks the "Include in Log File" option for the table. You can choose this option in the case of temporary tables (see the "Include in Log File" Option paragraph on page 22). After you validate this dialog box, a "Warning" status is assigned to the table. 4D v14 Upgrade 29

30 Chapter 2 Development workshop Once you have made your settings, click on Apply... to apply the changes to the database or Close to close the dialog box without modifying the database. When you click on Apply..., a confirmation dialog box appears listing the operations to be performed, then you can either Apply or Cancel the operation: If you have designated existing fields as primary keys, 4D checks each table to make sure that its existing data respects the rules concerning uniqueness and null values for this type of field. If, for example, a field contains duplicate values or null values, an error is generated: You will need to find and remove these anomalies before you are able to enable journaling for the data. Viewing the primary key in the MSC The Activity analysis page of the MSC was modified in order to display the primary key values of the records. The Record/BLOB column is now named Primary Key/BLOB and displays the contents of the primary key for each record. When the primary key consists of several fields, the values are separated by semicolons. The record numbers are listed in a new column on the right of the page. 30 4D v14 Upgrade

31 Debugging help Several new features in 4D v14 aim to facilitate debugging and maintenance of 4D applications. Debugging help Note A new format is also available for the debug log file. For more information, refer to the SET DATABASE PARAMETER, Get database parameter paragraph on page 147. Ignoring errors In the syntax error window, if you hit Alt (Windows) or Option (OS X), the current error is no longer indicated in the session. From then on, in this case, the Continue button changes to Ignore in order to indicate this functioning: Real Time Monitor 4D v14 offers a new function to monitor in real time the progress of "long" operations performed by the application. These operations are, for example, sequential queries, execution of formulas, etc. 4D v14 Upgrade 31

32 Chapter 2 Development workshop This function is found on the new "Real Time Monitor" page of the 4D Server Administration window: This page is available in the administration window of the server machine and also from a remote 4D machine. In the case of a remote machine, this page displays data from operations performed on the server machine. A line is added for each long operation performed on the data. This line automatically disappears when the operation is complete. The following information is provided for each line: Start Time: starting time of operation in the format: "dd/mm/yyyy - hh:mm:ss" Duration (ms): duration in milliseconds of operation in progress Information: title of operation. Sub-operations: dependent operations of the selected operation (lines containing sub-operations are displayed in bold). 32 4D v14 Upgrade

33 4D components The page is active and updated permanently as soon as it is displayed. It should be noted that its operation can significantly slow the execution of the application. It is possible to suspend the updating of this page in one of the following ways: clicking on the Pause button, clicking in the list, pressing the space bar. When you pause the page, a "PAUSED" message appears and the button label changes to Restart. You can resume monitoring of the operations by performing the same action as for pausing. Note Real-time monitoring of operations is also available using a new command, GET ACTIVITY SNAPSHOT, which contains additional options. Starting log files On the "Maintenance" page of the 4D Server Administration window in v14, the button used to start the request log also starts the recording of debug events. It is now labeled Start Request and Debug Logs: Two files are now generated in the database Logs folder when you click on this button: 4DRequestsLog_N 4DDebugLog.txt 4D components In 4D v14, the new On Host Database Event database method facilitates the initialization and backup phases for 4D components (see the On Host Database Event paragraph on page 160). 4D v14 Upgrade 33

34 Chapter 2 Development workshop For security reasons, you must explicitly authorize the execution of this method in each host database. To do this, you must check the new Execute "On Host Database Event" method of the components option on the "Security" page of the Database Settings: By default, this option is not checked. When this option is checked: 4D components are loaded, each On Host Database Event database method of the component (if any) is called by the host database, the code of the method is executed. When it is not checked: 4D components are loaded but they have to manage their initialization and backup phases themselves (as in previous versions of 4D). 34 4D v14 Upgrade

35 Application builder the developer of the component has to publish the component methods that must be called by the host database during these phases (startup and shutdown). the developer of the host database must call the appropriate methods of the component at the right time (must be covered in the component documentation). Application builder The application builder of 4D v14 includes new features that facilitate and automate the updating of your merged 4D applications: ability to automate updating of server applications or merged single-user applications (using new commands), new update procedure for client applications, new autoupdate XML keys under Windows, integration of certification under OS X. Automating updating of server applications In previous versions of 4D, updating server applications or merged single-user applications required user intervention (or programming custom system routines): whenever a new version of the merged application was available, you had to exit the application in production and manually replace the old files with the new ones; then restart the application and select the current data file. With 4D v14, you can automate this procedure using new language commands: SET UPDATE FOLDER, RESTART 4D, and also Get last update log path for monitoring operations. The idea is to implement a function in your application triggering the automatic update sequence described below. It can be a menu command or a process running in the background and checking at regular intervals for the presence of an archive on the FTP server. Here is the scenario of an update using the new commands: 1 - You transfer, for example using an FTP server, the new version of the server application or the merged single-user application onto the machine in production. 2 - In the application in production, you call the new SET UPDATE FOLDER command: this command designates the location of the folder where the "pending" update of the current application is found. 4D v14 Upgrade 35

36 Chapter 2 Development workshop Optionally, you can recopy in this folder the custom elements of the version in production (user files). 3 - In the application in production, call the new RESTART 4D command: this command triggers execution of a utility program named "updater" that exits the current application, replaces it using the "pending" update if one is specified, and restarts the application with the current data file. The former version is renamed. Note This is compatible with Windows server applications run as a Service. You also have new XML keys to elevate installation privileges so that you can use protected files under Windows (see the New "AutoUpdate" XML keys (Windows) paragraph on page 37). New automatic updating procedure for client applications The automatic update procedure for 4D client applications using HTTP is optimized for v14. The new procedure uses a utility application named "updater" that is installed on client machines and loaded to manage updates. This new procedure is manifested primarily by internal modifications. From the point of view of the 4D application developer or user, the update procedure does not change. The new procedure is compatible with client applications in v12 and v13: they are able to connect and download v14 versions. Update log The installation procedure now produces a log file detailing the update operations of merged applications (client, server or single-user) on the target machines. This file is useful for analyzing any errors that occur during the installation process. The update log is named YYYY-MM-DD_HH-MM-SS_log_<sequence>.txt, for example, _ _log_1.txt for a file created on August 25, 2013 at 14:23. This file is created in the "Updater" application folder, i.e.: under OS X: {username}/library/application Support/{ProductName}/4D/Updater/ under Windows: \{username}\appdata\roaming\{productname}\4d\updater\ 36 4D v14 Upgrade

37 Application builder You can find out the location of this file at any time using the new Get last update log path command. New "AutoUpdate" XML keys (Windows) 4D v14 provides new XML keys that can be used with the BUILD APPLICATION command. These keys allow you to elevate the installation privileges under Windows, so that the "updater" utility can install merged applications (clients and/or server) in protected system locations such as the "Desktop". Note It is generally not recommended to install merged applications in the "Program Files" folder under Windows since this folder includes specific mechanisms that are incompatible with the functioning of 4D applications. When these keys are set to True and the "updater" program attempts to update an applications in a protected location, a warning dialog box informs you that administrator privileges are required. If necessary, a dialog box appears on the machine so that you can log on using an administrator account. RuntimeVL/StartElevated /Preferences4D/BuildApp/AutoUpdate/RuntimeVL/StartElevated Values accepted: True / False Windows only: When this key contains the value True, the update of the single-user application is performed with the administrator privileges of the machine. When it contains False (default), this update is performed without elevating privileges. Under OS X, this key is always False. CS/Server/StartElevated /Preferences4D/BuildApp/AutoUpdate/CS/Server/StartElevated Values accepted: True / False Windows only: When this key contains the value True, the update of the server application is performed with the administrator privileges of the machine. When it contains False (default), this update is performed without elevating privileges. Under OS X, this key is always False. 4D v14 Upgrade 37

38 Chapter 2 Development workshop CS/Client/StartElevated /Preferences4D/BuildApp/AutoUpdate/CS/Client/StartElevated Values accepted: True / False Windows only: When this key contains the value True, the update of the merged client application is performed with the administrator privileges of the machine. When it contains False (default), this update is performed without elevating privileges. Under OS X, this key is always False. CS/ClientUpdateWin/ StartElevated /Preferences4D/BuildApp/AutoUpdate/CS/ClientUpdateWin/StartElevated Values accepted: True / False OS X only: When this key contains the value True, the update of the Windows client application is performed with the administrator privileges of the machine. When it contains False (default), this update is performed without elevating privileges. Under Windows, this key is ignored. The 4D v14 application builder includes a new functionality that signs merged 4D applications under OS X (single-user applications, 4D Server and client parts under OS X). Signing an application authorizes it to be executed using the Gatekeeper functionality of OS X when the "Mac App Store and identified Developers" option is selected. About Gatekeeper Gatekeeper is a security feature of OS X that controls the execution of applications downloaded from the Internet. The "Mac App Store and identified Developers" option is selected by default starting with OS X.8 Mountain Lion (Apple does not recommend selecting the lowest level "Anywhere" option). 38 4D v14 Upgrade

39 Application builder If a downloaded application does not come from the Apple Store or is not signed, it is rejected and cannot be launched. The new option of the 4D application builder lets you generate applications that are compatible with this option by default. Note Apple provides a reference document concerning the signature of an application ( l/codesigningguide/procedures/procedures.html). The 4D application builder simplifies this procedure. 4D v14 Upgrade 39

40 Chapter 2 Development workshop New option in Application builder The new Sign application option is included on the "Licences & Certificate" page of the application builder window. It is displayed under both Windows and OS X, but it is only taken into account for OS X versions: New option Sign application: Check this option to include certification in the application builder procedure for OS X. 4D will check the availability of elements required for certification when the build occurs. 40 4D v14 Upgrade

41 Application builder Name of certificate: Enter the name of your developer certificate validated by Apple in this entry area. The certificate name is usually the name of the certificate in the Keychain Access utility: To obtain a developer certificate from Apple, Inc., you can use the commands of the Keychain Access menu or go here: nceptual/codesigningguide/procedures/procedures.html Note This certificate requires the presence of the Apple codesign utility, which is provided by default and usually located in the /usr/bin/ folder. If an error occurs, make sure that this utility is present on your disk. New "SignApplication" XML keys MacSignature/ New XML keys can be used with the BUILD APPLICATION command to manage certification under OS X. /Preferences4D/BuildApp/SignApplication/MacSignature/ Values accepted: True / False This key must be present with the value True in order for the certificate designated by the MacCertificate/ key to be taken into account and for the application built to be signed. 4D v14 Upgrade 41

42 Chapter 2 Development workshop If this key is False (default), the update is performed without elevating privileges. Under OS X, this key is always False. MacCertificate/ /Preferences4D/BuildApp/SignApplication/MacCertificate/ Values accepted: String containing certificate name This key is used to designate the certificate to be used for signing the application to the certification tool. You can either pass the common name of the certificate, or the complete string of the identity preference of the keychain access. This key is mandatory when the MacSignature/ key is passed. Otherwise, the merged application is not signed and the key is not taken into account. New query editor The standard query editor and the query by formula editor are merged in 4D v14. The ergonomics of the new query editor has been completely redesigned and it now keeps the last ten queries performed during the session in memory. Queries by formula are now considered an advanced search mode, which is only available using a keyboard shortcut (see the Building queries paragraph on page 44). Access to editor The 4D v14 query editor is available using: the Query > Query... command in the Records menu, the Query... command in the menu associated with the Query button in the tool bar, 42 4D v14 Upgrade

43 New query editor the QUERY or QUERY BY FORMULA command of the 4D language, when no query string is passed. Compatibility note Following the merger of the two editors, the Query by formula commands of the Records/Query menu and the Query button have been removed in 4D v14. Editor menus The editor window consists of two parts: a menu area and an area for building queries. The Recent queries menu is displayed when at least one query has already been performed during the session: Menus Construction of query Edit menu The edit menu contains commands for managing the query code. Load... and Save...: as in previous versions of 4D, these commands manage the loading and saving of query files to disk. Note that these buttons manage standard queries as well as Query by formula files. Compatibility note This editor can load query files from previous versions of 4D. Copy formula to Clipboard: places the code of the formula built in the editing area on the Clipboard. Reset: deletes all the lines of the query defined in the editor. Warning: deleting lines is irreversible. 4D v14 Upgrade 43

44 Chapter 2 Development workshop Selection action menu This menu defines the query action to be performed based on the current selection of existing records. Create new selection (default action): 4D searches in all the records of the tables and replaces the original current selection to display the records found. Search in selection: 4D only searches in the records of the original current selection and then replaces this selection with the records found. Add to selection: 4D searches in all the records of the tables and adds the records found to the original current selection. Any records found that are already part of the current selection are displayed but not duplicated. Remove from selection: 4D searches in all the records of the tables and removes any records found from the original current selection. Recent queries menu This menu appears when at least one query has already been performed. It contains the most recent queries made during the session, so users can easily repeat their most common queries. Up to 10 queries are kept. Note that any selection actions associated with the queries (Search in selection, Add to selection, etc.) are not saved. When a query is selected from this menu, its description is displayed in the build area. You can then run it directly or modify it as needed. Building queries The new 4D v14 query editor can perform standard queries or queries by formula. 44 4D v14 Upgrade

45 New query editor As in previous versions of 4D, standard queries are built by specifying one or more query lines, combined using conjunctions. Queries by formula are an advanced query mode, available when you Alt+click (Windows) or Option+click (OS X) on the add line button (see the Query by formula paragraph on page 48). Standard queries To set up a standard query, just construct "field operator value" type line. To specify the field, you can use the hierarchical list found to the right of the editing area: You can also click in the editing area and type the first letter(s) of a table name (do not type the "["): a text prediction mechanism displays proposals matching what you type: Once you choose the table, press the right arrow button to validate the proposal and access the list of fields. Then you can either enter the first letter(s) of the field name or use the up/down arrows to scroll through the fields of the table: This list displays all the tables and fields of the database. If a virtual structure is specified using the SET TABLE TITLES and SET FIELD TITLES commands, it is taken into account. 4D v14 Upgrade 45

46 Chapter 2 Development workshop The list of comparison operators is updated based on the type of field defined. In addition to standard comparison operators, the new query editor offers extended operators and pre-entered value types to let you quickly perform the most common queries: Operator Alpha Date Text Time Bool Num Picture Description is empty x x The field contains no data. is not empty x x The field contains data. is equal to x is greater than or equal to x is strictly greater than x is lower than or equal to x Standard numeric comparators is strictly lower than x is different from x is false x is true x Standard Boolean comparators is x x x The field contains the exact value entered. is not x x x The field is different from the value entered. starts from x x x The field value is greater than or equal to the value entered (*). is after x x x The field value is strictly greater than the value entered (*). is up to x x x The field value is less than or equal to the value entered (*). is before x x x The field value is strictly less than the value entered (*). is between x The first date must be prior to the second. The query finds fields containing the dates entered (inclusive). is after and before x The first date must be prior to the second. The query does not find fields containing the dates entered (exclusive). is today x The current date is displayed. 46 4D v14 Upgrade

47 New query editor Operator is yesterday x is within current x Possible values: is within the last x is within the next x is within last x Possible values: - hours is within next Alpha Text Date Time Bool Num Picture Description is between x x x is between (excluded) x x x x The date of the day before is displayed. - week (sun-sat) - week (mon-sun) - week (mon-fri) - month - quarter - year These values are calculated with respect to the current date. - minutes - seconds These values are calculated with respect to the current time. The field value (included) is between the values entered (*). The field value (excluded) is between the values entered (*). lasts exactly x does not last x Possible values: lasts at least x - hours lasts over x - minutes lasts a maximum of x - seconds lasts less than x starts with x ends with x contains x Standard text comparators does not contain x contains word(s) x x Searches for the keyword(s). You have a choice between the "all does not contain word(s) x x words" (the field must contain all the words entered) or "some words" (the field must contain at least one of the words entered) option. weighs a maximum of x Search based on the picture size (different weighs at least x units are available: bytes, KB, MB, GB) (*) For strings, queries are based on the alphabet (where a < b). For example, a query of the type name is after "don" finds Donna, Don Juan, Smith, and so on, but does not find Alves or Dominick. 4D v14 Upgrade 47

48 Chapter 2 Development workshop Multiple queries To perform a query combining several criteria, you can click as many times as needed on the add line button. The editor adds a new line and you can set the conjunction operator to be used: You can also click on the delete line button of criteria. to reduce the number Query by formula In 4D v14, the query by formula has been integrated into the standard query editor. Query by formula is an advanced query mode. To define a query by formula, Alt+click (Windows) or Option+click (OS X) on the add line button. The added line then includes additional menus: Note For a single-line query by formula, delete the first line added by default. : displays a hierarchical list of all the database tables and fields whose type is compatible with a query by formula. : displays a hierarchical list of all the operators that can be used in a query by formula. 48 4D v14 Upgrade

49 Support of Mecab (Japanese version) : displays a list of 4D functions available by default in the context of a query by formula. Note As in previous versions of 4D, you can include project methods in this list by using the SET ALLOWED METHODS command. Through this new functioning, query by formula criteria can be combined with standard query criteria: Thanks to their integration into this dialog box, queries by formula now have the same functionality as standard queries: choice of result processing by means of the Selection action menu, addition to the Recent queries menu, saving and loading through a query file. Support of Mecab (Japanese version) On Japanese systems, 4D v14 supports the Mecab library, with a indexing algorithm for keywords that is particularly suited for the Japanese language. 4D v14 Upgrade 49

50 Chapter 2 Development workshop This new algorithm is used by default in Japanese versions of 4D v14. The files required for the Mecab library are installed in the mecab folder of the Resources folder for 4D applications (Japanese versions only). If you want, you can disable the use of the Mecab algorithm and use the conventional ICU library. To disable Mecab, just check the Consider only non-alphanumeric chars for keywords option in the Database Settings dialog box ("Database/Data storage" page): Disable Mecab in Japanese Note You can also disable the use of Mecab by deleting or renaming the Resources/mecab folder of your 4D application. 50 4D v14 Upgrade

51 3 Forms and objects In 4D v14, forms and objects have been revised so as to better meet the needs of 4D developers. More specifically, list objects (pop-up menus, hierarchical lists, etc.), Web areas and text areas have been enhanced. Placeholder text 4D v14 contains a new option that displays placeholder text in the fields of your forms. This text appears as watermark text in a field, supplying a help tip, indication or example for the data to be entered. This text disappears as soon as the user enters a character in the area: The placeholder text is displayed again if the contents of the field is erased. 4D v14 Upgrade 51

52 Chapter 3 Forms and objects You can set a placeholder text in the "Entry" theme of the Property List: Area for defining placeholder text The Placeholder option is available for the following objects: variables, fields, combo boxes. A placeholder can be displayed for the following types of data: string (text or alpha) date and time when the Blank if null property is checked. You can use an xliff reference in the ":xliff:resname" form as a placeholder, for instance: :xliff:ph_lastname You only pass the reference in the "Placeholder" field; it is not possible to combine a reference with static text. Note You can also set and get the placeholder text by programming using the new OBJECT SET PLACEHOLDER and OBJECT Get placeholder commands. 52 4D v14 Upgrade

53 Combo boxes Combo boxes In 4D v14, Combo box type objects accept two new options concerning choice lists: Automatic insertion and Excluded List (list of excluded values). In addition, the interface of combo boxes under OS X has been standardized. Automatic insertion of values The new Automatic insertion option is found in the "Data Source" theme of the Property List for Combo box type objects: Note This option is also available for list box columns since its cells are displayed as combo boxes when a column is associated with a choice list. When this option is checked, if a user enters a value that is not found in the choice list associated with the object, this value is automatically added to the list stored in memory. For example, given a choice list containing "France, Germany, Italy" that is associated with the "Countries" combo box: if the Automatic insertion option is checked and a user enters "Spain", then the value "Spain" is automatically added to the list in memory: 4D v14 Upgrade 53

54 Chapter 3 Forms and objects Naturally, the value entered must not belong to the list of excluded values associated with the object, if one has been set (see the following paragraph). Note If the list was created from a list defined in Design mode, the original list is not modified. If the Automatic insertion option is not checked, the value entered is stored in the object but not in the list in memory (functioning in previous versions of 4D). Excluded List The Excluded List option is now provided in the "Range of Values" theme for combo box type objects; it allows you to associate a list of excluded values to these objects. When a user enters a value that belongs to this list, its entry is rejected automatically. Option to associate a list of excluded values with a combo box Note that in 4D v14, you can associate lists of values to objects by programming using the new OBJECT SET LIST BY REFERENCE command on page 239 and the OBJECT SET LIST BY NAME command on page 253 (modified command). Note Associating a list of required values is not available for combo boxes. In an interface, if an object must propose a finite list of required values, then you must use a pop-up menu type object. 54 4D v14 Upgrade

55 Multi-style areas Mouseover of values under OS X To reinforce the compliance of 4D combo boxes with the native operation of these objects under OS X, values are no longer highlighted in the associated menu when the mouse moves over them. In addition, the current value of the object is selected in the menu: Combo boxes in 4D v13 and previous versions Combo boxes in 4D v14 Multi-style areas Several new features are available in multi-style areas (or rich text areas) in 4D v14. New functions are available using language commands. For more information, refer to the Styled Text paragraph on page 280. Mouseover Two new automatic functions are proposed when the mouse moves over a multi-style area: When it moves over a text selection, the cursor turns into an arrow: When it moves over a URL, a help tip containing the address appears: Note You can insert URL links using the new ST INSERT URL command. 4D v14 Upgrade 55

56 Chapter 3 Forms and objects Context Menu Two options are added to the context menu associated with rich text areas: Fonts...: displays the font system dialog box: Font (Windows) Recent fonts: displays the names of recent fonts selected during the session. The list can store up to 10 fonts (beyond that, the last font used replaces the oldest). By default, this list is empty and the option is not displayed. You can manage this list using the FONT LIST and SET RECENT FONTS commands. 56 4D v14 Upgrade

57 Multi-style areas New tags 4D Expression New tags are supported in rich text areas. <span style="-d4-ref:'expression'"> </span> Inserts a 4D expression (expression, method, field, variable, command, etc.) in the text. The expression is tokenized and evaluated: when the expression is inserted when the object is loaded when the ST COMPUTE EXPRESSIONS command is executed when the ST FREEZE EXPRESSIONS command is executed, if the second * parameter is passed. The evaluated value of the expression is not saved in the <span> tag, only its reference is. URL <span><a href="url">visible label</a></span> Inserts a URL in the text. Example: <span><a href=" Web Site</a></span> User link <span style="-d4-ref-user:'myuserlink'">click here</span> "User links" look the same as URLs, but when you click them, they do not automatically open the source. You can pass any string you want as reference, and it is up to the developer to program any custom actions that occur when it is clicked. This means you can create links which are not URLs but references to files, 4D methods, and so on, that you can open or execute when they are clicked. The new ST Get content type command detects if a user link has been clicked. User links are defined using the ST SET TEXT command. For example: ST SET TEXT(txtVar;"This is a user link: <span style=\"-d4-ref-user:'user- Link'\">User Label</span>";$start;$end) Custom tags You can now insert any tag in plain text, for example <img src=" It is stored in the code of the plain text without being interpreted or displayed. This is particularly useful in the context of s in HTML format and including pictures for example. 4D v14 Upgrade 57

58 Chapter 3 Forms and objects Allowing color and font pickers In 4D v14, the new OPEN COLOR PICKER and OPEN FONT PICKER commands display the system color and font picker windows. Users can change the color or font of an object that has the focus in the form directly just by clicking in one of these windows. To allow you to control user actions, this function is subject to the value of the new Allow Font/Color Picker property found in the "Text" theme: New property This property is available for form objects of the field, variable and combo box type. By default, it is unchecked for all form objects. You must explicitly check it for every object where you want font and/or color attributes to be modifiable using the system picker window. Hierarchical lists The graphic rendering of hierarchical lists under Windows has been modernized in 4D v14 so that these objects fit naturally into the latest Windows interfaces. The following characteristics were updated: expand/collapse icons are now triangles: (collapsed level) and (expanded level), 58 4D v14 Upgrade

59 List boxes the appearance of the item selected was changed and the item hovered over is now shown. The following picture compares the appearance of a hierarchical list in 4D v13.x with one in 4D v14: Hierarchical list in 4D v13 Hierarchical list in 4D v14 Note Hierarchical list references can now be associated with form objects. For more information, refer to the Hierarchical Lists paragraph on page 172. List boxes In addition to the new functions available through programming (see "List Box" section in the Language chapter), in 4D v14 you can set wordwrap, styles, font colors and background colors for list boxes on a per column basis. 4D v14 Upgrade 59

60 Chapter 3 Forms and objects New Wordwrap property The new Wordwrap property is found in the "Entry" theme for Listbox columns of the Text type: New Wordwrap option This option manages the display of the column contents when it exceeds the width of the column. When this option is checked, column text automatically wraps to the next line whenever its width exceeds that of the column, if the column height permits it. When you do not check this option, any text that is too long is truncated and displayed with an ellipse (...). In the following example, the Wordwrap option is checked for the left column but not for the right one: Option checked Option not checked Note that regardless of the Wordwrap option s value, the row height is not changed. If the text with line breaks cannot be entirely displayed in the column, it is truncated (without an ellipse). 60 4D v14 Upgrade

61 List boxes In the case of list boxes displaying just a single row, only the first line of text is displayed: Option checked Option not checked New graphic column properties You can define style, font color and background color attributes for list box columns using new column properties: New properties Row Background Color Array (array type list boxes) / Background colors (selection type list boxes): applies a custom background color to each cell of the column. You must use RGB color values. For array type list boxes, you must enter the name of a Longint array. Each element of this array corresponds to a cell of the column, so the array must be the same size as the array associated with the column. You can use the constants of the "SET RGB COLORS" theme. 4D v14 Upgrade 61

62 Chapter 3 Forms and objects If you want the cell to inherit the background color defined at the higher level (see the Inheriting styles and colors paragraph on page 65), pass the value -255 to the corresponding array element. For selection type list boxes, you must enter an expression or a variable (apart from an array type). The expression or variable is evaluated for each cell displayed. You can use the formula editor to define an expression. To do this, click on the [...] button that is shown when you select the area. You can use the constants of the "SET RGB COLORS" theme. Row Style Array (array type list boxes) / Styles (selection type list boxes): applies a custom font style to each cell of the column. For array type list boxes, you must enter the name of a Longint array. Each element of this array corresponds to a cell of the column, so the array must be the same size as the array associated with the column. To fill the array (using a method), use the constants of the "Font Styles" theme. You can add constants together to combine styles. If you want the cell to inherit the style defined at the higher level (see the Inheriting styles and colors paragraph on page 65), pass the value -255 to the corresponding array element. For selection type list boxes, you must enter an expression or a variable (apart from an array type). The expression or variable is evaluated for each cell displayed. You can use the formula editor to define an expression. To do this, click on the [...] button that is shown when you select the area. You can use the constants of the "Font Styles" theme. Row Font Color Array (array type list boxes) / Font Color (selection type list boxes): applies a custom font color to each cell of the column. You must use RGB color values. For array type list boxes, you must enter the name of a Longint array. Each element of this array corresponds to a cell of the column, so the array must be the same size as the array associated with the column. You can use the constants of the "SET RGB COLORS" theme. If you want the cell to inherit the background color defined at the higher level (see the Inheriting styles and colors paragraph on page 65), pass the value -255 to the corresponding array element. 62 4D v14 Upgrade

63 List boxes For selection type list boxes, you must enter an expression or a variable (apart from an array type). The expression or variable is evaluated for each cell displayed. You can use the formula editor to define an expression. To do this, click on the [...] button that is shown when you select the area. You can use the constants of the "SET RGB COLORS" theme. Priority of styles and colors In 4D v14, you have an additional possibility for setting background colors and font styles and colors in list boxes: by setting arrays or methods per column (see the New graphic column properties paragraph on page 61). This possibility is added to those that already existed in previous versions of 4D: properties of the list box object or column, use of arrays or methods for list box and definition at the cell level (if multi-style text). When the same property is set at more than one level, the following priority is applied: high priority low priority Cell (if multistyle text) Column arrays/methods (new in v14) List box arrays/methods Column properties List box properties For example, if you set a font style in the list box properties and another using a style array for the column, the latter one will be taken into account. 4D v14 Upgrade 63

64 Chapter 3 Forms and objects Given a list box where the rows have an alternating gray/light gray color, defined in the properties of the list box. A background color array has also been set for the list box in order to switch the color of rows where at least one value is negative to light orange: <>_BgndColors{$i}:=0x00FFD0B0 // orange <>_BgndColors{$i}:=-255 // default value Next you want to color the cells with negative values in dark orange. To do this, you set a background color array for each column, for example <>_BgndColor_1, <>_BgndColor_2 and <>_BgndColor_3. The values of these arrays have priority over the ones set in the list box properties as well as those of the general background color array: <>_BgndColorsCol_3{2}:=0x00FF8000 <>_BgndColorsCol_2{5}:=0x00FF8000 <>_BgndColorsCol_1{9}:=0x00FF8000 // dark orange 64 4D v14 Upgrade

65 List boxes <>_BgndColorsCol_1{16}:=0x00FF8000 You can get the same result using the new LISTBOX SET ROW COLOR and LISTBOX SET ROW FONT STYLE commands. They have the advantage of letting you skip having to predefine style/color arrays for the columns: instead they are created dynamically by the commands. Inheriting styles and colors For each attribute (style, color and background color), an inheritance is implemented when the default value is used: for cell attributes: attribute values of rows for row attributes: attribute values of columns for column attributes: attribute values of the list box This way, if you want for an object to inherit the attribute value from a higher level, you can use pass -255 (default value) to the definition command or directly in the element of the corresponding style/color array. 4D v14 Upgrade 65

66 Chapter 3 Forms and objects Given a list box containing a standard font style with alternating colors: You perform the following modifications: change the background of row 2 to red using the Row Background Color Array property of the list box object, change the style of row 4 to italics using the Row Style Array property of the list box object two elements in column 5 are changed to bold using the Row Style Array property of the column 5 object the 2 elements for column 1 and 2 are changed to dark blue using the Row Background Color Array property for the column 1 and 2 objects: To restore the original appearance of the list box, you can: pass the Listbox inherited constant in element 2 of the background color arrays for columns 1 and 2: then they inherit the red background color of the row. pass the Listbox inherited constant in elements 3 and 4 of the style array for column 5: then they inherit the standard style, except for element 4, which changes to italics as specified in the style array of the list box). pass the Listbox inherited constant in element 4 of the style array for the list box in order to remove the italics style. pass the Listbox inherited constant in element 2 of the background color array for the list box in order to restore the original alternating color of the list box. 66 4D v14 Upgrade

67 List boxes Support of standard actions In 4D v14, you can manage "selection" type list boxes by means of standard actions associated with buttons or menus. For example, it is now possible to use the Add Subrecord standard action to add a new record to a table by means of a list box. This new feature makes it easy to create modern interfaces based on list boxes. You can now use three standard actions with list boxes: Add Subrecord, Edit Subrecord and Delete Subrecord. Add Subrecord A button or a menu item associated with the Add Subrecord standard action is automatically enabled when there is at least one "selection" type list box in the form. If a form contains several list boxes, the action is applied to the one that has the focus (or, by default, to the frontmost one). Note You can now use the Tabable property with list boxes (see the Tabable paragraph on page 68). When the user clicks on the button or selects the menu item, a new blank record appears in the detail form defined for the list box (see the Detail Form paragraph on page 69). The user can enter values, then validate the record and a new blank record automatically appears. This continues until the user clicks on the cancel button. If the data source for the list box is the current selection, all the records created are displayed in the list. Edit Subrecord A button or a menu item associated with the Edit Subrecord standard action is automatically enabled when there is at least one row selected in a "selection" type list box. When multiple rows are selected, the action is applied to the last row included in the selection. When the user clicks on the button or selects the menu item, the record corresponding to the list box row appears in the detail form defined for the list box (see the Detail Form paragraph on page 69). The user can modify the values, then validate or cancel the form in order to return to the list box. Delete Subrecord A button or a menu item associated with the Delete Subrecord standard action is automatically enabled when there is at least one row selected in a "selection" type list box. When multiple rows are selected, the action is applied to all the records. 4D v14 Upgrade 67

68 Chapter 3 Forms and objects When a user clicks on the button or selects the menu item, a confirmation dialog box appears so that the user can confirm or cancel the deletion: New properties Tabable Double-click on Row Several new properties are available for list boxes. The Tabable property ("Entry" theme) is now available for "selection" and "array" type list boxes. The new Double-click on Row property sets the action to be performed when a user double-clicks on a row in the list box (for "selection" type list boxes only): The following options are available: Do nothing (default): double-clicking a line does not trigger any automatic action. Edit Record: double-clicking a row displays the corresponding record in the detail form defined for the list box (see the Detail Form paragraph on page 69). The record is opened in read-write mode so it can be modified. Display Record: identical to the previous action, except that the record is opened in read-only mode so it cannot be modified. Regardless of the action selected/chosen, the On Double clicked form event is generated. Note Double-clicking an empty row is ignored. 68 4D v14 Upgrade

69 Choice lists associated with objects Detail Form The new Detail Form property specifies the form to use for modifying or displaying individual records of the list box (for "selection" type list boxes only): The form defined is displayed: when using Add Subrecord and Edit Subrecord standard actions applied to the list box (see the Support of standard actions paragraph on page 67), when a row is double-clicked and the Double-click on Row property is set to "Edit Record" or "Display Record" (see the Double-click on Row paragraph on page 68). Form events Two form events are now taken into account for "selection" type list boxes: On Open Detail and On Close Detail. On Open Detail: generated when a record is about to be displayed in the detail form associated with the list box (and before this form is opened). On Close Detail: generated when a record displayed in the detail form associated with the list box is about to be closed (regardless of whether the record has been modified). For more information about displaying the detail form associated with a list box, refer to the Detail Form paragraph on page 69. Choice lists associated with objects In 4D v14, the association of choice lists with form objects has been extended and enhanced. You can now associate pop-up menu/drop-down list or combo box objects directly with fields and variables of your forms. Using a new option, you can save selected list items as references. In addition, new commands can be used to associate choice lists, as well as required and excluded values, with form objects by programming. For more information, refer to the Hierarchical Lists paragraph on page D v14 Upgrade 69

70 Chapter 3 Forms and objects Pop-up menus and combo boxes associated with fields and variables 4D v14 lets you reference a field or variable directly as the data source for pop-up menu/drop-down list type objects or for combo boxes (associated with a choice list). This makes it easier to manage listed fields. In previous versions of 4D, you used the "Lists" dialog box to enter values in a listed field or variable. It was also possible to use a pop-up menu/drop-down list or a combo box to manage a listed object, but to do so, you had to use an array to encode the interaction between the objects. In 4D v14, both these types of interfaces are favorably replaced by associating a pop-up menu or combo box directly with the object. For example, in the case of a "Color" field that can only contain the values "White", "Blue", "Green" or "Red", it is now possible to create a list containing these values and associate it with a pop-up menu object that references the 4D "Color" field. 4D then automatically takes care of managing the input and display of the current value in the form. To associate a pop-up menu/drop-down list or a combo box with a field or variable, you can just enter the name of the field or variable directly in the Variable Name area of the object: Field to be listed Choice List When the form is executed, 4D automatically manages the pop-up menu or combo box during input or display: when a user chooses a value, it is saved in the field; this field value is shown in the pop-up menu when the form is displayed: 70 4D v14 Upgrade

71 Choice lists associated with objects Storage of references The new Save as Value/Reference option is found in the "Data Source" theme for fields, variables and pop-up menus/drop-down lists: This option specifies, in the context of a field or variable associated with a list of values (choice list), the type of contents to save in the field: Save as Value (default option): the value of the item chosen in the list by the user is saved directly. For example, if the user chooses the value "Blue", then this value is saved in the field. This is how it worked in previous versions of 4D. Save as Reference: the reference of the choice list item is saved in the object. This reference is the numeric value associated with each item either through the itemref parameter of the APPEND TO LIST or SET LIST ITEM commands, or in the lists editor: This new option lets you optimize memory usage: storing numeric values in fields uses less space than storing strings. It also makes it easier to translate applications: you just create multiple lists in different languages but with the same item references, then load the list based on the language of the application. 4D v14 Upgrade 71

72 Chapter 3 Forms and objects Using the Save as Reference option requires compliance with the following principles: To be able to store the reference, the field or variable must be of the Number type (regardless of the type of value displayed in the list). Valid and unique references must be associated with list items. If you enable this option for a pop-up menu, it must be associated with a field (see the Pop-up menus and combo boxes associated with fields and variables paragraph on page 70). This option is compatible with choice lists defined in the structure. In this case, you can just select the option in each form where the listed field is used. Example You want to use a "Title" field to characterize people: Mr, Ms, but also Dr, Mgr, Hon, etc. To do this, you create a longint type field named "Title". You define a choice list (named "Titles") containing all the possible titles, then you associate it with the field. In the input form, we show the "Title" field twice in order to illustrate the mechanism implemented: once as a pop-up and once as an entry area. Both objects are associated with the same choice list and the data is saved as a reference: 72 4D v14 Upgrade

73 Choice lists associated with objects During input, you can select a value in the pop-up menu and it is displayed corrected in both objects: Note In this form, the "List" window is displayed when the entry area has the focus: To no longer show this window, you can just use a pop-up menu for input (and display) of the values. You can set up the output form on the same principle: you select the Reference option for saving the Title field: During execution, the value is correctly displayed: 4D v14 Upgrade 73

74 Chapter 3 Forms and objects Rotation of text In 4D v14, you can rotate text areas in your forms: The text rotation function is available either in the Form editor (permanent property) or using the new OBJECT SET TEXT ORIENTATION command (property set for the current process). Objects eligible to rotate The ability to rotate text concerns non-enterable text areas in forms, i.e.: static texts non-enterable textual variables and fields - "textual" refers to objects whose contents are text-based, including strings, as well as date, time or number, multiline or multi-style type objects. Other types of form objects (buttons, entry areas, lists, radio buttons, etc.) cannot be rotated. 74 4D v14 Upgrade

75 Rotation of text Setting the rotation The new "Orientation" property is found, for objects that support rotation, in the "Text" area of the Property List. Text areas can be rotated by increments of 90 : Each orientation option is applied while keeping the same lower left starting point for the object: 0 (default) 4D v14 Upgrade 75

76 Chapter 3 Forms and objects 90 Right Left Rotation using Form editor or language command When a rotation is applied in the Form editor, the object containing the text undergoes the same rotation as the text does. The principle is not the same when the text is rotated using the OBJECT SET TEXT ORIENTATION command: when this command is executed, only the text is modified, while the object containing the text is not rotated. 76 4D v14 Upgrade

77 Rotation of text For example, applying a rotation of 90 Left to a text "Chicago" in the Form editor or using the OBJECT SET TEXT ORIENTATION command, will have different results when the form is executed: 90 Left (Property List) 90 Left (language) For more information, refer to the description of the OBJECT SET TEXT ORIENTATION command. Rotation of fields and variables Only non-enterable and non-focusable text objects can be rotated. When you choose an option (other than 0 ) from the "Orientation" menu for a field or variable type object, the Enterable and Focusable properties are automatically unchecked for the object (if necessary): Automatic unchecking This object is then excluded from the entry order and its background becomes transparent by default. 4D v14 Upgrade 77

78 Chapter 3 Forms and objects Conversely, if you check the Enterable and/or Focusable property for a rotated object, its orientation property is automatically reset to 0. Modifying an object with rotation Once a text is rotated, you can still change its size or position using selection handles or using language commands such as OBJECT SET COORDINATES, as well as all its properties. Note that the text area s height and width properties do not depend on its orientation: If the object is resized in direction A, its width is modified; If the object is resized in direction C, its height is modified; If the object is resized in direction B, both its width and height are modified. You can also modify the contents of an area in the Form editor. Before changing to edit mode, the text switches to the default orientation: Memorization of window geometry 4D v14 includes new automatic features that save the specific appearance of windows when they are closed (their "geometry"), allowing users to find their working environment in the same state that they left it. 78 4D v14 Upgrade

79 Memorization of window geometry These automatic features concern the window coordinates and the position of the different objects it contains, as well as the current state of certain objects such as tabs. Note The new automatic features are only supported if forms are reopened with the same size they had when they were closed. Consequently, they are based primarily on the use of the Open form window command with the * parameter. Save Geometry option The new Save Geometry option is found in the form properties: Option to save position of objects When this option is checked, several form parameters are automatically saved by 4D when the window is closed, regardless of how they were modified during the session: the current page, the position, size and visibility of each form object (including the size and visibility of list box columns). Note This option does not take into account objects generated using the OBJECT DUPLICATE command. In order for a user to recover their environment when using this command, the developer must repeat the sequence of creation, definition and positioning of the objects. When this option is checked, the Save Value option is also available for some objects (see the following paragraph). 4D v14 Upgrade 79

80 Chapter 3 Forms and objects Save Value option The new Save Value option is found in the "Objects" theme of the Property List: Option to save current value of object This option is available when: the Save Geometry option is checked for the form, the selected object contributes to the overall geometry of the form. For example, this option is available for check boxes because their value can be used to hide or display additional areas in the window (see examples below). Here is the list of objects whose "value" can be saved: Object Radio button 3D radio button Check box 3D check box Tabs Pop-up/Drop-down list Picture pop-up menu Saved value Value of associated variable (1, 0, True or False for buttons according to their type) Number of selected tab Number of selected row Storage and use of information As in previous versions, 4D v14 keeps the coordinates of windows when they are closed as well as their maximized state under Windows when they were generated using the Open form window (formname; *) statement. This information, as well as that which can be saved optionally (geometry and value) is now saved in Json format in the current user folder of the machine, when the window is closed. Thanks to this, even when the "Default user" account is used, each user that connects with their own machine can keep their own environment. 80 4D v14 Upgrade

81 Memorization of window geometry This information is then only used if the form is reopened with the same dimensions and when closing. This means that either the Open form window(*) statement was used, or that the developer has set up a custom system for saving coordinates. The information saved is restored and reapplied in the following order: the size and position of the window are restored when the Open form window command is executed the values of the variables are restored when the form is loaded before calling the On Load event the current page is restored before calling the On Load event the position, size and visibility of each object are restored just after the On Load event. The properties of subform objects are saved and automatically reapplied in the same manner. Information saved using the "Save Geometry" and "Save Value" options is reset whenever the objects of a form are modified in Design mode (resized, moved, added, deleted or renamed). Consequently, we strongly recommend that you do NOT use this interface functionality for saving permanent values such as user preferences. Examples Memorization of separators You want for the relative positions of the form separators to be saved. In this case, you can just check the Save Geometry option. When the form is opened, it looks like this: 4D v14 Upgrade 81

82 Chapter 3 Forms and objects The user resizes the window and moves the separators. The objects are resized according to their own properties. Then the user closes the window. When the form is opened again, the objects retain their new look: Memorization of expandable areas In a form, you have placed one or more expandable areas managed using 3D check boxes. Each check box displays a triangle pointing to the right when the area is collapsed, and pointing downwards when it is expanded. There are several ways to set up these areas (movement or visibility of objects, using different form pages, etc.), and in all cases, the size of the window can vary. In order for the state of the expandable areas to be preserved between two sessions, you must: check the Save Geometry option for the form so that the current page, positions and visibility statuses of its objects are kept, 82 4D v14 Upgrade

83 Memorization of window geometry check the Save Value option for the 3D check box object so that the value of its associated variable is kept (0 or 1 for collapsed or expanded state). Memorization of tabs In a form, you have put tabs with the "Goto Page" standard action: In this case, for the memorization mechanism to work properly, you must check the Save Geometry option for the form and the Save Value option for the tab object: 4D v14 Upgrade 83

84 Chapter 3 Forms and objects Spell checking In 4D v14, Cordial dictionaries are no longer supported (see the Removed functions paragraph on page 17). Under OS X, the native spell checker is used by default. In addition, the checking and correction processes have been modernized. Choice of dictionary Spell-checking in 4D v14 can now use: under Windows and OS X, the Hunspell dictionary (already available in previous versions of 4D) under OS X only, the native spell checker. By default under OS X, 4D v14 uses the native spell checker. You can choose to use Hunspell spell-checking using the SET DATABASE PARAMETER command (see the SET DATABASE PARAMETER, Get database parameter). Note that additional functions are provided by the native OS X spell checker (see below). Checking process In 4D v14, spell-checking is applied continuously in text areas, with errors highlighted directly in the text with a dotted underline: Words to correct Note The "Auto Spellcheck" option must be checked for the object. Dotted lines in different colors are used in order to determine the type of correction to be made: In red for spelling errors In green for grammatical errors (only with native OS X spell checker) In blue for words to substitute (when the Show text substitutions option is enabled, see below). The user can then correct the text using the context menu (rightclicking on underlined word) or using the spell checker dialog box. 84 4D v14 Upgrade

85 Spell checking Context menu or spell checker dialog box To display the spell check options, you can right-click on an unknown word and a context menu containing spell checker commands appears: Note The "Auto Spellcheck" and "Context Menu" options must be checked for the object. You can select the Display spell checker dialog option to display a dialog where you can enter a corrected value: 4D v14 Upgrade 85

86 Chapter 3 Forms and objects This dialog box is a floating window that remains available for all the windows of the application during the session, until the user closes it. Spell checker functions In addition to suggestions for corrections, the following options and functions are provided by the spell checker in 4D v14 (in the context menu and/or the spell checker dialog box): Learn: the unknown word is added to the dictionary; it will no longer be indicated by the spell checker. - Under OS X, learned words are kept permanently in /Users/[UserName]/Library/Spelling (so a word learned by the system spell checker is also learned for all the applications using the system spell checker). - With Hunspell, learned words are saved in a custom Hunspell dictionary in the user system directory of the current application data that is always loaded along with the main dictionary (as in previous versions). Unlearn (context menu): This option appears when a previouslylearned word is selected. It lets the user remove this word from the list of learned words so that it is once again indicated as a possible spelling error. Ignore: the unknown word is left untouched and is no longer underlined, however it will be indicated again if it is detected later on. The spell checker keeps a table of words to ignore for each document. You can erase this table using the Clear list of ignored words option (see below). Previous / Next (dialog box): the unknown word is ignored but remains underlined and the spell checker examines the previous or next unknown word in the text. Spell checking (context menu): generally enables or disables spell checking in the area for the current process. Replace (dialog box): when the word selected in the text matches the one in the first editable field, it is replaced by the word in the second editable field, and moves on to the next error. Replace Always (dialog box): same as Replace but the substitution is memorized (see Text substitution below). 86 4D v14 Upgrade

87 Spell checking The Spell settings> submenu provides the following functions: Automatic correction: enables or disables automatic correction mode in the area for the current process. In this mode, unknown words are automatically replaced by the closest known word (except when the ambiguity is too great). Corrections are performed during input. By default, automatic correction is disabled. Text substitution: enables or disable text substitution. This consists in replacing one word by another. For example, you can choose to replace the word "Mr" with "Mister". To create "to be replaced"/"replaced by" word pairs, you must use the spell checker dialog box: enter the word to be replaced in the "Not in dictionary" area and the replacement word in the "Replace with" area, then click the Replace Always button: Replacements are performed throughout the application. With Hunspell, the spell checker keeps a global table of substitutions for the application that is saved in the user system directory of the application; for the OS X spellchecker, this table is merged with the system substitutions ("Use symbol and text substitution" option in the System Preferences). The substitution process differs depending on whether or not the Show text substitutions option in the Spell settings submenu is checked (see below). 4D v14 Upgrade 87

88 Chapter 3 Forms and objects Show text substitutions (this option is only shown when the Text substitution option is checked): When this option is checked, the spell checker underlines possible substitutions in the text with a blue line and the user must right-click on the word to select the value to be substituted. Additional options for native OS X spell checker When this option is not checked, substitutions are performed automatically, without any user intervention. Clear list of ignored words: erases the list of words chosen to be ignored in the document. The native OS X spell checker provides several other correction options: Automatic Language: automatically identifies dictionary language to be used based on text contents. By default, this spell checker uses the language of the 4D application, just like the Hunspell spell checker. Check grammar: enables grammar checking of text. 88 4D v14 Upgrade

89 Web Areas Smart dashes: replace double hyphens (--) with em dashes ( ) during input. Smart quotes: replace straight quotes with smart quotes adapted to the current language. Web Areas The interaction of Web Area objects with the 4D application has been extended in 4D v14: 4D methods can be executed from a Web area using the $4d object (with the integrated Web Kit), access to Inspector for code debugging. Accessing 4D methods In 4D v14, you can call 4D methods from the JavaScript code executed in a Web area and get values in return. Important: This new feature is only available if the Web area uses the integrated Web Kit as the rendering engine. Configuring the Web area To be able to call 4D methods from a Web area, you must check the new Access 4D methods option for the area in the Property List: Activation of JavaScript/4D methods bridge Note This option is only shown when Use integrated Web Kit option is checked. 4D v14 Upgrade 89

90 Chapter 3 Forms and objects When this property is checked, a special JavaScript object ($4d) is instantiated in the Web area, which you can use to manage calls to 4D project methods. Using the $4d object When the Access 4D methods option is checked, the 4D integrated Web Kit supplies the area with a JavaScript object named $4d that you can associate with any 4D project method using the "." object notation. For example, to call the HelloWorld 4D method, you just execute the following statement: $4d.HelloWorld(); Note JavaScript is case sensitive so it is important to note that the object is named $4d (with a lowercase "d"). The syntax of calls to 4D methods is as follows: $4d.4DMethodName(param1,paramN,function(result,error){}) param1...paramn: You can pass as many parameters as you need to the 4D method. These parameters can be of any type supported by JavaScript (string, number, array, object). function(result,error): Function to pass as last argument. This "callback" function is called synchronously once the 4D method finishes executing. It receives two parameters: result: The execution result of the 4D method, returned in the "$0" expression. This result can be of any type supported by JavaScript (string, number, array, object). You can use the new C_OBJECT command to return the objects. Note By default, 4D works in UTF-8. When you return text containing extended characters, for example characters with accents, make sure the encoding of the page displayed in the Web area is declared as UTF- 8, otherwise the characters may be rendered incorrectly. In this case, add the following line in the HTML page to declare the encoding: <meta http-equiv="content-type" content="text/html; charset=utf-8" /> error (optional parameter): array of objects containing the stack stack for any errors generated. This array is only filled when the error is not managed on the 4D side, more specifically using ON ERR CALL. 90 4D v14 Upgrade

91 Web Areas Each object consists of three properties: - message (text): Description of error - errcode (number): Error code - componentsignature (text): Signature of internal component at the basis of the error (4 characters). Example: "dbmg" for the database engine. Example 1 Given a 4D project method named today that does not receive parameters and returns the current date as a string. 4D code of today method: C_TEXT ($0) $0:=String (Current date;system date long) In the Web area, the 4D method can be called with the following syntax: $4d.today() The 4D method does not receive any parameters but it does return the value of $0 to the callback function called by 4D after the execution of the method. We want to display the date in the HTML page that is loaded by the Web area. Here is the code of the HTML page: <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <script type="text/javascript"> $4d.today(function(dollarZero) { var curdate = dollarzero; document.getelementbyid("mydiv").innerhtml=curdate; }); </script> </head> <body>today is: <div id="mydiv"></div> </body> </html> Web area in a form 4D v14 Upgrade 91

92 Chapter 3 Forms and objects Example 2 The 4D project method calcsum receives parameters ($1...$n) and returns their sum in $0: 4D code of calcsum method: C_REAL (${1}) // receives n REAL type parameters C_REAL ($0) // returns a Real C_LONGINT ($i;$n) $n:=count parameters For ($i;1;$n) $0:=$0+${$i} End for The JavaScript code run in the Web area is: $4d.calcSum(33, 45, 75, 102.5, 7, function(dollarzero) { var result = dollarzero // result is }); Example 3 This example uses the same calcsum project method as the previous example but includes error handling: $4d.calcSum("alpha", 45, 75, 102.5, 7, function(result, error) { if (error!= null) alert( "got error: " + error[0].message); else alert( "got result: " + result); }); Access to Web inspector In 4D v14 you can now view and use the Web inspector within Web areas of your forms. The Web inspector is the integrated Web Kit debugger, which parses the code and the flow of information of the Web pages. 92 4D v14 Upgrade

93 Web Areas This Web inspector is more particularly included in the Chrome browser. Web inspector windows Displaying the Web inspector The following conditions must be met in order to view the Web inspector in a Web area: You must select the integrated Web Kit for the area (the Web inspector is only available with the integrated Web Kit): You must enable the context menu for the area (this menu is used to call the inspector): 4D v14 Upgrade 93

94 Chapter 3 Forms and objects You must expressly enable the use of the inspector in the area by means of the following statement: WA SET PREFERENCE(*;"WA";WA enable Web inspector;true) For more information, refer to the description of the WA SET PREFERENCE command on page 320. Using the Web inspector When you have done the settings as described above, you then have the new Inspect Element option in the context menu of the area: 94 4D v14 Upgrade

95 Web Areas When you select this option, the Web area is divided into two parts and the different panels of the Web inspector are shown in the lower area: The inspector may, however, be used in a separate window. To do this, simply click on the "Unlock in separate windows" button at the bottom left of the area: The Web inspector is included in the Web Kit rendering engine. For a detailed description of the features of this debugger, refer to the documentation provided by Google at the following address: 4D v14 Upgrade 95

96 Chapter 3 Forms and objects 96 4D v14 Upgrade

97 4 SQL This section covers the new features and modifications made to the SQL engine of 4D v14. Support for SQL views The integrated SQL engine of 4D v14 supports standard SQL views. A view is a virtual table with data that may come from several different database tables. Once a view is defined, you can use it in a SELECT statement just like a real table. Data found in a view are defined using a definition query based on the SELECT command. Real tables used in the definition query are called "source tables". An SQL view contains columns and rows just like a standard table, but it does not actually exist; it is only a representation resulting from processing and stored in memory. Only the definition of the view is actually saved in the database. Two new SQL commands are used to manage views in 4D v14: CREATE VIEW and DROP VIEW. CREATE VIEW CREATE [OR REPLACE] VIEW [schema_name.]view_name [(column_list)] AS select_statement[;] The CREATE VIEW command creates an SQL view named view_name (which is a standard sql_name) containing the columns defined in the column_list parameter. You will need to specify a column name if this column is a function or is derived from an arithmetic operation (scalar). It is also necessary to specify a column name if you want to avoid having different columns with the same name (for example, during a JOIN operation) or when you want to use a different column name than the one from which it is derived. 4D v14 Upgrade 97

98 Chapter 4 SQL If the column_list parameter is passed, it must contain the same number of columns as there are in the select_statement definition query of the view. If column_list is omitted, the columns of the view will have the same names as those of the columns in the select_statement of the view. Views and tables must have unique names. If you pass the OR REPLACE option, the view is automatically created again if it already exists. This option can be useful in order to change the definition of an existing view without having to delete/recreate/affect the privileges of objects already defined for the current view. When the OR REPLACE option is not passed and the view already exists, an error is returned. schema_name is also a standard sql_name and you can use it to designate the name of the schema that will contain the view. If you do not pass schema_name or if you pass the name of a schema that does not exist, the view is automatically assigned to the default schema, which is entitled "DEFAULT_SCHEMA". select_statement designates the SELECT statement that is the definition query of the view. The select_statement is the same as a standard SELECT in 4D, but with the following restrictions: You cannot use INTO, LIMIT or OFFSET clauses since the limitation, offset or assignment of variables in 4D will be performed by the SELECT statement that calls the view. You cannot use the GROUP BY clause. Views are in read-only mode and cannot be updated. View definition is "static" and is not updated when a source table is modified or deleted. More particularly, any columns added to a table do not appear in the view based on this table. Similarly, if you try to access deleted columns by means of a view, this causes an error. However, a view that refers to a deleted source view will continue to work. In fact, when you create a view, it converts any view reference(s) into references to the source tables. 98 4D v14 Upgrade

99 CREATE VIEW Views have a global scope. Once a view is created using CREATE VIEW, it can be accessed by all parts of the application (4D remote using SQL, external databases created using the CREATE DATABASE command, other databases using the SQL LOGIN command, etc.) and at any time until it is deleted using the DROP VIEW command. Examples Given the PEOPLE table containing the following columns: ID INT64 FIRST_NAME VARCHAR(30) LAST_NAME VARCHAR(30) DEPARTMENT VARCHAR(30) SALARY INT Here are a few examples of view definitions: a view with no restrictions: CREATE VIEW FULLVIEW AS SELECT * FROM PEOPLE; a view with "horizontal" restrictions. For example, you want to only display people in the Marketing department: CREATE VIEW HORIZONTALVIEW (ID, FirstName, LastName, Salary) AS SELECT ID, FIRST_NAME, LAST_NAME, SALARY FROM PEOPLE WHERE DEPARTMENT = 'Marketing'; an aggregated view: CREATE VIEW AGGREGATEVIEW (FirstName, LastName AnnualSalary) AS SELECT FirstName, LastName, SALARY*12 FROM PEOPLE; a view with "vertical" restrictions. For example, you do not want to display the SALARY column: CREATE VIEW VERTICALVIEW (ID, FirstName, LastName, Department) AS SELECT ID, FIRST_NAME, LAST_NAME, DEPARTEMENT FROM PEOPLE; Once the views are defined, you can use them just like standard tables. For example, if you want to get every person whose salary is greater than 5,000 Euros: SELECT * FROM FULLVIEW WHERE SALARY < 5000 INTO :aid, :afirstname, :alastname, :adepartment, :asalary; 4D v14 Upgrade 99

100 Chapter 4 SQL Another example: you want to get every person in the Marketing department whose first name is "Michael": SELECT ID, LastName, Salary FROM HORIZONTALVIEW WHERE FirstName='Michael' INTO :aid, :alastname, :asalary; DROP VIEW DROP VIEW [IF EXISTS] [schema_name.]view_name[;] The DROP VIEW command deletes the view named view_name from the database. When the IF EXISTS constraint is passed, the command does nothing and no error is generated if the view_name view does not exist in the database. schema_name is a standard sql_name and you can use it to designate the name of the schema that will contain the view. If you do not pass schema_name or if you pass the name of a schema that does not exist, the view is automatically considered to belong to the default schema, which is entitled "DEFAULT_SCHEMA". New system tables on the views Two new system tables are available in order to manage information about the views: _USER_VIEWS Type Describes the views of database users VIEW_NAME VARCHAR Name of view SCHEMA_ID INT32 ID of schema_name to which the view belongs _USER_VIEW_COL UMNS Type Describes the columns of the views of the database users VIEW_NAME VARCHAR Name of view COLUMN_NAME VARCHAR Name of column DATA_TYPE INT32 Type of column DATA_LENGTH INT32 Size of column NULLABLE BOOLEAN True if column accepts NULL values; otherwise, False 100 4D v14 Upgrade

101 New options using ALTER TABLE New options using ALTER TABLE ALTER TABLE The SQL ALTER TABLE command now accepts new options: [TRAILING] (used with ADD keyword): forces column to be created after the last existing column of the table in the structure file. This option is useful when columns containing data have been deleted from the table (without the data being erased), to prevent existing data from being reassigned to the new column. enabling/disabling of journaling for the table enabling/disabling of "Autoincrement" option for Longint type fields enabling/disabling of "Auto UUID" option for Alpha fields of the UUID type. ALTER TABLE sql_name {ADD column_definition [PRIMARY KEY] [TRAILING] DROP sql_name ADD primary_key_definition DROP PRIMARY KEY ADD foreign_key_definition DROP CONSTRAINT sql_name [{ENABLE DISABLE} REPLICATE] [{ENABLE DISABLE} LOG] [{ENABLE DISABLE} AUTO_INCREMENT] [{ENABLE DISABLE} AUTO_GENERATE] SET SCHEMA sql_name} The command returns an error: when the optional ENABLE LOG parameter is passed and no valid primary key is defined, if you attempt to modify or delete the definition of the table s primary key without disabling journaling by means of DISABLE LOG. 4D v14 Upgrade 101

102 Chapter 4 SQL New columns for system tables The _USER_TABLES and _USER_COLUMNS system tables include new columns: _USER_TABLES Type Describes columns of database user tables REST_AVAILABLE BOOLEAN True if table is exposed with REST service; otherwise, False _USER_COLUMNS Type Describes columns of database user tables UNIQUENESS BOOLEAN True if column is declared Unique; otherwise, False AUTOGENERATE BOOLEAN True if column value is generated automatically for each new record; otherwise, False AUTOINCREMENT BOOLEAN True if column value is incremented automatically; otherwise, False REST_AVAILABLE BOOLEAN True if column is exposed with REST service; otherwise, False Note The AUTOGENERATE and AUTOINCREMENT columns are also available in 4D v13 starting with version Support of date and time constants The integrated SQL server of 4D v14 now supports date and time constants in accordance with the ODBC API D v14 Upgrade

103 Support of date and time constants Here is the syntax for sequences of ODBC date and time constants: {constant_type 'value'} constant_type value Description d yyyy-mm-dd Date only t hh:mm:ss[.fff] Time only ts yyyy-mm-dd hh:mm:ss[.fff] Date and time (timestamp) Note fff indicates milliseconds. For example, you can use the following constants: { d ' ' } { t '13:33:41' } { ts ' :23:56.123' } 4D v14 Upgrade 103

104 Chapter 4 SQL 104 4D v14 Upgrade

105 5 4D Mobile Wakanda, published by 4D SAS, is a platform for developing and publishing web applications entirely based on standard technologies such as JavaScript and HTML5. You can use the "4D Mobile" architecture to set up a direct link between 4D and Wakanda. With this configuration, you combine the graphical and functional richness of the latest generation of Wakanda Web interfaces with the power of your 4D databases. Note If you want to create your first link between 4D and Wakanda right away, check below that you have an appropriate configuration and then refer to the Step-by-step example paragraph on page D Mobile Architecture To set up an architecture using the 4D / Wakanda connector, you need a minimum of: 4D Server v14. You can also use a single-user 4D v14 (Professional version) to develop and test your solution using the 4D Mobile connector (three simultaneous client connections are allowed in this context). Wakanda Enterprise Server v7 as well as Wakanda Enterprise Studio v7 for development. You can download both of these applications from this site: a 4D database and a Wakanda application that you want to communicate with each other. On the 4D side, you have to configure every table, attribute and method to be accessed by the Wakanda applications (see the Configuring the 4D database paragraph on page 117). 4D v14 Upgrade 105

106 Chapter 5 4D Mobile The 4D Mobile architecture can be represented as follows: Connector (mergeoutsidecatalog) REST/JSON Wakanda Enterprise Server 4D session ticket 4D Server Client connections Web clients (desktop, tablet, mobile) The link is established between the Wakanda Enterprise server and 4D Server after the mergeoutsidecatalog() JavaScript method is executed by the Wakanda server (see the Execution of the mergeoutsidecatalog() method) when the Wakanda solution is started. Once the connection is accepted by 4D Server (see the Control of REST accesses paragraph on page 118), a REST session "ticket" is delivered to the Wakanda server. This ticket will be used by Wakanda for all subsequent REST client requests. By means of this link, the Wakanda server can potentially access two types of resources in the 4D database: tables and their attributes (including their data) project methods When authorized these resources are used directly on the Wakanda side, just as if they belonged to the local catalog of the Wakanda application (their access is transparent from the Wakanda application). When a Web client sends a request to the Wakanda server that requires access to the 4D database, this request is sent to the 4D server using the current ticket and a standard client connection is opened on the 4D Server machine. This connection remains open as long as the user is performing requests and closes by default after a 60-minute timeout. This default timeout can be changed during the Execution of the mergeoutsidecatalog() method by means of the timeout parameter D v14 Upgrade

107 Step-by-step example During the session, if the number of licenses corresponding to the number of authorized client connections on the 4D Server is reached, an error message is returned to the Wakanda server. Note You can also establish dynamic temporary links between Wakanda and 4D applications while the Wakanda application is being run using the addremotestore() and openremotestore() methods. These methods are described in openremotestore() and addremotestore(). Step-by-step example This section is intended to help familiarize you with Wakanda / 4D connector functionality by means of a step-by-step example. We are going to: create and configure a 4D database create a single-page Wakanda application display data from the 4D database in the Wakanda page. To keep the example simple, we re going to use a 4D application and a Wakanda application that are running on the same machine. Of course, you could also use a remote architecture. 1 - Creating and configuring the 4D database 1 Launch your 4D or 4D Server application and create a new database. You can name it "Emp4D", for example. 2 In the Structure editor, create an [Employees] table and add the following fields to it: LastName (Text) FirstName (Text) 4D v14 Upgrade 107

108 Chapter 5 4D Mobile Salary (Longint) The "Expose with REST Service" attribute is checked by default for the table and every field; do not change this setting. 3 Click on the Tables button and let 4D create default forms, then create a few employees: 4 Display the Web page of the Database Settings dialog box and click on the REST tab. 5 Check the "Activate Wakanda REST service" option then click on OK: 6 Select Start Web Server in the Run menu: 108 4D v14 Upgrade

109 Step-by-step example The 4D database is now ready to respond to REST requests from Wakanda. Note that in order to simplify this example, we are not controlling REST accesses. However, in a context of production or open architecture, it is indispensable to secure REST accesses (see the About 4D Mobile application security paragraph on page 141). 2 - Creating the Wakanda application 1 Launch the "Wakanda Enterprise Studio" application and click on the Create a New Solution button: 2 In the creation dialog box, enter, for example, "EmpWakanda" and click on OK: The application project is created and its default elements are shown in the Wakanda Studio Explorer, on the left side of the window. 3 Double-click on the Model element. The Wakanda Model Designer appears. Since we want to call an external model, we will not use this editor in our example. 4 In the Explorer area of Wakanda, double-click on the Model.js file. This file is created automatically when you open the graphical editor. It contains the JavaScript code description of your model. 4D v14 Upgrade 109

110 Chapter 5 4D Mobile 5 Just enter the following JavaScript statement: model.mergeoutsidecatalog("emp4d", "localhost","",""); This code will enable the connector and open a link between your Wakanda project and 4D: "Emp4D" is the local name of the link as it appears in Wakanda Enterprise Studio. You can enter any name but for clarity we are using the name of the 4D database "localhost" is the address of the HTTP server of 4D v14 (enter the hostname or the IP address if necessary) two empty strings are then passed for the name and password because we are not using them in this example. Now you need to close and open your solution again in order for the model to be loaded by Wakanda Enterprise Studio. 6 Click on the solution s close button in the Explorer: If you have not saved the model file, a dialog box appears, and you can click on Save All to save the changes. 7 Open the solution in Wakanda Enterprise Studio again by clicking on it in the list of "Recent Solutions". You can see that the "Emp4D" external model is listed in the files of the Wakanda application and the [Employees] table of the 4D application is listed in the datastore classes of the local model. External elements are indicated by a red arrow: Local file of external model Table of external catalog 110 4D v14 Upgrade

111 Step-by-step example In case of problems... If the table is not shown in the list at this time, check that: no third-party service or software (instant messenger, for instance) is in conflict with the publishing port of the 4D HTTP server (8080 by default), on the 4D side, the 4D Web server is started, Wakanda REST services are activated and the table has been exposed in REST, the address passed to mergeoutsidecatalog() is valid. To check whether the 4D server is actually responding to REST requests, you can try the following URLs in your browser: <address>/rest/$catalog/$all (returns all the tables exposed in REST) <address>/rest/my_table/my_method (returns the result of the method - if it returns a result) 3 - Displaying 4D data using a Wakanda widget Now we are going to associate a 4D table with a Wakanda widget by simple drag-and-drop, then launch the Wakanda Enterprise Server and view the data. 1 Open the "WebFolder" folder in the Explorer and double-click on the Index page to open the GUI Designer of Wakanda. Note The "WebFolder" contains elements intended for Web publication of your project. "Index" is the default page of the project. 4D v14 Upgrade 111

112 Chapter 5 4D Mobile 2 In the list of Widgets, click on "Grid" and drop it in the work area: 3 In the list of Datastore Classes for the model, click on "Employees" and drop it onto the grid that you just created: 112 4D v14 Upgrade

113 Step-by-step example At this point, the editor automatically create a datasource for you based on the "Employees" class, which will manage the contents of the widget. This datasource is a JavaScript object managed by Wakanda, named "employees" by default, i.e. the class name with its first letter in lowercase. The widget displays a preview of its contents. You can enlarge it to display all the fields of the datasource: The association between the datasource and the widget is now established. 4 Click on the Save button in the tool bar of the editor. Now we are going to display the data using a browser. 5 Click on the Run project button in the tool bar of the Wakanda Enterprise Studio: 4D v14 Upgrade 113

114 Chapter 5 4D Mobile This starts the Wakanda Enterprise Server and publishes the "EmpWakanda" application. Thanks to the 4D Mobile link that we set up, the data of the 4D database is displayed in a window of your default browser: You can test the dynamic properties of the link by changing data on the Web side. For instance, here we changed Maryanne Jones last name to "Jackson" and this change was immediately reflected in 4D: 4 - Creating and calling a 4D method Now we are going to create a very simple project method on the 4D side and execute it from our Web page. This method will double all the salaries. 1 On the 4D side, create a project method named DoubleSalary and enter the following code: FIRST RECORD ([Employees]) While (Not (End selection ([Employees]))) [Employees]salary:=[Employees]salary*2 SAVE RECORD ([Employees]) NEXT RECORD ([Employees]) End while 114 4D v14 Upgrade

115 Step-by-step example 2 Set the REST properties of the method and click on OK: REST properties In Wakanda, class methods apply to one of the following contexts: the entity (record), the entity collection (selection) or the datastore class (all records). You will need to specify this context on the 4D side. 3 On the Wakanda Enterprise Studio side, return to the Index page in the GUI Designer and add a button from the list of widgets: 4D v14 Upgrade 115

116 Chapter 5 4D Mobile 4 Double-click on the button and name it, for instance, "Double salaries": 5 Make sure that the "Double salaries" button is selected and then click on the Events button in the right-hand area of the GUI Designer. 6 Click on the icon for adding the "On Click" event: The code editor appears and you can enter the code to be executed when the button is clicked. We are just going to call the DoubleSalary method of 4D and then, in the callback function (onsuccess), cause all the records to be reloaded. 7 Enter the following code: sources.employees.doublesalary({ onsuccess:function(event){ sources.employees.allentities(); }}); In the code editor: Note the lowercase "e" used for "employees"; we are using the datasource that was created automatically when the class was associated with the widget. 8 Click on the Save button in the tool bar of the editor. We can test calling the 4D method but beforehand you must reload the model on the Wakanda Enterprise Server. 9 Click on the Reload Models button in the tool bar of Wakanda Enterprise Studio D v14 Upgrade

117 Configuring the 4D database 10 Refresh your browser page so that the Double salaries button appears and then click on this button: You can see that the salary values have all doubled: Note that this example is simply intended to show how to use the Wakanda / 4D connector. The simplified methods shown here cannot be used in a production context. Configuring the 4D database For security and performance reasons, access to the tables, data and methods of the 4D database by means of REST requests (protocol used by Wakanda servers) must be enabled and explicitly authorized. You must configure three levels of access: startup of Wakanda REST services, control of REST accesses (optional but recommended), 4D v14 Upgrade 117

118 Chapter 5 4D Mobile exposure of each database object (table, attribute or project method) in REST must be set individually according to your needs. By default: - all tables and all attributes are accessible in REST, - project methods are not accessible in REST. Starting Wakanda REST services By default, 4D Server v14 does not respond to REST requests. You must enable Wakanda REST services in order for these requests to be processed and so that the Wakanda / 4D connector can be used. Note REST services use the 4D HTTP server, so you need to make sure that the 4D Web server or 4D Server is started. To activate Wakanda REST services: 1 In the Database Settings, display the Web/REST page. 2 Check the Activate Wakanda REST service option: The warning message "Caution, check the access privileges" is displayed to draw your attention to the fact that when Wakanda REST services are activated, by default access to database objects is free as long as the REST accesses have not been controlled (see below). Control of REST accesses Control of REST accesses lets you authorize (or not) the opening of a session on the 4D side following a Wakanda REST request. Note As part of a Wakanda REST access, the identifiers checked are the name and password send during the Execution of the mergeoutsidecatalog() method D v14 Upgrade

119 Configuring the 4D database At the global level, there are two ways to control REST accesses: either automatically, by means of 4D passwords, or by programming by means of the new On REST Authentication database method. These two control modes are exclusive: if an On REST Authentication is defined, the control of automatic accesses by 4D passwords is disabled. Warning: if neither of these two control modes are enabled, accesses to the database through REST are always accepted (not recommended). Automatic controls by 4D password In 4D, you can specify the group of 4D users that is authorized to establish the link to the 4D server from the Wakanda application. To designate the logon account: 1 In the Database Settings, display the Web/REST page. 2 Choose the group to use in the "Read/Write" menu of the Access area: By default, the menu displays <Anyone>, which means that REST accesses are open to all users. 4D v14 Upgrade 119

120 Chapter 5 4D Mobile Once you have specified a group, only a 4D user account that belongs to this group may be used to access 4D by means of a Wakanda REST request -- in particular, to open a session on the 4D Server using the mergeoustidecatalog() method. If an account is used that does not belong to this group, 4D returns an authentication error to the sender of the request. Note that in order for this setting to take effect: the 4D password system must be activated (a password must have been assigned to the Designer), the On REST Authentication must not be defined. If it exists, 4D does not take into account any access settings defined in the Database Settings. On REST Authentication On REST Authentication ( $1; $2 ; $3 ) $0 Parameter Type Description $1 Text User name $2 Text Password $3 Boolean True = Digest mode False = Basic mode $0 Boolean True = request accepted, False = request rejected The On REST Authentication database method provides you with a custom way of controlling the opening of REST sessions on 4D. When the request to open a REST session comes from Wakanda Server by means of the mergeoutsidecatalog() method (general case), the connection identifiers are provided in the header of the request. The On REST Authentication database method is called so that you can evaluate these identifiers. You can use the list of users for the 4D database or you can use your own table of identifiers. Important: When the On REST Authentication is defined (i.e. when it contains code), 4D fully delegates control of REST requests to it: any setting made using the "Read/Write" menu on the Web/REST page of the Database Settings is ignored (see the Automatic controls by 4D password paragraph on page 119) D v14 Upgrade

121 On REST Authentication The database method receives two parameters ($1 and $2) of the Text type and a Boolean ($3), passed by 4D, and returns a Boolean, $0. You must declare these parameters as follows: // On REST Authentication C_TEXT($1;$2) C_BOOLEAN($0;$3)... // Code for the method $1 contains the user name and $2 the password used for the connection. The password ($2) can be received either in clear or hashed form, depending mode used by the request. This mode is indicated by the $3 parameter to enable you to perform the appropriate processing: If the password is sent in clear (Basic mode), $3 returns False. If it is sent in hashed form (Digest mode), $3 returns True. When a REST connection request comes from Wakanda Server, the password is always sent in hashed form. When requests do not come from Wakanda Server, it is up to the developer to manage authentication from the original HTML/JavaScript page by including the "username-4d" and "password- 4D" fields in the HTTP headers. In this case, the password must be sent in clear to the 4D REST Server (using SSL to avoid the risk of interception by a third party). You must check the identifiers of the REST connection in the database method. Usually, you check the name and password using a custom user table. If the identifiers are valid, pass True in $0. The request is then accepted; 4D executes it and returns the result in JSON. Otherwise, pass False in $0, in this case, the connection is rejected and the server returns an authentication error to the sender of the request. If the user is referenced in the list of 4D users of the database, you can check the password directly by means of the following statement: $0 := Validate password($1 ; $2 ; $3) Note The Validate password command has been extended to accept a user name as first parameter as well as an optional parameter indicating whether the password is expressed in hashed form (see the Validate password command on page 316). 4D v14 Upgrade 121

122 Chapter 5 4D Mobile If you want to use your own list of users external to the 4D database list, you can save their passwords in hashed form using the same algorithm as that used by Wakanda Server when sending the connection request to the On REST Authentication database method in $2. To hash a password using this method, you can write: $HashedPasswd := Generate digest ($ClearPasswd ; 4D digest) Note The Generate digest command now accepts 4D digest as a hashing algorithm, corresponding to the method used by 4D for its internal management of passwords (see the Generate digest command on page 312). This example of On REST Authentication only accepts the "admin" user with the password "123" that does not match a 4D user: C_TEXT ($1;$2) C_BOOLEAN ($0;$3) //$1: user //$2: password //$3: digest mode If ($1 = "admin") If ($3) $0 := ($2 = Generate digest ("123" ; 4D digest)) Else $0 := ($2 = "123") End if Else $0 := False End if This example of On REST Authentication checks that the connection request comes from one of the two authorized Wakanda servers, saved in the users of the 4D database: C_TEXT ($1;$2) C_BOOLEAN ($0) ON ERR CALL ("REST_error") If ($1="WAK1") ($1="WAK2") $0 := Validate password ($1 ; $2 ; $3) Else $0:=False End case 122 4D v14 Upgrade

123 On REST Authentication Setting 4D objects exposed in REST Once Wakanda REST services are enabled in the 4D database, by default a REST session can access all tables and fields of the database, and thus use their data. For example, if your database contains an [Employee] table, it is possible to write, on the Wakanda side: var emp=ds.employee.query("name == Martin "); //Return all employees whose name field is Martin Note 4D tables and/or fields that have the "Invisible" attribute are also exposed in REST by default. The Wakanda server can also access the project methods of the 4D database. However, by default, this access is disabled for security reasons. If you want to customize the list of database objects accessible in REST, you must: disable the exposure of each table and/or field that you want to hide, enable exposure of each project method to which you want to give access. When a REST request attempts to access an unauthorized resource (table or project method), 4D returns an error. Exposing tables By default, all tables are exposed in REST. For security reasons, you may want to only expose certain tables of your database to REST calls. For instance, if you created a [Users] table storing user names and passwords, it would be better not to expose it. To modify the REST exposure for a table: 1 Display the Table Inspector in the Structure editor and select the table you want to modify. 4D v14 Upgrade 123

124 Chapter 5 4D Mobile By default, the Expose with REST Service option is checked: 2 Uncheck the Expose with REST Service option. OR Check this option to expose a table. Do this for each table whose exposure needs to be modified. Exposing fields By default, all field are exposed in REST. You may not want to expose certain fields of your tables through REST. For example, you may not want to expose the [Employees]Salary field. To modify the REST exposure for a field: 1 Display the Field Inspector in the Structure editor and select the field you want to modify. By default, the Expose with REST Service option is checked: 124 4D v14 Upgrade

125 On REST Authentication 2 Uncheck the Expose with REST Service option for the field. OR Check this option to expose a field that was unchecked. Repeat this for each field whose exposure needs to be modified. Note that in order for a field to be accessible in REST, the parent table must be as well. If the parent table is not exposed, none of its fields will be, regardless of their status. Because of this, you can temporarily enable/disable REST exposure for a table, while the individual values of the Expose with REST server option for each field remain unchanged. Exposing project methods No project methods are exposed in REST by default. You may want to make certain project methods of your 4D database accessible by means of REST. To do this, you must check the appropriate option and define the REST execution context of the method. Note If an access group is associated with the 4D method, you need to make sure that the REST group is part of this group. To set REST exposure for a project method: 1 Display the "Method Properties" dialog box. Note You can access the method properties dialog box using the context menu on the "Methods" page of the Explorer, or from the Method/Method Properties... menu in the Method editor. 4D v14 Upgrade 125

126 Chapter 5 4D Mobile 2 Check the Available through REST call option: 3 Define the REST execution context for the project method by means of the Table and Scope menus. These settings are required in order to respect the REST syntax and the logic of Wakanda. For more information about this point, refer to the following section. 4 Click on OK to validate the changes. Project methods available through REST are listed in the "REST Methods" section of the 4D Explorer (see the Explorer paragraph on page 128) D v14 Upgrade

127 On REST Authentication Parent table and Scope of project methods When you declare a project method available through REST requests, you must explicitly declare its calling context using the Table and Scope parameters: Table: table to be attached with the project method. During REST calls, the method may be reached by means of the /tablename/methodname syntax. The menu displays the list of database tables that are exposed in REST. Select the table whose data is handled by the method. You can also create, for example, a [RESTInterface] table and associate all the project methods exposed in REST with it. Scope: span of records where method is applied. This declaration is necessary because, on the Wakanda side, methods are properties of JavaScript objects and can only be called by means of these objects. Each 4D method that is exposed must be explicitly associated with the database context where it will be called: Table, Current record and Current selection. Table: This option indicates that the 4D method will be executed using all the records of the designated table. On the Wakanda side, the method will be called on an object of the Datastore class type. Current record: This option indicates that the 4D method will be executed using the current record of the designated table. On the Wakanda side, the method will be called on an object of the Entity type. Current selection: This option indicates that the 4D method will be executed using the current selection of records of the designated table. On the Wakanda side, the method will be called on an object of the Entity Collection type. When you change the exposure or scope of a project method on the 4D side, you have to reload the remote model on the Wakanda side for these changes to be taken into account. 4D v14 Upgrade 127

128 Chapter 5 4D Mobile Explorer When Wakanda REST services are enabled, the tables exposed in REST and the project methods attached to them are displayed on the "Methods" page of the 4D Explorer in the REST Methods section: Configuration of Wakanda application Execution of the mergeoutsidecatalog () method On the Wakanda Enterprise side, you usually execute the mergeoutsidecatalog() JavaScript method to connect to a 4D v14 database. Once a connection is established between Wakanda and 4D, the Wakanda application can use all the exposed tables, attributes and project methods of the 4D application as local objects. You can also use this method to execute additional JavaScript code. For example, you could locally modify properties of remote attributes, or extend classes, or add calculated attributes. The mergeoutsidecatalog() JavaScript method designates a catalog of remote data and uses it within your current Wakanda model. You must call this method in the.js file associated with the current model and executed by the Wakanda server. There are two possible syntaxes: Direct syntax: model.mergeoutsidecatalog(localname, address, user, password); 128 4D v14 Upgrade

129 Configuration of Wakanda application Syntax using an object: model.mergeoutsidecatalog(localname, { hostname: address, user: username, password: password, jsfile: jsfilepath timeout: minutes }); The advantage of using the syntax with an object is that you can add a.js file that is executed after connection to the 4D database. This file can locally modify the catalog referenced from the remote database. Parameter Type Description localname String Local name of remote catalog ipaddress String Address of remote data server (use HTTPS for added security) username String User name for opening of session password String Password for opening of session jsfilepath String (optional) Pathname of JavaScript file timeout Num (optional) Timeout for client connection to 4D database in minutes (60 by default) Note For a detailed description, refer to the documentation of the mergeoutsidecatalog() method in the Wakanda Server-Side API manual. model The model object indicates the current "model" of the Wakanda application, in other words, the set of its "datastore classes" (tables) and methods. In the context of a 4D Mobile architecture, the Wakanda model can be empty. If the Wakanda application already contains objects, the classes and methods referenced from the remote 4D application are merged with the local model. 4D v14 Upgrade 129

130 Chapter 5 4D Mobile When the connection is established successfully, the "exposed" 4D tables are added to the classes of the model on the Wakanda side. In Wakanda Enterprise Studio, you can see the remote tables among the list of classes for the local model. They are indicated by a red arrow: Wakanda Studio - Explorer Remote tables The external catalog is also represented in Wakanda Studio by a specific file named localname.waremotecatalog: You can double-click on this file to view the external catalog in the model editor of Wakanda Studio: jsfile The jsfile property can contain the relative pathname of a JavaScript file located in the same folder as the model. This file is executed by Wakanda after the merger of the external catalog. It can modify the local version of the model, for the sake of customization, optimization, or security. Using this file, you can: modify properties of datastore class attributes, such as events or the scope. Example: model.classname.attributename.scope ="publiconserver" add calculated attributes to datastore classes. Example: model.classname.attributename.onget = function() model.classname.attributename.onset = function() 130 4D v14 Upgrade

131 Configuration of Wakanda application create local datastore classes derived from tables of the external catalog, to fully control data sent to clients. A derived datastore class can present a custom view of an external table, while maintaining overall access to the extended (parent) datastore class on the Wakanda server. Example: model.derivedclass = new DataClass("Emps", "public", "My4DTable") remove attributes from derived local datastore classes, by security or to optimize network traffic. Example: model.derivedclass = new DataClass("Emps", "public", "My4DTable") model.derivedclass.removeattribute("salary"); model.derivedclass.removeattribute("comments"); model.derivedclass.removeattribute("..."); With this example, you create a derived class named "DerivedClass", based on the "My4DTable" class, which sends only the attributes that you want using the network. For more information about JavaScript code for working with models, refer to the Model chapter in the Wakanda documentation. Example of direct connection: model.mergeoutsidecatalog("base4d","localhost:80", "admin", "123456"); Example of connection using an object: model.mergeoutsidecatalog("base4d", { hostname: " user: "wak", password: "123456", jsfile: "Model2.js" timeout: 15 }); Calling 4D tables 4D tables referenced in the Wakanda application can be used directly in the server-side JavaScript code as properties of the ds object, just like local datastore classes. Note The ds object contains the current datastore of the Wakanda application. 4D v14 Upgrade 131

132 Chapter 5 4D Mobile For example, to perform a query in the records of the [Employees] table, you can write: var emp = ds.employees.query("age > :1",30); // retrieve a collection of records from the Employees table // where age is greater than 30 in the emp variable On the client side, you can also take advantage of automatic mechanisms of the datasources based on the datastore classes and associated with the widgets. For example, if you associate the employees datasource with a Grid type widget, you can display the list of employees automatically: 132 4D v14 Upgrade

133 Configuration of Wakanda application When the table is associated with a datasource, you can also access its data using this datasource. For example, to sort the collection of records of the employees datasource, you can write: sources.employees.orderby("age"); //sorts the collection of employees by their age For more information about working with datastore classes, refer to the Wakanda documentation ( Using relations Relations established between 4D tables are used tranparently in the context of a 4D Mobile link. However, the way these relations are represented differs in Wakanda at the model level. In the model editor, relations are linked with specific attributes, called relational attributes. These attributes can be used to display the linked data directly or to perform queries. For more information about this, refer to the "Attributes" section in the Wakanda documentation. For each relation established on the 4D side, two relational attributes are added in the model representation on the Wakanda side: an n->1 attribute in the source table (class) of the relation a 1->n attribute in the destination table (class) of the relation. Both these attributes are given the name of the relation as it was defined respectively for the many-to-one and one-to-many relation in the Inspector on the 4D side. 4D v14 Upgrade 133

134 Chapter 5 4D Mobile For example, let s imagine that in the context of a "Employee/Company" structure, you create a relation from the [Employee] table to the [Company] table. You can characterize this relation by means of the name you give it: for example, you could name the many-to-one relation "worksfor" and the one-to-many relation could be "employs": 134 4D v14 Upgrade

135 Configuration of Wakanda application On the Wakanda side, through a link via the connector, these relations are automatically materialized by two additional relational attributes, that you can see in the model editor: You can give these relations (and thus their corresponding relational attributes) any name you want, based on the logic of your application. The advantage of this is that it is very simple to use these attributes on the Wakanda side to work with the related data. More particularly, you can create widgets associated with datasources that are based on relational attributes. These widgets are then managed and updated automatically according to user actions. For instance, it is very simple to create a page containing one grid with the list of companies, and another listing the employees of the company selected. 4D v14 Upgrade 135

136 Chapter 5 4D Mobile To do this, you just associate the "Company" datastore class with one grid, and the "employs" relational attribute with the other: 136 4D v14 Upgrade

137 Configuration of Wakanda application The corresponding datasources are automatically created, and during execution, both grids are synchronized automatically: Calling 4D methods Scope and objects 4D methods referenced in the Wakanda application can be used directly in the JavaScript code as properties of the datastore class, entity collection or entity objects, depending on their scope as defined on the 4D side (see the Parent table and Scope of project methods paragraph on page 127). Here is the correspondence between Wakanda objects and the scope of the project methods: 4D scope table current selection current record Wakanda object datastore class entity collection entity Note 4D methods can also be called on the client side using datasources (see below); in this case all the methods are available, and the datasource applies them automatically to the current collection or the current entity depending on the context. For example, if you perform a query using the query method (see previous section), Wakanda returns an entity collection. You can execute any 4D project method whose scope is declared as "current selection" on this collection. 4D v14 Upgrade 137

138 Chapter 5 4D Mobile Server and Client There are three ways for 4D methods to be called by JavaScript code: From the JavaScript code executed on the server (SSJS), using the SSJS Datastore API. In this case, 4D methods are called as properties of the datastore class, entity collection or entity objects, as described above. Example: var vtot = ds.emp.raisesalary(param)) From the JavaScript code executed on the client (i.e., the browser) using the Wakanda Ajax Framework (WAF). There are two possibilities: using WAF Datasource API: this high-level API provides many automatic functions for managing data. With this API, 4D methods are called as properties of datasources associated with datastore classes and will be applied automatically to the datastore class, the current entity collection, or the current entity depending on the context. You can manage return values of the methods or any errors using the asynchronous syntax (required for code executed on the client). Example: sources.employee.raisesalary(param, {onsuccess: function(event) {... //code to execute when method has finished} })) It is not mandatory to use a callback function because datasource objects have automatic functions that support, for example, updating data displayed in the current collection after a query. using WAF Dataprovider API: this low-level client API lets you work with objects directly. As with the SSJS Datastore API, 4D methods are called as properties of the datastore class, entity collection or entity objects. However, you must manage the return values of the methods or any errors using the asynchronous syntax (required for code executed on the client). Example: ds.employee.raisesalary(param, // syntax resembles a SSJS call {onsuccess: function(event)// but it s client-side code so you must // manage the callback method of the asynchronous call {... code to execute when 4D method has finished} })) The choice of location (server or client) and API depends on the needs of the application and is described in the Wakanda documentation D v14 Upgrade

139 Configuration of Wakanda application Parameters As with standard methods, you can pass parameters during the call, which are received in order in the parameters $1, $2, and so on. Similarly, the method can return a result in the $0 variable. You want to give a 5% raise to employees whose salary is less than On the 4D side, the IncreaseSalary method was exposed through REST and its scope is the "Current selection". Its code is as follows: C_REAL($1) READ WRITE ([Employees]) FIRST RECORD ([Employees]) While (Not (End selection ([Employees]))) [Employees]salary:=[Employees]salary*$1 SAVE RECORD ([Employees]) NEXT RECORD ([Employees]) End while UNLOAD RECORD ([Employees]) On the Wakanda side, you execute the following code on the server: var emp = ds.employees.query("salary < :1",1500); // emp contains the collection of employees whose salary is <1500 emp.increasesalary(1.05); //execute the IncreaseSalary method on the collection //You could also write: //"ds.employees.query("salary < :1",1500).IncreaseSalary(1.05); Update of 4D context When calling a 4D method by means of the Wakanda link: If the method applies to a selection (entity collection), it becomes the current selection and 4D is positioned on the first record of this selection without loading it or activating the links. If the selection is empty, the Selected record number command returns 0 instead of 1. If the method applies to a record (entity), it becomes the current record and is loaded in read-write state. The current selection is reduced to just this record and the Selected record number command returns 1. If the method applies to a table (datastore class), neither the current selection nor the current record are affected. Note that after executing a method through REST, the 4D context is reset: selections are reduced to 0, records are unstacked and unloaded, local selections and sets for the process are destroyed, 4D v14 Upgrade 139

140 Chapter 5 4D Mobile any transactions open during method execution are canceled, the configuration of automatic relations by fields, query destinations or queries on the server are reset, print jobs are canceled, windows are closed, any SQL, PHP or HTTP connections are closed. Scope error You must make sure the scope of the 4D method corresponds to the type of Wakanda object that is calling it, otherwise a "TypeError: 'undefined' is not a function" error is returned by Wakanda. For example, given the 4D "getcursel" method containing the following code: $0:=Records in selection([table_1]) Given the run method on the Wakanda side: var tt = ds.table_1.query("field_2 = 'a*'").getcursel(); The query( ) method returns a collection. If the scope of the getcursel method was set as "Current record", Wakanda returns the following error: TypeError: 'undefined' is not a function (evaluating 'ds.table_1.query("field_2 = 'a*'").getcursel()')". openremotestore() and addremotestore() The openremotestore() and addremotestore() methods are alternative ways of establishing dynamic links between a Wakanda application and a 4D application. Like mergeoutsidecatalog(), these methods provide dynamic access to the data of 4D databases but they work in a different way: they can reference a remote model at any time during the Wakanda session -- and not just when the solution is loaded. tables, attributes and methods of the external model can be accessed by means of a separate datastore; they are not merged with the local model of the Wakanda application (accessed by means of the ds object). openremotestore() only returns a valid reference in the current JavaScript context, whereas addremotestore() maintains the reference throughout the session D v14 Upgrade

141 About 4D Mobile application security For more information, refer to the description of the openremotestore() and addremotestore() methods in the Wakanda documentation. About 4D Mobile application security Once data from 4D database tables exposed through REST is integrated into the Wakanda catalog, you need to restrict access to certain "sensitive" resources. Unlike 4D applications, with Web applications you cannot use the interface to control the data exposed: for example, (just because a field is not displayed in the form does not make it inaccessible to the user) simply not displaying a field in a form does not make it/ you cannot just Not display a field in a form in order to make it inaccessible to the user. HTTP requests and the use of JavaScript can allow malicious users to potentially obtain any information from an insufficiently protected Web server. The purpose of this section is not to list all the security measures to take with 4D Mobile applications but to provide you with leads to help secure the data exposed in a minimal way. Protection of REST accesses to the 4D database: You must control REST connection requests. You can use either: 4D passwords (see Automatic controls by 4D password), the On REST Authentication database method. Control REST exposure on the 4D side: Each table, attribute and method can be exposed (or not) through REST. Only expose the data and methods that are strictly necessary; for instance, there is no need to expose any unused fields. Protection of exposed data: You must use the security systems provided by Wakanda to control the contents that are accessible by means of browsers. There are several ways to do so (not exclusive): Adjust the scope of the attributes and methods from the 4D database. In particular, you can set their scope as Public on Server, which means that they can be access freely for code run on the server, but they will not be accessible on Web clients. 4D v14 Upgrade 141

142 Chapter 5 4D Mobile This setting is done in the additional.js file that is executed by the mergeoutsidecatalog() method. For more information, refer to the Model API page of the Wakanda documentation. Use calculated attributes: calculated attributes work like standard attributes but their values are returned by specific functions (onget, onset...) that are executed when accessing the fields. This means that you can expose only the necessary calculated attributes without exposing the fields of the 4D database. Access to the 4D fields are performed from the Wakanda server in a secure manner. You can add calculated fields in the additional.js file that is executed by the mergeoutsidecatalog() method. For more information, refer to the Attributes page of the Wakanda documentation D v14 Upgrade

143 6 Language This chapter covers what is new or modified in the programming language of 4D v14. 4D Environment New commands Get last update log path Get last update log path String Function result String Pathname of most recent update log The Get last update log path command returns the complete pathname of the most recent update log file found on the machine where it is called. The update log is generated by the updater tool, used by 4D for automatic update processes. It contains information about the updates performed as well as any errors that occurred. See also: RESTART 4D, SET UPDATE FOLDER 4D v14 Upgrade 143

144 Chapter 6 Language RESTART 4D RESTART 4D {( time{; message} )} Parameter Type Description time Longint Time delay (seconds) before 4D restarts message String Text to display on client machines The RESTART 4D command restarts the current 4D merged application. This command is intended for use in the context of a merged application (client/server or single-user) and must be used in conjunction with the SET UPDATE FOLDER command. In this case, the automatic update process is launched: the new version of the application designated by SET UPDATE FOLDER automatically replaces the current version at the time of the restart resulting from RESTART 4D. The pathname of the data file is saved and used automatically. Note If no update information was specified using the SET UPDATE FOLDER command in the current session, the command simply restarts the merged application with the same data file. RESTART 4D cannot be used outside of this context. In particular, it does not work for a 4D database that is not merged. You can use the time parameter to defer restarting the application in order to give client machines time to disconnect. You must pass a value in seconds for the time. If you omit this parameter, the server application waits, for a maximum of 10 minutes, for all the client applications to be disconnected. After that, all client applications are automatically disconnected. Note The time parameter is only taken into account with server applications (it is ignored in the case of a single-user application). The optional message parameter displays a custom message for connected client applications. If the command is executed correctly, the OK system variable is set to 1; otherwise, it is set to 0 and the application restarts. You can intercept any errors generated by the command using a method installed using the ON ERR CALL command. See also: SET UPDATE FOLDER 144 4D v14 Upgrade

145 SET UPDATE FOLDER SET UPDATE FOLDER SET UPDATE FOLDER ( folderpath{; silenterrors}) Parameter Type Description folderpath String Pathname of folder (package under OS X) containing updated application silenterrors Boolean False (default) = display error messages, True = log errors silently The new SET UPDATE FOLDER command specifies the folder containing the update of the current merged 4D application. This information is stored in the 4D session until the RESTART 4D method is called. If the application is exited manually, this information is not kept. This command is intended to be used in an automatic update process for a merged application (server or single-user). For more information, refer to the Automating updating of server applications paragraph on page 35 Note This command only works with 4D Server or a single-user application merged with 4D Volume Desktop. In the folderpath parameter, pass the complete pathname for the folder of the new version of the merged application (folder containing the my4dapp.exe application under Windows or the my4dapp.app package under OS X). The new version must have been generated by the 4D v14 application builder. More particularly, it must contain a current version of the "updater" tool used to manage remote updates (see the Application builder paragraph on page 35). Note We recommend that you use the same names for the files in the new version of the application as the ones in the original, since the application folder is replaced during the update. If you use different names for these files, any stored shortcuts and/or paths will not work. If the parameters are valid, the update is placed "on hold" in the session until the RESTART 4D command is called. If you executed SET UPDATE FOLDER several times before calling RESTART 4D, the last valid call is taken into account. In case of anomaly, an error is generated; the silenterrors parameter determines whether or not these errors are displayed (see below). You can pass an empty string ("") in the folderpath parameter to reset the update information for the current session. 4D v14 Upgrade 145

146 Chapter 6 Language Modified commands The optional silenterrors parameter specifies how errors are reported by the updater tool: When you pass False or when this parameter is omitted, errors are recorded in the update journal and displayed in a warning dialog box. If you pass True, errors are simply recorded in the update journal. Exception: if the updater tool cannot create the journal file, a warning dialog box is displayed, regardless of the value of the silenterrors parameter. If the command is executed correctly, the OK system variable is set to 1; otherwise, it is set to 0. You can intercept any errors generated by the command using a method installed using the ON ERR CALL command. You created a "MyUpdates" folder on your disk, where you placed a new version of the "MyApp" application. You do not want to display errors. To prepare the update, you write: // Windows syntax SET UPDATE FOLDER("...MyUpdates"+Folder separator+ "MyApp";True) // OS X syntax SET UPDATE FOLDER("...MyUpdates"+Folder separator+ "MyApp.app";True) See also: RESTART 4D GET MEMORY STATISTICS GET MEMORY STATISTICS ( infotype ; arrnames ; arrvalues ; arrcount ) The GET MEMORY STATISTICS command returns two additional items of general information when you pass selector 1 in infotype: stack memory and free stack memory D v14 Upgrade

147 SET DATABASE PARAMETER, Get database parameter SET DATABASE PARAMETER, Get database parameter SET DATABASE PARAMETER ( {table; }selector; value ) Get database parameter ( {table; }selector{; stringvalue} ) Real The SET DATABASE PARAMETER, Get database parameter commands accept three new selectors and selector 34 is modified: Selector = 34 (Debug log recording) A new, more compact, tabbed text format is used in the event log file "4DDebugLog[_n].txt" for 4D v14 (where _n is the segment number of the file). The functioning of selector 34 is modified in order to allow you to enable and configure this new format. Values: now expects a Longint containing a bit field: value = bit1(1)+bit2(2)+bit3(4)+bit4(8)+ ). - Bit 1 (value 1) requests to enable the file (note that any other nonnull value also enables it as well) - Bit 2 (value 2) requests call parameters to methods and commands. - Bit 3 (value 4) enables new tabbed format. - Bit 4 (value 8) disables immediate writing of each operation on disk (enabled by default). Immediate writing is slower but more effective, for example for investigating causes of a crash. If you disable this mode, the file contents are more compact and are generated more quickly. - Bit 5 (value 16) disables recording of plug-in calls (enabled by default). (Compatibility note: Execution times are now always included in the file.) Examples: SET DATABASE PARAMETER (34;1) // enables mode v13 file without parameters, with runtimes SET DATABASE PARAMETER (34;2) // enables mode v13 file with parameters and runtimes SET DATABASE PARAMETER (34;2+4) // enables file with v14 format, with parameters and runtimes SET DATABASE PARAMETER (34;0) // disables file For more information about this format and on the use of the 4DDebugLog[_n].txt file, please contact the Technical Support of 4D Inc. 4D v14 Upgrade 147

148 Chapter 6 Language Selector = 81 (Spellchecker) Description: Enable Hunspell correction under OS X. Values: 0 (default) = native OS X spellcheck (Hunspell disabled), 1 = Hunspell spellcheck enabled. This parameter lets you enable the Hunspell spellchecker under OS X. By default, the native spellcheck is enabled on this platform. You may prefer to use the Hunspell spellcheck, for example, in order to unify the interface for your cross-platform applications (under Windows, only the Hunspell spellcheck is available). For more information about spellchecking in 4D v14, refer to the Spell checking paragraph on page 84 (interface) and to the Spell Checker paragraph on page 277 (language). Selector = 82 (QuickTime support) Description: Activation of QuickTime support. Values: 0 (default) = QuickTime disabled, 1 = QuickTime enabled. In 4D v14, by default QuickTime codecs are no longer supported (obsolete function, see the QuickTime paragraph on page 16). For compatibility, you can use this selector to re-activate them in your application. However, you should note that in future versions of 4D, QuickTime support is permanently removed. Selector = 85 (JSON use local time) Description: Choice of conversion mode for 4D dates to and from JSON. Values: 0 = ignore local time zone, 1 (default) = take time zone into account. In 4D v14, 4D dates converted to JSON format take the local time zone into account. For example, converting the date!23/08/2013! gives you " T22:00:00Z" in JSON format when the operation is performed in France during Daylight Savings Time (GMT+2). This principle conforms to the standard operation of JavaScript. This can be a source of errors when you want to send JSON date values to someone in a different time zone. This is the case, for example, when you export a table using Selection to JSON in France that is meant to be imported in the US using JSON TO SELECTION D v14 Upgrade

149 Version type By default, since dates are re-interpreted in each time zone, the values stored in the database will be different. In this case, you can modify the conversion mode for dates so that they do not take the time zone into account by passing 0 in this selector. Converting the date!23/08/2013! will then give you " T00:00:00Z" in all cases. You want to export data in JSON that contains a converted 4D date. Note that conversion occurs when the date is saved in the object, so you must call the SET DATABASE PARAMETER command before calling OB SET: C_OBJECT($o) SET DATABASE PARAMETER(JSON use local time; 0) OB SET( $o ; "mydate" ; Current date) // JSON conversion $json:=json Stringify($o) SET DATABASE PARAMETER(JSON use local time; 1) Version type Version type Longint Function result Longint Demo or full version, 64-bit or 32- bit version, 4D database / Merged application A new constant added to the "4D Environment" theme detects whether the current version is a merged application: Constant (value) Merged application (2) Comments Version is an application merged with 4D Engine This test lets you run different code depending on whether the version is a merged application or a database opened by 4D / 4D Server: If (Version type?? Merged application) // We are in a merged application Else // We are in a database executed by 4D End if 4D v14 Upgrade 149

150 Chapter 6 Language Arrays ARRAY BLOB ARRAY BLOB ( arrayname ; size {; size2} ) Parameter Type Description arrayname Array Name of array size Longint Number of array elements or Number of arrays if size2 is specified size2 Longint Number of 2D array elements The new ARRAY BLOB command creates and/or resizes an array of Blob type elements in memory. The arrayname parameter is the name of the array. The size parameter is the number of array elements. The size2 parameter is optional. If you pass it, this command creates a two-dimensional array. In this case, size specifies the number of rows and size2 the number of columns in each array. Each row in a twodimensional array can be processed both as an element and an array. This means that when you work with the first dimension of a twodimensional array, you can insert and remove entire arrays using other commands in this theme. When you apply the ARRAY BLOB command to an existing array: If you enlarge its size, existing elements are not changed and new elements are initialized to an empty BLOB (BLOB size = 0). If you reduce its size, elements at the "bottom" of the array are deleted and lost. This example creates a process array containing 100 BLOB-type elements: ARRAY BLOB (arrblob;100) This example creates a local array of 100 rows each containing 50 BLOB-type elements: ARRAY BLOB ($arrblob;100;50) 150 4D v14 Upgrade

151 ARRAY OBJECT This example creates a local array of 100 rows each containing 50 BLOB-type elements. The $vbytevalue variable receives the 10th byte of the BLOB placed in the 7th column and the 5th row of the BLOB array: C_INTEGER ($vbytevalue) ARRAY BLOB ($arrvalues;100;50)... $vbytevalue:=$arrvalues{5}{7}{9} ARRAY OBJECT ARRAY OBJECT ( arrayname ; size {; size2} ) Parameter Type Description arrayname Array Name of array size Longint Number of array elements or Number of arrays if size2 is specified size2 Longint Number of 2D array elements The new ARRAY OBJECT command creates and/or resizes an array of Language object type elements in memory. Note Language objects are a new data type supported by the language of 4D v14. For more information, refer to the Objects (Language) paragraph on page 256. The arrayname parameter is the name of the array. You can use any name that conforms to 4D conventions. The size parameter is the number of array elements. The size2 parameter is optional. If you pass it, this command creates a two-dimensional array. In this case, size specifies the number of rows and size2 the number of columns in each array. Each row in a twodimensional array can be processed both as an element and an array. This means that when you work with the first dimension of a twodimensional array, you can insert and remove entire arrays using other commands in this theme. When you apply the ARRAY OBJECT command to an existing array: If you enlarge its size, existing elements are not changed and new elements are undefined. You can test whether an element is defined using the OB Is defined command. If you reduce its size, elements at the "bottom" of the array are deleted and lost. 4D v14 Upgrade 151

152 Chapter 6 Language Creation of a process array of 100 Object-type elements: ARRAY OBJECT (arrobjects;100) Creation of a local array of 100 rows each containing 50 Object-type elements: ARRAY OBJECT ($arrobjects;100;50) Creation and filling of a local object array: C_OBJECT ($Children;$ref_richard;$ref_susan;$ref_james) ARRAY OBJECT ($arraychildren;0) OB SET ($ref_richard;"name";"richard";"age";7) APPEND TO ARRAY ($arraychildren;$ref_richard) OB SET ($ref_susan;"name";"susan";"age";4) APPEND TO ARRAY ($arraychildren;$ref_susan) OB SET ($ref_james;"name";"james";"age";3) APPEND TO ARRAY ($arraychildren;$ref_james) // $arraychildren{1} -> {"name":"richard","age":7} // $arraychildren{2} -> {"name":"susan","age":4} // $arraychildren{3} -> {"name":"james","age":3} See also: C_OBJECT, Objects (Language) ARRAY TIME ARRAY TIME ( arrayname ; size {; size2} ) Parameter Type Description arrayname Array Name of array size Longint Number of array elements or Number of arrays if size2 is specified size2 Longint Number of 2D array elements The new ARRAY TIME command creates and/or resizes an array of Time type elements in memory. Remember that in 4D, times can be processed as numeric values. In previous versions of 4D, you had to combine a longint array with a display format in order to manage an array of times. The arrayname parameter is the name of the array. The size parameter is the number of array elements D v14 Upgrade

153 ARRAY TIME The size2 parameter is optional. If you pass it, this command creates a two-dimensional array. In this case, size specifies the number of rows and size2 the number of columns in each array. Each row in a twodimensional array can be processed both as an element and an array. This means that when you work with the first dimension of a twodimensional array, you can insert and remove entire arrays using other commands in this theme. When you apply the ARRAY TIME command to an existing array: If you enlarge its size, existing elements are not changed and new elements are initialized to the null time value (00:00:00). If you reduce its size, elements at the "bottom" of the array are deleted and lost. When you apply SELECTION TO ARRAY, SELECTION RANGE TO ARRAY to a Time type field, note that they only create a Time type array if the array has not already been defined as another type, such as Longint for example. Note The Time function now accepts a number parameter representing the number of seconds. This example creates a process array containing 100 Time-type elements: ARRAY TIME (arrtimes;100) This example creates a local array of 100 rows each containing 50 Time-type elements: ARRAY TIME ($arrtimes;100;50) Since time arrays accept numeric values, the following code is valid: ARRAY TIME ($arrtimevalues;10) $CurTime:=Current time+1 APPEND TO ARRAY ($arrtimevalues;$curtime) $Found:=Find in array ($arrtimevalues;$curtime) See also: Time 4D v14 Upgrade 153

154 Chapter 6 Language ARRAY TO LIST ARRAY TO LIST ( array ; list {; itemrefs} ) Parameter Type Description array Array Array from which to copy array elements list String ListRef Name or reference of list into which to copy array elements itemrefs Array Item reference numbers The ARRAY TO LIST command now accepts a ListRef (longint) as the list parameter. This way you can copy the contents of an array directly into a hierarchical list. In other for this command to work, the list must have already been created (for example, using the New list command). In accordance with how the command works, only first level items in the list can be defined by the data of the array. You want to put the distinct values of a field into a list, for example to create a hierarchical pop-up menu. You can write: ALL RECORDS ([Company]) DISTINCT VALUES ([Company]country;$arrCountries) CountryList:=New list ARRAY TO LIST ($arrcountries;countrylist) See also: LIST TO ARRAY LIST TO ARRAY LIST TO ARRAY ( list ; array {; itemrefs} ) Parameter Type Description list String ListRef Name or reference of list from which to copy the first level items array Array Array to which to copy the list items itemrefs Array List item reference numbers The LIST TO ARRAY command now accepts a ListRef (longint) in the list parameter. This way you can convert a hierarchical list directly into an array. As per how the command works, only first level items in the list are exported to the array. If array does not exist, it is created and sized automatically by the command D v14 Upgrade

155 LIST TO ARRAY Given a hierarchical list created as follows: mylist2:=new list APPEND TO LIST (mylist2;"scotland";1) APPEND TO LIST (mylist2;"england";2) APPEND TO LIST (mylist2;"wales";3) mylist1:=new list APPEND TO LIST (mylist1;"france";1) APPEND TO LIST (mylist1;"germany";2) APPEND TO LIST (mylist1;"spain";3) APPEND TO LIST (mylist1;"great Britain";4;myList2;True) APPEND TO LIST (mylist1;"portugal";5) APPEND TO LIST (mylist1;"belgium";6) APPEND TO LIST (mylist1;"italy";7) APPEND TO LIST (mylist1;"netherlands";8) APPEND TO LIST (mylist1;"ireland";9) This list can be represented as: If you execute the following statement: LIST TO ARRAY (mylist1;$myarray)...you get: $MyArray{1} = "France" $MyArray{2} = "Germany" $MyArray{3} = "Spain" $MyArray{4} = "Great Britain" $MyArray{5} = "Portugal"... See also: ARRAY TO LIST 4D v14 Upgrade 155

156 Chapter 6 Language SELECTION TO ARRAY, SELECTION RANGE TO ARRAY In 4D v14, you can use the new ARRAY TIME command to define arrays of the Time type. When you apply the SELECTION TO ARRAY and SELECTION RANGE TO ARRAY commands to a Time type field, it is important to note that they only create a Time type array if the array has not already been defined as another type. For example, in the following context, the myarray array remains a Longint type array: ARRAY LONGINT (myarray; 0) SELECTION TO ARRAY ([mytable]mytimefield; myarray) See also: ARRAY TIME Backup INTEGRATE MIRROR LOG FILE INTEGRATE MIRROR LOG FILE ( pathname {; operationnum} ) Parameter Type Description pathname Text Name or pathname of the log file to be integrated operationnum Real variable Number of operation where integration begins Number of last operation integrated The new INTEGRATE MIRROR LOG FILE command integrates the log file designated by pathname into a 4D Server database, starting with the operationnum operation (optional). The command accepts to integrate any log file into the database, even if it does not correspond to the data file. This command is specifically intended for use in the context of a mirror database. In 4D v14, log file management has evolved (see the New data journaling paragraph on page 21). One consequence of this is the ability to use a log file as part of a "mirror" database: the "Use Log File" option can now be checked in the Database Settings of a 4D Server used as a logical mirror, thus allowing the implementation of a series of cascading mirror servers D v14 Upgrade

157 INTEGRATE MIRROR LOG FILE Unlike the existing INTEGRATE LOG FILE command, at the end of its execution INTEGRATE MIRROR LOG FILE does not replace the current log file with the integrated one: the current log file of the database continues to be used. Accordingly, any changes made during integration are saved in the current log file. In pathname, you pass an absolute or relative path to the database folder. If you pass an empty string in this parameter, a standard open file dialog box appears so that you can specify the file to be integrated. If this dialog box is canceled, no file is integrated and the OK system variable is set to 0. By default, when you omit the operationnum parameter, the command integrates all the operations of the log file. If you pass a value in the operationnum parameter, integration begins at the value specified. After integration, if you passed a variable in operationnum, this parameter contains the number of the last operation integrated. This allows you to follow on with subsequent log file integrations by directly passing the value returned in operationnum during the next call to INTEGRATE MIRROR LOG FILE. The following diagram details the integration process depending on the various cases. In the log file to be integrated, X is the number of the first operation and Y is the number of the last one: Case of : (operationnum < X-1) --> Error 1260 (Selected log file is too recent) : (operationnum >= X-1) and (operationnum <= Y) --> Start integration Case of : (Type of operation = "Addition") If (Record exists) --> Do nothing Else --> Add record End if : (Type of operation = "Modification") If (Record exists) --> Edit record Else --> Do nothing End if 4D v14 Upgrade 157

158 Chapter 6 Language : (Type of operation = "Deletion") If (Record exists) --> Delete record Else --> Do nothing End if End case Else // operationnum > Y --> Error 1261 (Selected log file is too old for database) End case Note that integration will stop at the first error encountered. In this case, if you want to continue with the integration you will need to use the MSC. BLOB BLOB TO VARIABLE, VARIABLE TO BLOB BLOB TO VARIABLE ( blob ; variable {; offset} ) VARIABLE TO BLOB ( variable ; blob {; offset *} ) These commands are adapted in 4D v14 in order to support language objects (see the Objects (Language) paragraph on page 256). With VARIABLE TO BLOB, if you pass a C_OBJECT object in the variable parameter, the command places it in the BLOB as JSON in UTF-8. If the C_OBJECT object contains pointers, their dereferenced values are stored in the BLOB, not the pointers themselves. The BLOB TO VARIABLE command performs the reverse operation D v14 Upgrade

159 Compiler Compiler C_OBJECT C_OBJECT ( {method ;} variable {; variable2 ;... ; variablen} ) Parameter Type Description method Method Name of method variable Variable Name(s) of variable(s) or parameter(s) ${...} to declare The new C_OBJECT command assigns the Object type to all the variables that are specified. Note The Object type is a new data type supported by the 4D v14 language. For more information, please refer to Objects (Language) paragraph on page 256. You use the first syntax of the command (when the method parameter is not passed) to declare and type a process, interprocess or local variable. This syntax can be used in interpreted databases. You use the second syntax of the command (when the method parameter is passed) to declare the method s result and/or parameters ($0, $1, $2, etc.) to the compiler in advance. You must use this syntax if you want to skip the variable typing phase in order to save time when the database is compiled. WARNING: You cannot execute the second syntax in interpreted mode. For this reason, when you use this syntax, you should store it in a method (whose name must begin with "COMPILER") that is not executed in interpreted mode. Advanced use: You can use the C_OBJECT(${...}) syntax to declare a variable number of parameters of the same type for a method as long as they are the last parameters of this method. For example, the declaration C_OBJECT(${5}) indicates to the compiler that beginning with the fifth parameter, the method can receive a variable number of parameters of this type. See also: ARRAY OBJECT, Objects (Language) 4D v14 Upgrade 159

160 Chapter 6 Language Database methods On Host Database Event $1 On Host Database Event Parameter Type Description $1 Longint Event code The new On Host Database Event database method allows 4D components to execute code when the host database is opened and closed. Note For security reasons, in order to be able to call this database method, you must explicitly allow its execution in the host database. For more information about this point, refer to the 4D components paragraph on page 33. The On Host Database Event database method is executed automatically only in databases used as components of host databases (when it is authorized in the Property List of the host database). It is called when events related to the opening and closing of the host database occur. To process an event, you must test the value of the $1 parameter inside the method, and compare it with one of the following new constants, available in the "Database Events" theme: Constant (value) On before host database startup (0) On after host database startup (1) Comments The host database has just been started. The On Startup database method of the host database has not yet been called. The On Startup database method of the host database is not called while the On Host Database Event database method of the component is running. The On Startup database method of the host database just finished running D v14 Upgrade

161 On Host Database Event On before host database exit (2) On after host database exit (3) This allows 4D components to load and save preferences or user states related to the operation of the host database. Example of typical structure of an On Host Database Event database method: // On Host Database Event database method C_LONGINT ($1) Case of :($1 = On before host database startup) // put code here that you want to execute before the "On Startup" // database method of the host database :($1 = On after host database startup) // put code here that you want to execute after the "On Startup" // database method of the host database :($1 = On before host database exit) // put code here that you want to execute before the "On Exit" // database method of the host database :($1 = On after host database exit) // put code here that you want to execute after the "On Exit" // database method of the host database End case The host database is closing. The On Exit database method of the host database has not yet been called. The On Exit database method of the host database is not called while the On Host Database Event database method of the component is running. The On Exit database method of the host database has just finished running. 4D v14 Upgrade 161

162 Chapter 6 Language On REST Authentication On REST Authentication ( $1; $2 ; $3 ) $0 Parameter Type Description $1 Text User name $2 Text Password $3 Boolean True = Digest mode False = Basic mode $0 Boolean True = request accepted, False = request rejected The new On REST Authentication database method is in charge of controlling access rights for REST requests sent to the Web server engine. When it is defined, it is automatically called by 4D or 4D Server when the server receives a REST request. This database method is mainly intended for filtering connections when setting up a connection between a Wakanda server and 4D v14. For more information, refer to the On REST Authentication paragraph on page 120. Date and Time Conversion of JavaScript dates Since dates in JavaScript are objects, they are sent to 4D as text containing their JSON form like any other object. This principle is implemented in particular when using 4D Mobile or Web Areas. The JSON form of the JavaScript Date object follows the ISO 8601 standard, for example " T00:00:00Z". It is your responsibility to convert this text into a 4D date (C_DATE). Two solutions are available: Using the new JSON Parse command: C_TEXT($1) // reception of a date in ISO format C_DATE($d) $d:=json Parse("\""+$1+"\"";Is date) Using the Date command: C_TEXT($1) // reception of a date in ISO format C_DATE($d) $d:=date($1) 162 4D v14 Upgrade

163 Time Note the difference between these two solutions: JSON Parse respects the conversion mode set using the SET DATABASE PARAMETER (if any), while Date is not subject to this. Conversion using the Date command always takes the local time zone into account. Time Time ( timevalue ) Time Parameter Type Description timevalue String Longint Value to return as a time Function result Time Time specified by timevalue The Time command now accepts a Longint type value as parameter: in this case, timevalue represents the number of seconds elapsed since 00:00:00. You can express any numerical value as a time: vtime:=time (10000) // vtime is 02:46:40 vtime2:=time((60*60)+(20*60)+5200) // vtime2 is 02:46:40 See also: ARRAY TIME Display of null dates In the Method editor, null dates are now displayed with 4-digit years:!00/00/0000! Design Object Access The commands in this theme return additional information that allows you, more particularly, to replace calls to the AP Create method command of 4D Pack (see the Commands removed from 4D Pack paragraph on page 328). 4D v14 Upgrade 163

164 Chapter 6 Language FORM GET NAMES FORM GET NAMES( {atable ;} arrnames {; filter}{; marker}{; *} ) Parameter Type Description atable Table Table reference arrnames Text array Array of form names filter Text Name filter marker Longint Marker for minimum version to return New value * Operator If passed = command applies to host database when executed from a component (parameter ignored outside of this context) The FORM GET NAMES command accepts a new optional marker parameter, which allows you to limit forms returned in arrnames to those that were modified after a given time. As part of a version control system, this parameter lets you update only forms that were modified since the last backup. This principle works as follows: 4D internally maintains a counter of form modifications. Each time a form is created or saved, this counter is incremented and its current value is saved in the internal marker of the created or saved form. If you pass the marker parameter, the command returns, in arrnames, only forms whose internal marker is greater than or equal to the value of the marker. In addition, if you pass a variable in marker, the command returns the new value of the modification counter, i.e., the highest one, in this variable. You can then save this value and use it in the next call of the FORM GET NAMES command to retrieve only new or modified forms. METHOD GET CODE METHOD GET CODE ( path ; code {; *} ) In the JSON metadata added in the header of the generated code, the command now adds a "folder" attribute containing the name of the method s parent folder. For example: // %attributes = {"lang":"en","folder":"web3"} comment added and reserved by 4D. This property is not shown if the method does not have a parent folder D v14 Upgrade

165 METHOD SET ATTRIBUTE METHOD SET ATTRIBUTE METHOD SET ATTRIBUTE ( path ; attribtype ; attribvalue{; attribtype2 ; attribvalue2 ;...; attribtypen ; attribvaluen}{; *} ) Parameter Type Description path Text Path of project method attribtype Longint Type of attribute attribvalue Boolean Text True = select attribute, False = deselect attribute, or Folder name * Operator If passed = command applies to host database when executed from a component (parameter ignored outside of this context) There are two new features concerning the METHOD SET ATTRIBUTE command: The new "folder" attribute, added in 4D v14, is available (see the METHOD SET CODE command). You can set this attribute by passing, in attribtype, the new Attribute folder name (1024) constant found in the "Design Object Access" theme. When you pass this constant, you must pass a folder name in attribvalue: if this name corresponds to a valid folder, the method is placed in this parent folder, if the folder does not exist, the command does not change anything at the parent folder level, if you pass an empty string, the method is placed at the root level. It is now possible to pass several attribtype;attribvalue pairs in a single call. Setting several attribute/value pairs, including the folder attribute: METHOD SET ATTRIBUTE (vpath;attribute invisible;vinvisible; Attribute published Web;v4DAction;Attribute published SOAP;vSoap; Attribute published WSDL;vWSDL;Attribute shared; vexported; Attribute published SQL;vSQL;Attribute executed on server;vremote; Attribute folder name;vfolder;*) 4D v14 Upgrade 165

166 Chapter 6 Language METHOD SET CODE METHOD SET CODE ( path ; code {; *} ) This command supports the new "folder" property of the metadata as follows: When this property is present and corresponds to a valid folder, the method is placed in its parent folder, If this property is not present or if the folder does not exist, the command makes no changes at the parent folder level, When this property contains an empty string, the method is placed at the root level. Drag and Drop SET DRAG ICON SET DRAG ICON ( icon {; horoffset {; vertoffset}} ) Parameter Type Description icon Picture Icon to use during drag horoffset Longint Horizontal offset from left edge of picture with respect to cursor position (>0 = to the left, <0 = to the right) vertoffset Longint Vertical offset from top edge of picture with respect to cursor position (>0 = upwards, <0 = downwards) The new SET DRAG ICON command associates the icon picture with the cursor during drag and drop operations that are managed by programming. This command can only be called in the context of the On Begin Drag Over form event. In the icon parameter, pass the picture to use. Its maximum size is 256x256 pixels. If one of its dimensions exceeds 256 pixels, it is automatically resized. In horoffset and vertoffset, you can pass offset values in pixels: for horoffset, you pass the horizontal offset from the left edge of the icon with respect to the cursor position. Pass a positive value to apply this offset towards the left or a negative value to apply it towards the right D v14 Upgrade

167 SET DRAG ICON for vertoffset, you pass the vertical offset from the top edge of the icon with respect to the cursor position. Pass a positive value to apply this offset upwards or a negative value to apply it downwards. If you omit this parameter, the cursor is placed at the center of the icon. In a form, a user can generate a label by dragging and dropping a row. In the object method of the list box, you can write: If (Form event=on Begin Drag Over) READ PICTURE FILE (Get 4D folder (Current Resources Folder)+"splash.png";vpict) CREATE THUMBNAIL (vpict;vpict;48;48) SET DRAG ICON (vpict) End if When you drag a row, the picture appears as shown here: Note that you can modify the position of the cursor with respect to the picture: SET DRAG ICON (vpict;0;0) 4D v14 Upgrade 167

168 Chapter 6 Language Form Events Form event Two new features concern form events in 4D v14: enterable fields and variables containing text (Text, Date, Time, Number types) now generate the On Clicked and On Double-Clicked events. In previous versions of 4D, only non-enterable fields and variables generated these events. the On Open Detail and On Close Detail events are now generated when a detail form associated with a "selection" type list box is opened or closed. For more information about this, refer to the Form events paragraph on page 69. Forms Current form name Current form name Text Parameter Type Description This command does not require any parameters Function result Text Name of current project form or current table form in the process The new Current form name command returns the name of the current form defined for the process. The current form can be a project form or a table form. By default, if you have not called the FORM LOAD command in the current process, the current form is the one being displayed or printed. If you have called the FORM LOAD command in the process, the current form is the one set by this command and it remains so until you call FORM UNLOAD (or CLOSE PRINTING JOB). If there is no current form defined for the process, the command returns an empty string D v14 Upgrade

169 FORM LOAD In an input form, place the following code in a button: C_TEXT ($FormName) $win:=open form window ([Members];"Input";Plain form window) DIALOG ([Members];"Input") $FormName:=Current form name // $FormName = "Input" FORM LOAD ([Members];"Drag") $FormName:=Current form name // $FormName = "Drag" //... You want to get the current form if it is a project form: $PointerTable:=Current form table If (Nil($PointerTable)) // this is a project form $FormName:=Current form name... // processing End if See also: FORM LOAD FORM LOAD FORM LOAD ( {atable;} form {; *} ) Parameter Type Description atable Table Table form to load (if omitted, load a project form) form String Name of form (project or table) to open * Operator If passed = command applies to host database when it is executed from a component (parameter ignored outside of this context) Compatibility note In previous versions of 4D, this command was named OPEN PRINTING FORM and was found in the "Printing" theme. Its action has been extended in 4D v14. The FORM LOAD command loads the form in memory in order to perform one of the following actions: print data using this form. This action corresponds to the previous functioning of the command. For this action to be performed, a print task must have been opened beforehand using the OPEN PRINTING JOB command. 4D v14 Upgrade 169

170 Chapter 6 Language The OPEN PRINTING JOB command makes an implicit call to the new FORM UNLOAD command, so in this context, it is necessary to execute FORM LOAD. The form becomes the new current printing form. The On Load then On Unload events are executed, as well as the object methods of the form. Note that in 4D v14, it is now possible to apply this command to table forms. Compatibility note In previous versions of 4D, the OPEN PRINTING FORM command accepted an empty string in the form parameter to close the current project form. This syntax is no longer supported and returns an error. In 4D v14, you must use the FORM UNLOAD command or the CLOSE PRINTING JOB command in order to close the form. parse the form contents. This new possibility consists in loading an offscreen form for parsing purposes. To perform this action, just call FORM LOAD outside the context of a print job. In this case, the form events are not executed. FORM LOAD can be used with the FORM GET OBJECTS and OBJECT Get type commands in order to perform any type of processing on the form contents. You must then call the FORM UNLOAD command in order to release the form from memory Note that in all cases, the form on screen remains loaded (it is not affected by the FORM LOAD command) so it is not necessary to reload it after calling FORM UNLOAD. When the command is executed from a component, it loads the component forms by default. If you pass the * parameter, the method loads the host database forms. Calling a project form in a print job: OPEN PRINTING JOB FORM LOAD ("print_form") // execution of events and object methods Calling a table form in a print job: OPEN PRINTING JOB FORM LOAD ([People];"print_form") // execution of events and object methods 170 4D v14 Upgrade

171 FORM UNLOAD Parsing of form contents to carry out processing on text input areas: FORM LOAD ([People];"my_form") // selection of form without execution of events or methods FORM GET OBJECTS (arrobjnames;arrobjptrs;arrpages;*) For ($i;1;size of array (arrobjnames)) If (OBJECT Get type (*;arrobjnames{$i}=object type text input) // processing End if End for FORM UNLOAD See also: FORM UNLOAD, Current form name, LISTBOX GET OBJECTS FORM UNLOAD FORM UNLOAD Parameter Type Description This command does not require any parameters The new FORM UNLOAD command releases from memory the current form designated using the FORM LOAD command. Calling this command is necessary when you use the FORM LOAD command outside of the printing context (in the case of printing, the current form is automatically closed again when the CLOSE PRINTING JOB command is called). See also: FORM LOAD Graphs Commands in this theme no longer support the 4D Chart plug-in. This plug-in is permanently discontinued in 4D v14 (see the Removed functions paragraph on page 17). 4D v14 Upgrade 171

172 Chapter 6 Language GRAPH GRAPH ( graphpicture ; graphnumber ; xlabels {; yelements} {; yelements2 ;... ; yelementsn} ) Parameter Type Description graphpicture Picture var Picture variable... In 4D v14, the GRAPH command only works with a picture variable as its first parameter. The obsolete syntax using a graph area (4D Chart) is no longer supported. GRAPH SETTINGS GRAPH SETTINGS ( graphpicture ; xmin ; xmax ; ymin ; ymax ; xprop ; xgrid ; ygrid ; title {; title2 ;... ; titlen}} ) Parameter Type Description graphpicture Picture var Picture variable... In 4D v14, the GRAPH SETTINGS command only accepts a picture variable as its first parameter. The obsolete syntax using a graph area (4D Chart) is no longer supported. GRAPH TABLE The GRAPH TABLE command is no longer supported in 4D v14 and is renamed _o_graph TABLE in 4D v14. In converted databases, we recommend removing any calls to this command. Hierarchical Lists Note The appearance of hierarchical lists has changed under Windows. For more information, refer to the Hierarchical lists paragraph on page 58. Association with form objects In 4D v14, it is possible to associate hierarchical list references with form object choice lists (sources, required values and excluded values) using the new OBJECT SET LIST BY REFERENCE command or the OBJECT SET LIST BY NAME command (previously named OBJECT SET CHOICE LIST NAME). In previous versions of 4D, only lists created in Design mode could be associated with objects D v14 Upgrade

173 HTTP Client HTTP Client HTTP Get HTTP Get ( url; response {;headernames; headervalues} {;*} ) Longint Parameter Type Description... response Text BLOB Result of request Picture Object... The HTTP Get command is adapted in 4D v14 in order to support: language objects (see the Objects (Language) paragraph on page 256), server certificates. When you pass a C_OBJECT type variable in the response parameter, if the request returns a result with an "application/json" (or "something/json") content-type, 4D attempts to parse the JSON content in order to define the C_OBJECT object. If the command uses a server certificate and this certificate is not valid (expired or revoked), the command returns 0 and the error 901 "Invalid server certificate" is returned. You can intercept this error using an errorhandling method installed by the ON ERR CALL command. HTTP Get certificates folder HTTP Get certificates folder Text Parameter Type Description Function result Text Complete pathname of active certificates folder The new HTTP Get certificates folder command returns the complete pathname of the active client certificates folder. By default, 4D uses the "ClientCertificatesFolder" folder that is created next to the structure file (folder only created if necessary). However, you can create a custom folder for the current process using the new HTTP SET CERTIFICATES FOLDER command. 4D v14 Upgrade 173

174 Chapter 6 Language You want to change certificates folder temporarily: C_TEXT ($certiffolder) $certiffolder:= HTTP Get certificates folder // save current folder HTTP SET CERTIFICATES FOLDER ("C:/temp/tempCertif/")... // execution of specific requests HTTP SET CERTIFICATES FOLDER ($certiffolder) // restore previous folder See also: HTTP SET CERTIFICATES FOLDER HTTP Request HTTP Request ( httpmethod; url; contents; response {;headernames; headervalues} {;*} ) Longint Parameter Type Description... contents Text BLOB Contents of request body Picture Object response Text BLOB Picture Object Result of request... The HTTP Request command is adapted in 4D v14 in order to support: language objects (see the Objects (Language) paragraph on page 256), server certificates (see HTTP SET CERTIFICATES FOLDER). When you pass a C_OBJECT type object in the contents parameter (usually with the PUT and/or POST methods), 4D automatically serializes the object in JSON (in other words, converts it to a string), defines the body of the request and writes "Content-Type: application/json" in its HTTP header. When you pass a C_OBJECT type variable in the response parameter, if the request returns a result with an "application/json" (or "something/json") content-type, 4D attempts to parse the JSON content in order to define the C_OBJECT object. If the command uses a server certificate and this certificate is not valid (expired or revoked), the command returns 0 and the error 901 "Invalid server certificate" is returned. You can intercept this error using an errorhandling method installed by the ON ERR CALL command D v14 Upgrade

175 HTTP SET CERTIFICATES FOLDER Request to add a record in JSON to a remote database: C_OBJECT ($content) OB SET ($content;"lastname";"doe";"firstname";"john") $result:=http Request (HTTP put method;"database.example.com";$content;$response) HTTP SET CERTIFICATES FOLDER HTTP SET CERTIFICATES FOLDER ( certificatesfolder ) Parameter Type Description certificatesfolder Text Pathname and name of client certificates folder The new HTTP SET CERTIFICATES FOLDER command modifies the active client certificates folder for the current process. The client certificates folder is the one where 4D looks for the client certificate files that are required by Web servers. By default, as long as the HTTP SET CERTIFICATES FOLDER command is not executed, 4D uses a folder named "ClientCertificatesFolder" that is created next to the structure file. This folder is only created when necessary. In 4D v14, it is now possible to use several client certificates. In certificatesfolder, you pass the pathname of the custom folder containing the client certificates. You can pass either a pathname relative to the application structure file, or an absolute pathname. The path must be expressed using the system syntax, for example: (OS X) : Disk:Applications:myserv:folder (Windows) C:\Applications\myserv\folder If the folder specified does not exist at the location defined, it is created automatically. Once this command has been executed, the new path is immediately taken into account (you do not have to restart the application). Since the scope of this command is the current process, you can execute as many SOAP or HTTP requests as you want in the process where it is called. If you want to perform several requests on different servers at the same time, you can just create multiple processes. When you want to use the default certificates folder, you can pass an empty string in certificatesfolder. 4D v14 Upgrade 175

176 Chapter 6 Language If the pathname passed in certificatesfolder is not valid, an error is generated. You can intercept this error using an error-handling method installed by the ON ERR CALL command. See also: HTTP Get certificates folder JSON This new theme contains several commands that generate and parse JSON format language objects. More particularly, this format makes it possible to access 4D databases (data and structure) using a Web browser. Support for structured objects is a major new feature of the language in 4D v14, intended to facilitate the exchange of structured data. The commands of the "JSON" theme let 4D work directly with JSON objects. However, the program can also work with "native" objects (whose structure is inspired by JSON), allowing exchanges with all types of language. For more information, refer to the Objects (Language) paragraph on page 256. Introduction to JSON "JSON or JavaScript Object Notation is a generic text-based data format derived from object notation of the ECMAScript language." (source: Wikipedia). JSON is independent from any other language, but uses conventions that are familiar to programmers using C++ or JavaScript, Perl, and so on. It is a format that is particularly suitable for data exchange. This section summarizes the notation principles implemented in JSON. For a complete description of this format, refer the following site: JSON syntax JSON syntax is based on the following principles: data consists of name/value pairs, data is separated by commas, objects are defined by braces {}, arrays are defined by brackets [ ] D v14 Upgrade

177 JSON JSON properties JSON data is expressed in name/value (or key/value) pairs. A name/value pair contains a field name (in quotes), then a colon, followed by a value: "firstname" : "John" For information, this example is equivalent to the following in JavaScript: firstname = "John" Keep in mind that property names are diacritical and case-sensitive. If you write "FirstName" instead of "firstname," this gives you a new name/value pair. JSON data types JSON objects The following types of values are supported in JSON: Type Description Comments string Any Unicode character except for " and \ Values, like property names, are in quotes ("), for example, "city":"paris" \ is used for control characters: \" = quotes \\ = backslash \/ = slash \b = backspace \f = form feed \n = line break \r = carriage return \t = tab \u = four hexadecimal digits number Integer or floating point number object { } array [ ] boolean true or false null null JSON objects are defined by braces and can contain an undefined number of name/value pairs, for example: { "firstname":"john", "lastname":"doe" } Number similar to a C or Java number, except that the octal and hexadecimal formats are not used 4D v14 Upgrade 177

178 Chapter 6 Language JSON arrays JSON arrays are defined by brackets. Each array can contain an undefined number of objects: { "employees": [ { "firstname":"john", "lastname":"doe" }, { "firstname":"anna", "lastname":"smith" }, { "firstname":"peter", "lastname":"jones" } ] } Time zone support By default, when 4D dates are converted to and from JSON, they take into account the time zone of the machine where the conversion took place (in conformity with JavaScript). For example, in France (GMT+2), converting!23/08/2013! gives you " T22:00:00Z" and vice versa. You can change this functioning and no longer take the time zone into account, during the implementation of export procedures for example, using the SET DATABASE PARAMETER, Get database parameter commands. Note For more information about converting 4D/JSON dates, refer to the Conversion of JavaScript dates paragraph on page 162. JSON Parse JSON Parse ( jsonstring {; type} ) Text, Real, Boolean, Pointer, Object Parameter Type Description jsonstring String JSON string to parse type Longint Type in which to convert the values Function result Text Real Boolean Pointer Object Values extracted from JSON string The JSON Parse command parses the contents of a JSON-formatted string and extracts values that you can store in a 4D field or variable. This command deserializes JSON data; it performs the opposite action of the JSON Stringify command. In jsonstring, pass the JSON-formatted string whose contents you want to parse. This string must be formatted correctly, otherwise a parsing error is generated D v14 Upgrade

179 JSON Parse By default, if you omit the type parameter, 4D attempts to convert the value obtained into the type of the variable or field used to store the results (if one is defined). Otherwise, 4D attempts to infer its type. You can also force the type interpretation by passing the type parameter: pass one of the following constants, available in the "Field and Variable Types" theme: Constant (value) Comments Is real (1) Values in the range e+-10 Is text (2) All special characters must be escaped, including quotes (see examples) Is date (4) JSON dates must be in the format: "\"YYYY-MM-DDTHH:mm:ssZ\"" The command considers that the 4D date contains a local time and not GMT. Is boolean (6) true false Is longint (9) Note If you use pointers, you must call the JSON Stringify command before calling JSON Parse. Examples of simple conversions: C_REAL ($r) $r:=json Parse ( "42.17") // $r = 42,17 (Real) C_LONGINT ($el) $el:=json Parse ("120.13";Is longint) // $el=120 C_TEXT ($t) $t:=json Parse ( "\"Year 42\"";Is text) // $t="year 42" (text) C_OBJECT ($o) $o:=json Parse ( "{\"name\":\"john\"}") // $o = {"name":"john"} (4D object) C_BOOLEAN ($b) $b:=json Parse ("{\"manager\":true}";is boolean) // $b=true 4D v14 Upgrade 179

180 Chapter 6 Language Example of converting date type data: $test:=json Parse ("\" T12:00:00Z\"") // $test= t12:00:00z C_DATE ($date) $date:=json Parse ("\" T12:00:00Z\"";Is date) // $date=01/01/08 This example shows the combined use of the JSON Stringify and JSON Parse commands: C_TEXT ($MyContact) C_OBJECT($Contact) // JSON Stringify: conversion of JSON object into a JSON string $MyContact:=JSON Stringify("{\"name\":\"Monroe\",\"firstname\":\"Alan\"}") // $MyContact = "{\\"name\\":\\"monroe\\",\\"firstname\\":\\"alan\\"}" // JSON Parse: conversion of JSON string into a JSON object $Contact:=JSON Parse("{\"name\":\"Monroe\",\"firstname\":\"Alan\"}") // $Contact = {"name":"monroe","firstname":"alan"} See also: JSON Stringify, JSON PARSE ARRAY JSON PARSE ARRAY JSON PARSE ARRAY ( jsonstring ; objarray ) Parameter Type Description jsonstring String JSON string to parse objarray Object array Array containing result from parsing of JSON string The JSON PARSE ARRAY command parses the contents of a JSONformatted string and puts the data extracted into the objarray array. This command deserializes the JSON data; it performs the opposite action of the JSON Stringify array command. In jsonstring, pass the JSON-formatted string whose contents you want to parse. This string must be formatted correctly, otherwise a parsing error is generated. In objarray, pass the object to receive the parsing results D v14 Upgrade

181 JSON Stringify In this example, data from fields of the records in a table are extracted and then placed in object arrays: C_OBJECT ($ref) ARRAY OBJECT ($sel;0) ARRAY OBJECT ($sel2;0) C_TEXT (v_string) OB SET ($ref;"name";->[company]company Name) OB SET ($ref;"city";->[company]city) While (Not (End selection ([Company]))) $ref_company:=ob Copy ($ref;true) APPEND TO ARRAY ($sel;$ref_company) // $sel{1}={"name":"4d SAS","city":"Clichy"} // $sel{2}={"name":"mycomp","city":"lyon"} //... NEXT RECORD ([Company]) End while v_string:=json Stringify array ($sel) // v_string= [{"name":"4d SAS","city":"Clichy"},{"name":"MyComp", // "city":"lyon"}...] JSON PARSE ARRAY (v_string;$sel2) // $sel2{1}={"name":"4d SAS","city":"Clichy"} // $sel2{2}={"name":"mycomp","city":"lyon"} //... See also: JSON Stringify JSON Stringify JSON Stringify ( value {; *} ) Text Parameter Type Description value Object Object Data to convert into JSON string array String Num Date Time * Operator Pretty formatting Function result Text String containing serialized JSON text The JSON Stringify command converts the value parameter into a JSON string. This command serializes data into JSON; it performs the opposite action of the JSON Parse command. 4D v14 Upgrade 181

182 Chapter 6 Language Pass the data to be serialized in value. It can be expressed in scalar form (string, number, date or time) or by means of a 4D object (or an object array). In the case of an object, you can include all types of values (see the JSON data types paragraph on page 177). JSON formatting must respect the following rules: String values must be enclosed in quotes. All Unicode character can be used except for special characters that must be preceded by a backslash. Numbers (interval of e+-10) Booleans ("true" or "false" strings) Pointers to a field, variable or array (the pointer is evaluated when it is stringified) Dates (Text type) Times (Real type) You can pass the optional * parameter to include formatting characters in the resulting string. This improves the presentation of JSON data (known as pretty formatting). Conversion of scalar values: $vc:=json Stringify ("Eureka!") // "Eureka!" $vel:=json Stringify (120) // "120" $vd:=json Stringify (!28/08/2013!) // " T22:00:00Z" $vh:=json Stringify (?20:00:00?) // " " seconds since midnight Conversion of a string containing special characters: $s:=json Stringify ("{\"name\":\"john\"}") // $s="{\\"name\\":\\"john\\"}" $p:=json Parse($s) // $p={"name":"john"} 182 4D v14 Upgrade

183 JSON Stringify Example using a pointer to a variable: C_OBJECT ($MyTestVar) C_TEXT ($name ; $jsonstring ) OB SET ($MyTestVar; "name" ; ->$name) // object definition // $MyTestVar = {"name":"->$name"} $jsonstring := JSON Stringify ($MyTestVar) // $jsonstring ="{"name":""}" //... $name:="smith" $jsonstring := JSON Stringify ($MyTestVar) // $jsonstring = "{"name" : "Smith"}" Serialization of a 4D object: C_TEXT ($varjsontextserialized) C_OBJECT ($Contact) OB SET ($Contact;"firstname";"Alan") OB SET ($Contact;"lastname";"Monroe") OB SET ($Contact;"age";40) OB SET ($Contact;"phone";"[ , ]") $varjsontextserialized:=json Stringify ($Contact) // $varjsontextserialized = "{"lastname":"monroe","phone":"[ , // ]","age":40,"firstname":"Alan"}" Examples of serializing a 4D object with and without the * parameter: C_TEXT ($MyContact) C_TEXT ($MyPContact) C_OBJECT ($Contact;$Children) OB SET ($Contact;"lastname";"Monroe";"firstname";"Alan") OB SET ($Children;"firstname";"Jim";"age";"12") OB SET ($Contact;"children";$Children) $MyContact:=JSON Stringify ($Contact) $MyPContact:=JSON Stringify ($Contact;*) //$MyContact = {"lastname":"monroe","firstname":"alan","children":{"firstname":"john","age":"12"}} //$MyPContact = {\n\t"lastname": "Monroe",\n\t"firstname": "Alan",\n\t"children": {\n\t\t"firstname": "John",\n\t\t"age": "12"\n\t}\n} 4D v14 Upgrade 183

184 Chapter 6 Language Standard formatting The advantage of this formatting is clear when the JSON is shown in a Web area: Pretty formatting See also: JSON Stringify array JSON Stringify array JSON Stringify array ( array {; *} ) Text Parameter Type Description array Text array, Real array, Boolean Array whose contents must be serialized array, Pointer array, Object array * Operator Pretty formatting Function result Text String containing the serialized JSON array The JSON Stringify array command converts the 4D array array into a serialized JSON array. This command performs the opposite action of the JSON PARSE ARRAY command. In array, pass a 4D array containing the data to be serialized. This array may be of the text, real, Boolean, pointer or object type. You can pass the optional * parameter to use pretty formatting in the resulting string. This improves the presentation of JSON data by including formatting characters when it is displayed in a Web page D v14 Upgrade

185 JSON Stringify array Conversion of a text array: C_TEXT ($jsonstring) ARRAY TEXT ($ArrayFirstname;2) $ArrayFirstname{1}:="John" $ArrayFirstname{2}:="Jim" $jsonstring := JSON Stringify array ($ArrayFirstname) // $jsonstring = "["John","Jim"]" Conversion of a text array containing numbers: ARRAY TEXT ($phonenumbers;0) APPEND TO ARRAY ($phonenumbers ; " ") APPEND TO ARRAY ($phonenumbers ; " ") $string := JSON Stringify array ($phonenumbers) // $string = "[" "," "]" Conversion of an object array: C_OBJECT ($ref_john) C_OBJECT ($ref_jim) ARRAY OBJECT ($myarray;0) OB SET ($ref_john; "name" ; "John";"age";35) OB SET ($ref_jim; "name" ; "Jim";"age";40) APPEND TO ARRAY ($myarray ; $ref_john) APPEND TO ARRAY ($myarray ; $ref_jim) $JsonString := JSON Stringify array ($myarray) // $JsonString = "[{"name":"john","age":35},{"name":"jim","age":40}]" // If you want to view the result in a Web page, // pass the optional * parameter: $JsonStringPretty := JSON Stringify array ($myarray;*) 4D v14 Upgrade 185

186 Chapter 6 Language Conversion of a 4D selection in an object array: C_OBJECT ($jsonobject) C_TEXT ($jsonstring) QUERY ([Company];[Company]Company Name="a@") OB SET ($jsonobject;"company name";->[company]company Name) OB SET ($jsonobject;"city";->[company]city) OB SET ($jsonobject;"date";[company]date_input) OB SET ($jsonobject;"time";[company]time_input) ARRAY OBJECT ($arraysel;0) While (Not (End selection ([Company]))) $ref_value:=ob Copy ($jsonobject;true) // If you do not copy them, the values will be empty strings APPEND TO ARRAY ($arraysel;$ref_value) // Each element contains the selected values, for example: // $arraysel{1} = // {"company name":"apple","time": ,"city": // "Paris","date":" T00:00:00Z"} NEXT RECORD ([Company]) End while $jsonstring:=json Stringify array ($arraysel) // $jsonstring = "[{"company name":"apple","time": ,"city": // "Paris","date":" T00:00:00Z"},{"company name": // "ALMANZA",...}]" See also: JSON Stringify JSON TO SELECTION JSON TO SELECTION ( atable; jsonobject ) Parameter Type Description atable Pointer Pointer to 4D table jsonobject Text String in JSON The JSON TO SELECTION command copies the contents of a JSON object to the selection of records of atable. If a selection exists for atable at the time of the call, the elements of the JSON object are copied into the records based on the order of the object and the order of the records. If the number of elements defined in the JSON object is greater than the number of records in the current selection, new records are created. The records, whether they are new or existing, are automatically saved D v14 Upgrade

187 JSON TO SELECTION Warning: Since JSON TO SELECTION replaces any information found in the existing records, this command must be used with caution. If a record is locked by another process during the execution of the command, it is not modified. All the locked records are placed in the LockedSet system set. After the execution of JSON TO SELECTION, you can test whether the LockedSet set contains any records that were locked. Using the JSON TO SELECTION command to add records to the [Company] table: C_OBJECT ($Object1;$Object2;$Object3;$Object4) C_TEXT ($ObjectString) ARRAY OBJECT ($arrayobject;0) OB SET ($Object1;"ID";"200";"Company Name";"4D SAS";"City";"Clichy") APPEND TO ARRAY ($arrayobject;$object1) OB SET ($Object2;"ID";"201";"Company Name";"APPLE";"City";"Paris") APPEND TO ARRAY ($arrayobject;$object2) OB SET ($Object3;"ID";"202";"Company Name";"IBM";"City";"London") APPEND TO ARRAY ($arrayobject;$object3) OB SET ($Object4;"ID";"203";"Company Name";"MI- CROSOFT";"City";"New York") APPEND TO ARRAY ($arrayobject;$object4) $ObjectString:=JSON Stringify array ($arrayobject) // $ObjectString = "[{"ID":"200","City":"Clichy","Company Name":"4D // SAS"},{"ID":"201","City":"Paris","Company Name":"APPLE"},{"ID":"202", // "City":"London","Company Name":"IBM"},{"ID":"203","City":"New // York","Company Name":"MICROSOFT"}]" JSON TO SELECTION ([Company];$ObjectString) // You create 4 records in the [Company] table, filling the ID, // Company name and city fields See also: Selection to JSON 4D v14 Upgrade 187

188 Chapter 6 Language Selection to JSON Selection to JSON ( atable {; afield1 {; afield2;...}} {; template} ) Text Parameter Type Description atable Table Table pointer afield1... afieldn Field Field(s) whose contents must be serialized template Object Object for selection of labels and fields Function result Text String containing serialized JSON array The Selection to JSON command returns a JSON string containing the values of the fields for the current selection of atable. If you only pass the atable parameter, the command includes, in the JSON string, the values of all the fields of the table that can be expressed in JSON. BLOB and Picture type fields are ignored. If you do not want to include all the fields of atable, you can use either the afield1...afieldn parameter or the template parameter: afield1...afieldn: pass one or more fields in this parameter. Only the values of the fields defined are included in the JSON string. template: pass a 4D object containing one or more name/value pairs where the value contains a pointer to a field you want to include (see example 3). You want to create a JSON string representing this selection: 188 4D v14 Upgrade

189 Selection to JSON 1) You want to include the values of all the fields of the [Members] table: $jsonstring := Selection to JSON ([Members]) // $jsonstring = [{"LastName":"Durant","FirstName":"Mark","Address": // "25 Park St","Zip code":"15205","city":"pittsburgh"},{"lastname": // "Smith","FirstName":"John","Address":"24 Philadelphia Ave", // "Zip code":"75203","city":"dallas"},{"lastname":"anderson", // "FirstName":"Adeline","Address":"37 Market St","Zip code": // "45205","City":"Cincinnati"},...] 2) You want to reduce the selection and only include two fields in the JSON string by using the syntax based on fields: QUERY ([Members];[Members]LastName="A@") $jsonstring := Selection to JSON ([Members];[Members]LastName; [Members]City) // $jsonstring = [{"LastName":"Anderson","City":"Cincinnati"}, // {"LastName":"Albert","City":"Houston"}] 3) You only want to include one field in the JSON string by using the template syntax: C_OBJECT ($template) OB SET ($template;"lastname";->[members]lastname) // a single field ALL RECORDS ([Members]) $jsonstring := Selection to JSON ([Members];$template) // $jsonstring = [{"LastName":"Durant"},{"LastName":"Smith"}, {"LastName":"Anderson"},{"LastName":"Albert"}, {"LastName":"Leonard"},{"LastName":"Pradel"}] See also: JSON TO SELECTION 4D v14 Upgrade 189

190 Chapter 6 Language List Box LISTBOX DUPLICATE COLUMN LISTBOX DUPLICATE COLUMN ( {*; } object ; colposition ; colname ; col- Variable ; headername ; headervar {; footername ; footervar} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) of the column to be duplicated positioncol Longint Location of new duplicated column colname String Name of new column colvariable Array, Field, Variable Name of the column array variable or field or variable headername String Column header object name headervar Integer Column header variable variable footername String Column footer object name footervar Integer variable Column footer variable The new LISTBOX DUPLICATE COLUMN command duplicates the column designated by the object and * parameters by programming in the context of the form being executed (Application mode). The original form, generated in the Design mode, is not modified. Note This functionality was already found in 4D, in Design mode only, using the Duplicate Column command found in the context menu of the Form editor. By default, all style options (size, color, formats, etc.) set for the source column by means of the Property list or using object management commands (OBJECT SET COLOR, etc.) are applied to the copy. The object method and the settings of the form events are also duplicated. However, the data source (array or selection, depending on the source type set for the list box) as well as the style and color arrays are not duplicated. It is your responsibility to define them for each new column after duplication D v14 Upgrade

191 LISTBOX DUPLICATE COLUMN The object and * parameters designate the column to duplicate. Passing the optional * parameter indicates that the object parameter is an column name (string). If you do not pass this parameter, it indicates that the object parameter is a column variable. In this case, you pass a variable reference instead of a string. Note This command does nothing when it is applied to the first column of a list box displayed in hierarchical mode. The new duplicated column is placed just before the column designated by the colposition parameter. If the colposition parameter is greater than the total number of columns, then the duplicated column is placed after the last column. In the colname and colvariable parameters, pass the object name and the variable of the new duplicated column. For array type list boxes, the variable name corresponds to the name of the array whose contents will be displayed in the column. For selection type list boxes, you can pass a field or variable in the colvariable parameter. So the contents of the column will be the value of this field or variable, evaluated for each record of the selection associated with the list box. This type of content can only be used when the "Data Source" property of the list box is set to Current Selection or Named Selection. Remember that the data source of the original column is not duplicated: you must set a source variable, array or field for the new duplicated column. In the headername and headervariable parameters, pass the object name and variable for the header of the new duplicated column. You can also pass the object name and variable for the footer of the inserted column in the footername and footervariable parameters. If you omit the footervariable parameter, 4D uses a dynamic variable. Note Object names must be unique in a form. You must make sure that the names passed in the colname, headername and footername parameters have not already been used. Otherwise, the column is not duplicated and an error is generated. 4D v14 Upgrade 191

192 Chapter 6 Language This command must be used in the context of displaying a form. It is usually called in the On Load form event or following a user action (On Clicked event). In an array type list box, we want to duplicate the "First Name" column, ready for input: Here is the code of the button: ARRAY TEXT (arrfirstnames2;records in table([members])) LISTBOX DUPLICATE COLUMN (*;"column2";3;"col2bis";arrfirstnames2; "FirstNameA";vHead2A) OBJECT SET TITLE (*;"FirstNameA";"Middle Name") EDIT ITEM (*;"col2a";0) When you click on the button, the list box appears as follows: See also: LISTBOX MOVE COLUMN 192 4D v14 Upgrade

193 LISTBOX Get array LISTBOX Get array LISTBOX Get array ( {*; } arrtype ) Pointer Parameter Type Description * If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) arrtype Longint Type of array Function result Pointer Pointer to array associated with property Note This command only works with array type list boxes. The new LISTBOX Get array command returns a pointer to the array associated with the style or color of the list box or list box column designated by the object and * parameters. Style, color, or background color arrays can be associated with array type list boxes using the Property list in Design mode or using the new LISTBOX SET ARRAY command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter. In arrtype, pass the type of array for the property you want to get. You can use one of the following constants, available in the "List box" theme: Constant Type Value Listbox font color array Longint 0 Listbox background color array Longint 1 Listbox style array Longint 2 The command returns one of the following values: Nil if no array for the requested property is associated with the column or the list box. a pointer to the array of the requested property, defined by the user. 4D v14 Upgrade 193

194 Chapter 6 Language a pointer to the array of the requested property, defined dynamically when calling the LISTBOX SET ROW COLOR or LISTBOX SET ROW FONT STYLE command. Typical examples of use: vptr:=listbox Get array (*;"MyLB";Listbox font color array) // returns a pointer to the font color array associated with the // "MyLB" list box vptr:=listbox Get array (*;"Col4";Listbox style array) // returns a pointer to the font style array associated with the // columns of the "Col4" list box See also: LISTBOX SET ARRAY LISTBOX GET OBJECTS LISTBOX GET OBJECTS ( {*; }object ; arrobjectnames ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) arrobjectnames Text array Names of sub-objects comprising list box (headers, columns, footers) The new LISTBOX GET OBJECTS command returns an array containing the names of each object making up the list box designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string D v14 Upgrade

195 LISTBOX GET OBJECTS In arrobjectnames you pass a text array that is automatically filled in by the command. Object names are returned in their display order, with the following sequence: namecol1 headernamecol1 footernamecol1 namecol2 headernamecol2 footernamecol2... The array returns the object names for all the columns (including column footers), regardless of whether or not they are visible. This command is useful in the context of the parsing of a form using the FORM GET OBJECTS and OBJECT Get type commands. You can use it, when needed, to obtain the names of list box sub-objects. You want to load a form and get a list of all the objects of list boxes that it contains. FORM LOAD ("MyForm") ARRAY TEXT (arrobjects;0) FORM GET OBJECTS (arrobjects) ARRAY LONGINT (ar_type;size of array (arrobjects)) ARRAY TEXT (ar_typename;size of array (arrobjects)) For ($i;1;size of array (arrobjects)) ar_type{$i}:=object Get type (*;arrobjects{$i}) If (ar_type{$i}=object type listbox) ARRAY TEXT (arrlbobjects;0) LISTBOX GET OBJECTS (*;arrobjects{$i};arrlbobjects) End if End for FORM UNLOAD See also: FORM LOAD 4D v14 Upgrade 195

196 Chapter 6 Language LISTBOX Get row color LISTBOX Get row color ( {*; } object ; row {; colortype ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) row Longint Row number colortype Longint Listbox font color (default) or Listbox background color Function result Longint Color value Note This command only works with array type list boxes. The new LISTBOX Get row color command returns the color of a row or a cell in the list box designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter: When object designates a list box, the command returns the color of the row. When object designates a list box column, the command returns the color of the cell. In row, pass the number of the row whose color you want to get. Note The command does not take any hidden/shown states of the list box rows into account. In the colortype parameter, you can pass either the Listbox background color or Listbox font color constant in order to find out the background or font color for the row. If you omit this parameter, the font color is returned. Warning: As described in the Priority of styles and colors paragraph on page 63, a color assigned to a row is not necessarily displayed in every cell of the row (see example) D v14 Upgrade

197 LISTBOX Get row font style If we return to the example of the list box for the LISTBOX SET ROW COLOR command: vcolor:= LISTBOX Get row color (*;"Col5";3) vcolor2:= LISTBOX Get row color (*;"List Box";3) vcolor3:= LISTBOX Get row color (*;"List Box";Listbox background color) // vcolor contains 0xFFFF00 (yellow) // vcolor2 contains 0x00FF (blue) // vcolor3 contains 0x00FF0000 (red) See also: LISTBOX SET ROW COLOR LISTBOX Get row font style LISTBOX Get row font style ( {*; } object ; row ) Longint Parameter Type Description * If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) row Longint Row number Function result Longint Style value Note This command only works with array type list boxes. The new LISTBOX Get row font style command returns the font style of a row or a cell in the list box designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter: When object designates a list box, the command returns the style of the row. When object designates a list box column, the command returns the style of the cell. 4D v14 Upgrade 197

198 Chapter 6 Language In row, pass the number of the row whose style you want to get. Note The command does not take any hidden/shown states of the list box rows into account. Warning: As described in the Priority of styles and colors paragraph on page 63, a style assigned to a row is not necessarily displayed in every cell of the row (see example). If we return to the example of the list box for the LISTBOX SET ROW FONT STYLE command: vstyle:= LISTBOX Get row font style (*;"Col5";3) vstyle2:= LISTBOX Get row font style (*;"List Box";3) // vstyle contains 1 (Bold) // vstyle2 contains 6 (Italic + Underline) See also: LISTBOX SET ROW FONT STYLE LISTBOX MOVE COLUMN LISTBOX MOVE COLUMN ( {*; } object ; colposition ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) of the column to be moved colposition Longint New location of column The new LISTBOX MOVE COLUMN command moves the column designated by the object and * parameters by programming in the context of the form being executed (Application mode). The original form, generated in the Design mode, is not modified. Note This functionality was already found in 4D in Application mode: the user can move non-static columns using the mouse D v14 Upgrade

199 LISTBOX SET ARRAY The object and * parameters designate the column to move. Passing the optional * parameter indicates that the object parameter is a column name (string). If you do not pass this parameter, this indicates that the object parameter is a column variable. In this case, you pass a variable reference instead of a string. The column is moved to just in front of the one designated by the colposition parameter. If the colposition parameter is greater than the total number of columns, then the column is moved to just after the last column. Note This command does nothing when it is applied to the first column of a list box displayed in hierarchical mode. The command takes the static and locked column properties into account: for example, if you try to move a static column, the command does nothing. However, unlike columns moved by the user, this command does not generate the On Column Moved event. You want to swap the 2nd and 3rd columns of the list box: LISTBOX MOVE COLUMN (*;"column2";3) See also: LISTBOX DUPLICATE COLUMN LISTBOX SET ARRAY LISTBOX SET ARRAY ( {*; } object ; arrtype ; arrptr ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) arrtype Longint Type of array arrptr Pointer Array to associate with property Note This command only works with array type list boxes. This new command associates a style or color array with the list box or list box column designated by the object and * parameters. In previous versions of 4D, arrays of styles, colors or background colors could be associated with array type list boxes using the Property list in Design mode only. 4D v14 Upgrade 199

200 Chapter 6 Language Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter. In arrtype, pass the type of array to associate with the list box or column. You can use one of the following constants, available in the "List box" theme: Constant Type Value Listbox font color array Longint 0 Listbox background color array Longint 1 Listbox style array Longint 2 In the arrptr parameter, you pass a pointer to the array to use to support the property type (font color, background color or font style). You want to reuse the font color array of the 4th column for the 10th column: // retrieve a pointer to the array for column 4 $Pointer:=LISTBOX Get array (*;"Col4";Listbox font color array) // check that it exists If (Not (Nil ($Pointer))) // transfer to column 10 LISTBOX SET ARRAY (*;"Col10";Listbox font color array;$pointer) End if See also: LISTBOX Get array 200 4D v14 Upgrade

201 LISTBOX SET ROW COLOR LISTBOX SET ROW COLOR LISTBOX SET ROW COLOR ( {*; } object ; row ; color {; colortype} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) row Longint Row number color Longint RGB color value colortype Longint Listbox font color (default) or Listbox background color Note This command only works with array type list boxes. This new command sets the color for a row or a cell in the array list box designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter: When object designates a list box, the command applies to the row. When object designates a list box column, the command applies to the cell located at the column/row intersection. In row, pass the number of the row where you want to apply the new color. Note The command does not take any hidden/shown states of the list box rows into account. In color, pass an RGB color value. For more information about RGB colors, refer to the description of the OBJECT SET RGB COLORS command. If you want the row to inherit the color set for the higher level, you can pass the Listbox inherited constant in color. For more information about this point, refer to the Inheriting styles and colors paragraph on page 65. 4D v14 Upgrade 201

202 Chapter 6 Language In the colortype parameter, pass the Listbox background color or Listbox font color constants to indicate whether you want to apply the color as the background or the font color of the row. If you omit this parameter, the color is applied as the font color. This command modifies values found in the array of colors that may have been defined for the column or list box. If these arrays are not already defined, the command dynamically creates arrays that you can access using the new LISTBOX Get array command. If conflicting color values are set using properties for list boxes or list box columns, an order of priority is applied. For more information, refer to the Inheriting styles and colors paragraph on page 65. In an array type list box, we want to set colors for a row and for one cell in this row: // Definition of font color for cell (yellow) LISTBOX SET ROW COLOR (*;"Col5";3;0x00FFFF00) // Definition of background and font color for row 3 // red background, blue font LISTBOX SET ROW COLOR (*;"ListBox";3;0x00FF0000; Listbox background color) LISTBOX SET ROW COLOR (*;"List Box";3;0x000000FF) See also: LISTBOX Get row color 202 4D v14 Upgrade

203 LISTBOX SET ROW FONT STYLE LISTBOX SET ROW FONT STYLE LISTBOX SET ROW FONT STYLE ( {*; } object ; row ; style ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) row Longint Row number style Longint Font style Note This command only works with array type list boxes. This new command sets a font style for a row or a cell in the array type list box designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a is a variable. In this case, you pass a variable reference instead of a string. You can designate a list box or a list box column in the object parameter: When object designates a list box, the command applies to the row. When object designates a list box column, the command applies to the cell located at the column/row intersection. In row, pass the number of the row where you want to apply the new style. Note The command does not take any hidden/shown states of the list box rows into account. In style, you pass a style value. You must use one (or a combination) of the constants found in the "Font Style" theme: Constant Type Value Bold Longint 1 Italic Longint 2 Plain Longint 0 Underline Longint 4 If an array of font styles has been associated with the list box or column, only the element matching the row is modified. In other words, executing the command has the same effect, in this case, as modifying an element of the font style array. 4D v14 Upgrade 203

204 Chapter 6 Language If there is no font style array associated with the list box or column, one will be created dynamically when this command is called. You can access them using the new LISTBOX Get array command. If conflicting style properties are set for the column or the list box, an order of priority is applied. For more information, refer to the Priority of styles and colors paragraph on page 63. Note Since style arrays for columns take priority over the ones for list boxes, when this command is applied to a list box, it will only have an effect if no style array has been assigned to the columns. Given an array type list box with the following characteristics: a font style array associated with the list box (ArrGlobalStyle) a font style array associated with column 5 (ArrCol5Style) the other columns do not have any style arrays. LISTBOX SET ROW FONT STYLE (*;"Col5";3;Bold) // equivalent to ArrCol5Style{3}:=Bold 3rd row of 5th column LISTBOX SET ROW FONT STYLE (*;"List Box";3;Italic+Underline) // equivalent toarrglobalstyle{3}:=italic+underline After the second statement, all the cells of the third row change to underlined italic, except for the one in the 5th column which stays in bold only (column style arrays take priority over list box arrays). See also: LISTBOX Get row font style 204 4D v14 Upgrade

205 Messages Messages DISPLAY NOTIFICATION DISPLAY NOTIFICATION ( title ; text {; duration} ) In 4D v14, the DISPLAY NOTIFICATION command can now be used under OS X (version 10.8): it displays a small sliding window in the top right corner of the screen. Note that, in accordance with Apple specifications, a notification is only displayed when the application is not in the foreground. However, the message will still appear in the list of the "notification center". Under OS X, you can now write: DISPLAY NOTIFICATION ("4D Export";"The data is ready to export.") Object Properties Objects (Forms) This theme is renamed "Objects (Forms)" in 4D v14. For more information about the modifications made to the commands and functions of this theme, refer to the Objects (Forms) paragraph on page 205. Compatibility note The "Objects (Forms)" theme was named "Object Properties" in previous versions of 4D. Furthermore, for greater precision, the "Form objects" constant theme is renamed "Form Objects (Properties)". 4D v14 Upgrade 205

206 Chapter 6 Language New commands GET STYLE SHEET INFO GET STYLE SHEET INFO ( stylesheetname ; font ; size ; styles ) Parameter Type Description stylesheetname Text Name of style sheet font Text Character font size Longint Font size styles Longint Style value The GET STYLE SHEET INFO command returns the current configuration of the style sheet designated in the stylesheetname parameter. In stylesheetname, you pass the name of the style sheet as defined in the Design mode. To designate "Automatic" style sheets, you can use the Automatic style sheet constant, available in the "Font Styles" theme: Constant Type Value Automatic style sheet Text " automatic " In font, the command returns the name of the font associated with the style sheet for the current platform. In size, the command returns the size in points of the font associated with the style sheet for the current platform. In styles, the command returns a value corresponding to the style(s) associated with the style sheet for the current platform. You can compare the value received with the following constants, found in the "Font Styles" theme: Constant Type Value Bold Longint 1 Bold and Italic Longint 3 Bold and Underline Longint 5 Italic Longint 2 Italic and Underline Longint 6 Plain Longint 0 Underline Longint 4 If the command is executed correctly, the OK system variable is set to 1. Otherwise (for example, if the stylesheetname does not exist), it is set to D v14 Upgrade

207 LIST OF STYLE SHEETS You want to find out the current configuration of the "Automatic" style sheet: C_LONGINT ($size;$style) C_TEXT ($font) GET STYLE SHEET INFO (Automatic style sheet;$font;$size;$style) See also: LIST OF STYLE SHEETS, OBJECT SET STYLE SHEET LIST OF STYLE SHEETS LIST OF STYLE SHEETS ( arrstylesheets ) Parameter Type Description arrstylesheets Text array Names of style sheets defined in the application The new LIST OF STYLE SHEETS command returns the list of application style sheets in the arrstylesheets array. If it was not already defined previously, the arrstylesheets text array is created by the command. It is automatically sized according to the number of style sheets defined. After executing the command, each element of the array contains the name of a style sheet. These names are sorted alphabetically, as in the style sheet editor. The first array element always contains " automatic ", which represents the "Automatic" style sheet. In your application, the following style sheets are defined: 4D v14 Upgrade 207

208 Chapter 6 Language If you execute the following code: LIST OF STYLE SHEETS ($arrstyles) // $arrstyles{1} contains " automatic " // $arrstyles{2} contains "Buttons" // $arrstyles{3} contains "Input_fields" // $arrstyles{4} contains "Default" // $arrstyles{5} contains "Labels" // $arrstyles{6} contains "Variables" See also: GET STYLE SHEET INFO OBJECT Get action OBJECT Get action ( {* ;} object ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Text Associated standard action The new OBJECT Get action command returns the code of the standard action associated with the object(s) designated by the object and * parameters. You can set a standard action for an object in the Design mode using the Property List, or using the new OBJECT SET ACTION command. The command returns a string containing the code for the standard action associated with the object. You can compare the value received with the constants of the "Text Values for Associated Standard Action" theme: Constant Type Value Object Refresh current URL action Text "39" Object Show Clipboard action Text "23" Object Add subrecord action Text "14" Object Goto page action Text "15" Object Cancel action Text "1" Object Undo action Text "17" Object Stop loading URL action Text "40" Object Paste action Text "20" Object Copy action Text "19" 208 4D v14 Upgrade

209 OBJECT Get action Constant Type Value Object Cut action Text "18" Object MSC action Text "36" Object Last record action Text "6" Object Last page action Text "11" Object Clear action Text "21" Object Previous record action Text "4" Object Next record action Text "3" Object Edit subrecord action Text "12" Object Open back URL action Text "37" Object Open next URL action Text "38" Object Previous page action Text "9" Object Next page action Text "8" Object First record action Text "5" Object First page action Text "10" Object Database Settings action Text "32" Object Quit action Text "27" Object Redo action Text "31" Object Return to Design mode action Text "35" Object Automatic splitter action Text "16" Object Delete record action Text "7" Object Delete subrecord action Text "13" Object Test Application action Text "26" Object Select all action Text "22" Object Accept action Text "2" Object No standard action Text "0" You want to associate the "Cancel" action with all the objects in the form that do not already have any associated action: ARRAY TEXT ($arrobjects;0) FORM GET OBJECTS ($arrobjects) For ($i;1;size of array ($arrobjects)) If (Object Get action (*;$arrobjects{$i})=object No standard action) OBJECT SET ACTION (*;$arrobjects{$i};object Cancel action) End if End for See also: OBJECT SET ACTION 4D v14 Upgrade 209

210 Chapter 6 Language OBJECT Get border style OBJECT Get border style ( {* ;} object ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Longint Border line style The new OBJECT Get border style command returns the border line style of the object(s) designated by the object and * parameters. You can set the border line style for an object in Design mode using the Property List, or using the new OBJECT SET BORDER STYLE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). The command returns a value corresponding to the border line style. You can compare the value received with the following constants, found in the "Form objects (Properties)" theme: Constant (value) Border None (0) Border Double (5) Border Plain (1) Border Raised (3) Border Sunken (4) Border System (6) Border Dotted (2) See also: OBJECT SET BORDER STYLE Comments Objects appear with no border. Objects appear framed with a double line, i.e., two continuous 1-pt. lines separated by a pixel. Objects appear framed with a continuous 1-pt. border line. Objects appear framed with a 3D effect (raised). Objects appear framed with a sunken 3D effect. The border line is drawn based on the graphic specifications of the system. Objects appear framed with a dotted 1-pt. border line D v14 Upgrade

211 OBJECT Get context menu OBJECT Get context menu OBJECT Get context menu ( {* ;} object ) Boolean Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Boolean True = context menu enabled, False = context menu disabled The new OBJECT Get context menu command returns the current state of the "Context Menu" option for the object(s) designated by the object and * parameters. You can set the "Context Menu" option in Design mode using the Property List, or using the new OBJECT SET CONTEXT MENU command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, this indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). The command returns True if the context menu is enabled for the object and False otherwise. See also: OBJECT SET CONTEXT MENU OBJECT Get data source OBJECT Get data source ( {* ;} object ) Pointer Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Pointer Pointer to current data source of object The new OBJECT Get data source command returns the current data source of the object(s) designated by the object and * parameters. 4D v14 Upgrade 211

212 Chapter 6 Language You can define the data source for an object in Design mode using the Property List, or using the new OBJECT SET DATA SOURCE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). Given a combo box object defined in a form: You execute the following code: $vptr := OBJECT Get data source (*;"vcombo") // vptr contains -> vcombo See also: OBJECT SET DATA SOURCE OBJECT GET EVENTS OBJECT GET EVENTS ( {*; } object ; arrevents ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name or "" to designate the form (if * is specified) or Field or variable (if * is omitted), arrevents Longint array Array of enabled events The new OBJECT GET EVENTS command gets the current configuration of the form events for the object(s) designated by the object and * parameters D v14 Upgrade

213 OBJECT GET EVENTS Form events can be enabled/disabled either using the Property List, or using the OBJECT SET EVENTS command if it is called in the current process. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). To get the configuration of events for the form itself, pass the optional * parameter and an empty string "" in object: in this case, you designate the current form. Note If you want to get events for a subform related to a table, you can only use the syntax based on the object name. Pass a longint array in the arrevents parameter. When the command is executed, this array is automatically sized and receives all the predefined or custom form events that are enabled for the object or the form. You can compare the values received with the constants of the "Form Events" theme. Note that the arrevents array is returned empty if no object method is associated with the object or if no form method is associated with the form. You want to enable two events and get the list of events for an object: ARRAY LONGINT ($ArrCurrentEvents;0) ARRAY LONGINT ($ArrEnabled;2) $ArrEnabled{1}:=On Header Click $ArrEnabled{2}:=On Footer Click OBJECT SET EVENTS (*;"Col1";$ArrEnabled;Enable events others unchanged) OBJECT GET EVENTS (*;"Col1";$ArrCurrentEvents) See also: OBJECT SET EVENTS 4D v14 Upgrade 213

214 Chapter 6 Language OBJECT Get indicator type OBJECT Get indicator type ( {* ;} object ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) Function result Longint Indicator type The new OBJECT Get indicator type command returns the current indicator type assigned to the thermometer(s) designated by the object and * parameters. You can set the indicator type using the Property List in Design mode, or using the new OBJECT SET INDICATOR TYPE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). You can compare the value returned by the command with the following constants, found in the "Form objects (Properties)" theme: Constant (value) Barber shop (2) Progress bar (1) Asynchronous progress bar (3) See also: OBJECT SET INDICATOR TYPE Comments Bar displaying continuous animation Standard progress bar Circular indicator displaying continuous animation 214 4D v14 Upgrade

215 OBJECT Get list reference OBJECT Get list reference OBJECT Get list reference ( {* ;} object {; listtype} ) ListRef Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) listtype Longint Type of list: Choice list, Required list or Excluded list Function result ListRef List reference number The new OBJECT Get list reference command returns the reference number (ListRef) of the hierarchical list associated with the object or group of objects designated by object and *. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, this indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). By default, if you omit the listtype parameter, the command returns the name of the choice list (list of values) associated with the object. You can also get the reference number for required lists or excluded lists by passing, in listtype, one of the following constants found in the "Form objects (Properties)" theme: Constant (value) Choice list (0) Required list (1) Excluded list (2) Comments Simple list of values to choose from ("Choice List" option in the Property List) (default) Lists only values accepted for entry ("Required List" option in the Property List) Lists values not accepted for entry ("Excluded List" option in the Property List) If there is no hierarchical list associated with the object for the listtype defined, the command returns 0. See also: OBJECT SET LIST BY REFERENCE, OBJECT Get list name 4D v14 Upgrade 215

216 Chapter 6 Language OBJECT GET MAXIMUM VALUE OBJECT GET MAXIMUM VALUE ( {*; } object ; maxvalue ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) maxvalue Date Time Integer Longint Integer 64 bits Real Float Current maximum value for object The new OBJECT GET MAXIMUM VALUE command returns, in the maxvalue variable, the current maximum value of the object(s) designated by the object and * parameters. You can set the "Maximum Value" property using the Property List in Design mode, or using the new OBJECT SET MAXIMUM VALUE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). See also: OBJECT SET MAXIMUM VALUE, OBJECT GET MINIMUM VALUE, 216 4D v14 Upgrade

217 OBJECT GET MINIMUM VALUE OBJECT GET MINIMUM VALUE OBJECT GET MINIMUM VALUE ( {*; } object ; minvalue ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) minvalue Date Time Integer Longint Integer 64 bits Real Float Current minimum value for object The new OBJECT GET MINIMUM VALUE command returns, in the minvalue variable, the current minimum value of the object(s) designated by the object and * parameters. You can set the "Minimum Value" property using the Property List in Design mode, or using the new OBJECT SET MINIMUM VALUE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). See also: OBJECT SET MINIMUM VALUE OBJECT Get multiline OBJECT Get multiline ( {* ;} object ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Longint Multiline status of object The new OBJECT Get multiline command returns the current state of the "Multiline" option for the object(s) designated by the object and * parameters. 4D v14 Upgrade 217

218 Chapter 6 Language You can set the "Multiline" option for an object using the Property List, or using the new OBJECT SET MULTILINE command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). The value returned corresponds to one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Multiline Auto (0) Multiline No (2) Multiline Yes (1) Note If you apply the OBJECT Get multiline command to an object that does not support the "Multiline" option, the command returns 0. See also: OBJECT SET MULTILINE Comments In single-line areas, words located at the end of lines are truncated and there are no line returns. In multiline areas, 4D carries out automatic line returns. There are never line returns: the text is always displayed on a single row. If the Alpha or Text field or variable contains carriage returns, the text located after the first carriage return is removed as soon as the area is modified. In single-line areas, the text is displayed up to the first carriage return or until the last word that can be displayed entirely. 4D inserts line returns; it is possible to scroll the contents of the area by pressing the down arrow key. In multiline areas, 4D carries out automatic line returns D v14 Upgrade

219 OBJECT Get placeholder OBJECT Get placeholder OBJECT Get placeholder ( {* ;} object ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Text Placeholder text associated with object The new OBJECT Get placeholder command returns the placeholder text associated with the object(s) designated by the object and * parameters. If there is no placeholder text associated with the object, the command returns an empty string. You can define the placeholder text either using the Property List, or using the OBJECT SET PLACEHOLDER command. For more information, refer to the Placeholder text paragraph on page 51. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). If the placeholder is an xliff reference defined using the Property List, the command returns the original reference in the form ":xliff:resname", and not its calculated value. You want to get the field placeholder text: $txt:=object Get placeholder ([People]LastName) See also: OBJECT SET PLACEHOLDER 4D v14 Upgrade 219

220 Chapter 6 Language OBJECT GET PRINT VARIABLE FRAME OBJECT GET PRINT VARIABLE FRAME ( {*; } object ; variableframe {; fixed- Subform} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) variableframe Boolean True = Variable frame printing, False = Fixed frame printing fixedsubform Longint Option for printing subforms in fixed size The new OBJECT GET PRINT VARIABLE FRAME command gets the current configuration of the variable frame print options for the object(s) designated by the object and * parameters. Variable frame printing properties can be defined using the Property List, or using the new OBJECT SET PRINT VARIABLE FRAME command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, this indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the variableframe parameter, the command returns a Boolean variable whose value indicates the enabled (True) or disabled (False) state of variable frame printing. If the object is a subform and if variable frame printing is disabled (False), the command also returns, in the fixedsubform parameter, the fixed frame print option of the subform D v14 Upgrade

221 OBJECT Get style sheet You can compare the value returned with the following constants, found in the "Form objects (Properties)" theme: Constant (value) Print Frame fixed with truncation (1) Print Frame fixed with multiple records (2) Comments See also: OBJECT SET PRINT VARIABLE FRAME 4D prints only the records that fit into the area of the subform. The form is printed only once and those records that are not printed are ignored. The frame remains the same size, but 4D prints the form several times to include all the records. OBJECT Get style sheet OBJECT Get style sheet ( {* ;} object ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Text Name of style sheet The new OBJECT Get style sheet command returns the name of the style sheet associated with the object(s) designated by the object and * parameters. Style sheets may have been assigned in Design mode using the Property List, or for the current process using the new OBJECT SET STYLE SHEET command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). 4D v14 Upgrade 221

222 Chapter 6 Language The command can return either: a style sheet name, the string " automatic " if the "Automatic" style sheet is assigned, an empty string ("") if no style sheet is assigned. If the command designates several objects, the style sheet returned is only meaningful if the style sheet is assigned to all of the objects. See also: OBJECT SET STYLE SHEET OBJECT Get text orientation OBJECT Get text orientation ( {* ;} object ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Longint Angle of text rotation The new OBJECT Get text orientation command returns the current orientation value applied to the text of the object(s) designated by the object and * parameters. You can set the "Orientation" option for an object in Design mode using the Property List (see the Rotation of text paragraph on page 74), or using the new OBJECT SET TEXT ORIENTATION command. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only) D v14 Upgrade

223 OBJECT Get text orientation The value returns corresponds to one of the following constants, found in the "Form objects (Properties)" theme:. Constant (value) Orientation 0 (0) Orientation 90 right (90) Orientation 180 (180) Orientation 90 left (270) Comments No rotation (default value) Orientation of text to 90 clockwise Orientation of text to 180 clockwise Orientation of text to 90 counter-clockwise Given the following object (where a "90 left" orientation was applied in the Form editor): When the form is executed, if you call the following statement: OBJECT SET TEXT ORIENTATION (*;"mytext";orientation 180 )... then the object appears as follows: $vort:=object Get text orientation (*;"mytext") // $vort=180 See also: OBJECT SET TEXT ORIENTATION 4D v14 Upgrade 223

224 Chapter 6 Language OBJECT Get three states checkbox OBJECT Get three states checkbox ( {* ;} object ) Boolean Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Boolean True = three-states checkbox, False = standard checkbox The new OBJECT Get three states checkbox command returns the current state of the "Three-States" property for the checkbox(es) designated by the object and * parameters. You can set the "Three-States" property either using the Property List, or using the OBJECT SET THREE STATES CHECKBOX command if it was called in the current process. See also: OBJECT SET THREE STATES CHECKBOX OBJECT Get type OBJECT Get type ( {* ;} object ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) Function result Longint Type of object The new OBJECT Get type command returns the type of the object designated by the object and * parameters in the current form. Passing the optional * parameter indicates that the object parameter is an object name (string). This syntax is mandatory if you are processing static objects such as lines or rectangles D v14 Upgrade

225 OBJECT Get type If you do not pass this parameter, it indicates that the object parameter is a variable. In this case, you pass a variable reference instead of a string. Note If you apply this command to a set of objects, the type of the last object is returned. The value returned corresponds to one of the following constants, available in the new "Form Object Types" theme: Constant Type Value Object type unknown Longint 0 Object type static text Longint 1 Object type static picture Longint 2 Object type text input Longint 3 Object type picture input Longint 4 Object type radio button field Longint 5 Object type hierarchical list Longint 6 Object type listbox Longint 7 Object type listbox header Longint 8 Object type listbox column Longint 9 Object type listbox footer Longint 10 Object type combobox Longint 11 Object type popup drop down Longint 12 Object type hierarchical popup Longint 13 Object type picture popup Longint 14 Object type push button Longint 15 Object type 3D button Longint 16 Object type highlight button Longint 17 Object type invisible button Longint 18 Object type picture button Longint 19 Object type button grid Longint 20 Object type group Longint 21 Object type radio button Longint 22 Object type 3D radio button Longint 23 Object type picture radio button Longint 24 Object type checkbox Longint 25 Object type 3D checkbox Longint 26 Object type progress indicator Longint 27 Object type dial Longint 28 Object type ruler Longint 29 Object type groupbox Longint 30 4D v14 Upgrade 225

226 Chapter 6 Language Object type rectangle Longint 31 Object type line Longint 32 Object type rounded rectangle Longint 33 Object type oval Longint 34 Object type matrix Longint 35 Object type splitter Longint 36 Object type tab control Longint 37 Object type plugin area Longint 38 Object type subform Longint 39 Object type web area Longint 40 OBJECT Is styled text OBJECT Is styled text ( {* ;} object ) Boolean Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) Function result Boolean True if object is a multi-style text, False otherwise The new OBJECT Is styled text command returns True when the "Multistyle" option is checked for the object(s) designated by the object and * parameters. The "Multi-style" option lets you use rich test areas including individual style variations. For more information, refer to the Design Reference manual. Multi-style objects can be managed by programming using the commands of the "Styled Text" theme. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only) D v14 Upgrade

227 OBJECT SET ACTION A form contains a field represented by two different objects; one of the objects has the "Multi-style" property checked, and the other one does not. You can write: $Style:=OBJECT Is styled text (*;"Styled_text") // returns True ("Multi-style" option is checked) $Style:=OBJECT Is styled text (*;"Plain_text") // returns False ("Multi-style" option is not checked) OBJECT SET ACTION OBJECT SET ACTION ( {*; } object ; action ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) action Text Action to associate The new OBJECT SET ACTION command modifies, for the current process, the standard action associated with the object(s) designated by the object and * parameters. In previous versions of 4D, standard actions could only be set using the Property list. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the action parameter, pass an action code (string) indicating the standard action to associate with the object. You can pass one of the following constants, found in the "Text Values for Associated Standard Action" theme: Constant Type Value Object Refresh current URL action Text "39" Object Show Clipboard action Text "23" Object Add subrecord action Text "14" Object Goto page action Text "15" Object Cancel action Text "1" Object Undo action Text "17" Object Stop loading URL action Text "40" 4D v14 Upgrade 227

228 Chapter 6 Language Constant Type Value Object Paste action Text "20" Object Copy action Text "19" Object Cut action Text "18" Object MSC action Text "36" Object Last record action Text "6" Object Last page action Text "11" Object Clear action Text "21" Object Previous record action Text "4" Object Next record action Text "3" Object Edit subrecord action Text "12" Object Open back URL action Text "37" Object Open next URL action Text "38" Object Previous page action Text "9" Object Next page action Text "8" Object First record action Text "5" Object First page action Text "10" Object Database Settings action Text "32" Object Quit action Text "27" Object Redo action Text "31" Object Return to Design mode action Text "35" Object Automatic splitter action Text "16" Object Delete record action Text "7" Object Delete subrecord action Text "13" Object Test Application action Text "26" Object Select all action Text "22" Object Accept action Text "2" Object No standard action Text "0" You want to associate the Validate standard action with a button: OBJECT SET ACTION (*;"bvalidate";object Accept action) See also: OBJECT Get action 228 4D v14 Upgrade

229 OBJECT SET BORDER STYLE OBJECT SET BORDER STYLE OBJECT SET BORDER STYLE ( {*; } object ; borderstyle ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) borderstyle Longint Border line style The new OBJECT SET BORDER STYLE command modifies the border line style of the object(s) designated by the object and * parameters. The "Border Line Style" property modifies the appearance of the object outlines. For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the borderstyle parameter, pass the value of the border line style that you want to apply to the object. You can pass one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Border None (0) Border Double (5) Border Plain (1) Border Raised (3) Border Sunken (4) Border System (6) Border Dotted (2) See also: OBJECT Get border style Comments Objects appear with no border. Objects appear framed with a double line, i.e., two continuous 1-pt. lines separated by a pixel. Objects appear framed with a continuous 1-pt. border line. Objects appear framed with a 3D effect (raised). Objects appear framed with a sunken 3D effect. The border line is drawn based on the graphic specifications of the system. Objects appear framed with a dotted 1-pt. border line. 4D v14 Upgrade 229

230 Chapter 6 Language OBJECT SET CONTEXT MENU OBJECT SET CONTEXT MENU ( {*; } object ; contextmenu ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) contextmenu Boolean True = enable context menu, False = disable context menu The new OBJECT SET CONTEXT MENU command enables or disables, for the current process, the association of a context menu by default with the object(s) designated by the object and * parameters. The "Context Menu" option is available for text type entry areas, Web areas and pictures. You can use it to associate a standard action menu with these objects depending on their type (for example Copy/Paste for text objects). For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). Pass True in the contextmenu parameter to enable the context menu, and False to disable it. See also: OBJECT Get context menu 230 4D v14 Upgrade

231 OBJECT SET COORDINATES OBJECT SET COORDINATES OBJECT SET COORDINATES ( {*; } object ; left ; top{; right ; bottom }) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Longint Object name (if * is specified) or Field or variable (if * is omitted) left Longint Left coordinate of object in pixels top Longint Top coordinate of object in pixels right Longint Right coordinate of object in pixels bottom Longint Bottom coordinate of object in pixels Note This command is the equivalent of using the existing OBJECT MOVE command and passing its 2nd * parameter. The new OBJECT SET COORDINATES command modifies the location and, optionally, the size of the object(s) designated by the object and * parameters for the current process. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the left and top parameters, pass the new absolute coordinates of the object in the form. These coordinates must be expressed in pixels with respect to the top left corner of the form. You can also pass absolute coordinate values in the right and bottom parameters, indicating the bottom right corner of the object. If this corner does not correspond to the corner of the object after application of the left and top parameters, the object is resized accordingly. Note If you want to move an object relative to its initial position, we recommend using the existing OBJECT MOVE command. This command only functions in the following contexts: Input forms in entry mode, Forms displayed using the DIALOG command, 4D v14 Upgrade 231

232 Chapter 6 Language Headers and footers of output forms displayed by the MODIFY SELECTION or DISPLAY SELECTION command, Forms being printed. The following statement places the "button_1" object at the (10,20) (30,40) coordinates: OBJECT SET COORDINATES (*;"button_1";10;20;30;40) See also: OBJECT MOVE OBJECT SET DATA SOURCE OBJECT SET DATA SOURCE ( {*; } object ; datasource ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) datasource Pointer Pointer to new data source for object The new OBJECT SET DATA SOURCE command modifies the data source of the object(s) designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only) D v14 Upgrade

233 OBJECT SET DATA SOURCE The data source is the field or variable whose value is represented by the object when the form is executed. In Design mode, the data source is defined in the Property list, usually through the Source and Source Field (fields) or Variable Name (variables) row: Data source (field) Data source (variable) Note In 4D v14, you can directly reference a field associated with an object of the pop-up/drop-down list or combo box type (see the Pop-up menus and combo boxes associated with fields and variables paragraph on page 70). Except for list boxes (see below), all data sources of the form can be modified by this command. It is up to the developer to ensure the consistency of the changes made. In the case of list boxes, the following points must be considered: Data source modifications must take the list box type into account: for example, it is not possible to use a field as the data source for a column in an array type list box. For selection type list boxes, it is not possible to modify or read the data source of the list box object itself: in this case, it is an internal reference and not a data source. This command is mainly used in the context of array type list boxes. For selection type list boxes, you can use the LISTBOX SET COLUMN FORMULA command instead. 4D v14 Upgrade 233

234 Chapter 6 Language If this command is applied to a data source that is not modifiable, it does nothing. Modification of the data source for an entry area: C_POINTER ($ptrfield) $ptrfield:=field (3;2) OBJECT SET DATA SOURCE (*;"Input";$ptrField) See also: OBJECT Get data source OBJECT SET EVENTS OBJECT SET EVENTS ( {*; } object ; arrevents ; mode ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name or "" to designate the form (if * is specified) or Field or variable (if * is omitted) arrevents Longint array Array of events to set mode Longint Activation mode for events defined in arrevents The new OBJECT SET EVENTS command modifies, for the current process, the configuration of the form events of the form or object(s) designated by the object and * parameters. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). To define the configuration of events for the form itself, pass the optional * parameter and an empty string "" in object: in this case, you designate the current form. Note If you want to modify the events of a subform related to a table, you can only use the syntax based on the object name. In the arrevents parameter, pass a longint array containing the list of predefined or custom form events that you want to modify (you can use the mode parameter to specify whether the modification consists of enabling or disabling the events) D v14 Upgrade

235 OBJECT SET EVENTS To designate a predefined event to modify, you can pass, in each element of the arrevents array, one of the following constants, found in the "Form Events" theme: Constant Type Value On Delete Action Longint 58 On Activate Longint 11 On Display Detail Longint 8 On Outside Call Longint 10 On Plug in Area Longint 19 On After Keystroke Longint 28 On After Edit Longint 45 On After Sort Longint 30 On Before Keystroke Longint 17 On Before Data Entry Longint 41 On Mac Toolbar Button Longint 55 On Close Box Longint 22 On Page Change Longint 56 On Load Record Longint 40 On URL Resource Loading Longint 48 On Clicked Longint 4 On Header Click Longint 42 On Arrow Click Longint 38 On Long Click Longint 39 On Footer Click Longint 57 On Collapse Longint 44 On Begin URL Loading Longint 47 On Begin Drag Over Longint 46 On Mouse Enter Longint 35 On Picture Scroll Longint 59 On Column Moved Longint 32 On Row Moved Longint 34 On Expand Longint 43 On Drop Longint 16 On Deactivate Longint 12 On Data Change Longint 20 On Double Clicked Longint 13 On Header Longint 5 On URL Loading Error Longint 50 On Close Detail Longint 26 On URL Filtering Longint 51 On End URL Loading Longint 49 On Mouse Leave Longint 36 On Getting Focus Longint 15 On Drag Over Longint 21 4D v14 Upgrade 235

236 Chapter 6 Language On Printing Detail Longint 23 On Printing Footer Longint 7 On Printing Break Longint 6 On Unload Longint 24 On Menu Selected Longint 18 On Timer Longint 27 On Bound Variable Change Longint 54 On Selection Change Longint 31 On Open Detail Longint 25 On Open External Link Longint 52 On Losing Focus Longint 14 On Resize Longint 29 On Column Resize Longint 33 On Window Opening Denied Longint 53 On Mouse Move Longint 37 On Validate Longint 3 It is important to note that the On Load (1) event is not included in this list: this event cannot be defined because it has already been generated during the execution of the command. In arrevents, you can also pass any value corresponding to a custom event. In this case, we recommend using negative values (see the documentation of the CALL SUBFORM CONTAINER command). You use the mode parameter to set the overall processing to be carried out for the array elements. To do this, you can pass one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Enable events disable others (0) Enable events others unchanged (1) Disable events others unchanged (2) Comments All the events listed in the arrevents array are enabled; all the other events are disabled All the events listed in the arrevents array are enabled; the status of other events remain unchanged All the events listed in the arrevents array are disabled; the status of other events remain unchanged The OBJECT SET EVENTS command can lead to the enabling of events that are not supported by the object (depending on its type). In this case, the events will simply be ignored D v14 Upgrade

237 OBJECT SET EVENTS If an object is duplicated after a call to the OBJECT SET EVENTS command, the resulting enabled/disabled configuration is also duplicated. Enabling three form events for a set of list box objects and disabling other events: ARRAY LONGINT ($MyEventsOnLB;3) $MyEventsOnLB {1}:=On After Sort $MyEventsOnLB {2}:=On Column Moved $MyEventsOnLB {3}:=On Column Resize OBJECT SET EVENTS (*;"MyLB@"; $MyEventsOnLB; Enable events disable others) // enables 3 events and disables all others Disabling three form events for a set of list box objects, without modifying the other events: ARRAY LONGINT ($MyEventsOnLB;3) $MyEventsOnLB {1}:=On After Sort $MyEventsOnLB {2}:=On Column Moved $MyEventsOnLB {3}:=On Column Resize OBJECT SET EVENTS (*;"MyLB@"; $MyEventsOnLB; Disable events others unchanged) // disables only these 3 events Enabling a form event for an object, without modifying the other events: ARRAY LONGINT ($MyEventsOnLB;1) $MyEventsOnLB {1}:=On Column Moved OBJECT SET EVENTS (*;"Col1"; $MyEventsOnLB;Enable events others unchanged) // only enables this event Disabling all events of the form: ARRAY LONGINT ($MyFormEvents;0) OBJECT SET EVENTS (*;""; $MyFormEvents;Enable events disable others) // disables all events Disables a single event of the form without modifying the others: ARRAY LONGINT ($MyFormEvents;1) $MyFormEvents{1}:=On Timer OBJECT SET EVENTS (*;""; $MyFormEvents;Disable events others unchanged) // only disables this event See also: OBJECT GET EVENTS 4D v14 Upgrade 237

238 Chapter 6 Language OBJECT SET INDICATOR TYPE OBJECT SET INDICATOR TYPE ( {*; } object ; indicator ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) indicator Longint Indicator type The new OBJECT SET INDICATOR TYPE command modifies the type of progress indicator for the thermometer(s) designated by the object and * parameters in the current process. The indicator type defines the display variant of the thermometer. For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the indicator parameter, pass the type of indicator you want to display. You can use one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Comments Barber shop (2) Bar displaying continuous animation Progress bar (1) Standard progress bar Asynchronous progress bar (3) Circular indicator displaying continuous animation See also: OBJECT Get indicator type 238 4D v14 Upgrade

239 OBJECT SET LIST BY REFERENCE OBJECT SET LIST BY REFERENCE OBJECT SET LIST BY REFERENCE ( {*; } object {; listtype}; list ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) listtype Longint Type of list: Choice list, Required list or Excluded list list ListRef List reference number The new OBJECT SET LIST BY REFERENCE command defines or replaces the list associated with the object(s) designated by the object and * parameters, with the hierarchical list referenced in the list parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). By default, if you omit the listtype parameter, the command defines a source choice list (choice of values) for the object. You can designate any type of list in the listtype parameter. To do this, you just need to pass one of the following constants found in the "Form objects (Properties)" theme: Constant (value) Choice list (0) Required list (1) Excluded list (2) Comments Simple list of values to choose from ("Choice List" option in the Property List) (default) Lists only values accepted for entry ("Required List" option in the Property List) Lists values not accepted for entry ("Excluded List" option in the Property List) In list, pass the reference number of the hierarchical list that you want to associated with the object. This list must have been generated using the New list, Copy list or Load list command. 4D v14 Upgrade 239

240 Chapter 6 Language To end the association of a list with an object, you can just pass 0 in the list parameter for the type of list concerned. Note Removing a list association does not delete the list reference from memory. Remember to call the CLEAR LIST command when you no longer need the list. This command is particularly interesting in the context of a pop-up or combo box associated with a variable or a field (see the Pop-up menus and combo boxes associated with fields and variables paragraph on page 70). In this case, the association is dynamic and any change in the list is copied to the form. When the object is associated with an array, the list is copied into the array and any changes to the list are not available automatically (see final example). Associating a simple choice list (default list type) to a text field: vcountrieslist:=new list APPEND TO LIST (vcountrieslist ; "Spain" ; 1) APPEND TO LIST (vcountrieslist ; "Portugal" ; 2) APPEND TO LIST (vcountrieslist ; "Greece" ; 3) OBJECT SET LIST BY REFERENCE ([Contact]Country;vCountriesList) Associating the "vcolor" list as a simple choice list with the "DoorColor" pop-up/drop-down list: vcolor:=new list APPEND TO LIST (vcolor ; "Blue" ; 1) APPEND TO LIST (vcolor ; "Green" ; 2) APPEND TO LIST (vcolor ; "Red" ; 3) APPEND TO LIST (vcolor ; "Yellow" ; 4) OBJECT SET LIST BY REFERENCE (*;"DoorColor";Choice list;vcolor) Now you want to associate the "vcolor" list with a combo box named "WallColor". Since this combo box is enterable, you want to make sure certain colors, such as "black," "purple," etc., cannot be used. These colors are placed in the "vreject" list: OBJECT SET LIST BY REFERENCE (*;"WallColor";Choice list;vcolor) vreject:=new list APPEND TO LIST (vreject ; "Black" ; 1) APPEND TO LIST (vreject ; "Gray" ; 2) APPEND TO LIST (vreject ; "Purple" ; 3) OBJECT SET LIST BY REFERENCE (*;"WallColor";Excluded list;vreject) 240 4D v14 Upgrade

241 OBJECT SET LIST BY REFERENCE You want to remove the list associations: OBJECT SET LIST BY REFERENCE (*;"WallColor";Choice list;0) OBJECT SET LIST BY REFERENCE (*;"WallColor";Required list;0) OBJECT SET LIST BY REFERENCE (*;"WallColor";Excluded list;0) This example illustrates the difference in how the command works when applied to a pop-up menu associated with a text array or one associated with a text variable (new in v14). There are two pop-up menus in a form: The contents of these pop-up menus is set using the <>vcolor list (containing color values). The following code is executed when the form is loaded: ARRAY TEXT (arr1;0) //arr1 pop up C_TEXT (text1) //text1 pop up OBJECT SET LIST BY REFERENCE (*;"arr1";<>vcolor) OBJECT SET LIST BY REFERENCE (*;"text1";<>vcolor) During execution, both menus propose the same values: Montage showing contents of menus simultaneously Then you run the following code, for example by means of a button: APPEND TO LIST (<>vcolor;"white";5) APPEND TO LIST (<>vcolor;"black";6) 4D v14 Upgrade 241

242 Chapter 6 Language Only the menu associated with the Text field is updated (by means of the dynamic reference): In order to update the list associated with the pop-up managed by array, you need to call the OBJECT SET LIST BY REFERENCE command again to copy the contents of the list. See also: OBJECT Get list reference OBJECT SET PLACEHOLDER OBJECT SET PLACEHOLDER ( {*; } object ; placeholdertext ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) placeholdertext Text Placeholder text associated with object The new OBJECT SET PLACEHOLDER command associates placeholder text with the object(s) designated by the object and * parameters. For more information about placeholder text, refer to the Placeholder text paragraph on page 51. If placeholder text is already associated with the object through the Property List, this text is replaced in the current process by the contents of the placeholdertext parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only) D v14 Upgrade

243 OBJECT SET PRINT VARIABLE FRAME In placeholdertext, pass the help text or indication that must appear when the object is empty. Note The OBJECT SET PLACEHOLDER command does not support the insertion of xliff references into the placeholder text. This is only possible for placeholder text that is defined using the Property List. This command can only be used with form objects of the variable, field or combo box type. You can associate placeholder text with Alpha and Text type values. You can also associate it with Date or Time type data if the form object is given the Blank if null property. You want to display "Search" as placeholder text in a combo box: OBJECT SET PLACEHOLDER (*;"search_combo";"search") See also: OBJECT Get placeholder OBJECT SET PRINT VARIABLE FRAME OBJECT SET PRINT VARIABLE FRAME ( {*; } object ; variableframe {; fixed- Subform} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) variable- Frame Boolean True = Variable frame printing, False = Fixed frame printing fixedsubform Longint Options for printing subforms in fixed size The new OBJECT SET PRINT VARIABLE FRAME command modifies the Print Variable Frame property of the object(s) designated by the object and * parameters. This property is available for Text or Picture type variables and fields, as well as subforms. Subforms have an additional option for fixed size printing. For more information, refer to the Design Reference manual. If you apply this command to an object that does not support this property, the command does nothing. 4D v14 Upgrade 243

244 Chapter 6 Language Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). Pass a Boolean in the variableframe parameter: if you pass True, the object is printed with a variable frame. If you pass False, it is printed with a fixed frame. The optional fixedsubform parameter lets you set an additional option when you pass False in the variableframe parameter and the object is a subform (it is ignored in all other cases). In this case, you can define the fixed frame printing mode for the subform. You can pass one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Print Frame fixed with truncation (1) Print Frame fixed with multiple records (2) Comments See also: OBJECT GET PRINT VARIABLE FRAME 4D prints only the records that fit into the area of the subform. The form is printed only once and those records that are not printed are ignored. The frame remains the same size, but 4D prints the form several times to include all the records. OBJECT SET MAXIMUM VALUE OBJECT SET MAXIMUM VALUE ( {*; } object ; maxvalue ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) maxvalue Date Time Integer Longint Integer 64 bits Real Float Maximum value for object The new OBJECT SET MAXIMUM VALUE command modifies the maximum value of the object(s) designated by the object and * parameters for the current process D v14 Upgrade

245 OBJECT SET MINIMUM VALUE The "Maximum Value" property can be applied to number, date or time type data. For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In maxvalue, pass the new maximum value you want to assign to the object for the current process. This value must correspond to the object type, otherwise error 18 "Field types are incompatible" is returned. See also: OBJECT SET MINIMUM VALUE, OBJECT GET MINIMUM VALUE OBJECT SET MINIMUM VALUE OBJECT SET MINIMUM VALUE ( {*; } object ; minvalue ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) minvalue Date Time Integer Longint Integer 64 bits Real Float Minimum value for object The new OBJECT SET MINIMUM VALUE command modifies the minimum value of the object(s) designated by the object and * parameters for the current process. The "Minimum Value" property can be applied to number, date or time type data. For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). 4D v14 Upgrade 245

246 Chapter 6 Language In minvalue, pass the new minimum value you want to assign to the object for the current process. This value must correspond to the object type, otherwise error 18 "Field types are incompatible" is returned. See also: OBJECT GET MINIMUM VALUE OBJECT SET MULTILINE OBJECT SET MULTILINE ( {*; } object ; multiline ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) multiline Longint Status of multiline property The new OBJECT SET MULTILINE command modifies the "Multiline" property of the object(s) designated by the object and * parameters. The "Multiline" property controls two parameters related to the display and printing of text areas: display of words located at the end of the line in single-line areas and the automatic insertion of line returns. For more information, refer to the Design Reference manual. If you apply this command to an object that does not support this property, the command does nothing. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the multiline parameter, pass the new value of the option that you want to set. You can use the following constants, found in the "Form objects (Properties)" theme: Constant (value) Multiline Auto (0) Comments In single-line areas, words located at the end of lines are truncated and there are no line returns. In multiline areas, 4D carries out automatic line returns D v14 Upgrade

247 OBJECT SET STYLE SHEET Multiline No (2) Multiline Yes (1) There are never line returns: the text is always displayed on a single row. If the Alpha or Text field or variable contains carriage returns, the text located after the first carriage return is removed as soon as the area is modified. In single-line areas, the text is displayed up to the first carriage return or until the last word that can be displayed entirely. 4D inserts line returns; it is possible to scroll the contents of the area by pressing the down arrow key. In multiline areas, 4D carries out automatic line returns. You want to prohibit multiple lines in an entry area: OBJECT SET MULTILINE (*;"ventry";multiline No) See also: OBJECT Get multiline OBJECT SET STYLE SHEET OBJECT SET STYLE SHEET ( {*; } object ; stylesheetname ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) stylesheetname Text Name of style sheet The new OBJECT SET STYLE SHEET command modifies, for the current process, the style sheet associated with the object(s) designated by the object and * parameters. A style sheet modifies the font, font size and font style. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). 4D v14 Upgrade 247

248 Chapter 6 Language In the stylesheetname parameter, you pass the name of the style sheet to be applied to the object. You can also pass either: the name of an existing style sheet (if the style sheet does not exist, an error is returned, that you can intercept using a method installed by the ON ERR CALL command). the Automatic style sheet constant from the "Font Styles" theme in order to apply the "Automatic" style sheet. an empty string ("") so as to not apply the style sheet to the object. If a style sheet was already associated with the object in Design mode, calling this command replaces it for the current process. During the session, if you use the ST SET TEXT, ST SET ATTRIBUTES or OBJECT SET FONT commands on the object in order to modify its font or font size, the reference to the style sheet is automatically deleted from the object -- even if you assign the same attributes as those of the style sheet. However, if you modify the style (bold, italic, etc.), for example using the ST SET ATTRIBUTES or OBJECT SET FONT STYLE commands, these new properties are added to the style sheet for the duration of the session. See also: GET STYLE SHEET INFO, LIST OF STYLE SHEETS, OBJECT Get style sheet OBJECT SET TEXT ORIENTATION OBJECT SET TEXT ORIENTATION ( {*; } object ; orientation ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) orientation Longint Value of object orientation The new OBJECT SET TEXT ORIENTATION command modifies the orientation of the contents for the object(s) designated by the object and * parameters for the current process D v14 Upgrade

249 OBJECT SET TEXT ORIENTATION The "Orientation" property, available in the Form editor, performs permanent rotations of text areas in your forms. Unlike this property, the OBJECT SET TEXT ORIENTATION command applies the rotation to the contents of the object, but not to the object itself. For more information, refer to the Rotation of text paragraph on page 74. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). Only static text as well as non-enterable variables and fields can be rotated. If you apply this command to an object that does not support text orientation, the command does nothing. For more information, refer to the Objects eligible to rotate paragraph on page 74. In the orientation parameter, you pass the absolute orientation that you want to assign to the object. You must use one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Orientation 0 (0) Orientation 90 right (90) Orientation 180 (180) Orientation 90 left (270) Note Only angles corresponding to these values are supported. If you pass any other value, it will be ignored. You want to apply an orientation of 270 to a variable in your form: OBJECT SET ENTERABLE (*;"myvar";false) // mandatory if variable is enterable OBJECT SET TEXT ORIENTATION (*;"myvar";orientation 90 left) See also: OBJECT Get text orientation Comments No rotation (default value) Orientation of text to 90 clockwise Orientation of text to 180 clockwise Orientation of text to 90 counter-clockwise 4D v14 Upgrade 249

250 Chapter 6 Language OBJECT SET THREE STATES CHECKBOX OBJECT SET THREE STATES CHECKBOX ( {*; } object ; threestates ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) threestates Boolean True = three-states checkbox, False = standard checkbox The new OBJECT SET THREE STATES CHECKBOX command modifies, for the current process, the "Three-States" property of the checkbox(es) designated by the object and * parameters. The "Three-states" option allows the additional "semi-checked" state to be used for checkboxes. For more information, refer to the Design Reference manual. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). This command only applies to checkboxes associated with variables, and not to Boolean fields that are represented as checkboxes. In the threestates parameter, pass True to enable the "three states" mode, or False to disable it. See also: OBJECT Get three states checkbox Modified commands OBJECT Get choice list name This command is renamed OBJECT Get list name in 4D v14 and its action was extended D v14 Upgrade

251 OBJECT Get list name OBJECT Get list name OBJECT Get list name ( {* ;} object {; listtype} ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) listtype Longint Type of list: Choice list, Required list or Excluded list Function result Text Name of list in Design mode Note In previous versions of 4D, this command was named OBJECT Get choice list name. The OBJECT Get list name command accepts a new optional parameter, listtype, used to designate the type of list that you want to get. By default, if you omit the listtype parameter, the command returns the name of the choice list (list of values) associated with the object like in previous versions of 4D. You can also get the names of required lists or excluded lists by passing, in listtype, one of the following constants found in the "Form objects (Properties)" theme: Constant (value) Choice list (0) Required list (1) Excluded list (2) If no list of the type defined is associated with the object, the command returns an empty string (""). See also: OBJECT SET LIST BY NAME Comments Simple list of values to choose from ("Choice List" option in the Property List) (default) Lists only values accepted for entry ("Required List" option in the Property List) Lists values not accepted for entry ("Excluded List" option in the Property List) 4D v14 Upgrade 251

252 Chapter 6 Language OBJECT GET RGB COLORS OBJECT GET RGB COLORS ( * ; object ; foregroundcolor ; backgroundcolor ; altbackgrndcolor ) A new constant that sets a transparent background has been added to the "SET RGB COLORS" theme: Constant Type Value Background color none Longint -16 This constant can be returned in the backgroundcolor and altbackgrndcolor parameters. OBJECT SET CHOICE LIST NAME OBJECT SET FONT This command is renamed OBJECT SET LIST BY NAME in 4D v14 and its action is extended. OBJECT SET FONT ( {*; }object ; font) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or a variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) font String Name of font The OBJECT SET FONT command now only accepts a font name (string) in the font parameter. The use of font numbers (longints) is no longer supported D v14 Upgrade

253 OBJECT SET LIST BY NAME OBJECT SET LIST BY NAME OBJECT SET LIST BY NAME ( {*; } object {; listtype}; list ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) listtype Longint Type of list: Choice list, Required list or Excluded list list String Name of choice list defined in Design mode or "" to disassociate the list Note In previous versions of 4D, this command was named OBJECT SET CHOICE LIST NAME. The OBJECT SET LIST BY NAME command now allows you to set or replace all the types of lists associated with the object(s) designated by the object and * parameters: choice lists, list of required values, and lists of excluded values. To do this, in the listtype parameter you pass one of the following constants, found in the "Form objects (Properties)" theme: Constant (value) Choice list (0) Required list (1) Excluded list (2) Comments Simple list of values to choose from ("Choice List" option in the Property List) (default) Lists only values accepted for entry ("Required List" option in the Property List) Lists values not accepted for entry ("Excluded List" option in the Property List) If you omit this parameter, value 0 (Choice list) is used by default. In addition, it is now possible to disassociate a list that was associated with an object: to do this, you pass an empty string ("") in the list parameter for the type of list concerned. Associate the "color_choice" list as a simple pop-up/drop-down list named "DoorColor": OBJECT SET LIST BY NAME (*;"DoorColor";Choice list;"color_choice") // in this case, the 3rd parameter (constant) can be omitted 4D v14 Upgrade 253

254 Chapter 6 Language You want to associate the "color_choice" list with a "WallColor" combo box. Since the combo box is enterable, you want for it not to be possible to use certain colors such as "black", "purple" etc. These colors are placed in the "excl_colors" list: OBJECT SET LIST BY NAME (*;"WallColor";Choice list;"color_choice") OBJECT SET LIST BY NAME (*;"WallColor";Excluded list;"excl_colors") You want to remove the list associations: // removal of a choice list OBJECT SET LIST BY NAME (*;"DoorColor";Choice list; "") // removal of list of values that are not allowed OBJECT SET LIST BY NAME (*;"WallColor";Excluded list;"") See also: OBJECT Get list name OBJECT SET RGB COLORS OBJECT SET RGB COLORS ( {*; } object ; foregroundcolor ; background- Color {; altbackgrndcolor} ) A new constant that sets a transparent background has been added to the "SET RGB COLORS" theme: Constant Type Value Background color none Longint -16 This constant can only be used with the backgroundcolor and altbackgrndcolor parameters. Changing to transparent background with a light font color: OBJECT SET RGB COLORS(*;"myVar";Light shadow color;background color none) See also: OBJECT GET RGB COLORS 254 4D v14 Upgrade

255 OBJECT SET RGB COLORS Interaction of generic commands with multi-style areas In 4D v14, a new way of interacting has been defined between generic commands such as OBJECT SET RGB COLORS or OBJECT SET FONT STYLE and multi-style text areas. In previous versions of 4D, executing one of these commands modified the contents of any custom style tags inserted in the area. From now on, only default properties are affected by these commands (as well as any properties saved by means of default tags). Custom style tags remain as they are. For example, given a multi-style area where default tags were saved: The plain text of the area is as follows: <span style="text-align:left;font-family:'segoe UI';font-size:9pt;color:#009900">This is the word <span style="color:#d81e05">red</span></span> If you execute the following code: OBJECT SET COLOR(*;"myArea";-(Blue+(256*Yellow))) With 4D v14, the red color remains: 4D v14 versions prior to 4D v14 <span style="text-align:left;font-family:'segoe UI';fontsize:9pt;color:#0000FF">This is the word <span style="color:#d81e05">red</span></sp an> <span style="font-family:'segoe UI';fontsize:9pt;text-align:left;font-weight:normal;font-style:normal;text-decoration:none;color:#0000FF;"><span style="background-color:#ffffff">this is the word red</span></span> The following generic commands are concerned: OBJECT SET RGB COLORS OBJECT SET COLOR OBJECT SET FONT OBJECT SET FONT STYLE OBJECT SET FONT SIZE In the context of multi-style areas, generic commands should be used to set default styles only. To manage styles during database execution, we recommend using the commands of the "Styled Text" theme. 4D v14 Upgrade 255

256 Chapter 6 Language Objects (Language) This new theme contains commands used to create and work with data in object form. This new feature in 4D v14 extends the exchange opportunities between 4D and any application that supports structured data. 4D objects are created and initialized using the new C_OBJECT ("Compiler" theme) or ARRAY OBJECT ("Arrays" theme) commands. Structure of 4D objects The structure of "native" 4D objects is based on the classic principle of "property/value" pairs. The syntax of these objects is based on notation JSON, but does not follow it completely. Note To work with JSON objects, you must use the commands found in the new "JSON" theme. A property name is always a text, for example "Name". A property value can be of the following type: number (Real, Integer, etc.) text array (Text, Real, Boolean, Object, Pointer) null Boolean pointer (stored as such, evaluated using the JSON Stringify command or when copying), date (format "\"YYYY-MM-DDTHH:mm:ssZ\"") object (objects can be nested on several levels) 256 4D v14 Upgrade

257 OB Copy OB Copy OB Copy ( object {; resolveptrs} ) Value Parameter Type Description object Language object Structured object resolveptrs Boolean True = resolve pointers, False or omitted = do not resolve pointers Function result Language object Copy of object The OB Copy command returns an object containing a complete copy of the properties, sub-objects and values for the object. object must have been defined using the C_OBJECT command. If object contains pointer type values, by default the copy also contains the pointers. However, you can resolve pointers when copying by passing True in the resolveptrs parameter. In this case, each pointer present as a value in object is evaluated when copying and its dereferenced value is used. You want to duplicate an object containing simple values: C_OBJECT ($Object) C_TEXT ($JsonString) ARRAY OBJECT ($arraysel;0) ALL RECORDS ([Product]) While (Not (End selection ([Product]))) OB SET ($Object;"id";[Product]ID_Product) OB SET ($Object;"Product Name";[Product]Product_Name) OB SET ($Object;"Price";[Product]Price) OB SET ($Object;"Tax rate";[product]tax_rate) $ref_value:=ob Copy ($Object) // direct copy APPEND TO ARRAY ($arraysel;$ref_value) // the contents of $ref_value are identical to those of $Object NEXT RECORD ([Product]) End while // the contents of $ref_value $JsonString:=JSON Stringify array ($arraysel) 4D v14 Upgrade 257

258 Chapter 6 Language You duplicate an object containing pointers: C_OBJECT ($ref) OB SET ($ref;"name";->[company]name) //object with pointers OB SET ($ref;"country";->[company]country) ARRAY OBJECT ($sel;0) ARRAY OBJECT ($sel2;0) ALL RECORDS ([Company]) While (Not (End selection ([Company]))) $ref_comp:=ob Copy ($ref) // copy without evaluating pointers // $ref_comp={"name":"->[company]name","country":"->[company]country"} $ref_comp2:=ob Copy ($ref;true) //copy with evaluation of pointers // $ref_comp={"name":"4d SAS","country":"France"} APPEND TO ARRAY ($sel;$ref_comp) APPEND TO ARRAY ($sel2;$ref_comp2) NEXT RECORD ([Company]) End while $Object:=JSON Stringify array ($sel) $Object2:=JSON Stringify array ($sel2) // $Object = [{"name":"","country":""},{"name":"","country":""},...] // $Object2 = [{"name":"4d SAS","country":"France"},{"name":"4D, Inc","country":"USA"},{"name":"Catalan","country":"France"}...] OB Is defined OB Is defined ( object {; property} ) Boolean Parameter Type Description object Language object Structured object property Text If passed = property to check, if omitted = check object Function result Boolean If property omitted: True if object is defined, otherwise False. If property passed: True if property is defined, otherwise False The OB Is defined command returns True if object or property is defined, and False otherwise. object must have been created using the C_OBJECT command D v14 Upgrade

259 OB Is empty By default, if you omit the property parameter, the command checks whether the object is defined. An object is defined if its contents has been initialized. Note An object can be defined but empty. To find out if an object is undefined or empty, use the OB Is empty command. If you pass the property parameter, the command checks whether this property exists in object. Note that the property parameter is case sensitive. Syntax testing the initialization of an object: C_OBJECT ($object) $def:=ob Is defined ($object) // $def=false since $object is not initialized OB SET ($object;"name";"martin") OB REMOVE ($object;"name") $def2:=ob Is defined ($object) // $def2=true since $object is empty {} but has been initialized Test for existence of a property: C_OBJECT ($ref) OB SET ($ref;"name";"smith";"age";42) //... If (OB Is defined ($ref;"age")) //... End if This test is equivalent to: If (OB Get type ($Object;"name") # Is undefined) See also: OB Is empty OB Is empty OB Is empty ( object ) Boolean Parameter Type Description object Language object Structured object Function result Boolean True if object is empty or undefined, otherwise False The OB Is empty command returns True if object is undefined or empty, and False if object is defined (initialized) and contains at least one property. 4D v14 Upgrade 259

260 Chapter 6 Language object must have been created using the C_OBJECT command. Here are the different results of this command as well as the OB Is defined command, depending on the context: C_OBJECT ($ref) $empty:=ob Is empty ($ref) // True $def:=ob Is defined ($ref) // False OB SET ($ref;"name";"susie";"age";4) // $ref="{"name":"susie","age":4}" $empty:=ob Is empty ($ref) // False $def:=ob Is defined ($ref) // True OB REMOVE ($ref;"name") OB REMOVE ($ref;"age") $empty:=ob Is empty ($ref) // True $def:=ob Is defined ($ref) // True See also: OB Is defined OB Get OB Get ( object ; property {; type} ) Value Parameter Type Description object Language object Structured object property Text Name of property to read type Longint Type to which to convert the value Function result Text, Real, Boolean, Pointer, Date, Time, Language object Current value of property The OB Get command returns the current value of the property of the object, optionally converted into the type specified. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property to be read. Note that the property parameter is case sensitive D v14 Upgrade

261 OB Get By default, 4D returns the value of the property in its original type. You can "force" the typing of the value returned using the type parameter. To do this, you pass one of the following constants in type. These constants are found in the "Field and Variable Types" theme (new constants are added in this theme in 4D v14): Constant (value) Is real (1) Is text (2) Is date (4) Is boolean (6) Is longint (9) Is integer (8) Is integer 64 bits (25) Is string var (24) Is time (11) Is object (38) Object array (39) Is JSON null (255) The command returns the value of the property. Several types of data are supported. Note that: a pointer is returned as such; it can be evaluated using the JSON Stringify command, dates are returned in the format "\"YYYY-MM-DDTHH:mm:ssZ\"" in real values, the decimal separator is always a period "." times are returned as a number (seconds for 4D, milliseconds for JSON). Retrieving a text type value: Comments New in 4D v14 New in 4D v14 New in 4D v14 C_OBJECT ($ref) C_TEXT ($FirstName) OB SET ($ref;"firstname";"harry") $FirstName:=OB Get ($ref;"firstname") // $FirstName = "Harry" (text) Retrieving a real number value converted into a longint: OB SET ($ref ; "age" ; 42) $age:=ob Get ($ref ; "age") // $age is a real number (default) $age:=ob Get ($ref ; "age" ; Is longint) // $age is a longint 4D v14 Upgrade 261

262 Chapter 6 Language Retrieving the values of an object: C_OBJECT ($ref1;$ref2) OB SET ($ref1;"lastname";"smith") // $ref1={"lastname":"smith"} OB SET ($ref2;"son";$ref1) // $ref2={"son":{"lastname":"smith"}} $son:=ob Get ($ref2;"son") // $son={"lastname":"john"} (object) $sonsname:= OB Get ($son ;"name") // $sonsname="john" (text) Modifying the age of an employee twice: C_OBJECT ($ref_john;$ref_jim) OB SET ($ref_john;"name";"john";"age";35) OB SET ($ref_jim;"name";"jim";"age";40) APPEND TO ARRAY ($myarray;$ref_john) // we create an object array APPEND TO ARRAY ($myarray;$ref_jim) // we change the age for John from 35 to 25 OB SET ($myarray{1};"age";25) // We replace the age of "John" in the array For ($i;1;size of array ($myarray)) If (OB Get ($myarray{$i};"name")="john") OB SET ($myarray{$i};"age";36) // instead of 25 // $ref_john={"name":"john","age":36} End if End for Deserializing a data string formatted in ISO: C_OBJECT ($object) C_DATE ($birthday) C_TEXT ($birthdaystring) OB SET ($object;"birthday";" t12:00:00z") $birthdaystring:=ob Get ($object;"birthday") // $birthdaystring=" t12:00:00z" $birthday:=ob Get ($object;"birthday";is date) // $birthday=25/12/ D v14 Upgrade

263 OB GET ARRAY You can use nested objects: C_OBJECT ($ref1;$child;$children) C_TEXT ($childname) OB SET ($ref1;"firstname";"john";"lastname";"monroe") // {"FirstName":"john","LastName";"Monroe"} OB SET ($children;"children";$ref1) $child:=ob Get ($children;"children") // $son = {"FirstName":"John","LastName":"Monroe"} (object) $childname:=ob Get ($child;"lastname") // $childname = "Monroe" (text) // or $childname:=ob Get (OB Get ($children;"children");"lastname") // $childname = "Monroe" (text) OB GET ARRAY OB GET ARRAY ( object ; property ; array ) Parameter Type Description object Language object Structured object property Text Name of property to read array Text array, Real array, Boolean array, Object array, Pointer array Value array of property The OB GET ARRAY command retrieves, in array, the array of values stored in the property of the language object designated by the object parameter. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property to be read. Note that the property parameter is case sensitive. Given an object array defined in the example of the OB SET ARRAY command: 4D v14 Upgrade 263

264 Chapter 6 Language We want to retrieve these values: ARRAY OBJECT ($result;0) OB GET ARRAY ($Children;"Children";$result) We want to change a value in the first element of the array: // Change the value of "age": ARRAY OBJECT ($refs) OB GET ARRAY ($refemployees; " ENTITIES" ; $refs) OB SET ($refs{1}; "age" ; 25) See also: OB SET ARRAY OB GET PROPERTY NAMES OB GET PROPERTY NAMES ( object ; arrproperties {; arrtypes} ) Parameter Type Description object Language object Structured object arrproperties Text array Property names arrtypes Longint array Property types The OB GET PROPERTY NAMES command returns, in arrproperties, the names of the properties contained in the language object designated by the object parameter. object must have been defined using the C_OBJECT command. Pass a text array in the arrproperties parameter. If the array does not exist, the command creates and sizes it automatically D v14 Upgrade

265 OB GET PROPERTY NAMES Optionally, you can also pass a longint array in arrtypes. For each element of arrproperties, the command returns, in arrtypes, the type of value stored in the property. You can compare the values received with the following constants, found in the "Field and Variable Types" theme (new constants are added in this theme in 4D v14): Constant (value) Is real (1) Is text (2) Is undefined (5) Is boolean (6) Is string var (24) Is object (38) Object array (39) Is JSON null (255) You want to test that an object is not empty: ARRAY TEXT (arrnames;0) ARRAY LONGINT (arrtypes;0) C_OBJECT ($ref_richard) OB SET ($ref_richard;"name";"richard";"age";7) OB GET PROPERTY NAMES ($ref_richard;arrnames;arrtypes) // arrnames{1}="name", arrnames{2}="age" // arrtypes{1}=2, arrtypes{2}=1 If (Size of array (arrnames)#0) //... End if Using an object array element: Comments New in 4D v14 New in 4D v14 New in 4D v14 C_OBJECT ($Children;$ref_richard;$ref_susan;$ref_james) ARRAY OBJECT ($arraychildren;0) OB SET ($ref_richard;"name";"richard";"age";7) APPEND TO ARRAY ($arraychildren;$ref_richard) OB SET ($ref_susan;"name";"susan";"age";4) APPEND TO ARRAY ($arraychildren;$ref_susan) OB SET ($ref_james;"name";"james";"age";3) APPEND TO ARRAY ($arraychildren;$ref_james) 4D v14 Upgrade 265

266 Chapter 6 Language OB GET PROPERTY NAMES ($arraychildren{1};$arrnames;$arrtypes) OB Get type OB Get type ( object ; property ) Longint Parameter Type Description object Language object Structured object property Text Property name Function result Longint Property value type The OB Get type command returns the type of value associated with the property of the object. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property whose type you want to find out. Note that the property parameter is case sensitive. The command returns a longint indicating the type of value. You can compare this value with the following constants, found in the "Field and Variable Types" theme (new constants are added to this theme in 4D v14): Constant (value) Is real (1) Is text (2) Is undefined (5) Is boolean (6) Is string var (24) Is object (38) Object array (39) Is JSON null (255) Comments New in 4D v14 New in 4D v14 New in 4D v D v14 Upgrade

267 OB REMOVE We want to get the type of standard values: C_OBJECT ($ref) OB SET ($ref;"name";"smith";"age";42) $type:=ob Get type ($ref;"name") // $type returns 2 $type2:=ob Get type ($ref;"age") // $type2 returns 1 See also: OB GET PROPERTY NAMES OB REMOVE OB REMOVE ( object ; property ) Parameter Type Description object Language object Structured object property Text Name of property to remove The OB REMOVE command removes the property of the language object designated by the object parameter. This command removes the property as well as its current value. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property to be read. Note that the property parameter is case sensitive. You want to remove the "age" property of an object: C_OBJECT ($Object) OB SET ($Object;"name";"smith";"age";42;"client";True) // $Object={"name":"smith","age":42,"client":true} OB REMOVE ($Object;"age") // $Object={"name":"smith","client":true} OB SET OB SET ( object ; property ; value {; property2; value2;...; propertyn; valuen} ) Parameter Type Description object Language object Structured object property Text Name of property to set value Text, Real, Date, Boolean, Pointer, Null, Language object New value of property The OB SET command creates or modifies one or more property/value pairs in the language object designated by the object parameter. 4D v14 Upgrade 267

268 Chapter 6 Language object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property to be created or modified. If the property already exists in object, its value is updated. If it does not exist, it is created. Note that the property parameter is case sensitive. In the value parameter, pass the value you want to set for the property. Several data types are supported. Note that: if you pass a pointer, it is kept as is; it is evaluated using the JSON Stringify command, dates must be in the format "\"YYYY-MM-DDTHH:mm:ssZ\"" if you pass a language object, the command uses the object reference and not a copy. Creating an object and adding a text type property: C_OBJECT ($Object) OB SET ($Object ; "FirstName" ; "John" ; "LastName" ; "Smith") // $Object = {"FirstName":"John","LastName":"Smith"} Creating an object and adding a Boolean type property: C_OBJECT ($Object) OB SET ($Object ; "LastName";"smith";"age";42;"client";True) // $Object = {"LastName":"smith","age":42,"client":true} Modifying a property: // $Object = {"FirstName":"John","LastName":"Smith"} OB SET ($Object ; "FirstName";"Paul") // $Object = {"FirstName":"Paul","LastName":"Smith"} Adding a property: // $Object = {"FirstName":"John","LastName":"Smith"} OB SET ($Object ; "department";"accounting") // $Object = {"FirstName":"Paul","LastName":"Smith","department":"Accounting"} 268 4D v14 Upgrade

269 OB SET Renaming a property: C_OBJECT ($Object) OB SET ($Object ; "LastName";"James";"age";35) // $Object = {"LastName":"James","age":35} OB SET ($Object ; "FirstName";OB Get ($Object ; "LastName")) // $Object = {"FirstName":""James","nom":"James","age":35} OB REMOVE ($Object ; "LastName") // $Object = {"FirstName":""James","age":35} Using a pointer: // $Object = {"FirstName":"Paul","LastName":"Smith"} C_TEXT ($LastName) OB SET ($Object ; "LastName";->$LastName) // $Object = {"FirstName":"Paul","LastName":"->$LastName"} $JsonString:=JSON Stringify ($Object) // $JsonString="{"FirstName":"Paul","LastName":""} $LastName:="Wesson" $JsonString:=JSON Stringify ($Object) // $JsonString="{"FirstName":"Paul","LastName":"Wesson"} Using an object: C_OBJECT ($ref_smith) OB SET ($ref_smith ; "name" ; "Smith") C_OBJECT ($ref_emp) OB SET ($ref_emp ; "employee" ; $ref_smith) $Json_string := JSON Stringify ($ref_emp) // $ref_emp = {"employee":{"name":"smith"}} (object) // $Json_string = "{"employee":{"name":"smith"}}" (string) You can also change a value on the fly: OB SET ($ref_smith ; "name" ; "Smyth") // $ref_smith = {"employee":{"name":"smyth"}} $string:= JSON Stringify ($ref_emp) // $string = "{"employee":{"name":"smyth"}}" 4D v14 Upgrade 269

270 Chapter 6 Language Using an object array: C_TEXT ($jsonstring) C_OBJECT ($Contact) OB SET ($Contact;"FirstName";"Alan") OB SET ($Contact;"LastName";"Monroe") OB SET ($Contact;"age";40) OB SET ($Contact;"telephone";"[ , ]") $jsonstring:=json Stringify ($Contact) // Value of $Contact: // {"LastName":"Monroe","telephone":"[ , ]", // "age":40,"firstname":"alan"} // Value of $jsonstring: // "{"LastName":"Monroe","telephone":"[ , ]", // "age":40,"firstname":"alan"}" See also: OB SET NULL OB SET ARRAY OB SET ARRAY ( object ; property ; array }) Parameter Type Description object Language object Structured object property Text Name of property to set array Text array, Real array, Boolean array, Object array, Pointer array Array to store in property The OB SET ARRAY command defines the array to be associated with the property in the language object designated by the object parameter. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property to be created or modified. If the property already exists in object, its value is updated. If it does not exist, it is created. Note that the property parameter is case sensitive. In the array parameter, pass the array that must be passed as the property value. Several array types are supported. Note It is not possible to use two-dimensional arrays D v14 Upgrade

271 OB SET ARRAY Using a text array: C_OBJECT ($Children) ARRAY TEXT ($arrchildren;3) $arrchildren{1}:="richard" $arrchildren{2}:="susan" $arrchildren{3}:="james" OB SET ARRAY ($Children;"Children";$arrChildren) // Value of $Children = {"Children":["Richard","Susan","James"]} Adding an element to an array: ARRAY TEXT ($arrtext;2) $arrtext{1}:="smith" $arrtext{2}:="white" C_OBJECT ($Employees) OB SET ARRAY ($Employees;"Employees";$arrText) APPEND TO ARRAY ($arrtext;"brown") // Add to the 4D array // $Employees = {"Employees":["Smith","White"]} OB SET ARRAY ($Employees;"Employees";$arrText) // $Employees = {"Employees":["Smith","White","Brown"]} Using a text array with selection of an element: // $Employees = {"Employees":["Smith","White","Brown"]} OB SET ARRAY ($Employees ;"Manager";$arrText{1}) // $Employees = {"Employees":["Smith","White","Brown"],"Manager":["Smith"]} Using an object array: C_OBJECT ($Children;$ref_richard;$ref_susan;$ref_james) ARRAY OBJECT ($arrchildren;0) OB SET ($ref_richard;"name";"richard";"age";7) APPEND TO ARRAY ($arrchildren;$ref_richard) OB SET ($ref_susan;"name";"susan";"age";4) APPEND TO ARRAY ($arrchildren;$ref_susan) OB SET ($ref_james;"name";"james";"age";3) APPEND TO ARRAY ($arrchildren;$ref_james) // $arrchildren {1} = {"name":"richard","age":7} // $arrchildren {2} = {"name":"susan","age":4} // $arrchildren {3} = {"name":"james","age":3} 4D v14 Upgrade 271

272 Chapter 6 Language OB SET ARRAY ($Children;"Children";$arrChildren) // $Children = {"Children":[{"name":"Richard","age":7},{"name":"Susan", // "age":4},{"name":"james","age":3}]} Here is how the object appears in the debugger: See also: OB GET ARRAY OB SET NULL OB SET NULL ( object ; property ) Parameter Type Description object Language object Structured object property Text Name of property where null value is to be applied The OB SET NULL command stores the null value in the language object designated by the object parameter. object must have been defined using the C_OBJECT command. In the property parameter, pass the label of the property where you want to store the null value. If the property already exists in object, its value is updated. If it does not exist, it is created. Note that the property parameter is case sensitive. We want to put the null value in the "age" property for Lea: C_OBJECT ($ref) OB SET ($ref;"name";"lea";"age";4) // $ref = {"name":"lea","age":4}... OB SET NULL ($ref ; "age") // $ref = {"name":"lea","age":null} See also: OB SET 272 4D v14 Upgrade

273 Picture operators Picture operators The functioning of the exclusive superimposition (&) and inclusive superimposition ( ) operators was modified following the update of the display management libraries used in 4D. "&" operator (exclusive superimposition) The & operator now places one picture on top of the other: Pict3 := Pict1 & Pict2 This operator produces the same result as: COMBINE PICTURES ( pict3 ; pict1 ; Superimposition ; pict2 ) Note that Pict1&Pict2 does not produce the same result as Pict2&Pict1 : " " operator (inclusive superimposition) The operator now returns the mask resulting from superimposing two pictures of the same size. 4D v14 Upgrade 273

274 Chapter 6 Language Pict3 := Pict1 Pict2 This operator produces the same result as: $equal:=equal pictures ( Pict1 ; Pict2 ; Pict3 ) Note that Pict1 and Pict2 must have exactly the same dimension. If both pictures are a different size, the operation Pict1 Pict2 produces a blank picture: Printing OPEN PRINTING FORM In 4D v14, this command is moved to the "Forms" theme. In addition, it is renamed FORM LOAD and its operation is modified. For more information, refer to the description of this command D v14 Upgrade

275 Processes Processes Execute on server Execute on server ( procedure ; stack {; name {; param {; param2 ;... ; paramn}}}{; *} ) -> Function result If you pass a 4D object (C_OBJECT) as param or return value, the JSON form is used in UTF-8 for the server. If the C_OBJECT object contains pointers, their dereferenced values are sent, and not the pointers themselves. Quick Report QR REPORT QR REPORT ( {atable ;} document {; hierarchical {; wizard {; search {; methodname{; *}}}}} ) Parameter Type Description atable Table Table to use for the report, or Default table if omitted document String Quick Report document to load hierarchical Boolean True = Display related Many tables False or omitted = Do not display (default) wizard Boolean True = Display the wizard button False or omitted = Do not display (default) search Boolean True = Display the search tools and master table choice, False or omitted = Do not display (default) methodname String Name of method to call * Operator Deletion of printing dialog boxes A new optional methodname parameter can be passed to the QR REPORT command. This parameter designates a 4D project method that will be executed each time a command of the Quick Report editor is called by selecting a menu item or clicking on a button. Using this parameter with the QR REPORT command is equivalent to using QR ON COMMAND in the context of the Quick Report editor window (QR ON COMMAND only works within the context of an included area). 4D v14 Upgrade 275

276 Chapter 6 Language More particularly, you can use this new parameter to change the character set used by the quick report. The methodname method receives two parameters: $1 contains the area reference (longint). $2 contains the number of the command selected (longint). Note If you want to compile your database using the Compiler, you must declare the $1 and $2 parameters explicitly as longints, even if you do not use them. If you want to execute the initial command chosen by the user, use the following statement in the methodname method: QR EXECUTE COMMAND($1;$2). If the methodname parameter is an empty string ("") or is omitted, no method is called and the standard operation of QR REPORT is applied. You want to convert the character set used in a quick report called using QR REPORT into Mac Roman: QR REPORT([MyTable];Char(1);False;False;False;"myCallbackMeth") The mycallbackmeth method converts the report when it is generated: C_LONGINT ($1;$2) If ($2=qr cmd generate) //if we generated a report C_BLOB ($myblob) C_TEXT ($path;$text) QR EXECUTE COMMAND ($1;$2) //execution of command QR GET DESTINATION ($1;$type;$path) //retrieval of destination DOCUMENT TO BLOB ($path;$myblob) //conversion to text using UTF-8 $text:=convert to text ($myblob;"utf-8") //use of MacRoman set CONVERT FROM TEXT ($text;"macroman";$myblob) //Return of converted report BLOB TO DOCUMENT ($path;$myblob) Else //otherwise, execution of the command QR EXECUTE COMMAND ($1;$2) End if 276 4D v14 Upgrade

277 QR SET DESTINATION QR SET DESTINATION QR SET DESTINATION ( area ; type {; specifics} ) Since 4D Chart is no longer supported starting with 4D v14 (see the Removed functions paragraph on page 17), you can no longer pass a 4D Chart area as a quick report destination. The qr 4D Chart area constant has been renamed _O_qr 4D Chart area and must no longer be used. Spell Checker The spell checker interface and functions are enhanced in 4D v14 with, more particularly, support for the native OS X spell checker (however, the "Cordial" spell checker is no longer supported). For more information, refer to the Spell checking paragraph on page 84. The following commands of the "Spell Checker" theme have also been modified. Note A new option lets you designate the spell checker to use under OS X using the SET DATABASE PARAMETER, Get database parameter commands. SPELL CHECK TEXT SPELL CHECK TEXT ( text ; errpos ; errlength ; checkpos ; arrsuggest ) Under OS X when the native spell checker is enabled, this command does not support grammar correction. SPELL GET DICTIONARY LIST SPELL SET CURRENT DICTIONARY SPELL GET DICTIONARY LIST ( langid ; langfiles ; langnames ) This command no longer returns references to Cordial dictionaries. SPELL SET CURRENT DICTIONARY {( dictionary )} In 4D v14, Cordial dictionaries are no longer supported. By default, 4D now uses: on Windows, the Hunspell dictionary, on OS X only, the native spell checker. 4D v14 Upgrade 277

278 Chapter 6 Language For compatibility, it is still possible to pass a "Cordial" dictionary number in the dictionary parameter (value or constant from the "Dictionaries" theme). In this case, however, the dictionary is redirected internally to an equivalent Hunspell dictionary (or the native dictionary under OS X). Note that in all cases, SPELL GET DICTIONARY LIST and SPELL Get current dictionary no longer return references to Cordial dictionaries. This command now accepts as parameter a BCP 47, ISO or ISO language code. For example, with the BCP 47 language code "en- US" indicates American English and "en-gb" specifies British English. These codes are redirected internally to the corresponding current dictionary (Hunspell or native OS X). String String String ( expression {; format {; addtime}} ) String With null dates, the Internal date short date display format produces a result where the year is displayed with 4 zeros as follows: 00/00/0000 In previous versions of 4D, the year was displayed with 2 zeros. Structure Access PAUSE INDEXES PAUSE INDEXES ( atable ) Parameter Type Description atable Table Table for which to pause indexes The new PAUSE INDEXES command temporarily disables all the indexes of atable, except for the index of the primary key. The indexes are not physically deleted from the data (.4DIndx file) or the structure of the database (_USER_INDEXES system table), but they are rendered invalid and are thus no longer updated. When indexes are disabled, all the operations performed on atable (queries, sorts, record additions, modifications and deletions) no longer use the indexes D v14 Upgrade

279 RESUME INDEXES This command is mainly useful when you are importing or modifying large amounts of data in tables that have several indexes. Since 4D must update the indexes each time a record is validated, the operation could take a considerable amount of time. Disabling the indexes beforehand can significantly speed up the operation. To resume the indexes after the operation is over, you can just call the new RESUME INDEXES command for atable. Note You can obtain a similar result by using the CREATE INDEX and DELETE INDEX commands, but you will have to call them for each index of atable. If you call the PAUSE INDEXES command for a table and then quit the database without having called the RESUME INDEXES command for this table, all this table s indexes are automatically rebuilt when the database is restarted. Note This command cannot be executed from a 4D remote. Example of method for importing large amounts of data: PAUSE INDEXES ([Articles]) IMPORT DATA ("HugeImport.txt") // Importing RESUME INDEXES ([Articles]) See also: RESUME INDEXES RESUME INDEXES RESUME INDEXES ( atable {; *} ) Parameter Type Description atable Table Table for which to resume indexes * Operator If passed = asynchronous indexing The new RESUME INDEXES command resumes all the indexes of atable when they have been paused previously using the PAUSE INDEXES command. If the indexes of atable have not been paused, this command does nothing. 4D v14 Upgrade 279

280 Chapter 6 Language In most cases, executing this command triggers the rebuilding of the indexes for atable. If you pass the optional * parameter, the rebuilding of the indexes is performed in asynchronous mode. This means that the method calling the command continues its execution after this call, regardless of whether the indexing is finished or not. If you omit this parameter, the rebuilding of the indexes blocks the execution of the method until the rebuilding operation is completed. The RESUME INDEXES command can only be called from 4D Server or a local 4D. If this command is executed from a remote 4D machine, the error is generated. This error can be intercepted using a method installed by the ON ERR CALL command. See also: PAUSE INDEXES Styled Text The new "Styled Text" theme contains the language commands used for managing and modifying multi-style text areas, also known as rich text areas. Commands concerning multi-style text that were previously found in the "Object Properties" have been prefixed and included in this new theme (see the Renamed commands paragraph on page 303) along with new commands that have been added. As a reminder, you declare a rich text area by enabling its Multi-style option in the Property List. In 4D v14, new tags and attributes are available in rich text areas. For more information, refer to the Multistyle areas paragraph on page 55. Note You can use the new OBJECT Is styled text command ("Objects (Forms)" theme) to find out whether or not a text area is in multi-style mode D v14 Upgrade

281 ST COMPUTE EXPRESSIONS New commands ST COMPUTE EXPRESSIONS ST COMPUTE EXPRESSIONS ( {*; } object {; startsel {; endsel} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) startsel Longint Start of selection endsel Longint End of selection The ST COMPUTE EXPRESSIONS command updates the dynamic 4D expressions found in the styled text field or variable designated by the object parameter. For more information about 4D expressions used in multi-style text areas, refer to the description of the ST INSERT EXPRESSION command on page 293. The command re-evaluates the result of expressions found in the object based on the current context and displays the result obtained. For example, if the expression inserted is the time, the value will be modified each time the ST COMPUTE EXPRESSIONS command is called. Expressions are also computed: when they are inserted when the object is loaded when they are "frozen" using the ST FREEZE EXPRESSIONS command, if the second * parameter is passed. ST COMPUTE EXPRESSIONS does not modify styled text (containing span tags) but only plain text displayed in object. The values computed are not stored in the styled text, only their reference is stored there. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). It is not necessary for the object to have the focus; however, the object must be included in a form, or else the ST COMPUTE EXPRESSIONS command has no effect. 4D v14 Upgrade 281

282 Chapter 6 Language The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags or references that may be present. Note that a reference is equivalent to a single character. If you pass startsel and endsel, ST COMPUTE EXPRESSIONS only updates the expressions located within this selection. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, all the expressions between startsel and the end of the text are computed. If you omit startsel and endsel, all the expressions included in the user selection of the object are computed. 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) Comments ST Start highlight (-1000) Designates first character of current text selection in object (*) ST End highlight (-1001) Designates last character of current text selection in object (*) ST Start text (1) Designates first character of text contained in object ST End text (0) Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. You want to update the references included in the selection of text: ST COMPUTE EXPRESSIONS (*;"mytext";st Start highlight;st End highlight) See also: ST FREEZE EXPRESSIONS 282 4D v14 Upgrade

283 ST FREEZE EXPRESSIONS ST FREEZE EXPRESSIONS ST FREEZE EXPRESSIONS ( {*; } object {; startsel {; endsel}} {; *} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) startsel Longint Start of selection endsel Longint End of selection * Operator If passed = update expressions before freezing them The ST FREEZE EXPRESSIONS command "freezes" the contents of expressions found in the styled text field or variable designated by the object parameter. This action converts dynamic expressions into static text and removes the associated references from the object. For more information about 4D expressions used in multi-style text areas, refer to the description of the ST INSERT EXPRESSION command on page 293. The ST FREEZE EXPRESSIONS command stores the computed value of an expression at a given time. This operation is necessary particularly before each use of the object outside of a multi-style area (exports, storage in a disk file, printing, etc.) since only the reference of the expression is kept in the area itself. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags or references that may be present. If you pass startsel and endsel, ST FREEZE EXPRESSIONS only freezes the expressions located within this selection. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, all the expressions between startsel and the end of the text are frozen. 4D v14 Upgrade 283

284 Chapter 6 Language If you omit startsel and endsel, all the expressions included in the user selection of the object are frozen. 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) Comments ST Start highlight (-1000) Designates first character of current text selection in object (*) ST End highlight (-1001) Designates last character of current text selection in object (*) ST Start text (1) Designates first character of text contained in object ST End text (0) Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. By default, expressions are not re-evaluated before they are frozen. If you want the expression to be recomputed and then frozen, you can pass the second * parameter You want to insert the current time at the start of the text and then freeze it before saving the record: // Inserting the time at the start of the text ST INSERT EXPRESSION (*;StyledText_t;"Current time";1) // We freeze the expression ST FREEZE EXPRESSIONS (*;StyledText_t;1) See also: ST INSERT EXPRESSION, ST COMPUTE EXPRESSIONS 284 4D v14 Upgrade

285 ST Get content type ST Get content type ST Get content type ( {* ;} object {; startsel {; endsel {; startblock {; endblock}}}} ) Longint Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) startsel Longint Start of selection endsel Longint End of selection startblock Longint Start position of first type of selection endblock Longint End position of first type of selection Function result Longint Type of content The ST Get content type command returns the type of content found in the styled text field or variable designated by the object parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). During execution, if the object has the focus, the command returns the information of the object being edited; if the object does not have the focus, the command returns the information of the object s data source (variable or field). If you omit the * parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string. During execution, the command returns the information of the variable or field. The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags that may be present. If you pass startsel and endsel, ST Get content type evaluates the contents within this selection. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, the contents between startsel and the end of the text is evaluated. If you omit startsel and endsel, the contents within the current text selection is evaluated. 4D v14 Upgrade 285

286 Chapter 6 Language 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) ST Start highlight (-1000) ST End highlight (-1001) ST Start text (1) ST End text (0) Comments Designates first character of current text selection in object (*) Designates last character of current text selection in object (*) Designates first character of text contained in object Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. The optional startblock and endblock parameters retrieve the position of the first and last character of the first homogenous block identified in the object or the selection of the object. For example, if the selection contains an expression and then plain text, startblock and endblock will return the limits of the expression. You can make a loop to process all the blocks of the selection. This command returns a value designating the type of contents identified. You can compare this value with the following constants, found in the "Multistyle Text" theme: Constant (value) Comments ST Plain type (0) Selection contains text and no references ST Url type (1) Selection contains only a URL reference ST Expression type (2) Selection contains only an expression reference ST Mixed type (3) Selection contains at least two different types of contents ST Unknown tag type (4) Selection contains only an unknown tag type ST User type (5) Selection contains only a custom reference 286 4D v14 Upgrade

287 ST Get content type You want to display context-menu commands based on the type of contents selected in the area. Case of : (Form event=on Clicked) // we retrieve the selection GET HIGHLIGHT (*;"mytext";startsel;endsel) If (Contextual click & (Macintosh control down=false)) // calls the context menu If (startsel=endsel) // no contents selected // we enable only certain commands DISABLE MENU ITEM (<>menu_styledtext;2) DISABLE MENU ITEM (<>menu_styledtext;4) ENABLE MENU ITEM (<>menu_styledtext;6)... Else // we get the content type CT_Texttype:=ST Get content type (*;"mytext";startsel;endsel) Case of // processing of different types : (CT_Texttype=ST Url Type) DISABLE MENU ITEM (<>menu_styledtext;6) ENABLE MENU ITEM (<>menu_styledtext;7)... : (CT_Texttype=ST Expression Type) DISABLE MENU ITEM (<>menu_styledtext;6) DISABLE MENU ITEM (<>menu_styledtext;7)... Else ENABLE MENU ITEM (<>menu_styledtext;6) DISABLE MENU ITEM (<>menu_styledtext;7)... End case End if GET MOUSE ($xcoord;$ycoord;$buttonstate) $AlphaVar:=Dynamic pop up menu (<>menu_styledtext;""; $xcoord;$ycoord) startsel:=-3 endsel:=-3 End if... End case 4D v14 Upgrade 287

288 Chapter 6 Language ST Get expression ST Get expression ( {* ;} object {; startsel {; endsel}} ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) startsel Longint Start of selection endsel Longint End of selection Function result Text Expression label The ST Get expression command returns the first expression found in the current selection of the styled text field or variable designated by the object parameter. The command returns the label of the expression as it was inserted into the object (for example "mymethod" or "[table1]field1"). The current value of the expression is not returned. Passing the optional * parameter indicates that the object parameter is an object name (string). During execution, if the object has the focus, the command returns the information of the object being edited; if the object does not have the focus, the command returns the information of the object s data source (variable or field). If you omit the * parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string. During execution, the command returns the information of the variable or field. The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags that may be present. If you pass startsel and endsel, ST Get expression looks for the expression within this selection. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, the command looks for the expression between startsel and the end of the text. If you omit startsel and endsel, the command looks for the expression within the current text selection D v14 Upgrade

289 ST Get expression 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) Comments ST Start highlight (-1000) Designates first character of current text selection in object (*) ST End highlight (-1001) Designates last character of current text selection in object (*) ST Start text (1) Designates first character of text contained in object ST End text (0) Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. If there is no expression found in the selection, the command returns an empty string. When there is a double-click event, you check that there is in fact an expression, and if so, you display a dialog where you have retrieved its values so that the user can modify them: Case of : (Form event=on Double Clicked) GET HIGHLIGHT (*;"StyledText_t";startSel;endSel) If (ST Get content type (*;"StyledText_t";startSel;endSel)= ST Expression Type) vexpression:=st Get expression (*;"StyledText_t";startSel;endSel) $winref:=open form window ("Dial_InsertExpr"; Movable form dialog box;horizontally Centered; Vertically Centered;*) DIALOG ("Dial_InsertExpr") 4D v14 Upgrade 289

290 Chapter 6 Language If (OK=1) ST INSERT EXPRESSION (*;"StyledText_t";vExpression;startSel; endsel) HIGHLIGHT TEXT (*;"StyledText_t";startSel;endSel) End if End if End case You want to execute a 4D method when a user link is clicked: Case of : (Form event=on Clicked) //we retrieve the selection HIGHLIGHT TEXT(*;"myText";startSel;endSel) If (startsel#endsel) //there is selected content //we get the content type $CT_type:=ST Get content type(*;"mytext";startsel;endsel) If ($CT_type=ST User type) //this is a user link MyMethod //we execute a 4D method End if End if End case See also: ST INSERT EXPRESSION ST GET OPTIONS ST GET OPTIONS ( {*; } object; option; value {; option2; value2;...; optionn; valuen} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) option Longint Option to get value Longint Current value of option The ST GET OPTIONS command gets the current value of one or more operating options for the styled text field or variable designated by the object parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). During execution, if the object has the focus, the command returns the information of the object being edited; if the object does not have the focus, the command returns the information of the object s data source (variable or field) D v14 Upgrade

291 ST GET URL If you omit the * parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string. During execution, the command returns the information of the variable or field. Pass the code of the option to get in the option parameter. The command returns the current value of this option in value. For both these parameters, you can use the following constants, found in the "Multistyle Text" theme: Constant (value) Comments ST Expressions display mode (1) You can pass as value: ST Values (0): displays computed values of expressions (default) ST References (1): displays source strings of expressions Refer to the example for the ST SET OPTIONS command. See also: ST SET OPTIONS ST GET URL ST GET URL ( {*; } object ; urltext ; urladdress {; startsel {; endsel}} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) urltext Text Visible text of URL urladdress Text URL address startsel Longint Start of selection endsel Longint End of selection The ST GET URL command returns the label and address of the first URL detected in the styled text field or variable designated by the object parameter. The text label and address are returned in the urltext and urladdress parameters. If the selection does not contain a URL, empty strings are returned in these parameters. 4D v14 Upgrade 291

292 Chapter 6 Language Passing the optional * parameter indicates that the object parameter is an object name (string). During execution, if the object has the focus, the command returns the information of the object being edited; if the object does not have the focus, the command returns the information of the object s data source (variable or field). If you omit the * parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string. During execution, the command returns the information of the variable or field. The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags that may be present. If you pass startsel and endsel, ST GET URL looks for the URL within this selection. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, the command looks for the URL between startsel and the end of the text. If you omit startsel and endsel, the command looks for the URL within the current text selection. 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) Comments ST Start highlight (-1000) Designates first character of current text selection in object (*) ST End highlight (-1001) Designates last character of current text selection in object (*) ST Start text (1) Designates first character of text contained in object ST End text (0) Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to D v14 Upgrade

293 ST INSERT EXPRESSION When there is a double-click event, you check that there is in fact an URL, and if so, you display a dialog where you have retrieved its values so that the user can modify them: Case of : (Form event=on Double Clicked) GET HIGHLIGHT (*;"StyledText_t";startSel;endSel) If (ST Get content type (*;"StyledText_t";startSel;endSel)=ST Url Type) //URL ST GET URL(*;"StyledText_t";vTitle;vURL;startSel;endSel) $winref:=open form window ("Dial_InsertURL"; Movable form dialog box;horizontally Centered; Vertically Centered;*) SET WINDOW TITLE ("URL settings") DIALOG ("Dial_InsertURL") If (OK=1) ST INSERT URL (*;"StyledText_t";vTitle;vURL;startSel;endSel) HIGHLIGHT TEXT (*;"StyledText_t";startSel;startSel+1) End if End if End case See also: ST INSERT URL ST INSERT EXPRESSION ST INSERT EXPRESSION ( {*; } object ; expression {; startsel {; endsel}} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) expression Text Expression and (optional) format to insert startsel Longint Start of selection endsel Longint End of selection The ST INSERT EXPRESSION command inserts a reference to the expression in the styled text field or variable designated by the object parameter. 4D v14 Upgrade 293

294 Chapter 6 Language Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the expression parameter, you pass the 4D expression to evaluate in the object. A valid 4D expression is a string returning a value. expression can be a field, a variable, a 4D command, a statement returning a value, a project method, etc. The expression must be placed in quotation marks (""). Note The expression parameter cannot be a Picture type variable. If expression returns a value containing carriage returns and tabs, 4D formats the text according to the object hosting the expression; carriage return characters are interpreted as line breaks. You can format the expression by including formatting information in the expression parameter. In this case, the parameter must be in the form: "String(value;format)"... where value contains the expression itself and format contains the format to apply. The format parameter can have the following values: for numbers: any number display format (existing or not), for example "###,##" for dates: a number designating an existing date format. You can use the constants of the "Date display formats" theme, for example System date short. for times: a number designating an existing time format. You can use the constants of the "Time Display Formats" theme, for example System time short. For example: "String([Table_1]Field_1;System date short)" By default, the expression values are displayed in the multi-style text areas. You can force the display of the references instead using the new ST SET OPTIONS command D v14 Upgrade

295 ST INSERT EXPRESSION The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags that may be present. If you pass startsel and endsel, ST INSERT EXPRESSION replaces the text in this selection with the result of the expression. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, all the characters between startsel and the end of the text are replaced by the result of the expression. If you omit startsel and endsel, the result of the expression replaces the current text selection in the object, or is inserted at the location of the cursor. 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) Comments ST Start highlight (-1000) Designates first character of current text selection in object (*) ST End highlight (-1001) Designates last character of current text selection in object (*) ST Start text (1) Designates first character of text contained in object ST End text (0) Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. You want to replace the highlighted text with the result of a project method: ST INSERT EXPRESSION (*;"mytext";"mymethod";st Start highlight;st End highlight) See also: ST INSERT URL, ST Get expression 4D v14 Upgrade 295

296 Chapter 6 Language ST INSERT URL ST INSERT URL ( {*; } object ; urltext ; urladdress {; startsel {; endsel}} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) urltext Text Visible text of URL urladdress Text URL address startsel Longint Start of selection endsel Longint End of selection The ST INSERT URLcommand inserts a URL link in the styled text field or variable designated by the object parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). In the urltext parameter, pass the visible text of the URL, as it must appear in the object. For example, text labels such as "4D Web Site" or "Follow this link for more information" can be used. You can also use the address itself, for instance " In the urladdress parameter, pass the complete address you want the browser page to connect to, for example " The optional startsel and endsel parameters designate a selection of text in object. The startsel and endsel values express a plain text selection, without taking into account any style tags that may be present. If you pass startsel and endsel, ST INSERT URL replaces the text in this selection with the urltext. If you only pass startsel or if the value of endsel is greater than the total number of characters in object, all the characters between startsel and the end of the text are replaced with the urltext. If you omit startsel and endsel, urltext replaces the current text selection in the object, or is inserted at the location of the cursor D v14 Upgrade

297 ST INSERT URL 4D v14 provides predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) ST Start highlight (-1000) ST End highlight (-1001) ST Start text (1) ST End text (0) Comments Designates first character of current text selection in object (*) Designates last character of current text selection in object (*) Designates first character of text contained in object Designates last character of text contained in object (*) You must pass an object name in object to be able to use this constant. If you pass a reference to a field or variable, the command is applied to all the text of the object. Note If startsel is greater than endsel (except when endsel is 0), the command does nothing and the OK variable is set to 0. Once the link is inserted, it is active: using Ctrl+click (Windows) or Command+click (OS X) on its label opens a page of the default browser at the address specified in the urladdress parameter. You want to insert a link to the 4D Web site to replace the text selected in the object: vtitle:="4d Web Site" vurl:=" ST INSERT URL (*;"mytext";vtitle;vurl;st Start highlight;st End highlight) See also: ST INSERT EXPRESSION 4D v14 Upgrade 297

298 Chapter 6 Language ST SET OPTIONS ST SET OPTIONS ( {*; } object; option; value {; option2; value2;...; optionn; valuen} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) option Longint Option to set value Longint New value of option The ST SET OPTIONS command modifies one or more operating options for the styled text field or variable designated by the object parameter. Passing the optional * parameter indicates that the object parameter is an object name (string). If you do not pass this parameter, it indicates that the object parameter is a field or variable. In this case, you pass a field or variable reference instead of a string (field or variable object only). Pass the code of the option to modify in option and its new value in value. For both of these parameters, you can use the following constants from the "Multistyle Text" theme: Constant (value) ST Expressions Display Mode (1) Comments You can pass as value: ST Values (0): display computed values of expressions (default) ST References (1): display source strings of expressions Display of values: Display of expressions 298 4D v14 Upgrade

299 ST Get plain text Modified command The following code lets you switch the display mode of the area: ST GET OPTIONS (*;"StyledText_t";ST Expressions Display Mode;$exprValue) If ($exprvalue=1) ST SET OPTIONS (*;"StyledText_t";ST Expressions Display Mode; ST Values) Else ST SET OPTIONS (*;"StyledText_t";ST Expressions Display Mode; ST References) End if See also: ST GET OPTIONS ST Get plain text ST Get plain text ( {* ;} object {; refmode} ) Text Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a field or variable object Form object Object name (if * is specified) or Field or variable (if * is omitted) refmode Longint Mode for handling references found in the text Function result Text Text without tags Compatibility note This command was named OBJECT Get plain text in previous versions of 4D (see the Renamed commands paragraph on page 303). The ST Get plain text command now accepts an optional parameter, refmode, used to indicate the way that references found in object must be returned. 4D v14 Upgrade 299

300 Chapter 6 Language In refmode, pass one of the following constants, found in the "Multistyle Text" theme (you can pass a single constant or a combination): Constant (value) ST References as spaces (0) ST 4D Expressions as values (1) ST 4D Expressions as sources (2) ST URL as labels (4) ST URL as links (8) ST User links as labels (16) ST User links as links (32) ST Tags as plain text (64) ST Tags as XML code (128) ST Text displayed with 4D Expression values (85) ST Text displayed with 4D Expression sources (86) Comments Each reference is returned as a non-breaking space character (default operation, used by other commands) 4D expression references are returned in their evaluated form (default functioning in forms) The original string of 4D expression references is returned The visible label of URLs is returned, for example "Visit our Web site" (default functioning in forms) The link is returned, for example " The visible label of the user link is returned (default functioning in forms) The contents of the user link is returned The label of the tag is returned in plain text. For example for the tag '<img src="test.jpg" alt= "picture">my picture</img>', the plain text is "my picture" (default functioning in forms) The XML code of the tag is returned in plain text. For example for the tag '<img src="test.jpg" alt="picture">my picture</img>', the plain text is '<img src="test.jpg" alt="picture">my picture</img>' Returns the text as it is shown in the forms with the 4D expressions in their evaluated form. Corresponds to a predefined combination of constants Returns the text as it is shown in the forms with the original string of the 4D expressions. Corresponds a predefined combination of constants Note Since plain text remains the same regardless of the values passed in the refmode parameter, the optional refmode parameter is only useful when the text contains references D v14 Upgrade

301 ST Get plain text Given the following text placed in the multi-style area entitled "MyArea": <span>it is now <span style="-d4-ref:'current time:c178'"> </span> <a href=" to the 4D site</a> or <span style="-d4-refuser:'openw'">open a window</span></span> This text is displayed: If you execute the following code: $txt := ST Get plain text (*;"myarea";st References as spaces) // $txt = "It is now or " (spaces) $txt := ST Get plain text (*;"myarea";st 4D Expressions as values) // $txt = "It is now 15:48:19 or " $txt := ST Get plain text (*;"myarea";st 4D Expressions as sources) // $txt = "It is now Current time or " $txt := ST Get plain text (*;"myarea";st URL as links) //$txt = "It is now or " $txt := ST Get plain text (*;"myarea";st Text displayed with 4D Expression values) //$txt = "It is now 15:48:19 Go to the 4D site or Open a window" $txt := ST Get plain text (*;"myarea";st Text displayed with 4D Expression sources) //$txt = "It is now Current time Go to 4D site or Open a window" $txt := ST Get plain text(*;"myarea";st User links as labels) //$txt = "It is now or Open a window" $txt := ST Get plain text(*;"myarea";st User links as links) //$txt = "It is now or openw" Automatic normalization of line endings In order to ensure greater multi-platform compatibility of texts handled in the database, beginning with v14, 4D automatically normalizes line endings so that they occupy a single character: '\r'. This is carried out at the level of the form objects (variables or fields) hosting plain or multi-style text. Line endings that are not native, or that use a mix of several characters (for example '\r\n'), are considered as a single '\r'. Note that in compliance with the XML standard (multi-style text format), the multi-style text commands also normalize line endings for text variables that are not associated with objects (same functioning as previous versions of 4D). 4D v14 Upgrade 301

302 Chapter 6 Language This principle makes it easier to use multistyle text commands or commands such as HIGHLIGHT TEXT in a multi-platform context. However, you must take this into account in your processing when you work with texts from heterogeneous sources. Using constants for selection limits 4D v14 provides new predefined constants so that you can designate the selection limits automatically in the startsel and endsel parameters. These constants are found in the "Multistyle Text" theme: Constant (value) ST Start highlight (-1000) ST End highlight (-1001) ST Start text (1) ST End text (0) Comments Designates first character of current text selection in object (object syntax only) Designates last character of current text selection in object (object syntax only) Designates first character of text contained in object Designates last character of text contained in object These constants can be used with all the commands that manage multi-style text, including the existing commands: ST SET ATTRIBUTES, ST GET ATTRIBUTES, ST SET TEXT and ST Get text (these commands are renamed in 4D v14, see the Renamed commands paragraph on page 303). Note that the ST Start highlight or ST End highlight constants only work with the object syntax (you must pass the * parameter and an object name in object). Given a [Table_1]StyledText field displayed in a form. The object has the Multistyle property and is named "StyledText_t". You want to get the highlighted text as well as the status of the Bold style attribute. You can proceed in two different ways depending on whether you use the object name or the field reference. - Using the object name: $text:=st Get text (*;"StyledText_t";ST Start highlight;st End highlight) ST GET ATTRIBUTES (*;"StyledText_t";ST Start highlight;st End highlight;attribute bold style;$bold) 302 4D v14 Upgrade

303 System Documents - Using the field name: GET HIGHLIGHT ([Table_1]StyledText;$Begin_l;$End_l) $text:=st Get text ([Table_1]StyledText;$Begin_l;$End_l) ST GET ATTRIBUTES ([Table_1]StyledText;$Begin_l;$End_l;Attribute bold style;$bold) Renamed commands The following commands were found in the "Object Properties" theme in previous versions of 4D. They were moved into the new "Multistyle Text" theme and renamed in 4D v14. Except in the case of the ST Get plain text command, their operation is unchanged. Names in 4D v14 ST Get plain text ST SET ATTRIBUTES ST GET ATTRIBUTES ST SET TEXT ST Get text ST SET PLAIN TEXT Former names (4D v13.x) OBJECT Get plain text OBJECT SET STYLED TEXT ATTRIBUTES OBJECT GET STYLED TEXT ATTRIBUTES OBJECT SET STYLED TEXT OBJECT Get styled text OBJECT SET PLAIN TEXT System Documents COPY DOCUMENT COPY DOCUMENT ( sourcename ; destinationname{; newname}{; *} ) Parameter Type Description sourcename String Pathname of file or folder to be copied destinationname String Name or pathname of copied file or folder newname String New name of copied file or folder * Operator Override existing document if any The COPY DOCUMENT command accepts a new optional newname parameter that renames the copied document in its destination location (file or folder). When it is passed in the context of copying a file, this parameter replaces the name (if any) passed in the destinationname parameter. 4D v14 Upgrade 303

304 Chapter 6 Language The following examples illustrate how the new parameter works (examples under Windows): COPY DOCUMENT( "folder1\\name1" ; "folder2\\") //creates the "folder2/name" file COPY DOCUMENT( "folder1\\name1" ; "folder2\\" ; "new") //creates the "folder2/new" file COPY DOCUMENT( "folder1\\name1" ; "folder2\\name2") //creates the "folder2/name2" file COPY DOCUMENT( "folder1\\name1" ; "folder2\\name2" ; "new") //creates the "folder2/new" file (name2 is ignored) COPY DOCUMENT( "folder1\\" ; "folder2\\") //creates the "folder2/folder1/" folder COPY DOCUMENT( "folder1\\" ; "folder2\\" ; "new") //creates the "folder2/new/" folder Document to text Document to text ( filename {; charset{; breakmode}} ) Text Parameter Type Description filename String Document name or Pathname to document charset Text Longint Name or Number of character set breakmode Longint Processing mode for line breaks Function result Text Text from the document The new Document to text command lets you retrieve the contents of a file directly on disk in a 4D text variable or text field. In filename, pass the name or pathname of the file to be read. The file must exist on the disk, otherwise an error is generated. You can pass: just the file name, for example "myfile.txt": in this case, the file must be located next to the structure file of the application. a pathname relative to the structure file of the application, for example "\\docs\\myfile.txt" under Windows or ":docs:myfile.txt" under OS X. an absolute pathname, for example "c:\\app\\docs\\myfile.txt" under Windows or "MacHD:docs:myFile.txt" under OS X D v14 Upgrade

305 Document to text In charset, you pass the character set to be used for reading the contents. You can pass a string containing the standard set name (for example ISO or UTF-8 ) or its MIBEnum ID (longint). For more information about the list of character sets supported by 4D, refer to the description CONVERT FROM TEXT command in the 4D Language Reference manual. If the document contains a Byte Order Mark (BOM), 4D uses the character set that it has set instead of the one specified in charset (this parameter is then ignored). If the document does not contain a BOM and if the charset parameter is omitted, by default 4D uses the following character sets: under Windows: ANSI under OS X: MacRoman In breakmode, you can pass a longint indicating the processing to apply to end-of-line characters in the document. You can pass one of the following constants, found in the "System Documents" theme: Constant (value) Document unchanged (0) Document with native format (1) Document with CRLF (2) Document with CR (3) Document with LF (4) Description No processing (Default) Line breaks are converted to the native format of the operating system: CR (carriage return under OS X), CRLF (carriage return + line feed under Windows) Line breaks are converted to Windows format: CRLF (carriage return + line feed) Line breaks are converted to OS X format: CR (carriage return) Line breaks are converted to Unix format: LF (line feed) By default, when you omit the breakmode parameter, line breaks are processed in native mode (1). Note This command does not modify the OK variable. In case of failure, an error is generated that you can intercept using a method installed by the ON ERR CALL command. 4D v14 Upgrade 305

306 Chapter 6 Language Given the following text document (fields are separated by tabs): id name price vat 3 4D Tags When you execute this code: $Text:=Document to text ("products.txt")... you get: // $Text = "id\tname\tprice\tvat\r\n3\t4d Tags\t99 \t19.6" // \t = tab // \r = CR See also: TEXT TO DOCUMENT TEXT TO DOCUMENT TEXT TO DOCUMENT ( filename; text{; charset{; breakmode}} ) Parameter Type Description filename String Document name or Pathname to document text Text Text to store in the document charset Text Longint Name or Number of character set breakmode Longint Processing mode for line breaks The new TEXT TO DOCUMENT command lets you write the text directly to a disk file. In filename, pass the name or pathname of the file to be written. If this file does not exist, it is created. When this file already exists on the disk, its prior contents are erased, except if it is already open, in which case, its contents are locked and an error is generated. In filename, you can pass: just the file name, for example "myfile.txt": in this case, the file is placed next to the structure file of the application. a pathname relative to the structure file of the application, for example "\\docs\\myfile.txt" under Windows or ":docs:myfile.txt" under OS X. an absolute pathname, for example "c:\\app\\docs\\myfile.txt" under Windows or "MacHD:docs:myFile.txt" under OS X D v14 Upgrade

307 TEXT TO DOCUMENT If you want the user to be able to indicate the name or location of the document, use the Open document or Create document commands, as well as the Document system variable. Note By default, documents generated by this command do not have an extension. You must pass an extension in filename. You can also use the SET DOCUMENT TYPE command. In text, pass the text to write to the disk. It can be a literal constant ("my text"), or a 4D text field or variable. In charset, you pass the character set to be used to write the document. You can pass a string containing the standard set name (for example ISO or UTF-8 ) or its MIBEnum ID (longint). For more information about the list of character sets supported by 4D, refer to the description of the CONVERT FROM TEXT command in the 4D Language Reference manual. If a Byte Order Mark (BOM) exists for the character set, 4D inserts it into the document. If you do not specify a character set, by default 4D uses the "UTF_8" character set and a BOM. In breakmode, you can pass a longint indicating the processing to apply to end-of-line characters before saving them in the file. You can pass one of the following constants, found in the "System Documents" theme: Constant (value) Description Document unchanged (0) No processing Document with native format (1) (Default) Line breaks are converted to the native format of the operating system: CR (carriage return under OS X), CRLF (carriage return + line feed under Windows) Document with CRLF (2) Line breaks are converted to Windows format: CRLF (carriage return + line feed) Document with CR (3) Line breaks are converted to OS X format: CR (carriage return) Document with LF (4) Line breaks are converted to Unix format: LF (line feed) 4D v14 Upgrade 307

308 Chapter 6 Language By default, when you omit the breakmode parameter, line breaks are processed in native mode (1). Note This command does not modify the OK variable. In case of failure, an error is generated that you can intercept using a method installed by the ON ERR CALL command. Here are some typical examples of using this command: TEXT TO DOCUMENT ("mytest.txt";"this is a test") TEXT TO DOCUMENT ("mytest.xml";"this is a test") Example allowing the user to indicate the location of the file to create: $MyTextVar:="This is a test" ON ERR CALL ("IO ERROR HANDLER") $vhdocref:=create document("") // Store document with the ".txt" extension // In this case, the.txt extension is always added to the name; it is not possible to change it If (OK=1) // If document has been created successfully CLOSE DOCUMENT ($vhdocref) // Closes the document TEXT TO DOCUMENT (Document; $MyTextVar) // We write the document Else // Error management End if See also: Document to text 308 4D v14 Upgrade

309 System Environment System Environment Modified commands FONT LIST FONT LIST ( fonts {; listtype *} ) Parameter Type Description fonts Text array Array of available font names listtype * Longint * Font type list to return or * returns font names under OS X The FONT LIST command now lets you obtain different lists of font types. To do so, you can pass one of the new "Font Type List" constants in the listtype parameter. The following constants are available: Constant (value) System fonts (0) Favorite fonts (1) Recent fonts (2) Comments The * parameter is still supported as in previous versions. You want to get a list of recent fonts: FONT LIST ($arrfonts;recent fonts) fonts contains the list of all the system fonts (equivalent to previous command functioning). Default option when listtype is omitted fonts contains the list of favorite fonts (the ones most commonly used on the machine) fonts contains the list of recent fonts (the ones used during the 4D session). This list is used in particular by the Multi-style areas. Font name Font name ( fontnumber ) Function result Compatibility note This command is now obsolete and must no longer be used in 4D. It is kept in 4D v14 for compatibility but it will not be supported in future versions of the program. Font number Font number ( fontname ) Function result Compatibility note This command is now obsolete and must no longer be used in 4D. It is kept in 4D v14 for compatibility but it will not be supported in future versions of the program. 4D v14 Upgrade 309

310 Chapter 6 Language New commands OPEN COLOR PICKER OPEN COLOR PICKER {( textorbackground )} Parameter Type Description textorbackground Longint 0 or omitted = text color 1 = text background color The OPEN COLOR PICKER command displays the system color picker dialog box. Note This is a modal dialog box under Windows but not under OS X. When the user selects a color and validates the dialog box, this color is applied to the current text selection in the object with the focus, if the Allow Font/Color Picker property is checked for this object (see the Allowing color and font pickers paragraph on page 58). If you pass 0 in the textorbackground parameter or omit this parameter, the selected color is applied to the text. If you pass 1 in textorbackground, this color is applied to the text background. If the color was changed, the On After Edit form event is generated for the object. See also: OPEN FONT PICKER OPEN FONT PICKER OPEN FONT PICKER Parameter Type Description This command does not require any parameters The OPEN FONT PICKER command displays the system font picker dialog box. Note This is a modal dialog box under Windows but not under OS X. When the user selects a font and/or a style and validates the dialog box, the changes are applied to the current text selection in the object with the focus, if the Allow Font/Color Picker property is checked for this object (see the Allowing color and font pickers paragraph on page 58) D v14 Upgrade

311 SET RECENT FONTS If the font was changed, the On After Edit form event is generated for the object. See also: OPEN COLOR PICKER SET RECENT FONTS SET RECENT FONTS ( fontsarray ) Parameter Type Description fontsarray Text array Array of font names The SET RECENT FONTS command modifies the list of fonts displayed in the context menu of the "recent fonts". This menu contains the names of the last fonts selected during the session. It is used in particular by Multi-style areas. You want to add a font to the menu of recent fonts: You execute the following code: ARRAY TEXT ($arrrecent;0) FONT LIST ($arrrecent;2) APPEND TO ARRAY ($arrrecent;"segoe Script") SET RECENT FONTS ($arrrecent) 4D v14 Upgrade 311

312 Chapter 6 Language So the menu contains: See also: FONT LIST Tools Generate digest Generate digest ( param ; algorithm ) Function result A new constant is available for the algorithm parameter: Constant (value) 4D digest (2) Comments Use internal algorithm of 4D This new constant lets you calculate digests identical to those used by 4D internally, and thus check the validity of 4D passwords. This mechanism is particularly useful in the context of the new On REST Authentication database method D v14 Upgrade

313 GET ACTIVITY SNAPSHOT GET ACTIVITY SNAPSHOT GET ACTIVITY SNAPSHOT ( {* ;} arractivities ) ( {* ;} arruuid ; arrstart; arr- Duration; arrinfo {; arrsubop} ) Parameter Type Description * Operator If passed = Get server activity arractivities Object array Complete description of operations arruuid Text array Operation UUIDs arrstart Text array Operation start times arrduration Longint array Operation durations in seconds arrinfo Text array Description arrsubop Object array Sub-operations The new GET ACTIVITY SNAPSHOT command returns one or more array(s) describing operations in progress on the 4D data. These operations usually display a progress window. This command is used to get a snapshot of the x operations that are most time-consuming and/or run most frequently, such as cache writing or the execution of formulas. Note The information returned by the GET ACTIVITY SNAPSHOT command is the same as that displayed on the "Real Time Monitor" (RTM) page of the 4D Server v14 administration window (see the Real Time Monitor paragraph on page 31) This command accepts two syntaxes: syntax using only an object array. syntax using several arrays. By default, GET ACTIVITY SNAPSHOT processes operations performed locally (with 4D single-user, 4D Server or 4D in remote mode). However, with 4D in remote mode, you can also get a snapshot of operations performed on the server: you just need to pass the asterisk (*) as the first parameter. In this case, the server data is recovered locally. The * parameter is ignored when the command is executed on 4D Server or 4D single-user. 4D v14 Upgrade 313

314 Chapter 6 Language First syntax: GET ACTIVITY SNAPSHOT ( {* ;} arractivities ) With this syntax, all the operations are returned in a structured form in the 4D object array (arractivities). Each element of the array is an object built as follows: progressindicator :{ ID: string StartTime: 12:15:20:0054 Duration: 501 Title: String, sub-operations: [ { Title: string, Start time: string, Duration: number (milliseconds) }, { Title: string, Start time: string, Duration: number (milliseconds) } ] } Second syntax: GET ACTIVITY SNAPSHOT ( {* ;} arruuid ; arrstart ; arrduration ; arrinfo {;arrsubop} ) With this syntax, all the operations are returned in several synchronized arrays (each operation causes an element to be added to all of the arrays). The following arrays are returned: arruuid: contains the UUIDs for each operation. arrstart: contains the start times for each operation in the format "dd/mm/yyyy - hh:mm:ss" (text) arrduration: contains the durations of each operation in milliseconds arrinfo: contains the labels describing each operation arrsubop (optional): each element of this array is an object containing the "suboperations" property. The value of this property is an object array containing all the sub-operations for the current operation. If the current operation does not have any suboperations, the value of the suboperations property is an empty array D v14 Upgrade

315 GET ACTIVITY SNAPSHOT This method, executed in a separate process on 4D or 4D Server, provides a snapshot of the operations that are underway: ARRAY TEXT (arruuid;0) ARRAY TEXT (arrstart;0) ARRAY LONGINT (arrduration;0) ARRAY TEXT (arrinfo;0) Repeat GET ACTIVITY SNAPSHOT (arruuid;arrstart;arrduration;arrinfo) If (Size of array (arruuid)>0) TRACE // calling of debugger End if Until (False) // Infinite loop You get arrays such as: 4D v14 Upgrade 315

316 Chapter 6 Language User Interface SHOW TOOL BAR, HIDE TOOL BAR Tool bar height In 4D v14, these commands no longer have any effect. In previous versions of 4D, these commands managed automatic tool bars in Application mode -- these tool bars are no longer supported in 4D v14. This command now always returns 0 when it is called in Application mode. Users and Groups Validate password Validate password (user; password {; digest} ) Text Parameter Type Description user Longint Unique user ID or User name String password String Password digest Boolean Digest password = True, Plain-text password (default)= False Function result Boolean True = valid password False = invalid password Two modifications are made to the Validate password command in 4D v14: You can now pass a user name (string) directly in the first parameter (user). An optional third parameter, digest, is added. This parameter indicates whether the password parameter contains a plain-text password or a hashed password (digest mode): When you pass True, this indicates that password contains a hashed password (digest mode), When you pass False or omit this parameter, this indicates that it contains a plain-text password. These modifications are particularly useful in the context of using the new On REST Authentication database method D v14 Upgrade

317 Web Area In the On REST Authentication database method, you want to test a connection request (using the 4D users of the database). You can just write: $0 := Validate password($1; $2; $3) Web Area WA Evaluate JavaScript WA Evaluate JavaScript ( {* ;} object; jscode {; type} ) Function result Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) jscode String JavaScript code type Longint Type into which to convert result Function result Text, Real, Date, Time, Boolean, Pointer, Language object Result of evaluation Compatibility note This command was named WA Execute JavaScript in previous versions of 4D. The WA Evaluate JavaScript command can now return types of results other than strings. Important: This new feature is only available if the Web area uses the integrated Web Kit as the rendering engine. By default, the command returns values as strings. You can use the optional type parameter to specify typing for the value returned. 4D v14 Upgrade 317

318 Chapter 6 Language Pass one of the following constants, found in the "Field and Variable Types" theme (new constants are added to this theme in 4D v14): Constant (value) Is real (1) Is text (2) Is date (4) Is boolean (6) Is longint (9) Is integer (8) Is integer 64 bits (25) Is string var (24) Is time (11) Is object (38) Object array (39) Is JSON null (255) Comments Number in milliseconds New in 4D v14 New in 4D v14 New in 4D v14 This example shows a few evaluations with conversion of the values received. JavaScript functions placed in an HTML file: <!DOCTYPE html> <html> <head> <script> function evallong(){ return 123; } function evaltext(){ return "456"; } function evalobject(){ return {a:1,b:"hello world"}; } function evaldate(){ return new Date(); } </script> </head> <body> TEST PAGE </body> </html> 318 4D v14 Upgrade

319 WA EXECUTE JAVASCRIPT FUNCTION In the 4D form method, you write: If (Form event=on Load) WA OPEN URL (*;"Web Area";"C:\\myDatabase\\index.html") End if You can then evaluate the JavaScript code from 4D: $Eval1:=WA Evaluate JavaScript (*;"Web Area";"evalLong()";Is longint) // $Eval1 = 123 // $Eval1 = "123" if type is omitted $Eval2:=WA Evaluate JavaScript (*;"Web Area";"evalText()";Is string var) // $Eval2 = "456" $Eval3:=WA Evaluate JavaScript (*;"Web Area";"evalObject()";Is object) // $Eval3 = {"a":1,"b":"hello world"} $Eval4:=WA Evaluate JavaScript (*;"Web Area";"evalDate()";Is date) // $Eval4 = 06/21/13 // $Eval4 = " T14:45:09.694Z" if type is omitted WA EXECUTE JAVASCRIPT FUNCTION WA EXECUTE JAVASCRIPT FUNCTION ( {* ;} object; jsfunction ; result * {; param}{; param2 ;... ; paramn} ) Parameter Type Description * Operator If specified, object is an object name (string) If omitted, object is a variable object Form object Object name (if * is specified) or Variable (if * is omitted) jsfunction String Name of JavaScript function to execute result * Variable * for a function with no result or Function result (if expected) param String, Number, Date, Object Parameter(s) to pass to the function The WA EXECUTE JAVASCRIPT FUNCTION command now supports parameters of types other than strings for both input (param) and output (result). You can now pass and retrieve data of the number, date, object and string types. Important: This new feature is only available if the Web area uses the integrated Web Kit as the rendering engine. 4D v14 Upgrade 319

320 Chapter 6 Language The "getcustomerinfo" JavaScript function receive a number ID as parameter and returns an object: C_OBJECT ($Result) C_LONGINT ($ID) $ID:=1000 WA EXECUTE JAVASCRIPT FUNCTION (*,"WA";"getCustomerInfo";$Result;$ID) WA SET PREFERENCE WA SET PREFERENCE ( {* ;} object ; selector ; value ) The WA SET PREFERENCE command accepts a new constant in the selector parameter: Constant (value) wa enable Web inspector (100) Comments Allow the display of the Web inspector in the Web area Displaying a debugger in a Web area is a new feature in 4D v14. For more information, refer to the Access to Web inspector paragraph on page 92. Web Server WEB SEND TEXT WEB SEND TEXT ( htmltext {; type} ) Parameter Type Description htmltext Text HTML text field or variable to be sent to the Web browser type Text MIME type The WEB SEND TEXT command now accepts a new optional text type parameter: type. Note This parameter replaces the Boolean nocontext parameter, which became obsolete in 4D v12. In type, you can specify the MIME type of the text to be sent. By default, if this parameter is omitted, the "text/html" type is used, as with previous versions of 4D D v14 Upgrade

321 Web Services (Client) For more information about MIME types, refer to the description of the WEB SEND BLOB command. Web Services (Client) In 4D v14, support for the SOAP 1.2 protocol is extended. Web Services also have server certificates (see HTTP SET CERTIFICATES FOLDER). WEB SERVICE CALL WEB SERVICE CALL ( accessurl ; soapaction ; methodname ; namespace {; complextype {; *}} ) If the command uses a server certificate and this certificate is not valid (expired or revoked), the OK system variable is set to 0 and error 901 "Invalid server certificate" is returned. You can intercept this error using an error-handling method installed by the ON ERR CALL command. WEB SERVICE Get info WEB SERVICE Get info ( infotype ) Function result In the context of this command, the causes of errors returned by the SOAP protocol have been renamed: Client Fault is renamed "Sender" Fault. Server Fault is renamed "Receiver" Fault. Windows Window types (OS X) Compositing mode In 4D v14 under OS X, window management is modified: compositing mode is generalized a new "full screen button" option is available In 4D v14, all windows are now created in compositing mode (see Windows in non-compositing mode (OS X) paragraph on page 18). Consequently, the Compositing mode and Compositing mode form window constants of the "Open Window" and "Open Form Window" themes are now prefixed with "_O_" and are no longer supported. 4D v14 Upgrade 321

322 Chapter 6 Language Full screen button The new "full screen button" option is available in 4D v14 under OS X for document type windows. When this option is used, a "Full screen" button is displayed in the top right corner of the window: Icon for switching to full screen When the user clicks on this icon, the window switches to full screen and 4D automatically hides the main tool bar. To use this option, you just add the Has full screen mode Mac constant to the type parameter for the Open window, Open form window and Open external window commands. Creating a form window with a full-screen button under OS X: $win:=open form window ([Interface];"User_Choice";Plain form window + Has full screen mode Mac) DIALOG ([Interface];"User_Choice") Note Under Windows, this option has no effect. Renamed constant For reasons of technical evolution, the following constant was renamed in 4D v14: Name in 4D v14 Former name in 4D v13.x Comments _O_qr 4D Chart area qr 4D Chart area Renaming due to the discontinuation of 4D Chart (see the Removed functions paragraph on page 17) 322 4D v14 Upgrade

323 4D Internet Commands 4D Internet Commands The 4D IC SMTP commands have been updated and enhanced in 4D v14: use of Unicode by default, management of IDs and HTML, new SMTP_MessageID command. Note The 4D Internet Commands plug-in is also provided in the 64-bit version in v14. For more information, refer to the Support for 64-bit plug-ins under Windows paragraph on page 14. Unicode by default The subject and body fields of all the SMTP commands in 4DIC now use the UTF-8 character set by default. This character set will be interpreted correctly by almost all of the clients. This new feature greatly simplifies the use of SMTP commands and makes using the SMTP_Charset or SMTP_SetPrefs commands unnecessary. SMTP_Attachment SMTP_Attachment ( smtp_id ; filename ; encodetype ; deleteoption ; attachmentid ) Function result Parameter Type Description smtp_id Longint Message reference filename Text Name of file to attach encodetype Integer 0 = No encoding (sends DataFork only) ±1 = BinHex ±2 = Base64 (sends DataFork only) ±3 = AppleSingle ±4 = AppleDouble ±5 = AppleSingle AND Base64 ±6 = AppleDouble AND Base64 ±7 = UUEncode deleteoption Integer 0 = Add to existing list, 1 = Replace all attachments with filename, 2 = Remove only this attachment attachmentid Text ID of attachment (HTML messages only) Function result Integer Error code The SMTP_Attachment command now accepts an additional parameter, attachmentid, that associates the attachment with a reference defined in the message body using the HTML tag <img src=\"cid:id\">. 4D v14 Upgrade 323

324 Chapter 6 Language This means that the contents of the files, for example a picture, can be displayed within the message on the client. This functioning is only supported with messages in HTML. Also note that the final result may vary depending on the client. Sending an HTML message with a picture included: $error:=smtp_new ($smtp_id) $error:=smtp_host ($smtp_id;"smtp.gmail.com") $error:=smtp_from ($smtp_id;"[email protected]") $error:=smtp_replyto ($smtp_id;"[email protected]") $error:=smtp_subject ($smtp_id;"html Test & picture included") $error:=smtp_to ($smtp_id;"[email protected]";1) $error:=smtp_body ($smtp_id;"<html><b><i>hello world in bold!</i> </B> <img src=\"cid:myid123\">(normal text)</html>";4) $error:=smtp_attachment ($smtp_id;"c:\\temp\\tulips.jpg";2;0; "myid123") $error:=smtp_auth ($smtp_id;"[email protected]";"*******") $error:=smtp_send ($smtp_id;1) $error:=smtp_clear ($smtp_id) SMTP_Body SMTP_Body ( smtp_id ; msgbody ; option ) Function result Parameter Type Description smtp_id Longint Message reference msgbody Text Body of message (UTF-8 by default) option Integer 0 = Replace (if msgbody not empty), 1 = Delete, 2 = Append, 4 = HTML text (plain text by default) Function result Integer Error code The SMTP_Body command now lets you send a message in HTML format. To do this, simply pass the value 4 in the option parameter. If you do not pass this value, by default he message is sent as plain text. To combine sending a message in HTML with a replacement option, you just add the two values together. For example, pass 1+4 in option in order to delete the body and send it in HTML. In addition, by default in 4D v14, the body of the message (msgbody) is encoded with the UTF-8 (Unicode) character set. See also: SMTP_Subject 324 4D v14 Upgrade

325 SMTP_MessageID SMTP_MessageID SMTP_MessageID ( smtp_id ; message_id; option ) Function result Parameter Type Description smtp_id Longint Message reference message_id Text Unique ID of message option Integer 0 = Add, 1 = Replace, 2 = Delete Function result Integer Error code The new SMTP_MessageID command adds a "message-id" field in the header of the message whose reference is passed in smtp_id. This unique ID is used in particular on forums or public mailing lists. In general, mail servers automatically add this header to the messages they send. You can use this command to define its contents. smtp_id contains the ID of an created with the SMTP_New command. In message_id, you pass an ID to associate with the message. The contents you pass is normally unrestricted, however conventionally, it is usually in the form "lettersornumbers@domainname", for example "abcdef @4d.com". Note that certain servers (such as Gmail) do not recognize custom "message-id" headers and replace them when they are not in this form. The option parameter lets you specify whether any existing message_id header should be kept or removed: If you pass 0 (default value if parameter is omitted), the contents of the parameter passed are added to the existing contents. If you pass 1, the contents of the parameter passed replace the existing contents. If you pass 2, the existing contents are removed from the message. 4D v14 Upgrade 325

326 Chapter 6 Language In this example, a message with a specific "message-id" header is sent for each record of the [Admin] table: $error:=smtp_new ($smtp_id) $error:=smtp_host ($smtp_id;"infoserv.com") $error:=smtp_from ($smtp_id;"[email protected]") $error:=smtp_subject ($smtp_id;"general statistics") FIRST RECORD ([Admin]) For ($i;1;records in selection ([Admin])) $error:=smtp_body ($smtp_id;$stats) $error:=smtp_to ($smtp_id;[admin] ;1) // Replaces the "A" header with a new value $error:=smtp_messageid ($smtp_id;[admin]id+"@infoserv.com";1) // Use of the admin ID $error:=smtp_send ($smtp_id) NEXT RECORD ([Admin]) End for $error:=smtp_clear ($smtp_id) SMTP_QuickSend SMTP_QuickSend ( hostname ; msgfrom ; msgto ; subject ; message {; sessionparam}{; port}{; username ; password} ) Function result Parameter Type Description hostname String Host name or IP address msgfrom Text MailAddress or AddressList msgto Text MailAddress or AddressList subject Text Subject (UTF-8 by default) message Text Message (UTF-8 by default) sessionparam Longint 0 or omitted = Do not use SSL but switchover allowed, 1 = Use SSL, 2 = Never use SSL (switchover not allowed), 4 = Send HTML text without SSL, 5 = Send HTML text with SSL port Longint Number of port to use username Text User name for authentication password Text Password for authentication Function result Integer Error code The SMTP_QuickSend command can now create and send a message in HTML format. To do this, you simply pass the following values in the sessionparam parameter: 4 = sending of HTML-format message in standard (non-ssl) mode 5 = sending of HTML-format message in SSL mode 326 4D v14 Upgrade

327 SMTP_Subject In addition, by default in 4D v14, the body of the message and its subject are both encoded with the UTF-8 (Unicode) character set. Sending a message in HTML with SSL: $Host:="smtp.gmail.com" $ToAddress:="[email protected]" $FromAddress:="[email protected]" $Subject:="HTML Message" $Message:="Let s meet at <b>joe s Coffee Shop</b>!" $Param:=5 // HTML with SSL $Port:=465 // SSL port of gmail $User:="[email protected]" $Password:="xyz&@!&@" $Error:=SMTP_QuickSend($Host;$FromAddress;$ToAddress;$Subject;$Message;$Param;$Port;$User;$Password) SMTP_Subject SMTP_Subject ( smtp_id ; subject ; option ) Function result By default in 4D v14, the message subject is encoded with the UTF-8 (Unicode) character set. See also: SMTP_Body 4D Pack Due to changes in technology and continuous integration of new features 4D, several commands have been removed from 4D Pack v14. Note The 4D Pack plug-in is also available in a 64-bit version in 4D v14. For more information, refer to the Support for 64-bit plug-ins under Windows paragraph on page 14. 4D v14 Upgrade 327

328 Chapter 6 Language Commands removed from 4D Pack Here are the commands that were removed from 4D Pack v14 and the recommended alternatives: Command removed Replaced with AP AVAILABLE MEMORY GET MEMORY STATISTICS (modified in v14) AP CLOSE HELP Obsolete commands - The Windows Help application (WinHlp32.exe) is no longer integrated in AP HELP INDEX AP HELP ON HELP Windows starting with Windows Vista. AP HELP ON KEY AP Create method METHOD SET CODE("myMeth";vCode;*) AP Modify method METHOD SET ATTRIBUTE("myMeth";vInvisible;2;v4DAction;3;vWebService;4;vWSDL;5;vExported;7;vSQL;8;vRemote;1024;vFolderName;*) AP Does method exist METHOD GET NAMES ($arrnames;"mymeth") $exists:=(size of array ($arrnames)>0) // -> True if method exists AP Get picture type Commands of "Pictures" theme AP Get templates Obsolete command _AP External clock New TimePicker Widget (4D v14) AP SET CLOCK AP Rect Dragger SET DRAG ICON (4D v14) AP Timestamp to GMT $date:=string (Current date;iso Date GMT; Current time) // returns, e.g. " T12:19:23Z" AP SET PARAM Obsolete commands - Secondary parameters AP GET PARAM managed by these commands are not maintained. TimePicker Widget The TimePicker widget provides new objects for displaying time data. Typically, you can use these objects to display dynamic clocks in your forms D v14 Upgrade

329 TimePicker Widget Two new types of objects are available: "clock" (TimeDisplay): "digital clock" (TimeDisplayLCD): There are two ways to insert a time display area in a form: by inserting a "Time display area" object from the 4D preconfigured object library by creating a subform area and assigning the "TimeDisplay" or "TimeDisplayLCD" detail form to it. Next, in the Property List, you define the object name and the name of the variable associated with the subform. You can also not give a name to the variable in order to take advantage of the dynamic variable mechanism. Clock The clock widget is drawn in SVG, and therefore has a vector path allowing deformations in Application mode (in Design mode, its size is fixed): Developers can displace this clock drawing and substitute their own creations by replacing the "clock.svg" file found at the first level of the "Resources" folder. Displaying current time By default, the variable associated with the clock widget is of the Real type. In this case, the widget automatically displays the current time and functions as a clock. Compatibility note This principle allows you to replace the clocks generated using the _AP EXTERNAL CLOCK area of 4D Pack (not retained in v14). 4D v14 Upgrade 329

330 Chapter 6 Language You can apply an offset to the displayed time: the value of the number variable indicates the offset in seconds. For example, 3600 = advancing the clock one hour, = turning the clock back 30 minutes, etc. You have the following additional functions: the second hand can be displayed or hidden using the TimePicker DISPLAY SECOND HAND method. the clock automatically changes to "day mode" or "night mode" depending on the time: The time ranges are 8:00:00 -> 19:59:59 = Day, 20:00 -> 07:59:59 = Night. Displaying a static time You can set up the clock widget so that it displays a preset time. To do this, you declare the associated variable as a "Time" type. Then you can either: use the C_TIME command with the associated variable, choose Time as the "Variable Type" in the Property List. In this case, the clock will display the value of the time variable. We want the clock to show 10:10:30: C_TIME (myvar) // myvar is the name of the widget s variable myvar:=?10:10:30? Digital clock The new "digital clock" widget displays the time like a LCD or LED screen: 330 4D v14 Upgrade

331 TimePicker DISPLAY SECOND HAND This widget is drawn in SVG so it can be resized without deteriorating the display result. It is transparent and has no background so it can be placed on top of colored objects in order to vary its appearance: Displays the current time or a static time Just like the "Clock" widget, the digital clock can display either the current time dynamically or a static time. To display the current time, associate a Real variable with the widget s subform object (default operation). Then widget functioning is automatic. To display a static time, associate a Time variable with the widget s subform object. The widget then displays the value of the variable. In "clock" mode, you can apply an offset to the displayed time: the value of the number variable indicates the offset in seconds. For example, 3600 = advancing the clock one hour, = turning the clock back 30 minutes, etc. There are several display options available through component methods, which are prefixed by "TimePicker LCD". TimePicker DISPLAY SECOND HAND TimePicker DISPLAY SECOND HAND ( objectname; secondhand ) Parameter Type Description objectname Text Name of subform object secondhand Boolean True (default) = second hand shown False = second hand hidden The TimePicker DISPLAY SECOND HAND command displays or hides the second hand in the objectname subform object (clock widget only). By default, the second hand is displayed. To hide it, call this command and pass False in the secondhand parameter. 4D v14 Upgrade 331

332 Chapter 6 Language TimePicker LCD DISPLAY AMPM TimePicker LCD DISPLAY AMPM ( objectname; ampm ) Parameter Type Description objectname Text Name of subform object ampm Boolean True = display AM/PM, False = do not display The TimePicker LCD DISPLAY AMPM command displays or hides the AM/PM placed to the right of the objectname subform object (digital clock only). These letters are used to distinguish between the morning and afternoon when the clock is used in 12-hour mode (see TimePicker LCD SET MODE). By default, these letters are displayed. You can pass False in ampm to hide them. We want to hide the AM/PM: TimePicker LCD DISPLAY AMPM ("Subform1";False) See also: TimePicker LCD SET MODE TimePicker LCD DISPLAY SECONDS TimePicker LCD DISPLAY SECONDS ( objectname; seconds ) Parameter Type Description objectname Text Name of subform object seconds Boolean True = display seconds, False = do not display The TimePicker LCD DISPLAY SECONDS command displays or hides the seconds part of the objectname subform object (digital clock only). By default, seconds are displayed. You can pass False in seconds to hide them D v14 Upgrade

333 TimePicker LCD SET COLOR TimePicker LCD SET COLOR TimePicker LCD SET COLOR ( objectname; color {;colorg; colorb} ) Parameter Type Description objectname Text Name of subform object color Longint Value of RGB color (4 bytes) or Value of red component (0..255) if the other parameters are passed colorg Longint Value of green component (0..255) colorb Longint Value of blue component (0..255) The TimePicker LCD SET COLOR command sets the colors for the digits in the objectname subform object (digital clock only). This command accepts two syntaxes: If you only pass the color parameter, you must pass a 4-byte longint whose format (0x00RRGGBB) is described below (the bytes are numbered from 0 to 3, starting from right to left): Byte Description 3 Must be zero for an absolute RGB color 2 Red component of color (0..255) 1 Green component of color (0..255) 0 Blue component of color ( You can also pass three parameters: color, colorg and colorb. In this case, each parameter must be a number between 0 and 255, representing a component of the RGB color. Change the clock digits to red: TimePicker LCD SET COLOR ("Subform1";0x00FF0000) // can also be written: TimePicker LCD SET COLOR ("Subform1";255;0;0) 4D v14 Upgrade 333

334 Chapter 6 Language TimePicker LCD SET MODE TimePicker LCD SET MODE ( objectname; mode ) Parameter Type Description objectname Text Name of subform object mode Longint 12 = display time in 12-hour mode, 24 = display time in 24-hour mode The TimePicker LCD SET MODE command sets the display to either 12- or 24-hour mode for the objectname subform object (digital clock only). By default, the object is displayed in 12-hour mode. You can pass the value 24 in the mode parameter if you want to switch to 24-hour mode. In this case, it s generally a good idea to hide the AM/PM as well (see the TimePicker LCD DISPLAY AMPM command). We want to switch to 24-hour mode and hide the AM/PM: TimePicker LCD SET MODE ("Subform1";24) TimePicker LCD DISPLAY AMPM ("Subform1";False) See also: TimePicker LCD DISPLAY AMPM 334 4D v14 Upgrade