ActiveX Pie Menu Documentation

Getting Pie Menus

Take a look and feel free! You can download the complete source code and compiled binary "piemenu.ocx" control for Windows, from: http://www.piemenu.com/ActiveXPieMenuSource.zip

The Pie Menu Web Page, maintained by Don Hopkins has more information about pie menus.

The Pie Menu Video is an instructional demo of ActiveX pie menus, and demos of many different pie menus developed over 12 years.

Integrating Pie Menus

Ole Control Containers

TODO.

ActiveX Web Pages

TODO.

Visual Basic

TODO.

Visual C++ Projects

TODO.

Configuring Pie Menus

Property Pages

TODO.

Menu Outlines

TODO.

Programming Pie Menus

Pie Menu Properties

• string Items (get/set, default "North;East;South;West")

  The "Items" property contains a string that defines the menu items. The syntax for Menu Outlines is described above. The outline format supports syntactic sugar like using ";" to separate lines. These are expanded when you set the "Items" property, so when you read it back again, the ";"s will have been converted to new lines and indentation. Each line is separated by a "carriage return, line feed" pair, and bare newlines or carriage returns are converted to cr/lf pairs.

• long ItemCount (get)

  The read-only "ItemCount" property tells the number of items in the menu, including submenu labels and submenu items. It is the count of the number of lines in the "Items" property. The index argument to the "Item" indexed property methods should be less than this number.

• long Direction (get)

  The read-only "Direction" property tells the direction from the menu center to the cursor. The direction is measured in degrees, from 0 to 359, counter clockwise from three o'clock. It updates dynamically during tracking, and retains the final cursor direction once an item is selected and the menu pops down.

• long Distance (get)

  The read-only "Distance" property tells the distance from the menu center to the cursor, measured in pixels. It updates dynamically during tracking, and retains the final cursor distance once an item is selected and the menu pops down.

• long Index (get)

  The read-only "Index" property tells the index of the currently selected item, ranging from zero, less than "ItemCount". If nothing is selected, its value is -1.

• string Action (get)

  The read-only "Action" property contains the action of the currently selected item, which is an arbitrary string that can be associated with each item. If an item doesn't have an associated action, the action defaults to the item label "CurrentItem". Items can have actions that are different from the label, for the convenience of the menu handler, which might be more interested in a magic number or a special string id, than the human readable item label.

• string CurrentItem (get)

  The read-only "CurrentItem" property contains the label of the currently selected item. Usually it's better to key the menu handler off of the "Action", which can be different from the label. For example, the label could be the name of a month, and the action could be the number of the month, which is easier for the handler to process.

• color ForeColor (get/set, default black)

  The "ForeColor" property controls the foreground color of the control. This applies to the target window on the screen, not the popup pie menus.

• color BackColor (get/set, default white)

  The "BackColor" property controls the background color of the control. This applies to the target window on the screen, not the popup pie menus.

• color PieForegroundColor (get/set, default black)

  The "PieForegroundColor" property controls the foreground color of the control. This applies to the target window on the screen, not the popup pie menus.

• color PieBackgroundColor (get/set, default green)

  The "PieBackgroundColor" property controls the background color of the control. This applies to the target window on the screen, not the popup pie menus.

• color LightColor (get/set, default light green)

  The "LightColor" property controls the light shadow color of the pie menu's beveled edges. It only applies if the "Bevel" property is turned on.

• color DarkColor (get/set, default dark green)

  The "DarkColor" property controls the dark shadow color of the pop-up pie menu's beveled edges. It only applies if the "Bevel" property is turned on.

• font Font (get/set, default from system)

  The "Font" property controls the font of the pie menu labels.

• picture TargetPicture (get/set, default null)

  The "TargetPicture" property controls the background image of the pie menu target window, the control window that's displayed on the screen, that you can click on to pop up the pie menu. The target picture is scaled to the size of the pie menu control's window. If the TargetPicture is null, the BackColor is used instead.

• picture BackgroundPicture (get/set, default null)

  The "BackgroundPicture" propery controls the background image of the pop-up pie menus. This image is scaled to fit each popup window. If you select a ShapePicture, the background picture is scaled to the same size, so it functions as a mask. If the BackgroundPicture is null, the BackColor is used instead.

• picture ShapePicture (get/set, default null)

  The "ShapePicture" property controls the shape of the pop-up pie menus, in conjunction with the "ShapeCenterX", "ShapeCenterY", "ShapeTransparentX", and "ShapeTransparentY" properties, when the "ShapeWindow" property is set to 6 (for "Picture"). These properties control the origin and transparent color of the shape. The menu is centered on the position given by "ShapeCenterX" and "ShapeCenterY", and the shape of the window is defined by the transparent pixel color in ShapePicture at "ShapeTransparentX" and "ShapeTransparentY".

