Returns zero if object was successfully activated. See Return Value Explanations below.
Procedure Activate Returns Integer
| Call: | Get msg_Activate to IntegerVariable |
The Activate message adds the object into the focus tree (by sending Add_Focus), and gives the object the focus. If the object is already active, then the focus is changed, and Add_Focus is not sent.
Activate can be augmented to add any setup processing code that the object may require before it receives the focus. Activate or Add_Focus can also be used to cancel object activation.
From a user's perspective, activation makes a dialog visible and usable. From a technical perspective, activation creates and displays the Windows dialog object and all of the child Windows objects within the dialog, places these objects in the DataFlex focus-tree, and it gives one of these objects the focus.
The Active_State property determines if an object is already active, meaning that it has already been added to the focus tree. The Window_Handle property determines if a Windows control is created. Normally, these two properties should change in tandem. If an object is in the focus tree, Active_State should be True and Window_Handle should be non-zero. The Focus property determines which object has the focus.
View (typically dbView or dbModalPanel) activation can be represented with this simplified pseudo-code. This code assumes that the view is not yet active (this is an activation and not a focus-change process).
Activate_View
Activate
Add_Focus
Page_Object (object added to focus-tree)
Activating
Page (Windows control created)
Broadcast Add_Focus to all children
Give the focus to the first focusable object (focus-change)
Activate_View is the message you should send to activate a view. The Activate message is what actually performs the activation. Add_Focus creates the Windows control and adds it to the focus tree. It does this by sending Page_Object, which adds the object to the focus tree, calls the Activating event and calls Page, which creates the Windows control. Add_Focus then sends Add_Focus to all of its children. Finally, Activate will move the focus to the first focusable child object. It does this by sending Activate to that object (where Activate is now used for focus-change).
The activation of modal dialogs is almost the same as views, but there are some key differences. You activate a modal dialog by sending it the Popup message. It does the following:
Popup
Activate
Create_Dialog (dialog Windows control created!)
----New UI level is created----
Add_Focus
Page_Object (object added to focus tree)
Activating
Page (Windows control created - except dialog)
Broadcast Add_Focus to all children
Give the focus to the first focusable object (focus-change)
The major difference here is that Create_Dialog (private) is called between Activate and Add_Focus. This enforces modality by disabling the parent objects and starts a new UI level. Starting a new UI level means that the Create_Dialog procedure is not completed until the modal dialog is closed. This completely changes the post-augmentation behavior of the Activate message. It is not executed until the modal dialog is closed. Therefore, don't use Activate for post augmentation purposes. You still use it for the same pre-augmentation techniques discussed with view activations.
There is another technical difference. For internal reasons, the modal dialog Windows control is created in Create_Dialog before Add_Focus is called. This means that the Windows control already exists when Activating is called and that Page actually doesn't need to create this control. Normally, this does not matter, but if you need to do something with the outer dialog control before it is created, you would do so in Activate. Only this dialog control is created early - all of the children of the modal dialog are created in a normal fashion (i.e., in Page following Activating).
You may notice that we are not using the Popup_Modal message for activation. This will work but it is not needed. Popup_Modal is a legacy message that calls Popup.
Most of the time when using this message, there is no need to check the return value, so you can simply use:
Send Activate of ObjectName
If you wish to make any changes in your view or dialog before activating it, you can do so before forwarding this message because the process has not really started yet.
Once you have forwarded Activate to the system classes, you have passed the point of no return and the dialog should be activated. If activation is stopped after this point, it is considered a programming error and things will not be good.
You can place augmentations after you forward Activate, but you can only do this with views and not with modal dialogs. At this point, the view is activated and some object within the view has the focus. You could change properties or even change the focus by sending Activate (focus-change) to some other object within the view.
This sample shows how to augment the Activate method to conditionally set the Value of the object (e.g. a Form) if it is currently blank.
Procedure Activate Returns Integer
String sValue
Integer iRetVal
Forward Get msg_Activate to iRetVal
Get Value to sValue
If (sValue = "") Begin
Set Value to "Type Name here"
End
Procedure_Return iRetVal
End_Procedure
Make sure to only send Activate to an object if its parent container object is active. You can use Active_State to verify that this is the case.
Get Active_State of oMyView to bIsActive
If (bIsActive) Begin
Send Activate of oMyDEO
End
If you wish to disallow activation, augment and just don't forward it.
Procedure Activate Returns Integer End_Procedure
You should never need to send Activate to activate a view or dialog.You can send Activate to change the focus. This is often done within a view or modal dialog to change the focus from one object to another. When changing the focus between views, it is recommended that you treat this as a view change. First activate the view and, if needed, send Activate to an object within the view. Remember that focus-change occurs when the dialog's Active_State is true.
If the object cannot be activated, a non-zero value is returned according to the following error conditions:
| Constant | Meaning |
|---|---|
| Error_Entering | msg_Entering returned a non zero value |
| Error_Exiting | msg_Exiting (of the current focus) returned a non zero value |
| Error_Activating | msg_Activating returned a non zero value |
| Error_Cant_Accept_Focus | The Focus_Mode of the object is No_Activate or, if the object being activated to the focus tree has its Client_Area_State set to True, none of its child objects are focusable |
| Error_Cant_Create_Tree | The object cannot be added to focus tree (probably due to lack of available memory) |
| Error_Add_To_Inactive_Object | The object was not yet active, and the focus parent object for its Add_Focus is not active |
| Error_No_Focusable_Children | If the object being added to the focus tree has its Client_Area_State set to true and none of its child objects could be added to the focus tree |