4D Plugin SDK v11. Another minor change, real values on 10 bytes is no longer supported.

Transcription

1 4D Plugin SDK v11 4D Plugin API 4D Plugin API v11 is a major upgrade of 4D Plugin API. The two major modifications are that it is now fully Unicode compliant, and that it gives support to the new 4D pictures. Plugins that use 4D Plugin API v11 exports now the FourDPackex method instead of FourDPack. When 4D loads a plugin, if the new method is exported, 4D will load the plugin as a new plugin, and will communicate with this plugin using only Unicode, and the new Picture format. Plugins that continue to export the old method will be considered as legacy plugins, and they will continue to work using a compatibility mode exactly like with 4D If for some reasons you prefere not to handle Unicode now, you can still use 4D Plugin SDK 2004 for this purpose, plugins created will continue to work exactly the same way. 4D will also export a different function pointer to allow the plugin to call 4D, which will accept only Unicode strings. The parameter block used to communicate between the plugin and 4D is also enhanced, it starts now with some fields that will handle unicode strings. Another minor change, real values on 10 bytes is no longer supported. 4D Plugin Wizard 4D Plugin Wizard generates now projects using the latest versions of the supported development tools, Xcode and Visual Studio D Plugin Wizard generates also a sample database that holds a Plugin folder where the debug version of the Plugin will be generated, so you can test easily your Plugin by launching 4 th Dimension and opening this database. A new Release target is now created, that generates the Plugin near the project folder. The command panel is enhanced, using the new listbox, and you can now associate a parameter to a constant group, so when the 4D developer types the method in the method editor, when it s time to fill the parameter, a popup window will allow him to select directly the needed constant. The relations between the command parameters and the constants are stored in an XML files in the Plugin resource folder ( kmapper.xml ). Unicode compliancy There is now a PA_Unichar type that stands for an UTF-16 character (Unicode 16 bits character). There is also a new PA_Unistring type that is an opaque structure that holds a string. The PA_Unistring type can be manipulated only using their specific API. The new string manipulation commands are: PA_Unichar* PA_GetUnistring( PA_Unistring* ustr ); long PA_GetUnistringLength( PA_Unistring* ustr ); PA_Unistring PA_CreateUnistring( PA_Unichar* ustr ); void PA_DisposeUnistring( PA_Unistring* ustr ); void PA_SetUnistring( PA_Unistring* ustr, PA_Unichar* str ); char PA_CompareUniBuffers(PA_Unichar* text1, long len1, PA_Unichar* text2, long len2, char char diacritic, char usewildchar ); PA_CompareUnichars( PA_Unichar* string1, PA_Unichar* string2,

2 char diacritic, char usewildchar ); char PA_CompareUnistrings( PA_Unistring* ustr1, PA_Unistring* ustr2, char diacritic, char usewildchar ); long PA_GetUnicharsLength( PA_Unichar* str ); void PA_CopyUnichars( PA_Unichar* source, PA_Unichar* dest, long maxbytesize ); All the Unicode strings are NULL terminated C Strings, so you no longer need to care about Windows or Mac Characters, or about C or Pascal strings. There are no longer a distinction between strings and texts, you just have Unicode strings of any size. This can be a pointer to a any size NULL terminated Unicode UTF-16 string, or an opaque PA_Unistring object that holds the string. All the API functions that were using one byte strings are now expecting Unicode strings. Example: In previous version, you will have to write the following code, and the name buffer will be filled by either Windows or Mac characters, and C or Pascal string, depending if it runs on Windows or Mac, or if you call PA_UseMacCharacters, PA_UseAnsiCharacters, PA_UseCStrings or PA_UsePStrings. char name[256]; PA_GetUserName( name ); Now, you just have to allocate a PA_Unichar buffer that will be filled by an UTF-16 CString. The only thing that may vary is the byte swap of the 16 bytes integers, depending on the processor. PA_Unichar name[256]; PA_GetUserName( name ); Pictures manipulations Pictures in 4D v11 are now composite objects that hold native data, like BMP, JPEG, PNG, PDF, EMF and others. Those pictures are represented with the PA_Picture type, and there is a specific API to create and manipulate those pictures. 4D v11 pictures are now based on Core Graphics on Macintosh and GDI Plus on Windows. // creates a picture on any JPEG, BMP, PNG, EMF or PDF buffer. PA_Picture PA_CreatePicture( void* buffer, long len ); void PA_DisposePicture( PA_Picture picture ); // creates a CGImageRef on Mac, and a gdiplus::bitmap* on Windows void* PA_CreateNativePictureForScreen( PA_Picture picture ); // creates a CGPDFDocumentRef on Mac, and a gdiplus::metafile* on Windows void* PA_CreateNativePictureForPrinting( PA_Picture picture ); 4D Plugin API cleanup Some API relative to Macintosh resources or Altura Mac2Win technology are now removed, but the entry points still exists in 4D for compatibility reasons, and if your Plugin rely on them, you can still cut and paste the function from a previous 4D Plugin API version and call them.