• long ShapeWindow (get/set, default 2)

  The "ShapeWindow" property controls the shape of the popup pie menu windows. It can take on several values, including:

  • 0: Rectangular
    Boring rectangular popup menu windows. No dynamic shaping.
  • 1: Minimal
    Minimal area windows, just the menu center and labels. Dynamic shaping shows menu center and selected label.
  • 2: Round
    Big round window that encompass all the labels. Dynamic shaping shows selected pie slice and label.
  • 3: Thought
    Thought balloons, with bubbles leading to labels. Dynamic shaping shows bubbles leading from menu center to selected label.
  • 4: Speech
    Speech balloons, with pointers leading to labels. Dynamic shaping shows pointer leading from menu center to selected label.
  • 5: Spokes
    Spokes radiating out from the menu center to the labels. Dynamic shaping shows spoke leading from menu center to selected label.
  • 6: Picture
    Shape defined by a picture mask. You must also define the "ShapePicture", "ShapeCenterX", "ShapeCenterY", "ShapeTransparentX", and "ShapeTransparentY" properties. Dynamic shaping shows masked shape and selected label.
  • 7: Punched
    Rectangular window with a round hole punched out of the middle of it.

• long MaxSlices (get/set, default 8)

  This property can take on the values 0, 1, 2, 4, and 8, defaulting to 8. If it's 0, the number of slices is not limited or increased. If it's non-zero, the number of slices is limited to that number or fewer. Then extra inactive slices may be added to round up the number of items. If there are 3 items, an extra is added to make 4 slices, and if there are 5, 6, or 7 items, extras are added to make 8 slices. Items are re-arranged so that they are added in left to right, top to bottom reading order.

• long InactiveRadius (get/set, default 8)

  The "InactiveRadius" property controls the size of the hole in the center of the pie menu, which doesn't select any items.

• long MinRadius (get/set, default 24)

  The "MinRadius" property control the minimum radius around which the labels are layed out.

• long Clockwise (get/set, default 1)

  The "Clockwise" property controls the rotational direction in which the labels are layed out.

• long InitialAngle (get/set, default 90)

  The "InitialAngle" property controls the layout angle of the first menu item. The first slice of the menu is centered on that direction, and the others are evenly spaced around the circle in the direction controlled by the "Clockwise" property. The initial angle is measured in degrees, counter clockwise from three o'clock.

• long BorderWidth (get/set, default 8)

  The "BorderWidth" property control the extra border around the edge of the popup menu window. Its effect is most obvious with rectangular popup windows, since the other window shapes are clipped around the labels.

• long ItemBorderWidth (get/set, default 1)

  The "ItemBorderWidth" property controls the extra border around the edge of each item label.

• long ItemGap (get/set, default 1)

  The "ItemGap" property controls the size of the gap around each item that keeps them from overlapping.

• long ExtraRadius (get/set, default 0)

  The "ExtraRadius" property controls the extra radius that is added in after the menu is layed out so no items overlap.

• long FixedRadius (get/set, default 0)

  The "FixedRadius" property controls the radius of the menu directly by overriding the layout routine, if it's non-zero.

• long ShrinkWrap (get/set, default 0)

  The "ShrinkWrap" property effects the layout behavior when non-zero, by moving the menu items in tighter towards the menu center when possible. It may result in smaller but less symetrical layouts.

• long SliceInset (get/set, default 4)

  The "SliceInset" property controls the radius by which the slice lines are inset.

• long Bevel (get/set, default 1)

  The "Bevel" property controls whether the edges of the popup pie menu windows are beveled. If it's non-zero, then the edges are beveled with the "LightColor" and the "DarkColor". Bevels can be applied to any shape of window, even arbitrary shapes defined by the "ShapePicture". If it's zero, then the edges are stroked with the "ForeColor".

• long DoubleBuffer (get/set, default 1)

  The "DoubleBuffer" property control the painting behavior of the pop-up pie menus. If it's non-zero, the painting is double buffered, so it doesn't flicker. This makes the dynamic window reshaping during tracking look much nicer.

• long PopupDelay (get/set, default 250)

  The "PopupDelay" property controls how long the cursor has to be still before a menu pops up on the screen. This allows you to smoothly "mouse ahead" through pie menus, to invisibly select items without disrupting the screen. The delay is measured in microseconds (1/1000 of a second).

