The %di format in detail

In this section:

• Using dialog resources
• What you need
• Getting started
• How %di works
• The %di format in detail
• How to use %di with menus
• Resource components for format codes
• Notes

In what follows id is used to represent an integer control identifier expressed in the dialog editor in the form IDC_STATIC, IDC_BUTTON1 etc. and accessed in the program via an INCLUDE statement.

Components 1 to 5 below appear only in the dialog resource editor. That is they appear in the resource script and not in the program code.

1. The caption and intial font
   These are provided in the Properties of the dialog.
   
2. Text
   Text is inserted using Static text components. The current font is used unless the text is given a unique id and a string resource is provided with the same id. Here is an example of such a string:
   
      Times New Roman,12,(0,0,255),(0),Bold,Italic
   
   Items are separated by commas. The name of the font is optionally followed by the size in points then a triplet for the text colour and one for the background colour (a single zero represents the default); then optionally, in any order, Bold, Italic and Underline. These three are not case sensitive and only the first character is significant.
   
3. Bitmaps, Icons, standard Icons and jpeg images
   Bitmaps and Icons must first be imported into the resource. For simpicity you can use the default id (IDB_BITMAP1, IDI_ICON1 etc.). You can then edit the dialog and select a Picture component from the Controls toolbox. Position this component in the dialog and use the default id for the picture (IDC_STATIC). Select the correct type (Bitmap or Icon) and select an image id (IDB_BITMAP1 etc) from the "Image" combobox. Standard icons are obtained by selecting an icon Picture component with id=IDC_STATIC. In the "Image" combobox enter one of the following numeric values.
   
   

   Value	Symbol
   32513	Stop sign
   32514	Question mark
   32515	Hazard sign
   32516	Information sign
   32517	Windows logo

   
   One way to import a jpeg image is to open the resource script as text and to type in:
   
     jpegname IMAGE DISCARDABLE "image.jpg"
   
   In the dialog editor, insert a Static Text component with the text set to %im[jpegname]. The simple Border style is automatically converted to the extended Client edge style. The simple Sunken style can be used to give a visual impression of the space used.
   
4. Group Boxes
   These provide a visual effect only and are not referred to in the program code.
   
5. Simple buttons that do not use a callback function or grey control.
   These need only appear in the resource. The "Tab order" is only significant when the value returned by winio@ is used to indicate which button was pressed on exit.
   Icons can be attached to buttons (equivalent to %bi (Button Icon)) if the button is given an id that is identical to that of an icon in the resource script. To change the font or background colour you must include the %bt (Button) in the program and use %bc (Button Background Colour) and %'bg.
   
   The following codes can be used with %di. With the exception of %sh (Property Sheet) and %sm (Modify System Menu), and the possible exception of %mn (Menu) and %pm (Popup Menu), it is recommended that %di should appear before all other format codes. Other arrangements may be possible but the outcome is reserved.
   
   In most cases %tc (Text Colour), %ts (Text Size) and %`bg can be used in the program to change the control text colour, text size and background colour. %`ts has been added. This takes no arguments and restores the text size to the size before the previous %ts.
   Except where stated, parameters in the program that determine the width and depth of the control are nolonger required. Additional styles and extended styles can often be added using the resource.
   
6. An "Edit Box" component is used to link to the formats %rd (Edit Integer), %rf (Edit Floating Point), %rs (Edit String), %re (Multiline Edit Box) and %st (String)
   The box automatically has a "Client edge" style and currently this cannot be switched off.
   
7. A "Button" component is used to link to formats %bt (Button) and %tt (Textual Toolbar) that have a callback and/or a grey control.
   Other details are the same as for item 5 above.
   
8. A "Radio button" component is used to link to the format %rb.
   Radio buttons can be ganged together (equivalent to %ga (Gang Controls)) by using the resource "Tab Order" and by marking the first button and the one after the last with the "Group" attribute. If one of the control variables is preset to 1 then the effect is the same as using %`ga (one control is always on). If all of the control variables are preset to zero then the effect is the same as using %ga.
   
9. A "Check box" component is used to link to the format %`rb.
   Check boxes can be ganged together using the same technique as for radio buttons (see item 8 above).
   
