SpaceMonger Customization

[ Prev: 3. Strings | Up: Contents | Next: 5. Key Bindings ]

4. Menus |

> You can change every menu and toolbar in SpaceMonger to anything you want. If you're just doing a translation, you should not change the layout of the menus. If you're customizing the program, you can change them as much as you want.

4a. Menu Tags |

> Menus are defined by menu tags. Menu tags generally follow this structure:

>     <menu name="my-menu" icons="icon-file.bmp" iconheight="16" iconwidth="16">
>     	...
>     	items and separators
>     	...
>     </menu>

> Every menu has a name that is used to identify it; for example, the menu named "main" is displayed at the top of the screen as a menu-bar/button-bar, and the menu named "context" appears when the user right-clicks on an object in the maps.

> Menu items can have icons displayed beside them. The icons are taken from a given image file in the same folder as the language files. The image file must be an uncompressed Windows BMP or TrueVision Targa file. All items in a menu get their icons from one image, but you may have a different image for each menu. The icons in a menu are all the same size, taken from consecutive portions of the image (as described below).

> You may create your own menus and reference them as popup menus from other menus. You may have as many sub-popups as you want.

> Menu tags may also have the special `reset` attribute, which looks like this:

>     <menu name="my-menu" reset="reset" ...>

> The `reset` attribute is useful when importing between databases; it causes the contents of any previous menu with the same name to be removed so that you're starting with an empty menu (without it, you would simply be appending to the existing menu).

4b. Menu Separators |

> Menu items can be separated by separator bars, which are the little horizontal (and vertical) lines you sometimes see in menus. You add a separator with one of the following three tags:

>     <sep/>
>     <sep style="horz"/>
>     <sep style="vert"/>

> The first two of these tags add a horizontal separator between menu items. The last tag adds a vertical separator and begins a new column of menu items.

4c. Menu Items |

> Each line of text on a menu is a "menu item". In general, each one is defined with a single `<item>` tag, more-or-less like one of these two lines:

>     <item action="action">Action</item>

>     <item submenu="menu">Sub-menu</item>

> The text in the quotation marks labeled here as `"action"` specifies what to do when the menu item or button is clicked by the user. It is an Action, which is a special kind of text string that you can learn more about in Section 6. The text in the submenu line names which menu to drop-down or pop-up when the menu item is clicked on or rolled over, depending on what kind of menu this item is contained within.

> Menu items may have one letter underlined, which will activate the menu item when the letter's associated key is pressed. To make a letter underlined, add `&amp;` before it. To include an actual ampersand, use `&amp;&amp;`.

>     <item>&amp;Open</item>

>     <item>Black &amp;&amp; White</item>

> Menu items may have associated "alternate" information. In drop-down and popup menus, the "alternate" information is displayed next to the item's text, right-justified. In menu bars and toolbars, the "alternate" information is displayed as a little yellow popup tooltip when the mouse rolls over the item. To add "alternate" information, separate it with a tab character:

>     <item action="open">Open&tab;Ctrl+O</item>

>     <item action="zoom-in">Zoom In&tab;Zoom in on the map</item>

> You can also add icons to menu items. To add an icon, add an attribute index to the item:

>     <item action="open" icon="1">Open</item>

> The index determines which part of the menu's image is used for the icon for this menu item. The image is assumed to be a set of horizontal strips of icons, each being the size given in the menu's tag. Thus if you use a 80×64-pixel image, and the icons are 16×16, then the icons in the image have these indices:

> 0 | 1 | 2 | 3 | 4
> 5 | 6 | 7 | 8 | 9
> 10 | 11 | 12 | 13 | 14
> 15 | 16 | 17 | 18 | 19

> Thus for this image, an icon index of "1" means to use the sub-image whose rectangle's upper-left corner is at (16,0) and whose size is (16,16).

> You can have transparent pixels in the icons by simply using a file format that supports a full alpha channel (or mask channel). BMP does not support this, but Targa does. SpaceMonger can draw paletted images and truecolor images, with or without alpha, in up to 24-bit color. (Note: as of this writing, not many programs seem to support creating Targa files with an alpha channel; in particular, Adobe Photoshop 5.5 and lower do not appear to correctly handle Targa's alpha channel. For what it's worth, all of the images used in SpaceMonger 2.1 were created with Corel Photo-Paint 11.)

> Menu items also frequently have a `comment` attached. A comment is displayed in a pop-up tooltip beside the menu item when it is highlighted or when the mouse moves over it. It provides more detailed information about the menu item, like this:

>     <item comment="Open the currently-selected file or folder">Open</item>

> When importing menus from another database, you may want to replace menu items in the imported menus. You can do this by using the `mode` attribute on a menu item:

>     <item action="open" mode="replace">Open</item>

> There are two allowed modes: replace, and append (the default). In append mode, new items are added at the end of the menu. In replace mode, the language parser searches for any existing menu item with the same action or submenu and replaces that existing item with this new one.

[ Prev: 3. Strings | Up: Contents | Next: 5. Key Bindings ]

Copyright © 2006 by Sixty-Five, Inc. All Rights Reserved.