Appendix A: Functions

Calling this function with no parameters will show the Configuration Dialog. Specifying a specifc Tab as the first parameter will open the Configuration Dialog to that tab. This function also allows you to get or set any preference from the configuration Dialog.

This is the main menu definition function. This function takes your XML menu definitions, parses them, and sets up menus to be displayed. For a complete understanding of this function, please see Appendix B. This function does not require that you use the root <CNSMenu> and </CNSMenu> tags unless you are using an internal DTD for entity definitions. If you do not use one of the root tags, you cannot use the other. In other words, both the opening <CNSMenu> and closing </CNSMenu> tags must be there, or both of the tags must not be there. You cannot have just the opening or just the closing tag.

This function is similar to the CNSMenu_DefineMenu function, except that instead of defining the actual XML text, you sepecify a file on the hard drive containing the XML text. The XML file you specify must be a "well-formed" XML document. Unlike the CNSMenu_Define function, the XML file you specify must contain the root <CNSMenu> and </CNSMenu> tags.

This function allows you to easily create a menu without using xml. The first two parameters are required. The "Name" parameter is the name of the menu. The "Items" parameter is a return-delimited list of menu items as explained below. The remaining parameters are optional. The "Script" and "DB" parameters allow you to specify the script to be called when a menu item is clicked, and the database that contains that script. If a script is specified and a database is not, the menu will assume the script is in the current database. The "FailScript" and "FailDB" allow you to define a script to be called if the user clicks off a menu without selecting anything. The "Persistent" parameter allows you to tell CNS Menu to save this menu between FileMaker Pro sessions. The "IgnoreMetaTags" parameter allows you to disable the "meta tag" parsing of the menu items as explained below.

The "Items" parameter is a return-delimited list of menu items for this menu. Each line represents one item on the menu. You can specify a value for a menu item by appending a semi-colon and the value onto the end of the item name. For example, if you had "Blue;0000FF" on a line, your menu would have an item with the name "Blue" and when a user selected that item, the value "0000FF" would be returned to your script. For sub-menus, specify the name of the sub-menu, followed by a greater-than sign (">") followed by the next sub-menu name or menu item. For example, if you had "Colors>Red" on a line, your menu would have a sub-menu named "Colors" with an item inside named "Red". Every sub-menu and menu item can be preceded with one or more special "meta tags" to specify different styles and marks for the sub-menu or item name as explained below:

• ! - the item will appear disabled.
• $ - the item will require the shift key to be pressed in order to show up.
• ^ - the item will require the control key to be pressed in order to show up.
• ~ - the item will require the alt/option key to be pressed in order to show up. (this is the tilde character, which is shifted version of the key to the left of the 1 on English keyboards) (only available on Mac)
• @ - the item will require the command key to be pressed in order to show up. (only available on Mac)
• # - the item will appear bold.
• % - the item will appear italicized.
• _ - the item will appear underlined.
• ` - the item will appear with a check mark. (this is the backtick character, which is the key to the left of the 1 on English keyboards) (on Mac, you can also use opt-v to type an actual check mark)
• * - the item will appear with a bullet mark. (On Mac, you can also use opt-8 to type an actual bullet mark)
• + - the item will appear with a diamond mark. (On Mac, you can also use shift-opt-v to type an actual diamond mark)
• = - disable the meta tag processing for the rest of the sub-menu or item name.

You can specify more than one of the above for any item to set multiple attributes at once, with the exception of the check mark, bullet mark, and diamond mark. You can only have one mark defined for a menu item. For example, if you had "!#%Delete Record" on a line, your menu would have an item with the name "Delete Record" that appeared disabled, bold, and italicized. If you need to display a menu item that starts with one of these "meta tags", you can either set the "IgnoreMetaTags" parameter to true, or you can use the equals ("=") meta tag to skip the meta tag processing for the item. For example, if you had "=$4.00" on a line, your menu would have an item with the name "$4.00" instead of a menu named "4.00" that required you to press the shift key in order to make the item visible.

This function will delete a previously defined menu. Specify the name of the menu to delete as the parameter.

You can use this function to return the complete path to a special folder on the local hard drive. The following folders can be returned:

• Database - a path to the folder containing the current database.
• FileMaker - a path to the folder containing the FileMaker Pro application.
• Root - the root of the hard drive.
• System - a path to the system folder.
• Desktop - a path to the user's desktop folder.
• Preferences - a path to the user's preferences folder.
• Temporary - a path to a temporary folder on the hard drive.
• Applications - a path to the Applications or Program Files folder.
• Documents - a path the user's documents folder.

This function will return the name or caption of the last menu item the user selected. If you have more than one menu item calling the same script in your database, you can use this function to determine which menu item was actually selected. If you specify a True value for the parameter, it will return the "full menu path" to the menu item the user selected. In other words, if you have a menu named "MyMenu", which contains a sub menu named "Colors", and the user selected the "Red" item in that sub menu, specifying True as the parameter will make this function return "MyMenu/Colors/Red" instead of just "Red".

This function will return the name of the menu that contains the menu item that the user last selected. If you have more than one menu set up to call the same script in your database, you can use this function to determine which menu was actually used.

This function will return the user-defined value of the last selected menu item. When defining your menu items, you can specify any data you want, and then that menu item is selected, you can use this function in the script that is called to retrieve that data.

This function will return a number to indicate which mouse button was last clicked. If you click on a button with the left mouse button, this function will return "1". If you click with the right mouse button, it will return "2". If you click with a third or middle button, it will return "3". This allows your mouse buttons to act independently of each other, such as entering a field with the left mouse button and showing a menu with the right mouse button. You can also use the constant values "CNSMenu_LeftMouseButton", "CNSMenu_RightMouseButton", and "CNSMenu_ThirdMouseButton" to test for which button was pressed. For example, you could have the calculation "If( CNSMenu_GetMouseButton = CNSMenu_RightMouseButton ; CNSMenu_ShowMenu( "RightClickMenu" ) ; CNSMenu_ShowMenu( "LeftClickMenu" ) )" to show either a Left Click Menu or a Right Click Menu depending on which mouse button was pressed.

This function retuns the cordinates of the mouse. The optional parameters are "layout" and "screen". The "layout" parameter returns the cordinates of the mouse in relation to the layout, and the "screen" parameter is in relation to the whole screen. If no parameter is defined, the default setting is "layout".

This function returns a list of all the currently defined menus.

This function enables or disables Popup dialogs that display menu errors. If a menu item does not have a database or script associated with it, and none of its parent items do, then when the user chooses that menu item, nothing will happen. If PopupMenuErrors has been turned on, then when the user chooses that menu item, an error dialog will pop up indicating the error. This function is useful when troubleshooting your menus and determining why a script is not being called for any specific menu item. To turn on PopupMenuErrors, use any of the following values for the parameter: 1, True, "T", "True", "Y", "Yes", or "On". To turn off PopupMenuErrors, use any of the following values for the parameter: 0, False, "F", "False", "N", "No", or "Off".

This function allows you to register your copy of CNS Menu. There are two ways you can use this function. If you specify "Dialog" as the first (or fourth) parameter, the plug-in will display a dialog asking you to fill in your registration information. Alternatively, you can specify your registration information in the order "First Name" ; "Last Name" ; "Registration Number". Whenever you use this function, you will be presented with a dialog containing our License Agreement for the plug-in that asks you to accept the agreement. If you need to use this function in a startup script to register the plug-in every time the solution starts, you can auto-accept the License Agreement by adding "I Accept The License Agreement" as a forth parameter.

This function allows you to define the Part Heights of your Layout so that CNS Menu can correctly place your menus in List View. Call this function before calling CNSMenu_ShowMenu when you are on a Layout that is in List View. Then, in CNSMenu_ShowMenu specify the Left and Top coordinates as if the Layout is being viewed in Form View.

Use this function to show a previously defined menu. You can have the menu popup at the current mouse coordinates, or you can specify where the popup menu should appear. If you want the menu to popup at the current mouse coordinates, just specify the name of the menu (ie. "My Menu"). If you want the menu to popup up at specific coordinates on your layout, you specify the values in the "Left" and "Top" parameters. For the X (vertical, column) pixel coordinate, specify it in the "Left" parameter. For the Y (horizontal, row) pixel coordnate, specify it in the "Top" parameter. An example: "My Menu"; "100"; "200". In all likelihood, if you want to specify coordinates, you will be wanting to line the menu up with some object on your layout. To know the coordinates for the menu to popup at, switch to Layout mode, change the Top and Left margins in the Layout Setup dialog to 0, select the object on the layout, and use the Object Info palette to get the pixel coordinates. The coordinates must be in pixels, so when looking at the Object Info palette, click on the measurement indicator to toggle between inches (in), centimeters (cm), and pixels (px). The "Align" parameter allows you to specify whether the menu will be left, center, or right justified from your cursor or the coordinates you specify. The options are "left", "center", and "right". If no parameter is specified the default value is "left". The last parameter "MinWidth", allows you to specify, in pixels, the minimum width the menu will always appear.

This function returns the current version of CNS Menu. You can also use this function to test whether the plug-in is installed. If you call this function and a question mark ("?") is returned, then the plug-in is either not installed, or not enabled.

This function returns an Auto Update friendly Version number of CNS Menu. The format of this version number is always exactly 8 digits long. The first two digits represent the major version of the plug-in (zero-filled). The third and fourth digits represent the minor version of the plug-in (zero-filled). The fifth and sixth digits represent the update portion of the version (zero-filled). The final two digits represent a special build number or a beta version number and will usually be zeros.

As an example, for CNS Menu 1.1.5, the major version is 1, the minor version is 1, the update version is 5, and there is no special build or beta version defined. So, the resulting Auto Update friendly version number would be 01010500.