• long ScrollingMovesCursor (get/set, default 0)

  The "ScrollingMovesCursor" property controls whether or not the cursor is moved back to the original menu center, when you scroll between item groups.

• long DynamicShaping (get/set, default 1)

  The "DynamicShaping" property controls the shape of the window during tracking, when an item is selected. If it's non-zero, and the "ShapeWindow" property is not 0 ("Rectangular"), then the pie menu popup window is dynamically reshaped whenever an item is selected and the button is down, to show just that item. When no items are selected or the button is not down, the window shape encompasses all of the items.

• long ShapeCenterX (get/set, default -1)

  The "ShapeCenterX" property defines the horizontal center of the menu shape, when the "ShapePicture" property in non-null and the "ShapeWindow" property is 6 (for "Picture"). If it's -1 (the default), the horizontal center of the ShapePicture is used.

• long ShapeCenterY (get/set, default -1)

  The "ShapeCenterY" property defines the vertical center of the menu shape, when the "ShapePicture" property in non-null and the "ShapeWindow" property is 6 (for "Picture"). If it's -1 (the default), the vertical center of the ShapePicture is used.

• long ShapeTransparentX (get/set, default 0)

  The "ShapeTransparentX" property helps define the shape of the popup pie menu window, when the "ShapePicture" property in non-null and the "ShapeWindow" property is 6 (for "Picture"). Together with "ShapeTransparentY", it specifies the location of a transparent pixel in the "ShapePicture" image, so it can be used as a mask.

• long ShapeTransparentY (get/set, default 0)

  The "ShapeTransparentY" property helps define the shape of the popup pie menu window, when the "ShapePicture" property in non-null and the "ShapeWindow" property is 6 (for "Picture"). Together with "ShapeTransparentX", it specifies the location of a transparent pixel in the "ShapePicture" image, so it can be used as a mask.

• IDispatch* UserData (get/set, default null)

  The "UserData" property is a place for programmers to stash an IDispatch pointer, for their own purposes. It's just a runtime pointer, not saved with the menu.

• long CPieMenuCtrl (get)

  The read-only "CPieMenuCtrl" property returns a raw pointer to the CPieMenuCtrl object, as a long integer. This is so the property pages can get intimate with the pie menus to provide advanced editing features. It's not for casual use, and shouldn't be used by code outside of the piemenu.ocx library.

• long Revision (get)

  The read-only "Revision" property increments each time the pie menu changes, so the property pages viewing the pie menu can know when to update their representations. It's not for casual use.

Pie Menu Methods

• void PopUp(long x, long y)

  The "PopUp" method pops the menu up underneath the cursor, ignoring the x and y arguments. Pie menus should always pop up underneath the cursor, so the x and y parameters do not matter, but they're included for compatibility with other popup menu components. It also works around problems where the coordinate system origin is ambiguous.

• void Clear()

  The "Clear" method deletes all the items in the menu, and is the same as setting the "Items" property to the null string.

• string Item(long index)

  The "Item" method retrieves the string of an indexed item. The items are numbered from zero, and include the submenu labels and indented submenus in depth first order, which is just the order of the lines in the "Items" outline.

• void Item(long index, string newValue)

  The "Item" method sets the string of an indexed item. In the case of indented submenu items, you must provide the appropriate indentation, since the given line of the "Items" outline is literally replaced and the outline is re-interpreted. If you want to change more than one item, it is more efficient to recreate the entire menu string and set the "Items" property all at once.

  These two "Item" methods implement the indexed "Item" property, so you can get and set "PieMenu.Item(0)" as if it were an indexed string array property.

Pie Menu Events

• void Preview(string item, string action, long direction, long distance)

  The "Preview" event is fired whenever the mouse moves, while the pie menu is popped up. It can be used to dynamically track the direction and distance of motion, as well as the selected item.

• void Change(string item, string action, long direction, long distance)

  The "Change" event is fired whenever the selected item changes. It can be used to dynamically track the selected item before the final selection has been made.

• void Action(string item, string action, long direction, long distance)

  The "Action" event is fired when the final selection is made. It can be used to perform the effects of the menu selection. The "item" argument is the label of the selected item. The "action" argument is the action associated with the item, which defaults to the item label. The "direction" argument is measured in degrees, counter clockwise from three o'clock. The "distance" argument is measured in pixels from the menu center. They can be used as arguments to the menu selection.

• void Cancel()

  The "Cancel" event is fired when a popped up menu is canceled without making a selection. It can be used to tell when the menu is no longer popped up, in cases when no selection was performed.