---

Standard Dialogs

Functions
pghandle	pgDialogBox (const char *title)
	Create a dialog box with title.
int	pgMessageDialog (const char *title, const char *text, u32 flags)
	Create a message dialog box.
int	pgMessageDialogFmt (const char *title, u32 flags, const char *fmt,...)
	Create a message dialog box, with formatting.
int	pgMenuFromString (char *items)
	Create a popup menu from a string.
int	pgMenuFromArray (pghandle *items, int numitems)
	Create a popup menu from string handles.
int	pgDatePicker (int *year, int *month, int *day, const char *title)
	Show a date on a calendar, allow the user to select a new date.
pghandle	pgInputDialog (const char *title, const char *message, pghandle deftxt)
	Allow the user to edit a one-line string.
pghandle	pgFontPicker (const char *title)
	Allow the user to select any font.
const char *	pgFilePicker (pgfilter filefilter, const char *pattern, const char *deffile, int flags, const char *title)
	Select a file to load or save.
int	pgColorPicker (pgcolor *c, const char *title)
	Display a dialog box allowing the user to select a color.

---

Detailed Description

Various prepackaged dialogs are supplied by the client library, for things like choosing files, picking dates, or entering text.

---

Function Documentation

int pgColorPicker (  pgcolor *    c, const char *    title )

Display a dialog box allowing the user to select a color. Parameters: c  Initially, the color to display. Returns the selected color title  The title string displayed across the dialog's top Returns: Nonzero if the dialog was closed with the "Ok" button See also: pgDialogBox

int pgDatePicker (  int *    year, int *    month, int *    day, const char *    title )

Show a date on a calendar, allow the user to select a new date. Parameters: year  Initially, the year to display. Returns the selected year month  Initially, the month to display. Returns the selected month day  Initially, the day to display. Returns the selected day title  Title to display in the dialog box Returns: Nonzero if a new date was selected, zero if the cancel button was pressed year, month, and/or day may be zero to use the current date. The year must be fully specified. For example, use 1984 instead of just 84. Of course the dialog is Y2K compliant! On systems with 32-bit time_t, it does not allow years beyond 2037. With a 64-bit time_t this isn't a problem. Months and days are both one-based. See also: pgDialogBox

pghandle pgDialogBox (  const char *    title )

Create a dialog box with title. This helpful function creates a centered, automatically sized dialog box equivalent to "pgNewPopup(PGDEFAULT,PGDEFAULT)" and creates a title widget with the given text. Returns: A handle to the dialog box title widget See also: pgNewPopup, pgNewPopupAt

const char* pgFilePicker (  pgfilter    filefilter, const char *    pattern, const char *    deffile, int    flags, const char *    title )

Select a file to load or save. Parameters: filefilter  An optional function to filter the displayed files pattern  This parameter is passed to the filter function deffile  An optional default file name flags  PG_FILE_* flags to control the dialog's operation title  The title string displayed across the dialog's top Returns: A fully qualified path name for the selected file. This string pointer is guaranteed to be valid until the next call to pgFilePicker() See also: pgfilter, PG_FILEOPEN, PG_FILESAVE

pghandle pgFontPicker (  const char *    title )

Allow the user to select any font. Parameters: title  The title string displayed across the dialog's top Returns: A font handle describing the selected font upon clicking "Ok" or zero if the dialog was cancelled. It is the app's responsibility to use pgDelete or contexts to delete this handle. See also: pgNewFont, pgDialogBox

pghandle pgInputDialog (  const char *    title, const char *    message, pghandle    deftxt )

Allow the user to edit a one-line string. Parameters: title  The title string displayed across the dialog's top message  If non-NULL, text to display above the field deftxt  If nonzero, a string handle for default field text Returns: A string handle with the value of the input field upon clicking "Ok" or zero if the dialog was cancelled. It is the app's responsibility to use pgDelete or contexts to delete this handle. See also: pgMessageDialog, pgMessageDialogFmt, pgDelete, pgEnterContext

int pgMenuFromArray (  pghandle *    items, int    numitems )

Create a popup menu from string handles. Parameters: items  An array of handles to string objects for each menu item numitems  The number of string handles Returns: The number (starting with 1) of the chosen item, or zero for a click outside the menu Unlike pgMenuFromString, this function does not perform memory management automatically. Before the client begins creating string objects for the items array, call pgEnterContext. After pgMenuFromArray returns, call pgLeaveContext to free the string handles and destroy the popup menu. Note that the popup menu will not disappear until the call to pgLeaveContext. This means it is possible to delay calling pgLeaveContext to display other popups on top of the menu, for example to create a tree of popup menus. See also: pgMenuFromString, pgNewPopup, pgNewPopupAt

int pgMenuFromString (  char *    items )

Create a popup menu from a string. Parameters: items  A list of menu items, separated by pipe characters. The menu items may contain newlines. Returns: The number (starting with 1) of the chosen item, or zero for a click outside the menu This function is a high-level way to create simple menus, equivalent to calling pgNewPopupAt to create a popup menu and filling it with menuitem widgets. See also: pgMenuFromArray, pgNewPopup, pgNewPopupAt

int pgMessageDialog (  const char *    title, const char *    text, u32    flags )

Create a message dialog box. Parameters: title  The title string displayed across the dialog's top text  Text to display within the dialog box flags  One or more PG_MSGBTN_* constants or'ed together, or zero for the default Returns: The PG_MSGBTN_* constant indicating which button was activated This creates a modal dialog box in the center of the screen, displaying the given message, and waits for an answer. If flags is zero, a simple dialog with only an "Ok" button is created. Possible PG_MSGBTN_* flags include: PG_MSGBTN_OK PG_MSGBTN_CANCEL PG_MSGBTN_YES PG_MSGBTN_NO See also: pgMessageDialogFmt

int pgMessageDialogFmt (  const char *    title, u32    flags, const char *    fmt, ...    )

Create a message dialog box, with formatting. This function is equivalent to pgMessage, with support for printf-style formatting See also: pgMessageDialog

---