From AlphaWiki

Commands: The [floatMenu] command

This file documents the [floatMenu] command as of version 8.2b15 of AlphaX.

• Introduction
• Synopsis
  • The [create] subcommand
  • The [delete] subcommand
  • The [find] subcommand
  • The [hide] subcommand
  • The [list] subcommand
  • The [move] subcommand
  • The [refresh] subcommand
  • The [set] subcommand
  • The [show] subcommand
  • The [top] subcommand
• Floating menu options
• Hooks
• Examples

Introduction

The [floatMenu] command lets you create and manipulate floating menus in Alpha. It was introduced in version 8.1 of AlphaX

It is a replacement for the old (and now deprecated) [closeFloat], [float], [floatShowHide], and [unfloat] commands.

Floating menus are like floating palettes which reproduce the contents of any menu in Alpha: for any item in the menu, there is a corresponding button in the floating palette, and clicking on the button is equivalent to selecting the item in the menu. In the rest of this page, the expressions palette or floating menu are synonymous.

Synopsis

The formal syntax of the [floatMenu] command is:

floatMenu subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be additionnally specified.

The [create] subcommand

This subcommand creates a floating menu from an existing menu. It accepts a wide variety of options. The complete syntax is:

 
     floatMenu create -menu menuToken [(-height|-width|-left|-top|-interspace) val] \
          [-name winname] [-justify (left|center|right)] [-sidebar (0|1)] \
 		 [-dynamic (0|1)]

The [floatMenu create] command returns a token used in the other subcommands to uniquely identify the floating menu. This token must not be confused with the token of the menu with which the floating palette is associated.

The possible options are described in the Floating menu options section below. By default, a floating window is made visible when it is created unless the -visible option was specified with value 0.

The [delete] subcommand

This subcommand lets you delete a floating menu. This is equivalent to closing the floating window with a mouse click in the Close box. The syntax is:

 
     floatMenu delete token

The [find] subcommand

This subcommand lets you find the floating menu associated with a given menu. The syntax is:

 
     floatMenu find menuToken

If there is a floating palette associated with the menu specified in the menuToken argument, the command returns the palette's token. Otherwise it raises an error. This command can be useful to test the existence of a floating window.

The [hide] subcommand

This subcommand lets you hide a floating menu. The syntax is:

 
 	floatMenu hide token

This subcommand is a convenience: it is equivalent to [menu set] invoked with -visible 0 argument.

The [list] subcommand

This subcommand returns a list of the tokens corresponding to the currently existing floating menus. Each time a new floating menu is created, its token is appended at the end of the list, so this list is ordered from the oldest to the newest float. The syntax is:

 
     floatMenu list

The [move] subcommand

This subcommand lets you reposition a floating menu on the screen. The syntax is:

 
     floatMenu move token left top

where left and top designate the position of the upper left corner of the float in screen coordinates. This subcommand is a convenience: it is equivalent to the [menu set] command invoked with -left and -top arguments.

The [refresh] subcommand

This subcommand lets you refresh the buttons of an already built floating menu. The syntax is:

 
     floatMenu refresh [-remake] token

If the -remake option is specified, the floating menu buttons will be entirely rebuilt. Otherwise, only the contents of the existing buttons will be refreshed in order to reflect the current properties of the coresponding menu item (name, icon, etc.).

The [set] subcommand

This subcommand lets you get or set several properties attached to a menu item. The syntax can take two forms:

 
     floatMenu set token option
     floatMenu set token option value ?option value...?

In the first form the command returns the current value of the specified option. In the second form, it lets you set the value of one or several options.

The possible options are described in the Floating menu options section below.

Note that it is not possible to reset the menu attached to a floating palette, i-e the -menu option is not accepted in the second form of this subcommand.

The [show] subcommand

This subcommand is the opposite of the [hide] subcommand. It lets you display an existing floating menu if it is hidden.

 
     floatMenu show token

This subcommand is a convenience: it is equivalent to [menu set] invoked with -visible 1 argument.

The [top] subcommand

This subcommand deals with the topmost floating menu. It can take two forms:

 
     floatMenu top
     floatMenu top token

The first form returns the token corresponding to the topmost float. The second form brings the float corresponding to the token argument on top of the others.

Floating menu options

The [floatMenu create] and [floatMenu set] commands accept many options to set the attributes and parameters of the floating menus. All these properties are specified by an option starting with a dash.

Here is the description of the various options:

• the -dynamic option lets you specify whether the floating menu should be updated automatically whenever the corresponding menu is modified. The possible values are 0 and 1 (which is the default). If this option is set to 0, you can still update the float menu programmatically using the [floatMenu refresh] command.
• the -height option lets you specify the height of the items in the float. If it is not specified or if it is equal to -1, the height for eacg item is automatically set to the best value based on the text and font used to draw the item. The default value is -1.
• the -interspace option lets you specify an extra horizontal margin which will be inserted to separate the items from each other. The default value is 0.
• the -justify option lets you specify the alignment of the menu items in the floating window: the possible values are left, center or right. The default value is left.
• the -left and -top options let you specify the position (left and top) of the upper-left corner of the float in screen coordinates. The default values for these options is 0.
• the -menu option lets you specify the token of the menu which will be turned into a floating palette. Its value is a token corresponding to a valid already existing menu: typically this menu token will have been obtained with the [menuRef create] command (see the MenuRefCommand page). With the [floatMenu create] command, this argument is required.
• the -name option lets you specify a name for the floating window. It is written in the title bar of the window. If this option is not specified when the floating menu is created, the name of the menu is used as a default. In order to have no title in the title bar, specify an empty string.
• the -sidebar option lets you specify a vertical orientation for the titlebar. The possible values are 0 (which is the default and corresponds to a horizontal title bar) and 1 (which corresponds to a vertical sidebar along the left side).
• the -visible option lets you get or set the visibility of the floating menu. By default, a floating menu is made visible when it is created: this can be changed with the -visible option set to 0 in the [floatMenu create] command.
• the -width option lets you specify the width of the float. If it is not specified or if it is equal to -1, the width of the float is adjusted to the widest item in the menu. The default value is -1.

Hooks

There are two hooks named floatHook and unfloatHook which are called respectively when the [floatMenu create] and [floatMenu delete] commands are invoked.

The floatHook proc is invoked when the floating window has been created in memory but before it is attributed its token: so, at this point, the new float would not be listed by the [floatMenu list] command.

The unfloatHook proc is invoked when the floating window has been disposed of. At this point, the floating menu token is not valid anymore.

Examples

Here are a few basic examples which can be executed from the Tcl shell in AlphaX:

 
     Welcome to AlphaX's AlphaTcl shell.
     «» set token1 $menu::core(Compare)
     «» set fm1 [floatMenu create -menu $token1 -name "Compare" -left 30 -top 50]
     floatmenu1
     «» floatMenu show $fm1
     «» floatMenu hide $fm1
     «» floatMenu list
     floatmenu1
     «» set token2 $menu::core(FileUtilities)
     «» set fm2 [floatMenu create -menu $token2 -height 25 -width 130 -name ""]
     floatmenu2
     «» floatMenu list
     floatmenu1 floatmenu2
     «» floatMenu delete $fm1
     «» floatMenu list
     floatmenu2