SET FORMAT

version 2004.5 (Modified)

SET FORMAT ({*; }object; displayFormat)

SET FORMAT sets the display format for the objects specified by object to the format you pass in displayFormat. The new format is only used for the current display; it is not stored with the form.

If you specify the optional * parameter, you indicate an object name (a string) in object. If you omit the optional * parameter, you indicate a field or a variable in object. In this case, you specify a field or variable reference (field or variable objects only) instead of a string. For more information about object names, see the section Object Properties.

SET FORMAT can be used for both input forms and output forms (displayed or printed) and can be applied to fields or variables (enterable/non-enterable).

Naturally, you must use a display format compatible with the type of data found in the object or with the object itself.

To format Boolean fields, there are two possibilities:

• You can pass a single value in displayFormat. In this case, the field will be displayed as a checkbox and its label will be the value specified.

• You can pass two values, separated by a semicolon (;), in displayFormat. In this case, the field will be displayed as two radio buttons.

To format Date fields or variables, pass Char(n) in displayFormat, where n is one of the following predefined constants provided by 4D:

To format Time fields or variables, pass Char(n) in displayFormat, where n is one of the following predefined constants provided by 4D:

To format Picture fields or variables, pass Char(n) in displayFormat, where n is one of the following predefined constants provided by 4D:

To format fields or variables of the Alpha or Number type, pass the label of the format directly in the displayFormat parameter.

For more information about display formats, see the 4th Dimension Design Reference manual.

Note: In displayFormat, to use custom display formats that you may have predefined in the Preferences dialog box, prefix the name of the format with a vertical bar (|).

To format picture buttons, in the displayFormat parameter, pass a character string respecting the following syntax:

• cols = number of columns in the picture.

• lines = number of lines in the picture.

• picture = picture used, coming from the picture library, a picture variable or a PICT resource:

- If the picture comes from the picture library, enter its number, preceded by a question mark (e.g.: "?250").

- If the picture comes from a picture variable, enter the variable name.

- If the picture comes from a PICT resource, enter its number, preceded by a colon (e.g.: ":62500").

• flags = display mode and operation of a picture button. This parameter can take any of the following values: 0, 1, 2, 16, 32, 64 and 128. Each of these values represents a display mode or an operation mode. These values are cumulative; for instance, if you want to enable the modes 1 and 64, pass 65 in the flags parameter. Here are the details for each value:

- flags = 0 (no option)

Displays the next picture in the series when the user clicks the picture. Displays the previous picture in the series when the user holds down the Shift key and clicks on the picture. When the user reaches the last picture in the series, the picture does not change when the user clicks it again. That is, it does not cycle back to the first picture in the series.

- flags = 1 (Switch Continuously)

Similar to the previous option except that the user can hold down the mouse button to display the pictures continuously (i.e., as an animation). When the user reaches the last picture, the object does not cycle back to the first picture.

- flags = 2 (Loop Back to First Frame)

Similar to the previous option except that the pictures are displayed in a continuous loop. When the user reaches the last picture and clicks again, the first picture appears, and so forth.

- flags = 16 (Switch when Roll Over)

The contents of the picture button are modified when the mouse cursor passes over it. The initial picture is re-established when the cursor leaves the button's area. This mode is frequently used in multimedia applications or in HTML documents. The picture that is then displayed is the last picture of the thumbnail table, unless the Use Last Frame as Disabled option is selected (128). If that option is selected, it is the next-to-last thumbnail that is displayed.

- flags = 32 (Switch Back when Released)

This mode operates with two pictures. It displays the first picture all the time except when the user clicks the button. In that case, the second picture is displayed until the mouse button is released, whereupon it switches back to the first picture. This mode allows you to create an action button that displays its status (idle or clicked). You can use this mode to create a 3D effect or display any picture that depicts the action.

- flags = 64 (Transparent)

Used to make the background picture transparent.

- flags = 128 (Use Last Frame as Disabled)

This mode allows you to set the last thumbnail as the thumbnail to display when the button is disabled. When this mode is selected, 4th Dimension displays the last thumbnail when the button is disabled. When this mode is used in addition to the modes 0, 1 and 2, the last thumbnail is not taken into account in the sequence of the other modes. It will appear only when the button is disabled.

• ticks = activates the "Switch every n Ticks" mode and sets the time interval between the display of each picture. When this optional parameter is passed, it allows you to cycle through the contents of the picture button at the specified speed. For example, if you enter "2;3;?16807;0;10", the picture button will display a different picture every 10 ticks. When this mode is active, only the Transparent mode can be used (64).

To format picture pop-up menus, in the displayFormat parameter, pass a character string respecting the following syntax:

• cols = number of columns in the picture.

• lines = number of lines in the picture.

• picture = picture used, coming from the picture library, a picture variable or a PICT resource:

- if the picture comes from the picture library, enter its number, preceded by a question mark (e.g.: "?250").

- If the picture comes from a picture variable, enter the variable name.

- If the picture comes from a PICT resource, enter its number, preceded by a colon (e.g.: ":62500")

• hMargin = margin in pixels between the horizontal limits of the menu and the picture.

• vMargin = margin in pixels between the vertical limits of the menu and the picture.

• flags = transparency mode of picture pop-up menu. Accepts the values 0 and 64:

- mode = 0: the picture pop-up menu is not transparent,

