[[Property:title|Constants]]
[[Property:weight|12]]
[[Property:uuid|f658bc39-da5f-1f12-ccf6-16b9c08732c2]]
EiffelBuild supports the use of constants, permitting you to define a particular value and use it comprehensively throughout your system. If a constant is in use, any changes are reflected immediately in all clients, providing a quick way of globally changing object properties. The Eiffel code generated by EiffelBuild, generates all constants as actual Eiffel constants for use in your system.

The following constant types are supported by EiffelBuild: 
*  '''String''' - Representing the Eiffel STRING type. 
*  '''Integer''' - Representing the Eiffel INTEGER type. 
*  '''Directory''' - Representing a directory location, of type STRING. 
*  '''Pixmap''' - Representing an EV_PIXMAP, and either absolute, or built from a directory constant. 
*  '''Font''' - Representing a font, of type EV_FONT. 
*  '''Color''' - Representing a color, of type EV_COLOR. 


==Constants Dialog==

Modification to all constant types is performed from the constants dialog, accessible from the [[Main toolbar|main toolbar]]  via the  [[Image:icon-format-onces-color]]  button. The constants dialog has the following appearance: 

[[Image:constants-dialog]]  

The screenshot above, shows the constants dialog displayed for a project containing twelve constants, a few of each available type. Each of the constants in the project are displayed in the multi column list occupying most of the dialog.

The "Type", "Name" and "Value" fields displayed along the bottom of the dialog are used to permit addition and modification of constants. The "OK" button displayed in the top right hand corner of the dialog closes the dialog when modifications to the constants are complete. 
===Adding a new constant===

To add a new constant to your project, select the type of the constant that you wish to add from the "Type" combo box. Depending on the type of constant selected, the remaining fields, and associated buttons will be modified appropriately, and the steps required to add the constant differ: 
*  '''String''' and '''Integer''' - Enter the name in the "Name" field, and value in the "Value" field. The "New" button is only enabled when the name is valid, and a valid entry is set, and clicking it adds the new constant. 
*  '''Directory''' - Enter a name for the directory in the "Name" field, and then select "New" which displays a choose directory dialog. Selecting a directory from this dialog and pressing "OK" adds the new directory constant to the project. 
*  '''Pixmap''' - Select the "New" button, which brings up the Pixmap Constant Dialog enabling you to select a constant. The use of this dialog is described further down this page. 
*  '''Font''' - Enter a name in the "Name" field, and then select "New" which displays a font dialog. Selecting a font from this dialog and pressing "OK" adds the new font constant to the project. 
*  '''Color''' - Enter a name in the "Name" field, and then select "New" which displays a color dialog. Selecting a color from this dialog and pressing "OK" adds the new color constant to the project. 

{{note|After adding a new constant, it is immediately displayed with all constants in the dialog. }}


===Modifying an existing constant===

To modify a constant that already exists, select the constant in the multi column list, and depending on the type of the constant, perform the following: 
*  '''String''' and '''Integer''' - Modify the value, which in turn, enables the "Modify" button, which must be selected for the value to change. Note that if you change the name, the "New" button is enabled as this will now add a new constant. 
*  '''Directory''' - Select the "Modify" button which displays a directory dialog, permitting selection of the new value. 
*  '''Pixmap''' - Select the "Modify" button which displays the Pixmap Constant Dialog, in a mode which permits you to select the new pixmap you wish to use. 
*  '''Font''' - Select the "Modify" button which displays a font dialog, permitting selection of the new font. 
*  '''Color''' - Select the "Modify" button which displays a color dialog, permitting selection of the new color. 

===Removing constants===

To remove a constant from the project, select it in the multi column list, and select the "Remove" button, or press the delete key. If the constant is not in use within the system, it will be removed, otherwise the following dialog is displayed:

[[Image:constant-in-use]]  

As objects are reliant on the constant you are removing, you must confirm that you really wish to remove it from the system. If you select "OK", the constant is removed, and the object property relying on that constant is converted to a manifest value. For example, if you are using an Integer constant with a value of 100, and you remove the constant, the property no longer references the constant, but is set explicitly to 100.

{{note|You may sort the constants displayed in the dialog, by clicking the associated column header. }}

==String constant==

A String constant represents an Eiffel STRING, and may be any valid STRING. For example, in the generated constants file, for a String constant named `modify_button_text`, the following code is generated:
<code>
    modify_button_text: STRING
            -- `Result' is STRING constant named modify_button_text.
        once
            Result := "Modify"
        end
</code>


==Integer constant==

A Integer constant represents an Eiffel INTEGER, and may be any valid INTEGER value. For example, in the generated constants file, for an Integer constant named `medium_padding`, the following code is generated:
<code>
    medium_padding: INTEGER
            -- `Result' is INTEGER constant named medium_padding.
        once
            Result := 8
        end</code>

==Directory constant==

