Context:

Epsilon User's Manual and Reference

Primitives and EEL Subroutines

Input Primitives

. . .

Other Input Functions

Dialogs

Standard Dialogs

Button Dialogs

Windowed Dialogs

The Main Loop

. . .

Epsilon User's Manual and Reference > Primitives and EEL Subroutines > Input Primitives > Dialogs >

Windowed Dialogs

	Dialog name	Windows	Dialog name	Windows
	AskExitBox	2	GeneralBox	1
	AskSaveBox	2	HelpSetup1	1
	CaptionBox	2	OneLineBox	1
	EditVarBox	2	PromptBox	2
	FileDateBox	1	SetColorBox	3
	FileDateBox2	1	UsageBox	1

Each dialog requires one to three handles to pop-up windows, created with add_popup( ) in the usual way. The primitive moves these windows to the new dialog box. If you use a dialog which requires only one or two window handles, provide zero for the remaining handles. The windows will be resized to fit the dialog, and each will be assigned a unique "screen handle". Mouse clicks in that window will set the mouse_screen variable to the matching screen handle. You can use the window_to_screen( ) primitive to determine the screen number assigned to each window.

The parameters button1, button2, button3, and button4 specify the text for the buttons. If you want fewer buttons, provide the value "" for any button except button 1 and it will not appear. The specified title appears at the top of the dialog box.

When you click on a button in a dialog, Epsilon normally returns a particular fixed keystroke: either Ctrl-m, or the abort key specified by the abort_key variable, or the help key specified by the HELPKEY macro, for the first, second, and third buttons respectively. These correspond to typical button labels of "OK", "Cancel", and "Help", so that most EEL programs don't need to do anything special to receive input from buttons. If an EEL program needs to know whether a keypress came from an actual key, or a button, it can examine the value of the key_is_button variable. This variable is zero whenever the last key returned was an actual key, and nonzero when it was really a button. In the latter case, its value is 1 if the leftmost button was pressed, 2 if the next button was pressed, and so forth.

Sometimes an EEL program puts different labels on the buttons. It can be more convenient in this case to retrieve a button press as a distinct key. Set the return_raw_buttons variable to a nonzero value before displaying the dialog to retrieve all button presses as the key code WIN_BUTTON. The key_is_button variable will still be set as described above, so you can distinguish one button from another by examining its value.

Epsilon for Windows remembers and restores the sizes of most of these dialogs. Some dialogs may be used in multiple contexts. To have Epsilon remember a different size for each context, pass a unique tag parameter. If the optional tag is missing or NULL, Epsilon uses a default context for remembering the dialog's size. You can use save_var to temporarily assign a value to the use_alternate_dialog_tag variable, and the various subroutines below that call display_dialog_box( ) will use it as the dialog's tag.

one_window_to_dialog(char *title, int win1,
               char *button1, char *button2, char *button3)
prompt_box(char *title, int win1, int win2, char *tag)
two_scroll_box(char *title, int win1, int win2,
               char *button1, char *button2, char *button3)
void (*use_alternate_dialog)(int win1, int win2, int win3);
char *use_alternate_dialog_name;

The subroutines one_window_to_dialog( ), prompt_box( ), and two_scroll_box( ) each call display_dialog_box( ) with some of its parameters filled in for you. They display certain common kinds of dialogs. Call one_window_to_dialog( ) to display a dialog with a single text window and one to three buttons. To see an example, define a bookmark with Alt-/ and then type Alt-x list-bookmarks. Call prompt_box( ) to display a dialog with a one-line window, and below it a list-box style window. To see an example, type Ctrl-x Ctrl-f and then '?'. Call two_scroll_box( ) to display a dialog box with two multi-line windows.

These subroutines all call a subroutine named do_display_dialog_box( ), which takes the same parameters as display_dialog_box( ), but can be told to use an alternative function to display the dialog, not display_dialog_box( ), by temporarily setting the function pointer use_alternate_dialog to a suitable function. Or they can be told to use a different dialog name by temporarily setting the use_alternate_dialog_name variable to its name.

next_dialog_item()
prev_dialog_item()

Within an Epsilon window that's part of a dialog box, the next_dialog_item( ) and prev_dialog_item( ) primitives move the focus to a different window or button within the dialog box. Epsilon normally binds <Tab> and Shift-<Tab> to commands that use these primitives.

int dialog_checkboxes;
int disable_dialog_controls;

Some dialogs include check boxes. The dialog_checkboxes variable controls which check boxes are checked. Each check box corresponds to a bit in this variable. When EEL code sets or clears a bit, it's reflected in the state of that check box; similarly, when the user clicks the check box, its corresponding bit in this variable changes to match. This also generates a WIN_BUTTON event; see Window Events.

The disable_dialog_controls variable lets EEL code disable check boxes and buttons in a dialog. Each check box or button corresponds to a bit in this variable. Setting the bit disables the corresponding control. Clearing the bit enables the control. For check boxes, it unchecks the check box, clearing the corresponding bit in dialog_checkboxes. Check boxes are assigned the low-order eight bits. Any buttons in the dialog are assigned the remaining bits.

set_window_caption(int win, char *title)
show_window_caption()

The set_window_caption( ) primitive sets the text in the title bar of the dialog box containing the window win. If the specified window is on Epsilon's main screen, it sets the main window title displayed above the menu bar. The show_window_caption( ) subroutine calls this to include the current file name in the caption of Epsilon's main window.

Previous	Up	Next
Button Dialogs	Primitives and EEL Subroutines	The Main Loop

Epsilon Programmer's Editor 14.04 manual. Copyright (C) 1984, 2021 by Lugaru Software Ltd. All rights reserved.