Using a 4D Dialog in a Plug-in
In our next tutorial, we are going to look at how you can create a 4D Dialog and then use that dialog inside a plug-in. As we have stated before, it is highly recommended that you look at the first tutorial before proceeding any further. Tutorial One covers the basic usage of the Plug-in Wizard. In this tutorial, we may use functions that are explained in the first tutorial.
We want to create a 4D Dialog within 4D that can contain 4D code or be used in calls to API commands to display from within a 4D plug-in. The plug-in itself will contain a resource of the 4D Dialog, which it can then use to display the dialog.
Here are a few areas of warning regarding what you cannot do in a 4D dialog that is to be used in a plug-in. You cannot call methods from the 4D Dialog. You must place all of your code within the body of the dialog, whether that is inside the Object Methods or the Form Method. From either of these locations you cannot call a method to complete the functionality. All the code must reside inside the Form. For a complete explanation of how 4D handles a Dialog from within, see the API Reference document starting on page 151.
Creating a 4D Dialog
The first thing we want to do is create a 4D Dialog to be used in our plug-in. For our example we are going to create a simple 4D Dialog that contains an Enterable Longint variable with two buttons to retrieve the value and display in an Alert. One button will use API calls to return the value, while the other will use 4D commands. Also included are two radio buttons with code that sets an enterable string area using API commands. The dialog will also have a Close and OK button with automatic actions.
Here is what our 4D Dialog looks like:
http://www.4d.fr/4ddoc67/CMU/CMU84460.HTM
Creating a 4D Dialog
The first thing we want to do is create a 4D Dialog to be used in our plug-in. For our example we are going to create a simple 4D Dialog that contains an Enterable Longint variable with two buttons to retrieve the value and display in an Alert. One button will use API calls to return the value, while the other will use 4D commands. Also included are two radio buttons with code that sets an enterable string area using API commands. The dialog will also have a Close and OK button with automatic actions.
Here is what our 4D Dialog looks like:
The only 4D code being used is behind the "Get Longint 4D" button:
ALERT("Longint value: "+String(vLongint))
The name of our dialog is "4DdialogInPlugin." This will be important later when we open our dialog with the API call PA_OpenDialog. This is because the API command will use the name as a reference to open the correct dialog.
The Close and OK buttons are using 4D automatic actions of Cancel and Accept respectively. The rest of the code will be API-based code from our plug-in. When we are finished with our new dialog, we can save this to disk as a "FO4D" resource.
Saving dialogs as "FO4D" resources is a basic operation: bring the structure window to front and press (Ctrl-9) under Windows or (Command-9) under MacOS. 4th Dimension generates one resource file per table at the top level of the hard disk. Those files are ResEdit files under MacOS and .RSR files under Windows. Each resource fork contains as many 'FO4D' resources as the table has forms, plus the linked 'CC4D' (which contain the form/object methods), plus some 'STL#' resources that handle the styles used in the forms. At least, each 'FO4D' resource has the name of the form. This is important since this name is used by the PA_OpenDialog routine.
IMPORTANT NOTES
- The structure window must be the front window. Pressing the shortcut with another window in front will do nothing.
- The shortcut uses the 9 of the numeric pad. Pressing Shift-9 will not generate the resource files. It may happen that users of portable computers could not save their dialogs unless they plug in an extended keyboard or a numeric pad.
As 4th Dimension generates one file per table, the developer should create one structure and build dialogs in the first table. Doing this avoids the creation by 4th Dimension of multiple files that contain multiple FO4D resources.
Once the dialog has been saved on disk, the developer can move the dialog resources to the Plug-in resource fork. This is a basic operation on Macintosh, using ResEdit. The best solution is to use the 4D Plug-in Wizard to merge the dialog resource files into the Plug-in resource file. To do so, check the "Use 4D Dialog file" check box on the project window, and select the dialog resource file you want to use.
Plug-in command
We only need one plug-in command. This command will receive the name of the 4D Dialog we want to open from the plug-in. We are passing in a string variable called NameOfDialog.
Plug-in API Calls
There are several important API commands that each developer should become familiar with when using a 4D Dialog in a plug-in. Instead of copying the code from our sample plug-in, the main API calls are discussed here along with an example of each API call. To see the full code listing, take a look at the sample plug-in project with either Codewarrior or Visual C++.
Note: The Get/Set and Update variable commands only apply to using the API calls to retrieve and set variables. Remember that you can use 4D code inside the 4D Dialog, which does not require the API calls to get and set the variables. This will be explained in the section "API calls verses 4D commands."
Creating and Opening a Dialog from the Plug-in
PA_NewDialog: The routine PA_NewDialog creates a new dialog context and returns a reference to that context. This context will be used in any subsequent call referring to this dialog. A dialog context handles the dialog variables so that the dialog can be used in compiled mode. Calling this routine should be the first thing done when using a 4th Dimension Dialog. In the improbable case where it could not allocate the context, PA_NewDialog returns 0L.
Example:
dialog = PA_NewDialog();
PA_OpenDialog: The routine PA_OpenDialog opens the dialog saved as a FO4D resource of name dialogName in a new window. If closeBox is 1, the window will have a close box. This resource is associated with the context dialog. PA_OpenDialog returns the dialog reference context. If dialog is a dialog context, PA_OpenDialog returns it unchanged. If dialog is 0L, 4th Dimension creates a dialog context and returns it.
Example:
PA_OpenDialog( dialog, NameOfDialog, 0 );
PA_ModalDialog: The routine PA_ModalDialog is called repetitively in a loop after having displayed a dialog (by calling PA_NewDialog and then PA_OpenDialog). It provides information on the last user action. If the user validates the dialog, PA_ModalDialog returns 1. If the user cancels the dialog, PA_ModalDialog return 2. If the user modifies any variable that does not validate or cancel the dialog, PA_ModalDialog returns 0. dialog is the dialog reference, as returned by PA_NewDialog or PA_OpenDialog. The lastVarName is the name of the last modified variable.
Example:
okOrCancel = PA_ModalDialog( dialog, lastVarName );
Getting and Setting Dialog Variables Using Non-4D code
PA_Dial4DGet<VarType>: The routine PA_Dial4DGet<VarType> gets the value of a variable whose name is variable and returns its value. This command is preferred over the PA_Dial4DGetVariable call because it handles the type casting for the developer.
If this command is applied to an array, it will return the current element of the array.
Example:
LongintVar = PA_Dial4DGetLong(dialog, "vLongint");
PA_Dial4DSet<VarType>: The routine PA_Dial4DSet<VarType> sets the value of a variable whose name is variable to the value newValue. This command is preferred to the PA_Dial4DSetVariable call because it handles the type conversion for the developer.
If this command is applied to an array, it will set the current element of the array.
Example:
PA_Dial4DSetLong(dialog, "vLongint", LongintVar);
Updating 4D Variables
PA_Dial4DbeginUpdateVariables: You must call PA_Dial4DBeginUpdateVariables if you want to modify any variables while the dialog appears on the screen. After you call this command, 4th Dimension will record all variables that you will modify further. When you balance this call with a PA_Dial4DEndUpdateVariables, 4th Dimension will redraw all variables that you have modified/enabled/shown/hidden between the two calls.
Example:
PA_Dial4DBeginUpdateVariables(dialog);
PA_Dial4DendUpdateVariables: You must call PA_Dial4DEndUpdateVariables after changing a few variable values. You must have called PA_Dial4DBeginUpdateVariables before calling this command. This command tells 4th Dimension that you are done changing variable values and/or states. After this command, 4th Dimension updates your dialog on the screen, re-drawing only the modified variables.
Example:
PA_Dial4DEndUpdateVariables(dialog);
Closing the Dialog
PA_CloseDialog: The routine PA_CloseDialog closes the dialog referenced by dialog. It disposes of all allocated memory used by objects such as the dialog window or the variables used, and switches back to the process context. Dialog variables and objects can no longer be used once this function has been called.
Example:
PA_CloseDialog( dialog );
API Calls versus 4D Commands
As we mentioned earlier, you can use either API commands to get and set variables, or you can use 4D code. This may sound a bit confusing, so let's take a look at the differences.
Let's look at the example of a Longint variable called vLongint on our sample dialog. In our button called "Get Longint 4D" the method contains the following 4D code:
ALERT("Longint value: "+String(vLongint))
Now in contrast, our button called "Get Longint API" is using the following API calls from our plug-in:
LongintVar = PA_Dial4DGetLong(dialog, "vLongint");
StrOne = "Longint value: ";
StrTwo = (char*)LongintVar;
strcat(StrOne, StrTwo);
PA_Alert(StrOne);
Both sets of code are returning the same value, but doing it in different ways. This is one of the strengths of using a 4D Dialog inside a plug-in. You have the choice of using current 4D Code to create the dialog functionality, or you can use API calls to help enhance the dialog. It is not necessary to use API calls within the 4D Dialog. At a minimum you would only need to use API calls to open the 4D Dialog.
Basic Structure of a Dialog Plug-in
The outline below shows in pseudo-code how the flow of a 4D Dialog plug-in would work:
Dialog = PA_NewDialog()
PA_OpenDialog(Dialog, Dialog Name)
Do
okOrCancel = PA_ModalDialog(Dialog, LastVariableClicked)
Compare the LastVariableClicked
Several lines of code would be needed here to see which
variable was returned from PA_ModalDialog. Depending on what the results
were, different actions would take place.
While (OkorCancel == 0)
Inside the Do-While loop, you would be using such commands as the Get/Set Variable and the Update Variables.
International |
Company | Contact
4D | Site Map | Privacy
Policy | © 4D UK 1995-2008 | Change font size: [A]
[A]
[A]
| 