Welcome
Welcome to the Aestan Tray Menu manual! In this help file, you'll (hopefully) find all the information you need in order to work with AeTrayMenu.

Getting Started

The best way of getting started is probably just reading through the whole help file. Look through the topics in this file sequentially, and read about the things you don't know yet. If you're looking about information on what AeTrayMenu is, start with the topic What is AeTrayMenu?; if you want to get started customizing it, read How to Configure?.

Finding More Information

Visit the AeTrayMenu website for the latest news and updates.


What is Aestan Tray Menu?

What is AeTrayMenu?
When a friend requested me to write an imitation of the External link (opens in a new window) Apache Service Monitor, I decided I wanted to write something that would be generally useful and flexible. With Aestan Tray Menu, you can create your own tray menu with access to all sorts of applications, documents and services.

What does it do?

AeTrayMenu puts a tray icon in your system tray. When you click on it with your left or right mouse button, a popup menu will appear. The menus that appear are fully configurable.

Features

An overview of the most important features of AeTrayMenu:
  • Fully configurable;
  • Separate menus for left and right click;
  • Run programs and launch documents;
  • Support for submenus;
  • Service control options:
    • Start, stop, pause and resume services;
    • Separate tray icons and tray icon hints for service states;
    • Easy access to "Services" control panel applet
  • Special menu design with sidebar and more;
  • Execute multiple commands for one menu item;
  • Handling of multiple instances.

Configuration

To tell AeTrayMenu what your menus should look like, you have to write a configuration file. Read on here for more information on this topic.

See also See Also
How to Configure


Documentation Conventions
Text that you would enter in a script file is given in monospaced text.

A text like dog|cat|fish means that you can either choose dog, cat or fish.

Code examples are given in blue-lined boxes, like this.

