JanetTerra
Sep 24, 2006
==Menus: The Liberty BASIC Menu Bar== [[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. Once the menu has been opened, the {{**ALT**}} is no longer necesssary. Just the letter following the {{**&**}} character needs to be pressed. Often the {{**&**}} precedes the first character in the menu title or item, but that isn'tnecessary.required. {{**E&xit**}}, or{{**ALT``-``X**}},{{**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 Menus=== [[image:MenuText.png]] 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.]]** ----