' Draft of Scripting class 25 (8/21/2011) ' These examples make use of the code generated by the WE Script Framework to explain in detail the use of commonly-used GW toolkit objects ' where-ever I have added comments, my comments will begin with '* (an apostrophe followed by a star) so you can tel them from comments which are generated by the WE Script Framework.
' example 1: ' automatic updating ' The myScriptUpdateURL variable stores the web address for the XML ' file that contains version information. This URL will be used ' when checking for updates. It's stored in a variable because it's ' used in two different GW Toolkit objects. Storing it in one location ' means only having to edit it once if the URL changes. Dim myScriptUpdateURL myScriptUpdateURL = "http://www.gwmicro.com/apps/testApp/xml"; '* note from Chip: you should edit your generated code, and change the value assigned to myScriptUpdateURL as below: '* myScriptUpdateURL = "http://www.gwmicro.com/App_Central/scriptTools.php?scriptid=1238&showXML&sh owChanges" ' this line is added to this example and is not generated by WE Script Framework '* the line above uses the web URL which makes use of the app's ID number, instead of the form which uses it's name; using this form allows you to change it's name later '* ... ' In this section of the app, we're going to monitor any changes to the ' SharedObjects object so that we can tell when objects come and go. Because ' we're interested in events that occur with SharedObjects, that's the object ' we need to connect to. We're also concerned with the state change of these ' objects, so that is the event we will connect to. Finally, the OnStateChange ' function will be called to handle the information the event provides when ' it fires (i.e. when a state change of a shared object occurs). ConnectEvent SharedObjects, "OnStateChange", "OnStateChange" ' OnStateChange is the routine that gets called with the OnStateChange event ' fires from the SharedObjects object. Sub OnStateChange(objName, objState) '* ... If objName = "com.GWMicro.GWToolkit.StandardHelpDialog" Then If objState Then Set SO_StandardHelpDialog = SharedObjects(objName, 0).NewDialog '* ... SO_StandardHelpDialog.UpdateUrl = myScriptUpdateURL '* ... ElseIf objName = "com.GWMicro.GWToolkit.CheckForUpdate" Then If objState Then Set SO_CheckForUpdate = SharedObjects(objName, 0).NewCheck '* note from Chip: the WE script framework code never uses the so_CheckForUpdate variable for anything If Not checkedForUpdates Then Queue "CheckForUpdates" checkedForUpdates = True End If Else Set SO_CheckForUpdate = Nothing End If End If End Sub '* OnStateChange Sub CheckForUpdates() ' Before instantiating the object, we need to see if automatic updates ' have been enabled. We do that by checking the Automatic_Updates ' section of our INI file for a key called OnScriptStart. If it exists, ' and the value is 1, then we'll attempt to check for a new version. If IniFile(myINIFile).Number("Automatic_Updates", "OnScriptStart") = 1 Then ' OnScriptStart was on, so we need to make sure the CheckForUpdate ' GW toolkit object is available for use (which is should be since ' this subroutine only gets called when the SharedObject is ' loaded). If Not SharedObjects("com.GWMicro.GWToolkit.CheckForUpdate", 10) Is Nothing Then ' The CheckForUpdate object is available, so we'll create our ' own copy of the object. Dim updateCheck : Set updateCheck = SharedObjects("com.GWMicro.GWToolkit.CheckForUpdate", 10).NewCheck ' Now that we have our copy, we'll provide the required ' information: our app version (which we stored in the ' ClientInformation object in the global variables section, and ' the web address to our XML file, which we also stored in ' the global variables section. updateCheck.ScriptVersion = ClientInformation.ScriptVersion updateCheck.UpdateUrl = myScriptUpdateURL ' Now that we've provided all the required information, we ' have the GW Toolkit check for an update. updateCheck.Check ' Finally, we'll set the global flag that indicates whether or ' not we've already checked for updates to True checkedForUpdates = True Else ' Since we weren't able to get the toolkit object at this point, ' we need to make sure our global flag that indicates whether ' or not we've already checked for updates is set to False. CheckForUpdates = False End If End If End Sub '* CheckForUpdates ' end of example 1 ' example 2: ' automatic error reporting '* WE Script Framework code now uses a newer version of the error reporting object: '* ErrorReporting2 is identical to the ErrorReporting object, with one additional parameter. When '* ErrorReporting2 is used, a check for updates will occur automatically after an error report dialog '* is closed. This behavior helps notify users of available app updates after an error '* occurs, even if automatic checking for updates is disabled. Refer to the '* ErrorReporting object for information on the return value, as well as additional error reporting options. '* Syntax: '* ErrorReporting(ScriptVersion, Email, PlaySound, UpdateURL) '* Dim appendGWTKErrorReportDetails ' holds additional info to be sent in error report '* if you add this global string variable to your app (which WE script framework does not), '* then you can include specialized information in the email report which is generated, such as the version of the program your app is specifically written for. '* appendGWTKErrorReportDetails = "User has program version ..." ' or whatever; you can change this variable at any time in your app '* and just having it exist will automatically cause the error reporting object to send it's contents to you in the report. '* ... Sub OnStateChange(objName, objState) '* ... ElseIf objName = "com.GWMicro.GWToolkit.ErrorReporting2" And objState Then ' The ErrorReporting2 object was just loaded, so now we can execute ' the code it provides for enhanced error reporting, assuming we haven't ' already done so (which the errorReportingEnabled variable will tell us). ' ErrorReporting2 is not stored as a global variable, because we only care ' about executing it once, and never again. If a valid email address was ' provided, the user will have the option to send error reports. If an ' update URL was provided, a check for updates will occur after the error ' dialog is closed. If Not errorReportingEnabled Then ExecuteGlobal SharedObjects(objName, 0)(ClientInformation.ScriptVersion, "[email protected]", True, "") '* note from Chip: the code generated by WE script framework does not take advantage of the new errorReporting2 object's new features, '* so you should edit the line above and replace the empty last parameter with the update URL as is done below: '* ExecuteGlobal SharedObjects(objName, 0)(ClientInformation.ScriptVersion, "[email protected]", True, myScriptUpdateURL ) ' this line is added to this example and is not generated by WE Script Framework '* I would also suggest putting the email address into your XML file, and so using a variable to retrieve it, and use this variable in the line above errorReportingEnabled = True End If '* ... end sub '* OnStateChange ' end of example 2 ' example 3: ' hotkeys ' registeredHotkeys is a global variable that will store the hotkeys ' defined in the hotkey manager. Dim registeredHotkeys : Set registeredHotkeys = CreateObject("Scripting.Dictionary") Dim SO_HotkeyManager : Set SO_HotkeyManager = Nothing ' The myStrings variable places text strings in the XML file into a ' dictionary object for easy retrieval. External strings allow for ' easy localization into other languages. Dim myStrings : Set myStrings = Strings(myXMLFile) Sub OnStateChange(objName, objState) If objName = "com.GWMicro.GWToolkit.StandardHelpDialog" Then If objState Then Set SO_StandardHelpDialog = SharedObjects(objName, 0).NewDialog '* ... If Not SO_HotkeyManager Is Nothing Then Set SO_StandardHelpDialog.UseHotkeyManager = SO_HotkeyManager End If '* ... ElseIf objName = "com.GWMicro.GWToolkit.HotkeyManager" Then ' Initialize Hotkey Manager for use with the StandardHelpDialog object for ' managing app hotkeys If objState Then Set SO_HotkeyManager = SharedObjects(objName, 0).NewDialog '* the 2 lines below cause the hotkey manager object to read hotkey definitions from the .ini file SO_HotkeyManager.INIFileName = myINIFile SO_HotkeyManager.INISectionName = "Hotkeys" '* the line below expects a dictionary of strings (from the XML file) to be assigned to the property (a dictionary object) Set SO_HotkeyManager.KeyStrings = myStrings '* there is *no* documentation on the dictionary entries needed here in this property's documentation '* (nor is it documented if this is necessary if there is hotkey info in the .ini file) '* it appears this dictionary is expected to have keys named "Keynn_Name" and "Keynn_Description", and it appears all other entries are ignored RegisterHotkeys Else Set SO_HotkeyManager = Nothing End if End If End Sub '* OnStateChange Sub RegisterHotkeys() If Not SO_HotkeyManager Is Nothing Then '* the IF below seems to be testing to see if any hotkeys are defined in the .ini file; if none are, then it looks at each one, and adds it if it's not found If UBound(Split(INIFile(myINIFile).GetSectionKeys(SO_HotkeyManager.INISectionNa me), vbNullChar)) < 0 Then '* I recommend removing this outer IF test (the one using uBound()) '* because it only allows the keys to be added if no keys at all are found in the .ini file. '* the IF below tests for the first hotkey, to see if it exists in the .ini file, and if not, then it's added If Instr(INIFile(myINIFile).GetSectionKeys(SO_HotkeyManager.INISectionName), "Key01") <= 0 Then SO_HotkeyManager.Add "Key01", "Control-Alt-Shift-X", "test_hotkey" End If '* the IF below tests for the second hotkey, to see if it exists in the .ini file, and if not, then it's added If Instr(INIFile(myINIFile).GetSectionKeys(SO_HotkeyManager.INISectionName), "Key02") <= 0 Then SO_HotkeyManager.Add "Key02", "Control-Alt-Shift-Y", "another_test_hotkey" End If End If '* If UBound(Split(INIFile(myINIFile).GetSectionKeys(SO_HotkeyManager.INISectionNa me), vbNullChar)) < 0 If Not registeredHotkeys Is Nothing Then If registeredHotkeys.Count > 0 Then '* removes any previous hotkey registrations, because this gets called after hotkeys may have been changed registeredHotkeys.RemoveAll End If End If '* now register each hotkey; '* the lines below cause the hotkey manager object to pull information from the .ini file, which is part of the information needed by the keyboard object to register the hotkeys '* the parameters for the registerHotKey method are themselves pulled out of the hotkey manager object (by specifying the ID of the hotkey; e.g. "key01") '* (these are the key specification, and the name of the subroutine to be called when that hotkey is pressed.) '* now register the first hotkey, which is global Set registeredHotkeys("Key01") = Keyboard.RegisterHotkey(SO_HotkeyManager.Key("Key01"), SO_HotkeyManager.Data("Key01"), Nothing, "Key01") '* now register the second hotkey, which is local to the running program Set registeredHotkeys("Key02") = Keyboard.RegisterHotkey(SO_HotkeyManager.Key("Key02"), SO_HotkeyManager.Data("Key02"), _ ClientInformation.Overlap, "Key02") '* and it generates registration commands for each hotkey End If End Sub '* RegisterHotkeys ' end of example 3 ' archives of these classes can be found at: ' https://www.gwmicro.com/App_Central/Developers/Interactive_Classes/
