API/Plug-in Center

Tutorials

Working with 4D Pointers

In all of our previous examples, we looked at how you can use the 4D Plug-in Wizard to help create the framework of a plug-in. So far we have looked at how to handle the basic API calls such as PA_Request and PA_Confirm. We have also looked at how to create and use Constants and 4D Dialogs. Before moving to plug-in areas, we need to take a moment to look at 4D Pointers. When writing code, most developers will be calling and using 4D Pointers, but how do these interact with plug-ins? Our sample plug-in will have one command. This command will determine if the Pointer is directed to a Table/Field or a Variable and return the current value of the Pointer in an Alert.

As we have mentioned in all of our previous tutorials, if you have not had an opportunity to look over Tutorial One, you should do so now. There may be areas in this tutorial that will rely on information from the first tutorial.

Tutorial 1

The first thing we want to do is create a new plug-in with the Plug-in Wizard. We only need one command, which we are calling "Tutorial_PointerInfo." The only parameter to this command is a pointer as shown below.

Inside our plug-in, we will determine what type of pointer is involved, and then return the appropriate information.

The first thing we want to do after getting the Pointer value is determine what type of pointer we are using.

PA_Pointer PointerVar; `Pointer variable sent to the Plugin
PA_PointerKind PointerKind; `The type of pointer

PointerVar = PA_GetPointerParameter( params, 1 ); `Get the pointer variable

PointerKind = PA_GetPointerKind( PointerVar ); `Determine what type of pointer

PA_GetPointerParameter is the API call that will return the Pointer value into the variable PointerVar of type PA_Pointer. This command is just like other "Get" commands such as PA_GetStringParameter. PA_GetPointerKind takes as a parameter the PointerVar variable, and returns in PointerKind the type of Pointer, for example if the Pointer is to a Table, Field, Variable, or an invalid pointer.

Next, we create a switch statement that operates on the PointerKind variable. The switch will allow us to handle each type of Pointer. Note that the Table and Field pointers are handled in the same method.

switch (PointerKind )
{
   case ePK_InvalidPointer :
    PA_Alert ("Invalid Pointer");
    break;

   case ePK_PointerToVariable :
    returnVariable( PointerVar );
    break;

   case ePK_PointerToTable :
    returnTableField( PointerVar );
    break;

   case ePK_PointerToField :
    returnTableField(PointerVar);
    break;

}

Tables and Fields

Lets take a look at how Tables and Fields are handled with the 4D API. There is one API call that will determine if the Pointer is pointing to a Table or a Field. By calling the following code, we can determine what values are returned:

short table, field;

PA_GetPointerTableField(Pointer, &table, &field);

PA_GetPointerTableField returns in &table the Table that is currently being pointed to, while &field returns the field that is currently being pointed to. If the pointer is only pointing to a Table, then &field returns a zero.

Variables

To determine what type of variable is being pointed to by the Pointer, a few more steps are needed compared to Tables and Fields. The following code determines what type of variables are being used. Note that the use of the switch statement below is similar to the switch statement we used earlier.

PA_Variable Variable;
PA_VariableKind VariableKind;
long index;
char* StrTextVar=" ";

`Get the actual variable in the pointer
Variable = PA_GetPointerVariable( Pointer, &index);

`Return the type of variable
VariableKind = PA_GetVariableKind (Variable);

`Return the type of variable
switch (VariableKind)
{
   case eVK_Real :
   PA_Alert("Real Variable: ");
   break;

   case eVK_Text :
   PA_Alert("Text Variable: ");
   break;

PA_GetPointerVariable returns the value pointed to by the Pointer. In addition, &index will hold the current index position of the variable that is an array. PA_GetVariableKind returns the type of variable. We then use this value in our switch statement to return the value of the Pointer to the user in an Alert statement.

International | Company | Contact 4D | Site Map | Privacy Policy | © 4D UK 1995-2008 | Change font size: [A] [A] [A] |