Description | Syntax | Arguments | Keywords | Examples

Description

---

Use this procedure to add menu items (buttons) to the ENVI Classic menu system from a user-defined procedure in a .pro or .sav file within the save_add directory. The .pro or .sav file must contain a procedure named filename_define_buttons, where filename is the name of that file. For instance, if the file in the save_add directory is named my_process.pro, a procedure named my_process_define_buttons.pro should be in that file to allow you to add buttons to the ENVI Classic menu system. The filename_define_buttons procedure has only one argument and no keywords, as shown in the following example code:

PRO my_process_define_buttons, buttonInfo
;
; Define Buttons with ENVI_DEFINE_MENU_BUTTON
;
END

The filename_define_buttons procedure is used to call the ENVI_DEFINE_MENU_BUTTON procedure, which enables you to define a new button. The ENVI_DEFINE_MENU_BUTTON procedure has one argument and several keywords that include information on where the new button is located in the ENVI Classic menu system. The following figure and comments show an example of button location terminology in the ENVI Classic menu system.

The Basic Tools menu is a button containing a submenu. It is also the parent button of Resize Data (Spatial/Spectral), Subset Data via ROIs, etc. Resize Data (Spatial/Spectral) is a child button of Basic Tools. Statistics is a sibling button to Resize Data (Spatial/Spectral), Subset Data via ROIs, etc. Statistics is also a parent button because it contains a submenu.

Syntax

---

ENVI_DEFINE_MENU_BUTTON, ButtonInfo [, /DISPLAY], EVENT_PRO=string, /MENU, [, POSITION=long integer or string] [, REF_INDEX=long integer] [, REF_UVALUE=variable], REF_VALUE=string [, SEPARATOR={0 | 1 | -1}] [, /SIBLING], UVALUE=string, VALUE=string

Arguments

---

ButtonInfo

This is a structure containing information about the new button. This argument must be the same as the argument used for the filename_define_buttons procedure.

Note: The value of the argument is defined by ENVI Classic and should not be modified.

Keywords

---

DISPLAY (optional)

Set this keyword to add the new button to the display group menu bar, instead of to the ENVI Classic main menu bar (default). Any child buttons that you add to a display group menu button also require /DISPLAY keywords.

EVENT_PRO (optional)

Use this keyword to specify a string containing the name of the event handling procedure for the new button, which is called when yo (optional)u select the new button. If you set the MENU keyword, the EVENT_PRO keyword is not required.

MENU

Set this keyword to indicate the new button has a submenu, making it a parent button. You are not required to specify a value for the UVALUE keyword if you set the MENU keyword. By default, the MENU keyword is not set.

POSITION (optional)

Use this keyword to specify the location of the new button relative to the reference button, which is specified with the REF_VALUE keyword.

Note: You cannot add a new button after Exit in the File option of the ENVI Classic main menu bar.

If the new button is a sibling (/SIBLING) to the reference button, then you can set the position to one of the following values:

• 'before': String value indicating the new button is placed just before the reference button
• 'after': String value indicating the new button is placed just after the reference button
• negative number: Long integer indicating the new button is placed a relative distance before the reference button. A value of 0 is not valid in this case. For example, a value of –1 is equivalent to a value of 'before'. A value of –2 places the new button before the reference button, with one sibling between the new and the reference button.
• positive number: Long integer indicating the new button is placed a relative distance after the reference button. A value of 0 is not valid in this case. A value of 1 is equivalent to a value of 'after'. A value of 2 places the new button after the reference button, with one sibling between the new and the reference button.

If the new button is a child of the reference button (SIBLING=0, default), then you can set the POSITION keyword to one of the following values:

• 'first': String value indicating the new button is placed as the first child
• 'last': String value indicating the new button is placed as the last child
• -1, 0, or a positive number: Long integer indicating the index of the child button relative to it parent. For example, POSITION=0 represents the first child, POSITION=1 represents the second child, and so forth. POSITION= –1 is equivalent to 'last', which places the new button as the last child (no matter how many children already exist).

The default value is POSITION='after' for a sibling button and POSITION='last' for a child button.

REF_INDEX (optional)

Use this keyword to indicate the index of the button used as a reference if the name specified for the REF_VALUE keyword is not unique. For example, the Preprocessing button appears in two places in the ENVI Classic menu system: in the Basic Tools and the Spectral menus. The index value is based on the sequential order of the button names in the envi.men file. REF_INDEX=0 represents the first instance in the file, REF_INDEX=1 represents the second instance, and so forth. If the value of REF_INDEX is greater than the number of instances in the file, the first instance of the button is used as the reference button. The default is REF_INDEX=0.

REF_UVALUE (optional)

Use this keyword to specify a reference button by its user-defined value.

Specifying an existing ENVI Classic button name with the REF_VALUE keyword may not always produce a match because you can edit the envi.men file and it may have been changed for a given installation (for example, when translating the button names into a different language). However, a user-defined value for this button does not change. The REF_UVALUE keyword enables you to specify this user-defined value so it can be used as a backup for the REF_VALUE when it does not match any existing buttons. However, the REF_UVALUE keyword does not work for parent buttons because submenus do not produce events.

REF_VALUE (optional)

