Using Button Widgets

Button widgets allow users to respond to "yes-or-no" type questions via the widget interface. While button widgets are generally fairly simple to understand and use, there are numerous options that allow you to fine-tune the appearance and behavior of buttons in your interface. This section discusses some useful ideas and techniques for using button widgets. See WIDGET_BUTTON for a complete description of the function used to create button widgets.

Bitmap Button Labels

In addition to setting the VALUE of a button widget to a text string, you can use a bitmap image as the label for the button. To us a bitmap image, set VALUE to one of the following:

the path to a bitmap image file, if the BITMAP keyword is also specified.

an n x m byte array converted to a bitmap byte array using the CVTTOBM function, which displays as a black-and-white bitmap image.

an n x m x 3 byte array, which displays as a 24-bit color bitmap image.

The following sections describe the process of creating bitmap files, black-and-white arrays, and color arrays for use as bitmap button labels.

Creating Bitmap Files for Buttons

You can produce appropriate bitmap files (for use with the BITMAP keyword to WIDGET_BUTTON) using any bitmap editor available on your operating system. Be sure to save the file as a .bmp file.

Additionally, on Windows, you can create a bitmap using the IDL GUIBuilder Bitmap Editor, which creates 16-color bitmaps for buttons. The Bitmap Editor can read and write bitmap files (*.bmp). Using the editor, you can create your own bitmaps, or you can open existing bitmap files and modify them. Open the Bitmap Editor from the Properties dialog for a created button. For more information, see Using the Bitmap Editor.

Transparent Bitmaps

For 16- and 256-color bitmaps included using the BITMAP keyword, IDL uses the color of the pixel in the lower left corner as the transparent color. All pixels of this color become transparent, allowing the button color to show through. This allows you to use bitmaps that do not appear to be rectangular. If you have a rectangular bitmap that you want to use as a button label, you must either draw a border of a different color around the bitmap or save the bitmap as a 24-bit (TrueColor) image. If your bitmap also contains text, make sure the border you draw is a different color than the text, otherwise the text color will become transparent.

Creating Black-and-White Bitmap Arrays for Buttons

You can produce appropriate black-and-white bitmap arrays in IDL in the following ways:

Create a black and white bitmap using an external bitmap editor, and read it into an IDL byte array using the appropriate procedure (READ_BMP, READ_JPEG, etc.) and convert the byte array to a bitmap byte array using the CVTTOBM function.

On an X-Window system, use the X11 bitmap utility to create a black and white bitmap byte array and read it in to IDL using the READ_X11_BITMAP routine.

Create a black and white bitmap using the XBM_EDIT procedure. This procedure offers several alternatives for the form of the final bitmap.

Create an n x m byte array using the BYTARR function and modify array elements using array operations. Use CVTTOBM to convert the array to a bitmap byte array.

Creating Color Bitmap Arrays for Buttons

Create a 24-bit color image using an external bitmap editor, and read it into an IDL byte array using the appropriate procedure (READ_BMP, READ_JPEG, etc.). Remember that the image array must be interleaved by plane (n x m 3), with the planes in the order red, green, blue. Note that image files created by image editors are often interleaved by pixel rather than by plane; use the TRANSPOSE function to reformat the array.

For example, if you read a 24-bit color image into an array using the READ_BMP function, the resulting array will be interleaved by pixel (with dimensions 3 x n x m), with planes in the order blue, green, red. To create an array in the proper format for use as a button bitmap, use the following IDL commands:

button_image = READ_BMP('bitmap_file.bmp', /RGB) 
button_image = TRANSPOSE(button_image, [1,2,0]) 
... 
button = WIDGET_BUTTON(base, VALUE=button_image)

Here, the RGB keyword to READ_BMP reorders the color planes to be in the order red, green, blue; the call to TRANSPOSE puts the array in the proper format for use in a bitmap button.

Create an n x m x 3 byte array using the BYTARR function and modify the array elements using array operations.

Although IDL places no restriction on the size of bitmap allowed, the various toolkits may prefer certain sizes.

Tooltips

You can specify a "tooltip" - a short text string that will appear when the mouse pointer hovers over a button widget - by specifying the string as the value of the TOOLTIP keyword to WIDGET_BUTTON.

Exclusive and Non-Exclusive Buttons

By default, when a user clicks on a button widget, the button appears to be depressed while the user holds down the mouse button, but the button returns to the undepressed appearance when the user releases the mouse button. While such "normal" buttons visually reflect the state of the button (depressed or undepressed), normal buttons are used to gather a single piece of information: whether the user clicked on the button or not.

Buttons placed into exclusive or non-exclusive bases (created via the EXCLUSIVE or NONEXCLUSIVE keywords to WIDGET_BASE procedure) are created as two-state "toggle" buttons. Visually, when a user clicks on an exclusive or nonexclusive button, it remains in the depressed state, either until the user clicks on it again or (in the case of exclusive buttons) until another button in the group is depressed. Buttons that toggle in this manner can be used to gather information about a quantity that has two possible states.

If a base is created with the EXCLUSIVE keyword, only one button on the base can be selected at a given time. If one button is selected and another button pressed, the first button becomes unselected.

If a base is created with the NONEXCLUSIVE keyword, any number of buttons can be selected at a given time. Pressing one button has no effect on the selected/unselected state of other buttons on the base.

Exclusive and nonexclusive buttons take on different appearances, depending on the type of button and on the windowing toolkit in use (Microsoft Windows or Motif).

Often, it is easier to create groups of buttons (normal, exclusive, or nonexclusive) using the CW_BGROUP compound widget than it is to program them yourself from base and button widgets and manage the events from each button individually. See Button Groups and CW_BGROUP for additional information on using button groups.