The GFA-BASIC 32 editor extension functions can be executed through the use of a set of predefined keystrokes or by selecting a menu item from the Extra submenu. To connect some functionality to a keyboard shortcut the name of the procedure should conform to a special format that describes the shortcut to use (Gfa_Ex_, Gfa_App_, etc).
Another way of invoking an extensibility function is to select a menu item from the Extra menu. To provide a menu entry the GLL must add a menu entry to the Extra menu in Gfa_Init sub using Gfa_AddMenu. This function adds an item to the menu and specifies a menu event sub that handles the menu entry when it is selected. Other commands are available to modify an appended menu entry. An item can be enabled or disabled, gets a checkmark in front of it, or its text can be changed afterwards.
[id = ]Gfa_AddMenu("Entry", eventsub)
f = Gfa_MenuCheck(id) (id As Int, f? as Boolean)
Gfa_MenuCheck(id) = f (id As Int, f? As Boolean)
d = Gfa_MenuDesc(id) (id As Int, d As String)
Gfa_MenuDesc(id) = d (id As Int, d As String)
f = Gfa_MenuEnable(id) (id As Int, f As Boolean)
Gfa_MenuEnable(id) = f (id As Int, f As Boolean)
t = Gfa_MenuText(id) (id As Int, t$ as String)
Gfa_MenuText(id) = t (id As Int, t$ as String)
Gfa_AddMenu this appends the menu item "Entry" to the Extra-Menu of the GFA-BASIC 32 IDE. The text may contain an ampersand (&) to provide keyboard shortcut. The Gfa_AddMenu is usually invoked in the Gfa_Init sub.
Gfa_MenuCheck(id) [=] returns or sets a value that determines whether a check mark is displayed next to a menu item.
Gfa_MenuDesc(id) [=] returns or sets the descriptive text displayed in the status bar for a menu item. The text is limited to 159 bytes.
Gfa_MenuEnable(id) [=] returns or sets a value that determines whether the specified menu item can respond to user-generated events.
Gfa_MenuText(id) [=] returns or sets the text displayed for a menu item. The text is limited to 159 bytes.
Sub Gfa_Init
Global IdxCreateCode% ' Declare Globals in Gfa_Init
IdxCreateCode = Gfa_AddMenu("&Create code"#9"Ctrl+Shift+C", MenuCreateCode)
Gfa_MenuDesc(IdxCreateCode) = "Inserts a code snippet at current cursor position"
EndSub
Sub MenuCreateCode(i%) ' a ByRef integer parameter
Debug "Menu selection ID "; i%
End Sub
The Sub MenuCreateCode is invoked when the menu entry is selected. The event sub must contain one Integer parameter (not ByVal). The integer parameter is a value between 1 and 50 (the maximum number of entries) representing its "position" in the Extra submenu. The numbers are given to the entries automatically when they are appended using Gfa_AddMenu. This value is returned when the function version of Gfa_AddMenu is used instead. Keeping this value in a global variable is necessary when the menu entry is later manipulated with Gfa_MenuDesc, Gfa_MenuEnable, or Gfa_MenuText.
Another use of saving the menu ID value is to use it later in a general menu event subroutine to differentiate between the menu items in a Switch statement. However, this is not encouraged because the execution of a menu event sub for one entry is faster.
The Win API menu ID is calculated by adding 2499 to the value returned by Gfa_AddMenu.
Note Multiple editor extensions can add menu entries to the Extra menu. Later, when a GLL is unloaded, their entries are unloaded as well. This will not lead to renumbering the ID values of the menu entries that are currently in the Extra menu.
{Created by Sjouke Hamstra; Last updated: 08/10/2014 by James Gaite}