Index: doc-rnd/gpmi/packages/dialogs.html
===================================================================
--- doc-rnd/gpmi/packages/dialogs.html (revision 779)
+++ doc-rnd/gpmi/packages/dialogs.html (revision 780)
@@ -30,88 +30,18 @@
structure using the hid package, builds up all the input fields
then calls dialog_attribute() with the hid.
-
API reference
+ Progress dialogs
- function void dialog_log(const char *msg)
- Append a message to the log (log window and/or stderr). Arguments:
-
- - const char *msg: the message
-
+ The script should call dialog_progress() periodicly from a process that
+ runs time consuming calculations and check the return value and break
+ the loop on cancel. The process should have an idea of how long it
+ will take. This is passed on in argument total. As long as
+ argument so_far is less than total, the dialog is
+ open.
+
+ After the process has finished, a call with so_far=total+1 should be
+ made to make sure the window is closed. If the call returns non-zero,
+ the process should be cancelled.
-
function int dialog_confirm(const char *msg, const char *ok, const char *cancel)
- Ask the user for confirmation. Returns 0 for cancel and 1 for ok. Arguments:
-
- - const char *msg: message to the user
-
- const char *ok: label of the OK button
-
- const char *cancel: label of the cancel button
-
- Arguments ok and cancel may be empty (or NULL) in which
- case the GUI will use the default (perhaps localized) labels for
- those buttons.
-
- function void dialog_report(const char *title, const char *msg)
- Pop up a report dialog. Arguments:
-
- - const char *title: title of the window
-
- const char *msg: message
-
- No return value.
-
- function char *dialog_prompt(const char *msg, const char *default_)
- Prompt the user for a single line textual data. Arguments:
-
- - const char *msg: message or question to the user
-
- const char *default: default answer
-
- Returns what the user typed or NULL (empty) if the user choosed to cancel.
-
- function void dialog_beep(void)
- Beeps. No argument, no return value.
-
- function int dialog_progress(int so_far, int total, const char *message)
- Request the GUI hid to draw a progress bar. Arguments:
-
- - int so_far: achieved state
-
- int total: maximum state
-
- const char *message: informs the users what they are waiting for
-
- If so_far is bigger than total, the progress bar is closed.
- Return value: returns !!!TODO!!! if the user pressed cancel.
-
- The script should call this periodicly from a loop that runs
- time consuming calculations and check the return value and
- break the loop on cancel. After the loop a call with so_far=total+1
- should be made to make sure the window is closed.
-
-
function int dialog_attribute(hid_t *hid, const char *title, const char *descr)
- Presents the user a custom dialog box, similar to those used by
- the exporters.
-
- - hid_t *hid: hid that describes options
-
- const char *title: window title
-
- const char *descr: description
-
- Return value: !!!TODO!!!. Values selected by the user are accessed
- using hid_get_attribute.
-
- function char *dialog_fileselect(const char *title, const char *descr, char *default_file_, char *default_ext, const char *history_tag, multiple dialog_fileselect_t flags)
- Pops up a file selection dialog.
-
- - const char *title: window title
-
- const char *descr: description
-
- char *default_file_
-
- char *default_ext: default file name extension
-
- const char *history_tag
-
- dialog_fileselect_t flags: one or more flags (see below)
-
- Returns the selected file or NULL (empty).
-
- dialog_fileselect_t flags:
-
- - FS_READ: TODO
-
- FS_NOT_EXIST: the function calling hid->fileselect will deal with the case where the selected file already exists. If not given, then the gui will prompt with an "overwrite?" prompt. Only used when writing.
-
- FS_TEMPLATE: the call is supposed to return a file template (for gerber output for example) instead of an actual file. Only used when writing.
-
- FS_NONE: none of the above
-