3.21) The height level functions.

Camlwin also provides functions of higher level such as open and manage a window to ask for a file name, open and manage a warning window, open and manage a window to ask a string, an integer...

3.21.1) Ask for a value.

All the functions with a name that start with "gr_input" open a window of the type shown in figure 3.1 and wait until the user types Enter or presses the Ok button to close the window and return the type value. The user can only type a value of the type defined by the called function.

Figure 3.1

gr_input_string : string -> string -> string
gr_input_string Title Init opens a block window with the top prompt Title, a line input area set with the string Init, and a button 'Ok'. When the user finishes typing his value, the window is closed and the function returns the typed string.
gr_input_natural : string -> int -> int
gr_input_natural Title n opens a block window with the top prompt Title, a line input area set with the positive integer n, and a button 'Ok'. When the user finishes typing his value, the window is closed and the function returns the typed integer.
gr_input_int : string -> int -> int
gr_input_int Title n opens a block window with the top prompt Title, a line input area set with the integer n, and a button 'Ok'. When the user finishes typing his value, the window is closed and the function returns the typed integer.
gr_input_hexa : string -> int -> int
gr_input_float : string -> float -> float
gr_input_float Title x opens a block window with the top prompt Title, a line input area set with the float x, and a button 'Ok'. When the user finishes typing his value, the window is closed and the function returns the typed float.
gr_input_password : string -> string -> string
gr_input_password Title Init opens a block window with the top prompt Title, a line input area set with the hide string Init, and a button 'Ok'. When the user finishes typing his value, the window is closed and the function returns the typed value.
gr_input_filename : string -> string -> string
gr_input_filename Title Init opens a block window with the top prompt Title, a line input area set with the string Init, and a button 'Ok'. When the user finishes typing a correct value, the window is closed and the function returns the typed name. If the name isn't a valid file name, the window remains opened and asks for a new value. To test if the value is a valid file name, Camlwin tries to open the file, and to erase the possible existing file with the same name.

3.21.2) Ask for values.

type minput_type = 
{
  minput_name : string;
  minput_type : string_type;
  minput_init : melted_type
};;
gr_minput : string -> minput_type vect -> melted_type vect
gr_minput
gr_string_of_melted : melted_type -> string
gr_string_of_melted Melted returns the string inside Melted if Melted match with string_type, otherwise returns "".
gr_int_of_melted : melted_type -> int
gr_int_of_melted Melted returns the integer inside Melted if Melted match with int_type, otherwise returns 0.
gr_float_of_melted : melted_type -> float
gr_float_of_melted Melted returns the float inside Melted if Melted match with float_type, otherwise returns 0.0.
gr_bool_of_melted : melted_type -> bool
gr_bool_of_melted Melted returns the boolean inside Melted if Melted match with bool_type, otherwise returns false.
gr_image_of_melted : melted_type -> image
gr_image_of_melted Melted returns the string inside Melted if Melted match with bitmap_type, otherwise returns gr_empty_image.

3.21.2) Edit a text.

The function gr_edit opens the window shown in figure 3.2.

Figure 3.2

gr_edit : string -> string -> string
gr_edit Title Init opens a window with a text edit object, a prompt object, and a button object. The text edit object is set with the value Init. The top prompt is set to Title. The button closes the window and returns the edit string (ex: gr_edit "Compile tmp.ml:" "" opens the window shown in figure 3.2).

3.21.3) the blocking warning.

When the program encounters a problem, or possible invalid command, it must display a message and ask what it should do next. In Camlwin, the function gr_warning a opens window with two areas:
  1. the text of the message, cut at the end of word to display it in the window,
  2. one (figure 3.3a), two, or three( figure 3.3b) buttons.

Figure 3.3a


Figure 3.3b

                                             
type gr_warn =
  { warn_name : string
  ; warn_callback : gr_button -> event -> bool
  }
