Custom Meters Command Summary

See Custom Meter Macros for an overview and simple example. See Phase Meter, THD Meter, and IMD Meter under Macro Examples and Mini-Apps for detailed examples.

• Introduction
• Meter Title
• Meter Text Color
• Meter Background Color
• Meter Absolute Position
• Meter Absolute Size
• Meter Relative Position
• Meter Font Size
• Meter Font Family
• Centering Meter Text
• Close Meter
• Meter Exit Code
• Count of Meters Open
• Copying Meter Text
• Meter Help

Introduction:

A Custom Meter (Mtr0 to Mtr3), is like a Message Macro; it can display any string expression, composed of quoted text and string or numerical variables, including formatting commands but no math operations:

    Mtr0="Volts: " + V +n + "Amps: " + A

To allow a variable meter number instead of an explicit digit 0-3, use MtrV after first setting the desired meter number with channel select variable Ch. This is useful in creating subroutine macros that can update any meter. For example, the _MeterUpdate subroutine macro might include a line like:

    MtrV="Volts: " + V +n + "Amps: " + A

Then after setting V and A appropriately, the caller could update any meter. To update Mtr2 it would do:

    Ch=2
    @_MeterUpdate

This becomes very useful when the update script is extensive.

Before invoking a Custom Meter, a setup macro typically sets the title of the meter, and possibly its colors, initial position, font size, and family.

The general format of these setup commands is a quoted string whose first character is a caret (<), and whose second character specifies the type of command.

A quoted string without the caret is interpreted as text to be displayed on the meter.

Meter Title:

    Mtr0="<<Meter 0 Title"

The << carets after the quote are mandatory, but they are not displayed.

Alternatively, you can use a string expression as long as it starts with quoted double carets. For example:

    Mtr0="<<" + Ch(c) + " Pulse Width"

In this example, if the current Ch Channel Select value is 0, the title will be "Left In Pulse Width".

Meter Text Color:

    Mtr0="<C(red,grn,blu)"

Meter Background Color:

    Mtr0="<B(red,grn,blu)"

For Text or Background color entry, red, grn, and blu may be constants, variables, or expressions that will be evaluated to determine each color component (0-255).

Alternatively, you can use a single constant, variable, or expression to set the color, as in Mtr0="<C(UX<<8)" or Mtr0="<B(hFF0088)". Only the low 24 bits of the value are used. The low 8 are Red, the middle 8 are Green, and the next 8 are Blue... so for a hexadecimal value the colors are in BBGGRR order, the opposite of the above (R,G,B) order.

Note that if you already have values in RRGGBB order, you can use lower-case Mtr0="<c(UX)" or Mtr0="<b(UX)" to accept them as-is.

You can obtain the color value of any main Daqarta trace via the ColorNum macro, as in Mtr0="<C(ColorNum?L)" to use the Left Input color. To get the color value that corresponds to the current Channel Select Ch setting, use ColorNum?c.

Meter Absolute Position:

    Mtr0="<P(x,y)"

Coordinates x and y are in pixels, relative to the upper left corner of the screen. They may be constants, variables, or expressions.

Meter Absolute Size:

    Mtr0="<S(width,height)"

Width and height coordinates are in pixels. Note that this command only sets the initial dimensions; you can still drag a border or corner to manually resize once the meter is open.

Note, however, that manually resizing this way will automatically change the displayed text size to fit, even if you have initially given this Absolute Size Command.

On the other hand, if you don't manually resize, the text size will be adjusted to accomodate the given meter height, even if you have given a Meter Font Size command (below).

If you also give a position command, either Meter Absolute Size (above) or Meter Relative Position (below), the position command must come before the size command.

Meter Relative Position:

    Mtr0="<D(x,y)"

Coordinates x and y are in dialog units, relative to the upper left corner of the Averager button in the Daqarta toolbar.

To aid in determining the x and y values during development, you can use Mouse Position Macros to read the position of the mouse at any screen or dialog location.

Alternatively, you can invoke the meter and drag it to wherever you like, and then read its position in pixels or dialog units:

A=Mtr0?X sets variable A to the absolute X position of Mtr0, where A can be any numeric variable.

B=Mtr0?Y sets variable B to the absolute Y position of Mtr0.

A=Mtr0?x (note lower case) sets variable A to the X-position of Mtr0 in dialog units.

B=Mtr0?y (note lower case) sets variable B to the Y-position of Mtr0 in dialog units.

