JanetTerra
Sep 24, 2006
==Menus==
[[toc]]
Adding a menu to your software program allows your user to easily make selections with just a few keyboard presses or clicks of the mouse. Menus provide shortcuts to frequently used actions. A very common menu offers the user file choices such as
* **NEW**
* **LOAD**
* **SAVE**
as well as a way to properly exit the program.
* **EXIT**
===Menu Bar===
The most common graphical user interface (GUI) menu is the [[http://en.wikipedia.org/wiki/Menu_bar#Windows|Menu Bar.]] The menubar appears just below the GUI caption. The menu bar allows users to navigate throughout the program using either keyboard presses or mouse clicks.
||[[image:MenuNo.png]][[image:MenuYes.png]][[image:MenuDrop.png]]||
The Liberty BASIC command for inclusion of a menu bar is, appropriately, {{**MENU**}}. The command line for the above depicted menu is
[[code format="vb"]]
MENU #main, "Options", "Load", [loadFile], "Save", [saveFile]
[[code]]
{{**MENU**}} is //case``-``insensitive//, meaning you can write {{**MENU**}} or {{**menu**}} or {{**Menu**}} or any other combination of upper and lower case letters. Menus are defined //before// the window is opened. The other parameters are
{{**#main**}}, the handle of the window to be opened
{{**"Options"**}}, the menu title visible on the menu bar itself
{{**"Load"**}}, the first listing of the opened menu
{{**[loadFile]**}}, the block of code to be executed if {{**Load**}} is clicked
{{**"Save"**}}, the second listing of the opened menu
{{**[saveFile]**}} the block of code to be executed if {{**Save**}} is clicked
The correct terminology for any separate menu appearing on the menu bar, e.g., **Options**, is //Sub Menu//. For the purposes of simplicity, any reference to //menu// in this article refers to the //sub menu//. Items which appear in the drop down list when that //sub menu// is opened are referred to as //menu items//.
===Menus and Window Types===
Not all window types support menu bars. Window types that do not support menu bars include //dialog windows//, //toolwindows// and //popup windows//. These windows may support [[OtherTypes|context menus.]]
===Menu Listings===
[[code format="vb"]]
MENU #main, "Menu Title", "1st Listed Item", [BranchTo1], "2nd Listed Item", [BranchTo2], _
"3rd Listed Item", [BranchTo3], "4th Listed Item", [BranchTo4], "5th Listed Item", _
[BranchTo5], "6th Listed Item", [BranchTo6], "7th Listed Item", [BranchTo7], "8th Listed Item", _
[BranchTo8], "9th Listed Item", [BranchTo9], "10th Listed Item", [BranchTo10]
[[code]]
||There is really no limit to the number of listed items a menu can contain. If there are many listings, it may be advisable to use Liberty BASIC's //line continuation character//, which is the underscore, to break up the listing onto multiple lines.||[[image:MenuLong.png]]||
===Multiple Menus===
[[code format="vb"]]
MENU #main, "File", "1st Listed Item", [BranchTo1], "2nd Listed Item", [BranchTo2]
MENU #main, "Color", "Color 1", [color1], "Color 2", [color2], "Color 3", [color3]
MENU #main, "Size", "Small", [sizeSmall], "Medium", [sizeMedium], "Large", [sizeLarge]
[[code]]
||[[image:MenuMult.png]]||A window can have more than one menu. The menus appear in the order in which they're defined.||
===Menu Separators===
[[code format="vb"]]
MENU #main, "Options", "New", [newFile], "Load", [loadFile], "Save", [saveFile],|, "Exit", [EndProgram]
[[code]]
||Similar menu items can be grouped by inserting a menu separator (horizontal) line. Instead of a listing and its associated branch label, insert a pipe {{**``|``**}}.||[[image:MenuSep.png]]||
===Accelerator or 'Hot Key' Selection===
[[code format="vb"]]
MENU #main, "&File", "&New", [newFile], "&Load", [loadFile], "&Save", [saveFile],|, "E&xit", [EndProgram]
[[code]]
||[[image:MenuHot.png]]||The ampersand ({{**&**}}) key is a special key when added to any menu title or item. This allows menu selection by keypress rather than mouse click. A menu with the title {{**&File**}} will open when the {{**ALT**}} is kept depressed while the {{**F key**}} is pressed. This key combination is known as {{**ALT``-``F**}}. The associated alphanumeric key is case``-``insensitive. Any alphanumeric key can be combined with the {{**ALT**}} key for menu selection. The {{**&**}} character doesn't appear on the menu; instead, the associated alphanumeric key appears underlined when activated. Often the {{**&**}} precedes the first character in the menu title or item, but that isn't necessary. {{**E&xit**}}, or {{**ALT``-``X**}}, is frequently used as a menu item to close a window and quit an application.||
===Branch Events and Subs===
Menu selection directs the code execution to the area specified by the branch label. Copy and paste the following code into your Liberty BASIC editor.
[[code format="vb"]]
NOMAINWIN
MENU #main, "&Files", "E&xit", [EndProgram]
MENU #main, "Fill &Color", "&1 - White", [fill1], "&2 - Black", [fill2], "&3 - Gray", [fill3]
OPEN "Accelerated 'Hot Keys'" for Graphics as #main
PRINT #main, "TRAPCLOSE [EndProgram]"
WAIT
[fill1]
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL WHITE"
PRINT #main, "FLUSH"
WAIT
[fill2]
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL BLACK"
PRINT #main, "FLUSH"
WAIT
[fill3]
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL LIGHTGRAY"
PRINT #main, "FLUSH"
WAIT
[EndProgram]
CLOSE #main
END
[[code]]
When code is directed to branch labels, that complete block of code must end with a {{**WAIT**}} statement. If there is no {{**WAIT**}} statement, code execution will continue through the lines in succession until a {{**WAIT**}} statement is reached, the {{**END**}} statement is reached, or the code encounters an error.
Subs can be used instead of branch labels. Do not insert a {{**WAIT**}} within the subroutine. Just simply {{**END SUB**}}. Unlike mouse events and buttons, menu items do not pass a handle. As such the designated sub will not support this or any parameters. This becomes especially important when subs are being used to exit a program in both the menu and the trapclose statement. Each will need its own unique sub, the menu item sub //without// a passed handle, and the trapclose sub //with// a passed handle. The following is the same program as above, but directing selected menu items to subs rather than branch labels.
[[code format="vb"]]
NOMAINWIN
MENU #main, "&Files", "E&xit", EndProgramM
MENU #main, "Fill &Color", "&1 - White", fill1, "&2 - Black", fill2, "&3 - Gray", fill3
OPEN "Accelerated 'Hot Keys'" for Graphics as #main
PRINT #main, "TRAPCLOSE EndProgramT"
WAIT
SUB fill1
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL WHITE"
PRINT #main, "FLUSH"
END SUB
SUB fill2
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL BLACK"
PRINT #main, "FLUSH"
END SUB
SUB fill3
PRINT #main, "CLS"
PRINT #main, "DOWN"
PRINT #main, "FILL LIGHTGRAY"
PRINT #main, "FLUSH"
END SUB
SUB EndProgramM
CALL EndProgramT "#main"
END SUB
SUB EndProgramT handle$
CLOSE #handle$
END SUB
[[code]]
===The Texteditor Menu===
[[image:MenuText.png]]
Texteditors and windows opened for Text automatically include two special menus: Files and Edit. Each additional menu placed by the coder will force these two automatic menus one position to the right.
//Code for the left and center images above//
[[code format="vb"]]
OPEN "The Texteditor Menus" for Text as #main
PRINT #main, "!Trapclose [EndProgram]"
WAIT
[EndProgram]
CLOSE #main
END
[[code]]
//Code for the right image above//
[[code format="vb"]]
MENU #main, "&Styles", "Style &1", [style1], "Style &2", [style2]
OPEN "The Texteditor Menus" for Text as #main
PRINT #main, "!Trapclose [EndProgram]"
WAIT
[EndProgram]
CLOSE #main
END
[[code]]
Opening a regular window with an embedded texteditor will remove the automatic Files menu while retaining the automatic Edit menu. For a more comprehensive discussion of manipulating the texteditor's automatic Edit menu, see **[[http://babek.info/libertybasicfiles/lbnews/nl131/texteditor.htm|Texteditors with Eddie.]]**
[[#OtherTypes]]
===Other Types of Menus===
Menus on the menu bar are not the only types of menus used in programs. Liberty BASIC supports **[[http://en.wikipedia.org/wiki/Context_menu|context menus]]**, also known as **//popup menus//**. The placement of the popup menu is dependent upon the placement of the mouse cursor. A tutorial for **Popup Menus** is in the planning stages but not yet available. Stay tuned.
A custom menu gaining popularity is the **[[http://en.wikipedia.org/wiki/Pie_menu|Pie Menu.]]** Custom menus can be easily coded into your Liberty BASIC program using a **Dialog_Modal** window that contains a **{{graphicbox}}**.
More **[[http://www.filesland.com/companies/Viklele-Associates/VLMenuPlus-6001-sm.jpg|complex menus]]**such as cascading menus, folding menus, menus with bitmaps, etc., require knowledge of API and DLL calls.||
If you have a Pie Menu or other custom menu you'd like to share, please consider **[[http://lbpe.wikispaces.com/Submit|submitting an article.]]**
----