Defining Command Buttons

Command buttons enable the user to perform specific actions. They should only be used in form components, not in reports.

When using command buttons, be aware of the following:

In a Windows environment, the default command button does not support images or text alignment. Set the Representation property to Uniface), if you want to align the text, use images or colors in the command button, or use images to represent buttons.
You can display an image in the button by setting its Data Type to Image and assigning an image or glyph as a value. However, to display both an image and text on the button, set the Data Type to String.
You can completely replace the representation of a button with an image by specifying an image or glyph with the Default Image property.
In non-Windows environments, use carriage returns to wrap the text correctly. (In the Microsoft Windows environment, text in a command button is automatically wrapped.)

The following instructions describe how to define some basic command buttons. Working samples are available on Rocket Community.

To display text on the command button, you can:
- Enter the text in the Initial Value of the field
- Assign the text to the field as a value
- Use $text to load a global message text into the command button
Ensure that the size of the button is large enough to accommodate the size of the text. For example, if you draw a button one character in depth and your font is too large, the text in the button becomes illegible at run time.
To use an image as a button, set the following field and widget properties:
- Data Type: String
- Representation: Uniface
- Default Image: Image or glyph name
Optionally, specify other images to provide visual feedback about the button state using the Active Image, Focus Image, and Hover Image properties.
The image fills the background of the button and is stretched to fill the button area. The button text (if the field has a value) is visible over the image, and it is possible to change it's color using the Active Text Color, Focus Text Color, and Hover Text Color properties.
To display an image or glyph in the command button:
- Set the following field and widget properties
  - Data Type: String
  - Initial Value or assigned field value: @Image!% (GOLD ! after the image name, followed by a percent sign)
  - Representation: Uniface
  You can use the Image Label Align Property to control the alignment and position of the image.
- Alternatively, set the following field and widget properties:
  - Data Type: Image
  - Initial Value or assigned field value: Image or glyph name
  - Representation: Uniface
  If the field is of the data type Image, Uniface assumes that the value is a glyph or image, and not text.
  To have Uniface automatically scale an image to fit a command button, set the Preserve Aspect Ratio property. If you load a glyph for which there are a number of variations, Uniface attempts (automatically) to load the one with the most suitable size. Microsoft Windows metafiles are rendered on a correctly-sized bitmap before displaying.
To display both an image and text in the command button, with the text coming from the field value, set the following field and widget properties:
- Data Type: String
- Initial Value or assigned field value: @Image!Text (GOLD ! after the image name)
- Representation: Uniface
To display both an image and text in the command button, with the text coming from the label:
- Set the following widget and field properties:
  - Data Type: Image
  - Initial Value or assigned field value: Image or glyph name.
  - Representation: Uniface
- Draw a label directly adjacent to the button. The height of the button and label should be the same. Rename the label to associate it with the button. This internalizes the label in the command button.
- Ensure that the Auto Label property is cleared, otherwise the label text is not displayed.
Command buttons (Image data type) and their associated labels are automatically internalized if the entity's Field List property is set to All Fields. If you draw a command button on an entity that already contains fields, and create a label, associating it with the command button, the label and command button are internalized. Internalized labels and command buttons are treated as single units. Clicking an internalized label or command button gives focus to both the label and the command button.
To define an empty command button, enter the text associated with the button adjacent to the command button on the component canvas, using a label or component text.
Make sure that the command button field is not data type Image. This prevents Uniface internalizing a label with the command button.
In the detail trigger, enter the ProcScript for the action that the button initiates.
For example, for a Save button, you could activate the ^Store macro:
```
macro "^STORE"
```