Destination (Magic xpa 3.x)
This property specifies whether the called program or subtask will be opened in one of the Subform controls of the currently running task or in its own window.
When developing SDI applications, each called program opens its own window. There are some scenarios in which different programs need to be opened in the same window, for example:
-
Wizard like application – in which the program calls another program or task which should replace the currently running program.
-
Running a program from the menu which should close the currently running program and show another program in its place.
The Destination property provides an easy way to open a program in a pre-defined region on the task’s form.
This property is relevant for Online and Rich Client programs. (Online support – Since version: 2.1)
-
In Rich Client, the property will search the destination in the Runtime tree.
-
In Online, when the destination is a subform, the property will only search subforms that are children of the current task.
-
In Online, when the destination is a frame, the property will search in the Runtime tree. This functionality is provided for backward compatibility of calling a program defined as a splitter child into a frame defined in another program. (Since version: 2.5) Exceptions for this behavior are listed in the Backward Compatibility section below.
The value for this field is a control name, which is either entered (Since version: 1.9) or selected from a list by clicking on the Zoom button or by pressing F5. The list shows all the Subform controls from the current task and higher level tasks.
Any change in the Subform control name on the form (or deletion of the subform) will not change the value of this property.
Note:
-
This property is disabled in the Main Program.
-
Unicode is not supported for this property.
-
Before initiating the new program on the Subform control, the currently running program will be exited. If there is an error or anything that stops the program from exiting, the user will have to fix and execute the Call command again.
-
If the Call operation with a defined Destination is performed before the task's form is loaded (such as from the Task Prefix), it will only be executed once the form is displayed.
-
If the Call operation with a defined Destination is performed after the task has ended (such as from the Task Suffix), this property will be ignored and the called program or task will be opened in a new window. If the called task has a non-modal window type, it will be closed immediately.
-
In Runtime, if it is not possible to open the task in the defined Destination, the task is opened in a new window.
When calling a task to run in a Destination subform, that subform can be defined at one of these:
-
Caller task – The Destination subform is inside the caller.
-
Parent task – The Destination subform is a sibling to the caller. This is only supported if the caller task is also a subform. (Since version: 1.9)
If there is more than one subform with the same name, Magic xpa will search from the current task upwards (current task, then parent, and so on). The search will not include any subform where the current task (or its ancestors) is running. If no subform is found, the program will be called as if the Destination property is blank.
Since version: 2.5
In Online, the following scenarios were supported when using a splitter:
-
A task with a splitter raised an event that was defined in a parent task. The parent task event handler called a program that was defined to be opened as a splitter child and as such, the called task was opened in the caller task form.
-
A task with a splitter called a Batch program that called an Online program. The Online program was defined as a splitter child and as such, the called program was opened in the caller task form.
This behavior is also possible when using frames, however, these tasks will open as phantom tasks This means that the following limitations apply:
-
When clicking on the frame, the logic in the handler that calls the frame program will be executed.
-
The end user cannot tab into the frame.
-
The Automatic Refresh and Refresh when Hidden properties are not supported. If arguments that were passed to the program running in the frame are changed, the view will not be refreshed automatically since the recompute is working only on controls from the current task and the caller for the subform/frame task is a parent task.
-
The Retain focus property and the Subform Refresh event are not supported.
Note that the handler that calls the destination program cannot be defined in the Main Program.
Retain Focus
How Do I Dynamically Replace the Content of a Subform?
The Online and Rich Client Samples projects (program SB11 and RSB11)