Meter Font Size:

    Mtr0="<F(n)"

n is the font height in pixels, which may be a constant, variable, or expression. The meter size will automatically adjust to accomodate the font height.

However, a Meter Absolute Size command will take priority, ignoring the Font command, and cause the font height to adjust to the meter height.

You can invoke the meter and adjust its size by dragging a lower edge or corner. This will automatically adjust the font height to the meter height, regardless of any Font or Absolute Size command.

You can read the current height with H=Mtr0?F, which sets variable H to the height.

Meter Font Family:

    Mtr0="<f(n)"

n is the font family number, which may be a constant, variable, or expression that evaluates to 0-3:

    0 = Don't Care (default Arial)
    1 = Times New Roman (proportional, with serifs)
    2 = Arial (proportional, no serifs)
    3 = Lucida Console (monospace, no serifs)

Since the Arial default is a proportional font, you may want to use the monospaced Lucida Console (Mtr0="<f(3)") to show multiple columns that stay aligned. You can use the String Expression 'p' (pad) command to set the start of each column, as used in the Missing Fundamental macro:

    Mtr0="N" +p6 + "Hz" +p16 + "Deg"
    ...
    Mtr0=Mtr0 + n + UH + p4 + X + p15 + P
    ...

See the Column Display Tips subtopic under String Variables and Expressions for more info.

Centering Meter Text:

Text is left-aligned by default, with a left margin of about one character space. This is needed for use with multiple columns of data, along with the Lucida Console font family as noted above. This left alignment is usually fine for most other purposes as well.

However, if you have a single column of data you might want to center all the values. Mtr0="<sC" sets the Mtr0 text alignment to Centered. Mtr0="<sL" restores alignment to Left. (Right alignment is not supported, and in fact any letter other than 'C' will also set Left alignment.)

Close Meter:

    Mtr0=

When the command is empty (nothing following the '=' sign) the meter is closed. You can use this command from a Custom Controls button that allows the user to toggle a meter display off and on.

Note that if a meter is toggled off via the [x] icon in its title bar, it will by default stay off until the macro is closed or cancelled and restarted. If you want to re-enable it while the macro is running (say from the above-mentioned meter display button), you must give a Meter Help command like Mtr0="<H4900". (See Meter Help, below.)

That particular Help number sets the THD Meter topic, one of the macro mini-apps included with Daqarta. Unless you are modifying an existing mini-app you won't have a relevant Help number, so just use Mtr0="<H4AFF" to (redundantly) set it to the default Custom Meters topic.

Meter Exit Code:

    C=Mtr0?E

This sets variable C to 1 if the meter was closed by clicking on the [x] at the the upper right of its title bar, otherwise C is set to 0. This allows a meter update task macro to test for manual meter closure, and uninstall itself if so.

Count of Meters Open

    C=Mtr0?O

This sets variable C to the count of meters currently open. It can be used instead of the above exit code when a task macro updates a selectable number of meters; the user may close unwanted meters, but when the last one is closed (C=0) the task can uninstall itself. Note that the same result is returned regardless of which meter (0-3 or V) is used in the command, and regardless of whether that meter is open or closed at the time.

Copying Meter Text:

To copy the meter text to the Windows Clipboard, left-click anywhere in the central region of the meter display. This captures a copy of the current text or value and pops up a message box allowing you to save it to the Clipboard. CTRL+left-click saves it directly, without the message prompt. SHIFT+left-click includes the meter title above the meter text. CTRL+SHIFT+left-click includes the title and omits the prompt.

Meter Help:

In the Macro Examples and Mini-Apps included with Daqarta you may notice a statement like Mtr0="<H4904" before a meter display command. (See, for example, the Lissajous macro listing.) This allows a right-click anywhere in the meter box to open the specific Help page for that example. (Otherwise, it opens the Custom Meters topic.)

Since there is no way for users to write and integrate their own Help pages, this would normally not be useful in your own macros. However, this same command also re-enables meter display after it has been cancelled by clicking the [x] in the meter's title bar. Unless you are modifying an existing mini-app, you should use Mtr0="<H4AFF" to specify the default Custom Meters topic. (See the Close Meter subtopic above.)

Note that although you can't integrate your own Help topics, you can use Msg messages (or even Mtr0 to Mtr3 Custom Meters) to display your custom help.

See also Custom Meter Macros, Macro Overview