10. A "Listbox" component is used to link to the formats %ls (List Box (or Combo Box)), %ms (Multi-select Box) and %pb (Parameter Box).
    A string resource with the same id as a Listbox can be used the specify the entries in a %ls or %ms list. Here is an example:
    
      $Apples$Bananas$Oranges$Pears$
    
    The first character ($ in this example) denotes the item separator. A character array of suitable size must be declared in the program.
    
11. A "Combobox" component is used to link to the formats %`ls and %el (Editable Combo Box).
    The Combobox can be populated by using the Data tab in the Combo Box Properties dialog. Alternatively a string resource with the same id as a Combobox can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program.
    
12. A "Listview" component is used to link to the format %lv (List View).
    A string resource with the same id as a Listview can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program. The item separator for rows must be different from the item separator for columns.
    
13. A "Treeview" component is used to link to the formats %bv (Branch View) and %tv (Tree Control) (%bv is preferred).
    A string resource with the same id as a Treeview can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program.
    
14. A "Progress bar" component is used to link to the format %br (Bar).
    Changing the extended styles has no effect. See the note 7 for new options.
    
15. A "Static Text" component is used to provide a place marker for the graphics format %gr (Graphics Region).
    Give the component a unique id (IDC_STATIC1 etc.) and give it a simple border to visualise its dimensions. Set the text itself to %gr. The width and height of the region are nolonger included in the program but are specified in the resource. The program must respond to these values by supplying a start up callback %sc (OnShow Callback) (say) in which the dimensions are obtained using CLEARWIN_INFO@('GRAPHICS_WIDTH') and CLEARWIN_INFO@('GRAPHICS_DEPTH'). The graphics image is drawn using these values. This is similar to the way in which the %gr option [user_resize] is used however in simple cases it is not necessary to attach a callback function to %gr.
    
16. The scheme for %gr (Graphics Region) is also used for %og (OpenGL Graphics Region), %pl (SIMPLEPLOT Graphics Region), %eb (Edit Box), %cw (ClearWin Window), %fr (MDI Frame) and %sl (Slider) but in these cases the resizing is automatic.
    i.e. use "Static Text" with the text set to the format code. A slider is given a "Button face" background colour.
    
17. A "Static Text" component is used to provide a place marker for the formats %ib (Image Button), %tb (Bitmap Button), %eq (Equation), %cl (Colour Palette), %tx (Text Array), %gi (GIF) and %ld (LED).
    The scheme is the same as for %gr etc. but in these cases the width and height are fixed. In the case of %tx, you must provide all of the usual arguments in the program as well as the id.
    
18. A "Static Text" component with the text set to %he is used instead of %he (Help Location) in the program to mark the position, width and height of an Edit box for help text. %he cannot appear in the program and (if help strings are provided for controls and/or menu items) this component must appear in the dialog resource (unless %th (Tooltip Help) is used). The Edit box might be shown in the form of a status bar at the foot of the dialog and given the sunken attribute (say) to make it visible.
    
19. A "Tab Control" component is used to link to at upgraded version of the format %ps (Property Sheet Container).
    The corresponding %sh (Property Sheet) dialogs are given the "Child" style in the dialog resource and %ca (Caption) is used in the program (see Samples\s8tab). The name of an icon resource can be appended (following a back-slash) to the caption (e.g. %ca[Telephone\icon1]) and %?sh[Telephone numbers] gives a MS style tooltip for the sheet which becomes visible when the Tooltips style is selected. The size of each %sh dialog is set in the resource. The size of all the sheets can be made exactly the same by viewing and editing the resource script as text. By default the size of the %ps control is also set in the resource (see note 6).
    
20. A "Static Text" component (with any text) can be linked with %wc, %wd, %we, %wf, %wg, %ws, or %wx in the program.
    Give the text a unique id and use the same id (before the usual argument) in the program.
    
21. A "Date Time Picker" component can be linked to a new format %dt (see note 8).
    
22. A "Month Calendar" component can be linked to a new format %mc (see note 9).