Merge pull request #360 from doc4d/main

fixes and new translations

docs/API/CollectionClass.md

@@ -208,16 +208,15 @@ You can pass any number of values of the following supported types:
 *	date
 *	time (stored as number of milliseconds - real)
 *	null
-*	shared object(*)
-*	shared collection(*)
+*	shared object
+*	shared collection
 
 :::note
 
 Unlike standard (not shared) collections, shared collections do not support pictures, pointers, and objects or collections that are not shared.  
 
 :::
 
-(\*)When a shared object or collection is added to a shared collection, they share the same *locking identifier*. For more information on this point, refer to [4D Doc Center](https://doc.4d.com).
 
 #### Example
 
@@ -3219,7 +3218,7 @@ With the following ***Flatten*** method:
 |---------|--- |:---:|------|
 |index |Integer|->|Element at which to start removal|
 |howMany |Integer|->|Number of elements to remove, or 1 element if omitted|
-|Result|Collection|<-|Original collection without removed element(s)|
+|Result|Collection|<-|Modified collection without removed element(s)|
 <!-- END REF -->
 
 

docs/API/DataClassClass.md

@@ -161,7 +161,7 @@ In the optional *settings* parameter, you can pass an object containing addition
 
 |Property| Type| Description|
 |---|---|---|
-|context|Text|Label for the optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](ORDA/entities.md#client-server-optimization).|
+|context|Text|Label for the optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](../ORDA/client-server-optimization.md).|
 
 > To know the total number of entities in a dataclass, it is recommended to use the [`getCount()`](#getcount) function which is more optimized than the `ds.myClass.all().length` expression.
 
@@ -222,6 +222,11 @@ $ds.Persons.clearRemoteCache()
 // Cache of the Persons dataclass = {timeout:30;maxEntries:30000;stamp:255;entries:[]}
 ```
 
+#### See also
+
+[`entitySelection.refresh()`](EntitySelectionClass.md#refresh)
+
+
 <!-- END REF -->
 
 <!-- REF DataClassClass.fromCollection().Desc -->
@@ -288,7 +293,7 @@ In the optional *settings* parameter, you can pass an object containing addition
 
 |Property |Type| Description|
 |---|---|---|
-|context|Text|Label for the optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](ORDA/entities.md#client-server-optimization).|
+|context|Text|Label for the optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](../ORDA/client-server-optimization.md).|
 
 #### Example 1
 
@@ -462,7 +467,13 @@ In the optional *settings* parameter, you can pass an object containing addition
 
 |Property| Type| Description|
 |---|---|---|
-|context| Text| Label for the automatic optimization context applied to the entity. This context will be used by the subsequent code that loads the entity so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](ORDA/entities.md#client-server-optimization).|
+|context| Text| Label for the automatic optimization context applied to the entity. This context will be used by the subsequent code that loads the entity so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](../ORDA/client-server-optimization.md).|
+
+:::info
+
+When you call the `.get()` function **without** *settings* parameter, a request for attribute values is directly sent to the server (the [ORDA cache](../ORDA/client-server-optimization.md#orda-cache) is not used). On the other hand, when you call the `.get()` function **with** a `context` passed in the *settings* parameter, attribute values are retrieved from the ORDA cache corresponding to the context. It may be advisable in this case to call [`reload()`](EntityClass.md#reload) to make sure the most recent data is retrieved from the server.
+
+:::
 
 #### Example 1  
 

docs/API/EntitySelectionClass.md

@@ -2059,7 +2059,8 @@ A list box displays the Form.students entity selection and several clients work
 
 #### See also
 
-[`.clean()`](#clean)
+[`.clean()`](#clean)<br/>
+[dataClass.clearRemoteCache()](DataClassClass.md#clearremotecache)
 
 <!-- END REF -->
 

docs/API/IMAPTransporterClass.md

@@ -785,10 +785,11 @@ The `boxInfo` object returned contains the following properties:
 
 |Property| Type| Description|
 |---|---|---|
-|name|text|Name of the mailbox
-|mailCount| number| Number of messages in the mailbox|
-|mailRecent| number| Number of messages with the "recent" flag (indicating new messages)|
+|name|Text|Name of the mailbox
+|mailCount| Number| Number of messages in the mailbox|
+|mailRecent| Number| Number of messages with the "recent" flag (indicating new messages)|
 |id| text| Unique id of the mailbox|
+|mailUnseen| Number|Number of messages marked "unseen"|
 
 #### Example
 
@@ -833,17 +834,25 @@ In the optional `parameters` parameter, pass an object containing values to filt
 |Property | Type| Description |
 |---|---|---|
 |isSubscribed|  Boolean |<li>**True** to return only subscribed mailboxes</li><li> **False** to return all available mailboxes</li>|
+| names      | Collection | Collection of objects containing a "name" attribute or collection of texts containing the box names |
+| withBoxProperties| Boolean | If true (default): adds the `selectable`, `inferior`, and `interesting` attributes to the result object. If false, these attributes are omitted.|
+| withBoxInfo| Boolean | Default value is false. If true, adds the `mailCount`, `mailRecent`, and `id` attributes to the result object.|
 
 #### Result
 
 Each object of the returned collection contains the following properties:
 
 |Property|  Type|Description |
 |---|---|---|
-|\[].name|text|Name of the mailbox |
-|\[].selectable |boolean |Indicates whether or not the access rights allow the mailbox to be selected: <ul><li>true - the mailbox can be selected</li><li>false - the mailbox can not be selected</li></ul>|
-|\[].inferior |boolean |Indicates whether or not the access rights allow creating a lower hierachy in the mailbox: <ul><li>true - a lower level can be created</li><li>false - a lower level can not be created</li></ul>|
-|\[].interesting |boolean  |Indicates if the mailbox has been marked "interesting" by the server: <ul><li>true - The mailbox has been marked "interesting" by the server. For example, it may contain new messages.</li><li>false - The mailbox has not been marked "interesting" by the server.</li></ul>|
+|\[].name|Text|Name of the mailbox. Returned if withBoxProperties=true or withBoxInfo=true |
+|\[].selectable |Boolean |Indicates whether or not the access rights allow the mailbox to be selected: <ul><li>true - the mailbox can be selected</li><li>false - the mailbox can not be selected</li></ul>	Returned if withBoxProperties=true|
+|\[].inferior |Boolean |Indicates whether or not the access rights allow creating a lower hierachy in the mailbox: <ul><li>true - a lower level can be created</li><li>false - a lower level can not be created</li></ul>	Returned if withBoxProperties=true|
+|\[].interesting |Boolean  |Indicates if the mailbox has been marked "interesting" by the server: <ul><li>true - The mailbox has been marked "interesting" by the server. For example, it may contain new messages.</li><li>false - The mailbox has not been marked "interesting" by the server.</li></ul>	Returned if withBoxProperties=true|
+| [].mailCount  | Number | Number of messages in inbox. Returned if withBoxInfo=true |
+| [].mailRecent | Number | Number of messages marked "recent" (indicating new messages). Returned if withBoxInfo=true  |
+| [].mailUnseen | Number | Number of messages marked "unseen". Returned if withBoxInfo=true |
+| [].id         | Text   | Unique mailbox identifier. Returned if withBoxInfo=true |
+
 
 If the account does not contain any mailboxes, an empty collection is returned.
 

docs/API/WebSocketServerClass.md

@@ -69,7 +69,7 @@ CALL WORKER("WebSocketServer"; Formula(wss:=4D.WebSocketServer.new($handler)))
 Function onConnection($wss : Object; $event : Object) : Object
 	//returns an instance of the user class
 	//that will handle the messages
-	return cs.myConnectionHandler.new() 
+	return cs.myConnectionHandler.new()
 ```
 
 3. Define the `myConnectionHandler` user class containing callback function(s) used to handle messages:
@@ -78,7 +78,7 @@ Function onConnection($wss : Object; $event : Object) : Object
 // myConnectionHandler class
 
 Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
-	//resends the message in uppercase	
+	//resends the message in uppercase
 	$ws.send(Uppercase($message.data))
 
 ```
@@ -128,7 +128,7 @@ Calling this function requires that the [4D Web Server](WebServerClass.md) is st
 
 ### *WSSHandler* parameter
 
-In the *WSSHandler* parameter, pass an instance of a user class that will be called every time an event occurs on the WebSocket server --essentially, connection events. The class should define the following callback functions (only `onConnection` is mandatory): 
+In the *WSSHandler* parameter, pass an instance of a user class that will be called every time an event occurs on the WebSocket server --essentially, connection events. The class should define the following callback functions (only `onConnection` is mandatory):
 
 |Property|Type|Description|Default|
 |---|---|---|---|
@@ -138,7 +138,7 @@ In the *WSSHandler* parameter, pass an instance of a user class that will be cal
 |onError|[Function](FunctionClass.md)|Callback when an error has occurred (see below)|undefined|
 
 
-**WSHandler.onConnection**(*WSServer* : Object ; *event* : Object) : Object | null 
+**WSHandler.onConnection**(*WSServer* : Object ; *event* : Object) : Object | null
 
 |Parameter||Type||Description|
 |---------|---|---|:---:|------|
@@ -190,21 +190,21 @@ Event emitted when an error occurs on the WebSocket server.
 This example of a basic chat feature illustrates how to handle WebSocket server connections in a *WSSHandler* class.
 
 ```4d
-//myWSServerHandler class 
+//myWSServerHandler class
 
 Function onConnection($wss : Object; $event : Object) : Object
 
 	If (VerifyAddress($event.request.remoteAddress))
 		// The VerifyAddress method validates the client address
-		// The returned WSConnectionHandler object will be used 
+		// The returned WSConnectionHandler object will be used
 		// by 4D to instantiate the 4D.WebSocketConnection object
 		// related to this connection
 		return cs.myConnectionHandler.new()   
 		// See connectionHandler object
-	Else 
+	Else
 		// The connection is cancelled		
-		return Null 
-	End if 
+		return Null
+	End if
 
 Function onOpen($wss : Object; $event : Object)
 LogFile("*** Server started")
@@ -231,7 +231,7 @@ A `request` object contains the following properties:
 
 ### `connectionHandler` object
 
-As a result of the `WSHandler.onConnection` callback, pass a `connectionHandler` object, which is an instance of a user class that will be called every time an event occurs in the WebSocket connection --essentially, messages received. The class should define the following callback functions (only `onMessage` is mandatory): 
+As a result of the `WSHandler.onConnection` callback, pass a `connectionHandler` object, which is an instance of a user class that will be called every time an event occurs in the WebSocket connection --essentially, messages received. The class should define the following callback functions (only `onMessage` is mandatory):
 
 |Parameter|Type|Description|
 |---------|---|---|
@@ -295,12 +295,12 @@ This example of a basic chat feature illustrates how to handle messages in a *co
 // myConnectionHandler Class
 
 Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
-	// Resend the message to all chat clients	
+	// Resend the message to all chat clients
 	This.broadcast($ws;$message.data)
 
 Function onOpen($ws : 4D.WebSocketConnection; $message : Object)
 	// Send a message to new connected users
-	$ws.send("Welcome on the chat!")	
+	$ws.send("Welcome on the chat!")
 	// Send "New client connected" message to all other chat clients
 	This.broadcast($ws;"New client connected")
 
@@ -315,8 +315,8 @@ Function broadcast($ws : 4D.WebSocketConnection; $message:text)
 		// Check that the id is not the current connection
 		If ($client.id#$ws.id)
 			$client.send($message)
-		End if 
-	End for each 
+		End if
+	End for each
 
 ```
 
@@ -338,7 +338,7 @@ In the optional *options* parameter, pass an object that contains the following
 
 #### Description
 
-The `.connections` property contains <!-- REF #WebSocketServerClass.connections.Summary -->all current connections handled by the WebSocket server<!-- END REF -->. Each element of the collection is a [`WebSocketConnection` object](WebSocketConnectionClass.md). 
+The `.connections` property contains <!-- REF #WebSocketServerClass.connections.Summary -->all current connections handled by the WebSocket server<!-- END REF -->. Each element of the collection is a [`WebSocketConnection` object](WebSocketConnectionClass.md).
 
 When a connection is terminated, its [`status`](WebSocketConnectionClass.md#status) changes to "Closed" and it is removed from this collection.
 
@@ -387,19 +387,28 @@ This property is read-only.
 <!-- REF #WebSocketServerClass.terminate().Desc -->
 ## .terminate()
 
-<!-- REF #WebSocketServerClass.terminate().Syntax -->**.terminate()**<!-- END REF -->
+<!-- REF #WebSocketServerClass.terminate().Syntax -->**.terminate**()<br/>**.terminate**( *timeout* : Integer )<!-- END REF -->
 
 
 <!-- REF #WebSocketServerClass.terminate().Params -->
 |Parameter|Type||Description|
 |---------|--- |:---:|------|
-||||Does not require any parameters|
+|timeout|Integer|->|Waiting time in seconds before terminating the WebSocket server|
 <!-- END REF -->
 
 
 #### Description
 
-The `.terminate()` function <!-- REF #WebSocketServerClass.terminate().Summary -->closes the WebSocket server<!-- END REF -->. 
+The `.terminate()` function <!-- REF #WebSocketServerClass.terminate().Summary -->closes the WebSocket server<!-- END REF -->.
+
+By default, if no *timeout* value is set, the function initializes close handshake and waits to receive close frame from the peer, after that sending FIN packet in attempt to perform a clean socket close. When answer received, the socket is destroyed.
+
+If a *timeout* value is set:
+- when the waiting time is reached, forcibly destroys the socket.
+- if *timeout* = 0, forcibly destroys the socket without closing frames or fin packets exchange, and does it instantly without waiting time.
+
+
+
 
 <!-- END REF -->
 
@@ -410,8 +419,7 @@ The `.terminate()` function <!-- REF #WebSocketServerClass.terminate().Summary -
 
 #### Description
 
-The `.terminated` property contains <!-- REF #WebSocketServerClass.terminated.Summary -->True if the WebSocket server is closed<!-- END REF -->. 
+The `.terminated` property contains <!-- REF #WebSocketServerClass.terminated.Summary -->True if the WebSocket server is closed<!-- END REF -->.
 
 This property is read-only.
 <!-- END REF -->
-

docs/API/overview.md

@@ -3,18 +3,20 @@ id: overview
 title: About class functions
 ---
 
-This section describes the built-in 4D class functions as well as the associated constructor commands. 4D class functions and properties are available through class instance objects. 
+This section describes the built-in 4D class functions as well as the associated constructor commands. 4D class functions and properties are available through class instance objects.
 
 - functions must be called on instances with the `()` operator. For example, `collection.sort()`.
 - properties are accessed without parentheses, for example `file.creationTime`. You can also use the \[] syntax, for example `file["creationTime"]`.
 - commands can be called independantly, with or without parameters. For example `Folder(fk database folder)`.
 
 ## Writing conventions
 
-The following conventions are used in the function syntax: 
+The following conventions are used in the function syntax:
 
 - the `{ }` characters (braces) indicate optional parameters. For example, `.delete( { option : Integer } )` means that the *option* parameter may be omitted when calling the function.
-- the `{ ; ...param }` notation indicates an unlimited number of parameters. For example, `.concat( value : any { ;...valueN } ) : Collection` means that an unlimited number of values of any type can be passed to the function. 
-- the `any` keyword is used for parameters that can be of any type that can be stored within attributes (number, text, boolean, date, time, object, collection...). 
+- the `{ ; ...param }` notation indicates an unlimited number of parameters. For example, `.concat( value : any { ;...valueN } ) : Collection` means that an unlimited number of values of any type can be passed to the function.
+- the `any` keyword is used for parameters that can be of any type that can be stored within attributes (number, text, boolean, date, time, object, collection...).
 
+## See also
 
+[Classes in the 4D Language](../Concepts/classes.md).