home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 June / PCWorld_1999-06_cd.bin / software / Servis / DreamK / readme.txt < prev   
Text File  |  1999-05-06  |  9KB  |  175 lines
  1. SDK for Dreamkeys v1.02 (spec-ver 1)
  2.  
  3. Here's the Software Development Kit for DreamKeys. It specifies how the DLL should be made,
  4. and how a plug-in is made for DreamKeys.
  5. The Project File is for Microsoft Visual C++ 6 SP2 and probably won't work on older versions.
  6. However, there are just a few things you need to do when you make a new project in Visual C++ 5.
  7. All functions available are explained. In the sample-code, extra information is provided as
  8. comments. You can build and test this sample code without trouble, so you can use it as a
  9. framework for your own plug-ins.
  10.  
  11. Making a new project:
  12. -Create a new "Win32 Dynamic-Link Library" project.
  13. -In the project settings, you'll need to set the calling convetion to __stdcall: Project|Settings,
  14. then the C++ tab, select "code generation" in the drop-list and in the "Calling convention" select
  15. "__stdcall". I've done this, so people programming in other languages also can make plug-ins.
  16. __stdcall is just the standard way of passing arguments and handling the stack.
  17. -Now add the source and header files you want. Don't forget you'll need to tell which functions
  18. are exported. Most easy way is using the .def file provided in this SDK. You can leave out unused
  19. functions. Exported functions have the same name as the functions in this source, so no name
  20. decoration is allowed. Using the standard .def file, you don't need to bother with this.
  21. -DreamKeys plug-ins always have the name DK_*.dll, so when you make your own plug-in, make sure
  22. it starts with "DK_" and has the .dll extension. If your DLL has another name, you'll need to
  23. rename it, or the control panel won't find it.
  24.  
  25. The source:
  26. There are required functions and functions you may omit. Required functions MUST be made,
  27. otherwise, things WILL crash and that's not what we want. The other functions can be used freely,
  28. so if you want to provide more infomation about the plug-in using the Control Panel, you can
  29. implement the MoreInfo function.
  30.  
  31. REQUIRED are:
  32. -DLLName
  33. -NumberOfHotkeys
  34. -DefaultHotkey
  35. -HotkeyName
  36. -HotkeyPressed
  37. -DLLSpecVersion
  38.  
  39. NOT required are:
  40. -MoreInfo
  41. -SaveSettings
  42. -LoadSettings
  43. -AcceptAuto
  44. -Config
  45.  
  46. The functions:
  47.  
  48. char* DLLName(void)
  49. The name of the plug-in. This is printed in the "Plug-in name" field of the control panel.
  50. IN: none.
  51. OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
  52.      fits in the control panel.
  53.  
  54.  
  55. int NumberOfHotkeys(void)
  56. The number of hotkeys that are used by this plug-in (a plug-in can have more than one hotkeys)
  57. This number is used extensivly and is printed in the "Number of Hotkeys used in this Plug-in"
  58. field in the control panel.
  59. IN: none.
  60. OUT: return an integer >=0. 0 doesn't make much sense, but is supported.
  61.  
  62.  
  63. void DefaultHotkey(int iHotkeyNr, int &iVkCode, int &iMod)
  64. Although the user can change the default hotkey combination, the plug-in provides a default
  65. combination for every hotkey. iMod specifies which of the modifiers (Control, Shift, Alt) must
  66. be pressed, iVkCode is the virtual key code of the key to activate. Usually this is simply the
  67. same character as the key.
  68. IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
  69. OUT: put the values you want in iVkCode and iMod, see the source for more details. iVkCode and
  70.      iMod can both 0, when both are 0, no hotkey is used.
  71.  
  72.  
  73. char* HotkeyName(int iHotkeyNr)
  74. Provides a name for every Hotkey Action. This name is used in the "Hotkeys used by Plug-in" field
  75. in the control panel. Make sure that when you place the words "In order to" in front of it, you
  76. get a nice sentence.
  77. IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
  78. OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
  79.      fits in the control panel.
  80.  
  81.  
  82. void HotkeyPressed(int iHotkeyNr)
  83. This function is called when a key combination associated with the plug-in is pressed. Which
  84. hotkey is pressed is provided in iHotkeyNr. Do whatever needs to be done to do the action.
  85. IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
  86. OUT: none.
  87.  
  88.  
  89. int DLLSpecVersion(int DKVersion)
  90. Verifies the plug-in and control panel can work with each other. The plug-in can decide if it
  91. can work with the version of the Control Panel, and the Control Panel can decide if it can work
  92. with the version of the plug-in.
  93. IN: DKVersion, integer, provides the specification-version (spec-ver) with which the Control Panel
  94.     communicates with the plug-ins. In DreamKeys v1.01 this is 1, but when the specifications
  95.     change, this will be a higher number. If your plug-in is written for spec-ver 3, and the
  96.     Control Panel reports in communicates with spec-ver 2, your plug-in is most likely to fail
  97.     and/or crash.
  98. OUT: To avoid these crashes, return 0 if your plug-in is made with a higher spec-ver than the
  99.      Control Panel, otherwise, return the spec-ver number for with which this plug-in was made.
  100.  
  101. Note: you CAN provide backwards compatibility in the plug-in. If the Control Panel reports it is
  102. using spec-ver 1, and your plug-in is written for spec-ver 2 it still might be possible to use
  103. the plug-in, as long as you stick to the rules of spec-ver 1. When you know your plug-in will
  104. work with an older version of the Control Panel, simply return the spec-ver of the plug-in.
  105.  
  106. As for now in spec-ver 1, you can simply return 1 without any checking.
  107.  
  108.  
  109. char* MoreInfo(void)
  110. This text is printed in the MessageBox when the user pressed the "More Information" button.
  111. Usually, this is a short description and a copyright notice.
  112. IN: none.
  113. OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
  114.      fits in the message box. Use '\n' to get a newline.
  115.  
  116.  
  117. BOOL AcceptAuto(void);
  118. Some plug-ins won't work correctly if they operate in "Auto" mode, since the plug-in is loaded
  119. and unloaded immediatly after the action is completed. Quick!hide, for example, need to store
  120. information. This information is lost when the plug-in is unloaded.
  121. With this function, you can tell the Control Panel if it is possible to use the plug-in in
  122. Auto-mode.
  123. IN: none.
  124. OUT: return 0 (false) if the plug-in won't work correctly in Auto-mode. Otherwise return
  125.      whatever you want (true).
  126.  
  127. Note: The control panel only issues a warning when a user tries to switch the plug-in to "auto"
  128. mode, when AcceptAuto is false. Look at Quick!Hide for an example.
  129.  
  130.  
  131. void Config(void);
  132. When the user presses the "Other plug-in settings" button, this function is called. You can open
  133. a dialog so the user can make additional settings for the plug-in. Both ICQ Shortcut and
  134. Quick!Start use this feature.
  135. IN: none.
  136. OUT: none.
  137.  
  138.  
  139. BOOL LoadSettings(int iNumber, char *&pszKey, char *&pszValue, int &iValueSize)
  140. Provides an interface to load settings from the DreamKeys.ini file.
  141. This function is implemented because I think it's a good thing when all settings are together in
  142. one .ini file. This way, settings can be copied and backuped easily.
  143. LoadSettings is the first thing executed after the version check.
  144. IN: iNumber: integer, starts at 0, increased by one every call to LoadSettings.
  145.     pszKey: a pointer to a zero-terminated string with the key- or item-name of which data you
  146.     want to read. Make this static or global!
  147.     pszValue: a pointer to a zero-terminated string which will receive the data.
  148.     ALLOCATE the memory before passing this pointer, and/or make it a global variable!
  149.     iValueSize: put the size of pszValue in this variable.
  150. OUT: return TRUE when you need more things to load, otherwise return FALSE (0)
  151.  
  152.  
  153. BOOL SaveSettings(int iNumber, char *&pszKey, char *&pszValue)
  154. Provides an interface to save settings in the DreamKeys.ini file. Use this in conjuction with the
  155. LoadSettings function. You can only save strings, so you'll have to convert numbers to a string.
  156. Also, avoid using key names starting with "Mod" or "VkCode" as this is likely to interfere with
  157. other things.
  158. SaveSettings is executed just before the plug-in is unloaded.
  159. IN: iNumber: integer, starts at 0, increased by one every call to SaveSettings.
  160.     pszKey: a pointer to a zero-terminated string with the key- or item-name of which data you
  161.     want to save. Make this static or global!
  162.     pszValue: a pointer to a zero-terminated string which contains the data to be saved. Make sure
  163.     this data is available outside the function, so make it global or static!
  164. OUT: return TRUE when you need more things to save, otherwise return FALSE (0)
  165.  
  166.  
  167. Need more help making plug-ins?
  168. I'll be glad to help you out with problems. Keep in mind that I've only used Visual C++, and I've
  169. no experience with Inprise products. Also, my knownledge is limited to the Win32 API.
  170. e-mail: Randy@dgdr.com
  171. ICQ UIN: 1384866. When you ask for my authorization when you want to add me to your ICQ list,
  172. please make clear it's about DreamKeys; I get a lot of requests from people asking me if I can
  173. "hack" something and other things I'm not interested in...
  174.  
  175.