Use this keyword to specify a string containing the name of the reference button, which is already located in the ENVI Classic menu system.

SEPARATOR (optional)

Set this keyword to place a separator before the new button. By default, SEPARATOR=0. To place the separator after the new button, set SEPARATOR to -1.

SIBLING (optional)

Set this keyword to indicate that the new button is a sibling of the reference button, which is specified with the REF_VALUE keyword. By default, a new button is a child of the reference button unless the SIBLING keyword is set. However, if the reference button is not a parent button (i.e., it does not contain a submenu), you do not need to set this keyword because the new button is always a sibling to that reference button.

UVALUE

Use this keyword to specify a string containing information you want to maintain about the new button. This string is passed to the event handling procedure for the new button. If the MENU keyword is set, you are not required to specify a value for the UVALUE keyword.

Note: In general, the user-defined value of a widget can be of any type, but for this procedure, the value for the UVALUE keyword must be a string.

VALUE

Use this keyword to specify a string containing the name of the new button you want to create. The name specified for the VALUE keyword is also used as the label for the new button.

Examples

---

1. Copy and paste each code example into the IDL Editor and save the file as my_process.pro.
2. Save the file in the save_add directory of the ENVI Classic installation path.
3. Start IDL.
4. At the IDL command line, type envi to start ENVI Classic. The respective menu entries will appear in the menu bar.

Example 1

The first example adds four new buttons. The My Menu parent button is placed in the ENVI main menu bar just after Basic Tools and just before Classification. This new button contains three children: Option 1, Option 2, and Option 3.

PRO MY_PROCESS_DEFINE_BUTTONS, buttonInfo

  compile_opt IDL2

  envi_define_menu_button, buttonInfo, $

     value = 'My Menu',   /menu, $

     ref_value = 'Basic Tools', $

     /sibling, position = 'after'

  envi_define_menu_button, buttonInfo, $

     value = 'Option 1', uvalue = 'option 1', $

     event_pro = 'my_process', $

     ref_value = 'My Menu', position = 'last'

  envi_define_menu_button, buttonInfo, $

     value = 'Option 2', uvalue = 'option 2', $

     event_pro = 'my_process', $ 

     ref_value = 'My Menu', position = 'last'

  envi_define_menu_button, buttonInfo, $

     value = 'Option 3',    uvalue = 'option 3', $

     event_pro = 'my_process', $   

     ref_value = 'My Menu', position = 'last', $

     /separator

END

PRO MY_PROCESS, event

  compile_opt IDL2

  print, 'Running the process'

END

Example 2

The previous example used string values for the POSITION keyword. This example creates the same buttons, but it uses integer values for the POSITION keyword.

PRO MY_PROCESS_DEFINE_BUTTONS, buttonInfo

  compile_opt IDL2

  envi_define_menu_button, buttonInfo, $

     value = 'My Menu',   /menu, $

     ref_value = 'File', $

     /sibling, position = 2

  envi_define_menu_button, buttonInfo, $

     value = 'Option 2', uvalue = 'option 2', $

     event_pro = 'my_process', $

     ref_value = 'My Menu', position = 0

  envi_define_menu_button, buttonInfo, $

     value = 'Option 1', uvalue = 'option 1', $

     event_pro = 'my_process', $ 

     ref_value = 'Option 2', $

     ref_uvalue = 'Option 1', $

     position = -1

  envi_define_menu_button, buttonInfo, $

     value = 'Option 3',    uvalue = 'option 3', $

     event_pro = 'my_process', $   

     ref_value = 'Option 2', $

     ref_uvalue = 'Option 1', $

     position = 1, /separator

END

PRO MY_PROCESS, event

  compile_opt IDL2

  print, 'Running the process'

END

Example 3

The following example shows how to add new buttons as children to the Preprocessing button under Basic Tools.

PRO MY_PROCESS_DEFINE_BUTTONS, buttonInfo

  compile_opt IDL2

  envi_define_menu_button, buttonInfo, $

     value = 'New Tools', /menu, $

     ref_value = 'Preprocessing', $

     ref_index = 0, position = 'last'

  envi_define_menu_button, buttonInfo, $

     value = 'Tool 1', uvalue = 'tool 1', $

     event_pro = 'my_process', $

     ref_value = 'New Tools', position = -1

  envi_define_menu_button, buttonInfo, $

     value = 'Tool 2', uvalue = 'tool 2', $

     event_pro = 'my_process', $

     ref_value = 'New Tools', position = -1

  envi_define_menu_button, buttonInfo, $

     value = 'New Tools', /menu, $

     ref_value = 'Preprocessing', $

     ref_index = 1, position = 'last'

  envi_define_menu_button, buttonInfo, $

     value = 'Tool 1', uvalue = 'tool 1', $

     event_pro = 'my_process', $

     ref_value = 'New Tools', $

     ref_index = 1, position = -1

  envi_define_menu_button, buttonInfo, $

     value = 'Tool 2', uvalue = 'tool 2', $

     event_pro = 'my_process', $

     ref_value = 'New Tools', $

     ref_index = 1, position = -1

END

PRO MY_PROCESS, event

  compile_opt IDL2

  print, 'Running the process'

END

API Version

---

4.2