Main Page Modules Alphabetical List Compound List File List Compound Members File Members

# 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