- mode = 64: the picture pop-up menu is transparent.

To format objects of the thermometer or ruler type, in the displayFormat parameter, pass a character string respecting the following syntax:

• min = value of the first graduation of the indicator.

• max = value of the last graduation of the indicator.

• unit = interval between the indicator graduations.

• step = minimum interval of cursor movement in the indicator.

• flags = display mode and operation of indicators. This parameter accepts the values 0, 2, 3, 16 and 32. These values can be accumulated in order to set several options. Here are the details for each value:

- flags = 0: does not display the units.

- flags = 2: displays the units on the right or below the indicator.

- flags = 3: displays the units on the left or above the indicator.

- flags = 16: displays graduations adjacent to the units.

- flags = 32: On Data Change is executed while the user is adjusting the indicator. If this value is not used, On Data Change occurs only after the user is finished adjusting the indicator.

• format = display format of the indicator graduations.

Keep in mind that the units and graduations are automatically hidden if the size of the indicator object does not permit them to be displayed correctly.

To format objects of the dial type, in the displayFormat parameter, pass a character string respecting the following syntax:

• min = value of the first graduation of the indicator.

• max = value of the last graduation of the indicator.

• unit = interval between the indicator graduations.

• step = minimum interval of cursor movement in the indicator.

• flags = operation mode of the dial (optional). This parameter only accepts the value 32: On Data Change is executed while the user is adjusting the indicator. If this value is not used, On Data Change occurs only after the user is finished adjusting the indicator.

To format button grids, in the displayFormat parameter, pass a character string respecting the following syntax:

• cols = number of columns of the grid.

• lines = number of lines of the grid.

Note: For more information about the display formats for form objects, refer to the 4th Dimension Design Reference manual.

To format 3D buttons, in the displayFormat parameter, pass a character string respecting the following syntax:

• title = Button title. This value can be expressed as text or a resource number (ex.: ":16800,1")

• picture = Picture linked to a button that comes from a picture library, a picture variable or a PICT resource:

- If the picture comes from a picture library, enter its number, preceded with a question mark (ex.: "?250").

- If the picture comes from a picture variable, enter the variable name.

-If the picture comes from a PICT resource, enter its number, preceded by a colon (ex.: ":62500").

• background = Background picture linked to a button (Custom style), that comes from a picture library, a picture variable or a PICT resource (see above).

• titlePos = position of the button title. Five values are possible:

- titlePos = 0: Middle

- titlePos = 1: Right

- titlePos = 2: Left

- titlePos = 3: Bottom

- titlePos = 4: Top

• titleVisible = Defines whether or not the title is visible. Two values are possible:

- titleVisible = 0: the title is hidden

- titleVisible = 1: the title is displayed

• iconVisible = Defines whether or not the icon is visible. Two values are possible:

- iconVisible = 0 : the icon is hidden

- iconVisible = 1 : the icon is displayed

• style = Button style. The value of this option determines whether various other options are taken into consideration (for example, background). Ten values are possible:

- style = 0: None

- style = 1: Background offset

- style = 2: Push button

- style = 3: Toolbar button

- style = 4: Custom

- style = 5: Circle

- style = 6: Small system square

- style = 7: Office XP

- style = 8: Bevel

- style = 9: Rounded bevel

• horMargin = Horizontal margin. Number of pixels delimiting the inside left and right margins of the button (areas that the icon and the text must not encroach upon).

• vertMargin = Vertical margin. Number of pixels delimiting the inside top and bottom margins of the button (areas that the icon and the text must not encroach upon).

• iconOffset = Shifting of the icon to the right and down. This value, expressed in pixels, indicates the shifting of the button icon to the right and down when the button is clicked (the same value is used for both directions).

• popupMenu = Association of a pop-up menu with the button. Three values are possible:

- popupMenu = 0: No pop-up menu

- popupMenu = 1: With linked pop-up menu

- popupMenu = 2: With separate pop-up menu

Certain options are not taken into account for all 3D button styles. Also, in certain cases, you may wish to not change all the options. To not pass an option, simply omit the corresponding value. For example, if you do not want to pass the titleVisible and vertMargin options, you can write:

   SET FORMAT(myVar;"NiceButton;?256;:562;1;;1;4;5;;5;0")

1. The following line of code formats the [Employee]Date Hired field to Month Date Year.

   SET FORMAT ([Employee]Date Hired; Char(Month Date Year))

2. The following example changes the format for a [Company]ZIP Code field according to the length of the value stored in the field:

   If (Length ([Company]ZIP Code) = 9)
      SET FORMAT ([Company]ZIP Code; "#####–####") 
   Else 
      SET FORMAT ([Company]ZIP Code; "#####") 
   End if

3. The following example sets the format of a Boolean field to display Married and Unmarried, instead of the default Yes and No:

   SET FORMAT ([Employee]Marital Status;"Married;Unmarried")

4. The following example sets the format of a Boolean field to display a checkbox labelled "Classified":

   SET FORMAT ([Folder]Classification; "Classified")

5. You have a table of thumbnails containing 1 row and 4 columns, intended to display a picture button ("default", "clicked", "roll over" and "disabled"). You want to associate the Switch when Roll Over, Switch back when Released and Use Last Frame as Disabled options with it:

   SET FORMAT (*;"PictureButton"; "4;1;?15000;176")

Get format, SET FILTER.