;;
The type gr_warn is used to define the label of a button and the callback function of the button.
gr_warning : string -> gr_warn vect -> unit
gr_warning "It's not a file created with Camlicon!" [| { warn_name="Ok"; warn_callback=gr_close_warning} |] opens a window with the text "It's not a file created with Camlicon!", and a button centered at the bottom of the window (figure 3.3a). This button is filled with the label 'Ok', and the function called when the button is pressed is gr_close_warning; a function that closes the warning window. If the gr_warn vect parameter is of length two, the window is opened with two buttons, and if the length is three or more, the window is opened with the first three defined buttons (ex: gr_warning "The file add_draw.ml isn't saved. Save it?" [| { warn_name="Yes"; warn_callback=Save}; { warn_name="No"; warn_callback=DontSave}; { warn_name="Cancel"; warn_callback=Cancel} |] opens the window of figure 3.3b).
gr_close_warning : 'a -> 'b -> bool
gr_close_warning is the function that closes the warning window. It can be used as the callback of the buttons in the warning window.
  
type gr_answer = gr_ans1
               | gr_ans2
               | gr_ans3
;;
gr_warning1 : 'a -> 'b -> bool
gr_warning2 : 'a -> 'b -> bool
gr_warning3 : 'a -> 'b -> bool
gr_warn_button : unit -> gr_answer
Another way of managing a warning window is to set the callback functions to gr_warning1 for the first button, gr_warning2 for the second button, gr_warning3 for the third button. These three functions set a mutable variable to gr_ans1, gr_ans2, gr_ans3 repectively. The value of the variable can be obtained with gr_warn_button ().

3.21.4) The look menu.

gr_look_menu : gr_menu
The menu gr_menu_look can be added to a menu bar. It changes the global variable that defines the present look. The menu is the one shown in figure 3.4.

Figure 3.4.

3.21.5) Select a file.

The user can select a file in a window that provides a list of directories, a list of files inside the current directory and a filter to display only matching files. The window look like the one shown in figure 3.5.


Figure 3.5.

A filter is present at the bottom of the window. The user can change it, and press "Enter" to match the file list to the new filter. The user can change directory just by clicking on the desired directory. If the user presses the 'Ok' button with a file selected, or double clicks on the same file, the window is closed and the function returns the file name. If the user presses 'Cancel' button, the window is closed and the function returns an empty string.

gr_select_file : string -> string
gr_select_file Filter opens the file select window and returns the selected file name if the user presses the 'Ok' button or an empty string if the user presses the 'cancel' button. The filter is set with Filter. Inside Filter, the character '*' represents any numbers (including zero) of characters. The character '?' represents any single character.
gr_without_suffix : string -> string
gr_without_suffix Name returns the part of the string Name which is before the first dot, if there is one inside Name.
gr_suffix_only : string -> string
gr_suffix_only Name returns the part of the string Name which is after the first dot inside Name. a = (gr_without_suffix a) ^ "." ^ (gr_suffix_only a).

3.21.6) Select a line.

gr_select : string -> string vect -> (int * string)
gr_select Title Lines opens a window with a top prompt Title, and a list object set with Lines, and an 'Ok' button. When the user presses the 'Ok' button, the window is closed, and the function returns the couple: (number of the selected line, string of the selected line).

3.21.7) Find and replace in a text.

gr_find_in_text : gr_text -> int -> int -> unit
Figure 3.6.

gr_find_in_text Text x y opens the window shown in figure 3.6. This window has its upper left corner at (x,y). When the user presses 'Ok', the Text cursor moves to the end of the first found string of the input line object "Text to find:". If the string is not found in Text, a warning window says it.
gr_replace_in_text : gr_text -> int -> int -> unit
Figure 3.7.

gr_replace_in_text Text x y opens the window shown in figure 3.7. The upper left corner is at (x,y). When the user presses the 'Ok' button, every occurence of the "Text to find" string in the text edit object Text is replaced with the "Replace with" string. If the search string is not found, a warning window says it.

3.21.8) The shell window.


Figure 3.8.

gr_shell : window
gr_shell is a window with a shell object inside, such as the window shown in figure 3.8. In this window, the user can type shell commands and see their response. When the user presses the 'Ok' button, the window is closed. This window is not a blocking window, but it doesn't need to be added to the window list taken by gr_main_loop as an argument.

3.21.9) The color selection.


Figure 3.9.

gr_select_font : Formated_string -> Formated_string
gr_select_font FontSpec opens the window shown in Figure 3.9. The user selects a font, shows the result in the white area, and then press 'Ok'. The return value is the selected font.

3.21.10) The font selection.


Figure 3.10.

gr_select_color : color -> color
gr_select_color Color opens the window shown in Figure 3.10. The user selects a color by pressing the predefined color button or by moving the scrollbars, shows the result in the top rectangle, and then press 'Ok'. The return value is the selected color.