This changes the current group for use with the actions and expressions in the “Current Group” sub-menus. The second parameter allows you to specify if the object should ensure a new group name is specified. If it is set to 0, then the current group is set to the first parameter, no matter what. If the second parameter is set to 1, then the current group is set to the first parameter with ‘.x’ appended to the end, where x is the lowest number which means the group does not exist. For instance, if the first parameter is set to group and the second parameter is set to 1, then if there already exist groups group, group.1, group.3, then the current group would be set to group.2.
All the actions in this sub-menu are identical to the more general version of the action, except with the “group” parameter set to the current group, as specified by the Set Current Group action. There is one remark to be made. The Rename Group action will also change the current group to the new name of the group.
This action sets the value of the specified item to a number. The third parameter asks whether the number specified in the forth parameter will be an integer (whole number) or floating point number (not whole number). The advantage of specifying floating point is obviously that the digits after the decimal point will be saved. The disadvantage of selecting ‘floating point’ is that if you are just working with large whole number, they may get approximated. If ‘integer’ is selected then there are a larger range of values until it is approximated. For instance, if 1, 000, 002, 124 is stored as an integer, it can be received exactly. However, if the floating point option was used it would actually be stored and received as 1, 000, 002, 112. Therefore: If you just want to store whole numbers, use the whole number setting. When integer mode is used, large integers can ‘wrap around’ to large negative integers. When the floating point mode is used, you may sometimes notice that numbers aren’t stored exactly as you would expect. This is because some numbers cannot be exactly represented in floating point. If the number is extremely large, it may be represented as ‘1.#INF’.
This action sets the value of the specified item to a specified string.
This action sets the value of the specified item to the MD5 hash value from a string. What is meant by this is a fixed length code that represents the string. For instance, some strings hash as follows:
Obviously, many strings might harsh to the same value, but there are still a large number of different possible codes. Therefore it can be used to store a password without anybody being able to work out what the password originally was. Hashing is case sensitive regardless of case sensitivity options. Use the Item Has Hashed Value condition to see if the value of a particular item is the hash generated from a particular string.
This allows some attributes of an active object (or an object with similar property to an active object) to be saved easily. A group is specified and items in that group store various values. The second parameter allows the user to specify if the position of the object is saved. If this parameter is non-zero, then the following items will be stored in the group:
The second parameter allows the user to specify if the alterable values of the object is saved. If this parameter is non-zero, then the following items will be stored in the group:
The first parameter allows an object to be specified. The second parameter specifies a group. The various item in this group are loaded into the object. The meanings of the items are as specified above in the Save Object section, If any values are missing, they will not be loaded.
Saves the specified position as a string in the form “x position,y position”. Use the Get X Position and Get Y Position expressions to easily receive the x and y positions.
This saves the global values and strings into the specified group. Global strings are written in the form strn and global values in the form valn. Single digits values of n will have a zero prefixed, for instance str03 instead of str3. vals specifies the number of global values and strs specifies the number of global strings.
This load the global values and strings from the specified group. All present values in the form strn and valn are loaded (for n at least two digits long and less than strs and vals). The number of global values and strings will be dynamically altered if required.
“Add Repeated Item” will automatically rename the item name (or group name) to a similar but unique name, so data can easily be saved without overwriting anything else. The first parameter specifies a group name, the second an item name, the third the value for the item to have and the forth will decide the mode. If the last parameter is 0 then the action will ensure the item is unique by changing the item name. It will do this by appending ‘.n’ to the end of the name, where n is the lowest whole number such that the item does not already exist in the specified group. It will not change the group name. If the last parameter is 1 then the action will ensure the item is unique by changing the group name. It will do this by appending ‘.n’ to the end of the name, where n is the lowest whole number such that the group does not already contain an item with the given name. The group may already exist. It will not change the item name. The value must be specified as a string. Use the Str expression to convert a number to a string. See also the Set Current Group action, which can set the current group to a new group using a similar renaming system.
The actions in this menu allow items to be moved and copied between groups and groups to be renamed and copied.
This action will rename a group. The third parameter specifies what to do if a group with the new specified already exists. This can be one of the following:
0 (Overwrite) The existing group with the destination name is overwritten. 1 (Merge) The old group and the new group are merged together. The group being renamed has priority if the two groups have items in common. 2 (Never Overwrite) If a group already exists with the destination name, the action fails.
This action renames an item within a group. It will not move it outside the group. The forth parameter specifies whether this operation will allow another piece of information to be overwritten. If it is set so that overwrites are not allowed and there is already an item with the destination name in the group, this action will fail. Note that Move Item is a more general version of this action.
This action allows an item to be moved from one group to another, possibly changing its name in the process. The fifth parameter specifies whether this operation will allow another piece of information to be overwritten. If it is set so that overwrites are not allowed and there is already an item with the destination name in the destination group, this action will fail. Note that Rename Item and Move Item between groups are less general versions of this action.
This action allows an item to be moved from one group to another, keeping its item name intact. The forth parameter specifies whether this operation will allow another piece of information to be overwritten. If it is set so that overwrites are not allowed and there is already an item with the same name in the destination group, this action will fail. Note that Move Item is a more general version of this action.
This action allows a complete group to be copied into another group. The third parameter specifies what this operation will do in the event the destination group already exists. The options are:
0 (Overwrite) The existing group with the destination name is overwritten. 1 (Merge) The old group and the new group are merged together. The source group has priority if the two groups have items in common.
This action copies an item. The destination group name and item name can be specified. This action will always overwrite any existing data, there is no option for it. If you wish to ensure it does now overwrite data, check if it exists using the Group Has Item condition.
As the name suggests, this action can perform various operations, such as shifting data, sorting data and shuffling data. The first parameter selects the operation to be performed, and the second parameter selects the group for it to be performed on. The various operations are listed below. The following group is used for examples:
Sort Sorts the values without changing the item names. For instance, the example would be sorted as:
Shuffle Randomly swaps the values about, whilst keeping the item names unchanged. Shift Up/Down ‘Shift up’ shifts all the values up, discarding the first value and deleting the last item name. ‘Shift down’ is similar. Cycle Up/Down ‘Cycle up’ shifts all the values up, and sets the last item name to the old first value (hence ‘cycling’ the values). ‘Cycle down’ is similar. Reverse Reverses the pairing between item names and values. For instance the example would become:
Swap items and values Swaps the item names for their values. If there are repeats, the last is used. For instance, on the example group:
Renumber items Changes each item name to a number. For instance, the example becomes:
This menu contains a variety of actions which can delete items.
This action deletes a group. All items in the group are removed. If the group does not exist the action does nothing.
This action deletes an item in a group. If the group or item does not exist, this action does nothing. If the ‘Allow empty groups’ option is not checked (by default it is not), and the item removed is the last in a group, the whole group will be removed. Otherwise it will still exist, although it will be empty.
This action deletes all items with a specified name, regardless of what group they reside in. The name of the item to be deleted is in the first and only parameter.
This action deletes all items which match a search. Search patterns can be specified for the group name, item name and item value. These are the first, second and third parameters respectively. For an item to be deleted, it must match each search pattern. In a search pattern, ‘.’ means any single character and ‘*’ denotes any sequence of characters. The final parameter decides if the search is case sensitive. Even if it is set to 1, the group and item names will only be case sensitive if object is in case sensitive mode.
Removes all data in the object. It does not change the current file. Contract this to ‘New File’.
This menu contains a variety of actions which can allow the object to be searched.
This action performs a search. It looks at each item in the Ini++ object (subject to optimizations) and compares the group name, item name and item value to the three patterns given. If an item matches all of these (unless the ‘match any of these conditions’ option is used), it is added to the search results. The search results can be accessed by expressions in the ‘Search Results’ section of the expressions menu. The patterns are usual strings. However, the character ‘.’ (dot) denotes “any character”, and the character ‘*’ (asterisk) denotes “any sequence of characters”. For instance:
You can also prefix the expression by an exclamation mark (‘!’) for it to mean the opposite. For instance,
The first parameter is the pattern for the group. The second is the pattern for the item name, and the third is the pattern for the item value. The forth parameter determines which settings are used. These are as follows:
Case sensitive This determines if the search is case sensitive. When the Ini++ object is not in case sensitive mode, this option will only apply to the ‘value’ pattern, with the other two patterns not case sensitive. When the Ini++ object is in case sensitive mode, it applies to all patterns. Match any of the conditions An item is added to the search results if it matches any of the three conditions. Without this, it must match them all. Note this mode is slower than other modes as it must search every group. Add group name only to results When this is selected, only the name of the group is added to the results if an item is found in the group. The item name and value fields are left blank. This is useful when the aim of the search is to find groups with a certain property. It also allows you to use ‘and’, ‘or’ and ‘xor’ in these situations.
You may also select how the results are combined with the old results (if at all). The possibilities are:
Discard previous results The old search results are cleared before the search is performed. Or The results are merged with the old results. And An item will only be in the results if it is in both the old results and satisfies the new search. Xor An item will be in the results if it was in the old results or if it satisfies the new search, but not both
It should be noted that when an item is put into the search results, the entire item is copied into the search results. This means that the results can be received exactly how they were when the search was performed, regardless of if items were deleted or modified. Use the expressions in the ‘Search Results’ subsection of the expressions menu to receive this information. The search results can be cleared by the ‘Clear Results’ action. The ‘Find ’Repeats’ of Item’ and ‘Find ’Subgroups” actions can also modify the search results.
This finds all items that correspond to a repeat of an item, when the ‘Rename’ repeat mode is enabled. That is, it finds all those in the form ‘item.*’ in the specified group. The search results will also include ‘item’ itself, if it exists. The first parameter is the group name and the second parameter is the item name. The search is always case sensitive. The results to this are put into the usual search results, accessible from expressions. The previous results are always cleared before the action is performed. For instance, given the file:
Then the search results for when this action is performed with group ‘group’ and item ‘item’ would be:
This finds the names of all groups that correspond to subgroups of another group, when the ‘Allow Subgroups’ option is enabled. The first parameter is the name of the group to find the subgroups of. This can itself by a subgroup (i.e. one with a ‘/’ in its name). The second parameter is the number of levels. If this is a positive number, it finds all subgroups at that level or less. If it is a negative number, it finds all subgroups at exactly that level. If it is 0, if finds all subgroups of any depth. For instance, consider the following Ini++ file with subgroups enabled:
(The item called ‘item’ in each group is actually the depth of that group with respect to ‘parent’) Then if you:
For this example, the proper names of the groups have not been used to make it easier. For instance, ‘aba’ is really called ‘group/a/ab/aba’. It is the latter which will come up in the search results. The results are put in the usual search results, accessible by expressions. The previous search results are cleared first. The item names and item values for all the search results are all blank from this, as they are not relevant.
This clears the current search results. There is no necessary reason to do this (as every search action either automatically or gives you the option to clear the current results), but it might help with the logic of your program.
This is as the ‘Perform Search’ action, however the result is saved as an Ini file to the specified path. This Ini file will contain only those items that fulfill the search. The settings for the Ini file will be taken from the object. The first parameter is the file name to save to. This may be a relative path. In that case, it will be relative to the default directory. The remaining parameters are as with the ‘Perform Search’ action. This action does not effect the search results.
This is as the ‘Perform Search’ action, however all the matched items are copied into another Ini++ object. The first parameter is the name of the Ini++ object to copy the data into. This is the name of the object as set in the frame editor. It should be typed exactly, noting it is case sensitive. The target Ini++ object cannot be the same as the Ini++ object that is generating the action. In addition, it cannot share data with it. This means they cannot both be global objects. When the program is ran from the event editor, if either of these things happen, or the Ini++ object specified does not exist, a message box will be displayed. When the program is built, there will be no error message and the action will just fail. The remaining parameters are as with the ‘Perform Search’ action. This action does not effect the search results.
This menu contains a variety of actions which allow one Ini++ object to be merged with another.
A file and the current data in the Ini++ object are merged with this action. The first parameter is the file to merge with. This can be a relative path, and it will be relative to the default path. The second parameter decides if overwrites are allowed. If they are (that is, this parameter is set to 1), then all the data is copied from the file into the object. However, if they are not allowed (that is, the parameter is set to 0) then data is only copied from the file into the object if it does not overwrite any existing data. This generated the ‘On Merge’ condition event.
This merges a specific groups from a file with the current data. The first parameter is the file to merge with. This can be a relative path, and it will be relative to the default path. The second parameter asks for the name of the group in the Ini file. The third parameter asks for the name of the destination name of the group. This is what the group will be called in the Ini++ object. Often you will just want this to be the same as the second parameter. The forth parameter decides if overwrites are allowed. If they are not allowed (that is, this parameter is set to 0) then data is only copied from the file into the object if it does not overwrite any existing data. This generated the ‘On Merge’ condition event.
This action merges two Ini++ objects together, and puts the result in the calling object. The first parameter is the name of the Ini++ object to merge with. This is the name of the object as set in the frame editor. It should be typed exactly, noting it is case sensitive. The specified Ini++ object cannot be the same as the Ini++ object that is generating the action. In addition, it cannot share data with it. This means they cannot both be global objects. When the program is ran from the event editor, if either of these things happen, or the Ini++ object specified does not exist, a message box will be displayed. When the program is built, there will be no error message and the action will just fail. It should be stressed that the object that is typed in for this parameter will not be modified. Only the calling object will be modified. The second parameter determines whether data from the specified object can overwrite data in the calling object. If this is set to 0, then in effect the calling object gets priority if there are items in with the same name and in the same group in both objects. Otherwise, if it is set to 1, then the object specified in the first parameter does. This generated the ‘On Merge’ condition event.
This action merges a specific group in two Ini++ objects together, and puts the result in the calling object. The first parameter is the name of the Ini++ object to merge with. This is the name of the object as set in the frame editor. It should be typed exactly, noting it is case sensitive. The specified Ini++ object cannot be the same as the Ini++ object that is generating the action. In addition, it cannot share data with it. This means they cannot both be global objects. When the program is ran from the event editor, if either of these things happen, or the Ini++ object specified does not exist, a message box will be displayed. When the program is built, there will be no error message and the action will just fail. It should be stressed that the object that is typed in for this parameter will not be modified. Only the calling object will be modified. The second parameter asks for the name of the group in the specified Ini++ object to be merged. The third parameter asks for the name of the destination name of the group. This is what the group will be called in the calling Ini++ object. Often you will just want this to be the same as the second parameter. The final parameter determines whether data from the specified object can overwrite data in the calling object. If this is set to 0, then in effect the calling object gets priority if there are items in with the same name in both objects. Otherwise, if it is set to 1, then the object specified in the first parameter does. This generated the ‘On Merge’ condition event.
This menu contains a variety of actions to do with loading and saving.
This action changes the filename of the current file, possibly clearing all the data. The first parameter is the filename of the new file. This may be a relative path. If this is left blank (i.e. it is the empty string) then the file is kept internal. The second parameter decides if the current data should be cleared or not. Setting it to 0 retains the current data. Setting it to 1 clears the current data. If 0 is selected, and auto save is enabled, then the file will be immediately saved. However, if 1 is selected then it will not be saved regardless of the auto save settings. Read only status is unaffected by this action. It should be noted that this action is different to ‘Load File’ as it does not actually load the file. It just sets it as the current file for auto save and auto load.
This action clears all the current data and loads an Ini file. The file is loaded based on the current settings. This includes encryption and compression settings. Make sure you load the file with the correct settings! The second parameter specifies whether the file should be opened in read only mode. This means ‘Save’ and the auto-save feature are both disabled. The data can still be modified in memory. If the ‘Create folders for files if they do not exit?’ option is selected, then folders will be created for the file to ensure it can be created so long as read only was not selected. If read only was selected, folders will not be created, regardless of the settings.
This action saves the Ini++ object to the current file. All the settings are respected. The action will fail if the file is in read only mode, or there is no current file (which is the case if ‘New’ had been used with a blank string as the parameter, or if ‘New’ or ‘Load’ haven’t been used and no file was specified in the frame editor).
This action saves the Ini++ object to the specified file. All the settings are respected. The current file will be set to the specified file name. This can be a relative path. The action will work even if the file is in read only mode. If the file is successfully saved, read only mode will be disabled.
This action saves the Ini++ object to a file. Compression and encryption settings can be specified. The first parameter is the file name. This may be a relative path, and it will be relative to the default directory. The second parameter decides if the file should be compressed. The third parameter is the encryption key. If this is blank (i.e. the empty string), then there is no encryption. This action does not change the current file path. The action will work even if the file is in read only mode. It will not change read only mode.
This clears all the data and sets the current path to the blank string, making the file internal.
This action allows data to be imported or exported in CSV form. CSV stands for ’comma-separated values’, and it is just a list of values separated by commas (or another character of your choice). The fist parameter asks if you wish to import or export. Input 0 to import and 1 to export. This action does not affect the current file path.
This imports data from a CSV file. The second parameter is the file name to load from. This can be a relative path. The third parameter is the name of the group to load. If it is left blank then each group can be on a line of its own and the first value on each line is considered the group name. The forth parameter is the separator. Usually this will be a comma, but if commas might occur in your data then you might wish to change it to a symbol you don’t use. For instance, the pipeline character ‘k’ is a popular separation character. As an example, consider the following CVS file (with separator ’,’): Group 1|Item 1|Value 1|Item 2|Value 2 Group 2|Item 3|Value 3|Item 4|Value 4|Item 5|Value 5 If the group setting is left blank, it will be loaded as:
On the other hand, if the group parameter is set as “Group”, then it is loaded as follows:
(Note how if there is an item with no data at the end of the line, it is ignored) This action does not clear the old data first.
This exports data as a CSV file. The second parameter is the file name to save to. This can be a relative path. The third parameter is the name of the group to save. If it is left blank then each group will be on line of its own and the first value on each line will be the groups name. Otherwise only the specified group is saved and its name will not be prefixed to the line. The forth parameter is the separator. Usually this will be a comma, but if commas might occur in your data then you might wish to change it to a symbol you don’t use. For instance, the pipeline character ‘k’ is a popular separation character. Settings like ‘Save repeated items as original’ are not respected and escape characters are not used. Use the ‘Get INI as CSV String’ expression to get this data without saving it to disc.
This action can import data or export the data as a CSV Array. This is a CSV file where the top line defines the possible items for each group, and the following lines represent each individual group. The first parameter decides whether the file should be imported or exported to. The second parameter decides the file (which may be relative) and the final parameter decides the separator character (usually a comma). For instance, suppose we have the data:
Then this would be exported as: Group,item1,item2,item3,item4 Group 1,Hat,Toothbrush,Lipstick,Key Group 2,Glass,Chewing Gum,Hammer Notice how the first line defines the item names. Each line has these items, with the first item its group name. Importing is similar. Data is not cleared before the import. If an item is blank, it is not loaded. For instance, Group,item1,item2,item3,item4 Group 1,Hat,Toothbrush,,Key Would merely be loaded as:
As the third item was blank. It is not loaded as a blank string. Neither mode changes the current file path.
This action loads an INI file from a string. The string must be formatted as an INI file. All settings (including the choice of new line character) are respected when this is loaded except compression and encryption. The first parameter is the string you wish to load. The second parameter decides if you want to clear all the old data (0) or if you wish to merge the new data with the old data (1). In the case of a merge, the new data will replace any old data if they have the same group and item names.
This action changes the currently selected global data slot. If the slot does not exist, it is created. If the object was not created in ‘global’ mode, it will be converted to global mode. This means the local data will be removed from memory. So make sure you save it if you want to keep it!
This action allows auto-load and auto-save to be enabled and disabled. This does not modify the data in any form.
This action allows compression to be enabled or disabled (for auto-load, autosave, ‘Load’, ‘Save’ and ‘Save As...’). This does not change the data, but it may change how the file is saved. It therefore causes the file to be re-saved.
This action allows the encryption key to be set. Leaving the key blank causes encryption to be disabled. The encryption key is used for auto-load, autosave, ‘Load’, ‘Save’ and ‘Save As...’. This does not change the data, but it may change how the file is saved. It therefore causes the file to be re-saved.
Allows the read-only status of the object to be changed. This does not change the data or the way the data is saved. Regardless of how this option is set, the object can still be modified in memory. However, read-only mode disabled auto-save and the ‘Save’ action.
The Ini++ object has a built in dialog that can be of help when debugging your applications. It can also serve as a cheat screen, an advanced opitions editor or a data editor in the released program.
This action opens the dialog box. Only one dialog can be ran at a time. If another dialog box is open, it will closed. The first parameter allows the title bar text for the dialog to be set. The second parameter allows the various options to be set. These are:
The drop down menu at the bottom of the dialog allows the formatting of items on the tree to be selected. The dialog box is automatically shut when the frame changes, as the object it is associated with will not exist anymore.
If a dialog box is open, this action closes it. This will cause the ‘On Dialog Closed’ condition event. If no dialog box is open, this does nothing.
If a dialog box is open, this performs a complete refresh of it. This may be distracting to the user, and for large amounts of data it could be slow.
This is yet to be made.
The actions in this sub-menu allow the options of the object to be set.
Allows the Ini++ object to change between case insensitive and case sensitive modes. Changing from case sensitive mode to case insensitive mode may cause data to be changed.
Allows the escape character modes to be toggled.
Allows the ‘always quote strings’ option to be changed.
Allows the repeat mode settings to be changed. See the title of the parameter dialog boxes for information.
Allows the new line string to be set. If the empty string is given, the default new line string is used (an actual windows new line).
Allows the default directory to be set. This must be a path. If you wish to use the program folder, windows folder, etc., then it is best to use the properties in the frame editor.
Allows the group settings to be changed. This is: Should loading and saving recognise subgroups and should empty groups be allowed? Beware: Changing from allowing to not allowing empty groups can cause data to change.
The actions in this sub-menu allow the options of the object to be set.
Compresses the file specified in the first parameter and places it in the location specified by the second parameter. Some Ini++ settings are respected. For instance, relative paths may be used and folders will be created for destination file if ‘Create folders for files if they do not exit?’ is enabled. Folders are never created for the source file, regardless of options.
Decompresses the file specified in the first parameter and places it in the location specified by the second parameter. Some Ini++ settings are respected. For instance, relative paths may be used and folders will be created for destination file if ‘Create folders for files if they do not exit?’ is enabled. Folders are never created for the source file, regardless of options.