Index: trunk/doc-rnd/gpmi/packages/dialogs.html =================================================================== --- trunk/doc-rnd/gpmi/packages/dialogs.html (revision 779) +++ trunk/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 -

Index: trunk/doc-rnd/gpmi/packages/dialogs_ref.html =================================================================== --- trunk/doc-rnd/gpmi/packages/dialogs_ref.html (nonexistent) +++ trunk/doc-rnd/gpmi/packages/dialogs_ref.html (revision 780) @@ -0,0 +1,71 @@ + + +

PCB GPMI

Reference manual for package dialogs

+Automatically generated from dialogs.h + +

Events

Events do not have return value. The first argument is always the even id +

Functions

The following functions are registered in script context. + +

void dialog_log(char* msg)

+ Append a msg to the log (log window and/or stderr). 
+

+ +

int dialog_confirm(char* msg, char* ok, char* cancel)

+ Ask the user for confirmation (usually using a popup). Returns 0 for
+   cancel and 1 for ok.
+   Arguments:
+     msg: message to the user
+     ok: label of the OK button
+     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. 
+

+ +

void dialog_report(char* title, char* msg)

+ Pop up a report dialog.
+   Arguments:
+     title: title of the window
+     msg: message 
+

+ +

void dialog_beep(void)

+ Audible beep 
+

+ +

int dialog_progress(int so_far, int total, 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.
+   Returns nonzero if the user wishes to cancel the operation.
+
+

+ +

int dialog_attribute(* hid, char* title, char* descr)

+ Pop up an attribute dialog; content (widgets) of the dialog box are coming
+   from hid (see the hid package).
+   Arguments:
+     hid: widgets
+     title: title of the window
+     descr: descripting printed in the dialog 
+

+ + + + +