3 Obsolete removed functions: PA_UseMacCharacters PA_UseAnsiCharacters PA_GetUserCharSet PA_UsePStrings PA_UseCStrings PA_GetUserStringKind PA_ReturnNullTerminatedText PA_IsReturningNullTerminatedText PA_Open4DPreferencesMacResFile PA_Close4DPreferences PA_SetGrowZone PA_Get4DWinMacOSGlobals PA_MethodNames PA_CreateTableRef PA_AddField PA_CreateTable PA_GetTemplateName PA_UpdateInternalCache PA_GetPictureHandleField PA_GetTextField PA_SetPictureHandleField PA_SetTextField PA_GetPictureHandleParameter PA_GetTextParameter PA_GetPointerKind PA_GetPointerTableField PA_GetPointerVariable PA_SetPointerVariable PA_ReturnText PA_ReturnPictureHandle PA_SetTextParameter PA_SetStringParameter PA_SetPictureHandleParameter PA_GetPictureHandleVariable PA_SetTextVariable PA_SetPictureHandleVariable PA_GetTextInArray PA_GetPictureHandleInArray PA_SetTextInArray PA_SetPictureHandleInArray PA_DetokenizeInTEHandle PA_GetBackupStatus PA_NewLog PA_OpenLog PA_GetLogInfo PA_GetLogField PA_GetTextLogField PA_GetPictureLogField PA_PerformLogAction PA_GetLogFieldKind PA_GetResourceNameList PA_CountUsers PA_GetIndUserName PA_CountUserGroups PA_GetIndGroupName PA_RedrawWindow PA_Dial4DSetArrayText

4 Mac Intel support 4D v11 is available on the Macintosh platform as a universal binary. On a Mac PPC, 4D v11 uses PPC code and will load only plugins that contain PPC code. On a Mac Intel, by default 4D v11 uses Intel code and will load only plugins that contain Intel code. If the user on a MacIntel needs to use a plugin that doesn t contain Intel code then he must ask to open 4D v11 using Rosetta in the Finder information window on 4Dv11. It is therefore very important to provide plugins as universal binary so that users won t have to run their 4D application in Rosetta emulation mode. Note 1: Even if 4D 2004 is not universal binary, it can load the ppc code from universal binary plugins. That means you may deliver the same universal binary plugin for both 4D 2004 and 4D v11. Note2: The recommended format for a 4D plugin is a bundle located in the Plugins folder next to the database or inside the 4D bundle. By having a Windows folder inside the plugin bundle folder, you can provide your customers one single bundle usable on both Macintosh and Windows platforms. How to build a universal binary plugin. If you re already using Xcode, it may be as simple as checking a check-box. But it may be more complex depending on your code due to differences between Intel and PPC architectures. For those who are using the now defunct Codewarrior product which is not capable to produce a universal binary, we recommend to use Xcode. Recommended reading: Important notice: In your Xcode project, make sure you checked Symbols Hidden by Default and Inline Functions Hidden to avoid conflicts with 4D symbols. For more information see: SymbolVisibility.html Altura 4D v11 will be the last major version to support plugins that use ASINTPPC.dll. If your plugin still relies upon this dll, we encourage you to do what is necessary to remove this dependency. New entry points have been added in 4D 2004 and 4D v11 to make this transition easier. Altura support has been removed from 4D Plugin Wizard v11.

