MenusIn PowerBASIC terminology a menu is called a "menu", a "bar, or a "menu bar". The top-level selections on a menu bar are called "popup menus". A popup menu may have dropdown selections, called "menu items",
PowerBASIC applications can also display "context menus", but the method requires the use of API to augment the PowerBASIC menu features. Displaying context menus is covered further down this page.
Using the terminology above, here is a description of the four primary PowerBASIC menu commands.
In addition to these four commands, PowerBASIC provides several other commands which help manage an application's menus. Here's a list of all MENU commands, categorized by the features they provide. Note that all of these commands start with "Menu".
| New Bar, Attach |
| New Popup, Add Popup, Add String |
| Get State, Set State, Set Text, Get Text |
| Draw Bar, Delete |
Note that both the menu bar and popup menus are memory structures. One command is used to create the structures, including assigning them a windows handle. A second command is require to associate the structures with a parent (associating a menu bar with a parent dialog, and associating a popup menu with a parent menu bar).
The dropdown menu items are essentially controls and require that the PowerBASIC programmer assign them control IDs. Menu items are created and assigned to a parent popup menu using a single statement.
Menu Functions Listing
Here are one-line descriptions of all the menu functions.
Creating a Menu
There are four steps to creating a complete menu. They are:
Dim hMenu As Dword
Menu New Bar To hMenu
'Create File + Children -------------------------
Dim hMenuFile As Dword
Menu New PopUp To hMenuFile
Menu Add PopUp, hMenu, "&File", hMenuFile, %mf_enabled
Menu Add String, hMenuFile, "&Open", %ID_Open, %mf_enabled
Menu Attach hMenu, hDlg
Dialog Show Modal hdlg
Example - Dialog + Menu
Here's the complete code for creating the following example of
a dialog with a tool bar. The tool bar has two main items
(File and Help). Each of those have submenus.
|
|
|
|
#Compile Exe
#Dim All
%ID_Open = 201
%ID_Save = 202
%ID_SaveAs = 203
%ID_Exit = 204
%ID_Email = 901
%ID_WebSite = 902
%ID_Help = 903
%ID_Update = 904
%ID_About = 905
Function PBMain()
Dim hDlg As Dword
Dialog New 0, "My Dialog",,, 150,100, %ws_overlappedwindow , To hDlg
'Create Bar -------------------------
Dim hMenu As Dword
Menu New Bar To hMenu
'Create File + Children -------------------------
Dim hMenuFile As Dword
Menu New PopUp To hMenuFile
Menu Add PopUp, hMenu, "&File", hMenuFile, %mf_enabled
Menu Add String, hMenuFile, "&Open", %ID_Open, %mf_enabled
Menu Add String, hMenuFile, "&Save", %ID_Save, %mf_enabled
Menu Add String, hMenuFile, "&Save As ..", %ID_SaveAs, %mf_enabled
Menu Add String, hMenuFile, "E&xit", %ID_Exit, %mf_enabled
'Create Help + Children -------------------------
Dim hMenuHelp As Dword
Menu New PopUp To hMenuHelp
Menu Add PopUp, hMenu, "&Help", hMenuHelp, %mf_enabled
Menu Add String, hMenuHelp, "&Email Author", %ID_Email, %mf_enabled
Menu Add String, hMenuHelp, "&WebSite", %ID_WebSite, %mf_enabled
Menu Add String, hMenuHelp, "&Online Help ..", %ID_Help, %mf_enabled
Menu Add String, hMenuHelp, "&Online Update ..", %ID_Update, %mf_enabled
Menu Add String, hMenuHelp, "&About ..", %ID_About, %mf_enabled
'Attach Bar to Dialog -------------------------
Menu Attach hMenu, hDlg
Dialog Show Modal hdlg
End Function
Menu Item States
Several of the statements use the state& property. Allowed
values are:
%MF_CHECKED - has checkmark
%MF_DISABLED - disabled (not grayed out)
%MF_ENABLED - enabled
%MF_GRAYED - disabled (grayed out)
%MF_HILITE - highlighted
%MF_SEPARATOR - separator (horizontal line)
%MF_UNCHECKED - no checkmark
Even though state& can be set at the time a menu item is created, remember that the menu item is not visible until the menu item's parent popup menu is selected.
To apply more than one state, combine them with the OR operator.
Menu Statements Examples
Here are examples for each of the menu functions. The
functions are listed in alphabetical order.
Menu Add PopUp, hMenu, "&Text", hPop, %mf_enabled 'now on bar
Before a popup can be added to an existing menu, it must be created first. See the complete example up above.
Menu Add String,hMnu,"&Txt",201,%mf_enabled
Menu Add String, hMnu, "&Txt", 201, %mf_enabled, _
AT BYCMD pos%,CALL callback
Adds a menu item to an existing Popup menu. Normally added at botom of list, but can be inserted at pos% or before pos% (if BYCMD) is used.
Before a string can be added to a popup menu, the popup menu must be created and added to an existing menu bar. See the complete example up above.
Menu Attach hMenu, hDlg
Menu Delete hHelpMenu, BYCMD %ID_About 'deletes %ID_About
Menu Draw Bar hDlg 'use when menu altered by code
Menu Get State hHelpMenu, BYCMD %ID_About TO state&
-1 is returns if the specified menu item does not exist. If the menu item is a popup child menu, LO(BYTE, state&) contains the menu flags for the item, and HI(BYTE, state&) contains the number of items in the popup child menu. Otherwise the result is a bitmask containing one or more of the above mentioned flags combined together with the OR operator to form the bitmask.
Use an equation like this: iResult = state& And %MF_CHECKED to test for the presence of a flag with the returned bitmask.
Menu Get Text hHelpMenu, BYCMD %ID_About TO txt$
Dim hMenu as DWORD
Menu New Bar TO hMenu 'create menu, assign handle to hMenu
Dim hPop As Dword
Menu New PopUp To hPop 'create popup (not yet on menu bar)
Note that this statement creates a popup menu, but does not associate it with an existing menu bar. The Menu Add Popup statement must be used for that purpose.
state& = %MF_CHECKED OR %MF_ENABLED
Menu Set State hHelpMenu, BYCMD %ID_About, state&
Menu Set Text hHelpMenu, BYCOMD %ID_About, "NewText"
Context Menus
The PowerBASIC MENU statements, along with the TrackMenuPopup API
function can be used to provide context menus - menus which appear
when a dialog or control is right clicked.
To create a context menu, a programmer creates a menu item using Menu New Popup, but does not attach the new menu item to a menu bar. Sub-menu strings are added to the Popup just like they would be to any other menu bar popup menu item.
Finally, the TrackPopupMenu API is used to display the unattached Popup menu item at a specific location.
To activate a context menu, press and release the right mouse button. On release, Windows will send a WM_CONTEXTMENU message (as well as the WM_RBUTTONUP message).
The WM_CONTEXTMENU message is used to respond to a menu selection because it is specifically sent when the user selects a command item from a menu - whereas a WM_RBUTTONUP can occur independently of any menu selection.
Here's the basic code for creating a context menu.
Case %WM_CONTEXTMENU
x = Lo(Word,Cb.LParam) : y = Hi(Word, Cb.LParam)
Menu New PopUp To hPopup
Menu Add String, hPopup, "One", 101, %MF_Enabled
Menu Add String, hPopup, "Two", 102, %MF_Enabled
TrackPopupMenu hPopup, %TPM_LEFTALIGN, x, y, 0, Cb.Hndl, ByVal 0
The %TPM_LEFTALIGN value is one of several flags. MSDN says to use zero of more of the following flags.
Horizontal Alignment
Vertical Alignment
To Work Without A Parent Window
Specify Mouse Button
Animation <
For any animation to occur, the SystemParametersInfo function must set SPI_SETMENUANIMATION. Also, all the TPM_*ANIMATION flags, except TPM_NOANIMATION, are ignored if menu fade animation is on,
See the SPI_GETMENUFADE flag in SystemParametersInfo.
Use the TPM_RECURSE flag to display a menu when another menu is already displayed. This is intended to support context menus within a menu.
To have text layout from right-to-left, use TPM_LAYOUTRTL. By default, the text layout is left-to-right.
If you have any suggestions or corrections, please let me know.