Furthermore, you may encounter the following icons in this help file:

  • REQ - indicates that a parameter or directive is required (if you don't specify it, a syntax error will occur);
  • VAR - indicates that you may use variables when entering the value of a parameter or directive.


How to Configure?
AeTrayMenu reads its settings from a script, a text file with a format somewhat similar to .INI files (actually, the format was taken from Inno Setup by Jordan Russell).

Normally AeTrayMenu tries to load a .INI file in the same directory and with the same name as the executable. However, you can also specify a script file by using the -scriptfile command-line parameter.

In the Examples directory (located in the directory where you've installed AeTrayMenu), you'll find a couple of sample scripts.

See also See Also
Script Format Overview
Command-line Parameters


Script Format Overview
AeTrayMenu scripts are divided into sections. Each section controls a different aspect of the behaviour of the tray menu. A section is started by specifying the name of the section enclosed in square brackets [ ]. Each section contains a number of entries.

There are two different types of sections: those such as [Config] whose entries contain directive names and values (in the form Directive=Value), and those such as [Variables] whose entries are divided into parameters.

Here is an example:

[Config]
ImageList=myimages.bmp
TrayIcon=myicon.ico

[Variables]
Name: MyAppVersion; Type: static; Value: "version 1.0"

Note that you can specify multiple sections of the same name. In this case, the contents of those sections are merged.

You can put "comments" in the script (which are ignored by AeTrayMenu) by placing a semicolon at the beginning of a line. For example: ; This is a comment. I could put reminders to myself here...

See also See Also
Parameters in Sections
Variables
[Config] Section


Parameters in Sections
All of the sections in a script, with the exception of [Config], [Messages] and [Menu.*.Settings], contain lines separated into parameters. The following is an example of a [Variables] section: [Variables] Name: MyAppVersion; Type: static; Value: "version 1.0" Name: MyAppPath; Type: registry; Root: HKLM; Key: "Software\MyApp"; ValueName: InstallPath; Flags: ispath

Each parameter consists of a name, followed by a colon, and then a value. Unless otherwise noted, parameters are optional in that they assume a default value if they are not specified. Multiple parameters on a line are separated by a semicolons, and can be listed in any order.

The value of a parameter is traditionally surrounded in double quotes (") when it contains a user-defined string, such as a filename. Using quotes is not required, though, but by doing so it makes it possible to embed leading and trailing spaces in the value, as well as semicolons and double-quote characters.

To embed a double-quote character inside a quoted value, use two consecutive double-quote characters. For example: "This "" contains "" embedded "" quotes" AeTrayMenu would see that as: This " contains " embedded " quotes

If you want the value of a parameter to be a single double-quote character, use four double-quote characters: """". The outer two are needed to surround the string in quotes; the inner two are used to embed a single double-quote character.


Variables
The majority of the script entries can have variables embedded in them. These are predefined strings enclosed in percent characters %. AeTraymenu translates the variables to their literal values, depending on e.g. the system configuration. For example, %ProgramFiles%, as described below, would translate to "C:\Program Files" on most systems.

You can define your own variables in the [Variables] section.

If a variable has been marked as a path variable, AeTrayMenu automatically removes any double backslashes that are caused by the variable's contents ending in a backslash. For example, if a particular path variable myvar would contain the value C:\, and you would type %myvar%\file, AeTrayMenu would translate this to C:\file and not C:\\file.

In this documentation, parameters and directives that may include variables are marked with this icon: VAR.

Built-in Variables

Besides the variables you can define in the [Variables] section, AeTrayMenu already provides the following variables:
%AeTrayMenuPath% (path variable)
The directory in which the AeTrayMenu executable is located.
%Cmd%
The full pathname of the system's standard command interpreter. On Windows NT/2000/XP, this is Windows\System32\cmd.exe. On Windows 9x/Me, this is Windows\COMMAND.COM. Note that the COMSPEC environment variable is not used when expanding this constant.
%CommonFiles% (path variable)
Common Files. The path of the system's Common Files directory, typically "C:\Program Files\Common Files".
%Program Files% (path variable)
Program Files. The path of the system's Program Files directory, typically "C:\Program Files".
%System% (path variable)
The system's Windows System directory (System32 on Windows NT platforms).
%SysDrive% (path variable)
The drive onto which Windows has been installed.
%Temp% (path variable)
The Windows temporary directory. This is the value of the user's TMP or TEMP environment variable.
%Windows% (path variable)
The system's Windows directory, typically "C:\WINDOWS" or "C:\WINNT" on NT systems.

See also See Also
[Variables] section


[Config] Section
This section contains general settings, some of which are required. Here is an example of a [Config] section:
[Config]
ImageList=images.bmp
TrayIcon=trayicon.ico
ServiceCheckInterval=3
ID={42F9F6BD-49C0-42E6-8250-25C98ACE1DAB}

The following directives can be placed in the [Config] section:

General

  • ID
  • ImageList REQ
  • TrayIcon REQ

Services-related

  • ServiceCheckInterval
  • ServiceGlyphPaused, ServiceGlyphRunning, ServiceGlyphStopped
  • TrayIconAllRunning, TrayIconNoneRunning, TrayIconSomeRunning


[Messages] Section
Some of the message texts used in AeTrayMenu can be changed by setting directives in this section. Here is an example of a [Messages] section:
[Messages]
AllRunningHint=Service Monitor - All services are up and running
SomeRunningHint=Service Monitor - Some of your services are down!
NoneRunningHint=Service Monitor - None of your services are running!!!

The following directives can be placed in the [Messages] section:

  • AllRunningHint, NoneRunningHint, SomeRunningHint


[Variables] Section
In this section, you can define your own Variables. The variables are initialized at startup (when reading the configuration file).

Here is an example of a [Variables] section: [Variables] Name: MyAppVer; Type: static; Value: "version 1.0" Name: MyAppPath; Type: registry; Root: HKLM; Key: "Software\My Company\My App"; ValueName: "InstallPath"; Flags: ispath; DefaultValue: "%ProgramFiles%\MyApp" Name: ComputerName; Type: environment; EnvName: "COMPUTERNAME" Name: MyParam; Type: commandline; ParamName: "MyParam"; DefaultValue: "Cow" Name: Prompt; Type: prompt; PromptCaption: "My Tray Menu"; PromptText: "Please enter a message:"; DefaultValue: "Hello World"

The following is a list of the supported parameters:

NameREQ

Value

String

Description

The name of the variable.

Example

Name: MyVariable
TypeREQ

Value

static|registry|environment|commandline|prompt

Description

Tells AeTrayMenu what sort of variable you're creating. The following variable types are available:
  • Static variables just contain a fixed value;
  • Registry variables are read from the Windows registry;
  • Environment variables are taken from Windows environment variables;
  • Commandline variables are read from the AeTrayMenu command-line arguments;
  • Prompt variables don't contain a fixed value; instead, when they are encountered, a message box pops up, asking the user for its contents.

Example

Type: static
Flags

Value

Flag list

Description

This parameter is a set of extra options. Multiple options may be used by separating them by spaces. The following options are supported:
ispath
Marks the variable as a path variable (see Variables for more information).

Example

Flags: ispath
Value

Value

String

Description

If the variable's type is "static", this parameter specifies the contents of the variable.

Example

Value: "my text here"
Root

Value

HKCR|HKCU|HKLM|HKU|HKCC

Description

For registry variables, this parameter specifies the root key.

Example

Root: HKCU
Key

Value

StringVAR

Description

For registry variables, this parameter specifies the subkey name.

Example

Key: "Software\My Company\My Program"
ValueName

Value

StringVAR

Description

For registry variables, this parameter specifies the name of the registry value to read. If this is blank, the "Default" value is read. The registry value's contents are automatically converted to a string.

Example

ValueName: "Version"
EnvName

Value

StringVAR

Description

For environment variables, this parameter specifies the name of the environment variable to read.

Example

EnvName: "PATH"
ParamName

Value

StringVAR

Description

For command-line variables, this parameter gives the name of the command-line parameter to read (case-insensitive). The command-line parameter should be in the form -name=value. See Command-line Parameters for more information.

Example

ParamName: "myparam"
PromptCaptionVAR

Value

String

Description

Contains the text in the caption bar of the message box that pops up when the prompt variable is encountered.

Example

PromptCaption: "My Tray Menu"
PromptTextVAR

Value

String

Description

Contains the message box text of the prompt that appears when the prompt variable is encountered.

Example

PromptText: "Please enter the message you want to send:"
DefaultValue

Value

StringVAR

Description

If you specify a default value, this value will be used if reading the variable's contents from the registry, the environment or the command-line fails (e.g. because the command-line parameter hasn't been specified, or the key doesn't exist). If reading the variable fails, and no default value has been given, AeTrayMenu will show an error message and exit at startup.

Example 1

DefaultValue: "%ProgramFiles%\MyApp"

Example 2

DefaultValue: ""
This example will cause any errors to be hidden from the user; if there is an error, the variable will be empty.

See also See Also
Variables


[Services] Section
In this section, you can define any services you want to be able to control with AeTrayMenu.

Here is an example of a [Services] section: [Services] Name: Apache2 Name: MySQL

The following is a list of the supported parameters:

NameREQ

Value

String

Description

The name of the service. This is not the display name (as seen in the list of the Services control panel applet), but the 'internal' name of the service. If you open the property sheet of a service in the Services applet, you'll see the service name there (under Service name, not Display name).

Example

Name: Apache2

See also See Also
How to Use the Service Features


[Menu.*.Settings] Section
You can define two popup menus for the tray icon: one for the left mouse button and one for the right button. In the [Menu.Left.Settings] and [Menu.Right.Settings] sections, you can customize the look & feel of those menus.

Here is an example of a [Menu.Right.Settings] section:

[Menu.Right.Settings]
BarVisible=yes
BarCaptionAlignment=bottom
BarCaptionCaption=My Caption
BarCaptionFont=Tahoma,16,clWhite,bold italic
BarGradientEnd=$00550000
BarGradientStart=clBlue
BarGradientStyle=horizontal
BarSide=left
BarSpace=0
BarWidth=32

The following directives can be placed in the [Config] section:

General

  • AutoHotKeys
  • AutoLineReduction
  • MenuFont

Sidebar

  • BarBackPictureDrawStyle
  • BarBackPictureHorzAlignment
  • BarBackPictureOffsetX
  • BarBackPictureOffsetY
  • BarBackPicturePicture
  • BarBackPictureTransparent
  • BarBackPictureVertAlignment
  • BarCaptionAlignment
  • BarCaptionCaption
  • BarCaptionDepth
  • BarCaptionDirection
  • BarCaptionFont
  • BarCaptionHighlightColor
  • BarCaptionOffsetY
  • BarCaptionShadowColor
  • BarPictureHorzAlignment
  • BarPictureOffsetX
  • BarPictureOffsetY
  • BarPicturePicture
  • BarPictureTransparent
  • BarPictureVertAlignment
  • BarBorder
  • BarGradientEnd
  • BarGradientStart
  • BarGradientStyle
  • BarSide
  • BarSpace
  • BarVisible
  • BarWidth

Separators

  • SeparatorsAlignment
  • SeparatorsFade
  • SeparatorsFadeColor
  • SeparatorsFadeWidth
  • SeparatorsFlatLines
  • SeparatorsFont
  • SeparatorsGradientEnd
  • SeparatorsGradientStart
  • SeparatorsGradientStyle
  • SeparatorsSeparatorStyle

See also See Also
[Menu.*] Section


[Menu.*] Section
You can define two popup menus for the tray icon: one for the left mouse button and one for the right button. In the [Menu.Left] and [Menu.Right] sections, you can define the menu-items you want to appear in the menus.

Here is an example of a [Menu.Left] section: [Menu.Left] Type: separator; Caption: "Service Monitor" Type: item; Caption: "&About..."; Action: about; Glyph: 1 Type: item; Caption: "E&xit"; Action: exit Type: separator; Caption: "Services" Type: servicesubmenu; Caption: "&Messenger"; Service: Messenger; SubMenu: MessengerMenu Type: servicesubmenu; Service: ClipSrv; SubMenu: ClipSrvMenu Type: item; Caption: "Start All Services"; Action: multi; Actions: StartAll Type: item; Caption: "Stop All Services"; Action: multi; Actions: StopAll Type: item; Caption: "&Services Applet"; Action: controlpanelservices Type: separator; Caption: "Programs" Type: item; Caption: "&Notepad"; Action: run; FileName: "%Windows%\Notepad.exe"; Glyph: 5 Type: submenu; Caption: "&Other"; SubMenu: MySubMenu; Glyph: 3 [MessengerMenu] ... [ClipSrvMenu] ... [MySubMenu] ...

The following is a list of the supported parameters:

TypeREQ

Value

item|separator|submenu|servicesubmenu

Description

There are four types of menu items:
  • item - a normal menu item that can perform an action when the user clicks on it. You should also specify the Caption and Action parameters.
  • separator - a horizontal line. You can adapt the separators' style using the Separators* settings in the [Menu.*.Settings] sections.
    • If you've set the SeparatorsSeparatorStyle directive to shortline or caption, you can also specify a Caption. Omitting the Caption parameter in case of the caption style causes a 'normal' separator to be drawn.
  • submenu
    • - defines a submenu. You also have to add the Caption and the SubMenu parameters.
  • servicesubmenu - a special kind of submenu whose glyph is automagically adjusted to the running state of the service; see also [Config]: ServiceGlyph*. You also have to specify the Service and SubMenu parameters. If you omit Caption, the caption will be set to the service's display name.

Example

Type: separator
Caption

Value

String

Description

If the item is a menu item, Caption defines the caption of the menu item. The first character that is preceeded by an ampersand (&) will serve as hotkey. If you've set AutoHotKeys to true, it's possible that the hotkey will be changed/added if there are duplicate hotkeys. To embed an ampersand in the caption, use two consecutive ampersands.
If the item is a separator, and if you've set SeparatorsSeparatorStyle to shortline or caption, Caption can be used to insert a text into the separator.

Example

Caption: "&Drag && Drop"
Glyph

Value

Glyph index

Description

If you want a glyph to appear next to the menu item, specify its index here.

Example

Glyph: 2
SubMenu

Value

Section name

Description

If the item's type is submenu or servicesubmenu, you have to create a section in the configuration file in which you list its items. Specify that section's name here.

Example

SubMenu: MySubMenu
Action

Value

Action type

Description

If the item's type is item, then an action is performed when the user clicks it. Take a look at the List of Available Actions for a complete reference on the actions that can be performed by AeTrayMenu.
If the action that's associated with the menu item appears to be unavailable, AeTrayMenu will automatically disable the item. For example, if a service is already running, menu items that would start the service will be disabled.

See also See Also
[Menu.*.Settings] Section
[Config]: ImageList
List of Available Actions


[DoubleClickAction] Section
You can display different menus depending on whether the user clicks the tray icon with the left or right mouse button, but what if the user double-clicks on it?

In the [DoubleClickAction] section, you can list the actions that should be performed when the user double-clicks on the tray icon. Look at the documentation on Batch Action Sections for more information on how to do this, and for an example.

seealso (1K) See Also
Batch Actions Sections


Submenu Sections
You can easily create submenus using the submenu menu item type. When you create a submenu, you have to add a section to your script file with some name; you then have to link the submenu item to that section using the SubMenu parameter of the item.

You can then fill the submenu section with menu items, just as you do with the [Menu.*] sections.

Example

[Menu.Right] Type: submenu; Caption: "Submenu Example"; SubMenu: MySubMenu [MySubMenu] Type: item; Caption: "&About"; Action: about Type: item; Caption: "E&xit"; Action: exit Type: submenu; Caption: "Another Submenu"; SubMenu: AnotherSubMenu [AnotherSubMenu] Type: item; Caption: "&Notepad"; Action: run; FileName: "%Windows%\Notepad.exe"

seealso (1K) See Also
[Menu.*] Section


Batch Actions Sections
If you're using the multi action, or if you want to use the [DoubleClickAction], you'll have to create sections in your script file that contain a list of actions that are to be performed by AeTrayMenu sequentially. (Tip: you could see a batch action section as a [Menu.*] section with some parameters removed).

Here is an example of a [DoubleClickAction] section: [DoubleClickAction] Action: run; FileName: "%Apache%\bin\Apache.exe"; Parameters: "-k install"; ShowCmd: hidden; Flags: waituntilterminated Action: run; FileName: "%MySQL%\bin\mysqld-opt.exe"; Parameters: "--install"; ShowCmd: hidden; Flags: waituntilterminated Action: resetservices Action: service; Service: Apache2; ServiceAction: startresume; Flags: ignoreerrors Action: service; Service: MySQL; ServiceAction: startresume; Flags: ignoreerrors

The following is a list of the supported parameters:

ActionREQ

Value

Action type

Description

If the item's type is item, then an action is performed when the user clicks it. Take a look at the List of Available Actions for a complete reference on the actions that can be performed by AeTrayMenu.
If the action that's associated with the menu item appears to be unavailable, AeTrayMenu will automatically disable the item. For example, if a service is already running, menu items that would start the service will be disabled.

seealso (1K) See Also
How to Use Batch Actions
List of Available Actions
"Multi" Action
[DoubleClickAction] Section


[Config]: ID

Value

String

Description

If you don't want multiple instances of your tray menu running simultaneously, you can put an identifier (ID) into your configuration file. You can use anything you want as an ID, but using a Globally Unique IDentifier (GUID) is recommended. There are various tools on the internet for generating those GUIDs. See below for some links.

When it starts, AeTrayMenu checks if there are any other instances running with the same ID. If so, it immediately terminates. You can also use the ID to close running instances, using the -quit command-line parameter.

Example

[Config] ID={42F9F6BD-49C0-42E6-8250-25C98ACE1DAB}

See also See Also
Command-line parameters
External link (opens in a new window) Aerodynamica Software - Creator of GUIDGen, a handy utility for generating GUIDs


[Config]: ImageList

Value

FilenameVARREQ

Description

As in normal Windows menus, a small image (called a glyph) can appear beside each menu item. Those glyphs are stored in one single bitmap file. This bitmap file should contain one single row of glyphs that are 16 by 16 pixels. This is an example of such a bitmap: imagelistexample (14K) For each glyph, the upper left pixel's color is treated as the transparent color.

All 'glyph index' values (as in for example the TrayIcon*Running directives) specify a glyph in this bitmap. The first (leftmost) bitmap is number 0, the second is number 1 etc.

You can specify a filename relative to the location of the AeTrayMenu executable, or a fully-qualified path.

Examples

[Config] ImageList=images.bmp [Config] ImageList=res\images.bmp [Config] ImageList=%MyAppPath%\traymenuimages.bmp


[Config]: ServiceCheckInterval

Value

Integer

Description

The number of seconds between the moments that AeTrayMenu checks which services are still running. At these moments, the tray icon hint text and, if the TrayIcon*Running directives are set, the tray icon itself are updated.

Example

[Config] ServiceCheckInterval=3

See also See Also
How to Use the Service Features
TrayIconAllRunning, TrayIconNoneRunning, TrayIconSomeRunning


[Config]: ServiceGlyph*

Value

Glyph index

Description

The ServiceGlyphPaused, ServiceGlyphRunning and ServiceGlyphStopped directives control which glyph is displayed for a 'servicesubmenu' menu item when the corresponding service is paused, running or not running.

Example

[Config]
ServiceGlyphRunning=5
ServiceGlyphPaused=6
ServiceGlyphStopped=7

See also See Also
How to Use the Service Features
[Menu.*] Section
[Config]: ImageList


[Config]: TrayIcon

Value

FilenameVARREQ

Description

The value of this directive should point to a Windows icon file; it will be used for the tray icon.

Stopsign You cannot specify both the TrayIcon directive and the TrayIcon*Running directives.

Example

[Config] TrayIcon=trayicon.ico

See also See Also
[Config]: TrayIcon*Running


[Config]: TrayIcon*Running

Value

Glyph index

Description

The directives TrayIconAllRunning, TrayIconNoneRunning and TrayIconSomeRunning control which tray icon is displayed when all, none and some of the services specified in the [Services] section are running. Instead of pointing to a Windows icon file, these directives contain a glyph index that points to a sub-bitmap in the ImageList.

Stopsign You cannot specify both the TrayIcon directive and the TrayIcon*Running directives.

Example

[Config]
ImageList=images.bmp
TrayIconAllRunning=0
TrayIconSomeRunning=1
TrayIconNoneRunning=2

See also See Also
How to Use the Service Features
[Config]: ImageList
[Config]: TrayIcon


[Messages]: *RunningHint

Value

StringVAR

Description

The directives AllRunningHint, NoneRunningHint and SomeRunningHint control the hint text of the tray icon. Which of the hint texts is used depends on whether all, some or none of the services listed in the [Services] section are running.

Besides the normal variables, you can also use two special 'variables' that only work for these directives:

%n
If you include the string %n in your directive value, it will be replaced with the number of services currently running.
%t
Will be replaced with the total number of services listed in the [Services] section.

Examples

[Messages]
AllRunningHint=Service Monitor - All services are up and running
SomeRunningHint=Service Monitor - Some of your services are down!
NoneRunningHint=Service Monitor - None of your services are running!!!

[Messages]
AllRunningHint=All of %t services are running
SomeRunningHint=%n of %t services are running
NoneRunningHint=None of %t services are running

[Messages]
AllRunningHint=My Tray Menu
SomeRunningHint=My Tray Menu
NoneRunningHint=My Tray Menu

See also See Also
How to Use the Service Features
[Services] Section


List of Available Actions
AeTrayMenu can perform certain actions when menu items are clicked by the user. There are also other places where actions appear, such as the [DoubleClickAction] section, and batch action sections.

First of all, you often need to specify which action you want to have performed by specifying an Action parameter. Furthermore, some actions also require additional parameters.

The following is a list of all the available action types along with a description. Actions that need additional parameters will be explained in more detail in separate topics.

about
Displays the AeTrayMenu about dialog.
closeservices
In order to be able to monitor the services you've specified, AeTrayMenu keeps handles open to them. If you want to uninstall a service from within the traymenu, this will cause it to be "marked for deletion" (that is: it won't be fully removed until a reboot) since Windows detects it's still in use. By executing the closeservices action, you can make sure AeTrayMenu won't interfere. You can let AeTrayMenu re-open the handles by executing the resetservices action.
If you want to uninstall a service from an external program while AeTrayMenu is running, you can use command-line parameters to temporarily shut the traymenu down.
controlpanelservices
Displays the "Services" console (on NT systems, you can open it by going to Start > Settings > Control Panel > Administrative Tools > Services).
exit
Shuts down AeTraymenu.
multi
Provides you with a way to execute multiple actions consecutively, much like Windows/DOS batch files. More information... (See also How to Use Batch Actions).
readconfig
This actions lets AeTrayMenu reset itself and reload its configuration file.
resetservices
Causes AeTrayMenu to reset all its handles to the services it monitors. Can e.g. be used to 'restore' the traymenu after a call to the closeservices action.
run
With this type of action, you can run a program. You can specify which program is to be executed, along with the working directory, parameters etc. More information...
service
Allows you to start, stop, suspend, resume and restart services. More information...
shellexecute
This action is similar to the run action, but it can also be used to open documents with their associated programs. More information...

seealso (1K) See Also
[Menu.*] Section
[DoubleClickAction] Section
How to Use Batch Actions
Command-line parameters


"Run" Action

Description

With this type of action, you can run a program. You can specify which program is to be executed, along with the working directory, parameters etc.

Parameters

The following is a list of the supported parameters:
FileNameREQVAR

Value

String

Description

Specifies the name of the file to be executed. The file has to be an executable; if you want to open a document, use the shellexecute action instead.

Example

FileName: "%Windows%\Notepad.exe"
ParametersVAR

Value

String

Description

If you want to pass command-line parameters to the program, you can put them here.

Example

Parameters: "%AeTrayMenuPath%\AeTrayMenu.ini"
WorkingDirVAR

Value

String

Description

With this parameter, you can control the directory in which the program is executed. Some programs look for files in the 'current' directory, so in that case this setting will be useful.

Example

WorkingDir: "%Windows%"
ShowCmd

Value

normal|hidden|maximized|minimized

Description

Most programs open a window on the screen when executed; with this setting, you can control how (and if) that window will be shown.

Example

ShowCmd: maximized
Flags

Value

Flag list

Description

This parameter is a set of extra options. Multiple options may be used by separating them by spaces. The following options are supported:
ignoreerrors
Normally, AeTrayMenu pops up a message box when the action cannot be performed for some reason (e.g. when it can't find the program). Specify this flag to suppress these error messages.
waituntilterminated
If you're executing multiple actions sequentially (in a batch action section), you can use this flag to suspend execution of the next action until the program has been terminated.
waituntilidle
This flag works like the waituntilterminated flag, but instead waits until the program is waiting for user input with no input pending.

Example

Flags: ignoreerrors waituntilterminated

Example

Action: run; FileName: "%Windows%\Notepad.exe"; Parameters: "%AeTrayMenuPath%\AeTrayMenu.ini"; ShowCmd: maximized; Flags: waituntilterminated

See also See Also
List of Available Actions
"ShellExecute" Action


"ShellExecute" Action

Description

This action can launch a document with its associated program (or a program), much like the run action. You can e.g. use it to run batch files or print text documents.

Parameters

The following is a list of the supported parameters:
FileNameREQVAR

Value

String

Description

Specifies the name of the file/document to be launched. If you want to run a program, you can use the run action instead.

Example

FileName: "%MyAppPath%\License.doc"
ParametersVAR

Value

String

Description

If you want to pass command-line parameters to the program that is used to launch the file, you can put them here.

Example

Parameters: "/someparameter"
WorkingDirVAR

Value

String

Description

With this parameter, you can control the directory in which the program is executed that's used to launch the file. Some programs look for files in the 'current' directory, so in that case this setting will be useful.

Example

WorkingDir: "%MyAppPath%"
ShowCmd

Value

normal|hidden|maximized|minimized

Description

Most programs open a window on the screen when executed; with this setting, you can control how (and if) that window will be shown.

Example

ShowCmd: normal
Verb

Value

String

Description

The verb controls the action that is performed. If no verb is specified, the default one will be used by Windows. You can find out which verbs are supported for a file type in the Windows registry (look up information on Windows' file type associations if you don't know what I'm talking about).

Example

Verb: "Print"
Flags

Value

Flag list

Description

This parameter is a set of extra options. Multiple options may be used by separating them by spaces. The following options are supported:
ignoreerrors
Normally, AeTrayMenu pops up a message box when the action cannot be performed for some reason (e.g. when it can't find the program). Specify this flag to suppress these error messages.
waituntilterminated
If you're executing multiple actions sequentially (in a batch action section), you can use this flag to suspend execution of the next action until the program has been terminated.
waituntilidle
This flag works like the waituntilterminated flag, but instead waits until the program is waiting for user input with no input pending.

Example

Flags: ignoreerrors waituntilterminated

Examples

Action: shellexecute; FileName: "%MyAppPath%\License.doc"; Verb: "Print" Action: shellexecute; FileName: "%AeTrayMenuPath%\AeTrayMenu.ini"; WorkingDir: "%Windows%"; Flags: waituntilidle

See also See Also
List of Available Actions
"Run" Action


"Service" Action

Description

Windows services can be manipulated through the service action.

Parameters

The following is a list of the supported parameters:
ServiceREQ

Value

String

Description

The name of the service you want to control. Note that you also have to list all the services you refer to in the [Services] section.

Example

Service: mysql
ServiceActionREQ

Value

startresume|pause|stop|restart

Description

To resume a service after it has been paused, use startresume (not a second pause).

Example

ServiceAction: startresume
Flags

Value

Flag list

Description

This parameter is a set of extra options. Multiple options may be used by separating them by spaces. The following options are supported:
ignoreerrors
AeTrayMenu automatically disables a menu item when the specified action can't be performed on a service. However, when you're using batch action sections, this won't work. In that case, it's often handy to use the ignoreerrors flag to prevent the batch from getting stuck when a service is not available.
waituntilterminated
If you're executing multiple actions sequentially (in a batch action section), you can use this flag to suspend execution of the next action until the service has been started, paused, etc.

Example

Flags: ignoreerrors waituntilterminated

Example

Action: service; Service: mysql; ServiceAction: restart

See also See Also
List of Available Actions
How to Use the Service Features
[Services] Section


"Multi" Action

Description

A powerful feature of AeTrayMenu is that you can let it perform multiple actions for one menu item, so that you don't have to write a separate batch file or so. You can enumerate the actions in a section to which you link using a multi action.

Parameters

The following is a list of the supported parameters:
ActionsREQ

Value

String

Description

The name of the section that contains the list of actions that should be performed.

Example

Actions: BatchSection

Example

[Menu.Left] Type: item; Caption: "Start All Services"; Action: multi; Actions: StartAll [StartAll] Action: service; Service: apache2; ServiceAction: startresume; Flags: ignoreerrors Action: service; Service: mysql; ServiceAction: startresume; Flags: ignoreerrors

See also See Also
List of Available Actions
How to Use Batch Actions
Batch Actions Sections


Using the Service Features
AeTrayMenu was originally developed as a service monitor. Therefore, the program has some special features for this purpose. This topic describes the steps you should follow in order to use these features.

Listing Services

Before you can use the service control/monitoring features, you have to tell AeTrayMenu which services you want to control. You have to do this in the [Services] section.

Service Control

You can define menu items that start/resume, stop, pause and restart services. For this, the service action has been provided. Those menu items will be automagically enabled/disabled when necessary.

Status Indication

AeTrayMenu's tray icon can be changed to reflect the running state of the services you have specified. At intervals set by the ServiceCheckInterval setting in the [Config] section, AeTrayMenu will update its tray icon and the tray icon's hint text.

If you want to control multiple services, it can be handy to put the start, stop etc. menu items for a service in a submenu. For these cases, there's a special kind of submenu available; the servicesubmenu automatically adapts its glyph to the running state of the service it has been linked to.

Other features

There are some other features available that may come in useful when working with services:
  • You can open the Windows NT "Services" console using the controlpanelservices action.
  • When you want to install/uninstall services while AeTrayMenu is running, this may lead to trouble because of AeTrayMenu having handles open to them. You can either use the -quit command-line parameter to shutdown a running AeTrayMenu instance, or use the closeservices action to let AeTrayMenu close its handles.

See also See Also
[Services] Section
"Service" Action
[Config]: ServiceCheckInterval
[Config]: TrayIcon*Running
[Messages]: *RunningHint
List of Available Actions
[Menu.*] Section
Command-line Parameters


How to Use Batch Actions
Sometimes, you'd like to make AeTrayMenu perform multiple actions when a menu item is clicked. Normally, you would write a batch (.bat) file and then run that batch file. However, AeTrayMenu gives you a way to include those batches in the configration file, in order to keep your configuration centralized: multi actions.

How "Multi" Actions Work

First, you assign the multi action to a menu item, like this: [Menu.Left] Type: item; Caption: "Run Multiple Commands"; Action: multi; Actions: MultiActions This tells AeTrayMenu to look in a section called [MultiActions] for the actions that have to be performed when the user chooses the menu item.

In such a batch actions section, you list the actions. It is like listing a menu, but without the Type, Caption and Glyph parameters. For example: [MultiActions] Action: run; FileName: "%Windows%\Notepad.exe" Action: run; FileName: "%Windows%\Calc.exe" This example opens both Notepad and Calculator.

Preventing Simultaneous Execution

It is possible to suspend execution of the next action until the current item has completed. In the example above, AeTrayMenu tells Windows to run Notepad, and right after that issues the command to run Calculator. What if you want to run Notepad, and after Notepad has closed run Calculator?

For those situations, the actions run, shellexecute and service have the waituntilterminated flag. You could for example enter: [MultiActions] Action: run; FileName: "%Windows%\Notepad.exe"; Flags: waituntilterminated Action: run; FileName: "%Windows%\Calc.exe" in the configuration file, so that Calculator will be run after Notepad has closed.

Another flag, waituntilinputidle, is supported only by run and shellexecute. It suspends execution of the batch actions until the program/document that is executed is ready for user input.

Ignoring errors

If one of the actions in the batch causes an error, the execution of the batch will stop. You can prevent this by using the ignoreerrors flag. An example: [MultiActions] Action: service; Service: apache2; ServiceAction: startresume; Flags: ignoreerrors Action: service; Service: mysql; ServiceAction: startresume; Flags: ignoreerrors A good example of where this may be useful is a service controller. Suppose you can't be sure that all services exist, but you want to be able to start all existing services. You'd have to somehow dynamically adapt the above section depending on which services exist and which don't. However, by using the ignoreerrors flag, you can just attempt starting them all, without bothering about error messages.

Service Handles

There's one tricky thing about working with AeTrayMenu: you have to be careful when running programs that modify service configurations while the traymenu is running. AeTrayMenu keeps handles open to all services it is told to control, so that e.g. uninstaling the services will "mark it for removal upon reboot" instead of removing it immediately. When doing this from external applications, you can use the -quit command-line parameter, but what to do when attempting to uninstall a service from within the traymenu itself?

For this purpose, two special actions are available: closeservices and resetservices. closeservices will let the traymenu close its handles, while resetservices will re-open them (if possible). An example of their usage: [MultiActions] Action: closeservices Action: run; FileName: "%Apache%\bin\Apache.exe"; Parameters: "-k uninstall" Action: resetservices Always be sure to call resetservices as well, otherwise the user won't be able to control any of the services!

seealso (1K) See Also
Batch Actions Sections
"Multi" Action
List of Available Actions


Command-line Parameters
There are cases in which it is not enough to be able to control AeTrayMenu through its configuration file; at those times it is useful to be able to control it through the command-line.

The syntax of the AeTrayMenu command-line is as follows:

AeTrayMenu.exe [-quit -id=id] [-myvar1=value1 [-myvar2=value2 [...]] [-scriptfile=filename]
in which:
  • AeTrayMenu.exe is the name of the AeTrayMenu executable. It is possible to rename the program (see also Some Remarks).
  • -quit can be used to close a running instance of AeTrayMenu. You also need to specify the instance's ID using the -id= switch.
  • you can specify the value of a commandline type variable using the switch -varname=value. The varname part should be replaced with the switch name specified in the ParamName parameter of your variable's declaration. value should be replaced with the variable's value, but please note that you have to put the whole thing in quotes (see the example below) if the value contains spaces!
  • -scriptfile= can be used to tell AeTrayMenu which file contains the script. Please note that you have to enclose the whole thing with quotes if the specified filename contains spaces (see the example below)!

Examples

AeTrayMenu.exe -quit -id={42F9F6BD-49C0-42E6-8250-25C98ACE1DAB} AeTrayMenu.exe -scriptfile=MyScript.cfg "-myvar=some variable containing spaces" MyTray.exe "-scriptfile=C:\Program Files\MyTray\Config.ini"

seealso (1K) See Also
Some Remarks
[Config]: ID
[Variables] Section


Redistributing AeTrayMenu
The main purpose of AeTrayMenu is that it may be redistributed for use in other software packages. You are completely free to use it both in commercial and non-commercial packages (see the License Agreement). There are a couple of technical and non-technical issues you may consider when redistributing AeTrayMenu:

Files You Need

Since all thirdparty libraries AeTrayMenu uses are linked to the executable, you'll only need to include the following files:
  • The AeTrayMenu executable - If you want, you can rename the executable to suit your wishes and needs.
  • The configuration file - In most cases, it's the most convenient to name this file <name of the AeTrayMenu executable>.ini.
  • An imagelist bitmap - You must specify the filename of this bitmap in the ImageList directive. You could name this file <name of the AeTrayMenu executable>.dat.
  • If you have specified one or more sidebar images in the [Menu.*.Settings] sections, you'll have to include those bitmaps as well.

Installing the Traymenu

The program doesn't need a special installation, but you might consider the following:
  • Be sure to close the traymenu using the -quit command-line parameter if there's a chance that your installer will attempt to overwrite the traymenu's executable while it's running.
  • If you want the traymenu to run at Windows startup, you can place a shortcut in the Startup folder in the Start menu. You can also use the HKEY_LOCALMACHINE\Software\Microsoft\Windows\CurrentVersion\Run registry key (or the same key under HKEY_CURRENT_USER).

The About Box

As you've probably seen, you can easily leave AeTrayMenu's About box out of the traymenu. You're allowed to do so, but I would appreciate it if you'd put a menu item with the about action somewhere.

seealso (1K) See Also
License Agreement
[Config]: ImageList
Command-line parameters


About
AeTrayMenu has been written by Onno Broekmans using Borland Delphi 6.

Thirdparty Code

AeTrayMenu makes extensive use of thirdparty libraries and code written by others. Please refer to the About box for more information.

madExcept

Some releases of AeTrayMenu are compiled with madExcept, a package for handling 'unhandled exceptions'. These releases are for non-commercial use only! madExcept is part of madCollection; madCollection is Copyright (c) Mathias Rauen.


License Agreement
Made by Onno Broekmans; visit http://onnodb.com/aetraymenu for more information.

THE SOFTWARE PRODUCT IS PROVIDED "AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED. THE USER MUST ASSUME THE ENTIRE RISK OF USING THIS PROGRAM. To the maximum extent permitted by applicable law, in no event shall the author or its suppliers be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the SOFTWARE PRODUCT, even if the author has been advised of the possibility of such damages.

This work is hereby released into the Public Domain. To view a copy of the public domain dedication, visit:

http://creativecommons.org/licenses/publicdomain/
or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Part of the AeTrayMenu source code has been based on the Inno Setup source code by Jordan Russell (portions by Martijn Laan).


Contact Information
You can contact me at the following e-mail address:
obroekma@angelfire.com
All feature suggestions and other ideas are welcome.

You can also visit the AeTrayMenu website at:

http://onnodb.com/aetraymenu

Bug Reports

If you encounter a bug in AeTrayMenu, please make sure that you include the following information in your e-mail:
  • Any error messages that pop up (you can copy the text in a message box to the clipboard by pressing Ctrl+C). If you've got the version that's compiled with madExcept, please include the bug report.
  • What one has to do to trigger the bug. This is very important: if you can give me an exact description of the circumstances that cause the bug, I can solve it much faster (providing e.g. a minimal configuration file that triggers it would be ideal).
  • Information about your system may come in useful, as well (madExcept includes this information by default).
Thanks!