5 Macintosh Resources Because there s no easy way to manage Macintosh resources on Windows and because Apple encourages finding alternative solutions, we started to move to other solutions such as XLIFF files instead of STR# resources and individual picture or icon files instead of picture resources. We suggest you adopt similar solutions for your plugins. Unicode 4D v11 has made an important step forward full Unicode adoption. This will allow a better handling of multi-language text manipulation. The new 4D Plugin SDK uses exclusively this character set in UTF-16 encoding. UTF-16 is the encoding used natively by both Windows and Carbon/Cocoa. We encourage you to also use Unicode exclusively in your plugins. Pictures 4D used to be based upon the now deprecated Quickdraw PICT format for C_PICTURE data type. 4D v11 implements a new imaging architecture that doesn t depend on this format anymore. The PICT format is still supported but is now optional and considered as one format among others. 4D Plugin SDK v11 provides now a PA_Picture type with the entire necessary API to manipulate the new C_PICTURE data. New 4D Limits Texts limit has been extended to 2Go instead of 32ko. That means that the length field when coded on a short, such as in the PA_VARIABLE struct definition of the previous plugin sdk, is irrelevant for text greater than 32Ko and is set to -1. When the length field is -1 call PA_GetHandleSize to know the actual length. Set it to -1 for texts greater than 32ko. When using the new 4D Plugin SDK v11 which is Unicode based, you don t have anything special to do since new APIs have been added to properly manipulate Unicode texts. Alpha fields can now be longer than 80 bytes. The new limit is 255 bytes. 4D used to be limited to 255 tables and 511 fields each. It s now for both. That means if you used to store a table id or a field id in a short integer, it should still be ok. The user can now delete fields and tables. Don t assume that a table or field id is valid just because it is between two valid table or field ids. To know if an arbitrary table or field id is valid, you may call PA_GetTableName or PA_GetFieldName and check for error code or an empty name string. Also entry points EX_COUNT_TABLES and EX_COUNT_FIELDS actually return the last table id and the last field id respectively. Dial4D 4D v11 loads the 4D dialogs you may have in your plugins in their own execution context the same way as the new components architecture.

6 That means the 4D code running in your dialogs has the same restrictions regarding access to the main database objects as components. Please see the 4D documentation regarding components for that matter. 4D dialogs may now have their own inter-process variables but the meaning is different than in a regular database because it is in no way related to multi-process. Inter-process variables in a 4D dialog are maintained until the plugin is unloaded so you can keep & share 4D variables between your 4D dialogs. View Embedding on MacOS On MacOS, the 4D developer can decide to activate the compositing mode on windows he creates using the Open Window command by passing the 4096 modifier value (see 4D v11 documentation). In this mode, 4D creates a custom HIView in which live all 4D controls. When the compositing mode is activated you must take special care to things like event handling and subcontrols creation. For example, if you have some code that uses NewControl to attach a new control in the window, you must modify your code to attach your control to the proper HIView. See Apple documentation regarding compositing mode and Controls. The easiest way to test your plugin in a 4D window with compositing mode is to ask for the metal look in the form properties. The metal look forces the compositing mode. If you want to provide a plugin area that works properly with or without the compositing mode you may have to check the compositing attribute of the 4D window using the GetWindowAttributes system call. The compositing mode is currently not set by default because of compatibility problems with unprepared plugins but that may change in the next major release of 4D. View Embedding on Windows If you implement your plugin area on Windows using a child window, you should call PA_SetPluginAreaClipMode at init time to tell 4D you are fully responsible for the redrawing of your plugin area. This will reduce flickering because 4D won t erase the contents of your plugin area before asking you to draw it and make your plugin compatible with the offscreen drawing architecture of 4D. PA_SetPluginAreaClipMode may also be used on MacOS although it should not be necessary if you implement your plugin area as a HIView.