ARG-Software Command Bars Library v.4.3

• Overview
• Usage
• Classes
  • CommandBarsManager
  • CommandBar
  • DialogBar
  • MenuBar
  • Popup
  • _ControlButton
  • _ControlComboBox
  • _ControlTextBox
  • _MenuBarItem
  • _MenuItem [1 | 2 | 3 | 4 | 5]

Overview

• Microsoft® Style Toolbars
• Microsoft® Style Menus
• Hide and Show Toolbars
• Add and Remove Toolbar Buttons Dynamically
• Windows XP Theme Support plus Alpha Icons
• Faded Menu and Toolbar Icons
• Disabled Menu and Toolbar Icons
• Menu and Toolbar Icon Shadows
• Menu Shadows
• Menu Shortcuts
• ToolTips and StatusBarText
• Most Recently Used (MRU) type menus
• Tear-Off Popups
• Menu Animations
• ComboBox Control
• TextBox Control
• ButtonPopup Control
• SplitButtonPopup Control

Usage

Register the Builders for the Command Bars Library, run the ACBBuilders.app without parameters, or simply copy it to the Wizards folder ( i.e.: "C:\Program Files\Microsoft Visual FoxPro 8\Wizards\").

Create new or open existing form. Add the ARGCommandBars.VCX to the Form Controls toolbar.

Add the CommandBarsManager object to a form. Right-click the CommandBarsManager object and choose "Builder...".

Use the CommandBarsManager builder to add/remove/customize CommandBars, MenuBars or Popups (Shortcut menus) and set CommandBarsManager properties to required values. You can also Right-click on a command bar, menu bar or popup to build it by using specialized builder.

Use the OnClick property, or add code for the Click event of a command bar buttons and menu items.

Add the following code to the Init event of a form:

DoDefault()

If Type( "ThisForm.CommandBarsManagerName") != "O" ;
    Or IsNull( ThisForm.CommandBarsManagerName)

	&& CommandBarsManager initialization failed: Trial expired, etc.
	Return .F.
EndIf

&& you can set properties of commandbars and/or commandbar controls here;
&& add new commandbars, commandbar controls, build menu, etc.

&& Now you need to call the InitCommandBars method
ThisForm.CommandBarsManagerName.InitCommandBars()

&& ...other initialization code can go here

Now the form is ready to run.

CommandBarsManager Class

Properties:

AttachToFrame

Specifies whether the dock bars will be attached to the frame of the form or not.

AttachToScreen

Specifies whether the dock bars will be attached to the main VFP screen or to the form.

AutoDisable

Specifies whether the commadnbars/menu and the main form will be automatically disabled when a child modal form activates. Default is .F.

ClientArea

The client area (Container control) which will be used with the form. This container will be automatically moved and resized whenever command bars are shown/hidden/docked or floated.
If you do not want to use container leave this property blank, all visible controls will be moved, when necessary, by the library automatically.

CommandBars

Represents the collection of command bars.

DisableCustomize

Specifies whether the customization of command bars is disabled.

DisplayKeysInTooltips

Specifies whether the shortcut key is displayed in a tooltip.

DisplayTooltips

Specifies whether the tool tips are displayed.

FixedControls

The list of fixed controls, the delimiter is a semicolon (;). These controls will not be automatically moved whenever command bars are shown/hidden/docked or floated. May be necessary if you do not use the ClientArea property and want some controls to have fixed position, for sample, status bar control.

LargeButtons

Gets or sets a value indicating whether buttons appear in standard size or in large size.

You can use this property to enhance accessibility. Large buttons are 32 by 32 pixels rather than the standard 16 by 16 pixels.

MainMenu

Specifies the name of the menu bar that will be used as the main menu bar of a form.

MenuAnimationStyle

Specifies the animation type of Popup menus.

0 - System default;
1 - Random;
2 - Unfold;
3 - Slide;
4 - Fade;
5 - None.

VisualTheme

Specifies the visual theme used to display command bars.

0 - Office XP Visual Theme;
1 - Office 2000 Visual Theme;
2 - Office 2003 Visual Theme;
3 - Native Windows XP Visual Theme;
4 - Office 2003 on Windows XP (Luna) Visual Theme;
5 - Visual Studio 2005 Visual Theme;
6 - Office 2007 Visual Theme;
7 - Custom Theme. Based on the Office 2007 Visual Theme;

Methods:

AfterShowModalForm()

Call this memeber function to enable command bars/menu after displaying modal form.

BeforeShowModalForm()

Call this memeber function to disable command bars/menu before displaying modal form.

CreateCommandBar( [ tnCommandBarType [, tcObjectName]])

Creates new command bar, menu, or popup.

Parameters

tnCommandBarType - the type of command bar:

0 - Command Bar, default;
1 - Menu Bar;
2 - Popup;
3 - Dialog Bar.

tcObjectName - the name of command bar object:

Returns

Command bar object.

CreateGradientBitmap( tcFileName, tnColor1, tnColor2, tnSize, tlVertical)

Creates gradient bitmat and writes it to the specified BMP file.

Parameters

tcFileName - BMP file name to create;

tnColor1 - top/left color;

tnColor2 - bottom/right color;

tnSize - width or height of the image. Depends on value of the tlVertical parameter;

tlVertical - gradient fill mode:

.T. - vertical;
.F. - horizontal.

Notes

For more information, see _ACB_COLOR_* definitions in the ARGCommandBars.h file.

ShowModalForm( [ toModalForm])

Disables command bars/menu, displays a modal form, and then enables command bars/menu when modal form closes.

Parameters

toModalForm - reference to the form to be displayed.

GetColor( tnColorIndex)

Returns RGB color value of specified color index.

Parameters

tnColorIndex - the index of a color to retrieve.

Notes

For more information, see _ACB_COLOR_* definitions in the ARGCommandBars.h file.

GetDockBarSize( tnDockBarID)

Returns the size (width or height) of the specified dock bar (docking area).

Parameters

tnDockBarID - the dock bar identifier:

0 - Left;
1 - Top;
2 - Right;
3 - Bottom.

GetFormSize( @rnWidth, @rnHeight)

Returns real size (Width and Height) of the form.

Parameters

rnWidth - receives the Width.

rnHeight - receives the Height.

Notes

Parameters should be passed by reference.

Maybe useful if AttachToFrame property set to .T. the Width and Height properties of the form contain the width and height of client area (inside dock bars), and not real width and height of the form.

InitCommandBar( toCommandBar)

Initializes specified command bar, menu, popup or dialog bar.

InitCommandBars()

Initializes the command bars and menus.

LocalizeString( tnStringID, tcNewValue)

Allows to translate internal string values: commandbar tooltips and popup items.

Parameters

tnStringID - Identifier of a string to localize:

1 - Localize the "Toolbar Options" tooltip;
2 - Localize the "Close" tooltip;
3 - Localize the "&Add or Remove Buttons" item of the Toolbar options popup;
4 - Localize the "&Reset Toolbar" item of the Toolbar options popup.

tcNewValue - Localized string value

RefreshCommandBars( [ tlFullRefresh ])

Refreshes (redraws) the command bars and menus. May be useful when you hide/show controls on a form, a statusbar control, for sample.

Parameters

tlFullRefresh - refresh command bars, menus, popups and all child controls (buttons, menu items, etc). Default - .F.

SetColor( tnColorIndex, tnColorValue)

Sets the RGB value for the specified color index.

Parameters

tnColorIndex - the index of a color to be set;

tnColorValue - RGB color value.

Notes

For more information, see _ACB_COLOR_* definitions in the ARGCommandBars.h file.

SetFormSize( tnWidth, tnHeight)

Set the size of the form.

Parameters

tnWidth - the Width.

tnHeight - the Height.

ShowPopupMenu( toPopupMenu [, tnLeft, tnTop])

Displays the specified popup menu at the current mouse position, or at the specified position relative to the screen.

Events:

OnAdjustClientRect( tnLeft, tnTop, tnRight, tnBottom)

Occurs when the client area has to be resized or moved. You may use this event to adjust the size and position of the client area. For sample, if you have a status bar control on your form, decrease value of the tnBottom parameter by the height of a status bar. All parameters passed by reference.

OnCommand( tnCommandID, toControl)

Occurs when the users clicks the command bar button or menu item. Occurs only if the CommandID property of that button or menu item is not equal to zero.

Note: The Click event doesn't occur for that control.

OnSetStatusBarText( tcStatusMessage)

Occurs when the status message has to be changed. You may use this event to set the status message displayed on your status bar control. By default this event sets the text that is displayed in main VFP status bar.

CommandBar Class

Properties:

AllowFloating

Specifies that the command bar can be a floating command bar.

Caption

Specifies the title of the command bar.

Closable

Specifies whether the Close button appears and the command bar can be closed by clicking the Close button.

CommandBarControls

Represents the collection of command bar controls.

DisableCustomize

Specifies whether the user can customize the command bar.

DockingFlags

Specifies the location(s) where the command bar can be docked to.

DockPosition

Specifies the dock position of the command bar. See also DockPosition property in VFP Help.

HasGripper

Specifies that the command bar will display the "gripper" on the far left of the command bar that lets the user know that the command bar can be "gripped" and moved.

HideCloseButton

Specifies whether the Close button is visible.

HideOptionsButton

Specifies whether the Toolbar Options button is visible.

LockRedraw

Specifies whether a command bar batches all changes to property settings for its contained controls.

Set LockRedraw to True (.T.) to reduce annoying command bar refreshes when its properties or contained controls (state, visibility, and so on) are changed during run time.

MasterToolbar

Specifies the location of the master toolbar. The master toolbar is native VFP toolbar (or derived from).

Movable

Specifies whether the CommandBar can be moved at run time by the user.

ShowTextBelowIcons

Specifies that the caption of buttons will be displayed below the icon.

Stretched

Specifies that the command bar is stretched across the entire window.

Visible

Sets a boolean value indicating whether the command bar is visible.

Methods:

Activate( [tnControlIndex])

Activates the command bar and selects specified control.

CreateControl( [ tnControlType [, tcObjectName]])

Creates new command bar control.

Parameters

tnControlType - the type of control:

0 - Button, default;
1 - ComboBox;
2 - TextBox.

tcObjectName - the name of control:

Returns

Command bar control.

Dock( tnDockPosition [, tnX, tnY])

Docks or undocks the command bar. See also Dock method in VFP Help.

InitControl( toControl)

Initializes specified control.

IsDocked()

Returns a boolean value indicating whether the command bar is docked.

IsVisible()

Return a boolean value indicating whether the command bar is visible.

Move( tnLeft, tnTop)

Undocks the command bar and moves it to the specified position on the screen.

Events:

AfterDock()

Occurs after a command bar is docked.

OnSetMasterControl( toCBControl, tcMasterControlLocation)

Occurs only if the Master toolbar is assigned to the command bar. Occurs when the command bar creates child controls and sets their properties.

UnDock()

Occurs when the commandbar is dragged from its docked position.

DialogBar Class

Properties:

CaptionFlags

Specifies the caption style.

0 - no flags, default;
1 - hide caption of docked DialogBar.

Resizable

Specifies whether the dialog bar will be re-sizable.

ReleaseChildFormOnDestroy

Specifies whether the child form will be released when the dialog bar releases.

Methods:

SetChildForm( toForm || tnFormHandle)

Call this method to specify the child window displayed under the dialog bar.

Parameters

toForm - reference to the child form;
or
tnFormHandle - window handle of the child form.

SetSize( tnWidth, tnHeight)

Call this method to specify the size of child window.

Parameters

tnWidth - specifies the width of the child form;
tnHeight - specifies the height of the child form.

Note

Both the specified width and height are used when the DialogBar is floating. If the bar is docked on the left or right, only the width is used, the height will depend on how much of the client area the dialog bar can occupy. If the bar is docked on the top or bottom, then only the height is used to size the child window.

MenuBar Class

Properties:

AllowFloating

Specifies that the menu bar can be a floating menu bar.

Caption

Specifies the title of the menu bar.

CommandBarControls

Represents the collection of command bar controls.

DockPosition

Specifies the dock position of the menu bar.

HasGripper

Specifies that the menu bar will display the "gripper" on the far left of the menu bar that lets the user know that the menu bar can be "gripped" and moved.

Movable

Specifies whether the MenuBar can be moved at run time by the user.

Stretched

Specifies that the menu bar is stretched across the entire window.

Visible

Sets a boolean value indicating whether the menu bar is visible.

Methods:

CreateControl( [ tnControlType [, tcObjectName]])

Creates new menu bar item.

Parameters

tnControlType - the type of control:

0 - MenuBarItem, always;

tcObjectName - the name of control:

Returns

Menu bar control.

InitControl( toControl)

Initializes specified control.

IsVisible()

Return a boolean value indicating whether the menu bar is visible.

Popup Class

Properties:

CommandBarControls

Represents the collection of command bar controls.

TearOff

Enables the popup control to be teared off and used separately as a floating command bar.

_ControlButton Class

Properties:

BeginGroup

Gets/Sets a boolean value indicating whether the control is a separator and thus begins a new group.

ButtonStyle

Specifies the style of a command bar button.

0 - default;
1 - Caption only;
2 - Image only;
3 - Image and Caption.

ButtonType

Specifies the type of a command bar button.

0 - Standard;
1 - Popup;
2 - ButtonPopup;
3 - SplitButtonPopup.

Caption

Specifies the caption of the command bar button.

Checked

Gets/Sets a boolean value indicating whether the control is checked. See also MarkFor property.

CommandBarControls

Represents the collection of command bar controls.

CommandID

Specifies the command Id of a control. See also OnCommand event of the CommandBarsManager class.

Description

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control.

Enabled

Gets/Sets a boolean value indicating whether the control is enabled. See also SkipFor property.

HideFlags

Control flags.

Currently supported values are:

0 - flags not set;
16 - control is hidden but the user may display it by selecting it in the "Add or Remove Buttons" popup;

OnClick

Gets/Sets a code to be executed when control is clicked. Default value is "This.Click()", the Click event executed.

MarkFor

Checks or unchecks the button. If specified Expression (string value) evaluates to true (.T.), the button is checked. If specified Expression evaluates to false (.F.), the button is unchecked.

Note: The current value of the Checked property is ignored (not used) in case the MarkFor property is not empty. 

Picture

Specifies an image (bitmap or icon file) to display on a control.

SelectedDropDownMenuIndex

Gets/sets the selected dropdown menu index. Applies only to SplitButtonPopup type buttons.

SkipFor

Enables or disables the button. If specified Expression (string value) evaluates to true (.T.), the button is disabled. If specified Expression evaluates to false (.F.), the button is enabled.

Note: The current value of the Enabled property is ignored in case the SkipFor property is not empty.

ShortcutText

Gets/Sets the shortcut text of the control.

ToolTip

Gets/Sets the Tooltip text associated with the control.

Visible

Gets/Sets a boolean value indicating whether the control is visible.

Methods:

CreateControl( [ tnControlType [, tcObjectName]])

Creates new dropdown menu item.

Parameters

tnControlType - the type of control:

0 - MenuItem, always;

tcObjectName - the name of control:

Returns

Menu item control.

GetIconHandle()

Returns icon handle, or 0 (zero) if a control doesn't have an icon.

InitControl( toControl)

Initializes specified control.

IsVisible()

Return a boolean value indicating whether the control is visible.

SetPicture( tuPicture)

Sets the picture for the button.

Parameters

tuPicture - image file name, or icon handle. See also GetIconHandle method.

Events:

Click()

Occurs when the user clicks the command bar button.

Note: The Click event doesn't occur if you specify the CommandID for this control.

_ControlComboBox Class

Properties:

BeginGroup

Gets/Sets a boolean value indicating whether the control is a separator and thus begins a new group.

Caption

Specifies the caption of a control.

Description

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control.

DisplayCaption

Gets or sets a value indicating whether a caption is displayed to the left of the combo box.

DisplayValue

Specifies the text displayed in the text box portion of the combo box.

DropDownStyle

Gets or sets a value specifying the style of the combo box.

The DropDownStyle property controls the interface that is presented to the user. It may be a drop-down list box, where the text portion is not editable and you must select an arrow to view the drop-down, or the default drop-down list box, where the text portion is editable and the user must press the arrow key to view the list.

DropDownWidth

Gets or sets the width of the of the drop-down portion of a combo box. The width, in pixels, of the drop-down box.

Enabled

Gets/Sets a boolean value indicating whether the control is enabled.

List

A character string array used to access the items in a combo box control.

ListCount

Specifies the number of items in the list portion of a combo box.

ListIndex

Specifies the index number of the selected item in a combo box.

MaxLength

Gets or sets the maximum number of characters allowed in the editable portion of a combo box.

OnClick

Gets/Sets a code to be executed when control is clicked. Default value is "This.Click()", the Click event executed.

OnSelectedIndexChange

Gets/Sets a code to be executed when selected list index changes. Default value is "This.InteractiveChange()", the InteractiveChange event executed.

ToolTip

Gets/Sets the Tooltip text associated with the control.

Visible

Gets/Sets a boolean value indicating whether the control is visible.

Width

Specifies the width of the combo box, includes the width of caption in case the DisplayCaption property is set to true.

Methods:

AddItem( tcString [, tnIndex])

Adds a new item to a combo box, optionally making it possible for you to specify the item's index.

Clear()

Clears the contents of a combo box control.

RemoveItem( tnIndex)

Removes an item from a combo box.

Events:

Click()

Occurs when the user clicks a combo box item. See also OnClick property.

InteractiveChange()

Occurs when selected list index changes. See also OnSelectedIndexChange property.

_ControlTextBox Class

Properties:

BeginGroup

Gets/Sets a boolean value indicating whether the control is a separator and thus begins a new group.

Caption

Specifies the caption of a control.

Description

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control.

DisplayCaption

Gets or sets a value indicating whether a caption is displayed to the left of the text box.

Enabled

Gets/Sets a boolean value indicating whether the control is enabled.

MaxLength

The maxumum number of characters allowed in the text box. The default is 0, which indicates that the property is not set.

OnClick

Gets/Sets a code to be executed when control is clicked. Default value is "This.Click()", the Click event executed.

OnTextChange

Gets/Sets a code to be executed when the content of the text box changes. Default value is "This.InteractiveChange()", the InteractiveChange event executed.

ReadOnly

Specifies whether the user can edit the text in a text box.

SelectOnEntry

Specifies whether text in a text box selected when the user moves to it.

ToolTip

Gets/Sets the Tooltip text associated with the control.

Visible

Gets/Sets a boolean value indicating whether the control is visible.

Width

Specifies the width of the text box, includes the width of caption in case the DisplayCaption property is set to true.

Events:

InteractiveChange()

Occurs when the content of the text box changes. See also OnTextChange property.

_MenuBarItem Class

Properties:

Caption

Specifies the caption of the menu bar item.

CommandBarControls

Represents the collection of command bar controls.

Description

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control.

Enabled

Gets/Sets a boolean value indicating whether the control is enabled

TearOff

Enables the sub-popup to be teared off and used separately as a floating command bar.

Visible

Gets/Sets a boolean value indicating whether the control is visible.

Methods:

CreateControl( [ tnControlType [, tcObjectName]])

Creates new menu item.

Parameters

tnControlType - the type of control:

0 - MenuItem, always;

tcObjectName - the name of control:

Returns

Menu item control.

InitControl( toControl)

Initializes specified control.

_MenuItem Class

Properties:

BeginGroup

Gets/Sets a boolean value indicating whether the control is a separator and thus begins a new group.

ButtonStyle

Specifies the style of a command bar button.

Caption

Specifies the caption of the menu item.

Checked

Gets/Sets a boolean value indicating whether the control is checked. See also MarkFor property. 

CommandBarControls

Represents the collection of command bar controls.

CommandID

Specifies the command Id of a control. See also OnCommand event of the CommandBarsManager class.

Description

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control.

Enabled

Gets/Sets a boolean value indicating whether the control is enabled. See also SkipFor property. 

MarkFor

Checks or unchecks the item. If specified Expression (string value) evaluates to true (.T.), the item is checked. If specified Expression evaluates to false (.F.), the item is unchecked.

Note: The current value of the Checked property is ignored in case the MarkFor property is not empty. 

OnClick

Gets/Sets a code to be executed when control is clicked. Default value is "This.Click()", the Click event executed.

Picture

Specifies an image (bitmap or icon file) to display on a control.

SkipFor

Enables or disables the item. If specified Expression (string value) evaluates to true (.T.), the item is disabled. If specified Expression evaluates to false (.F.), the item is enabled.

Note: The current value of the Enabled property is ignored in case the SkipFor property is not empty.

ShortcutText

Gets/Sets the shortcut text of the control.

SpecialControl

Specifies the type of menu item, normal or special.

0 - Normal, default;
1 - ToolBarList, the tool bar list is displayed in place of menu item;
2 - WindowList, the list of windows is displayed in place of menu item;
3 - CustomList, allows you to build your own dynamic lists. See also OnBuildCustomList event.

The CustomList type allows to create the list of open forms, most recent files, and so on. See samples (form2) for more information.

TearOff

Enables the sub-popup to be teared off and used separately as a floating command bar.

ToolTip

Gets/Sets the Tooltip text associated with the control.

Visibility

MRU options. Specifies if the menu item is rarely used and it is not visible because the expandable menus option is on.

Visible

Gets/Sets a boolean value indicating whether the control is visible.

Methods:

CreateControl( [ tnControlType [, tcObjectName]])

Creates new menu item.

Parameters

tnControlType - the type of control:

0 - MenuItem, always;

tcObjectName - the name of control:

Returns

Menu item control.

InitControl( toControl)

Initializes specified control.

Events:

Click()

Occurs when the user clicks the menu item.

Note: The Click event doesn't occur if you specify the CommandID for this control.

OnBuildCustomList( taListItems)

Occurs before the parent popup is displayed. Allows to build custom list

Note: This event occurs only for special menu items, SpecialControl = 3.

Parameters

taListItems - array of custom items

Column	Type	Description
1	N	Item Options
2	C	Caption
3	C	Command (Action) to execute
4	C	Status message
5	N	Icon Handle

Example

LParameters taItems

Dimension taItems[ 3, 5]

taItems[ 1, 1] = 0
taItems[ 1, 2] = "Custom item #1"
taItems[ 1, 3] = "MessageBox( 'Custom item #1')"
taItems[ 1, 4] = "Custom item #1"
taItems[ 1, 5] = 0

taItems[ 2, 1] = 0
taItems[ 2, 2] = "Custom item #2"
taItems[ 2, 3] = "MessageBox( 'Custom item #2')"
taItems[ 2, 4] = "Custom item #2"
taItems[ 2, 5] = 0

taItems[ 3, 1] = 0
taItems[ 3, 2] = "Custom item #3"
taItems[ 3, 3] = "MessageBox( 'Custom item #3')"
taItems[ 3, 4] = "Custom item #3"
taItems[ 3, 5] = 0