A Directory constant is an Eiffel representation of a directory, as a STRING value. For example, in the generated constants file, for a Directory constant named `pixmap_location`, the following code is generated:
<code>
    pixmap_location: STRING
            -- `Result' is DIRECTORY constant named pixmap_location.
        once
            Result := "C:\pixmaps"
        end</code>


==Pixmap constant==

A pixmap constant is a representation of a pixmap image, and two types are available:
*  '''Absolute''' - The generated code contains a constant of type EV_PIXMAP, built from a single, absolute path, based on the location of the original pixmap on disk as follows: 
<code>
    main_pixmap: EV_PIXMAP
            -- `Result' is PIXMAP constant named main_pixmap.
        local
            a_file_name: FILE_NAME
        once
            create Result
            create a_file_name.make_from_string ("C:\pixmaps\main_pixmap.png")
                -- Now set `Result' based on `a_file_name'.
            set_with_named_file(Result, a_file_name)
         end</code>

*  '''Relative''' - The generated code contains a constant of type EV_PIXMAP, built from a file name and a directory constant. This type of pixmap constant is the most frequently used, as it is more flexible. By redefining the value of the directory constant on which it is based, your systems may easily account for the installation location of the pixmap. A relative Pixmap constant is generated as follows: 
<code>
    main_pixmap: EV_PIXMAP
            -- `Result' is PIXMAP constant named main_pixmap.
        local
            a_file_name: FILE_NAME
        once
            create Result
            create a_file_name.make_from_string (pixmap_location)
            a_file_name.set_file_name("main_pixmap.png")
                -- Now set `Result' based on `a_file_name'.
            set_with_named_file(Result, a_file_name)
        end</code>

Where `pixmap_location` is the name of the Directory constant to which the pixmap is relative.


==Font constant==

A Font constant represents an EV_FONT. For example, in the generated constants file, for a font constant named `times_new_roman`, the following code is generated:
<code>
    times_new_roman: EV_FONT
            -- `Result' is EV_FONT constant named `times_new_roman'.
        once
            create Result
            Result.set_family (feature {EV_FONT_CONSTANTS}.Family_roman)
            Result.set_weight (feature {EV_FONT_CONSTANTS}.Weight_regular)
            Result.set_shape (feature {EV_FONT_CONSTANTS}.Shape_regular)
            Result.set_height_in_points (12)
            Result.preferred_families.extend ("Times New Roman")
        end</code>

==Color constant==

A Color constant represents an EV_COLOR. For example, in the generated constants file, for a color constant named `red`, the following code is generated:
<code>
    red: EV_COLOR
            -- `Result' is EV_COLOR constant named `red'.
        once
            Result := create {EV_COLOR}.make_with_8_bit_rgb (255, 0, 0)
        end</code>

===Pixmap constant dialog===

The Pixmap Constant dialog is used to select pixmaps for addition to an EiffelBuild project, and is displayed from the Constants dialog when necessary. The Pixmap Constant dialog has the following appearance:

[[Image:pixmap-selection-dialog]]  

An individual pixmap may be selected, or a whole directory of pixmaps may be selected from this dialog for addition. In the screenshot above, a directory containing two pixmaps was selected. The "Build from" option at the bottom of the dialog permits you to select if you wish to add an absolute or relative pixmap, and if multiple pixmaps are being added, the currently selected pixmap from the list above is active. The relative "DIRECTORY" for relative pixmaps is filled in automatically if EiffelBuild finds a directory constant in the system that matches the path chosen. If not, you may enter a name in this field to create a new directory matching the required path. If you do not enter a directory name for one or more relative pixmaps, upon closing the dialog, you will be prompted to enter a name for a directory constant used for these pixmaps. 
{{note|If you are selecting new pixmaps, and they appear in the dialog as unchecked, it means that an equivalent pixmap already exists in the project. }}


==Loading constants==

The generation of an EiffelBuild project creates two constants classes, an interface class and an implementation class, named to match the setting from the [[EiffelBuild: Project settings window|project settings]] . For example, if you have specified the name "constants" for the constants, two classes are generated, <eiffel>CONSTANTS</eiffel> and the implementation, <eiffel>CONSTANTS_IMP</eiffel>. 

By default, all constant values are hard coded into the implementation class, but it is possible to set these to be loaded from an external file upon execution of the generated system. To do this, the "Load constants from file" setting of the [[EiffelBuild: Project settings window|project settings]]  must be checked, which causes a file "constants.txt" to be generated, containing the definitions of all Integer and String constant values. As the system is executed, the values of these constants are loaded from the file, and by providing different versions of the file, at the time of deployment, multiple languages may be accounted for in your generated system. 

==Using constants==

Constants may be associated to properties of your [[EiffelBuild Notation|objects]]  via an [[Object editor|object editor]]  targeted to that [[EiffelBuild Notation|object]] . The  [[Image:icon-format-onces-color]]  button denotes the use of a constant value. For more information regarding using constants, in [[Object editor|object editors]] , see [[Object editor|object editor]] . 

When an EiffelBuild project is generated, all constants are added to a class, inherited by each window class. There is an "_IMP" and interface versions of these classes as with each window. For more information regarding the generation of constants, see [[EiffelBuild: Code Generation|code generation]] . 
{{note|To modify pixmap constants based on the current installation of an EiffelBuild generated interface, simply redefine the Directory constant used to access the pixmaps within the interface constants class (not "_IMP"), which is not re-generated if it already exists. }}

{{seealso|<br/>
[[EiffelBuild: Code Generation|Code generation]]  <br/>
[[Object editor|Object editor]]  <br/>
[[EiffelBuild: Project settings window|Project settings]]  }}